Puzzles' aim is to provide an easy way to add functionalities to an application through plugins.
Puzzles will hide from you the burden and complexity of handling dynamic class loading, plugins storage, notifications, etc. It's a rather small library with no external dependency and quite easy to use.
A package is a file containing everything the plugin needs. In most cases the package will be a zip or jar file, containing images, css files, jar files, etc.
A PackageReader is an object that knows to read inside a package, and access the files it contains. As long as you use plugins packaged as zip/jar files, you only need to use the ZipPackageReader that comes bundled with Puzzles.
A PluginStore is a repository where the plugins' packages (zip/jar files mainly) will be saved. Most commonly, the store will be a folder on the local file system.
The PluginDescriptor is metainformation about the plugin. It contains information about the name of the plugin, the author, a URL where more information can be found, but also specifies how to instanciate the plugin (in case the plugin contains java code) and the public resources of the plugin. By "Public resources", we refer to any file in the package that are to be available outside of the plugin's scope: typically, you don't want the jar libraries to be available, so you won't declare them as public resource. But if your plugin contains images that you want to display in a web application, the image will have to be declared as a public resource.
This is an object that is able to build a PluginDescriptor instance from a file. So far, Puzzles only comes with a PluginDescriptorBuilder that builds descriptors from java's properties files.
A PluginLoader has two roles: the first one is to be a front-end to the PackageReader and PluginDescriptorBuilder, so that higher level objects don't have to deal with the Package/Descriptor stuff. The second role is to load the jar dependencies of the plugin (if there are any) and to instanciate the Plugin itself.
The PluginRegistry is what you'll deal with: it hides the Storing/Loading/Reading/etc. from you. It knows which plugins are installed, it knows how to give you URLs to the plugins' resources, it can install new plugins, uninstall previously installed plugins, etc., it notifies its listeners when plugins are installed or uninstalled.
Any object that implements this interface and that is added to the registry's PluginListeners will be notified when a plugin is installed/uninstalled.
Two minutes tutorial
For this tutorial, we'll build a simple stupid command line application that echoes every line you type: if you enter "toto" and press return, the program will display "toto". Simple, yes, but, let's add a possibility to extend the application: before displaying what you typed, the text will be handled to a Decorator, and those decorators will be our plugins, when the application is first started, there are no plugin:
First, our Decorator interface:
then our main class:
ok so you can run that now. type "border HaHaHa I'm using the internet!" and the program will answer
Now let's write a plugin:
compile it and package it in a jar named border_plugin.jar (the name in itself is not important, but we reuse it later in the plugin descriptor)
then we write a plugin descriptor:
finally let's zip all that in a file called myFirstPuzzlesPlugin.zip. So you now have a zip file which contains a jar file and a properties file, let's run the application again:
type "border HaHaHa I'm using the internet!" and the program will still answer
now type "install /path/to/zipfile/myFirstPuzzlesPlugin.zip"
Now you should see:
now type again "border HaHaHa I'm using the internet!" and you will see:
Now stop the application, and restart it, you should see:
the plugin has been loaded since it was in the store, you can try it again, it'll work.
to uninstall it, simply type: "uninstall border".
there you go, you just used a plugin !