You are viewing a plain text version of this content. The canonical link for it is here.
Posted to scm@excalibur.apache.org by le...@apache.org on 2004/08/13 17:18:18 UTC
svn commit: rev 36352 - excalibur/trunk/site/xdocs/instrument
Author: leif
Date: Fri Aug 13 08:18:17 2004
New Revision: 36352
Added:
excalibur/trunk/site/xdocs/instrument/xml-client-snapshots.xml
Modified:
excalibur/trunk/site/xdocs/instrument/xml-client-snapshot.xml
excalibur/trunk/site/xdocs/instrument/xml-client.xml
Log:
More documentation work.
Modified: excalibur/trunk/site/xdocs/instrument/xml-client-snapshot.xml
==============================================================================
--- excalibur/trunk/site/xdocs/instrument/xml-client-snapshot.xml (original)
+++ excalibur/trunk/site/xdocs/instrument/xml-client-snapshot.xml Fri Aug 13 08:18:17 2004
@@ -41,9 +41,10 @@
For example, to request the <b>instrument-manager.memory.maximum_1000_600</b>
Instrument Sample Snapshot, the following URL can be used. Note that
this assumes that such a sample lease has been granted for the specified
- sample.
+ sample. (The <b>compact</b> flag is being set because some browsers have
+ a difficult time rendering large XML files quickly.)
</p>
- <source><a href="http://localhost:15080/sample.xml?name=instrument-manager.memory.maximum_1000_600">http://localhost:15080/sample.xml?name=instrument-manager.memory.maximum_1000_600</a></source>
+ <source><a href="http://localhost:15080/snapshot.xml?name=instrument-manager.memory.maximum_1000_600&compact=true">http://localhost:15080/snapshot.xml?name=instrument-manager.memory.maximum_1000_600&compact=true</a></source>
<subsection name="Parameters">
<table>
<tr>
@@ -68,10 +69,10 @@
<td>long</td>
<td>
Used to specify a base reference time of the data points included
- in the snaphots.
+ in the snapshots.
<p/>
When requesting a snapshot of an Instrument Sample for the first
- time, this parameter should be ommitted or set to 0.
+ time, this parameter should be omitted or set to 0.
<p/>
However on subsequent requests, this can be set to the value of
the <b>time</b> attribute of the previous request. By doing so,
@@ -286,9 +287,9 @@
<tr>
<td><b>value</b></td>
<td>
- If the <b>compact</b> parameter was set to "false" or ommitted
+ If the <b>compact</b> parameter was set to "false" or omitted
then the each individual data point in the snapshot will be
- represended by a single <b>value</b> child element.
+ represented by a single <b>value</b> child element.
<p/>
Attributes:
<table>
Added: excalibur/trunk/site/xdocs/instrument/xml-client-snapshots.xml
==============================================================================
--- (empty file)
+++ excalibur/trunk/site/xdocs/instrument/xml-client-snapshots.xml Fri Aug 13 08:18:17 2004
@@ -0,0 +1,348 @@
+<?xml version="1.0"?>
+
+<!--
+Copyright 2004 The Apache Software Foundation
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied.
+
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<document>
+ <properties>
+ <author email="leif.AT.tanukisoftware.DOT.com">Leif Mortenson</author>
+ <title>Excalibur Instrument - XML Client - Instrument Sample Snapshot</title>
+ </properties>
+ <body>
+ <section name="XML Client - Instrument Sample Snapshot">
+ <p>
+ The Sample Snapshots URL work similar to the
+ <a href="xml-client-snapshot.html">Sample Snapshot URL</a>
+ except that it makes it possible to request snapshots for several
+ Samples in a single request.
+ </p>
+ </section>
+ <section name="Request">
+ <p>
+ Request parameters are set as HTTP GET parameters when sending the
+ request to the server.
+ </p>
+ <p>
+ For example, to request the <b>instrument-manager.memory.maximum_1000_600</b>
+ and <b>instrument-manager.total-memory.maximum_1000_600</b>
+ Instrument Sample Snapshots, the following URL can be used. Note that
+ this assumes that such a sample leases have been granted for the specified
+ samples. (The <b>compact</b> flag is being set because some browsers have
+ a difficult time rendering large XML files quickly.)
+ </p>
+ <source><a href="http://localhost:15080/snapshots.xml?name=instrument-manager.memory.maximum_1000_600&name=instrument-manager.total-memory.maximum_1000_600&compact=true">http://localhost:15080/snapshots.xml?name=instrument-manager.memory.maximum_1000_600<br/>&name=instrument-manager.total-memory.maximum_1000_600&compact=true</a></source>
+ <subsection name="Parameters">
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Data Type</th>
+ <th>Description</th>
+ <th>Notes</th>
+ </tr>
+ <tr>
+ <td><b>name</b></td>
+ <td>boolean</td>
+ <td>
+ One or more fully qualified names of the Instrument Samples being
+ requested. The names are generated by the Instrument Manager when
+ the Instrument Samples are created. They are each built up using
+ three tokens; the type of the sample, the interval and the size
+ (number of data points).
+ <p/>
+ To request multiple snapshots, the <b>name</b> parameter is specified
+ multiple times.
+ </td>
+ <td>Optional.</td>
+ </tr>
+ <tr>
+ <td><b>base-time</b></td>
+ <td>long</td>
+ <td>
+ Used to specify a base reference time of the data points included
+ in the snapshots.
+ <p/>
+ When requesting a snapshot of an Instrument Sample for the first
+ time, this parameter should be omitted or set to 0.
+ <p/>
+ However on subsequent requests, this can be set to the value of
+ the <b>time</b> attribute of the previous request. By doing so,
+ the last data point of the previous request and all newer data
+ points will be returned. Previous data points will not have
+ changed so there is really no reason to have the server resend
+ them.
+ <p/>
+ It can add complexity to a client, but the bandwidth with the
+ server can be greatly reduced by carefully avoiding the
+ unnecessary retransmition of data points.
+ <p/>
+ If at least one <b>base-time</b> parameter is specified then the
+ number of <b>base-time</b>s must equal the number of <b>name</b>
+ parameters.
+ </td>
+ <td>
+ Optional. If not specified, then it defaults to 0 for all snapshots
+ requested, meaning that all data points will be returned.
+ </td>
+ </tr>
+ <tr>
+ <td><b>packed</b></td>
+ <td>boolean</td>
+ <td>
+ Normally XML is returned in a human-readable pretty format
+ with indenting and line feeds. While this makes it easy to
+ work with, it also adds several percent to the size of the
+ XML returned to the client. By setting the packed parameter
+ to "true", all white space is removed from the generated XML.
+ </td>
+ <td>Optional. Defaults to "false".</td>
+ </tr>
+ <tr>
+ <td><b>compact</b></td>
+ <td>boolean</td>
+ <td>
+ The data point values can be returned in two different XML
+ formats.
+ <p/>
+ The first is a verbose format where each individual data point
+ gets its own <b>value</b> child element with <b>value</b> and
+ <b>time</b> attributes. This can be useful in certain contexts
+ as it allows for easy XSL transformation of the data. The
+ drawback is that the XML can be large when the full set of data
+ points are requested.
+ <p/>
+ The second format is specified by setting the <b>compact</b>
+ parameter to "true". All of the data point values are placed
+ into a comma separated list and stored as the value of a
+ <b>values</b> child element. This results in much smaller
+ XML, but requires that the client be able to parse out the
+ individual values as well as calculate the times of each data
+ point.
+ </td>
+ <td>Optional. Defaults to "false".</td>
+ </tr>
+ </table>
+ </subsection>
+ </section>
+ <section name="Response XML">
+ <p>
+ The XML received in the response will be UTF-8 encoded. The root node
+ will be named <b>samples</b>. A <b>sample</b> child node will be returned
+ for each requested sample which still exists at the time of the call.
+ Samples which have expired will not be returned.
+ </p>
+ <p>
+ Each individual <b>sample</b> child element will have the following attributes.
+ Depending on the value of the <b>compact</b> parameter, either a single
+ <b>values</b> child element, or set of individual <b>value</b> elements will
+ be included.
+ </p>
+ <subsection name="Attributes">
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Data Type</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><b>name</b></td>
+ <td>String</td>
+ <td>
+ Fully qualified name of the Instrument. This
+ name is used to reference the Instrument in
+ other requests.
+ The name is generated by the Instrument Manager when an Instrument
+ Sample is created. It is built up using three tokens; the type of
+ the sample, the interval and the size (number of data points).
+ </td>
+ </tr>
+ <tr>
+ <td><b>description</b></td>
+ <td>String</td>
+ <td>
+ A human readable descripton of the Instrument. If the Instrument
+ Sample was specified in the <a href="configuration.html">Instrument configuration file</a>
+ then the description may have been specified there. Otherwise, the
+ description will have been specified as part of the lease request
+ for the sample.
+ </td>
+ </tr>
+ <tr>
+ <td><b>type</b></td>
+ <td>int</td>
+ <td>
+ Specifies the type of the Instrument Sample.
+ <ul>
+ <li><b>101</b> - Counter Sample - Available for Counter Instruments</li>
+ <li><b>102</b> - Minumum Value Sample - Available for Value Instruments</li>
+ <li><b>103</b> - Maximum Value Sample - Available for Value Instruments</li>
+ <li><b>104</b> - Mean Value Sample - Available for Value Instruments</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td><b>interval</b></td>
+ <td>long</td>
+ <td>
+ The interval of time, in milliseconds, covered by each data point in
+ the Instrument Sample.
+ </td>
+ </tr>
+ <tr>
+ <td><b>size</b></td>
+ <td>int</td>
+ <td>
+ The number of data points maintained by the Instrument Sample. If this
+ value is 600, and the interval is 1000, then the full Instrument Sample
+ represents a period of 10 minutes.
+ </td>
+ </tr>
+ <tr>
+ <td><b>value</b></td>
+ <td>int</td>
+ <td>
+ The current value of the most recent data point in the Instrument
+ Sample.
+ </td>
+ </tr>
+ <tr>
+ <td><b>time</b></td>
+ <td>long</td>
+ <td>
+ The time of the beginning of the interval represented by the most
+ recent data point. If the interval is one 1000, or 1 second, then
+ this will be the current time rounded down to the second. If it
+ is a larger value like 60000, then it will the current time rounded
+ down to the current minute.
+ </td>
+ </tr>
+ <tr>
+ <td><b>first-time</b></td>
+ <td>long</td>
+ <td>
+ The time of the beginning of the interval represented by the first
+ data point returned by the sample. The start time of any data point
+ can be calculated by adding N * the interval to this value.
+ </td>
+ </tr>
+ <tr>
+ <td><b>count</b></td>
+ <td>int</td>
+ <td>
+ The number of data points returned in the snapshot. If the
+ <b>base-time</b> parameter was not specified then this will be
+ equal to the <b>size</b> attribute.
+ </td>
+ </tr>
+ <tr>
+ <td><b>expiration-time</b></td>
+ <td>long</td>
+ <td>
+ The time at which the lease on the Instrument Sample will expire.
+ The lease can be renewed at any time to extend this time. An
+ expiration time of 0 specifies that the Instrument Sample is
+ permanent. It is not possible to create a permanent Sample from
+ a client. They must be configured in the
+ <a href="configuration.html">Instrument configuration file</a>.
+ </td>
+ </tr>
+ <tr>
+ <td><b>state-version</b></td>
+ <td>int</td>
+ <td>
+ Current State-Version of the Instrument Sample. The
+ state version will be incremented whenever there are any
+ changes to the Instrument. It can be compared with a last
+ known state version to decide whether or not it is necessary
+ to to request further details.
+ <p/>
+ Changes to the lease expiration time will cause the state to
+ be incremented. Individual changes to the <b>value</b> or
+ <b>time</b> attributes occur as Instrument values are set and
+ do not affect the state version.
+ <p/>
+ If the application is running long enough, the
+ state version will eventially overflow. To makes
+ sure your application will handle this case use
+ an equality test when comparing state versions.
+ </td>
+ </tr>
+ <tr>
+ <td><b>configured</b></td>
+ <td>boolean</td>
+ <td>
+ Indicates whether or not the Instrument Sample has been declared
+ in the <a href="configuration.html">Instrument configuration file</a>.
+ All configured Samples will be permanent, meaning that their
+ <b>expiration-time</b> will be 0.
+ </td>
+ </tr>
+ </table>
+ </subsection>
+ <subsection name="Child Elements">
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><b>value</b></td>
+ <td>
+ If the <b>compact</b> parameter was set to "false" or omitted
+ then the each individual data point in the snapshot will be
+ represented by a single <b>value</b> child element.
+ <p/>
+ Attributes:
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Data Type</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><b>time</b></td>
+ <td>long</td>
+ <td>
+ The time at the beginning of the data point sample.
+ The difference between the <b>time</b> values of each
+ data point value will be equal to the value of the
+ <b>interval</b> attribute.
+ </td>
+ </tr>
+ <tr>
+ <td><b>value</b></td>
+ <td>int</td>
+ <td>
+ The value of the data point
+ </td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+ <tr>
+ <td><b>values</b></td>
+ <td>
+ If the <b>compact</b> parameter was set to "true", then all of the
+ data point values will be placed into a comma separated list and
+ returned as the value of a single <b>values</b> child element.
+ <p/>
+ The <b>values</b> child element does not have any attributes.
+ </td>
+ </tr>
+ </table>
+ </subsection>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Modified: excalibur/trunk/site/xdocs/instrument/xml-client.xml
==============================================================================
--- excalibur/trunk/site/xdocs/instrument/xml-client.xml (original)
+++ excalibur/trunk/site/xdocs/instrument/xml-client.xml Fri Aug 13 08:18:17 2004
@@ -24,12 +24,14 @@
<body>
<section name="XML Client">
<p>
- The HTTP Connector provides a way to connect the Instrument Manager using
- HTTP requests to obtain XML descriptions of the contents of the file.
- Used correctly, this interface provides a powerful and efficient way to
- work with the Instrument Manager.
+ The HTTP Connector makes it possible for remote applications to connect
+ to an Instrument Manager. The connector is capable of serving both
+ HTML and XML formatted content which makes it possible to monitor
+ and manipulate the Instruments registered with the Instrument Manager.
</p>
<p>
+ Used correctly, this interface provides a powerful and efficient way to
+ work with the Instrument Manager.
The Swing based <a href="java-client.html">Java client</a> makes use of
the XML interface to communicate with the Instrument Manager.
</p>
@@ -112,7 +114,7 @@
<td><a href="xml-client-snapshots.html">Sample Snapshots</a></td>
<td>/snapshots.xml</td>
<td>
- The Sample Snapshots URL work simmilar to the Sample Snapshot URL
+ The Sample Snapshots URL work similar to the Sample Snapshot URL
except that it makes it possible to request snapshots for several
Samples in a single request.
</td>
---------------------------------------------------------------------
To unsubscribe, e-mail: scm-unsubscribe@excalibur.apache.org
For additional commands, e-mail: scm-help@excalibur.apache.org