001: //========================================================================
002: //$Id: Continuation.java,v 1.1 2005/11/14 17:45:56 gregwilkins Exp $
003: //Copyright 2004-2005 Mort Bay Consulting Pty. Ltd.
004: //------------------------------------------------------------------------
005: //Licensed under the Apache License, Version 2.0 (the "License");
006: //you may not use this file except in compliance with the License.
007: //You may obtain a copy of the License at
008: //http://www.apache.org/licenses/LICENSE-2.0
009: //Unless required by applicable law or agreed to in writing, software
010: //distributed under the License is distributed on an "AS IS" BASIS,
011: //WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012: //See the License for the specific language governing permissions and
013: //limitations under the License.
014: //========================================================================
015:
016: package org.mortbay.util.ajax;
017:
018: /* ------------------------------------------------------------ */
019: /** Continuation.
020: *
021: * A continuation is a mechanism by which a HTTP Request can be
022: * suspended and restarted after a timeout or an asynchronous event
023: * has occured.
024: * Blocking continuations will block the process of the request during a
025: * call to {@link #suspend(long)}.
026: * Non-blocking continuation can abort the current request and arrange for it
027: * to be retried when {@link #resume()} is called or the timeout expires.
028: *
029: * In order to supprt non-blocking continuations, it is important that
030: * all actions taken by a filter or servlet before a call to
031: * {@link #suspend(long)} are either idempotent (can be retried) or
032: * are made conditional on {@link #isPending} so they are not performed on
033: * retried requests.
034: *
035: * With the appropriate HTTP Connector, this allows threadless waiting
036: * for events (see {@link org.mortbay.jetty.nio.SelectChannelConnector}).
037: *
038: * @author gregw
039: *
040: */
041: public interface Continuation {
042:
043: /* ------------------------------------------------------------ */
044: /** Suspend handling.
045: * This method will suspend the request for the timeout or until resume is
046: * called.
047: * @param timeout. A timeout of < 0 will cause an immediate return. I timeout of 0 will wait indefinitely.
048: * @return True if resume called or false if timeout.
049: */
050: public boolean suspend(long timeout);
051:
052: /* ------------------------------------------------------------ */
053: /** Resume the request.
054: * Resume a suspended request. The passed event will be returned in the getObject method.
055: */
056: public void resume();
057:
058: /* ------------------------------------------------------------ */
059: /** Reset the continuation.
060: * Cancel any pending status of the continuation.
061: */
062: public void reset();
063:
064: /* ------------------------------------------------------------ */
065: /** Is this a newly created Continuation.
066: * <p>
067: * A newly created continuation has not had {@link #getEvent(long)} called on it.
068: * </p>
069: * @return True if the continuation has just been created and has not yet suspended the request.
070: */
071: public boolean isNew();
072:
073: /* ------------------------------------------------------------ */
074: /** Get the pending status?
075: * A continuation is pending while the handling of a call to suspend has not completed.
076: * For blocking continuations, pending is true only during the call to {@link #suspend(long)}.
077: * For non-blocking continuations, pending is true until a second call to {@link #suspend(long)},
078: * thus this method can be used to determine if a request is being retried.
079: * @return True if the continuation is handling a call to suspend.
080: */
081: public boolean isPending();
082:
083: /* ------------------------------------------------------------ */
084: /** Get the resumed status?
085: * @return True if the continuation is has been resumed.
086: */
087: public boolean isResumed();
088:
089: /* ------------------------------------------------------------ */
090: /** Arbitrary object associated with the continuation for context.
091: * @return An arbitrary object associated with the continuation
092: */
093: public Object getObject();
094:
095: /* ------------------------------------------------------------ */
096: /** Arbitrary object associated with the continuation for context.
097: * @param o An arbitrary object to associate with the continuation
098: */
099: public void setObject(Object o);
100:
101: }
|