Installing AtmosphereServlet with or without native support

Jeanfrancois Arcand edited this page Jan 13, 2015 · 21 revisions

FAQ

Step by Step Tutorials

Concepts & Architecture

15 Minutes Tutorial

Advanced Topics

API

Known WebServer Issues

References

External Documentations

githalytics.com alpha

Clone this wiki locally

Use it with Tomcat 6, WebLogic and JBoss 7.x ONLY.

Dependencies

Starting with 2.0, the only dependency an application needs, by default:

./WEB-INF
./WEB-INF/lib
./WEB-INF/lib/atmosphere-runtime-2.0.0.jar         
./WEB-INF/lib/slf4j-api-1.6.1.jar                  

Note: If you are using a framework that build on top of atmosphere-runtime, make sure the dependency is EXCLUDED from the dependency tree to avoid issue.

if you see this message, you may want to install the native package

Caused by: java.lang.IllegalStateException: JBoss[Tomcat] failed to detect this is a Comet application because the APR Connector is not enabled. 
Make sure atmosphere-compat-jboss|tomcat.jar is not under your WEB-INF/lib and You must use the atmosphere-native-runtime dependency in order to use native Comet Support
there is no context.xml under WEB-INF

Servlet 3.0 Async API

Starting with 2.0, the Atmosphere Framework will, by default, only support the Servlet 3.0 Async API with either JSR 356 (WebSocket API) or native WebSocket support. For jsr356 support, only jsr356 + Servlet 3.0 will be supported.

Native Comet Support using Atmosphere 1.0.x

To use Native Comet/WebSocket Support like Tomcat AIO/WebSocket, Jetty Continuation/WebSocket or Grizzly Comet WebSocket, add in web.xml/application.xml

        <init-param>
            <param-name>org.atmosphere.useNative</param-name>
            <param-value>true</param-value>
        </init-param>

Native Comet Support using Atmosphere 2.0.x

Note: atmosphere-runtime IS NOT NEEDED AND MUST BE EXCLUDED when atmosphere-runtime-native is used.

For Tomcat 6/7 and JBossWeb 3.x native Comet support

For those server, you need use atmosphere-runtime-native jar file:

        <dependency>
            <groupId>org.atmosphere</groupId>
            <artifactId>atmosphere-runtime-native</artifactId>
            <version>2.0.0.x</version>
        </dependency>

and also make sure the following dependency are present. By default they are pulled from Maven, but if you build with another tool, make sure you add them:

Tomcat 7

        <dependency>
            <groupId>org.atmosphere</groupId>
            <artifactId>atmosphere-compat-jbossweb</artifactId>
            <version>2.0.1</version>
        </dependency>
        <dependency>
            <groupId>org.atmosphere</groupId>
            <artifactId>atmosphere-compat-tomcat</artifactId>
            <version>2.0.1</version>
        </dependency>

Tomcat 6

        <dependency>
            <groupId>org.atmosphere</groupId>
            <artifactId>atmosphere-compat-jbossweb</artifactId>
            <version>2.0.1</version>
        </dependency>
        <dependency>
            <groupId>org.atmosphere</groupId>
            <artifactId>atmosphere-compat-tomcat7</artifactId>
            <version>2.0.1</version>
        </dependency>

JBossWeb

        <dependency>
            <groupId>org.atmosphere</groupId>
            <artifactId>atmosphere-compat-tomcat</artifactId>
            <version>2.0.1</version>
        </dependency>
        <dependency>
            <groupId>org.atmosphere</groupId>
            <artifactId>atmosphere-compat-tomcat7</artifactId>
            <version>2.0.1</version>
        </dependency>

Native WebSocket implementation with Native Comet support

To use native WebSocket support with native Comet support, you must add, in web.xml/application.xml

        <init-param>
            <param-name>org.atmosphere.useWebSocketAndServlet3</param-name>
            <param-value>false</param-value>
        </init-param>

and make sure you have read the previous section if you are using Tomcat or JBossWeb.

WEB-INF/context.xml (Tomcat) and META-INF/context.xml (JBoss)

Make sure the context.xml is present

<Context>
    <Loader delegate="true"/>
</Context>

and if not, please make sure you exclude the server's jar from being pulled. For example, with Tomcat 7

         <dependency>
            <groupId>org.atmosphere</groupId>
            <artifactId>atmosphere-runtime-native</artifactId>
            <version>2.0.0.x</version>
            <exclusions>
                <exclusion>
                    <groupId>org.atmosphere</groupId>
                    <artifactId>atmosphere-compat-tomcat7</artifactId>
                </exclusion>
            </exclusions>
         </dependency>  

Quick dependency reference

runtime runtime native compat jbossweb compat tomcat compat tomcat7
jetty9 Y N N N N
tomcat8 Y N N N N
glassfish4 Y N N N N
tomcat7 N Y Y Y N
tomcat6 N Y Y N Y
jboss3 N Y N Y Y