A compatible implementation may need to access the internals possibly from a different module (classloader). @PatchedPublic annotation currently serves this purpose.

The annotated method is patched to be public at runtime, while the class is being loaded. The calling code is typically resides in the same package, although a different module with an implementation dependency. Using @PatchedPublic it can access the method even at runtime, although from a different classloader.

Note that this approach still requires that method signature dependencies affect the API module dependency closure. All types referenced from the signature must be present for the compilation and execution of the API module. If the referenced type contains an illegal platform or library dependency in its API/impl, then the illegal component infects even the API module.

If some classes are split from module "A" into a different module (say B), source and binary compatibility can be retained if the module "A" declares "B" as an additional implied dependency for clients who depend on an older version of the module. Clients compiled against older version will receive the additional dependency at both run-time and compile-time.

During compilation, a special file in config area will be generated. The generated file will be recognized when dependent module load, and their dependencies will be transformed according to the description.

The automatic dependencies must be stored in the file module-automatic-deps.xml in the module project’s root folder. A typical example of dependencies implied when a module is split to several ones is shown below:

If a class in a module A patches a class in module B, the system must esnure proper visibility between A and B classloaders. With the Compatible Superclass approach, the compatibility class in A typically uses types defined by B, but B must see A’s contents at run-time as B class will be made to extend A type (see below). The simplest way is to join contents of A and B in the same classloader.

If a module’s MANIFEST.MF defines OpenIDE-Module-Fragment-Host: header, the module becomes a Module Fragment and its contents is included into the fragment host’s module classloader.

Because of JVM definition of method resolution, JVM looks not only in the class hosting the target method and specified as part of the Method Reference, but also in superclasses of that class. It’s therefore binary-compatible to move the methods to some superclass.

We must still prevent the superclass from appearing in the extends clause of the source, in order not to retain the dependencies from the superclass' dependency closure (the requirement was to avoid them). At run-time, the API class A which was compiled as extending superclass S, will be patched to extend another superclass, C. Provided that C extends S, type checks in the running JVM should not be affected. The superclass C can then add methods with illegal dependencies in their transitive dependency closure.

The class which delivers the binary-compatible implementation must be annotated using @PatchFor annotation, which also identifies the target class which should be modified at run-time. To preserve inheritance hierarchy properties, there are some rules to be followed. Given API class "A" which extends "X", and binary-compatible implementation class "A"

In addition, A and I must be loaded by the same classloader. To instruct NetBeans module system to do so, the module that contain I must list the following Manifest entry:

where the codename identifies the original module which contains API class A.

API class A may have a constructor, which is no longer acceptable, because of its signature dependencies. If the constructor was just implemented in an 'unlucky' way, the implementation could be lobotomized, but if the constructor’s signature contain an unwanted dependency, it should be rather removed at all from the class.

To preserve backward compatibility, the constructor has to be added back at run-time. Although JVM linking algorithm would eventually find <init>()V method to call after new, the constructor "inherited" from the superclass would not be able to initialize the API class fields.

The initialization of the original API class is implemented by its default constructor - this means the API class must have default constructor, even though it is private. Delegation to other A constructors is not implemented yet, but is feasible.

Initialization of the superclass, or possibly setup of API (A) fields are delegated to a static "factory" method in the @PatchFor superclass. The initialization method must be annotated with @ConstructorDelegate. It’s first parameter must be of type of the compatible superclass itself and the rest of parameters must be the same as the to-be-generated constructor in the API class. Modifiers and declared exceptions are copied to the generated constructor.