org.atmosphere.cpr
Interface AtmosphereResource

All Known Implementing Classes:

AtmosphereResourceImpl

public interface AtmosphereResource

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

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 is the suspend() has been invoked.
AtmosphereResource	notifyListeners() Notify All AtmosphereResourceEventListener.
AtmosphereResource	notifyListeners(AtmosphereResourceEvent e) Notify AtmosphereResourceEventListener.
AtmosphereResource	removeEventListener(AtmosphereResourceEventListener e) Remove aAtmosphereResourceEventListener.
AtmosphereResource	removeEventListeners() Remove all AtmosphereResourceEventListener.
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.
javax.servlet.http.HttpSession	session() Return the HttpSession is supported, null if not
javax.servlet.http.HttpSession	session(boolean create) Return the HttpSession is 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, TimeUnit timeunit) Suspend the AtmosphereResponse.
AtmosphereResource.TRANSPORT	transport() Return the current AtmosphereResource.TRANSPORT.
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(String s) Write the String.
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.

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, 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,
                           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, 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.

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

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

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

Returns:

this

writeOnTimeout

Object writeOnTimeout()

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

uuid

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 aAtmosphereResourceEventListener.

Parameters:

e -

Returns:

this

removeEventListeners

AtmosphereResource removeEventListeners()

Remove all AtmosphereResourceEventListener.

Returns:

this

notifyListeners

AtmosphereResource notifyListeners(AtmosphereResourceEvent e)

Notify AtmosphereResourceEventListener.

Parameters:

e - an instance of AtmosphereResourceEvent

Returns:

this

notifyListeners

AtmosphereResource notifyListeners()

Notify All AtmosphereResourceEventListener.

Returns:

this

session

javax.servlet.http.HttpSession session()

Return the HttpSession is supported, null if not

Returns:

the HttpSession is supported, null if not

session

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

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

Returns:

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

close

void close()
           throws IOException

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

Throws:

IOException