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 }