Understanding Broadcaster

Configuring the default

By default, Atmosphere is using the DefaultBroadcaster and JerseyBroadcaster if atmosphere-jersey is used. You can either extends those Broadcaster or write your own. You can configure it by doing: In web.xml

        <init-param>
            <param-name>org.atmosphere.cpr.broadcasterClass</param-name>
            <param-value>org....</param-value>
        </init-param>

or in atmosphere.xml

        <applicationConfig>
            <param-name>org.atmosphere.cpr.broadcasterClass</param-name>
            <param-value>org...</param-value>
        </applicationConfig>

Atmosphere auto discovery of Broadcaster

Atmosphere is able to auto discover the following Broadcaster when available on the classpath

• RedisBroadcaster
• JGroupsBroadcaster
• XMPPBroadcaster
• HazelcastBroadcaster
• JMSBroadcaster

That means you don't have to specify them by default.

Asynchronous I/O and Broadcast.

By default, a Broadcaster always creates two ExecutorServices: one for supporting asynchronous broadcast, one for supporting asynchronous write. If you don't need asynchronous I/O, it is recommended you use the SimpleBroadcaster or SimpleJerseyBroadcaster.

Preventing Out Of Memory

Using shareable ExecutorServices

If your application creates a lot of Broadcaster, you may experiment some Out Of Memory error because too many instance of ExecutorServices has been created, e.g number of broadcaster * 2. If that's the case, you can configure Atmosphere to share ExecutorServices amongst Broadcaster. In that case only two ExecutorServices will be created: In web.xml

        <init-param>
            <param-name>org.atmosphere.cpr.broadcaster.shareableThreadPool</param-name>
            <param-value>true</param-value>
        </init-param>

or in atmosphere.xml

        <applicationConfig>
            <param-name>org.atmosphere.cpr.broadcaster.shareableThreadPool</param-name>
            <param-value>true</param-value>
        </applicationConfig>

Using BroadcasterLifeCyclePolicy

Another way to prevent or reduce memory usage is by configuring a BroadcasterFactoryLifecyclePolicy. Supported policy are:

• IDLE: Release all resources associated with the Broadcaster when the idle time expires. Suspended AtmosphereResource will NOT get resumed and instead be closed right away.
• IDLE_DESTROY: Release all resources associated with the Broadcaster when the idle time expires and destroy the Broadcaster. This operation remove the Broadcaster from it's associated BroadcasterFactory. Suspended AtmosphereResource will NOT get resumed and instead be closed right away.
• IDLE_RESUME:Release all resources associated with the Broadcaster when the idle time expires. All associated AtmosphereResource WILL BE resumed and this broadcaster destroyed.
• EMPTY: If there is no AtmosphereResource associated with the Broadcaster release all resources.
• EMPTY_DESTROY: If there is no AtmosphereResource associated with the Broadcaster, release all resources and destroy the broadcaster. This operation remove the Broadcaster from it's associated BroadcasterFactory
• NEVER: Never release or destroy the Broadcaster from it's associated BroadcasterFactory

The default is NEVER, which means that a fair amount of Broadcaster may "polute' the BroadcasterFactory if not handled properly. BroadcasterFactoryLifecyclePolicy can be configured

Programmatically

You can configure the policy on a Broadcaster directly:

 Broadcaster b = BroadcasterFactory.getDefault().get();
 b.setBroadcasterLifeCyclePolicy(BroadcasterLifeCyclePolicy.IDLE);

You can also associate BroadcasterLifeCyclePolicyListener to a Broadcaster so you get notified when a policy is exectuted.

 b.addBroadcasterLifeCyclePolicyListener(new BroadcasterLifeCyclePolicyListener() {...});

Using web/atmosphere.xml

In web.xml

        <init-param>
            <param-name>org.atmosphere.cpr.broadcasterLifeCyclePolicy</param-name>
            <param-value>IDLE</param-value>
        </init-param>

or in atmosphere.xml

        <applicationConfig>
            <param-name>org.atmosphere.cpr.broadcasterLifeCyclePolicy</param-name>
            <param-value>IDLE</param-value>
        </applicationConfig>