Package com.infradna.tool.bridge_method_injector

Annotation Type WithBridgeMethods

  • @Retention(CLASS)
@Target(METHOD)
@Documented
@Indexed
public @interface WithBridgeMethods
    Request that bridge methods of the same name and same arguments be generated with each specified type as the return type. This helps you maintain binary compatibility as you evolve your classes.

    For example, if you have the following code: 

     @WithBridgeMethods(Foo.class)
 public FooSubType getFoo() { ... }

    The Maven mojo will insert the following bridge method: 

     public Foo getFoo() {
     return getFoo(); // invokevirtual to getFoo() that returns FooSubType
 }

    In some cases, it's necessary to widen the return type of a method, but in a way that legacy calls would still return instances of the original type. In this case, add castRequired=true to the annotation. For example, if you have the following code: 

     @WithBridgeMethods(value=FooSubType.class, castRequired=true)
 public <T extends Foo> createFoo(Class<T> clazz) {
   return clazz.newInstance();
 }

    The Maven mojo will insert the following bridge method: 

     public FooSubType createFoo(Class clazz) {
   return (FooSubType) createFoo(clazz); // invokeVirtual to createFoo that returns Foo
 }

    In extreme cases, this method can add a method whose return type has nothing to do with the return type of the declared method. For example, if you have the following code: 

     @WithBridgeMethods(value=String.class, adapterMethod="convert")
 public URL getURL() {
   URL url = ....
   return url;
 }

 private Object convert(URL url, Class targetType) { return url.toString(); }

    The Maven mojo will insert the following bridge method: 

     public String getURL() {
   return (String)convert(getURL(),String.class);  // invokeVirtual to getURL that returns URL
 }

    The specified adapter method must be a method specified on the current class or its ancestors. It cannot be a static method.

    Author:
    Kohsuke Kawaguchi

    • Required Element Summary

      Required Elements 
      Modifier and Type Required Element Description
      Class<?>[] value
      Specifies the return types.

    • Optional Element Summary

      Optional Elements 
      Modifier and Type Optional Element Description
      String adapterMethod
      Specifies the method to convert return value.
      boolean castRequired
      Specifies whether the injected bridge methods should perform a cast prior to returning.

    • Element Detail

      • value

        Class<?>[] value
        Specifies the return types. These types must be assignable from the actual method return type, or castRequired() should be set to true.

      • castRequired

        boolean castRequired
        Specifies whether the injected bridge methods should perform a cast prior to returning. Only set this to true when it is known that calls to the bridge methods will in fact return objects assignable to the bridge method return type, even though the declared method return type is not assignable to them.
        Since:
        1.4
        Default:
        false

      • adapterMethod

        String adapterMethod
        Specifies the method to convert return value. This lets bridge methods to return any types, even if it's unrelated to the return type of the declared method.
        Since:
        1.14
        Default:
        ""