The Instrumentable URL is used to obtain information about a particular Instrumentable, including any child Instrumentables or Instruments. By providing a recurse parameter, it is possible to request a full instrument tree in a single request.
Request parameters are set as HTTP GET parameters when sending the request to the server.
For example, to request the instrument-manager Instrumentable, the following URL can be used:
| Name | Data Type | Description | Notes |
|---|---|---|---|
| name | String | The fully qualified name of the Instrumentable 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 Instrumentable URL will return information about the Instrumentable itself along with any direct child Instrumentables and Instruments. 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 instrumentable and have the following attributes.
Each child Instrumentable will be given a instrumentable child element and each Instrument will be given a instrument element. If the recurse parameter was specified in the request then each of the Instrumentables and Instruments will have all of the attributes and child elements described for the Instrumentable and Instrument URLs.
| Name | Data Type | Description |
|---|---|---|
| name | String | Fully qualified name of the Instrumentable. This name is used to reference the Instrumentable in other requests. |
| description | String | A human readable descripton of the Instrumentable. 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. |
| state-version | int | Current State-Version of the Instrumentable. The state version will be incremented whenever there are any changes to the Instrumentable 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 Instrumentable has been registered with the Instrument Manager after the application was started. It is possible for the Instrumentable to exist but not to have been registered if the Instrumentable 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 Instrumentable has been declared in the Instrument configuration file. |
| Name | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| instrumentable |
Instrumentable elements will exist for each direct child
Instrumentable that is currently registered with this
Instrumentable. This list may increase as the application
runs so the state-version of the parent instrumentable
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:
|
|||||||||
| instrument |
Instrument elements will exist for each Instrument that is
currently registered with this Instrumentable. This list may
increase as the application runs so the state-version
of the parent instrumentable 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
Instrument
URL for further details.
Attributes:
|