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
static class AtmosphereResource.TRANSPORT
           
 
Method Summary
 AtmosphereResource addEventListener(AtmosphereResourceEventListener e)
          Add a AtmosphereResourceEventListener.
 void close()
          Close the underlying connection.
 boolean forceBinaryWrite()
          Return true when binary write is forced.
 AtmosphereResource forceBinaryWrite(boolean force)
          Force binary write and never write String value.
 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.
 AtmosphereResource initialize(AtmosphereConfig config, Broadcaster broadcaster, AtmosphereRequest req, AtmosphereResponse response, AsyncSupport asyncSupport, AtmosphereHandler atmosphereHandler)
          Initialize an AtmosphereResource.
 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, 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 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,
                           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(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. Can 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 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 IOException
Close the underlying connection. Invoking this method will close the underlying connection and resume the AtmosphereResource}.

Throws:
IOException

forceBinaryWrite

AtmosphereResource forceBinaryWrite(boolean force)
Force binary write and never write String value. return this


forceBinaryWrite

boolean forceBinaryWrite()
Return true when binary write is forced.

Returns:
true when binary write is forced.

initialize

AtmosphereResource initialize(AtmosphereConfig config,
                              Broadcaster broadcaster,
                              AtmosphereRequest req,
                              AtmosphereResponse response,
                              AsyncSupport asyncSupport,
                              AtmosphereHandler atmosphereHandler)
Initialize an AtmosphereResource.

Parameters:
config - The AtmosphereConfig
broadcaster - The Broadcaster.
req - The AtmosphereRequest
response - The AtmosphereResource
asyncSupport - The AsyncSupport
atmosphereHandler - The AtmosphereHandler
Returns:
this


Copyright © 2014. All Rights Reserved.