Managing Continuous Querying

This topic provides additional information about managing CQs.

Initial Result Set of a CQ

You can optionally retrieve an initial result set when you execute your CQ. To do this, execute the CQ with the executeWithInitialResults method. The initial SelectResults returned is the same as you would get if you ran the query ad hoc, by calling QueryService.newQuery.execute on the server cache, but with the key included. This example retrieves keys and values from an initial result set:

SelectResults cqResults = cq.executeWithInitialResults();
for (Object o : cqResults.asList()) {
  Struct s = (Struct)o; // Struct with Key, value pair
  Portfolio p = (Portfolio)s.get("value"); // get value from the Struct
  String id = (String)s.get("key"); // get key from the Struct
}

If you are managing a data set from the CQ results, you can initialize the set by iterating over the result set and then updating it from your listeners as events arrive. For example, you might populate a new screen with initial results and then update the screen from a CQ listener.

You should note that if a CQ is executed using the ExecuteWithInitialResults method, the returned result may already include the changes with respect to the event. This can arise when updates are happening on the region while CQ registration is in progress. The CQ does not block any region operation as it could affect the performance of the region operation. You should design your application to synchronize between the region operation and CQ registration to avoid duplicate events from being delivered.

States of a CQ

A CQ has three possible states, which are maintained on the server. You can check them from the client through CqQuery.getState.

Query State What does this mean? How does the CQ get here? Notes
STOPPED The CQ is in place and ready to run, but is not running. When it's first created and after being stopped from a running state. A stopped CQ uses system resources. Stopping a CQ only stops the CQ event messaging from server to client. All server-side CQ processing continues, but new CQ events are not placed into the server's client queue. Stopping a CQ does not change anything on the client side (but, of course, the client stops receiving events for the CQ that is stopped).
RUNNING The CQ is running against server region events and the client listeners are waiting for CQ events. When it's executed from a stopped state. This is the only state in which events are sent to the client.
CLOSED The CQ is not available for any further activities. You cannot rerun a closed CQ. When it's closed by the client and when cache or connection conditions make it impossible to maintain or run. The closed CQ does not use system resources.

CQ Management Options

You manage your CQs from the client side. All calls are executed only for the calling client's CQs.

Task For a single CQ use ... For groups of CQs use ...
Create a CQ QueryService.newCq N/A
Execute a CQ CqQuery.execute and CqQuery.executeWithInitialResults QueryService.executeCqs
Stop a CQ CqQuery.stop QueryService.stopCqs
Close a CQ CqQuery.close QueryService.closeCqs
Access a CQ CqEvent.getCq and QueryService.getCq QueryService.getCq
Modify CQ Listeners CqQuery.getCqAttributesMutator N/A
Access CQ Runtime Statistics CqQuery.getStatistics QueryService.getCqStatistics