Installing Atmosphere

Configuring pom.xml

To install The Atmosphere Framework, you first need to install Maven, and add the following dependency in your pom.xml

            <dependency>
                <groupId>org.atmosphere</groupId>
                <artifactId>atmosphere-runtime</artifactId>
                <version>${atmosphere-version}</version>
            </dependency>

where atmosphere version can be 0.9.x or 1.0.0. If you are planning to use the Jersey extension, just add

            <dependency>
                <groupId>org.atmosphere</groupId>
                <artifactId>atmosphere-jersey</artifactId>
                <version>${atmosphere-version}</version>
            </dependency>

For GWT,

            <dependency>
                <groupId>org.atmosphere</groupId>
                <artifactId>atmosphere-gwt</artifactId>
                <version>${atmosphere-version}</version>
            </dependency>

The same pattern apply for Atmosphere's PlugIn extension.

Configuring web.xml

Next you need to decide how you want to install Atmosphere, e.g using the Servlet named AtmosphereServlet, using the Servlet's Filter AtmosphereFilter or by embedding the AtmosphereFramework class.

AtmosphereServlet

The AtmosphereServlet is defined as:

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:j2ee="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee    http://java.sun.com/xml/ns/j2ee/web-app_2.5.xsd">

    <description>AtmosphereServlet</description>
    <display-name>AtmosphereServlet</display-name>
    <servlet>
        <description>AtmosphereServlet</description>
        <servlet-name>AtmosphereServlet</servlet-name>
        <servlet-class>org.atmosphere.cpr.AtmosphereServlet</servlet-class>
        <!-- If you want to use Servlet 3.0 -->
        <async-supported>true</async-supported>
        <!-- List of init-param --> 
    </servlet>
    <servlet-mapping>
        <servlet-name>AtmosphereServlet</servlet-name>
        <!-- Any mapping -->
        <url-pattern>/*</url-pattern>
    </servlet-mapping>
</web-app>

The available init-param are described in that document.

AtmosphereFilter

The AtmosphereFilter only supports Servlet 3.0 WebServer, Jetty and GlassFish.
WebLogic and Tomcat are not supported.

The AtmosphereFilter is defined as:

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:j2ee="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee    http://java.sun.com/xml/ns/j2ee/web-app_2.5.xsd">

    <description>AtmosphereFilter</description>
    <display-name>AtmosphereFilter</display-name>
    <filter>
        <description>AtmosphereFilter</description>
        <filter-name>AtmosphereFilter</filter-name>
        <filter-class>org.atmosphere.cpr.AtmosphereFilter</filter-class>
        <!-- List of init-param --> 
    </filter>
    <filter-mapping>
        <filter-name>AtmosphereFilter</filter-name>
        <!-- Any mapping -->
        <url-pattern>/*</url-pattern>
    </filter-mapping>
</web-app>

The available init-param are described in that document.

AtmosphereFramework

The AtmosphereFramework class can be used to embed Atmosphere into another framework or application. As simple as

   AtmosphereFramework f = new AtmosphereFramework();
   f.init();

   // When request comes in:
   f.doCometSupport(AtmosphereRequest, AtmosphereResponse);

Configuring your application

If you are using Atmosphere Runtime, you can configure your application using an atmosphere.xml or web.xml's init-param, or use Atmosphere's Annotation. The available annotations are:

Using annotation

• AtmosphereHandlerService : At least on class must be annotated with this annotation if you are using AtmosphereServlet. The class must implements the AtmosphereHandler interface. See this tutorial for more information.
• BroadcasterCacheService : If you are planning to support your own BroadcasterCache implementation, use this annotation to tell Atmosphere to use it.
• BroadcasterFilterService : If you want to add BroadcastFilter to your application, annotate them using this annotation.
• BroadcasterService : If you are planning to support your own Broadcaster implementation, use this annotation to tell Atmosphere to use it.
• MeteorService : At least on class must be annotated with this annotation if you are using Atmosphere as as MeteorServlet. This class will install Meteor automatically.
• WebSocketHandlerService : If you want to write pure WebSocket application.
• WebSocketProtocolService : If you want to write your own WebSocketProtocol support for Atmosphere.
• AtmosphereInterceptor : Install AtmosphereInterceptor
• AsyncSupportListenerService : You can install a global events listener using that annotation. Read this document for more information.

Using atmosphere.xml

You can configure Atmosphere using an atmosphere.xml file located under META_INF/. The atmopshere.xml file takes the form of:

<atmosphere-handlers>
    <atmosphere-handler support-session="false"
                        context-root="PATH"
                        class-name="An AtmosphereHandler class name">
        <property name="servletClassName" value=""/>
        <applicationConfig> ... </applicationConfig>
    </atmosphere-handler>
</atmosphere-handlers>

See this page for more information about available applicationConfig.

Using web.xml

You can configure Atmosphere via several Servlet's init-param value. See this page for more information about available init-param.