Configuring Atmosphere Listener - Atmosphere/atmosphere GitHub Wiki

The Atmosphere Framework supports several event listeners that can be used to monitor when a connection gets suspended, resumed, timed out or canceled. Those listeners can be used to track and clean the state that is associated with a connection. You can defined them in META-INF/services, annotate them or add it programmatically.

Using an AtmosphereFrameworkListener

You can configure AtmosphereFrameworkListener by implementing the interface and by annotating it using an AtmosphereFrameworkListenerService annotation. The interface is defined as

public interface AtmosphereFrameworkListener {
    /**
     * Invoked before {@link AtmosphereFramework#init()} gets invoked
     *
     * @param f an {@link org.atmosphere.cpr.AtmosphereFramework}
     */
    void onPreInit(AtmosphereFramework f);

    /**
     * Invoked after {@link AtmosphereFramework#init()} gets invoked
     *
     * @param f an {@link org.atmosphere.cpr.AtmosphereFramework}
     */
    void onPostInit(AtmosphereFramework f);

    /**
     * Invoked before {@link AtmosphereFramework#destroy()} gets invoked
     *
     * @param f an {@link org.atmosphere.cpr.AtmosphereFramework}
     */
    void onPreDestroy(AtmosphereFramework f);

    /**
     * Invoked after {@link AtmosphereFramework#destroy()} gets invoked
     *
     * @param f an {@link org.atmosphere.cpr.AtmosphereFramework}
     */
    void onPostDestroy(AtmosphereFramework f);
}

Using an AsyncSupportListener

You can configure AsyncSupportListener by implementing the interface and by annotating it using an AsyncSupportListenerService annotation. The interface is defined as:

public interface AsyncSupportListener {
    /**
     * Invoked when an AtmosphereResource gets suspended.
     * @param request an AtmosphereRequest
     * @param response an AtmosphereResponse
     */
    void onSuspend(AtmosphereRequest request, AtmosphereResponse response);

    /**
     * Invoked when an AtmosphereResource gets resumed
     * @param request an AtmosphereRequest
     * @param response an AtmosphereResponse
     */
    void onResume(AtmosphereRequest request, AtmosphereResponse response);

    /**
     * Invoked when an AtmosphereResource gets timed out
     * @param request an AtmosphereRequest
     * @param response an AtmosphereResponse
     */
    void onTimeout(AtmosphereRequest request, AtmosphereResponse response);

    /**
     * Invoked when an AtmosphereResource gets closed
     * @param request an AtmosphereRequest
     * @param response an AtmosphereResponse
     */
    void onClose(AtmosphereRequest request, AtmosphereResponse response);

    /**
     * Invoked when an AtmosphereResource gets destroyed
     * @param request an AtmosphereRequest
     * @param response an AtmosphereResponse
     */
    void onDestroyed(AtmosphereRequest request, AtmosphereResponse response);
}

The Atmosphere Framework will invoke each method based on the life cycle of the connection.

Using AtmosphereResourceEventListener

If you are using Atmosphere's Runtime module and have implemented an AtmosphereHandler or ManagedService, you can add an AtmosphereResourceEventListener or one of this adapter

public interface AtmosphereResourceEventListener {

    /**
     * Invoked when the AtmosphereResource#suspend has been completed and the response
     * considered as suspended.
     *
     * @param event a org.atmosphere.cpr.AtmosphereResourceEvent
     */
    void onSuspend(AtmosphereResourceEvent event);

    /**
     * Invoked when the AtmosphereResource#resume is invoked or when the
     * suspend's time out expires.
     *
     * @param event a org.atmosphere.cpr.AtmosphereResourceEvent
     */
    void onResume(AtmosphereResourceEvent event);

    /**
     * Invoked when the remote connection gets closed.
     *
     * @param event a org.atmosphere.cpr.AtmosphereResourceEvent
     */
    void onDisconnect(AtmosphereResourceEvent event);

    /**
     * Invoked when a Broadcaster#broadcast occurs.
     *
     * @param event a org.atmosphere.cpr.AtmosphereResourceEvent
     */
    void onBroadcast(AtmosphereResourceEvent event);

    /**
     * Invoked when an operations failed to execute for an unknown reason like : IOException because the client
     * remotely closed the connection, a broken connection, etc.
     *
     * @param event a org.atmosphere.cpr.AtmosphereResourceEvent
     */
    void onThrowable(AtmosphereResourceEvent event);

    /**
     * Invoked when AtmosphereResource#close is invoked.
     *
     * @param event a org.atmosphere.cpr.AtmosphereResourceEvent
     */
    void onClose(AtmosphereResourceEvent event);
}

to your AtmosphereResource by simply doing:

   atmosphereResource.addEventListener( new AtmosphereResourceEventListenerAdapter() {} );

If your application supports WebSocket, you can add a specialized WebSocketEventListener that will be invoked with more events:

public interface WebSocketEventListener extends AtmosphereResourceEventListener{

    /**
     * When the hanshake occurs
     * @param event WebSocketEvent
     */
    void onHandshake(WebSocketEvent event);

    /**
     * When a message is sent
     * @param event WebSocketEvent
     */
    void onMessage(WebSocketEvent event);

    /**
     * When the close occurs
     * @param event WebSocketEvent
     */
    void onClose(WebSocketEvent event);

    /**
     * When the control occurs
     * @param event WebSocketEvent
     */
    void onControl(WebSocketEvent event);

    /**
     * When the disconnect occurs
     * @param event WebSocketEvent
     */
    void onDisconnect(WebSocketEvent event);

     /**
     * When the connect occurs
     * @param event WebSocketEvent
     */
    void onConnect(WebSocketEvent event);
}

by doing

   atmosphereResource.addEventListener( new WebSocketEventListenerAdapter() {...} );

Using the @Suspend annotation or SuspendResponse

If you are using Atmosphere's Jersey module, you can add listeners by adding them using the @Suspend annotation:

   @Suspend(listeners="comma-separated list of classes that extend WebSocketEventListenerAdapter"

Or programmatically using the SuspendResponse API:

        return new SuspendResponse.SuspendResponseBuilder<String>()
                .addListener(new WebSocketEventListenerAdapter() {...} )
                .build();