Package org.atmosphere.cpr

Interface BroadcasterCache

All Superinterfaces:
AtmosphereConfigAware
All Known Implementing Classes:
AbstractBroadcasterCache, DefaultBroadcasterCache, SessionBroadcasterCache, UUIDBroadcasterCache
public interface BroadcasterCache extends AtmosphereConfigAware
A BroadcasterCache is a cache for broadcasted messages. When a Broadcaster is about to execute a broadcast operation (Broadcaster.broadcast(Object), the messages is cached, and the the write operation is executed. If the write operation succeed, the message is removed from the cache. If the write operation fails for an AtmosphereResource, the message stays in the cache so next time the client reconnects, the message can be sent back to the client. BroadcasterCache is useful for applications that require that no messages are lost, e.g all broadcasted message must be delivered to the client. If your application can survive lost messages, your don't need to install a BroadcasterCache.

A BroadcasterCache works the following way. The methods are always invoked from the application's Broadcaster. 

     1. When the Broadcaster is created, a unique BroadcasterCache is created and assigned to it as well. That means
     a BroadcasterCache is, by default, associated with a Broadcaster. You can share BroadcasterCache instances among
     Broadcasters as well.
     2. Just after the constructor has been invoked, the 


invalid reference

#configure(BroadcasterConfig)



 will get invoked, allowing
     the instance to configure itself based on a BroadcasterConfig.
     3. When Broadcaster starts, start() will be invoked.
     4. Every time a Broadcaster.broadcast(Object) invocation occurs, the addToCache(String, String, org.atmosphere.cache.BroadcastMessage)
     method will be invoked, allowing the instance to cache the object.
     5. If the write operation succeeds, the clearCache(String, String, org.atmosphere.cache.CacheMessage) method will
     be invoked. If the write operation fail the cache won't be cleared, and the message will be available next time the
     client reconnects. An application that write a BroadcasterCache must make sure cached message aren't staying in the
     cache forever to prevent memory leaks.
     6. When a client reconnects, the retrieveFromCache(String, String) method will be invoked.
     If messages are available, a List will be returned and written back to the client.
     7. When messages are added to the cache, an application can always customize the messages by creating BroadcasterCacheInspector
     and add them using inspector(org.atmosphere.cache.BroadcasterCacheInspector). BroadcasterCacheInspector
     will be invoked every time addToCache(String, String, org.atmosphere.cache.BroadcastMessage) is executed.
     8. An application may decide that, at one point in time, stop caching message for a particular AtmosphereResource by invoking
     excludeFromCache(String, AtmosphereResource)

Implementations of this interface must be thread-safe.

A BroadcasterCache can be configured by invoking BroadcasterConfig.setBroadcasterCache(BroadcasterCache), by defining it in your web/application.xml or by using the BroadcasterCacheService annotation.

Author:
Jeanfrancois Arcand