The Sample URL is used to obtain information about a particular Sample. To obtain the actual data points of the sample, the Sample Snapshot URL must be used.
Request parameters are set as HTTP GET parameters when sending the request to the server.
For example, to request the instrument-manager.memory.maximum_1000_600 Instrument Sample, the following URL can be used. Note that this assumes that such a sample lease has been granted for the specified sample.
| Name | Data Type | Description | Notes |
|---|---|---|---|
| name | String | The fully qualified name of the Instrument Sample being requested. 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). | 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". |
The XML received in the response will be UTF-8 encoded. The root node will be named sample and have the following attributes.
| Name | Data Type | Description |
|---|---|---|
| name | String | 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). |
| description | String | A human readable descripton of the Instrument. If the Instrument Sample was specified in the Instrument configuration file then the description may have been specified there. Otherwise, the description will have been specified as part of the lease request for the sample. |
| type | int |
Specifies the type of the Instrument Sample.
|
| interval | long | The interval of time, in milliseconds, covered by each data point in the Instrument Sample. |
| size | int | 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. |
| value | int | The current value of the most recent data point in the Instrument Sample. |
| time | long | 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. |
| expiration-time | long | 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 Instrument configuration file. |
| state-version | int | 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. Changes to the lease expiration time will cause the state to be incremented. Individual changes to the value or time attributes occur as Instrument values are set and do not affect the state version. 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. |
| configured | boolean | Indicates whether or not the Instrument Sample has been declared in the Instrument configuration file. All configured Samples will be permanent, meaning that their expiration-time will be 0. |