Matte supports plugins for extending the some features from beyond the built-in ones that come with Matte itself. This document describes how plugins are managed by Matte in a general sense: how Matte locates them, initializes them, and allows the application to query for them.
The Plugin API is a generic API in Matte that facilitates finding and registering plugins dynamically when Matte starts.
Plugins are gouped into types, which each type represents a specific function
the plugin will perform. The getPluginType() method must return the plugin's
type. In this way Matte can perform tasks like "give me all plugins that
support this type of function". The type is represented by an interface that must
extend the Plugin interface. For example, the
BrowseModePlugin is a
"browse mode" plugin type.
When Matte locates a plugin at startup, it will call the initialize() method,
passing in the Spring ApplicationContext for the running Matte application. In
this way each plugin has access to the full application configuration and is free to perform
any initialization routines necessary.
Each plugin can register one or more plugin-specific message resource bundles if it needs
to supply internationalizable messages to the Matte user interface. Matte will call the
getMessageResourceNames() method after it has initialized the plugin, and for any
message resource name returned it will call the registerMessageResource() method
those messages will become available just like any other message bundle in Matte.
When Matte starts up, the SystemBiz
is responsible for finding, initializing, and registering all available plugins. Matte does so
by looking for all available classpath resources named META-INF/matte-plugin.properties.
That means plugins should be distributed as normal Java JAR files, with this special properties
file included in the META-INF directory in the JAR file. To make the plugin available
to Matte, then, you just need to add it to Matte's classpath by adding the JAR to the
WEB-INF/lib directory in the Matte WAR archive.
This properties file must define the plugin class (or classes) that should be registered by
the given plugin. It must contain first one property matte.plugin which should
contain a list of plugin aliases in the properties file. Then for each plugin aliases named
in that list, there should be one more property named matte.plugin.[alias].class
that contains the full Java class name to load as the plugin.
For example, the Matte built-in configuration looks like this:
matte.plugin = noop, albumBrowse, popularityBrowse, ratingAvgBrowse matte.plugin.noop.class = magoffin.matt.ma2.plugin.NoopPlugin matte.plugin.albumBrowse.class = magoffin.matt.ma2.dao.support.AlbumsByDateBrowseModePlugin matte.plugin.popularityBrowse.class = magoffin.matt.ma2.dao.support.PopularityBrowseModePlugin matte.plugin.ratingAvgBrowse.class = magoffin.matt.ma2.dao.support.RatingAverageBrowseModePlugin
The alias names can be anything, but must be unique within a given
matte-plugins.properties file.
Each plugin instance is instantiated using the Java Class.newInstance() method,
so it must provide a default, no-argument constructor for this to work. The plugin class must
implement the Plugin interface.
Immediately after the plugin instance is instantiated, Matte will call the initialize()
method, passing in the current Spring ApplicationContext. It is the responsibility of the
plugin to perform any/all start-up initialization and configuration at this point. A good way for
plugin implementations to initialize themselves by using Spring, and the
AbstractPlugin provides a default base
class that provides a standardized way for plugins to configure themselves via a
plugin-specific Spring XML configuration file.
Once initialized, the plugin will be registered based on the plugin type returned by
the plugin's getPluginType() method. Then, when any part of Matte calls the
SystemBiz.getPluginsOfType() method, all plugins of the given type will be returned.
See the BrowseAlbumsController
for an example of how this is used for the BrowseModePlugin type.