CTP Plugins

This article describes how to add functionality to CTP through the CTP Plugin mechanism. The intended audience for this article is software engineers who are extending or maintaining the code.

CTP has three basic components:

• The embedded servlet container provides an HTTP server with support for server-side computation through a simplified, non-W3C-compliant servlet mechanism implemented in the org.rsna.server and org.rsna.servlets packages. See The Util Module for more information.
• The Pipeline mechanism supports ordered sequences of processing stages that implement the org.rsna.ctp.PipelineStage interface. See Pipelines for more information.
• The Plugin mechanism supports adding functionality into the program outside the framework of pipelines and pipeline stages.

This article will concentrate on the design of plugins. It assumes familiarity with the other articles listed in the Articles for Developers and Planners section of the CTP Articles article.

1 Building and Deploying a Plugin

To implement a plugin, first set up a development environment as described in Setting Up a MIRC Development Environment and build the Util and CTP modules. This provides the jars that must be referenced in the build of the plugin, and equally important, it provides all the Javadocs.

As described in Building an Extension JAR, the best way to deploy CTP extensions is to put them in jars that are placed in the CTP/libraries directory or any of its subdirectories.

2 The Plugin Interface

To be recognized as a Plugin, a class must implement the org.rsna.ctp.plugin.Plugin interface. An abstract class, org.rsna.ctp.plugin.AbstractPlugin, is provided to supply some of the basic methods required by the Plugin interface. All the standard plugins extend this class.

The Javadocs explain the methods which must be implemented in a Plugin.

Each Plugin class must have a constructor that takes its configuration file XML Element as its argument. The constructor must obtain any configuration information it requires from the element. While it is not required that all configuration information be placed in attributes of the element, the getConfigHTML method provided by AbstractPlugin expects it, and if you choose to encode configuration information in another way, you must override the getConfigHTML method to make that information available to the configuration servlet.

3 The Plugin Lifecycle

Like all CTP components, a plugin is instantiated when the system starts. At the time the class is instantiated, the rest of the system configuration is not yet available, so the constructor must perform only those tasks that can be accomplished with the information contained in its configuration element. That is, it cannot access other plugins or pipeline stages.

Once CTP has instantiated all the configured components, it calls the start method of every component. CTP starts all the plugins first and only then starts the pipeline stages. Thus, a pipeline stage that references a plugin can assume that the plugin is available when its start method is called.

Plugins that are configured with id attributes are indexed by the org.rsna.ctp.Configuration class and can be found by other plugins or pipeline stages through the getRegisteredPlugin method like this:

Plugin thePlugin = Configuration.getInstance().getRegisteredPlugin(thePluginID);

When CTP shuts down, it calls the shutdown method of every component. CTP shuts down all the pipeline stages first and only then shuts down the plugins. Thus, a pipeline stage that references a plugin can use the plugin if necessary while its shutdown method is running.

The org.rsna.ctp.plugin.Plugin interface provides an isDown method to allow CTP to know when the plugin is down. Plugins that take some time to shut down typically return from the shutdown method as soon as they have initiated the shutdown, but they don't return true from the isDown method until the the shutdown is complete. The org.rsna.ctp.plugin.AbstractPlugin class handles this handshaking, and plugins that extend the class only have to override the shutdown method if they have special things to do (commit a database, close files, etc.).