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 }