Annotation Interface PatchFor

@Retention(CLASS) @Target(TYPE) public @interface PatchFor
Marks a class, which provides binary-compatible implementation for a changed API class. When removing @deprecated code from API, it is still desirable to retain backward binary compatibility. Because of JVM method/field/class resolution mechanism, it is permitted to move the implementation upwards the inheritance hierarchy. However, the superclass that receives the methods must not be visible in the sources (otherwise the change would not serve any good) and specifically, must not be referenced from extends clause of the changed class.

The compatibility superclass ought to reside in a different module to allow reduce type dependencies and should be only injected into inheritance chain if and only if some of enabled modules depend on the obsolete version of the API module.

This annotation is designed to mark code which should be injected to provide backward compatibility and will provide implementation for removed API methods. The marked class will be used as a superclass of the API class identified by value of the annotation, so old clients can still use removed members at run time.

The injected superclass must extend the same type as the original API class, so that API-visible inheritance chain is preserved. It must declare all non-private constructors as the original superclass.

The module that contains PatchFor classes must be defined as module fragment, since it has to share classloader with the patched module: put 

OpenIDE-Module-Fragment-Host: codenamebase
into the Module's manifest. The codenamebase must identify the host module which contains the class(es) to be patched.

Note that it is not possible to support removed constructors this way; the constructor has to be physically present on the API class. To provide backward-compatibile code injection for constructors, please use ConstructorDelegate annotation.

For examples, plese see the NetBeans Wiki

Since:
7.44

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    MANIFEST_FRAGMENT_HOST
    The manifest header name.

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    Class<?>
    value
     

  • Field Details

  • Element Details

    • value

      Class<?> value
      Returns:
      Class that should be changed to extend the annotated class