org.atmosphere.cpr
Interface AtmosphereResource

All Superinterfaces:

AtmosphereEventLifecycle

All Known Implementing Classes:

AtmosphereResourceImpl

public interface AtmosphereResource
extends AtmosphereEventLifecycle

A AtmosphereResource encapsulates the mechanism to suspend(), resume() and broadcast (getBroadcaster()) messages among suspended response. AtmosphereResource are passed at runtime to an instance of AtmosphereHandler.

Author:

Jeanfrancois Arcand

Nested Class Summary

static class

AtmosphereResource.TRANSPORT

Method Summary

AtmosphereConfig	getAtmosphereConfig() Return the AtmosphereConfig
AtmosphereHandler	getAtmosphereHandler() Return the associated AtmosphereHandler associated with this resource.
AtmosphereResourceEvent	getAtmosphereResourceEvent() Return the current AtmosphereResourceEvent.
Broadcaster	getBroadcaster() Return the current Broadcaster
AtmosphereRequest	getRequest() Return the underlying AtmosphereRequest Request.
AtmosphereResponse	getResponse() Return the AtmosphereResponse
Serializer	getSerializer() Get the Serializer or null if not defined.
boolean	isCancelled() Return true if this object has been cancelled.
boolean	isResumed() Return true if this object has been resumed.
boolean	isSuspended() Return true is the suspend() has been invoked.
AtmosphereResource	resume() Complete the AtmosphereResponse and finish/commit it.
boolean	resumeOnBroadcast() Return the is the resumeOnBroadcast()
AtmosphereResource	resumeOnBroadcast(boolean resumeOnBroadcast) Set to true to resume the response once after the first broadcast.
AtmosphereResource	setBroadcaster(Broadcaster broadcaster) Set the current Broadcaster.
AtmosphereResource	setSerializer(Serializer s) Set the Serializer to use when write(java.io.OutputStream, java.lang.Object) execute the operation.
AtmosphereResource	suspend() Suspend the AtmosphereResponse indefinitely.
AtmosphereResource	suspend(long timeout) Suspend the AtmosphereResponse.
AtmosphereResource	suspend(long timeout, boolean flushComment) Suspend the AtmosphereResponse.
AtmosphereResource	suspend(long timeout, TimeUnit timeunit) Suspend the AtmosphereResponse.
AtmosphereResource	suspend(long timeout, TimeUnit timeunit, boolean flushComment) Suspend the AtmosphereResponse.
AtmosphereResource.TRANSPORT	transport() Return the current AtmosphereResource.TRANSPORT.
AtmosphereResource	write(OutputStream os, Object o) Write the Object using the OutputStream by invoking the current Serializer.
Object	writeOnTimeout() Return the object that will be written when the resource times out;
AtmosphereResource	writeOnTimeout(Object o) Set a message that will be written when the resource times out.

Methods inherited from interface org.atmosphere.cpr.AtmosphereEventLifecycle

addEventListener, notifyListeners, notifyListeners, removeEventListener, removeEventListeners

Method Detail

transport

AtmosphereResource.TRANSPORT transport()

Return the current AtmosphereResource.TRANSPORT. The transport value is retrieved using the HeaderConfig.X_ATMOSPHERE_TRANSPORT header value.

resumeOnBroadcast

AtmosphereResource resumeOnBroadcast(boolean resumeOnBroadcast)

Set to true to resume the response once after the first broadcast. False by default.

Parameters:

resumeOnBroadcast -

isSuspended

boolean isSuspended()

Return true is the suspend() has been invoked.

Returns:

true is the suspend() has been invoked.

resumeOnBroadcast

boolean resumeOnBroadcast()

Return the is the resumeOnBroadcast()

isResumed

boolean isResumed()

Return true if this object has been resumed.

Returns:

true if this object has been resumed.

isCancelled

boolean isCancelled()

Return true if this object has been cancelled.

Returns:

true if this object has been cancelled.

resume

AtmosphereResource resume()

Complete the AtmosphereResponse and finish/commit it. If the AtmosphereResponse is in the process of being resumed, invoking that method has no effect.

suspend

AtmosphereResource suspend()

Suspend the AtmosphereResponse indefinitely. Suspending a AtmosphereResponse will tell the underlying container to avoid recycling objects associated with the current instance, and also to avoid commiting response.

The Framework will output some HTML comments when suspending the response in order to make sure all Browser works well with suspended response.

suspend

AtmosphereResource suspend(long timeout)

Suspend the AtmosphereResponse. Suspending a AtmosphereResponse will tell the underlying container to avoid recycling objects associated with the current instance, and also to avoid commiting response. Invoking this method when a request is being timed out, e.g. AtmosphereResourceEvent.isResumedOnTimeout() return true, has no effect.

The Framework will output some HTML comments when suspending the response in order to make sure all Browser works well with suspended response. By default, the AtmosphereResponse.getWriter() will be used. You can change that behavior by setting a request attribute named org.atmosphere.useStream to so the framework will use AtmosphereResponse.getOutputStream()

Parameters:

timeout - The maximum amount of time, in milliseconds, a AtmosphereResponse can be suspended. When the timeout expires (because nothing has been written or because the resume() , the AtmosphereResponse will be automatically resumed and commited. Usage of any methods of a AtmosphereResponse that times out will throw an IllegalStateException.

suspend

AtmosphereResource suspend(long timeout,
                           TimeUnit timeunit)

Suspend the AtmosphereResponse. Suspending a AtmosphereResponse will tell the underlying container to avoid recycling objects associated with the current instance, and also to avoid commiting response. Invoking this method when a request is being timed out, e.g. AtmosphereResourceEvent.isResumedOnTimeout() return true, has no effect.

The Framework will output some HTML comments when suspending the response in order to make sure all Browser works well with suspended response. By default, the AtmosphereResponse.getWriter() will be used. You can change that behavior by setting a request attribute named org.atmosphere.useStream to so the framework will use AtmosphereResponse.getOutputStream()

Parameters:

timeout - The maximum amount of time, a AtmosphereResponse can be suspended. When the timeout expires (because nothing has been written or because the resume() , the AtmosphereResponse will be automatically resumed and commited. Usage of any methods of a AtmosphereResponse that times out will throw an IllegalStateException.

timeunit - The time unit of the timeout value

suspend

AtmosphereResource suspend(long timeout,
                           boolean flushComment)

Suspend the AtmosphereResponse. Suspending a AtmosphereResponse will tell the underlying container to avoid recycling objects associated with the current instance, and also to avoid commiting response. Invoking this method when a request is being timed out, e.g. AtmosphereResourceEvent.isResumedOnTimeout() return true, has no effect.

The Framework will output some HTML comments when suspending the response in order to make sure all Browser works well with suspended response. By default, the AtmosphereResponse.getWriter() will be used. You can change that behavior by setting a request attribute named org.atmosphere.useStream to so the framework will use AtmosphereResponse.getOutputStream()

Parameters:

timeout - The maximum amount of time, in milliseconds, a AtmosphereResponse can be suspended. When the timeout expires (because nothing has been written or because the resume() , the AtmosphereResponse will be automatically resumed and commited. Usage of any methods of a AtmosphereResponse that times out will throw an IllegalStateException.

flushComment - By default, Atmosphere will output some comments to make WebKit based browser working. Set it to false if you want to remove it.

suspend

AtmosphereResource suspend(long timeout,
                           TimeUnit timeunit,
                           boolean flushComment)

Suspend the AtmosphereResponse. Suspending a AtmosphereResponse will tell the underlying container to avoid recycling objects associated with the current instance, and also to avoid commiting response. Invoking this method when a request is being timed out, e.g. AtmosphereResourceEvent.isResumedOnTimeout() return true, has no effect.

The Framework will output some HTML comments when suspending the response in order to make sure all Browser works well with suspended response. By default, the AtmosphereResponse.getWriter() will be used. You can change that behavior by setting a request attribute named org.atmosphere.useStream to so the framework will use AtmosphereResponse.getOutputStream()

Parameters:

timeout - The maximum amount of time, in milliseconds, a AtmosphereResponse can be suspended. When the timeout expires (because nothing has been written or because the resume() , the AtmosphereResponse will be automatically resumed and commited. Usage of any methods of a AtmosphereResponse that times out will throw an IllegalStateException.

timeunit - The time unit of the timeout value

flushComment - By default, Atmosphere will output some comments to make WebKit based browser working. Set it to false if you want to remove it.

getRequest

AtmosphereRequest getRequest()

Return the underlying AtmosphereRequest Request.

Returns:

AtmosphereRequest the underlying Request.

getResponse

AtmosphereResponse getResponse()

Return the AtmosphereResponse

Returns:

AtmosphereResponse the underlying Response.

getAtmosphereConfig

AtmosphereConfig getAtmosphereConfig()

Return the AtmosphereConfig

Returns:

the AtmosphereConfig

getBroadcaster

Broadcaster getBroadcaster()

Return the current Broadcaster

Returns:

the current Broadcaster

setBroadcaster

AtmosphereResource setBroadcaster(Broadcaster broadcaster)

Set the current Broadcaster. If null, a new Broadcaster will be created with Broadcaster.SCOPE.REQUEST will be created if that resource hasn't been yet suspended.

Parameters:

broadcaster -

setSerializer

AtmosphereResource setSerializer(Serializer s)

Set the Serializer to use when write(java.io.OutputStream, java.lang.Object) execute the operation. By default, the Serializer is null.

Parameters:

s - the Serializer

write

AtmosphereResource write(OutputStream os,
                         Object o)
                         throws IOException

Write the Object using the OutputStream by invoking the current Serializer. If Serializer is null, the Object will be directly written using the {

Parameters:

os - OutputStream

o - Object

Throws:

IOException

getSerializer

Serializer getSerializer()

Get the Serializer or null if not defined.

Returns:

the Serializer or null if not defined.

getAtmosphereResourceEvent

AtmosphereResourceEvent getAtmosphereResourceEvent()

Return the current AtmosphereResourceEvent.

getAtmosphereHandler

AtmosphereHandler getAtmosphereHandler()

Return the associated AtmosphereHandler associated with this resource.

Returns:

the associated AtmosphereHandler associated with this resource.

writeOnTimeout

AtmosphereResource writeOnTimeout(Object o)

Set a message that will be written when the resource times out. Cab be an Object or Callable

writeOnTimeout

Object writeOnTimeout()

Return the object that will be written when the resource times out;