org.atmosphere.cpr
Interface BroadcasterCache

All Known Implementing Classes:

AbstractBroadcasterCache, DefaultBroadcasterCache, HeaderBroadcasterCache, 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, AtmosphereResource, org.atmosphere.cache.BroadcastMessage)
     method will be invoked, allowing the instance to cache the object.
     5. If the write operation succeeds, the clearCache(String, AtmosphereResource, 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, AtmosphereResource) 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, AtmosphereResource, 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

Method Summary

CacheMessage	addToCache(String broadcasterId, AtmosphereResource r, BroadcastMessage e) Start tracking messages associated with AtmosphereResource from the cache.
void	cleanup() Clean resources associated with this instance.
void	clearCache(String broadcasterId, AtmosphereResource r, CacheMessage cache) Remove the previously cached message.
void	configure(BroadcasterConfig config) Configure the cache.
void	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.
List<Object>	retrieveFromCache(String id, AtmosphereResource r) 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

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,
                        AtmosphereResource r,
                        BroadcastMessage e)

Start tracking messages associated with AtmosphereResource from the cache.

Parameters:

broadcasterId - The associated Broadcaster#addAtmosphereResource(AtmosphereResource).getID

r - AtmosphereResource

e - BroadcastMessage.

Returns:

The CacheMessage

retrieveFromCache

List<Object> retrieveFromCache(String id,
                               AtmosphereResource r)

Retrieve messages associated with AtmosphereResource.

Parameters:

id - The associated Broadcaster#addAtmosphereResource(AtmosphereResource).getID

r - AtmosphereResource

Returns:

a List of messages (String).

clearCache

void clearCache(String broadcasterId,
                AtmosphereResource r,
                CacheMessage cache)

Remove the previously cached message.

Parameters:

broadcasterId - The Broadcaster.getID()

r - an AtmosphereResource

cache - the CacheMessage

excludeFromCache

void 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

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