+ +

@ExtensionMethod

Annoying API? Fix it yourself: Add new methods to existing types!

Since

+ @ExtensionMethod was introduced as experimental feature in lombok v0.11.2. +

Experimental

+ Experimental because: +

High-impact on code style
Really would like to ship with utility methods to expand common classes, but so far lombok doesn't have a good distribution method for such runtime dependencies
Affects quite a bit of eclipse, and auto-complete e.d. do not work yet in netbeans
Should @ExtensionMethod be legal on methods? Should it be legal on packages?

+ Current status: positive - Currently we feel this feature may move out of experimental status with no or minor changes soon. +

Overview

+ You can make a class containing a bunch of public, static methods which all take at least 1 + parameter. These methods will extend the type of the first parameter, as if they were instance methods, using the + @ExtensionMethod feature. +

+ For example, if you create public static String toTitleCase(String in) { ... }, you can use the + @ExtensionMethod feature to make it look like the java.lang.String class has a method named + toTitleCase, which has no arguments. The first argument of the static method fills the role of this + in instance methods. +

+ All methods that are public, static, and have at least 1 argument whose type is not primitive, are + considered extension methods, and each will be injected into the namespace of the type of the first parameter as if they were + instance methods. As in the above example, a call that looks like: foo.toTitleCase() is replaced with + ClassContainingYourExtensionMethod.toTitleCase(foo);. Note that it is actually not an instant + NullPointerException if foo is null - it is passed like any other parameter. +

+ You can pass any number of classes to the @ExtensionMethod annotation; they will all be searched for + extension methods. These extension methods apply for any code that is in the annotated class. +

+ Lombok does not (currently) have any runtime dependencies which means lombok does not (currently) ship with any useful + extension methods so you'll have to make your own. However, here's one that might spark your imagination: +

public class ObjectExtensions {
+	public static <T> or(T object, T ifNull) {
+		return object != null ? object : ifNull;
+	}
+}

+ With the above class, if you add @ExtensionMethod(ObjectExtensions.class) to your class definition, you can write: +

String x = null;
+System.out.println(x.or("Hello, World!"));

+ The above code will not fail with a NullPointerException; it will actually output Hello, World! +

With Lombok

@HTML_PRE@

Vanilla Java

@HTML_POST@

Supported configuration keys:

lombok.extensionMethod.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @ExtensionMethod as a warning or error if configured.

Small print

+ Calls are rewritten to a call to the extension method; the static method itself is not inlined. Therefore, the + extension method must be present both at compile and at runtime. +

+ Generics is fully applied to figure out extension methods. i.e. if the first parameter of your extension method is + List<? extends String>, then any expression that is compatible with that will have your extension method, + but other kinds of lists won't. So, a List<Object> won't get it, but a List<String> will. +

+ +