geode-docs/developing/continuous_querying/continuous_querying_whats_next.html.md.erb - geode - Git at Google

 ---
 title:  Managing Continuous Querying
 ---

 <!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 -->

 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:

 ``` pre
 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.

 ## <a id="continuous_querying_whats_next__section_35F929682CD24478AF0B2249C5065A27" class="no-quick-link"></a>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.                                                                                                                                                                                                                                                                                                                   |

 ## <a id="continuous_querying_whats_next__section_4E308A70BCE44031BB1F37B95B4D06E6" class="no-quick-link"></a>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` |

 ## <a id="continuous_querying_whats_next__section_B274DA982AE6441288323A1D11B58786" class="no-quick-link"></a>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](../../tools_modules/gfsh/command-pages/close.html#topic_27555B1929D7487D9158096BC065D372).
 -   List all durable CQs for a given durable client ID. See [list](../../tools_modules/gfsh/command-pages/list.html).
 -   Show the subscription event queue size for a given durable client ID. See [show subscription-queue-size](../../tools_modules/gfsh/command-pages/show.html#topic_395C96B500AD430CBF3D3C8886A4CD2E).

 ## <a id="continuous_querying_whats_next__section_345E9C144EB544FBA61FC9C83BF1C1ED" class="no-quick-link"></a>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:

 ``` pre
 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.
	---
	title: Managing Continuous Querying
	---

	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->

	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:

	``` pre
	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.

	## <a id="continuous_querying_whats_next__section_35F929682CD24478AF0B2249C5065A27" class="no-quick-link"></a>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. \|

	## <a id="continuous_querying_whats_next__section_4E308A70BCE44031BB1F37B95B4D06E6" class="no-quick-link"></a>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` \|

	## <a id="continuous_querying_whats_next__section_B274DA982AE6441288323A1D11B58786" class="no-quick-link"></a>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](../../tools_modules/gfsh/command-pages/close.html#topic_27555B1929D7487D9158096BC065D372).
	- List all durable CQs for a given durable client ID. See [list](../../tools_modules/gfsh/command-pages/list.html).
	- Show the subscription event queue size for a given durable client ID. See [show subscription-queue-size](../../tools_modules/gfsh/command-pages/show.html#topic_395C96B500AD430CBF3D3C8886A4CD2E).

	## <a id="continuous_querying_whats_next__section_345E9C144EB544FBA61FC9C83BF1C1ED" class="no-quick-link"></a>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:

	``` pre
	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.