For example, you may have a dashboard showing thousands of hosts and their metrics in a table. Populating these metric values can results in numerous back-end round-trips, which affects the table performance when any of the following actions are performed:
The ObservationQuery interface includes methods to set the time range, retrieve observations, and the retrieval type. When used from WCF, the start and end times of the time range are set based on the SpecificTimeRange object provided by WCF. If the metrics are used in chart components, a SpecificTimeRange object for charts can be obtained by calling the method functionHelper.getSpecificTimeRangeForCharting().
NOTE: Any metrics used by the dashboard implementing the Batch API mode need to be added to the set of observations that are to be retrieved. There are no restrictions on which observation keys can be added to the set: they can be obtained from different topology objects, and can be of different types (such as Metrics, StringObservations, and so on). The retrieval type defines the type of data access. If the view is displaying current and period values, then the retrieval type should be AGGREGATE_AND_LAST (the default). The other options are AGGREGATE, if only the period value is required, LAST_N if only the current value is required, or RAW if raw metric values are required.
The following Groovy script has an example of how you can call the batch API. The results of the batch data access call are not important for the observation pre-loading to work, and can be discarded by the Groovy script. WCF is not aware of batch queries and the dashboards will continue to access the observations in the usual way, but that access will not require any database round trips because the observations will be in the Persistence Cache after the batch loading script completes.
Next, in WCF, to enter the Batch API mode, invoke that function by using the Prepare For Inspection property.
The Tree Table and Row-Oriented Table components include this property. The calling component does not take into consideration the result of this function, so as long as you call the function this way, it starts the Batch API mode.
For example, a dashboard can list thousands of hosts, including their names and different metrics (for example, Metric A, B and C). This data displays in columns of a Row-Oriented Table component. If Metric B is more important than metrics A and C, so the user should be able to sort this column or search for a specific value. The layout cannot display all of the rows, so for example, it only shows 20 rows. If the end-user attempts to sort the column containing Metric B, that sort will not be very fast because it requires a round-trip to server to get that value for each host.
At run-time when the table is rendered, if the user sort the column that contains Metric B, this function is invoked and the Batching API mode starts. Row objects with all instances of Metric B (one for each host) are cached, which eliminates the need for subsequent round trips to the server to retrieve individual Metric B values. If you want to apply this behavior to Metric A and Metric C, invoke the function for each column.