- -

@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. -

- -