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 AtmosphereResources, which are representing suspended responses. AtmosphereResource can be added using addAtmosphereResource(org.atmosphere.cpr.AtmosphereResource), so when broadcast(java.lang.Object) is executed, 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 will by default use an ExecutorService, and the number of Threads will be computed based on the number of cores/CPUs of the OS under which the application runs. Thus invoking broadcast(Object) will be executed asynchronously so this is important to wait for the Future.get() to awake/unblock to be guaranteed that 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

Nested Classes

Modifier and Type	Interface and Description
static class	Broadcaster.POLICY
static class	Broadcaster.SCOPE

Method Summary

Methods

Modifier and Type	Method and Description
Broadcaster	addAtmosphereResource(AtmosphereResource resource) Add a AtmosphereResource to the list of items to be notified when the broadcast(java.lang.Object) is invoked.
void	addBroadcasterLifeCyclePolicyListener(BroadcasterLifeCyclePolicyListener b) Add a BroadcasterLifeCyclePolicyListener.
Broadcaster	addBroadcasterListener(BroadcasterListener b) Add a BroadcasterListener.
Future<Object>	awaitAndBroadcast(Object t, long time, TimeUnit timeUnit) Await for available AtmosphereResource before broadcasting.
Future<Object>	broadcast(Object o) Broadcast the Object to all suspended responses, eg.
Future<Object>	broadcast(Object o, AtmosphereResource resource) Broadcast the Object to all suspended responses, eg.
Future<Object>	broadcast(Object o, Set<AtmosphereResource> subset) Broadcast the Object to all suspended response, eg.
Future<Object>	broadcastOnResume(Object o) Broadcast the Object when an AtmosphereResource is resumed by a timeout or when using AtmosphereResource.resume().
Future<Object>	delayBroadcast(Object o) Delay the broadcast operation.
Future<Object>	delayBroadcast(Object 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.
Broadcaster	initialize(String name, URI uri, AtmosphereConfig config) Configure a Broadcaster.
boolean	isDestroyed() Return true if this Broadcaster has been destroyed.
void	releaseExternalResources() Release external resources associated with this Broadcaster.
Broadcaster	removeAtmosphereResource(AtmosphereResource resource) Remove a AtmosphereResource from the list of s to be notified when the broadcast(java.lang.Object) 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).
Future<Object>	scheduleFixedBroadcast(Object o, long waitFor, long period, TimeUnit t) Broadcast periodically.
Future<Object>	scheduleFixedBroadcast(Object 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 AtmosphereResources.

Method Detail

initialize

Broadcaster initialize(String name,
                     URI uri,
                     AtmosphereConfig config)

Configure a Broadcaster.

Parameters:

name -

uri -

config - an AtmosphereConfig

Returns:

a usable Broadcaster.

setSuspendPolicy

void setSuspendPolicy(long maxSuspended,
                    Broadcaster.POLICY policy)

Set the maximum number of suspended AtmosphereResources. If the maximum 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 unlimited.

Parameters:

maxSuspended - maximum number of suspended AtmosphereResource

broadcast

Future<Object> broadcast(Object o)

Broadcast the Object to all suspended responses, eg. invoke AtmosphereHandler.onStateChange(org.atmosphere.cpr.AtmosphereResourceEvent).

Parameters:

o - the Object to be broadcasted

Returns:

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

delayBroadcast

Future<Object> delayBroadcast(Object o)

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

Parameters:

o - the Object to be broadcasted

Returns:

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

delayBroadcast

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

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

Parameters:

o - the Object to be broadcasted

delay - Amount of time to delay

t - the TimeUnit of the delay

Returns:

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

scheduleFixedBroadcast

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

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

Parameters:

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

Future<Object> scheduleFixedBroadcast(Object 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 - the 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

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

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

Parameters:

o - the Object to be broadcasted

resource - an AtmosphereResource

Returns:

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

broadcastOnResume

Future<Object> broadcastOnResume(Object o)

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

Parameters:

o - the Object to be broadcasted

Returns:

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

broadcast

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

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

Parameters:

o - the 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 items to be notified when the broadcast(java.lang.Object) 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 s to be notified when the broadcast(java.lang.Object) 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 situations.

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 this Broadcaster has been destroyed.

Returns:

true if this Broadcaster has been destroyed

awaitAndBroadcast

Future<Object> awaitAndBroadcast(Object 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