CQ API and Main Features

This chapter documents the primary native client API for CQ management.

The Pivotal GemFire native client API allows your clients to create and manage CQs. (The server side does not have an API.) Continuous querying provides native client query syntax, events-based management, integration with client/server architecture, active query execution, and interest criteria based on data values. For complete information on the classes and interfaces described here, see the documentation for the C++ API or the .NET API.

Apache.Geode.Client.Cache

Only C# versions of CQ API interfaces, classes, and methods are shown here (example: CqQuery.execute). The code examples demonstrate both C++ and C# versions.

  • QueryService interface. Provides methods that enable you to:

    • Create a new CQ and specify whether it is durable (available for durable clients)
    • Execute a CQ with or without an initial result
    • List all the CQs registered by the client
    • Close and stop CQs
    • Get a handle on CqStatistics for the client

    You run QueryService CQ methods against the server cache. The QueryService can be obtained from the cache or from a pool.

  • CqQueryinterface. Provides methods for managing a continuous query after it is created through the QueryService. This interface is used typically to begin and end CQ execution and to retrieve other CQ-related objects such as CQ attributes, CQ statistics, and CQ state.

  • CqListener application plug-in interface. Handles continuous query events after they occur. You program this interface.

  • CqEventinterface. Provides all information sent from the server about the CQ event, which is passed to the CQ’s CqListener methods.

  • CqState interface. Provides information on the state of a CqQuery, through the getState method of the CqQuery instance.

  • CqAttributes, CqAttributesFactory, CqAttributesMutator interfaces. Allow you to manage CQ attributes. The attributes consist of CqListenerplug-in specifications.

  • CqStatistics, CqServiceStatistics interfaces. Allow you to access statistics information for a single CQ and for the query service’s management of CQs as a whole. For details on statistics, see Statistics API.

Main Features of Continuous Querying

Continuous querying in the native client has the following features:

  • Standard GemFire native client query syntax and semantics. CQ queries are expressed in the same language used for other native client queries. See Remote Querying.
  • Standard GemFire events-based management of CQ events. The event handling used to process CQ events is based on the standard GemFire event handling framework. The CQListener interface is similar to Application Plug-Ins and Application Callbacks.
  • Complete integration with the client/server architecture. CQ functionality uses existing server-to-client messaging mechanisms to send events. All tuning of your server-to-client messaging also tunes the messaging of your CQ events. If your system is configured for high availability then your CQs are highly available, with seamless failover provided in case of server failure (see High Availability for Client-to-Server Communication). If your clients are durable, you can also define any of your CQs as durable (see Durable Client Messaging).
  • Interest criteria based on data values. CQ queries are run against the region’s entry values. Compare this to register interest by reviewing Registering Interest for Entries.
  • Active query execution. Once initialized, the queries only operate on new events instead of on the entire region data set. Events that change the query result are sent to the client immediately.