How to create an API for users who don’t want to depend on your code?

First of all, how would you ever end up asking yourself that question? Well, if you’re the implementer of a class reloading system (e.g. www.javeleon.org) then this question makes perfect sense. Most users take advantage of the basic capabilities of Javeleon simply by adding a Java agent to the JVM arguments.

That’s all good; no direct linking is required to gain the class reloading capabilities in e.g. Java SE applications. Other users will also want to add class reloading capabilities to classes loaded by custom class loaders. This is quite tricky since Javeleon requires integration with classloaders to function properly. In essence, Javeleon needs to know which class loader objects should be made reload-aware. A reload-aware class loader will load only reloadable classes meaning that whenever a reload is triggered Javeleon will reload those classes and you’ll see the changed code immediately in the running application. In order to reload all the classes loaded by a custom class loader Javeleon needs a fresh class loader instance during reload, thus a listener approach would come in handy. The following simple API would suffice to communicate with the Javeleon runtime in this case.

public final class JaveleonReloadManager {
	public static void register(ClassLoader loader, JaveleonClassLoaderListener listener) {}
	

	public static void unregister(ClassLoader loader) {}
   
	public static interface JaveleonClassLoaderListener {
        	public ClassLoader createClassLoader();
    	}
}

The above code would make it possible to register and un-register class loaders. When a reload happens Javeleon will ask the listener associated with the registered class loader object to create a new fresh class loader instance. Now, this approach assumes that users link against the Javeleon API code directly, which can be a problem in some projects. Especially, since Javeleon is only a development dependency, thus users don’t want to execute Javeleon-specific code in their production system (for good reasons). One way to avoid executing Javeleon-specific code is to hide behind the powers of reflection.

You could test reflectively that Javeleon is enabled in the running system, simply be trying to load a known Javeleon class. This would make you able to guard all invocations to the Javeleon “API” by a simple “isJaveleonPresent” check. This approach is actually taken in the integration for the NetBeans Platform and such code is present in the official code base of the NetBeans project. This solution is OK, but very clumsy, since you have no compile-time verification. On the other hand providing an official Javeleon API that users can link against is often too intrusive remembering that Javeleon is only a development dependency. This brings us back to the main question - How do you create an API for users who don’t want to depend on your code?

Well, there is (at least) one path that will lead us there. It turns out that some clever bytecode tricks carry us on to a usable solution. The main idea of our approach is simple. We provide a source file containing the classes as shown above with no implementation within any methods. Users then copy this piece of code to an appropriate package of their choice. Now users can link against this code that does nothing if Javeleon is not present in the system.

If for example the JaveleonReloadManager.register method is invoked nothing will happen since this method is empty. Now, this doesn’t sound too promising since no code will be executed. The trick is that when Javeleon is enabled for this project it will inject code into the register and unregister methods at load-time. This will allow users to communicate with Javeleon without having to link with a specific Javeleon API. However, there is still one big problem with this solution!

The interface JaveleonClassLoaderListener is not compatible with any type internally known by Javleon. Of course we could just use reflection to hack around this but then we have just moved the burden to our side of the equation, which is better but by no means optimal. Instead, we define an internal interface inside Javeleon called e.g. InternalJaveleonClassLoaderListener declaring the exact same methods (here only one method). At load time we then add the internal interface as a superinterface of the interface defined in user code like this:

public static interface JaveleonClassLoaderListener extends InternalJaveleonClassLoaderListener {
	ClassLoader createClassLoader();
}

Now, all of a sudden we have a compatible callback instance as obtained by the register method of which we can safely invoke the createClassLoader method on. That’s it! It is as simple as that!

This approach only requires users to define a small amount of “unknown” code in their project that does absolutely nothing if Javeleon is not around. When Javeleon is enabled they can invoke methods directly into an “API” which is then linked together at load-time so that a communication channel is established without the need to rely on reflective code.