Hazelcast Continuous Query Using C++ Client

I am happy to announce that we now added the Continuous Query capability to C++ client with the release of our Hazelcast C++ client version 3.6.2.

It is now possible to register an entry listener for a Map that will be triggered only when the specific Map entries that you choose are affected. This allows you to do more optimal queries.

Let’s start with an example.

1. intMap = client->getMap<int, int>("IntMap");
2. 
3. MyListener listener;
4. 
5. // 5 <=key <= 8
6. std::string listenerId = intMap.addEntryListener(listener, query::BetweenPredicate<int>(
7. query::QueryConstants::getKeyAttributeName(), 5, 8), true);
8. 
9. intMap.put(1, 1);
10. intMap.put(8, 17);
11. intMap.put(5, 12, 1000); // evict after 1 second
12. intMap.remove(1);
13. 
14. util::sleep(2);
15. 
16. intMap.get(5); // trigger eviction

In this example, we register an EntryListener to only retrieve Map events for entries with keys between 5 and 8 (inclusive). So, if an entry within this key range is added/updated/removed/evicted, you will be notified through the registered listener.

Line 6: Creates a built-in BetweenPredicate (see http://docs.hazelcast.org/docs/latest-dev/manual/html-single/index.html#query-api and https://github.com/hazelcast/hazelcast-cpp-client/blob/master/examples/distributed-map/query/queryExample.cpp for all built-in predicates) and an EntryListener is added to listen to entry events with keys 5 through 8.

“query::QueryConstants::getKeyAttributeName()” is used to tell that the query is being performed on the key of the entry. Similarly, you can use “query::QueryConstants::getValueAttributeName()” if you want to query on the value of the entry.

Line 9: Puts an entry for key = 1. This does not match your listener predicate, hence no event is received for this line. Line 10: Puts an entry for key = 8. This key matches our interested key range, so you receive an event for the entry addition, and the entryAdded method of our listener will be called. Line 11: Adds an entry for key=5 with an expiry timeout of 1,000 milliseconds. This operation triggers an entryAdded event for our listener since the key is in our interested range. Line 12: Removal of entry with key=1 does not trigger any event and thus you will not receive any callback to your listener. Line 14: Sets sleep for enough time that the entry with key=5 will be evicted. Line 16: Triggers an eviction for entry with key=5. This line will cause an entryEvicted event to be received by your listener.

As shown by the above example, by using an EntryListener with predicates you can minimize the events to only ones in which you are interested. This is also known as the “Continuous Query” feature. You will keep receiving all events that match your query (which is the predicate that you provide on registration of your listener) while entries are being modified in the map in real time. The filtering is performed at the server side, so this method is a lot faster than receiving all the events and filtering at the client side.

Please examine all different kinds of built in Predicates that we provide in the code examples. You can just grab a predicate or combine multiples of them using the AndPredicate or OrPredicate, which provides you the capability to write complex queries. You can not only query on keys or values, as explained above, but you can also use properties of an object for querying. The object can be the key as well as the value. Please see the query sections of the Hazelcast reference manual (http://docs.hazelcast.org/docs/latest-dev/manual/html-single/index.html) for details on queries.

Please be careful with the runtime behavior of your listener implementations to ensure that the listener callback methods return very quickly. If you need to perform long running tasks when an entry is changed, please off-load those operations to another thread.

In addition to this rich set of built-in predicates, you can also write your own custom queries simply by implementing your own Predicate (you also have to implement the Java server-side Predicate as well to make this work).

I hope you’ll enjoy the new capabilities for our C++ client.