Getting Started with the ManagedService Annotation

The easiest way to create Atmosphere's application is by using the ManagedService annotation. This annotation makes it easy to build application with Atmosphere without the need to interact with Atmosphere's more sophisticated API. For example, if you are familiar with AtmosphereHandler and how an AtmosphereResource life cycle must be handled, this annotation will transparently handle it. The annotation also install the best BroadcasterCache and several AtmosphereInterceptor, significantly reducing the number of code required to build a powerful real time application. For example, Atmosphere ships with an extremely simple Chat application, which support multi room, all transports transparently, message caching, etc. All of this in less than 100 lines!

@ManagedService

The annotation's attributes available are

• path: The path to the resource. The default is "/" so if your have mapped the AtmosphereServlet to '/*', all request will be delivered to your annotated classe. You can also customize the path.
• listeners: Add one or several AtmosphereResourceEventListener. Usefull if your application needs to execute some actions based on the AtmosphereResource's life cycle.
• broadcaster: The Broadcaster to use for every request. The default is the DefaultBroadcaster
• interceptors: The list of AtmosphereInterceptor. By default, AtmosphereResourceLifecycleInterceptor, TrackMessageSizeInterceptor, HeartbeatInterceptor, SuspendTrackerInterceptor and AnnotationServiceInterceptor are installed.
• atmosphereConfig: Configure some ApplicationConfig parameters. Those parameters can be used to configure the Atmosphere's runtime. Default is empty.
• broadcasterCache: Install a BroadcasterCache to repent loosing messages when a network outage happens.. Default is UUIDBroadcasterCache
• broadcastFilters: Install BroadcastFilter for manipulating messages before they get delivered to the client. Default is empty.

Class Scope Annotations available

@Singleton

The Singleton annotation can be used to force Atmosphere to create a single, thread safe instance of a ManagedService annotated classes. For example, if your application use the @ManagedService's path attribute with using path templates {something}, by default a new instance of the annotated classes will be created. When annotated with Singleton, a single class will be created.

Method Scope Annotations available

When using the @ManagedService annotation, it is recommended to use the following annotations. At last, you can use the annotation defined in the next section.

@Ready

The Ready will be invoked when the underlying connection is ready to be used, e.g for write operations. The annotation's attributes available are:

• value: The returned value of the an annotated method can be dispatched to the resource itself, to all the broadcaster associated with that resource, or to all created Broadcaster. Default is RESOURCE.
• encoders: A list of Encoder that will be used to encode the returned value of the method. Default is empty (no encoder).

Annotated method needs to take the form of

@Ready
public void onReady(AtmosphereResource r) {...}

The method's return value can be customized by defining an Encoder associated with that return value. For example, you can use the Jackson's JSON library to encode returned value:

@Ready(encoders = {JacksonEncoder.class})
public Message onReady(AtmosphereResource r) {
    return new Message(...);
}

When the onReady annotation gets invoked, the returned value will be processed by Jackson and the result will be dispatched to the appropriate resource, which will in turn write back that value to the client.

@Disconnect

The Disconnect will be invoked when the client disconnect, e.g close the connection, when a network outage happens or when a proxy close the connection. Annotated method needs to take the form of:

@OnDisconnect
public void onGet(AtmosphereResourceEvent r) {...}

Other Methods Scope Annotations available

@Get:

The Get will tell the framework to dispatch HTTP GET to the annotated method. Annotated method needs to take the form of:

@Get
public void onGet(AtmosphereResource r) {...}

@Post:

The Post will tell the framework to dispatch HTTP GET to the annotated method. Annotated method needs to take the form of:

@Post
public void onPost(AtmosphereResource r) {...}

@Delete:

The Delete will tell the framework to dispatch HTTP Delete to the annotated method. Annotated method needs to take the form of:

@Delete
public void onDelete(AtmosphereResource r) {...}

@Put:

The Put will tell the framework to dispatch HTTP Delete to the annotated method. Annotated method needs to take the form of:

@Put
public void onPut(AtmosphereResource r) {...}