The Instrument Manager URL is used to obtain information about the Instrument Manager as a whole, including any root Instrumentables. By providing a recurse parameter, it is possible to request the entire instrument tree for the system in a single request.
Request parameters are set as HTTP GET parameters when sending the request to the server.
For example, to request the entire Instrument tree in a single request, the following URL can be used:
| Name | Data Type | Description | Notes |
|---|---|---|---|
| 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 Manager URL will return information about the Instrument Manager itself along with any top level Instrumentables. By setting the recurse parameter to "true", the generated XML will recurse all the way down through the Instrument tree returning information about each object. 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-manager and have the following attributes.
Each root Instrumentable will be given a instrumentable child element. If the recurse parameter was specified in the request then each of the Instrumentables will have all of the attributes and child elements described for the Instrumentable URL.
| Name | Data Type | Description |
|---|---|---|
| name | String | The name of the Instrument Manager, or the Application of which the Instrument Manager is a part. It is specified in the Instrument configuration file and can not be modified from a client. |
| description | String | A human readable descripton of the Instrument Manager. It is specified in the Instrument configuration file and can not be modified from a client. |
| state-version | int | Current State-Version of the Instrument Manager. The state version will be incremented whenever there are any changes to the Instrument Manager 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 make sure your application will handle this case use an equality test when comparing state versions. Because this is the root of the tree, this would be the first value to eventually overflow. |
| batched-updates | boolean | The batched updates attributes is used to indicate that the HTTP Connector supports the following batch update URLs: This attribute will be set to "true" in all new versions of the HTTP Connector and can be ignored unless your client application will be making connections to versions of the HTTP Connector prior to the version 1.2 release. If the attribute does not exist, then it should be assumed to have a value of "false". |
| read-only | boolean | The read-only attribute is used to indicate that the HTTP Connector is operating in read-only mode. When operating in this mode, URLs which can be used to modify the state of the Instrument tree will not be available. These include the following: The read-only status of the HTTP Connector is specified in the Instrument configuration file. |
| Name | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| instrumentable |
Instrumentable elements will exist for each root Instrumentable
that is currently registered with the Instrument Manager. This
list may increase as the application runs so the state-version
of the parent instrument-manager should be monitored for
changes.
If the recurse parameter was set to "true" in the
request, an expanded list of attributes and child
elements will be available. See the documentation for the
Instrumentable
URL for further details.
Attributes:
|