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 }