View source for 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 <b><tt>org.rsna.server</tt></b> and <b><tt>org.rsna.servlets</tt></b> packages. See [[The Util Module]] for more information.
* The Pipeline mechanism supports ordered sequences of processing stages that implement the <b><tt>org.rsna.ctp.PipelineStage</tt></b> interface. See [[CTP-The_RSNA_Clinical_Trial_Processor#Pipelines|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 <b>Articles for Developers and Planners</b> section of [[CTP Articles]].

==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 [[Extending CTP#Building an Extension JAR|Building an Extension JAR]], the best way to deploy CTP extensions is to put them in jars that are placed in the <b><tt>CTP/libraries</tt></b> directory or any of its subdirectories.

==The Plugin Interface==
To be recognized as a Plugin, a class must implement the <b><tt>org.rsna.ctp.plugin.Plugin</tt></b> interface. An abstract class, <b><tt>org.rsna.ctp.plugin.AbstractPlugin</tt></b>, 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 <b><tt>getConfigHTML</tt></b> method provided by <b><tt>AbstractPlugin</tt></b> expects it, and if you choose to encode configuration information in another way, you must override the <b><tt>getConfigHTML</tt></b> method to make that information available to the configuration servlet.

==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 <b><tt>start</tt></b> 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 <b><tt>start</tt></b> method is called.

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

::<tt>Plugin thePlugin = Configuration.getInstance().getRegisteredPlugin(thePluginID);</tt>

When CTP shuts down, it calls the <b><tt>shutdown</tt></b> 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 <b><tt>shutdown</tt></b> method is running.

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

==Examples==
===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 <b><tt>start</tt></b> 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.

<pre>
/*---------------------------------------------------------------
*  Copyright 2013 by the Radiological Society of North America
*
*  This source software is released under the terms of the
*  RSNA Public License (http://mirc.rsna.org/rsnapubliclicense)
*----------------------------------------------------------------*/

package org.rsna.ctp.stdplugins;

import org.apache.log4j.Logger;
import org.rsna.ctp.plugin.AbstractPlugin;
import org.rsna.server.HttpRequest;
import org.rsna.server.HttpResponse;
import org.rsna.service.HttpService;
import org.rsna.service.Service;
import org.rsna.util.StringUtil;
import org.w3c.dom.Element;

/**
 * A Plugin to monitor an HTTP port and redirect connections to an HTTPS port.
 */
public class Redirector extends AbstractPlugin {

	static final Logger logger = Logger.getLogger(Redirector.class);

	int httpPort;
	String httpsHost;
	int httpsPort;
	HttpService monitor = null;
	Service handler = null;

	/**
	 * Construct a plugin implementing a Redirector.
	 * @param element the XML element from the configuration file
	 * specifying the configuration of the plugin.
	 */
	public Redirector(Element element) {
		super(element);
		httpPort = StringUtil.getInt(element.getAttribute("httpPort"), 80);
		httpsHost = element.getAttribute("httpsHost").trim();
		httpsPort = StringUtil.getInt(element.getAttribute("httpsPort"), 443);
		try {
			handler = new RedirectionHandler();
			monitor = new HttpService(false, httpPort, handler);
			logger.info("Redirector Plugin instantiated");
		}
		catch (Exception ex) {
			logger.warn("Unable to instantiate the Redirector plugin on port "+httpPort);
		}
	}

	/**
	 * Start the plugin.
	 */
	public void start() {
		if (monitor != null) {
			monitor.start();
			logger.info("Redirector Plugin started on port "+httpPort+"; target port: "+httpsPort);
		}
	}

	/**
	 * Stop the plugin.
	 */
	public void shutdown() {
		if (monitor != null) {
			monitor.stopServer();
			logger.info("Redirector Plugin stopped");
		}
		stop = true;
	}

	class RedirectionHandler implements Service {

		public RedirectionHandler() { }

		public void process(HttpRequest req, HttpResponse res) {
			String host = httpsHost;
			if (host.equals("")) {
				req.getHost();
				int k = host.indexOf(":");
				if (k >= 0) host = host.substring(0,k);
			}
			host += ":" + httpsPort;
			String query = req.getQueryString();
			if (!query.equals("")) query = "?" + query;
			String url = "https://" + host + req.getPath() + query;
			res.redirect(url);
		}
	}

}
</pre>