Platonos

Tutorial 1 - Starting the Plugin Engine

The first thing to learn about the plugin engine is that it is a singleton class. Every method that you will make use of within the primary PluginEngine.java file is public static. The main reason for this is, there really is no reason to have more than one instance of the engine. If you feel you have an app that needs to separate plugins into individual engines, there are other ways to handle this using the single instance. Presently, we can not think of a good reason to have more than one instance of the engine container running in a JVM. Each and every plugin can be considered a self container mini application. You could theoretically bundle an entire application within a single plugin!

The engine itself is very easy to start. You really only have two parameters that you need be concerned with. The method call to start the engine is as follows: 

  PluginEngine.start(List list, Map tokens)
This one single line is all it takes to start the engine. The first parameter is a List of URL objects, each specifying one location to find plugins at. The second is a Map of key/value pairs that allow plugins to make use of application specified tokens. Tokens are explained in a later tutorial (PLACE LINK HERE), although we'll briefly describe them here. First let's explain the List.

As stated, the passed in List contains nothing but URL objects, or String objects. The URL objects are preferred as the String objects are converted to URL objects. Each URL object can contain a directory path OR a path to a single plugin archive file. As you'll learn in Tutorial 2 (PLACE LINK HERE), there is minor differences between the two methods of packaging a plugin. Just know that when you specify a directory, if it exists, the engine will traverse the directory looking for any plugin archive format files OR check to see if the directory is the root of an expanded directory plugin. Let's define the two briefly here. A plugin archive format is basically a jar file with a slightly different internal structure. It is more akin to a web application archive (WAR). The expanded directory plugin is identical in terms of the structure on disk as is the plugin archive file, only, it is not bundled into a single file. It is one or more files and directories on disk.

So what's the diff, you may ask? Well, not a lot for the most part. The primary reason for the expanded directory format is during development you can store the plugin directory format as part of your project. Generally, you would have an ant build script that bundles up only the necessary parts for the plugin archive file. This way, you are killing two birds with one stone. During development, you point one of your URL objects at the root directory of your plugin project. As you change the src and presumably your IDE/editor recompiles the changes for you, you can hot-swap the plugin (at runtime) or reload it so that you do not have to restart your entire application and JVM. This allows for a more rapid development cycle. As a side note, if you are running one of the more up to date IDE's that allow you to run your application (and hence the plugin engine) in debug mode, with JDK 1.4 and later you can "hot-swap" individual classes on the fly if they don't change various bits of structure. This is another benefit to the expanded directory structure, it is on disk and in this debug mode the hot-swap occurs. In the bundled plugin archive file, this will not work. Now, you can still zip up your entire plugin project folder OR just the parts of the plugin you wish to deploy as a zip file to bundle it up into a single file. But at deploy time you would have to unzip the plugin into it's own directory for it to be accessible.

What makes up a plugin directory structure, and for that matter a plugin project directory all depends on what your plugin needs to do. As you'll learn in Tutorial , you do not need to include compiled classes as part of your plugin, so you are not necessarily going to have the exact same structure for all plugin projects. But, for the majority of plugins, they will include classes, so we'll describe each directory below and it's purpose.

We'll start off with the '/' character as representing the plugin project root directory. Where you actually deploy the plugin (as an expanded directory) or setup your project is up to you. Just know that '/' is the root for both the internal plugin archive file structure and the on-disk expanded directory structure.

The first and most important piece of a plugin is the configuration file, plugin.xml. This file must reside in the root directory, or the engine will not acknowledge the directory (or .par file) as a plugin. This is the absolute minimum requirement for a plugin to be a valid plugin. Of course, it wouldn't do much good by itself, but you could, theoretically have nothing more than a plugin.xml and have a valid loadable plugin that could infact provide something to the application. Again we'll refer you to the tutorial on extension points and extensions for examples. (NOTE: MAKE SIMPLE SIMPLE PLUGIN WITH NOTHING OTHER THAN PLUGIN.XML THAT SHOWS HOW IT IS VALID).