Installing Atmosphere - Atmosphere/atmosphere GitHub Wiki

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 1.x. 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.

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.

Embedding 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);