Understanding BroadcasterCache - Atmosphere/atmosphere GitHub Wiki

The BroadcasterCache is an API that allows the caching of Broadcaster messages. Caching is required, if you don't want to lose broadcasted messages. You can lose messages under the following scenario:

1. When a connection gets closed (by a proxy, a timeout, the browser, the server), the Broadcaster.broadcast operation might still be in the process of delivering a message to that connection. Since that connection is closed, the message will be lost.
2. Similar to 1, when a Browser reconnects, during the reconnection process messages can always be broadcasted and may not be delivered to that connection properly.

By default, the Atmosphere Framework install UUIDBroadcasterCache, but ships with many implementations:

• UUIDBroadcasterCache This implementation use the unique UUID generated by the Atmosphere Framework and shared with the clients using the X-Atmosphere-Tracking-id. This is the recommended BroadcasterCache implementation.
• SessionBroadcasterCache : Similar to HeaderBroadcasterCache, but this time the timestamp is cached inside the HttpSession using the org.atmosphere.cpr.BroadcasterCache attribute to store the timestamp of the last message that was sent to the browser.

You can also easily write your own BroadcasterCache. As an example, the Atmosphere's sample for the jquery-socket library has a pretty simple custom implementation.

To install a BroadcasterCache, just add, in web.xml or application.xml:

        <init-param>
            <param-name>org.atmosphere.cpr.broadcasterCacheClass</param-name>
            <param-value>org....</param-value>
        </init-param>

You can also annotate your implementation by using the @BroadcasterCacheService as:

  @BroadcasterCacheService
  public class MyBroadcasterCache implements BroadcasterCache {...}

You can also configure them at runtime, per Broadcaster, by doing

   Broadcaster.getBroadcasterConfig().setBroadcasterCache(new MyBroadcasterCache());

When used with BroadcastFilter, you can control which of the original or the filtered message gets cached by using

      <init-param>
            <param-name>org.atmosphere.cpr.BroadcasterCache.strategy</param-name>
            <param-value>beforeFilter|afterFilter</param-value>
       </init-param>

Finally, if you are using BroadcasterCache without extending the AbstractReflectorAtmosphereHandler, your AtmosphereHandler.onStateChange will be invoked with an AtmosphereResourceEvent which will return:

   List<Object> cachedMessage = (List<Object>) atmosphereResourceEvent.getMessage(); 

It is recommended to extend AbstractReflectorAtmosphereHandler or make sure the above case is well handled.

You can filter the messages that get cached inside a BroadcasterCache by adding one or more [BroadcasterCacheInspector], which is a simple interface defined as:

public interface BroadcasterCacheInspector {
    /**
     * Inspect the {@link BroadcasterCache.Message} and return true if the message can be cached, false if not. A
     * Message can also be modified
     * @param message {@link BroadcasterCache.Message}
     * @return true if allowed to be cached, false if not.
     */
    boolean inspect(BroadcasterCache.Message message);
}

Return true means the message will be cached. You can also modify the message inside the inspect method.

You can programmatically add inspectors by doing:

   myBroadcaster.getBroadcasterCache().inspector(new BroadcasterCacheInspector() {
            @Override
            public boolean inspect(BroadcasterCache.Message message) {
                // Allow all messages to be cached
                return true;
            }
        });

or use the @BroadcasterCacheInspectorService annotation

@BroadcasterCacheInspector
public class MyInspector implements BroadcasterCacheInspector {
       @Override
       public boolean inspect(BroadcasterCache.Message message) {
           // Allow all messages to be cached
           return true;
       }
}

An application can ban (or block) a client from receiving cached messages:

   BroadcasterCache cache = atmosphereResource.getBroadcaster()
       .getBroadcasterConfig().getBroadcasterCache();
   cache.excludeFromCache(atmosphereResource.getBroadcaster().getID(), atmosphereResource);

Now the client represented by the AtmosphereResource.uuid() won't receive any cached messages from Broadcaster.getID(). You can re-add the AtmosphereResource by doing:

   cache.cacheCandidate(atmosphereResource.getBroadcaster().getID(), atmosphereResource.uuid());