The Instrument URL is used to obtain information about a particular Instrument, including any permanent or leased Samples.
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:
| 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". |
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.
| 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.
|
| 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. |
| 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:
|