Package jmri.web.xmlio

Show UML class diagram

The JMRI XML I/O package allows communications to and from a running JMRI program through the exchange of XML-format information.

See:
Description

Interface Summary

XmlIORequestor	Interface received a delayed response to a monitoring request.
XmlIOServer	Interface for doing XML I/O.

Class Summary

DefaultXmlIOServer	Default implementation for XML I/O.
XmlIOFactory	Provide server objects for doing XML I/O This file is part of JMRI.

Package jmri.web.xmlio Description

The JMRI XML I/O package allows communications to and from a running JMRI program through the exchange of XML-format information.

Serialization of the XML is done elsewhere, for example in the jmri.web.servlet.xmlio Servlet package, as this package works via the exchange of JDOM Element objects.

Both synchronous reads and writes, and asynchronous read and monitor operations are available.

The XmlIOFactory class provides XmlIOServer objects, which handle the interactions. Each XmlIOServer is independent and thread safe.

The XML schema is defined in the xmlio.xsd schema document. A typical message is

<xmlio>
    <item>
        <type>turnout</type>
        <name>Turnout 12</name>
        <set>4</set>
    </item>
    <item>
        <type>turnout</type>
        <name>Turnout 12</name>
        <value>4</value>
    </item>
    <item>
        <type>sensor</type>
        <name>IS34</name>
    </item>
</xmlio>

The presence of a <set> element indicates a write; the returned element will have the <set> element deleted, but the item will remain present.

All writes are done before the values are collected for any reads, but there is no guarantee that the consequences of the writes have propagated completely.

A synchronous request completes immediately, having made any changes needed and returning current values.

An asynchronous request returns immediately iff any object has a value different from its value element. Otherwise, it returns when any values for any of the items changes. All values are provided; because of the asynchronous nature there may be more than one change recorded.

By sending an Element back and forth as an asynchronous request, a client may reliably get all changing values without risk of losing changes that occur while elements are in transmission. Just send an element containing references to, but not set requests for, all interesting objects, and then keep turning it around as an asynchronous request. The first reply will be immediate, returning the initial values. Later iterations will only return when changes have been made.

A <list> element returns all existing objects of a given type as a list of <item> elements. This can then be turned around to start a sequence of read and monitor operations.

<xmlio>
    <list>
        <type>turnout</type>
    </list>
</xmlio>

A <throttle> element can be used to control a DCC Throttle via the default ThrottleManager. The first use allocates the throttle, and all later ones set any attributes present:

<xmlio>
    <throttle>
        <address>1234</address>
        <speed>0.75</speed>
        <forward>true</forward>
        <F3>false</F3>
    </throttle>
</xmlio>

A throttle element is returned unchanged.

Related Documentation

C.F. K H Wolf, K Froitzheim, M Weber, Department of Distributed Systems, University of Ulm, "Interactive Video and Remote Control via the World Wide Web", in "Lecture Notes in Computer Science", Springer, Berlin, 1996.
Previously in Volume 7, Number 5 of "Marklin Digital Newsletter", Dr. T Catherall Ed, September/October 1995, page referenced rehosted.

Since:

2.7.1