The MIRC Module

UNDER CONSTRUCTION

The MIRC module (MIRC.jar) contains the code of the CTP plugin that implements TFS, the RSNA Teaching File System. This article describes the theory of operation of the packages and files contained in the MIRC module. The intended audience for this article is software engineers extending or maintaining any of that software.

See Setting Up a MIRC Development Environment for information on obtaining and building the MIRC module. It will be helpful to get the source code and build it so you can reference the Javadocs as you go along.

1 Overview

The MIRC module contains many packages. In general, major system functions (as well as some minor ones) are encapsulated in their own packages, but because many functions interact, this principle is not universally maintained. Most system functions have classes and files that are contained in the jar file. Often, the files are XSL programs used for the generation of web pages or Javascript and CSS files referenced by the web pages. These files are served directly from the jar file without having to be installed on the disk. See The Util Module for a description of how the server serves files from the classpath.

2 The TFS-installer

The TFS-installer uses the same installer program as CTP. It includes a full installation of CTP, but it includes a different config.xml file snd additional libraries.

To prevent the loss of site-specific configuration information, the installer does not overwrite the config.xml file during an upgrade installation. The standard TFS config.xml file includes the MIRC plugin and pipelines for the File Service, the DICOM Service, and the TCE Service.

The additional libraries include the Apache XML libraries because the standard Java XML libraries don't support passing DOM objects as parameters to XSL transforms. This capability is used widely in TFS, but not CTP, so they are only included in the TFS installer.

3 The MIRC Plugin

All the code for TFS is included in the MIRC plugin, including all the servlets, the TFS-specific pipeline stages, and many XSL, Javascript, CSS, image, and files. The plugin is loaded when CTP loads the configuration, and it is started after the server is started but before any of the pipelines are started.

The root attribute of the MIRC plugin's configuration file element defines the root directory of all the TFS files. The default location is mircsite under the CTP directory, but it can be changed if it is desired to locate the teaching files on another drive or network system. Because the installer never overwrites any of the teaching file information, in most cases it is safe in the CTP directory tree.

When the plugin is started, it loads the MIRC configuration file. It then loads various databases and adds all the TFS servlets to the server. It also ensures that if the admin user exists, it has the author, publisher, and department roles. Finally, it rebuilds the RadLex index (if necessary), and starts several daemon threads to monitor the status of non-local libraries (LibraryMonitor), draft documents (DraftDocumentMonitor)), and the activity report submission process that sends information on the site to the RSNA (SummarySubmitter).

When CTP shuts down, the MIRC plugin receives a shutdown method call, which triggers the closing of all the databases.

4 The MIRC Configuration File

The MIRC plugin and the three TFS pipelines are configured in the config.xml file, but all the other configuration information for a TFS site is contained in the mirc.xml file, located in the root of the plugin (typically CTP/mircsite). The mirc.xml file contains all the configuration information for the site, all the local libraries it contains, all the non-local libraries it can query. the File Service, and the Case of the Day (if any). The file is parsed and managed by the mirc.MircConfig class. It is managed by the admin servlets for each of the major subsystems: QueryServiceAdmin, StorageServiceAdmin, and FileServiceAdmin. This file is not overwritten by the installer during an upgrade.

This is an abbreviated listing of a mirc.xml file for a test site:

<mirc
    UI="integrated"
    addresstype="dynamic"
    date="2012.12.23 at 09:28:28 CST"
    disclaimerurl=""
    downloadenb="yes"
    email="johnperry@dls.net"
    masthead="ChildrensLogo2.jpg"
    mastheadheight="109"
    mode="rad"
    popup="login"
    roles="department"
    rsnaVersion="Z97"
    sharestats="yes"
    showptids="yes"
    showsitename="yes"
    siteid="1343228846573"
    sitename="JP's Teaching Files"
    siteurl="http://192.168.0.4:80"
    timeout="7"
    version="Z105">
    <Libraries>
        <Library
            address="/storage/ss1"
            authenb="yes"
            autoindex="no"
            dcmenb="yes"
            deflib="yes"
            enabled="yes"
            id="ss1"
            jpegquality="-1"
            local="yes"
            maxsize="75"
            subenb="yes"
            tceenb="yes"
            timeout="0"
            zipenb="no">
            <title>My MIRC Site</title>
            <tagline/>
        </Library>
        <Library
            address="http://mirc.childrensmemorial.org/storage/ss12"
            deflib="no"
            enabled="yes"
            local="no">
            <title>CMH: Children's Memorial Hospital General Pediatric Cases</title>
        </Library>
    </Libraries>
    <FileService
        maxsize="75"
        timeout="0"/>
    <news>
        <title>20110902 DX CHEST STUDY</title>
        <image>
            /storage/ss4/docs/20121002065223174/9999.68816769595213868527999756405838373430_base.jpeg
        </image>
        <url>/storage/ss4/docs/20121002065223174/MIRCdocument.xml</url>
    </news>
</mirc>

4.1 The mirc Element

The mirc root element has these attributes:

• UI: the default UI of the system. Standard values are integrated and classic.
• addresstype: the addressing mode of the system. Standard values are dynamic and static. For sites that operate in dynamic mode and have a numeric IP address, the siteurl attribute is updated with the actual IP address obtained from the operating system when the system starts. For sites that operate in static mode or have a non-numeric IP address, the siteurl attribute is not modified when the system starts.
• date: the build date of the MIRC.jar file, obtained from the file's manifest when the system starts.
• disclaimerurl: the URL of a web page to be displayed if the value of the popup attribute is notes.
• downloadenb: whether to enable the DownloadService on the site. Typically, on the RSNA site has this service enabled.
• email: the email address of the site admin. This is reported to the RSNA site as part of an Activity Summary report.
• masthead: the name of the masthead file displayed in the classic UI. This file is loaded by the QueryService, and its context is query, so this file must be located in the CTP/mircsite/query directory. The default file is called manifest.jpg, and it is located in the MIRC.jar at query/masthead.jar. Unless a site has provided its own masthead, the default file is served from the jar.
• mastheadheight: the vertical height of the masthead file.
• mode: the mode in which to operate the site. Standard values are rad and vet, the latter for veterinary medicine. The choice affects the structure of the advanced query fields.
• popup: the initial popup to display when a user first accesses the site. The standard values are help, notes, login, and none.
• roles: a comma-separated list of user roles used by the site in addition to the standard roles.
• rsnaVersion: the current MIRC version running on the RSNA site, obtained from the RSNA site when the local site starts. This is compared to the local version in the About TFS popup to determine whether to indicate that a newer version is available.
• sharestats: whether to automatically submit Activity Summary reports to the RSNA site. Standard values are yes and no.
• showptids: whether to display PHI in patient elements in MIRCdocuments. Standard values are yes and no.
• showsitename: whether to overlay the sitename on the masthead in the classic UI. Standard values are yes and no.
• siteid: the unique ID of the site, assigned automatically by the system. Its value is the system time in milliseconds when the system first starts. It is used by the RSNA TFS site to collate activity reports from the various sites in the field.
• sitename: the name displayed on the query page.
• siteurl: the URL of the site, including the protocol, the IP or domain name, and the port, but no path information.
• timeout: the timeout in seconds for queries.
• version: the version of the MIRC.jar file, obtained from the file's manifest when the system starts.

4.2 The Libraries Element

The Libraries element lists all the libraries known to the system, whether local or not. Each library is represented by a Library element. Local libraries have these attributes:

• address: the URL path for the library. All local libraries have paths consisting of /storage/, followed by the library's ID.
• authenb: whether to authoring is enabled on the library. Standard values are yes and no.
• autoindex: whether documents saved on the library are to be indexed automatically. Standard values are yes and no. The attribute controls users' ability to save documents that have permissions that allow them to be seen by unauthenticated users. Such documents are called public, and the act of making a document public is called publishing. If autoindexing is enabled, then any author can publish a document. If autoindexing is not enabled, then only users with the publisher role are allowed to publish a document.
• dcmenb: whether the DICOM Service is enabled on the library. Standard values are yes and no.
• deflib: whether the library is to be included in the list of libraries queried when a user first accesses the system. Standard values are yes and no.
• enabled: whether the library is actually to be queried if it is included in the list of libraries to be searched in a query. Standard values are yes and no. This attribute is managed by the system. It is intended to suppress queries of remote libraries that are known to be down. The LibraryMonitor daemon thread periodically checks remote libraries to see if they respond and then updates the enabled attributes accordingly.
• id: the ID of the local library. This is a string consisting of ss followed by an integer. The integer is automatically assigned by the Storage Service Admin servlet when a library is created.
• jpegquality: the compression quality to be used when saving images in MIRCdocuments. Standard values range from 1 to 100. The value -1 indicates the use of the system standard quality.
• local: whether the library is local. Standard values are yes and no.
• maxsize: the maximum size of a POST upload in megabytes. The default is 75.
• subenb: whether the Submit Service is enabled on the library. Standard values are yes and no.
• tceenb: whether the TCE Service is enabled on the library. Standard values are yes and no.
• timeout: the maxmum time in days to store a draft document before automatically deleting it in the DraftDocumentMonitor. A zero value indicates to keep draft documents forever.
• zipenb: whether the Zip Service is enabled on the library. Standard values are yes and no.

The Library element can have two child elements:

• title: the name to be displayed for the library in query results and on admin pages.
• tagline: an optional short description of the library to be displayed on query results pages in the classic UI.

4.3 The FileService Element

The FileService element configures the File Cabinets.

• maxsize: the maximum size of a POST upload in megabytes. The default is 75.
• timeout: the maxmum time in days to retain a file in the Shared File Cabinet before automatically deleting it. A zero value indicates to keep shared files forever.

4.4 The news Element

The optional news element specifies a link to a MIRCdocument, along with the title and a representative image. These are displayed on the query page, allowing a user to click the title or the image and go directly to the document without going through a query. This element is updated by an admin clicking on the Case of the Day button on a MIRCdocument. It is removed by checking a box on the Query Service Admin page.

5 The MIRC Servlet

The MIRC servlet (mirc.MircServlet) is installed with /mirc context.

When called with the /mirc path, it redirects the request to the /query path. This is just for backward compatibility with the Tomcat/MIRC version.

It has several other, somewhat eclectic, uses:

• When called with the /mirc/roles path, it returns a comma-separated list of the defined roles on the system. Defined roles are just those additional roles listed in the mirc.xml file.
• When called with the /mirc/roles/xml path, it returns an XML structure containing a list of all the roles on the system, including defined roles and the roles built into the User Manager.
• When called with the /mirc/version path, it returns the version of the MIRC.jar file as defined in its manifest.
• When called with the /mirc/libraries path, it returns an XML structure containing a list of all the Libraries on the system, with the address attributes of local libraries updated to include the value of the siteurl attribute. The order of the Library elements is alphabetical by their title elements.
• When called with the /mirc/sortedlibraries path, it returns an XML structure containing a list of all the Libraries on the system, with the address attributes of local libraries updated to include the value of the siteurl attribute. The order of the Library elements is alphabetical by their title elements, except that all the local libraries come first.
• When called with the /mirc/phi path, it returns the contents of the Access Log, a file that is typically stored as Ctrp/mircsite/phi/AccessLog.txt. This function is only available to users with the admin role.

6 Users, Roles, and Preferences

TFS users have accounts defined in the CTP/users.xml file. A user has a username, a password, and a set of roles.

Access to user accounts is provided by the org.rsna.server.Users class. This class has two subclasses, one that authenticates passwords as stored in the XML file and one that authenticates passwords against an external LDAP server. (See the Server article for more information.)

The admin user has access to a User Manager Servlet to create or delete accounts, and to assign roles to users. The CTP application assigns the standard org.rsna.servlets.UserManagerServlet to the context /users before it starts the plugins and pipelines, but the MIRC plugin subsequently overrides that context with the mirc.users.MircUserManagerServlet.

In addition to an account, a user also has a set of preferences that are unique to TFS. The preferences are stored in the JDBM CTP/mircsite/preferences database. Users have access to the Preferences Servlet to manage their preferences.

6.1 MircUserManagerServlet

The MircUserManagerServlet allows the admin user to manage the CTP/users.xml file. It also allows the admin user to enter certain preferences (person name, affiliation, and contact) on behalf of a user.

The servlet allows the admin user to set passwords for users, but if the server is configured for LDAP authentication, these passwords are ignored. The servlet provides no way to update passwords in an LDAP server.

6.2 PreferencesServlet

The PreferencesServlet allows an individual user to manage the preferences database entry for his account. It also provides a way for a user to change his password, although as noted above, passwords in the CTP/users.xml file are ignored in servers configured to use LDASP authentication.

The managed preferences are:

• UI: the individual user's choice of UI (classic or integrated). This choice overrides the site default as soon as the user is authenticated. This preference is automatically updated whenever the user changes the UI through either the Classic UI lin in the footer of the Integrated UI query page or the Switch to Integrated User Interface menu item in the Help menu of the Classic UI. Thus, the system always provides the user the last UI in effect when the user last accessed the system.
• Password change
• Personal information: the information that is used to populate the author element when a user creates a MIRCdocument. The person name is also displayed in the header bar of the Integrated UI. This information can be updated by the admin user through the MircUserManagerServlet. This information is also automatically updated when the user creates a MIRCdocument through one of the author services.
  • Name: the person name
  • Affiliation: normally the user's department or university name
  • Contact: normally the user's email address or phone number
• MyRSNA credentials: the username and password of the user's MyRSNA account. These credentials are used by the server to upload MIRCdocuments to the user's MyRSNA Files.
• Export destinations: a list of destination URLs and credentials for use in exporting MIRCdocuments from one library to another (possibly on a different server).

7 QueryService

The Query Service is the primary portal into TFS. It is implemented in the mirc.query.QueryService class, which extends org.rsna.servlets.Servlet. The doGet method has three important responsibilities:

• It verifies that the request used the same URL that is known to the site, and it redirects the request to the site URL if it did not. This is necessary to ensure that session information will be passed to the Storage Service when a document is viewed.

A successful login generates a Set-Cookie for the RSNASESSION cookie. This cookie carries the information that authenticates a request as belonging to a specific user session. Browsers supply cookies in requests based on the text of the URL. Thus, a cookie that was set for 127.0.0.1 will not be supplied in a request using 192.168.0.4, even if the two IP addresses refer to the same system. When a user clicks on a query result to view a MIRCdocument, the URL is based on the site URL. If the MIRCdocument requires authentication, it is important that the RSNASESSION cookie be supplied in the request to enable the Storage Service to obtain the user's roles. Thus, it is critical that all the requests use the site URL.

• It determines whether the request includes a query, in which case it services the query as if it had been received as a POST.

• If the request did not include a query, it generates a query page based on the selected UI.

The mirc.query.UI interface is implemented by two classes: mirc.query.ClassicUI and mirc.query.IntegratedUI. Each class generates a page using an XSL transform obtained from the MIRC.jar file:

• /query/ClassicUI.xsl
• /query/IntegratedUI.xsl

The Query Service handles queries in the serviceQuery method. This is called from either the doGet or doPost methods depending on the request. The serviceQuery method first constructs an XML object from the parameters of the request, and then transforms that object into an XML object in the MIRCquery schema. (See The MIRCquery Schema for more information.)

The Query Service instantiates one mirc.query.MircServer object for each library (local or remote) to be queried and passes it the MIRCquery XML object. The MircServer objects are separate threads that handle the connection to the library and the receipt of the query results.

Once all the MircServers have been started, the Query Service polls them to see when all have finished receiving their query results. The whole process respects the value of the timeout obtained from the singleton MircConfig object that encapsulates the MIRC configuration.

When the MircServers have finished, the Query Service assembles a single XML object containing all the query results. The query results are returned in one of three forms, depending on the parameters of the query:

• In the Integrated UI, a query is an AJAX call, and the query results XML object is returned directly, and the Javascript programmatically populates the query results table on the query page.
• In the Classic UI, normal results are in the form of a page showing a list of links to matching MIRCdocuments. The page is constructed by transforming the query results XML object with the /query/MIRCqueryresult.xsl program.
• In the Classic UI, Case Navigator results are in the form of a page with a header bar providing navigation and a main body showing a matching MIRCdocument. The page is constructed by transforming the query results XML object with the /query/CaseNavigatorResult.xsl program.

In the Integrated UI, it is possible to select one or more MIRCdocuments from the query results table and click an icon to display the selected documents in the Case Navigator. This is performed by the mirc.casenav.CaseNavigatorService servlet. This servlet simply constructs an XML object containing the selected documents and then transforms it using the /query/CaseNavigatorResult.xsl program, resulting in the requested page.

7.1 QueryServiceAdmin

The QueryServiceAdmin servlet provides a UI for managing the CTP/mircsite/mirc.xml file. The doGet method generates a page containing a form, and the doPost method updates the file from the form parameters. The servlet does not write the file directly; it makes calls to the singleton mirc.MircConfig object to do the updates and write the file.

8 StorageService

The StorageService servlet is the primary interface into the stored MIRCdocuments in the system. It responds to requests whose paths start with /storage.

In general, a request URL has one of two forms:

/storage/delete/{ssid}/{MIRCdocumentPath}

/storage/{ssid}/{MIRCdocumentPath}?{query}

where:

• {ssid} is the identifier of the local library containing the MIRCdocument
• {MIRCdocumentPath} is the path to the MIRCdocument from the root of the library.

Local libraries are stored in root directories in this structure

CTP/mircsite/storage/{ssid}

The doGet method provides different responses depending on the requested resource, the supplied query parameters, and the requesting user's roles.