org.atmosphere.cpr
Interface Broadcaster

All Known Implementing Classes:
AbstractBroadcasterProxy, DefaultBroadcaster, ExcludeSessionBroadcaster, JerseyBroadcaster, JerseySimpleBroadcaster, 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) ):

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


Copyright © 2014. All Rights Reserved.