Understanding BroadcasterCache - Atmosphere/atmosphere 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:

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:


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

  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


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.

Filtering Cached Messages (supported with Atmosphere 1.1 and up)

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() {
            public boolean inspect(BroadcasterCache.Message message) {
                // Allow all messages to be cached
                return true;

or use the @BroadcasterCacheInspectorService annotation

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

Banning AtmosphereResource from receiving Cached Messages (supported with Atmosphere 1.1 and up)

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

   BroadcasterCache cache = atmosphereResource.getBroadcaster()
   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());