2010/12/15 - Apache Excalibur has been retired.

For more information, please explore the Attic.

XML Client - Instrument

The Instrument URL is used to obtain information about a particular Instrument, including any permanent or leased Samples.

Request

Request parameters are set as HTTP GET parameters when sending the request to the server.

For example, to request the instrument-manager.memory Instrument, the following URL can be used:

Parameters

Name Data Type Description Notes
name String The fully qualified name of the Instrument being requested. Required.
packed boolean 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. Optional. Defaults to "false".
recurse boolean By default, the Instrument URL will return information about the Instrument itself along with any direct permanent or leased Samples. By setting the recurse parameter to "true", the generated XML will include the full attribute list of the Samples. This can be quite useful to initialize a client application with the current state of the Instrument tree. Once initialized, it is more efficient to monitor the state-version attributes and only request information which has changed. Optional. Defaults to "false".

Response XML

The XML received in the response will be UTF-8 encoded. The root node will be named instrument and have the following attributes.

Each Sample will be given a sample child element. If the recurse parameter was specified in the request then each of the Samples will have all of the attributes described for the Sample URL.

Attributes

Name Data Type Description
name String Fully qualified name of the Instrument. This name is used to reference the Instrument in other requests.
description String A human readable descripton of the Instrument. It is optionally specified in the Instrument configuration file and can not be modified from a client. If not configured then the description will be equal to the last token in the name.
type int Specifies the type of the Instrument.
  • 1 - Counter Instrument
  • 2 - Value Instrument
state-version int Current State-Version of the Instrument. The state version will be incremented whenever there are any changes to the Instrument or any of its child elements. It can be compared with a last known state version to decide whether or not it is necessary to to request further details.

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.
registered boolean Indicates whether or not the Instrument has been registered with the Instrument Manager after the application was started.

It is possible for the Instrument to exist but not to have been registered if the Instrument was declared in the Instrument configuration file or had any outstanding leases that survived from a previous application invocation.
configured boolean Indicates whether or not the Instrument has been declared in the Instrument configuration file.

Child Elements

Name Description
sample Sample elements will exist for each permanent or leased Instrument Sample that is currently registered with this Instrument. Samples may be added or removed from this list as the application runs so the state-version of the parent instrument should be monitored for changes.

If the recurse parameter was set to "true" in the request, an expanded list of attributes will be available. See the documentation for the Sample URL for further details.

Attributes:
Name Data Type Description
name String Fully qualified name of the Sample. This name is used to reference the Sample in other requests.
state-version int Current State-Version of the Sample. The state version will be incremented whenever there are any changes to the Sample. It can be compared with a last known state version to decide whether or not it is necessary to to request further details.

If the application is running long enough, the state version will eventially overflow. To make sure your application will handle this case use an equality test when comparing state versions.