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