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  import javax.servlet.ServletRequest;
19  
20  
21  /* ------------------------------------------------------------ */
22  /** Continuation.
23   * 
24   * A continuation is a mechanism by which a HTTP Request can be 
25   * suspended and restarted after a timeout or an asynchronous event
26   * has occured.
27   * Blocking continuations will block the process of the request during a
28   * call to {@link #suspend(long)}.
29   * Non-blocking continuation can abort the current request and arrange for it 
30   * to be retried when {@link #resume()} is called or the timeout expires.
31   * 
32   * In order to supprt non-blocking continuations, it is important that
33   * all actions taken by a filter or servlet before a call to 
34   * {@link #suspend(long)} are either idempotent (can be retried) or
35   * are made conditional on {@link #isPending} so they are not performed on 
36   * retried requests.
37   * 
38   * With the appropriate HTTP Connector, this allows threadless waiting
39   * for events (see {@link org.mortbay.jetty.nio.SelectChannelConnector}).
40   * 
41   * @author gregw
42   * @deprecated use {@link ServletRequest#suspend()}
43   *
44   */
45  public interface Continuation
46  {
47  
48      /* ------------------------------------------------------------ */
49      /** Suspend handling.
50       * This method will suspend the request for the timeout or until resume is
51       * called.
52       * @param timeout. A timeout of < 0 will cause an immediate return. I timeout of 0 will wait indefinitely.
53       * @return True if resume called or false if timeout.
54       */
55      public boolean suspend(long timeout);
56      
57      /* ------------------------------------------------------------ */
58      /** Resume the request.
59       * Resume a suspended request.  The passed event will be returned in the getObject method.
60       */
61      public void resume();
62      
63  
64      /* ------------------------------------------------------------ */
65      /** Reset the continuation.
66       * Cancel any pending status of the continuation.
67       */
68      public void reset();
69      
70      /* ------------------------------------------------------------ */
71      /** Is this a newly created Continuation.
72       * <p>
73       * A newly created continuation has not had {@link #getEvent(long)} called on it.
74       * </p>
75       * @return True if the continuation has just been created and has not yet suspended the request.
76       */
77      public boolean isNew();
78      
79      /* ------------------------------------------------------------ */
80      /** Get the pending status?
81       * A continuation is pending while the handling of a call to suspend has not completed.
82       * For blocking continuations, pending is true only during the call to {@link #suspend(long)}.
83       * For non-blocking continuations, pending is true until a second call to {@link #suspend(long)} or 
84       * a call to {@link #reset()}, thus this method can be used to determine if a request is being 
85       * retried.
86       * @return True if the continuation is handling a call to suspend.
87       */
88      public boolean isPending();
89      
90      /* ------------------------------------------------------------ */
91      /** Get the resumed status?
92       * @return True if the continuation is has been resumed.
93       */
94      public boolean isResumed();
95  
96      /* ------------------------------------------------------------ */
97      /** Get the resumed status?
98       * @return True if the continuation is has been expired.
99       */
100     public boolean isExpired();
101     
102     /* ------------------------------------------------------------ */
103     /** Arbitrary object associated with the continuation for context.
104      * @return An arbitrary object associated with the continuation
105      */
106     public Object getObject();
107     
108     /* ------------------------------------------------------------ */
109     /** Arbitrary object associated with the continuation for context.
110      * @param o An arbitrary object to associate with the continuation
111      */
112     public void setObject(Object o);
113     
114     /* ------------------------------------------------------------ */
115     /** 
116      */
117     public void setMutex(Object mutex);
118     
119 }