Getting Started with the ManagedService Annotation - Atmosphere/atmosphere GitHub Wiki

The easiest way to create an Atmosphere application is by using the ManagedService annotation. This annotation makes it easy to build applications with Atmosphere without the need to interact with Atmosphere's more sophisticated APIs. 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 installs the best BroadcasterCache and several AtmosphereInterceptors, significantly reducing the amount of code required to build a powerful real time application.

For example, Atmosphere ships with an extremely simple Chat application, which supports multi room, all transports transparently, message caching, etc. All of this in less than 100 lines! It is strongly recommended to take a look at the Chat and MultiChat sample after reading this introduction to see how simple it is to build an application with Atmosphere.

You can use the default built-in injection framework of Atmosphere for injecting Atmosphere's object, at runtime or request scoped, or jsr330, Spring or Guice.

You can also inject your own object by implementing the Injectable as described here

@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 class. You can also customize the path. The path value will be used to associate the AtmosphereResource with a Broadcaster, and the Broadcater's getID() will be the path value.
• listeners: Add one or several AtmosphereResourceEventListeners. Useful 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 AtmosphereInterceptors. By default, AtmosphereResourceLifecycleInterceptor, TrackMessageSizeInterceptor, HeartbeatInterceptor, SuspendTrackerInterceptor and AnnotationServiceInterceptor are installed.
• atmosphereConfig: Configure ApplicationConfig properties. Those properties can be used to configure the Atmosphere's runtime. Default is empty.
• broadcasterCache: Install a BroadcasterCache to avoid losing 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 set 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:

• 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. You can only annotate a single method with this annotation.

@Message

The Message will be invoked when a message is ready to be delived, e.g as a result of a Broadcaster#broadcast operation. The annotation's attributes available are:

• `encoders': A list of Encoder that will be used to encode the annotated method return's value. The returned value of an annotated Message's method will be broadcasted to all resources associated with the Broadcaster associated with this annotated classes. For example, you can use the Jackson JSON library to encode the returned value into a String or Bytes or any Object:

@Message(encoders = {AuthorMessageToBytesEncoder.class}, decoders = {JacksonEncoder.class})
public AuthorMessage authorMessage(Author message) {
    ...
    return new AuthorMessage(...);
}

Encoders can be chained, e.g the returned value of an Encoder can be used as an input for the next defined Encoder.

• `decoders': A list of Decoder used to decode a broadcasted messages into an object matching the method's signature. For example, you can use the Jackson JSON library to decode the broadcasted message:

@Message(decoders = {JacksonEncoder.class})
public void authorMessage(Author message) {
    ...
}
@Message(decoders = {JacksonEncoder.class})
public void userMessage(UserMessage message) {
    ...
}

Decoders can be chained, e.g the returned value of an Decoder can be used as an input for the next defined Decoder. You can annotate several methods with the Message annotation.

@DeliverTo

Any @Ready or @Message method can indicate to Atmosphere how the returned value should be dispatched with @DeliverTo annotation:

@Ready
@DeliverTo(DeliverTo.DELIVER_TO.BROADCASTER) // default is resource
public String ready() {
    ...
}

@Message
@DeliverTo(DeliverTo.DELIVER_TO.RESOURCE) // default is broadcaster
public String message() {
    ...
}

The returned value of the an annotated method can be dispatched to the resource itself (default for @Ready), to all the broadcasters associated with that resource (default for @Message), or to all created Broadcasters.

@Disconnect

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

@Disconnect
public void disconnected(AtmosphereResourceEvent r) {...}

You can only annotate a single method with this annotation.

@Resume

The Resume will be invoked when the connection is resumed. This principally happens with the long-polling transport. Annotated method needs to take the form of:

@Resume
public void onResume(AtmosphereResourceEvent r) {...}

You can only annotate a single method with this annotation.

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) {...}

You can only annotate a single method with this annotation.

@Post:

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

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

You can only annotate a single method with this annotation.

@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) {...}

You can only annotate a single method with this annotation.

@Put:

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

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

You can only annotate a single method with this annotation.