View Javadoc

    1   //========================================================================
    2   //$Id: Continuation.java,v 1.1 2005/11/14 17:45:56 gregwilkins Exp $
    3   //Copyright 2004-2005 Mort Bay Consulting Pty. Ltd.
    4   //------------------------------------------------------------------------
    5   //Licensed under the Apache License, Version 2.0 (the "License");
    6   //you may not use this file except in compliance with the License.
    7   //You may obtain a copy of the License at
    8   //http://www.apache.org/licenses/LICENSE-2.0
    9   //Unless required by applicable law or agreed to in writing, software
    10  //distributed under the License is distributed on an "AS IS" BASIS,
    11  //WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  //See the License for the specific language governing permissions and
    13  //limitations under the License.
    14  //========================================================================
    15
    16  package org.mortbay.util.ajax;
    17
    18
    19  /* ------------------------------------------------------------ */
    20  /** Continuation.
    21   *
    22   * A continuation is a mechanism by which a HTTP Request can be
    23   * suspended and restarted after a timeout or an asynchronous event
    24   * has occured.
    25   * Blocking continuations will block the process of the request during a
    26   * call to {@link #suspend(long)}.
    27   * Non-blocking continuation can abort the current request and arrange for it
    28   * to be retried when {@link #resume()} is called or the timeout expires.
    29   *
    30   * In order to supprt non-blocking continuations, it is important that
    31   * all actions taken by a filter or servlet before a call to
    32   * {@link #suspend(long)} are either idempotent (can be retried) or
    33   * are made conditional on {@link #isPending} so they are not performed on
    34   * retried requests.
    35   *
    36   * With the appropriate HTTP Connector, this allows threadless waiting
    37   * for events (see {@link org.mortbay.jetty.nio.SelectChannelConnector}).
    38   *
    39   * @author gregw
    40   *
    41   */
    42  public interface Continuation
    43  {
    44
    45      /* ------------------------------------------------------------ */
    46      /** Suspend handling.
    47       * This method will suspend the request for the timeout or until resume is
    48       * called.
    49       * @param timeout. A timeout of < 0 will cause an immediate return. I timeout of 0 will wait indefinitely.
    50       * @return True if resume called or false if timeout.
    51       */
    52      public boolean suspend(long timeout);
    53
    54      /* ------------------------------------------------------------ */
    55      /** Resume the request.
    56       * Resume a suspended request.  The passed event will be returned in the getObject method.
    57       */
    58      public void resume();
    59
    60
    61      /* ------------------------------------------------------------ */
    62      /** Reset the continuation.
    63       * Cancel any pending status of the continuation.
    64       */
    65      public void reset();
    66
    67      /* ------------------------------------------------------------ */
    68      /** Is this a newly created Continuation.
    69       * <p>
    70       * A newly created continuation has not had {@link #getEvent(long)} called on it.
    71       * </p>
    72       * @return True if the continuation has just been created and has not yet suspended the request.
    73       */
    74      public boolean isNew();
    75
    76      /* ------------------------------------------------------------ */
    77      /** Get the pending status?
    78       * A continuation is pending while the handling of a call to suspend has not completed.
    79       * For blocking continuations, pending is true only during the call to {@link #suspend(long)}.
    80       * For non-blocking continuations, pending is true until a second call to {@link #suspend(long)},
    81       * thus this method can be used to determine if a request is being retried.
    82       * @return True if the continuation is handling a call to suspend.
    83       */
    84      public boolean isPending();
    85
    86      /* ------------------------------------------------------------ */
    87      /** Get the resumed status?
    88       * @return True if the continuation is has been resumed.
    89       */
    90      public boolean isResumed();
    91
    92      /* ------------------------------------------------------------ */
    93      /** Arbitrary object associated with the continuation for context.
    94       * @return An arbitrary object associated with the continuation
    95       */
    96      public Object getObject();
    97
    98      /* ------------------------------------------------------------ */
    99      /** Arbitrary object associated with the continuation for context.
    100      * @param o An arbitrary object to associate with the continuation
    101      */
    102     public void setObject(Object o);
    103
    104 }