The Extensions API is divided into two parts. A core part and a web client specific part. The core part can be found in the net.sf.basedb.util.extensions package and it's sub-packages, and consists of two sub-parts:

Let's start by looking at the extensions manager and related classes.

The BASE application is using a single manager and a single registry (handled by the Application) class. The manager has been configured to look for extensions and plug-ins in the directory specified by the plugins.dir setting in base.config. Theoretically, a single manager can handle multiple directories, but we do not use that feature. The BASE core also include some special files that are added with the addURI() method. They contain definitions for the core extensions and core plug-ins and are shipped as XML files that reside inside the BASE core JAR files.

The ExtensionsManager.scanForChanges() method is called to initiate a check for new, updated and deleted files. The manager uses the XmlLoader to find information about each JAR or XML file it find in the directory. After the scan, the ExtensionsManager.getFiles() method can be used to find more information about each individual file, for example, if it is a new or modified file, if it contains valid extension definitions and information about the author, etc. This information is used by the installation wizard in the web client to display a dialog were the user can select which extensions to intall. See Figure 22.2, “Extensions and plug-ins installation wizard”. Note that no installation or other actions take place at this stage.

The ExtensionsManager.processFiles() method is called to actually do something. It needs an ExtensionsFileProcessor implementation as an argument. As you can see in the diagram above there are multiple implementations (all are not shown in the diagram), each with a very specific task. A processor is usually also paired with a filter to target it at files that fulfil some criteria, for example, only at valid extension files that has been updated. Typically, the ExtensionsManager.processFiles() method need to be called multiple times with different processor implementations to perform a full installation of an extension or plug-in. Here is a list of the various processors currently in use in BASE.

The result of the processing can be collected with a ProcessResults object and is then displayed to the user as in Figure 22.3, “Extensions and plug-ins installation results”. All of the above is only used when BASE is starting up and initializing the extensions system or when the server administrator is performing a manual installation or update. The next diagram shows the part of the extensions system that is used when actually using the extensions for what they are intended to do (the web client adds some extra features to this as well, but that is discussed later).

The Registry is one of the main classes in the extension system. All extension points and extensions must be registered before they can be used. Typically, you will first register extension points and then extensions, beacuse an extension can't be registered until the extension point it is extending has been registered.

An ExtensionPoint is an ID and a definition of an Action class. The other options (name, description, renderer factory, etc.) are optional. An Extension that extends a specific extension point must provide an ActionFactory instance that can create actions of the type the extension point requires.

Call the Registry.useExtensions() method to use extensions from one or several extension points. This method will find all extensions for the given extension points. If a filter is given, it checks if any of the extensions or extension points has been disabled. It will then call ActionFactory.prepareContext() for all remaining extensions. This gives the action factory a chance to also disable the extension, for example, if the logged in user doesn't have a required permission. The action factory may also set attributes on the context. The attributes can be anything that the extension point may make use of. Check the documentation for the specific extension point for information about which attributes it supports. If there are any renderer factories, their RendererFactory.prepareContext() is also called. They have the same possibility of setting attributes on the context, but can't disable an extension.

After this, an ExtensionsInvoker object is created and returned to the extension point. Note that the ActionFactory.getActions() has not been called yet, so we don't know if the extensions are actually going to generate any actions. The ActionFactory.getActions() is not called until we have got ourselves an ActionIterator from the ExtensionsInvoker.iterate() method and starts to iterate. The call to ActionIterator.hasNext() will propagate down to ActionFactory.getActions() and the generated actions are then available with the ActionIterator.next() method.

The ExtensionsInvoker.renderDefault() and ExtensionsInvoker.render() are just convenience methods that will make it easer to render the actions. The first method will of course only work if the extension point is providing a renderer factory, that can create the default renderer.

Any errors that happen during usage of an extension is handled by an ErrorHandler. The core provides two implementations. We usually don't want the errors to show up in the gui so the LoggingErrorHandlerFactory is the default implementation that only writes to the log file. The RethrowErrorHandlerFactory error handler can be used to re-throw exceptions which usually means that they trickle up to the gui and are shown to the user. It is also possible for an extension point to provide its own implementation of an ErrorHandlerFactory.

The web client specific parts of the Extensions API can be found in the net.sf.basedb.client.web.extensions package and it's subpackages. The top-level package contains the ExtensionsControl class which is used to administrate the extension system. It is more or less a wrapper around the ExtensionsManager provided by the core, but adds permission control and a few other things.

In the top-level package there are also some abstract classes that may be useful to extend for developers creating their own extensions. For example, we recommend that all action factories extend the AbstractJspActionFactory class. All web client extension points use the JspContext class instead of ClientContext. The JSP context provides some extra information about the current request.

The sub-packages to net.sf.basedb.client.web.extensions are mostly specific to a single extension point or to a specific type of extension point. The net.sf.basedb.client.web.extensions.menu package, for example, contains classes that are/can be used for extensions adding menu items to the Extensions menu. See Section 27.8, “Extension points defined by BASE” for more information about the extension points defined by BASE.

When the Tomcat web server is starting up, the ExtensionsServlet is automatically loaded. This servlet has as two purposes:

Using extensions only involves calling the ExtensionsControl.createContext() and ExtensionsControl.useExtensions() methods. This returns an ExtensionsInvoker object as described in the previous section.

To render the actions it is possible to either use the ExtensionsInvoker.iterate() method and generate HTML from the information in each action. Or (the better way) is to use a renderer together with the Render taglib.

To get information about the installed extensions, change settings, enabled/disable extensions, performing a manual installation, etc. use the ExtensionsControl.get() method. This will create a permission-controlled object. All users has read permission, administrators has write permission.

The XJspCompiler is mapped to handle the compilation .xjsp files which are regular JSP files with a different extension. The difference is that the XJSP compiler include the extension's JAR file on the class path, which means that the JSP file can use classes that would otherwise be impossible. This feature is experimental and requires installing an extra JAR into Tomcat's lib directory. See Section 22.1.4, “Installing the X-JSP compiler” for more information.