JMRI: XML Usage

JMRI uses XML for a number of purposes: to hold decoder definitions, for its persistance system for configuration and panel information, and to create parts of the web site from other files. This page describes some aspects of this.

Access to File Format Definitions

JMRI uses DTDs to define the format of its files.

Those DTDs need to be available to the program when it reads the files, as they define the default values of missing attributes and other needed information.

In the JMRI distributions, these are stored in the xml/DTD directory. Note that they are not stored in each directory alongside the XML files. There are just too many locations to keep such a set of DTD files up to date. JMRI itself, via the jmri.jmrit.XmlFile class, provides support for locating those files when the XML parser needs them.

Each file contains a DOCTYPE line that specifies a DTD name. There are three different methods used to locate the actual DTD file:

Web browsers look exactly where the DOCTYPE line specifies, and must find the DTD there to function.
JMRI 1.8 and earlier assumes that the name is relative to the program's xml/DTD directory, and looks for it using that. In practice, this allows two forms for the DOCTYPE line:
- name.dtd
- ../DTD/name.dtd
Early XML files used both; the program itself could generate either depending on the circumstances.
JMRI 1.9.2 through 2.0 provide a more powerful DTD search procedure using the jmri.util.JmriLocalEntityResolver class. It parses the reference in the DOCTYPE and handles it in several ways:
- If it's an HTTP URL, JMRI first attempts to find the corresponding file in the local distribution. If so, it uses the local copy, otherwise it attempts to load a copy from the Internet using the URL.
- If it's a file path that starts with "../DTD/", JMRI looks in it's local xml/DTD directory for the DTD file.
- If the path is just a filename, JMRI looks in it's local xml/DTD directory for the DTD file.
- In any other case, e.g. a local or absolute pathname, JMRI looks there for the DTD file. Relative pathnames are interpreted as starting from the JMRI install directory.
If the file can't be found, the XML file isn't opened.
These JMRI versions write just the DTD filename in the DOCTYPE line when writing XML files.
This provides complete backward compatibility with existing files and older versions of JMRI back to 1.7.1. At the same time, since it can handle HTTP URLs even without an Internet connection, it allows us to eventually move forward.

The JMRI 2.1 test release series will eventually start writing HTTP URL DOCTYPE lines in it's output XML files. These will still be readable by JMRI 2.0, the prior production version, but will also allow us to version control the DTD files. We're going to need that capability eventually, and this is a way to get to it.

Formatting with XSLT

The xml/XSLT directory contains a number of XSLT transformations that can be used to format JMRI XML files. They are used in several ways, described here.

Web Pages from Decoder Definitions

There's an Ant build.xml file provided which runs a number of transforms to create web pages from the decoder files. These are then uploaded to the web site as part of each release.

Viewing XML Files

There are also XSLT transforms that are used as stylesheets when displaying a JMRI XML file in a web browser. In most cases, they just provide a human readable form. For decoder definition files, this goes further to convert the file to a form which can be used to submit updates.

To ease this, JMRI writes a line like

<?xml-stylesheet href="http://jmri.sourceforge.net/xml/XSLT/panelfile.xsl" type="text/xsl"?>

at the start of each file. When the browser encounters this, it loads the stylesheet from the main JMRI web server and uses it to transform the XML file into HTML, which it then displays.

Use without Internet Access

If you don't have a web connection, or want to use a local copy of the spreadsheet for some reason, just change the href URL. For example, href="panelfile.xsl" would reference a local file in the same location as the file being viewed.

Note that there's a known bug in recent versions of Firefox that prevents it from loading the stylesheet from the Internet, even when access is available. Normally, security requires that pages loaded from remote locations (e.g. servers, not the local computer) are not allowed to reference local resources (e.g. local files). This prevents malicious pages from accessing your local secrets. On the other hand, there's no problem with a local page referencing a remote page; that happens all the time. Unfortunately, the current (December 2007) versions of FireFox have this backwards, allowing remote pages to access local ones and preventing local ones from accessing remote resources. This stops a local JMRI XML page from loading the remote formatting information, and prevents the page from displaying. Use the solution described above for the case of no access: Put a copy of the stylesheet in the same directory as the file you want to display, and then edit the xml-stylesheet line to point to that directly.

Standards and Future Work

Once JMRI has moved forward to Java 1.4, we will consider moving from DTDs (which have issues of name reuse, localization, etc) to schema for defining our formats.

The OASIS collaboration defines a number of schema and schema elements that have become well-known standards. Were possible, we should use those standard elements to improve inter-operability. Perhaps the first ones of interest are:

DockBook defines elements for several concepts we use:
- author
- address
UBL, though aimed at business transactions, defines elements to represent parties (companies, people), devices, model numbers, etc.
OpenDocument (OODF) defines a set of elements and structures for computations as part of its spreadsheet module.

Learning to use these will require some work, as we can't assume that computers using JMRI have internet access, so can't just reference the entire schema as remote entities.