Implementing Durable Client/Server Messaging

Implementing Durable Client/Server Messaging

Use durable messaging for subscriptions that you need maintained for your clients even when your clients are down or disconnected. You can configure any of your event subscriptions as durable. Events for durable queries and subscriptions are saved in queue when the client is disconnected and played back when the client reconnects. Other queries and subscriptions are removed from the queue.

Use durable messaging for client/server installations that use event subscriptions.

These are the high-level tasks described in this topic:

  1. Configure your client as durable
  2. Decide which subscriptions should be durable and configure accordingly
  3. Program your client to manage durable messaging for disconnect, reconnect, and event handling

Configure the Client as Durable

Use one of the following methods:
  • file:
  • Java:
    Properties props = new Properties(); 
    props.setProperty("durable-client-id", "31"); 
    props.setProperty("durable-client-timeout", "" + 200); 
    CacheFactory cf = new CacheFactory(props);

The durable-client-id indicates that the client is durable and gives the server an identifier to correlate the client to its durable messages. For a non-durable client, this id is an empty string. The ID can be any number that is unique among the clients attached to servers in the same distributed system.

The durable-client-timeout tells the server how long to wait for client reconnect. When this timeout is reached, the server stops storing to the client's message queue and discards any stored messages. The default is 300 seconds. This is a tuning parameter. If you change it, take into account the normal activity of your application, the average size of your messages, and the level of risk you can handle, both in lost messages and in the servers' capacity to store enqueued messages. Assuming that no messages are being removed from the queue, how long can the server run before the queue reaches the maximum capacity? How many durable clients can the server handle? To assist with tuning, use the GemFire message queue statistics for durable clients through the disconnect and reconnect cycles.

Program the Client to Manage Durable Messaging

Program your durable client to be durable-messaging aware when it disconnects, reconnects, and handles events from the server.
  1. Disconnect with a request to keep your queues active by using Pool.close or ClientCache.close with the boolean keepalive parameter.
  2. Program your durable client's reconnection to:
    1. If desired, detect whether the previously registered subscription queue is available upon durable client reconnection and the count of pending events in the queue. Based on the results, you can then decide whether to receive the remaining events or close the cache if the number is too large.
      For example, for a client with only the default pool created:
      int pendingEvents = cache.getDefaultPool().getPendingEventCount();
      if (pendingEvents == -2) { // client connected for the first time  … // continue
      else if (pendingEvents == -1) { // client reconnected but after the timeout period  
      … // handle possible data loss
      else { // pendingEvents >= 0  
      … // decide to invoke readyForEvents() or cache.close(false)/pool.destroy()
      For a client with multiple pools:
      int pendingEvents = 0;
      int pendingEvents1 = PoolManager.find(“pool1”).getPendingEventCount();
      pendingEvents += (pendingEvents1 > 0) ? pendingEvents1 : 0;
      int pendingEvents2 = PoolManager.find(“pool2”).getPendingEventCount();
      pendingEvents += (pendingEvents2 > 0) ? pendingEvents2 : 0;
      // process individual pool counts separately.
      The getPendingEventCount API can return the following possible values:
      • A value representing a count of events pending at the server. Note that this count is an approximate value based on the time the durable client pool connected or reconnected to the server. Any number of invocations will return the same value.
      • A zero value if there are no events pending at server for this client pool
      • A negative value indicates that no queue is available at the server for the client pool.
        • -1 indicates that the client pool has reconnected to the server after its durable-client-timeout period has elapsed. The pool's subscription queue has been removed possibly causing data loss.
        • A value of -2 indicates that this client pool has connected to server for the first time.
    2. Connect, initialize the client cache, regions, and any cache listeners.
    3. Run all interest registration calls.
      Note: Registering interest with InterestResultPolicy.KEYS_VALUES initializes the client cache with the current values of specified keys. If concurrency checking is enabled for the region, any earlier (older) region events that are replayed to the client are ignored and are not sent to configured listeners. If your client must process all replayed events for a region, register with InterestResultPolicy.KEYS or InterestResultPolicy.NONE when reconnecting. Or, disable concurrency checking for the region in the client cache. See Consistency for Region Updates.
    4. Call ClientCache.readyForEvents so the server will replay stored events. If the ready message is sent earlier, the client may lose events.
    ClientCache clientCache = ClientCacheFactory.create(); 
    // Here, create regions, listeners that are not defined in the cache.xml . . .
    // Here, run all register interest calls before doing anything else
  3. When you program your durable client CacheListener:
    1. Implement the callback methods to behave properly when stored events are replayed. The durable client’s CacheListener must be able to handle having events played after the fact. Generally listeners receive events very close to when they happen, but the durable client may receive events that occurred minutes before and are not relevant to current cache state.
    2. Consider whether to use the CacheListener callback method, afterRegionLive, which is provided specifically for the end of durable event replay. You can use it to perform application-specific operations before resuming normal event handling. If you do not wish to use this callback, and your listener is an instance of CacheListener (instead of a CacheListenerAdapter) implement afterRegionLive as an empty method.