The schema for the b><tt>ConfigurationTemplates.xml</tt></b> file has somewhat more capability. A complete example can be found in the source code for CTP in the <b><tt>CTP/source/resources/ConfigurationTemplates.xml</tt></b> file.

+

The schema for the <b><tt>ConfigurationTemplates.xml</tt></b> file has somewhat more capability. A complete example can be found in the source code for CTP in the <b><tt>CTP/source/resources/ConfigurationTemplates.xml</tt></b> file.

==Examples==

==Examples==

Revision as of 14:29, 21 November 2013

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 CTP Articles.

Contents

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:

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 that class only have to override the shutdown method if they have special things to do (commit a database, close files, etc.).

4 Interfacing to the Configuration Editor

The CTP Launcher.jar program provides a manual way of starting CTP, stopping, and monitoring CTP. It also includes a very convenient configuration editor. See The CTP Launcher Configuration Editor for a description of the user interface. The configuration editor is driven by XML files. When the Launcher program starts, the configuration editor searches the CTP/libraries directory and all its subdirectories for all jar files containing a file named ConfigurationTemplates.xml located in the root of the jar file's directory tree. It combines the contents of all such files into a single XML DOM object and uses that object to drive the editor's user interface. A simple example of a ConfigurationTemplates.xml file that might be in a jar for a plugin is shown here:

The schema for the ConfigurationTemplates.xml file has somewhat more capability. A complete example can be found in the source code for CTP in the CTP/source/resources/ConfigurationTemplates.xml file.

5 Examples

5.1 The Redirector Plugin

The CTP servlet container can operate on HTTP or HTTP, but not both simultaneously. On sites that use HTTPS, it is sometimes convenient to provide a redirect service on port 80 to switch the user to the HTTPS port. CTP includes a standard plugin to provide this function. For convenience, all the code is shown below. Note the division of work between the constructor and the start method. Note also that because the shutdown for this pipeline is fast, no attempt is made to return before it is down. Finally, it is generally a good idea to log the status of startup and shutdown. This can be a big help in debugging problems in the field.

5.2 The MIRC Plugin

The entire MIRC Teaching File System is implemented as a single plugin. The plugin installs servlets, opens databases, ensures that the user accounts are at least minimally correct, and starts background threads for various purposes. Note that most of this work must be done in the start method because it requires access to the org.rsna.ctp.Configuration object and the servlet container. For convenience, the code is shown here:

5.3 The AuditLog Plugin

CTP provides an audit logging plugin that allows pipeline stages or other plugins to log text in a database that is accessible to an admin user. This feature was originally intended for use in 21CFR11-compliant clinical trials, but it has been used for many other purposes. Several standard pipeline stages (HttpExportService, DicomExportService, and FtpExportService) can be configured to record audit log entries when exporting data objects. The main body of the code is shown below. Note the installation of the servlet in the start method.