org.mortbay.util.ajax.Continuation Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of jetty-util Show documentation
Utility classes for Jetty
There is a newer version: 7.0.0.pre5
//========================================================================
//$Id: Continuation.java,v 1.1 2005/11/14 17:45:56 gregwilkins Exp $
//Copyright 2004-2005 Mort Bay Consulting Pty. Ltd.
//------------------------------------------------------------------------
//Licensed under the Apache License, Version 2.0 (the "License");
//you may not use this file except in compliance with the License.
//You may obtain a copy of the License at 
//http://www.apache.org/licenses/LICENSE-2.0
//Unless required by applicable law or agreed to in writing, software
//distributed under the License is distributed on an "AS IS" BASIS,
//WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//See the License for the specific language governing permissions and
//limitations under the License.
//========================================================================

package org.mortbay.util.ajax;


/* ------------------------------------------------------------ */
/** 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 {@link #suspend(long)}.
 * Non-blocking continuation can abort the current request and arrange for it 
 * to be retried when {@link #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 
 * {@link #suspend(long)} are either idempotent (can be retried) or
 * are made conditional on {@link #isPending} so they are not performed on 
 * retried requests.
 * 
 * With the appropriate HTTP Connector, this allows threadless waiting
 * for events (see {@link org.mortbay.jetty.nio.SelectChannelConnector}).
 * 
 * @author gregw
 *
 */
public interface Continuation
{

    /* ------------------------------------------------------------ */
    /** Suspend handling.
     * This method will suspend the request for the timeout or until resume is
     * called.
     * @param timeout. A timeout of < 0 will cause an immediate return. I timeout of 0 will wait indefinitely.
     * @return True if resume called or false if timeout.
     */
    public boolean suspend(long timeout);
    
    /* ------------------------------------------------------------ */
    /** Resume the request.
     * Resume a suspended request.  The passed event will be returned in the getObject method.
     */
    public void resume();
    

    /* ------------------------------------------------------------ */
    /** Reset the continuation.
     * Cancel any pending status of the continuation.
     */
    public void reset();
    
    /* ------------------------------------------------------------ */
    /** Is this a newly created Continuation.
     * 
     * A newly created continuation has not had {@link #getEvent(long)} called on it.
     * 
     * @return True if the continuation has just been created and has not yet suspended the request.
     */
    public boolean isNew();
    
    /* ------------------------------------------------------------ */
    /** 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 {@link #suspend(long)}.
     * For non-blocking continuations, pending is true until a second call to {@link #suspend(long)}, 
     * thus this method can be used to determine if a request is being retried.
     * @return True if the continuation is handling a call to suspend.
     */
    public boolean isPending();
    
    /* ------------------------------------------------------------ */
    /** Get the resumed status?
     * @return True if the continuation is has been resumed.
     */
    public boolean isResumed();
    
    /* ------------------------------------------------------------ */
    /** Arbitrary object associated with the continuation for context.
     * @return An arbitrary object associated with the continuation
     */
    public Object getObject();
    
    /* ------------------------------------------------------------ */
    /** Arbitrary object associated with the continuation for context.
     * @param o An arbitrary object to associate with the continuation
     */
    public void setObject(Object o);
    
}