The MIRC Object Classes

The article is intended for software developers working on extensions to the MIRC software. To fully understand this article, you may wish to reference the RSNA MIRC Source Code.

1 The Object Classes

MIRC provides four classes to encapsulate files of various types. The classes are all in the org.rsna.mircsite.util package. Reference the Javadocs for details of the methods available in each class.

1.1 FileObject

The FileObject class encapsulates a file of unknown contents. It is the parent class of the other three classes and provides a method for obtaining a java.io.File object pointing to the file, as well as methods for moving, renaming, and copying the file. It also provides dummy methods for obtaining key information about the file. These methods are overridden by subclasses that can parse their corresponding file types to obtain meaningful values. The FileObject class also includes a factory method, getObject(java.io.File), which parses a file and returns an instance of the matching FileObject subclass or, if no subclass matches the file, a FileObject itself.

1.2 XmlObject

The XmlObject class encapsulates an XML file, parsing the XML in the constructor and throwing an Exception if the file does not parse. In addition to the methods of the FileObject, it provides methods for accessing the XML DOM object and reading its elements and attributes. For many purposes, the getValue(String path) method makes it easy to obtain the necessary data to insert into a database, but if necessary, you can use the entire XML DOM.

The Javadocs explain how specific types of data (the uid, the study-uid, the file description) are obtained from the XML DOM object. When designing XML metadata files for a clinical trial, if you put the data in those places, MIRC will be able to manage the files and pass them to your database interface more efficiently.

1.3 ZipObject

The ZipObject class encapsulates a zip file, parsing the file in the constuctor and throwing an Exception if the file does not parse. In addition to the methods of the FileObject, it provides methods for accessing the individual files within the zip file. It also provides methods for accessing the contents of a special file, manifest.xml, that contains data necessary to identify the zip file and relate it to other clinical trial data.

The ZipObject allows a clinical trial to collect a group of related objects, for example multiple output files from an analytical program for a single analysis, and to manage them as a single object.

The Javadocs explain how identifying data are obtained from the manifest.xml file. The ZipObject is much less flexible than the XmlObject in the placement of identifying data. When designing zip metadata files for a clinical trial, you should try to construct manifests exactly by the rules described in the Javadocs.

1.4 DicomObject

The DicomObject class encapsulates a DICOM dataset, parsing the file in the constructor and throwing an Exception if the file does not parse. In addition to the methods of the FileObject, it provides access to all the DICOM attributes, as well as image conversion methods returning JPEG images of any size from the DICOM image.

2 Operational Note

When the getObject(java.io.File) method is called, the FileObject attempts to determine 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:

1. DicomObject
2. ZipObject
3. 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 Tomcat/logs/stdout.log 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.