Atmosphere Framework Concepts - Atmosphere/atmosphere GitHub Wiki
WORK in PROGRESS
Introduction
The Atmosphere Framework is designed to make it easier to build asynchronous/Comet-based Web applications that include a mix of Comet and RESTful behavior. The Atmosphere Framework is portable and can be deployed on any Web Server that supports the Servlet Specification 2.3. This document introduces the framework and its module. For any questions or feedback, post them at [email protected]
Terminology
- Suspend: The action of suspending consist of telling the underlying Web Server to not commit the response, e.g. to not send back to the browser the final bytes the browser is waiting for before considering the request completed.
- Resume: The action of resuming consist of completing the response, e.g. committing the response by sending back to the browser the final bytes the browser is waiting for before considering the request completed.
- Broadcast: The action of broadcasting consists of producing an event and distributing that event to one or many suspended response. The suspended response can then decide to discard the event or send it back to the browser.
- Long Polling: Long polling consists of resuming a suspended response as soon as event is getting broadcasted.
- Http Streaming: Http Streaming, also called forever frame, consists of resuming a suspended response after multiples events are getting broadcasted.
- WebSocket: A new protocol allowing bi-directional communication between a browser and server.
- Native Asynchronous API: A native asynchronous API means an API that is proprietary, e.g. if you write an application using that API, the application will not be portable across Web Server.
What is the Atmosphere Framework?
The Atmosphere Framework contains several modules, which can be used depending on your needs:
- Atmosphere Runtime (Comet Portable Runtime): This module can be used to write POJO written in Java, JRuby or Groovy. The main component of this module is an AtmosphereHandler. An AtmosphereHandler can be used to suspend, resume and broadcast and allow the use of the usual HttpServletRequest and HttpServletResponse set of API.
- Atmosphere Annotations: This module defines the set of annotations that can be implemented to support Atmosphere concepts. By default, the Atmosphere Jersey module implements them, but any framework can also add an implementation.
- Atmosphere Jersey: This module can be used to write REST & Asynchronous Web application. The REST engine used is Jersey (Sun’s JAX RS implementation).
- Atmosphere Meteor: This module can be used with existing Servlet or Servlet based technology like JSP, JSF, Struts, etc. The main component is a Meteor that can easily be looked up from any Java Object.
- Atmosphere GWT: This module adds Atmosphere's support to the GWT Framework.
The Framework also contains it’s own ready to use Web Server named the Atmosphere Spade Server, which consist of an end to end stack containing the Grizzly Web Server, Jersey and all Atmosphere modules and Plug-in. The Atmosphere Framework supports natively the following Web Server asynchronous API:
- Tomcat’s CometProcessor
- GlassFish’s CometHandler
- Jetty’s Continuation
- JBoss’ HttpEvent
- Netty HTTP
- Grizzly’s CometHandler
- Servlet 3.0’s AsyncListener
- Tomcat WebSocket
- Jetty WebSocket
- GlassFish WebSocket
- Netty WebSocket
If Atmosphere fails to detect the above native API, it will instead use its own asynchronous API implementation, which will consist of blocking a Thread per suspended connections. That means Atmosphere applications are guarantee to work on any Web Server supporting the Servlet specification version 2.3 and up. Note that it is also possible to write your own native implementation and replace the one used by default in Atmosphere by providing an implementation of the CometSupport SPI. See next section for more information.