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 }