View source for Implementing an External Preprocessor for MIRC Clinical Trials

The article is intended for software developers working on clinical trials which require the imposition of special rules on the types of objects which are accepted into the trial. To fully understand this article, you may wish to reference [[the RSNA MIRC Source Code]] and [[Implementing an External Database Interface for MIRC Clinical Trials]].

===The ObjectProcessor===
The ObjectProcessor is a component of a MIRC Storage Service. It processes files which are received from DICOM and HTTP sources and either creates or updates MIRCdocuments to reference them. The processing can include:
* External preprocessing.
* Anonymization.
* Queuing for export to DICOM or HTTP destinations.
* Queuing for processing by an external database interface.

This article describes how to develop a preprocessor and connect it to the ObjectProcessor.  A preprocessor is a Java class to which the ObjectProcessor passes an object encapsulating a file. The preprocessor returns a result indicating whether the object is acceptable. If it is acceptable, the Object processor continues processing the file. If it is not, the ObjectProcessor quarantines it. The ObjectProcessor dynamically loads the preprocessor's class, obtaining the name of the class from the Storage Service’s <b>trial/trial.xml</b> configuration file. This file is typically configured by the trial administrator through the Admin Service.

===The Object Classes===
MIRC provides four classes to encapsulate files of various types. See [[The MIRC Object Classes]] for details. The classes are:
* FileObject
* XmlObject
* ZipObject
* FileObject

===The PreprocessorAdapter Class===
The PreprocessorAdapter class, <b>org.rsna.mircsite.util.PreprocessorAdapter</b>, is a base class for building an external preprocessor. To be recognized and loaded by the ObjectProcessor, an external preprocessor class must be an extension of PreprocessorAdapter.

All the methods of the PreprocessorAdapter class return an integer status value. Static values for the statuses are defined in the class. There are two values:
*<b>STATUS_OK</b> means that the object meets the external criteria for inclusion in the study.
*<b>STATUS_REJECT</b> means that the object is to be excluded from the study, in which case the ObjectProcessor will quarantine it.
All the methods of the PreprocessorAdapter class return the value <b>STATUS_OK</b>.

===Extending the PreprocessorAdapter Class===
To implement a useful preprocessor, you must extend the <b>PreprocessorAdapter</b> class. Since the PreprocessorAdapter class implements dummy methods returning STATUS_OK, your class that extends PreprocessorAdapter only has to override the methods that apply to your application. If, for example, you only care about XML objects, you can just override the <b>process(XmlObject xmlObject)</b> method and let PreprocessorAdapter supply the other <b>process()</b> methods, thus ignoring objects of other types.

If you want to reject objects of certain types, you must override the <b>process()</b> method for that type and return <b>STATUS_REJECT</b>.

The preprocessor can be also be used to modify objects before any further processing takes place. The various object classes provide access to the data and you can programmatically do anything you want with it (it's great to be king).

If you want to log information to the <b>Tomcat/logs/stdout.log</b> directory, the PreprocessorAdapter class provides a static <b>org.apache.log4j.Logger</b> object called <b>logger</b>. The MIRC site typically runs at the logging level WARN, so unless you change that, you should make calls like:

:logger.warn("...");

If you want to log information that will be visible through the <b>Show Log</b> button on the admin page, you can use the static methods in the <b>org.rsna.mircsite.log.Log</b> class. Remember, however, that the <b>Log</b> class only maintains a circular buffer of the past 200 entries, so if you make many calls, you may be removing log entries made by other objects.

===Connecting Your Preprocessor Class to MIRC===
After building your preprocessor and producing a jar file for it, you have to install it and configure it. The preprocessor is part of a Storage Service, and each storage service can have its own (possibly different) external preprocessor. Therefore, the interface is installed and configured at the level of the Storage Service.
====Installation====
The preprocessor jar file must be installed in the <b>Tomcat/webapps/[storageservice]/WEB-INF/lib</b> directory, where <b>[storageservice]</b> is the name of the storage service for the clinical trial. Do <b>not</b> place the jar file in the Tomcat/shared/lib directory. Doing so will cause the class not to load.

The MIRCsite-installer program always deletes the <b>Tomcat/webapps/[storageservice]/WEB-INF/lib</b> directory during an upgrade to prevent old libraries from contaminating a new release. This has the unfortunate effect of deleting the database interface jar file. You must therefore be careful to restore the preprocessor jar file after an upgrade.

====Configuring MIRC for Your Preprocessor Class====
The Admin Service provides a web interface for setting the configuration parameters. The interface is accessed by clicking the <b>Update Configuration</b> button in the <b>DICOM Service</b> column on the admin page. In the <b>Preprocessor</b> section of the resulting page, there are two parameters:
*<b>Enabled</b> determines whether objects are preprocessed. 
*<b>Preprocessor class name</b> specifies the fully qualified name of the class. If this field is empty, the system will operate as if preprocessing is disabled.

====Operational Note====
When a file is received, the PreprocessorAdapter attempts to figure out the type of file by parsing it. It first tries to parse the file based on the extension of its filename. If that fails, it tries all the untried classes in the order:
#DicomObject
#ZipObject
#XmlObject
If none of the objects can be instantiated, a FileObject is created for the file. If the file is a binary object that is neither a DICOM file nor a zip file, the attempt to instantiate the XmlObject will cause the Xerces parser to encounter a fatal, but not serious, error, which it logs to the console stream where it can be seen in the log viewer or by accessing the <b>Tomcat/logs/stdout.log</b> file. The error is not serious because although the Xerces parser fails, it is reinstantiated whenever it is needed, so there is no effect on the operation of the system. This error will never occur in trials which produce only DICOM, zip, or XML files.