org.atmosphere.cpr
Interface BroadcasterCache

All Known Implementing Classes:
AbstractBroadcasterCache, DefaultBroadcasterCache, SessionBroadcasterCache, UUIDBroadcasterCache

public interface BroadcasterCache

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 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

Field Summary
static BroadcasterCache DEFAULT
           
static String NULL
           
 
Method Summary
 BroadcasterCache addBroadcasterCacheListener(BroadcasterCacheListener l)
          Add a BroadcasterCacheListener
 CacheMessage addToCache(String broadcasterId, String uuid, BroadcastMessage message)
          Start tracking messages associated with AtmosphereResource from the cache.
 BroadcasterCache cacheCandidate(String broadcasterId, String uuid)
          Add a AtmosphereResource.uuid() to the list of active AtmosphereResource Message will be cached for the resource associated with the uuid.
 void cleanup()
          Clean resources associated with this instance.
 BroadcasterCache clearCache(String broadcasterId, String uuid, CacheMessage cache)
          Remove the previously cached message.
 void configure(BroadcasterConfig config)
          Configure the cache.
 BroadcasterCache excludeFromCache(String broadcasterId, AtmosphereResource r)
          Allow an application to exclude, or block, an AtmosphereResource to received cached message.
 BroadcasterCache inspector(BroadcasterCacheInspector interceptor)
          Add a BroadcasterCacheInspector that will be invoked before a message gets added to the cache.
 BroadcasterCache removeBroadcasterCacheListener(BroadcasterCacheListener l)
          Remove a BroadcasterCacheListener
 List<Object> retrieveFromCache(String id, String uuid)
          Retrieve messages associated with AtmosphereResource.
 void start()
          This method is invoked when the Broadcaster is started.
 void stop()
          This method is invoked when the Broadcaster is stopped.
 

Field Detail

NULL

static final String NULL
See Also:
Constant Field Values

DEFAULT

static final BroadcasterCache DEFAULT
Method Detail

start

void start()
This method is invoked when the Broadcaster is started.


stop

void stop()
This method is invoked when the Broadcaster is stopped.


cleanup

void cleanup()
Clean resources associated with this instance. This method is useful when ExecutorServices are shared and some future must be cancelled. This method will always be invoked when a Broadcaster gets destroyed.


configure

void configure(BroadcasterConfig config)
Configure the cache.

Parameters:
config - a BroadcasterConfig

addToCache

CacheMessage addToCache(String broadcasterId,
                        String uuid,
                        BroadcastMessage message)
Start tracking messages associated with AtmosphereResource from the cache.

Parameters:
broadcasterId - The associated Broadcaster#addAtmosphereResource(AtmosphereResource).getID
uuid - AtmosphereResource.uuid()
message - BroadcastMessage.
Returns:
The CacheMessage

retrieveFromCache

List<Object> retrieveFromCache(String id,
                               String uuid)
Retrieve messages associated with AtmosphereResource.

Parameters:
id - The associated org.atmosphere.cpr.Broadcaster#addAtmosphereResource(org.atmosphere.cpr.AtmosphereResource).getID
uuid - AtmosphereResource
Returns:
a List of messages (String).

clearCache

BroadcasterCache clearCache(String broadcasterId,
                            String uuid,
                            CacheMessage cache)
Remove the previously cached message.

Parameters:
broadcasterId - The Broadcaster.getID()
uuid - an AtmosphereResource.uuid()
cache - the CacheMessage

excludeFromCache

BroadcasterCache excludeFromCache(String broadcasterId,
                                  AtmosphereResource r)
Allow an application to exclude, or block, an AtmosphereResource to received cached message. No new message will get sent to this client except the ones already cached.

Parameters:
broadcasterId - The Broadcaster.getID()
r - an AtmosphereResource
Returns:
this

cacheCandidate

BroadcasterCache cacheCandidate(String broadcasterId,
                                String uuid)
Add a AtmosphereResource.uuid() to the list of active AtmosphereResource Message will be cached for the resource associated with the uuid.

Parameters:
broadcasterId - The Broadcaster.getID()
uuid - an AtmosphereResource.uuid()
Returns:
this

inspector

BroadcasterCache inspector(BroadcasterCacheInspector interceptor)
Add a BroadcasterCacheInspector that will be invoked before a message gets added to the cache.

Parameters:
interceptor - an instance of BroadcasterCacheInspector
Returns:
this

addBroadcasterCacheListener

BroadcasterCache addBroadcasterCacheListener(BroadcasterCacheListener l)
Add a BroadcasterCacheListener

Parameters:
l - a BroadcasterCacheListener
Returns:
this

removeBroadcasterCacheListener

BroadcasterCache removeBroadcasterCacheListener(BroadcasterCacheListener l)
Remove a BroadcasterCacheListener

Parameters:
l - a BroadcasterCacheListener
Returns:
this


Copyright © 2014. All rights reserved.