Serge NOEL
271 lines
8.7 KiB
Plaintext
271 lines
8.7 KiB
Plaintext
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy for HTML5 for Apple macOS version 5.8.0">
|
|
<!-- Copyright 2015 -->
|
|
|
|
<title>JMRI: XML I/O Servlet - no longer supported</title><!--#include virtual="/help/en/parts/Style.shtml" -->
|
|
</head>
|
|
<body>
|
|
<!--#include virtual="/help/en/parts/Header.shtml" -->
|
|
|
|
<div id="mBody">
|
|
<!--#include virtual="Sidebar.shtml" -->
|
|
|
|
<div id="mainContent">
|
|
<h1>JMRI: XML I/O Servlet - no longer supported</h1>
|
|
<strong>The XML I/O protocol was removed from JMRI in the 3.11 development
|
|
cycle.</strong><br>
|
|
Affected applications should be ported to using the <a href="JsonServlet.shtml">JSON
|
|
protocol</a>.<br>
|
|
This page is only for reference of older versions.
|
|
<p>The JMRI XML I/O Servlet provides bidirectional web access to JMRI services.</p>
|
|
|
|
<p>The servlet lives in the <a href=
|
|
"https://jmri.org/JavaDoc/doc/jmri/web/servlet/xmlio/package-summary.html">jmri.web.servlet.xmlio</a>
|
|
package, and provides web access to the <a href=
|
|
"https://jmri.org/JavaDoc/doc/jmri/web/xmlio/package-summary.html">JMRI XML I/O package</a>.
|
|
By default, the JMRI Web Server will send any URL that starts with <code>/xmlio</code> to
|
|
this servlet. It will list all known elements of a specified type, accept changes to the
|
|
value/state of elements, and respond with current value/state of elements. If sent a list of
|
|
elements with current values, it will "monitor" for changes to any of those elements,
|
|
returning the new values.</p>
|
|
Element types fully supported:
|
|
<ul>
|
|
<li>power</li>
|
|
|
|
<li>turnout</li>
|
|
|
|
<li>sensor</li>
|
|
|
|
<li>signalhead</li>
|
|
|
|
<li>signalmast</li>
|
|
|
|
<li>memory</li>
|
|
|
|
<li>route</li>
|
|
</ul>
|
|
Element types list-only:
|
|
<ul>
|
|
<li>roster</li>
|
|
|
|
<li>frame</li>
|
|
|
|
<li>panel</li>
|
|
|
|
<li>metadata</li>
|
|
|
|
<li>railroad</li>
|
|
</ul>
|
|
Throttle is a unique case, with a slightly different syntax, supporting read and change, but
|
|
not list or monitoring:
|
|
<ul>
|
|
<li>throttle</li>
|
|
</ul>
|
|
There are several sample pages that (used to) show how this can be used:
|
|
<dl>
|
|
<dt>
|
|
<a href="http://localhost:12080/web/request.html">web/request.html</a>
|
|
</dt>
|
|
|
|
<dd>Makes a single XML request for all available sensors, and shows their status in a
|
|
table.</dd>
|
|
|
|
<dt>
|
|
<a href="http://localhost:12080/web/monitor.html">web/monitor.html</a>
|
|
</dt>
|
|
|
|
<dd>Uses delayed requests to monitor the status of all sensors, updating a table when any
|
|
change.</dd>
|
|
|
|
<dt>
|
|
<a href="http://localhost:12080/web/throttle.html">web/throttle.html</a>
|
|
</dt>
|
|
|
|
<dd>Sends a speed command to a DCC locomotive on the layout when a button is pressed.</dd>
|
|
|
|
<dt>
|
|
<a href="http://localhost:12080/web/turnoutPanel.html">web/turnoutPanel.html</a>
|
|
</dt>
|
|
|
|
<dd>Example of a control panel on a web page.</dd>
|
|
|
|
<dt>
|
|
<a href="http://localhost:12080/web/turnoutMonitor.html">web/turnoutMonitor.html</a>
|
|
</dt>
|
|
|
|
<dd>More complex turnout table, with buttons to throw and close turnouts.</dd>
|
|
|
|
<dt>
|
|
<a href="http://localhost:12080/web/JMRI_XMLIO_test.html">web/JMRI_XMLIO_test.html</a>
|
|
</dt>
|
|
|
|
<dd>Useful for sending various commands to xmlio server and viewing the responses.</dd>
|
|
|
|
<dt>
|
|
<a href="http://localhost:12080/web/JMRIMobile.html">web/JMRIMobile.html</a>
|
|
</dt>
|
|
|
|
<dd>This tool uses the xmlio server for retrieving data from JMRI, sending changes and
|
|
monitoring for changes to elements.</dd>
|
|
</dl>
|
|
|
|
<p>Please note that the XML I/O servlet was only supported with the <a href=
|
|
"index.shtml">JMRI Web Server</a>, and may not work with other servlet containers.</p>
|
|
|
|
<h2>Request Format</h2>
|
|
|
|
<p>The XML schema is defined in the <a href="https://jmri.org/xml/schema/xmlio.xsd">xmlio.xsd
|
|
schema document</a>.</p>
|
|
|
|
<p>There is also an attribute-based syntax available (see status examples below). The xmlio
|
|
server responds with the same syntax used in the request.</p>
|
|
|
|
<p>Below are some example requests and responses.</p>
|
|
|
|
<h3>Get the status of individual objects</h3>
|
|
Request:
|
|
|
|
<pre style="font-family: monospace;">
|
|
<xmlio>
|
|
<item>
|
|
<type>turnout</type>
|
|
<name>IT12</name>
|
|
</item>
|
|
<item>
|
|
<type>sensor</type>
|
|
<name>West sensor</name>
|
|
</item>
|
|
<item>
|
|
<type>power</type>
|
|
<name>power</name>
|
|
</item>
|
|
</xmlio>
|
|
</pre>Reply:
|
|
|
|
<pre style="font-family: monospace;">
|
|
<xmlio>
|
|
<item>
|
|
<type>turnout</type>
|
|
<name>IT12</name>
|
|
<value>2</value>
|
|
</item>
|
|
<item>
|
|
<type>sensor</type>
|
|
<name>West sensor</name>
|
|
<value>4</value>
|
|
</item>
|
|
<item>
|
|
<type>power</type>
|
|
<name>power</name>
|
|
<value>2</value>
|
|
</item>
|
|
</xmlio>
|
|
</pre>The "value" element is inserted in the request, and then it's returned as the reply. You can
|
|
just turn the reply around and use it as another request. If "value" elements are present for all
|
|
items, the response will only be returned when one or more of the included item's state has changed
|
|
to something different.
|
|
<h3>Get all objects of a type</h3>
|
|
Request:
|
|
|
|
<pre style="font-family: monospace;">
|
|
<xmlio>
|
|
<list>
|
|
<type>sensor</type>
|
|
</list>
|
|
</xmlio>
|
|
</pre>Reply:
|
|
|
|
<pre style="font-family: monospace;">
|
|
<xmlio>
|
|
<item>
|
|
<type>sensor</type>
|
|
<name>IS1</name>
|
|
<value>2</value>
|
|
</item>
|
|
<item>
|
|
<type>sensor</type>
|
|
<name>IS2</name>
|
|
<value>4</value>
|
|
</item>
|
|
<item>
|
|
<type>sensor</type>
|
|
<name>West sensor</name>
|
|
<value>2</value>
|
|
</item>
|
|
</xmlio>
|
|
</pre>The response can be turned around and used as the next request.
|
|
<h3>Set the status of an object</h3>
|
|
Request:
|
|
|
|
<pre style="font-family: monospace;">
|
|
<xmlio>
|
|
<item>
|
|
<type>turnout</type>
|
|
<name>IT12</name>
|
|
<set>2</set>
|
|
</item>
|
|
</xmlio>
|
|
</pre>Reply:
|
|
|
|
<pre style="font-family: monospace;">
|
|
<xmlio>
|
|
<item>
|
|
<type>turnout</type>
|
|
<name>IT12</name>
|
|
<value>2</value>
|
|
</item>
|
|
</xmlio>
|
|
</pre>The "set" element in the request results in the state being set to the given value, and then
|
|
it's returned in the reply as a value element with the proper value at that point.
|
|
<p>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.</p>
|
|
|
|
<h3>Set the status of an object (attribute-based syntax)</h3>
|
|
Request:
|
|
|
|
<pre style="font-family: monospace;">
|
|
<turnout name="IT12" set="2" />
|
|
</pre>Reply:
|
|
|
|
<pre style="font-family: monospace;">
|
|
<turnout name="IT12" value="2" />
|
|
</pre>
|
|
<h3>Control a Throttle</h3>
|
|
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:
|
|
|
|
<pre style="font-family: monospace;">
|
|
<xmlio>
|
|
<throttle>
|
|
<address>1234</address>
|
|
<speed>0.75</speed>
|
|
<forward>true</forward>
|
|
<F3>false</F3>
|
|
</throttle>
|
|
</xmlio>
|
|
</pre>A throttle element is returned unchanged.
|
|
<h2>Related Documentation</h2>
|
|
|
|
<ul>
|
|
<li>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 "<em>Lecture
|
|
Notes in Computer Science</em>", Springer, Berlin, 1996.</li>
|
|
|
|
<li>Previously in Volume 7, Number 5 of "<em>Märklin Digital Newsletter</em>", Dr. T.
|
|
Catherall Ed, September/October 1995 (<a href=
|
|
"http://rr.informatik.tu-freiberg.de/index.php?con=home&sel=&lang=eng&js=1&">project
|
|
website no longer online</a>).
|
|
</li>
|
|
</ul>
|
|
<!--#include virtual="/help/en/parts/Footer.shtml" -->
|
|
</div>
|
|
<!-- closes #mainContent-->
|
|
</div>
|
|
<!-- closes #mBody-->
|
|
<script src="/js/help.js"></script>
|
|
</body>
|
|
</html>
|