Managing Continuous Querying

This topic discusses CQ management options, CQ states, and retrieving initial result sets.

Using CQs from a RegionService Instance

If you are running durable client queues from the RegionService instance, stop and start the offline event storage for the client as a whole. The server manages one queue for the entire client process, so you need to request the stop and start of durable CQ event messaging for the cache as a whole, through the ClientCache instance. If you closed the RegionService instances, event processing would stop, but the server would continue to send events, and those events would be lost.

Stop with:

clientCache.close(true);

Start up again in this order:

1. Create ClientCache instance.
2. Create all RegionService instances. Initialize CQ listeners.
3. Call ClientCache instance readyForEvents method.

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?	When does the CQ reach this state?	Notes
STOPPED	The CQ is in place and ready to run, but is not running.	When CQ is 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 CQ is 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 CQ is 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
Get all durable CQs registered on the server	N/A	QueryService.getAllDurableCqsFromServer

Managing CQs and Durable Clients Using gfsh

Using the gfsh command-line utility, you can perform the following actions:

• Close durable clients and durable client CQs. See close.
• List all durable CQs for a given durable client ID. See list.
• Show the subscription event queue size for a given durable client ID. See show subscription-queue-size.

Retrieving an 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 that 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.

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. Design your application to synchronize between the region operation and CQ registration to avoid duplicate events from being delivered.