org.atmosphere.cpr

Interface AtmosphereResource

All Known Implementing Classes:

AtmosphereResourceImpl

public interface AtmosphereResource

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

Author:

Jeanfrancois Arcand

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	AtmosphereResource.TRANSPORT

Method Summary

Methods

Modifier and Type	Method and Description
AtmosphereResource	addEventListener(AtmosphereResourceEventListener e) Add a AtmosphereResourceEventListener.
void	close() Close the underlying connection.
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 if the suspend() has been invoked.
AtmosphereResource	notifyListeners() Notify all AtmosphereResourceEventListeners.
AtmosphereResource	notifyListeners(AtmosphereResourceEvent e) Notify all AtmosphereResourceEventListener.
AtmosphereResource	removeEventListener(AtmosphereResourceEventListener e) Remove a AtmosphereResourceEventListener.
AtmosphereResource	removeEventListeners() Remove all AtmosphereResourceEventListeners.
AtmosphereResource	resume() Complete the AtmosphereResponse and finish/commit it.
boolean	resumeOnBroadcast() Return true if this AtmosphereResource is resumed after the first broadcast.
AtmosphereResource	resumeOnBroadcast(boolean resumeOnBroadcast) Set to true to resume the response after the first broadcast.
javax.servlet.http.HttpSession	session() Return the HttpSession if supported, null if not
javax.servlet.http.HttpSession	session(boolean create) Return the HttpSession if supported, and creates it if not already created.
AtmosphereResource	setBroadcaster(Broadcaster broadcaster) Set the current Broadcaster.
AtmosphereResource	setSerializer(Serializer s) Set the Serializer to use when write(java.lang.String) execute the operation.
AtmosphereResource	suspend() Suspend the AtmosphereResponse indefinitely.
AtmosphereResource	suspend(long timeout) Suspend the AtmosphereResponse.
AtmosphereResource	suspend(long timeout, java.util.concurrent.TimeUnit timeunit) Suspend the AtmosphereResponse.
AtmosphereResource.TRANSPORT	transport() Return the current AtmosphereResource.TRANSPORT.
java.lang.String	uuid() Return the unique ID associated with this AtmosphereResource.
AtmosphereResource	write(byte[] s) Write the bytes If resumeOnBroadcast() is true, the underlying connection will be resumed (@link #resume());
AtmosphereResource	write(java.lang.String s) Write the String.
java.lang.Object	writeOnTimeout() Return the object that will be written when the resource times out.
AtmosphereResource	writeOnTimeout(java.lang.Object o) Set a message that will be written when the resource times out.

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 after the first broadcast. False by default.

Parameters:

resumeOnBroadcast -

isSuspended

boolean isSuspended()

Return true if the suspend() has been invoked.

Returns:

true if the suspend() has been invoked

resumeOnBroadcast

boolean resumeOnBroadcast()

Return true if this AtmosphereResource is resumed after the first broadcast.

See Also:

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 this 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 committing a response.

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

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 committing response. Invoking this method when a request is being timed out (e.g. AtmosphereResourceEvent.isResumedOnTimeout() returns true) has no effect.

The Framework will output some HTML comments when suspending the response in order to make sure all browsers work well with suspended responses. By default, the AtmosphereResponse.getWriter() will be used. You can change that behavior by setting a request attribute named org.atmosphere.useStream 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, the AtmosphereResponse will be automatically resumed and committed. Usage of any methods of a AtmosphereResponse that times out will throw an IllegalStateException.

suspend

AtmosphereResource suspend(long timeout,
                         java.util.concurrent.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 committing response. Invoking this method when a request is being timed out (e.g. AtmosphereResourceEvent.isResumedOnTimeout() returns true) has no effect.

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

Parameters:

timeout - The maximum amount of time a AtmosphereResponse can be suspended. When the timeout expires, the AtmosphereResponse will be automatically resumed and committed. Usage of any methods of a AtmosphereResponse that times out will throw an IllegalStateException.

timeunit - The time unit of the timeout value

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 if that resource hasn't been suspended yet.

Parameters:

broadcaster -

Returns:

this

setSerializer

AtmosphereResource setSerializer(Serializer s)

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

Parameters:

s - the Serializer

Returns:

this

write

AtmosphereResource write(java.lang.String s)

Write the String. If resumeOnBroadcast() is true, the underlying connection will be resumed (@link #resume());

Parameters:

s -

Returns:

this

write

AtmosphereResource write(byte[] s)

Write the bytes If resumeOnBroadcast() is true, the underlying connection will be resumed (@link #resume());

Parameters:

s -

Returns:

this

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(java.lang.Object o)

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

Returns:

this

writeOnTimeout

java.lang.Object writeOnTimeout()

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

uuid

java.lang.String uuid()

Return the unique ID associated with this AtmosphereResource.

Returns:

the unique ID associated with this AtmosphereResource

addEventListener

AtmosphereResource addEventListener(AtmosphereResourceEventListener e)

Add a AtmosphereResourceEventListener.

Parameters:

e - an instance of AtmosphereResourceEventListener

Returns:

this

removeEventListener

AtmosphereResource removeEventListener(AtmosphereResourceEventListener e)

Remove a AtmosphereResourceEventListener.

Parameters:

e -

Returns:

this

removeEventListeners

AtmosphereResource removeEventListeners()

Remove all AtmosphereResourceEventListeners.

Returns:

this

notifyListeners

AtmosphereResource notifyListeners(AtmosphereResourceEvent e)

Notify all AtmosphereResourceEventListener.

Parameters:

e - an instance of AtmosphereResourceEvent

Returns:

this

notifyListeners

AtmosphereResource notifyListeners()

Notify all AtmosphereResourceEventListeners.

Returns:

this

session

javax.servlet.http.HttpSession session()

Return the HttpSession if supported, null if not

Returns:

the HttpSession if supported, null if not

session

javax.servlet.http.HttpSession session(boolean create)

Return the HttpSession if supported, and creates it if not already created.

Returns:

the HttpSession if supported, and creates it if not already created

close

void close()
           throws java.io.IOException

Close the underlying connection. Invoking this method will close the underlying connection and resume the AtmosphereResource}.

Throws:

java.io.IOException