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. Prerequisites for understanding this article are The Util Module and The CTP Module.

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 CTP/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 mirc.users.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 mirc.prefs.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 mirc.qsadmin.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 mirc.storage.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/{function}/{ssid}/{MIRCdocumentPath}

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

where:

• {function} is a function name. The only supported function is delete.
• {ssid} is the identifier of the local library containing the MIRCdocument. All {ssid} path elements start with ss, which allows them to be distinguished from {function} path elements.
• {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 from the root of a library to a MIRCdocument always starts with docs.

Each MIRCdocument in a library is stored in its own directory. The directory contains the MIRCdocument's XML file and any files that it references. The referenced files are typically images, but there is no restriction on the types of files that can be referenced.

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

• If the request calls the delete function, it deletes the MIRCdocument. (I know that this is not RESTful, but it grew up organically, and it might be nice to implement the rest of the RESTful methods in the server and then reflect that in all of TFS, but that's for someone else to do.)

• If the requested resource has the .dcm extension, there are several possibilities, depending on the query parameters:
  • If the dicom query parameter is supplied (with or without a value), a web page is generated listing the DICOM elements.
  • If the params query parameter is supplied (with or without a value), an XML structure is returned listing several key technical parameters of the DICOM object. This feature is used in the Advanced Author Service on the pane that allows a user to change the WW/WL values of an image.
  • If the jpeg query parameter is supplied (along with parameters specifying a frame number, a compression quality value, and WW/WL values), a JPEG image is returned with the requested characteristic of the DICOM object. This feature is used in the Advanced Author Service on the pane that allows a user to change the WW/WL values of an image.
  • If the update query parameter is supplied (along with parameters specifying a frame number, a compression quality value, and WW/WL values, plus parameters identifying the MIRCdocument XML file and whether to update only the requested resource or all images of the same series), a background thread is started to update the WW/WL values of the identified images. This feature is used in the Advanced Author Service on the pane that allows a user to change the WW/WL values of an image.
  • If the bi query parameter is supplied (with or without a value), an attempt is made to return a serialized BufferedImage. This feature does not work because BufferedImage is not serializable. The code is left in place against the day when somebody figures out how to do it.
  • If none of the above conditions are met, the servlet returns the requested resource with the Content-Type application/dicom.

• If the requested resource has the .xml extension, there are several possibilities, depending on the root element name and the query parameters:
  • If the root element name is not MIRCdocument, the servlet returns the requested resource with the Content-Type text/xml;charset=UTF-8.
  • If the ppt query parameter is supplied (with or without a value) and the user has the export privilege on the MIRCdocument, the servlet creates a presentation file for the requested resource and returns it with the Content-Type application/vnd.openxmlformats-officedocument.presentationml.presentation and a Content-Disposition allowing the file to be saved as a .odp file.
  • If the zip query parameter is supplied (with or without a value) and the user has the export privilege on the MIRCdocument, the servlet creates a zip file for the MIRCdocument and returns it with the Content-Type application/zip and a Content-Disposition allowing the file to be saved. If the ext parameter is present, its value is used as the extension of the file; otherwise, the extension is .zip.
  • If the xsl query parameter is supplied (with or without a value), the servlet filters the PHI out of the MIRCdocument and returns the resulting XML with Content-Type text/xml;charset=UTF-8. There is no requirement that the user have the export privilege on the MIRCdocument. The reason is that this feature is used by third-party phone and tablet apps to obtain the XML so they can render it themselves. Note: the filter operation is by-passed if the user is the owner of the MIRCdocument.
  • If none of the above conditions are met, the servlet transforms the MIRCdocument XML using the /storage/MIRCdocument.xsl resource from the MIRC.jar and returns it with Content-Type text/html;charset=UTF-8.

The doPost method responds to queries from Query Services. It expects a MIRCquery XML structure with the Content-Type text/xml, and it returns a MIRCqueryresult XML structure. The query is implemented by searching the indexes of the libraries identified in the MIRCquery.

The index of all libraries is encapsulated by the mirc.storage.Index class. This class has a static getInstance(String ssid) method that returns a singleton instance of the index of the specified library. Each library index is a JDBM database that contains many HTrees that index specific MIRCdocument schema elements, plus HTrees that are used for free text queries. All the library indexes are stored in the CTP/mircsite directory.

The HTrees include each word indexed, plus all substrings of the word. This mechanism is the most efficient that has been implemented to date in TFS; nevertheless, it is possible that a change to SOLR would provide greater efficiency as well as additional features. When this change is made, a new mirc.storage.Index class should be all that is needed to interface it to the rest of TFS.

8.1 StorageServiceAdmin

The mirc.ssadmin.StorageServiceAdmin servlet provides a UI for managing the library parameters in 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.

The servlet allows the admin user to create and delete libraries. When deleting a library, the references to the library in the CTP/mircsite/mirc.xml file are removed; neither the index nor the stored MIRCdocuments of the library are deleted.

8.2 Support Services

There are several other servlets that are related to the Storage Service, so they are described here.

8.2.1 AddImagesService

The mirc.addimg.AddImagesService servlet allows a user with the update privilege on a MIRCdocument to add images to it.

The servlet context is addimg. It is triggered by clicking the Add images to this Document button on the MIRCdocument.

The servlet contains only a doPost method. The method receives a POST with Content-Type multipart/form-data containing files from the client to add to the MIRCdocument. The method that inserts the files automatically unpacks zip files and inserts their contents.

After adding the files, the servlet redirects the client to the MIRCdocument so it will be rendered with the new files.

8.2.2 SortImagesService

The mirc.sort.SortImagesService servlet allows a user with the author role and the update privilege on a MIRCdocument to sort the images in the image-section by a series of keys:

• StudyDate
• StudyTime
• StudyInstanceUID
• SeriesInstanceUID
• AcquisitionInstanceUID
• InstanceNumber

The servlet context is sort. It is triggered by clicking the Sort the Image Section button on the MIRCdocument.

The sorting is accomplished in the sortImageSection method of the mirc.util.MircDocument class.

The servlet contains only a doGet method.

After sorting the image-section and saving the file, the servlet redirects the client to the MIRCdocument so it will be rendered with the images in the new order.

8.2.3 CommentService

The mirc.comment.CommentService servlet allows a user with the author role to create comment threads in and post comments to a MIRCdocument.

The servlet contains only a doPost method.

The servlet context is comment. It responds to two URLs:

• /comment/newthread
• /comment/newpost

A collection of comment threads is encapsulated in a threadblock element in the MIRCdocument. A threadblock element is uniquely identified by an id attribute.

Comment threads are encapsulated in thread elements in the MIRCdocument. They are uniquely identified by an id attribute. The newthread command requires two query parameters:

• threadblockID
• threadtitle

Individual posts to a thread are encapsulated in post child elements of the thread element. They appear in the order in which they were inserted, and they are not uniquely identified. The newpost command requires two query parameters:

• threadID
• posttext

The servlet obtains the username from the request and then gets the user's person name from the preferences database. It includes that information as well as the current date in the XML that is added to the MIRCdocument.

After inserting the thread or post and saving the file, the servlet redirects the client to the MIRCdocument so it will be rendered with the changes.

8.2.4 RevertService

The mirc.revert.RevertService servlet allows a user with the update privilege on a MIRCdocument to change it from a completed case to a draft case.

The servlet contains only a doGet method.

The servlet context is revert. It is triggered by clicking the Revert to draft status button on the MIRCdocument.

A draft case is one for which the MIRCdocument root element has the temp attribute set to yes. Normally, a draft case is created automatically by the DICOM Service or the TCE Service. When a draft case is opened and then saved, the Advanced Author Tool converts it to a completed case by removing the temp attribute and storing it in a different folder from the one automatically created for it when it was first constructed. At the same time, the tool adds the draftpath attribute pointing to the location it had as a draft document.

The DICOM Service inserts DICOM images into a MIRCdocument (creating the MIRCdocument if necessary) based on one of the elements in the image. If the DICOM Service is operated in the patient-centric mode, the element used to construct the folder for the MIRCdocument is the PatientID. If the service is operated in the study-centric mode, the element is the StudyInstanceUID. Once a MIRCdocument has been converted to a completed case, the document is in a different folder, so subsequent images for the same patient or study will cause the creation of a new draft document. The purpose of the RevertService is to allow a document to be switched back to the draft status so new images can be added through the DICOM Service.

Conversion back to the draft status is only possible if the draftpath attribute is available in the root element. Once the conversion is done, the URL of the document changes to the one it had when it was originally created as a draft case, and the URL it had as a completed case is no longer valid.

After converting the document to a draft case, the servlet redirects the client to the MIRCdocument so it will be loaded from the new location.

8.2.5 PublishService

The mirc.publish.PublishService servlet allows a user with the publisher role to make a MIRCdocument public. Making a MIRCdocument public is done by inserting an asterisk in the MIRCdocument.authorization/read element. Public documents can be viewed by unauthenticated users.

The servlet contains only a doGet method.

The servlet context is publish. It is triggered by clicking the Publish button on the MIRCdocument.

When publishing a document, the service removes the publication request, if present, from the document.

A publication request is indicated by setting the pubreq attribute of the root element to yes. This is done automatically when a non-publisher attempts to publish a document on a library for which the autoindexing is not enabled.

After publishing the document, the servlet redirects the client to the MIRCdocument so it will reflect the public status.

9 ConferenceService

The mirc.confs.ConferenceService servlet provides access to a JDBM database of conferences, organized into two categories:

• Shared conferences are accessable by unauthenticated users
• Personal conferences are visible only to the user who created them.

The database is implemented in the mirc.confs.Conferences class. The database is contained in the CTP/mircsite/conferences.db file.

A conference is implemented in the mirc.confs.Conference class. A conference may contain both child conferences and agenda items, providing a hierarchy.

Agenda items are implemented in the mirc.confs.AgendaItem class. An agenda item is essentially a link to a resource. In most cases, the resource is a MIRCdocument, but it is possible to have an agenda item that is simply a URL pointing to any web resource.

The servlet context is confs.

The servlet contains only a doGet method.

• When accessed with the /confs path, the servlet returns a web page with a left pane for navigating the hierarchy of public and personal conferences.
• When accessed with the /confs/casenavigator path, the servlet returns a web page showing the agenda items in the Case Navigator format (as if the user had done a query that resulted in the list of MIRCdocuments that are in the conference).
• All other paths return XML structures. These requests come from Javascript AJAX calls on the query pages or on the Conference Service page.

In retrospect, the index of conferences would have better as a part of the mirc.storage.Index class. The current implementation suffers from two significant problems:

• Agenda items do now know the permissions of the target resource, so restricted documents may be listed for users who do not have permission to view them.
• If a MIRCdocument is deleted, the conferences in which it appears are not notified to delete the corresponding agenda items.

If the storage index is changed to SOLR, it would be wise to consider changing the conference mechanism so the information is normalized.

10 FileService

The mirc.files.FileService servlet provides access to directory trees of files, organized into two categories, called file cabinets:

• The Shared file cabinet is accessable by all authenticated users
• Personal file cabinets are visible only to an individual user.

The purpose of the File Service is to allow users to store files of any kind, outside the structure of the MIRCdocument libraries.

The root of the hierarchy is CTP/mircsite/files.

• The root of the Shared file cabinet is CTP/mircsite/files/Shared.
• The root of a user's Personal file cabinet is CTP/mircsite/files/Personal/{username}.

Within a file cabinet, there are two subfolders, one for files, and one for icons that are displayed when the contents of a file cabinet are shown on a web page.

• CTP/mircsite/files/Personal/{username}/Files
• CTP/mircsite/files/Personal/{username}/Icons

The two subfolders have exactly the same structure. For each leaf file in the Files tree, there is a corresponding leaf file in the Icons tree, with the same name, but with an appended extension (.jpg or .gif). For example, these two files correspond:

• CTP/mircsite/files/Personal/{username}/Files/folder1/folder2/file.dat
• CTP/mircsite/files/Personal/{username}/Icons/folder1/folder2/file.dat.jpg

The servlet context is files.

The servlet allows the admin user to create and delete libraries. When deleting a library, the references to the library in the CTP/mircsite/mirc.xml file are removed; neither the index nor the stored MIRCdocuments of the library are deleted.

The servlet contains both doGet and doPost methods for managing the file cabinets, creating and deleting subfolders, uploading, downloading files, and deleting files, etc. For DicomObjects, it also provides a an element listing page. As in all TFS upload functions, if the user uploads a zip file, the file is automatically unpacked and its individual files are put into the file cabinet. This process is not recursive, so it is possible to put a zip file into a file cabinet by encapsulating it in another zip file before uploading it.

The File Service also has a DICOM Storage SCP to allow files to be received from a PACS or DICOM workstation and stored in the file cabinets. The function is implemented in a CTP pipeline. See File Service Pipeline for details.

10.1 FileServiceAdmin

The mirc.fsadmin.FileServiceAdmin servlet provides a UI for controlling the maximum upload size for files and for setting the maximum time files are kept in the Shared file cabinet before being automatically deleted.

The automatic deletion mechanism is implemented in the mirc.fsadmin.SharedFileCabinetManager class. That class is a daemon thread that periodically looks for files that are older that the specified maximum and deletes them.

11 Author Services

TFS contains several mechanisms for manually creating MIRCdocuments.

11.1 The Advanced Author Service

The mirc.aauth.AuthorService servlet provides a UI for creating MIRCdocuments from a template. Templates are described in detail in MIRC Templates. The Advanced Author Service is the most complete authoring tool of all the TFS authoring tools; it supports all the elements described in The MIRCdocument Schema.

The context of the servlet is aauth.

The doGet method provides different responses depending on the path.

• The /aauth/{ssid} path displays the template selection page, listing the user's preferences for person name, affiliation, and contact, plus an option for choosing a template to serve as the starting point for creating a new MIRCdocument. The templates are contained in MIRC.jar in the /aauth/templates directory. They are copied to the disk into the CTP/mircsite/aauth directory when required. On the template selection page, an example of the format of the MIRCdocument tempate is displayed when the template is selected. The example images are in MIRC.jar in the /aauth/tokens directory.

• The /aauth/{ssid}/{librarypath}/{MIRCdocument}.xml path opens the MIRCdocument in the editor window.

The doPost method handles three general cases, depending on the request path and whether the request includes the docText parameter.

• If the request path is /aauth/{ssid} and the the docText parameter is missing, the request is a POST from the template selection page, in which case the servlet opens the selected template in the editor window. At this time, the servlet also copies the user's person name, affiliation, and contact information from the form parameters to the user's preferences.

• If the request path is /aauth/{ssid} and the docText parameter is present, the request is a POST of the content of a new MIRCdocument, in which case the servlet creates a new directory in the specified library, saves the text of the docText query parameter as the MIRCdocument.xml file, and then inserts any files identified in the XML from the file cabinets.

• If the request path is /aauth/{ssid}/{librarypath}/{MIRCdocument}.xml and the docText parameter is present, the request is a POST of the edited contents of an existing MIRCdocument, in which case there are two cases:
  • If the original document was a draft document (as indicated by the root element having the temp="yes" attribute), then the document is first moved to a different directory in the same library. Then, the servlet replaces the text of the original MIRCdocument with the text of the docText parameter, and then inserts any files identified in the XML from the file cabinets. See the Revert Service section for more information about draft documents.
  • If the original document was not a draft document, the servlet replaces the text of the original MIRCdocument with the text of the docText parameter, and then inserts any files identified in the XML from the file cabinets.

When processing the text of a docText parameter, the servlet first saves it to the appropriate file and then instantiates an org.util.MircDocument object from the file. It then uses that object for subsequent modifications and save operations.

In the text of the docText parameter, references to files in the file cabinets are src, href, or docref attributes that have the form "[path]", where path starts with either Shared or Personal. When such references appear, the servlet copies the files from the file cabinets to the MIRCdocument's directory and changes the attribute values to point to the files in that location.

The editor window is generated by an XSL transform using the /aauth/Editor.xsl program in MIRC.jar. This program produces an HTML page that references several Javascript files from either MIRC.jar or util.jar. The principal Javascript file is /aauth/Editor.js.

11.2 The Basic Author Service

The mirc.bauth.BasicAuthorService servlet provides a UI for creating MIRCdocuments from a template. Templates are described in detail in MIRC Templates. The Basic Author Service is a very simplified authoring tool. It provides no means for adding elements to the document that are not in the template. Further, whereas the Advanced Author tool has access to files stored in the file cabinets, the Basic Author tool requires that any files added to the document when it is created are uploaded from the client. A common use of the Basic Author tool is to create an initial version of the document. The document is then opened in the Advanced Author tool for adding content beyond what was supported by the template.

The context of the servlet is bauth.

The doGet method responds to the /bauth/{ssid} path and provides a form for selecting a template and entering information into the document. The templates are contained in MIRC.jar in the /bauth directory. They are copied to the disk into the CTP/mircsite/bauth directory when required. The form is generated by an XSL transform using the /bauth/BasicAuthorService.xsl program in MIRC.jar. This program produces an HTML page that references several Javascript files from either MIRC.jar or util.jar, but the page does not have the complex interactivity of the Advanced Author tool's Editor page. The principal Javascript file is /bauth/BasicAuthorService.js.

The doPost method receives the form parameters and any posted files and creates the MIRCdocument in the selected library.