com.ibm.websphere.objectgrid.continuousquery
Interface ContinuousQueryManager

public interface ContinuousQueryManager

The management interface used to define new continuous queries, retrieve an existing query, or destroy a query. An instance can be retrieved via ContinuousQueryManagerFactory.getManager(com.ibm.websphere.objectgrid.ObjectGrid)

Since:

8.6

Method Summary

<KeyType,ValueType> ContinuousQueryTopic<KeyType,ValueType>	defineContinuousQuery(String mapName, ContinuousQueryFilter filter, boolean keysOnly, boolean returnInitialResultSet, boolean notifyOnUpdated, Collection<ContinuousQueryListener<KeyType,ValueType>> continuousQueryListeners, boolean noCache, boolean useRawFormat, Integer... partitionSubset) Define a new continuous query.
<KeyType,ValueType> ContinuousQueryTopic<KeyType,ValueType>	defineContinuousQuery(String mapName, ContinuousQueryFilter filter, boolean keysOnly, boolean returnInitialResultSet, boolean notifyOnUpdated, Integer... partitionSubset) Define a new continuous query.
List<ContinuousQueryTopic>	getDefinedContinuousQueries() Returns a list view of the currently defined Continuous Query Topics.
boolean	removeContinuousQuery(ContinuousQueryTopic topic, Integer... partitionSubset) Remove a defined continuous query.

Method Detail

defineContinuousQuery

<KeyType,ValueType> ContinuousQueryTopic<KeyType,ValueType> defineContinuousQuery(String mapName,
                                                                                  ContinuousQueryFilter filter,
                                                                                  boolean keysOnly,
                                                                                  boolean returnInitialResultSet,
                                                                                  boolean notifyOnUpdated,
                                                                                  Collection<ContinuousQueryListener<KeyType,ValueType>> continuousQueryListeners,
                                                                                  boolean noCache,
                                                                                  boolean useRawFormat,
                                                                                  Integer... partitionSubset)
                                                              throws ContinuousQueryIncompatibleDuplicateException,
                                                                     UndefinedMapException

Define a new continuous query. This query will run in the grid container processes. When cache entries that match the filter criteria are inserted or deleted, the client's ContinuousQueryCache will be updated and any ContinuousQueryListener implementations will be invoked. This will also occur if a cache entry is updated such that it now matches, or no longer matches, the filter criteria. Optionally, notifications can be sent for update operations to cache entries that previously matched the criteria, and still match the criteria after the update.

Parameters:

mapName - - the name of the map the continuous query will be defined on.

filter - - the filter that the will determine the contents of the continuous query. Custom filter logic can be implemented by extending AbstractCQFilter.

keysOnly - - true if the query should only return the keys of items that satisfy the query; false to also send the values as well as the keys. If false, the ContinuousQueryCache and ContinuousQueryNotificationEvent objects will include the value associated with cache entries that match the query.

returnInitialResultSet - - true to run the filter on all existing matches in the map at the time of the query definition and return the items to the cache. If false, the client will only be notified of matches which occur after the query is defined. Returning the initial result set will have a high computational requirement for large maps.

notifyOnUpdated - - true causes this topic to get called every time an existing item that satisfies this query gets updated and continues to satisfy this query. This will drive ContinuousQueryListener call backs as well as updated values in the query cache if keysOnly is false.

continuousQueryListeners - - used to register listeners before the query is defined. These listeners will be guaranteed to be invoked for any entries in the initial result set, as well as changes to the result set which might occur before ContinuousQueryTopic.addListener(ContinuousQueryListener) can be invoked. Can be null.

noCache - - true to indicate that no caching of keys or values should occur on the client. Continuous Query listeners will still be notified.

useRawFormat - - when true, keys and values returned from the ContinuousQueryCache and ContinuousQueryListener will be in SerializedEntry format when a DataSerializer is defined on the map. - when false, or when no DataSerializer is defined, keys and values will be returned as Objects.

partitionSubset - - An optional parameter used to indicate that this continuous query should only be defined on the specified subset of partitions. Passing no arguments indicates this continuous query should be defined on all existing and future partitions containing this map. An IllegalArgumentException may be thrown if an invalid partition ID is passed.

Returns:

The ContinuousQueryTopic for this continuous query. If the call to this method would result in an topic which is identical to an existing topic being created, the existing instance is returned.

Throws:

ContinuousQueryIncompatibleDuplicateException

UndefinedMapException

IllegalArgumentException

defineContinuousQuery

<KeyType,ValueType> ContinuousQueryTopic<KeyType,ValueType> defineContinuousQuery(String mapName,
                                                                                  ContinuousQueryFilter filter,
                                                                                  boolean keysOnly,
                                                                                  boolean returnInitialResultSet,
                                                                                  boolean notifyOnUpdated,
                                                                                  Integer... partitionSubset)
                                                              throws ContinuousQueryIncompatibleDuplicateException,
                                                                     UndefinedMapException

Define a new continuous query. This query will run in the grid container processes. When cache entries that match the filter criteria are inserted or deleted, the client's ContinuousQueryCache will be updated and any ContinuousQueryListener implementations will be invoked. This will also occur if a cache entry is updated such that it now matches, or no longer matches, the filter criteria. Optionally, notifications can be sent for update operations to cache entries that previously matched the criteria, and still match the criteria after the update.

Parameters:

mapName - - the name of the map the continuous query will be defined on.

filter - - the filter that the will determine the contents of the continuous query. Custom filter logic can be implemented by extending AbstractCQFilter.

keysOnly - - true if the query should only return the keys of items that satisfy the query; false to also send the values as well as the keys. If false, the ContinuousQueryCache and ContinuousQueryNotificationEvent objects will include the value associated with cache entries that match the query.

returnInitialResultSet - - true to run the filter on all existing matches in the map at the time of the query definition and return the items to the cache. If false, the client will only be notified of matches which occur after the query is defined. Returning the initial result set will have a high computational requirement for large maps.

notifyOnUpdated - - true causes this topic to get called every time an existing item that satisfies this query gets updated and continues to satisfy this query. This will drive ContinuousQueryListener call backs as well as updated values in the query cache if keysOnly is false.

partitionSubset - - An optional parameter used to indicate that this continuous query should only be defined on the specified subset of partitions. Passing no arguments indicates this continuous query should be defined on all existing and future partitions containing this map. An IllegalArgumentException may be thrown if an invalid partition ID is passed.

Returns:

The ContinuousQueryTopic for this continuous query. If the call to this method would result in an topic which is identical to an existing topic being created, the existing instance is returned.

Throws:

ContinuousQueryIncompatibleDuplicateException

UndefinedMapException

IllegalArgumentException

removeContinuousQuery

boolean removeContinuousQuery(ContinuousQueryTopic topic,
                              Integer... partitionSubset)

Remove a defined continuous query. Does the opposite of #defineContinuousQuery(String, ContinuousQueryFilter, boolean, boolean, boolean, int...). If the number of calls to this method for a given topic equals the number of calls to defineContinuousQuery that return the specified topic, the topic will cease receiving updates from the server, all listeners of this topic will be removed and the reference to this topic will be invalid.

Parameters:

topic - - the topic to remove

partitionSubset - - If the continuous query was defined on a subset of partitions, that same set of partitions must be passed for the remove to succeed. If no subset was specified when the continuous query was defined, then no subset should be specified for the remove to succeed. An IllegalArgumentException may be thrown if an invalid partition ID is passed.

Returns:

true if the topic was removed, false otherwise

Throws:

IllegalArgumentException

getDefinedContinuousQueries

List<ContinuousQueryTopic> getDefinedContinuousQueries()

Returns a list view of the currently defined Continuous Query Topics.

Returns:

a list of Continuous Query Topics