Project Lombok
Get Lombok for Enterprise

@ExtensionMethod

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

@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?
  • This feature has more bugs associated with it than we would like, and it is a large maintenance burden.
Current status: hold - Currently we feel this feature will not move out of experimental status anytime soon, but it will not significantly change and support for it is unlikely to be removed in future versions of lombok either.

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

import lombok.experimental.ExtensionMethod;

@ExtensionMethod({java.util.Arrays.class, Extensions.class})
public class ExtensionMethodExample {
  public String test() {
    int[] intArray = {5, 3, 8, 2};
    intArray.sort();
    
    String iAmNull = null;
    return iAmNull.or("hELlO, WORlD!".toTitleCase());
  }
}

class Extensions {
  public static <T> T or(T obj, T ifNull) {
    return obj != null ? obj : ifNull;
  }
  
  public static String toTitleCase(String in) {
    if (in.isEmpty()) return in;
    return "" + Character.toTitleCase(in.charAt(0)) +
        in.substring(1).toLowerCase();
  }
}

Vanilla Java

public class ExtensionMethodExample {
  public String test() {
    int[] intArray = {5, 3, 8, 2};
    java.util.Arrays.sort(intArray);
    
    String iAmNull = null;
    return Extensions.or(iAmNull, Extensions.toTitleCase("hELlO, WORlD!"));
  }
}

class Extensions {
  public static <T> T or(T obj, T ifNull) {
    return obj != null ? obj : ifNull;
  }
  
  public static String toTitleCase(String in) {
    if (in.isEmpty()) return in;
    return "" + Character.toTitleCase(in.charAt(0)) +
        in.substring(1).toLowerCase();
  }
}

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.