org.atmosphere.cpr
Interface Broadcaster

All Known Implementing Classes:

AbstractBroadcasterProxy, DefaultBroadcaster, ExcludeSessionBroadcaster, SimpleBroadcaster

public interface Broadcaster

A Broadcaster is responsible for delivering messages to its subscribed AtmosphereResource, which are representing a suspended response. AtmosphereResource can be added using addAtmosphereResource(org.atmosphere.cpr.AtmosphereResource), so when broadcast(java.lang.Object) execute, AtmosphereHandler.onStateChange(org.atmosphere.cpr.AtmosphereResourceEvent) will be invoked and the suspended connection will have a chance to write the message available using AtmosphereResourceEvent.getMessage()
A Broadcaster, by default, will use an ExecutorService, and the number of Thread will be computed based on the core/cpu of the OS under which the application run. Thus invoking broadcast(Object) will be executed asynchronously so this is important to wait for the Future.get() to awake/unblock to be garantee the operation has completed.
One final word on Broadcaster: by default, a Broadcaster will broadcast using all AtmosphereResource on which the response has been suspended, e.g. {AtmosphereResource#suspend()} has been invoked. This behavior is configurable and you can configure it by invoking the setScope(org.atmosphere.cpr.Broadcaster.SCOPE) ):

• REQUEST: broadcast events only to the AtmosphereResourceEvent associated with the current request.
• APPLICATION: broadcast events to all AtmosphereResourceEvent created for the current web application.
• VM: broadcast events to all AtmosphereResourceEvent created inside the current virtual machine.

Author:

Jeanfrancois Arcand

Nested Class Summary

static class	Broadcaster.POLICY
static class	Broadcaster.SCOPE

Method Summary

Broadcaster	addAtmosphereResource(AtmosphereResource resource) Add a AtmosphereResource to the list of item to be notified when the broadcast(T) is invoked.
void	addBroadcasterLifeCyclePolicyListener(BroadcasterLifeCyclePolicyListener b) Add a BroadcasterLifeCyclePolicyListener
Broadcaster	addBroadcasterListener(BroadcasterListener b) Add a BroadcasterListener
<T> Future<T>	awaitAndBroadcast(T t, long time, TimeUnit timeUnit) Await for available AtmosphereResource before broadcasting.
<T> Future<T>	broadcast(T o) Broadcast the Object to all suspended response, e.g.
<T> Future<T>	broadcast(T o, AtmosphereResource resource) Broadcast the Object to all suspended response, e.g.
<T> Future<T>	broadcast(T o, Set<AtmosphereResource> subset) Broadcast the Object to all suspended response, e.g.
<T> Future<T>	broadcastOnResume(T o) Broadcast the Object when an AtmosphereResource is resumed by a timeout or when using AtmosphereResource.resume()
<T> Future<T>	delayBroadcast(T o) Delay the broadcast operation.
<T> Future<T>	delayBroadcast(T o, long delay, TimeUnit t) Delay the broadcast operation.
void	destroy() Destroy this instance and shutdown it's associated ExecutorService
Collection<AtmosphereResource>	getAtmosphereResources() Return an List of AtmosphereResource.
BroadcasterConfig	getBroadcasterConfig() Return the current BroadcasterConfig
String	getID() Return the id of this Broadcaster
Broadcaster.SCOPE	getScope() Return the Broadcaster.SCOPE
boolean	isDestroyed() Return true if that Broadcaster has been destroyed
void	releaseExternalResources() Release external resources associated with this Broadcaster.
Broadcaster	removeAtmosphereResource(AtmosphereResource resource) Remove a AtmosphereResource from the list of item to be notified when the broadcast(T) is invoked.
void	removeBroadcasterLifeCyclePolicyListener(BroadcasterLifeCyclePolicyListener b) Remove a BroadcasterLifeCyclePolicyListener
Broadcaster	removeBroadcasterListener(BroadcasterListener b) Remove a BroadcasterListener
void	resumeAll() Resume all suspended responses (AtmosphereResource) added via addAtmosphereResource(org.atmosphere.cpr.AtmosphereResource).
<T> Future<T>	scheduleFixedBroadcast(T o, long waitFor, long period, TimeUnit t) Broadcast periodically.
<T> Future<T>	scheduleFixedBroadcast(T o, long period, TimeUnit t) Broadcast periodically.
void	setBroadcasterConfig(BroadcasterConfig bc) Set the BroadcasterConfig instance.
void	setBroadcasterLifeCyclePolicy(BroadcasterLifeCyclePolicy policy) Set the BroadcasterLifeCyclePolicy.
void	setID(String name) Set the id of this Broadcaster
void	setScope(Broadcaster.SCOPE scope) Set the scope.
void	setSuspendPolicy(long maxSuspended, Broadcaster.POLICY policy) Set the maximum number of suspended AtmosphereResource.

Method Detail

setSuspendPolicy

void setSuspendPolicy(long maxSuspended,
                      Broadcaster.POLICY policy)

Set the maximum number of suspended AtmosphereResource. If the max is reached, Atmosphere will either resume AtmosphereResource using Broadcaster.POLICY.FIFO (first in first out) or Broadcaster.POLICY.REJECT the AtmosphereResource.

By default the number is uunlimited.

Parameters:

maxSuspended - max suspended

broadcast

<T> Future<T> broadcast(T o)

Broadcast the Object to all suspended response, e.g. invoke AtmosphereHandler.onStateChange(org.atmosphere.cpr.AtmosphereResourceEvent).

Parameters:

o - and Object to be broadcasted.

Returns:

a Future that can be used to synchronize using the Future.get()

delayBroadcast

<T> Future<T> delayBroadcast(T o)

Delay the broadcast operation. The Object will be broadcasted when the first broadcast(java.lang.Object) is invoked.

Parameters:

o - and Object to be broadcasted.

Returns:

a Future that can be used to synchronize using the Future.get()

delayBroadcast

<T> Future<T> delayBroadcast(T o,
                             long delay,
                             TimeUnit t)

Delay the broadcast operation. The Object will be broadcasted once the specified delay expires or when the first broadcast(java.lang.Object)

Parameters:

o - and Object to be broadcasted.

delay - Amount of time to delay.

t - a TimeUnit of delay.

Returns:

a Future that can be used to synchronize using the Future.get()

scheduleFixedBroadcast

<T> Future<T> scheduleFixedBroadcast(T o,
                                     long period,
                                     TimeUnit t)

Broadcast periodically. The Object will be broadcasted after every period specified time frame expires. If the TimeUnit is set null, the Object will be broadcasted when the first broadcast(java.lang.Object) is invoked.

Parameters:

o - and Object to be broadcasted.

period - Every so often broadcast.

t - a TimeUnit of period.

Returns:

a Future that can be used to synchronize using the Future.get()

scheduleFixedBroadcast

<T> Future<T> scheduleFixedBroadcast(T o,
                                     long waitFor,
                                     long period,
                                     TimeUnit t)

Broadcast periodically. The Object will be broadcasted after every period specified time frame expires. If the TimeUnit is set null, the Object will be broadcasted when the first broadcast(java.lang.Object) * is invoked.

Parameters:

o - and Object to be broadcasted.

waitFor - Wait for that long before first broadcast.

period - The period inbetween broadcast.

t - a TimeUnit of waitFor and period.

Returns:

a Future that can be used to synchronize using the Future.get()

broadcast

<T> Future<T> broadcast(T o,
                        AtmosphereResource resource)

Broadcast the Object to all suspended response, e.g. invoke AtmosphereHandler.onStateChange(org.atmosphere.cpr.AtmosphereResourceEvent) with an instance of AtmosphereResource, representing a single suspended response..

Parameters:

o - and Object to be broadcasted.

resource - an AtmosphereResource

Returns:

a Future that can be used to synchronize using the Future.get()

broadcastOnResume

<T> Future<T> broadcastOnResume(T o)

Broadcast the Object when an AtmosphereResource is resumed by a timeout or when using AtmosphereResource.resume()

Parameters:

o - and Object to be broadcasted.

Returns:

a Future that can be used to synchronize using the Future.get()

broadcast

<T> Future<T> broadcast(T o,
                        Set<AtmosphereResource> subset)

Broadcast the Object to all suspended response, e.g. invoke AtmosphereHandler.onStateChange(org.atmosphere.cpr.AtmosphereResourceEvent) with a Set of AtmosphereResource, representing a set of AtmosphereHandler.

Parameters:

o - and Object to be broadcasted.

subset - a Set of AtmosphereResource

Returns:

a Future that can be used to synchronize using the Future.get()

addAtmosphereResource

Broadcaster addAtmosphereResource(AtmosphereResource resource)

Add a AtmosphereResource to the list of item to be notified when the broadcast(T) is invoked. It is strongly recommended to suspend the AtmosphereResource before adding it to a Broadcaster.

Parameters:

resource - an AtmosphereResource

Returns:

this

removeAtmosphereResource

Broadcaster removeAtmosphereResource(AtmosphereResource resource)

Remove a AtmosphereResource from the list of item to be notified when the broadcast(T) is invoked.

Parameters:

resource - an AtmosphereResource

Returns:

this

setBroadcasterConfig

void setBroadcasterConfig(BroadcasterConfig bc)

Set the BroadcasterConfig instance.

Parameters:

bc - Configuration to be set.

getBroadcasterConfig

BroadcasterConfig getBroadcasterConfig()

Return the current BroadcasterConfig

Returns:

the current BroadcasterConfig

destroy

void destroy()

Destroy this instance and shutdown it's associated ExecutorService

getAtmosphereResources

Collection<AtmosphereResource> getAtmosphereResources()

Return an List of AtmosphereResource.

Returns:

List of AtmosphereResource associated with this Broadcaster.

See Also:

addAtmosphereResource(AtmosphereResource)

setScope

void setScope(Broadcaster.SCOPE scope)

Set the scope.

Parameters:

scope - Broadcaster.SCOPE to set.

getScope

Broadcaster.SCOPE getScope()

Return the Broadcaster.SCOPE

Returns:

Broadcaster.SCOPE of Broadcaster.

setID

void setID(String name)

Set the id of this Broadcaster

Parameters:

name - ID of this Broadcaster

getID

String getID()

Return the id of this Broadcaster

Returns:

the id of this Broadcaster

resumeAll

void resumeAll()

Resume all suspended responses (AtmosphereResource) added via addAtmosphereResource(org.atmosphere.cpr.AtmosphereResource).

releaseExternalResources

void releaseExternalResources()

Release external resources associated with this Broadcaster. This is useful when a Broadcaster no longer have suspended AtmosphereResource and some resource (like database connections, JMS queue, etc.) needs to be closed.

setBroadcasterLifeCyclePolicy

void setBroadcasterLifeCyclePolicy(BroadcasterLifeCyclePolicy policy)

Set the BroadcasterLifeCyclePolicy. Make sure you are selecting the right policy to avoid unexpected situation.

Parameters:

policy - a BroadcasterLifeCyclePolicy

addBroadcasterLifeCyclePolicyListener

void addBroadcasterLifeCyclePolicyListener(BroadcasterLifeCyclePolicyListener b)

Add a BroadcasterLifeCyclePolicyListener

Parameters:

b - a BroadcasterLifeCyclePolicyListener

removeBroadcasterLifeCyclePolicyListener

void removeBroadcasterLifeCyclePolicyListener(BroadcasterLifeCyclePolicyListener b)

Remove a BroadcasterLifeCyclePolicyListener

Parameters:

b - a BroadcasterLifeCyclePolicyListener

isDestroyed

boolean isDestroyed()

Return true if that Broadcaster has been destroyed

Returns:

true if that Broadcaster has been destroyed

awaitAndBroadcast

<T> Future<T> awaitAndBroadcast(T t,
                                long time,
                                TimeUnit timeUnit)

Await for available AtmosphereResource before broadcasting. This method will block until addAtmosphereResource(AtmosphereResource) gets invoked.

addBroadcasterListener

Broadcaster addBroadcasterListener(BroadcasterListener b)

Add a BroadcasterListener

Parameters:

b - a BroadcasterListener

Returns:

this

removeBroadcasterListener

Broadcaster removeBroadcasterListener(BroadcasterListener b)

Remove a BroadcasterListener

Parameters:

b - a BroadcasterListener

Returns:

this