Usage

• What is the best export method for plugins?

There is no best one. In general, however, I prefer LipeRMI, because it supports callbacks and transparently wraps complex return types. XMLRPC is nice for IPC with other languages but does not support all data types, ERMI claims to be the fastest one but lacks callbacks. If you are in doubt which one you should use, just use several ones at the same time. Plugins can be exported concurrently with different mechanisms without problems.

• How can I obtain the plugin manager from inside a plugin?

The plugin manager that created your component can be obtained by adding these lines to your component's implementation:

@InjectPlugin
public PluginManager pluginManager;

The name of the field does not matter, it only has to be public.

• Does it work inside Java Applets?

Yes it does. However, you have to sign the applet. Additionally, all plugins have to be enabled manually (see below).

• How do I enable a plugin manually? Why would I want to do that?

Enabling a plugin manually means that you tell the manager directly which class it should try to spawn as a plugin. While you lose some comfort, this allows you to spawn plugins in certain conditions where access to the classpath is not easily possible; applets are such an example. You spawn plugins manually like this:

pm.addPluginsFrom(new URI("classpath://net.xeoh.plugins.remote.impl.lipermi.RemoteAPIImpl"));

// or

pm.addPluginsFrom(new ClassURI(RemoteAPIImpl.class).toURI());

• My application does not shut down properly since I started using JSPF ...

Technically that's not a question. However, the reason for this behavior is usually that some plugin you used created a non-daemonic background thread, like for example remote plugins which exported functionality over the network. All you have to do is to call the PluginManager's shutdown method so that all plugins know when they aren't needed anymore, e.g. at the end of the main method.

pm.shutdown()

• Can I download plugins from the net?

This feature is enabled, but experimental. Only use it if you trust the plugin's author, the server and your communications infrastructure. It works just like you'd expect it to work:

pm.addPluginsFrom(new URI("http://server.com/plugin.jar"));

• Does it handle circular dependencies (i.e. A requires B to spawn and B requires A)?

No, and it never will. Circular dependencies are ugly and it is usually easy to replace them.

• The first call to find a remote service takes ~1s, why?

In case you use the automatic discovery jmDNS needs some warmup time. After the discovery started the first time, we delay all calls until one second has elapsed. After this first second no delay should be noticeable.

• The startup takes 1-2 seconds, can I improve this time?

Yes, just enable caching. See the Usage Guide how this is done. The reason for this delay is that JSPF has to search the whole classpath for existing plugins. If you enable caching a list of found plugins is saved between invocations.

• What is caching?

JSPF can memorize all plugins it found within a JAR file and store them for later use. This feature is disabled by default. See the previous point.

• What is weak caching?

In some cases the generation of an MD5 ('strong' for our purposes; yes, we know that MD5 has already been broken for security related applications) can take some time. If you enable weak hashing the PluginManager will not at all try open the file, but just take into account its filename and size.

• Some simple methods seem to hang / throw exceptions unexpectedly.

A couple of times I had bugs with apparently simple methods that do not work as expected. In all these circumstances I forgot that this method belonged to an object which was imported using a RemoteAPI over the network. If the connection breaks, for example because the peer was closed in the meantime, all methods of this object will throw exceptions or won't respond unless they timeout.

Please notice that, due to the convenience some RemoteAPI plugins offer, even very deeply nested objects like Listeners, Callbacks and others are transparently exported as well, which might lead to problems at places not obviously connected to some remote functionality.

Development

• Why are there no start() / stop() methods for plugins? Why do all plugins start automatically?

Because otherwise it wouldn't be simple anymore. If you want to start plugins explicitly feel free to create an ActivatablePlugin that provides start and stop methods and derive your plugins from that.

• Does it mix well with static initializers?

Short answer: No. Long answer: No, it doesn't. Static initializers are an abomination and cause many problems in complex cases where multiple classloaders are involved -- which is the case for JSPF. So, if you enjoy doing many things in static initializers, better refrain from using JSPF. Final static variables however (like constants) are perfectly fine.

• How does classloading work internally?

The specific details might change between versions, but in principle you can assume the following: If the plugin framework detects that it is in Applet-mode, then it will use the classloader which created the PluginManager. In case you add plugins from the classpath all these items should share the same classloader. In case you add plugins from other sources (like external JARs), the PluginManager assumes they are self contained and puts each of them into their own ClassRealm (aka classloader).

Stability

• Why is the version number so low?

There is no real reason. As soon as I have the feeling that a critical mass of people have tested the framework the version will turn to 1.0

• Is it stable?

A couple of people have used it for several projects now and never had any show stoppers. There are, of course, still unknown bugs within, as well as unimplemented features. You should keep in mind however that the framework only helps you writing clean and modularized code, it doesn't do it on its own.

• What platforms are supported?

The framework has been successfully tested on Mac OS X, Windows and Linux with Java 5 and 6. It currently runs on Java 5+, but we might switch to Java 6 some time in the future.

Troubleshooting

• I get an java.lang.ClassNotFoundException: net.xeoh.plugins.base.impl.JARCache$JARInformation on startup...

In version 0.6.2 we changed some cache details. Old cache files cannot be loaded anymore, just delete the file, it will be recreated on the next application startup. This exception does not change the runtime behavior of your app, it is caught gracefully and only shown due to curiosity reasons ;-)

General

• Why do I need this? All you achieve can be done otherwise, too!

You probably don't need it if you ask. From a technical point of view, this framework solves nothing that could not be done otherwise by other solutions. So it's not about the what, it's about the how.

There are so many component frameworks, library toolkits, techniques, whatever out there which allow you to create different implementation of the same service. Most of them have, however, one big problem: the are, well, big and bulky and need lot of configuration before something works. This framework, on the other hand, tries to walk the Python way: simple things are kept simple and should work out of the box.

• So does this try to replace JPF, OSGi, ... ?

No! JSPF was not created to compete with any existing plugin-framework solution -- at least not the ones we know. Please also have a look at these projects to find out what's best for you JPF or OSGi.

• What is the targeted audience?

We see two principal scenarios to use the Java Simple Plugin Framework: 1) Teams, regardless of their size, who just want to use plugin framework to extend their existing projects with dynamic code loading. 2) Teams of about 1 - 10 people who create a new application from the scratch, but still want to have clean code, reusability and all the other benefits it offers.

• What does this "5 minutes and it works" mean?

The full version of the slogan is: Even if you never used this framwork before, if it takes you more than five minutes to develop your first plugin, we did something wrong.

• Really?

If you are an experienced Java programmer (but have no idea about any specific plugin framework), we really think it shouldn't take you more than five minutes to get started.

• Why is the download so big?

The RDF plugin contains Jena ...