Registering Interest for Entries
For native client regions, you can programmatically register interest in entry keys stored on a cache server region. A client region receives update notifications from the cache server for the keys of interest.
You can register interest for specific entry keys or for all keys. Regular expressions can be used to register interest for keys whose strings match the expression. You can also unregister interest for specific keys, groups of keys based on regular expressions, or for all keys.
Note: Interest registration and unregistration are symmetrical operations. Consequently, you cannot register interest in all keys and then unregister interest in a specific set of keys. Also, if you first register interest in specific keys with
registerKeys, then call
registerAllKeys, you must call
unregisterAllKeys before specifying interest in specific keys again.
You register client interest through the C++ or NET API. The C++ API provides the
registerRegex methods, with corresponding unregistration accomplished using the
unregisterRegex methods. The .NET API provides the
RegisterRegex methods, with corresponding unregistration accomplished using the
registerAllKeys methods have the option to populate the cache with the registration results from the server. The
registerAllKeys methods can also optionally return the current list of keys registered on the server.
In addition to the programmatic function calls, to register interest for a server region and receive updated entries you need to configure the region with the
CACHING_PROXY RegionShortcut setting. The region’s pool should have
subscription-enabled=true set either in the client XML or programmatically via a
CacheFactory::setSubscriptionEnabled(true) API call. Otherwise, when you register interest, you will get an
<region name = "listenerWriterLoader" refid="CACHING_PROXY"> ...
Both native clients and Java clients that have subscriptions enabled track and drop (ignore) any duplicate notifications received. To reduce resource usage, a client expires tracked sources for which new notifications have not been received for a configurable amount of time.
CacheListeners of cacheless clients in all cases for keys that have been registered on the server. Similarly, invalidates received from the server invoke
CacheListeners of cacheless clients.
If you register to receive notifications, listener callbacks are invoked irrespective of whether the key is in the client cache when a
invalidate event is received.
You register and unregister interest for specific keys through the
unregisterKeys functions. You register interest in a key or set of keys by specifying the key name using the programmatic syntax shown in the following example:
keys0.push_back(keyPtr1); keys1.push_back(keyPtr3); regPtr0->registerKeys(keys0); regPtr1->registerKeys(keys1);
The programmatic code snippet in the next example shows how to unregister interest in specific keys:
If the client registers interest in all keys, the server provides notifications for all updates to all keys in the region. The next example shows how to register interest in all keys:
The following example shows a code sample for unregistering interest in all keys.
registerRegex function registers interest in a regular expression pattern. The server automatically sends the client changes for entries whose keys match the specified pattern.
Keys must be strings in order to register interest using regular expressions.
The following example shows interest registration for all keys whose first four characters are
Key-, followed by any string of characters. The characters
.* represent a wildcard that matches any string.
To unregister interest using regular expressions, you use the
unregisterRegex function. The next example shows how to unregister interest in all keys whose first four characters are
Key-, followed by any string (represented by the
In this register interest scenario, a cache listener is used with a cacheless region that has
subscription-enabled set to
true. The client region is configured with caching disabled; client notification is enabled; and a cache listener is established. The client has not registered interest in any keys.
When a value changes in another client, it sends the event to the server. The server will not send the event to the cacheless client, even though
client-notification is set to
To activate the cache listener so the cacheless region receives updates, the client should explicitly register interest in some or all keys by using one of the API calls for registering interest. This way, the client receives all events for the keys to which it has registered interest. This applies to Java-based clients as well as native clients.