The Sample Snapshot URL is used to obtain a snapshot of the data points in a particular Instrument Sample. All of the attributes returned by the Instrument Sample URL are included, so there is no need to request that URL first. The snaphot URL includes the individual data points as well as additional attributes describing the data points.
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 Snapshot, the following URL can be used. Note that this assumes that such a sample lease has been granted for the specified sample. (The compact flag is being set because some browsers have a difficult time rendering large XML files quickly.)
| 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. |
| base-time | long | Used to specify a base reference time of the data points included in the snapshots. When requesting a snapshot of an Instrument Sample for the first time, this parameter should be omitted or set to 0. However on subsequent requests, this can be set to the value of the time attribute of the previous request. By doing so, the last data point of the previous request and all newer data points will be returned. Previous data points will not have changed so there is really no reason to have the server resend them. It can add complexity to a client, but the bandwidth with the server can be greatly reduced by carefully avoiding the unnecessary retransmition of data points. | Optional. Defaults to 0, meaning that all data points will be returned. |
| 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". |
| compact | boolean | The data point values can be returned in two different XML formats. The first is a verbose format where each individual data point gets its own value child element with value and time attributes. This can be useful in certain contexts as it allows for easy XSL transformation of the data. The drawback is that the XML can be large when the full set of data points are requested. The second format is specified by setting the compact parameter to "true". All of the data point values are placed into a comma separated list and stored as the value of a values child element. This results in much smaller XML, but requires that the client be able to parse out the individual values as well as calculate the times of each data point. | 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. Depending on the value of the compact parameter, either a single values child element, or set of individual value elements will be included.
| 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. |
| first-time | long | The time of the beginning of the interval represented by the first data point returned by the sample. The start time of any data point can be calculated by adding N * the interval to this value. |
| count | int | The number of data points returned in the snapshot. If the base-time parameter was not specified then this will be equal to the size attribute. |
| 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. |
| Name | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| value |
If the compact parameter was set to "false" or omitted
then the each individual data point in the snapshot will be
represented by a single value child element.
Attributes:
| |||||||||
| values | If the compact parameter was set to "true", then all of the data point values will be placed into a comma separated list and returned as the value of a single values child element. The values child element does not have any attributes. |