org.mortbay.util.ajax
Interface Continuation

All Known Implementing Classes:
SelectChannelConnector.RetryContinuation, WaitingContinuation

public interface Continuation

Continuation. A continuation is a mechanism by which a HTTP Request can be suspended and restarted after a timeout or an asynchronous event has occured. Blocking continuations will block the process of the request during a call to suspend(long). Non-blocking continuation can abort the current request and arrange for it to be retried when resume() is called or the timeout expires. In order to supprt non-blocking continuations, it is important that all actions taken by a filter or servlet before a call to suspend(long) are either idempotent (can be retried) or are made conditional on isPending() so they are not performed on retried requests. With the appropriate HTTP Connector, this allows threadless waiting for events (see SelectChannelConnector).

Author:
gregw

Method Summary
 Object getObject()
          Arbitrary object associated with the continuation for context.
 boolean isNew()
          Is this a newly created Continuation.
 boolean isPending()
          Get the pending status? A continuation is pending while the handling of a call to suspend has not completed.
 boolean isResumed()
          Get the resumed status?
 void reset()
          Reset the continuation.
 void resume()
          Resume the request.
 void setObject(Object o)
          Arbitrary object associated with the continuation for context.
 boolean suspend(long timeout)
          Suspend handling.
 

Method Detail

suspend

boolean suspend(long timeout)
Suspend handling. This method will suspend the request for the timeout or until resume is called.

Parameters:
timeout. - A timeout of < 0 will cause an immediate return. I timeout of 0 will wait indefinitely.
Returns:
True if resume called or false if timeout.

resume

void resume()
Resume the request. Resume a suspended request. The passed event will be returned in the getObject method.


reset

void reset()
Reset the continuation. Cancel any pending status of the continuation.


isNew

boolean isNew()
Is this a newly created Continuation.

A newly created continuation has not had #getEvent(long) called on it.

Returns:
True if the continuation has just been created and has not yet suspended the request.

isPending

boolean isPending()
Get the pending status? A continuation is pending while the handling of a call to suspend has not completed. For blocking continuations, pending is true only during the call to suspend(long). For non-blocking continuations, pending is true until a second call to suspend(long), thus this method can be used to determine if a request is being retried.

Returns:
True if the continuation is handling a call to suspend.

isResumed

boolean isResumed()
Get the resumed status?

Returns:
True if the continuation is has been resumed.

getObject

Object getObject()
Arbitrary object associated with the continuation for context.

Returns:
An arbitrary object associated with the continuation

setObject

void setObject(Object o)
Arbitrary object associated with the continuation for context.

Parameters:
o - An arbitrary object to associate with the continuation