GemFire 5.7

com.gemstone.gemfire.cache.query
Interface QueryService


public interface QueryService

Interface for the query service, which is used for instantiating queries, creating and destroying indexes, creating CQs and operating on CQs. The CQs work on the server regions, the client can use the CQ methods supported in this class to create/operate CQs on the server. The CQ obtains the Server connection from the corresponding local region on the client. The implementation of this interface is obtained from the Cache using Cache.getQueryService().

Since:
4.0

Field Summary
static com.gemstone.gemfire.cache.query.internal.Undefined UNDEFINED
          The undefined constant
 
Method Summary
 void closeCqs()
          Unregister all Continuous Queries.
 Index createIndex(String indexName, IndexType indexType, String indexedExpression, String fromClause)
          Create an index that can be used when executing queries.
 Index createIndex(String indexName, IndexType indexType, String indexedExpression, String fromClause, String imports)
          Create an index that can be used when executing queries.
 void executeCqs()
          Starts execution of all the registered continuous queries for this client.
 void executeCqs(String regionName)
          Starts execution of all the continuous queries registered on the specified region for this client.
 CqQuery getCq(String cqName)
          Retrieves the Continuous Query specified by the name.
 CqQuery[] getCqs()
          Retrieve all registered Continuous Queries.
 CqQuery[] getCqs(String regionName)
          Retrieves all the registered Continuous Queries for a given region.
 CqServiceStatistics getCqStatistics()
          Returns CqServiceStatistics object, which provides helper methods to get CQ service related statistics for this client.
 Index getIndex(Region region, String indexName)
          Get the Index from the specified Region with the specified name.
 Collection getIndexes()
          Get a collection of all the indexes in the Cache.
 Collection getIndexes(Region region)
          Get a collection of all the indexes on the specified Region
 Collection getIndexes(Region region, IndexType indexType)
          Get a collection of all the indexes on the specified Region of the specified index type.
 CqQuery newCq(String queryString, CqAttributes cqAttr)
          Constructs a new continuous query, represented by an instance of CqQuery.
 CqQuery newCq(String queryString, CqAttributes cqAttr, boolean isDurable)
          Constructs a new continuous query, represented by an instance of CqQuery.
 CqQuery newCq(String name, String queryString, CqAttributes cqAttr)
          Constructs a new named continuous query, represented by an instance of CqQuery.
 CqQuery newCq(String name, String queryString, CqAttributes cqAttr, boolean isDurable)
          Constructs a new named continuous query, represented by an instance of CqQuery.
 Query newQuery(String queryString)
          Constructs a new Query object.
 void removeIndex(Index index)
          Remove the specified index.
 void removeIndexes()
          Remove all the indexes from this cache.
 void removeIndexes(Region region)
          Remove all the indexes on the specified Region
 void stopCqs()
          Stops execution of all the continuous queries for this client to become inactive.
 void stopCqs(String regionName)
          Stops execution of all the continuous queries registered on the specified region for this client.
 

Field Detail

UNDEFINED

static final com.gemstone.gemfire.cache.query.internal.Undefined UNDEFINED
The undefined constant

Method Detail

newQuery

Query newQuery(String queryString)
Constructs a new Query object.

Parameters:
queryString - the String that is the query program
Returns:
The new Query object.
Throws:
QueryInvalidException - if the syntax of the queryString is invalid.
See Also:
Query

createIndex

Index createIndex(String indexName,
                  IndexType indexType,
                  String indexedExpression,
                  String fromClause)
                  throws IndexInvalidException,
                         IndexNameConflictException,
                         IndexExistsException,
                         RegionNotFoundException,
                         UnsupportedOperationException
Create an index that can be used when executing queries.

Parameters:
indexName - the name of this index, used for statistics collection and to identify this index for later access
indexType - the type of index
indexedExpression - the expression to index on, a function dependent on region entries individually; must not contain query parameters (e.g. $1).
fromClause - expression that evaluates to the collection(s) that will be queried over, must contain one and only one region path, must not contain query parameters. For primary key indexes, the fromClause must be just one collection which must be a region path only.
Returns:
the newly created Index
Throws:
QueryInvalidException - if the argument query lanaguage strings have invalid syntax
IndexInvalidException - if the arguments do not correctly specify an index
IndexNameConflictException - if an index with this name already exists
IndexExistsException - if an index with these parameters already exists with a different name
RegionNotFoundException - if the region referred to in the fromClause doesn't exist
UnsupportedOperationException - If Index is being created on a region which overflows to disk

createIndex

Index createIndex(String indexName,
                  IndexType indexType,
                  String indexedExpression,
                  String fromClause,
                  String imports)
                  throws IndexInvalidException,
                         IndexNameConflictException,
                         IndexExistsException,
                         RegionNotFoundException,
                         UnsupportedOperationException
Create an index that can be used when executing queries.

Parameters:
indexName - the name of this index, used for statistics collection and to identify this index for later access
indexType - the type of index
indexedExpression - the expression to index on, a function dependent on region entries individually; must not contain query parameters (e.g. $1).
fromClause - expression that evaluates to the collection(s) that will be queried over, must contain one and only one region path, must not contain query parameters. For primary key indexes, the fromClause must be just one collection which must be a region path only.
imports - string containing imports (in the query language syntax, each import statement separated by a semicolon), providing an import context for the indexedExpression and the fromClause.
Returns:
the newly created Index
Throws:
QueryInvalidException - if the argument query language strings have invalid syntax
IndexInvalidException - if the arguments do not correctly specify an index
IndexNameConflictException - if an index with this name already exists
IndexExistsException - if an index with these parameters already exists with a different name
RegionNotFoundException - if the region referred to in the fromClause doesn't exist
UnsupportedOperationException - If Index is being created on a region which overflows to disk

getIndex

Index getIndex(Region region,
               String indexName)
Get the Index from the specified Region with the specified name.

Parameters:
region - the Region for the requested index
Returns:
the index of the region with this name, or null if there isn't one

getIndexes

Collection getIndexes()
Get a collection of all the indexes in the Cache.

Returns:
the collection of all indexes in this Cache

getIndexes

Collection getIndexes(Region region)
Get a collection of all the indexes on the specified Region

Parameters:
region - the region for the requested indexes
Returns:
the collection of indexes on the specified region

getIndexes

Collection getIndexes(Region region,
                      IndexType indexType)
Get a collection of all the indexes on the specified Region of the specified index type.

Parameters:
region - the region for the requested indexes
indexType - the type of indexes to get. Currently must be Indexable.FUNCTIONAL
Returns:
the collection of indexes for the specified region and type

removeIndex

void removeIndex(Index index)
Remove the specified index.

Parameters:
index - the Index to remove

removeIndexes

void removeIndexes()
Remove all the indexes from this cache.


removeIndexes

void removeIndexes(Region region)
Remove all the indexes on the specified Region

Parameters:
region - the Region to remove all indexes from

newCq

CqQuery newCq(String queryString,
              CqAttributes cqAttr)
              throws QueryInvalidException,
                     CqException,
                     CqInvalidException
Constructs a new continuous query, represented by an instance of CqQuery. The CqQuery is not executed until the execute method is invoked on the CqQuery.

Parameters:
queryString - the OQL query
cqAttr - the CqAttributes
Returns:
the newly created CqQuery object
Throws:
IllegalArgumentException - if queryString or cqAttr is null.
IllegalStateException - if this method is called from a cache server.
QueryInvalidException - if there is a syntax error in the query.
CqException - if failed to create CQ.
CqInvalidException - if the query does not meet the CQ constraints. E.g.: Query string should refer to only one region. Joins are not supported. The query must be a SELECT statement. DISTINCT queries are not supported. Projections are not supported. Only one iterator in the FROM clause is supported, and it must be a region path. Bind parameters in the query are not yet supported.
Since:
5.5

newCq

CqQuery newCq(String queryString,
              CqAttributes cqAttr,
              boolean isDurable)
              throws QueryInvalidException,
                     CqException,
                     CqInvalidException
Constructs a new continuous query, represented by an instance of CqQuery. The CqQuery is not executed until the execute method is invoked on the CqQuery.

Parameters:
queryString - the OQL query
cqAttr - the CqAttributes
isDurable - true if the CQ is durable
Returns:
the newly created CqQuery object
Throws:
IllegalArgumentException - if queryString or cqAttr is null.
IllegalStateException - if this method is called from a cache server.
QueryInvalidException - if there is a syntax error in the query.
CqException - if failed to create CQ.
CqInvalidException - if the query does not meet the CQ constraints. E.g.: Query string should refer to only one region. Joins are not supported. The query must be a SELECT statement. DISTINCT queries are not supported. Projections are not supported. Only one iterator in the FROM clause is supported, and it must be a region path. Bind parameters in the query are not yet supported.
Since:
5.5

newCq

CqQuery newCq(String name,
              String queryString,
              CqAttributes cqAttr)
              throws QueryInvalidException,
                     CqExistsException,
                     CqException,
                     CqInvalidException
Constructs a new named continuous query, represented by an instance of CqQuery. The CqQuery is not executed until the execute method is invoked on the CqQuery. The name of the query will be used to identify this query in statistics archival.

Parameters:
name - the String name for this query
queryString - the OQL query
cqAttr - the CqAttributes
Returns:
the newly created CqQuery object
Throws:
CqExistsException - if a CQ by this name already exists on this client
IllegalArgumentException - if queryString or cqAttr is null.
IllegalStateException - if this method is called from a cache server.
QueryInvalidException - if there is a syntax error in the query.
CqException - if failed to create cq.
CqInvalidException - if the query does not meet the CQ constraints. E.g.: Query string should refer to only one region. Joins are not supported. The query must be a SELECT statement. DISTINCT queries are not supported. Projections are not supported. Only one iterator in the FROM clause is supported, and it must be a region path. Bind parameters in the query are not yet supported.
Since:
5.5

newCq

CqQuery newCq(String name,
              String queryString,
              CqAttributes cqAttr,
              boolean isDurable)
              throws QueryInvalidException,
                     CqExistsException,
                     CqException,
                     CqInvalidException
Constructs a new named continuous query, represented by an instance of CqQuery. The CqQuery is not executed until the execute method is invoked on the CqQuery. The name of the query will be used to identify this query in statistics archival.

Parameters:
name - the String name for this query
queryString - the OQL query
cqAttr - the CqAttributes
isDurable - true if the CQ is durable
Returns:
the newly created CqQuery object
Throws:
CqExistsException - if a CQ by this name already exists on this client
IllegalArgumentException - if queryString or cqAttr is null.
IllegalStateException - if this method is called from a cache server.
QueryInvalidException - if there is a syntax error in the query.
CqException - if failed to create cq.
CqInvalidException - if the query does not meet the CQ constraints. E.g.: Query string should refer to only one region. Joins are not supported. The query must be a SELECT statement. DISTINCT queries are not supported. Projections are not supported. Only one iterator in the FROM clause is supported, and it must be a region path. Bind parameters in the query are not yet supported.
Since:
5.5

closeCqs

void closeCqs()
Unregister all Continuous Queries. All artifacts and resources associated with the CQs are released. Any attempt to access closed CqQuery objects will result in the CqClosedException being thrown to the caller.

Since:
5.5

getCqs

CqQuery[] getCqs()
Retrieve all registered Continuous Queries. This is a collection of CqQuery objects.

Returns:
CqQuery[] list of registered CQs, null if there are no CQs.
Since:
5.5

getCqs

CqQuery[] getCqs(String regionName)
                 throws CqException
Retrieves all the registered Continuous Queries for a given region. This is a collection of CqQuery objects.

Returns:
CqQuery[] list of registered CQs on the specified region, null if there are no CQs.
Throws:
CqException - if the region does not exist.
Since:
5.5

getCq

CqQuery getCq(String cqName)
Retrieves the Continuous Query specified by the name.

Parameters:
cqName - - String, name of the CQ
Returns:
CqQuery object, null if no CqQuery object is found.
Since:
5.5

executeCqs

void executeCqs()
                throws CqException
Starts execution of all the registered continuous queries for this client. This is complementary to stopCqs.

Throws:
CqException - if failure to execute CQ.
Since:
5.5
See Also:
stopCqs()

stopCqs

void stopCqs()
             throws CqException
Stops execution of all the continuous queries for this client to become inactive. This is useful when client needs to control the incoming CQ messages during bulk region operations.

Throws:
CqException - if failure to execute CQ.
Since:
5.5
See Also:
executeCqs()

executeCqs

void executeCqs(String regionName)
                throws CqException
Starts execution of all the continuous queries registered on the specified region for this client. This is complementary method to stopCQs().

Throws:
CqException - if failure to stop CQs.
Since:
5.5
See Also:
stopCqs()

stopCqs

void stopCqs(String regionName)
             throws CqException
Stops execution of all the continuous queries registered on the specified region for this client. This is useful when client needs to control the incoming CQ messages during bulk region operations.

Throws:
CqException - if failure to execute CQs.
Since:
5.5
See Also:
executeCqs()

getCqStatistics

CqServiceStatistics getCqStatistics()
Returns CqServiceStatistics object, which provides helper methods to get CQ service related statistics for this client. Specifically the following aggregate information on the client's CQs is collected: Number of CQs created (cumulative) Number of CQs active currently Number of CQs stopped or suspended currently Number of CQs closed (cumulative) Number of CQs active on a specified region currently

Returns:
CqServiceStatistics
Since:
5.5
See Also:
CqServiceStatistics

GemFire 5.7

Copyright © 2002-2008 GemStone Systems, Inc. All Rights Reserved.