| // |
| // ======================================================================== |
| // Copyright (c) 1995-2014 Mort Bay Consulting Pty. Ltd. |
| // ------------------------------------------------------------------------ |
| // All rights reserved. This program and the accompanying materials |
| // are made available under the terms of the Eclipse Public License v1.0 |
| // and Apache License v2.0 which accompanies this distribution. |
| // |
| // The Eclipse Public License is available at |
| // http://www.eclipse.org/legal/epl-v10.html |
| // |
| // The Apache License v2.0 is available at |
| // http://www.opensource.org/licenses/apache2.0.php |
| // |
| // You may elect to redistribute this code under either of these licenses. |
| // ======================================================================== |
| // |
| |
| package org.eclipse.jetty.continuation; |
| |
| import javax.servlet.Filter; |
| import javax.servlet.FilterChain; |
| import javax.servlet.Servlet; |
| import javax.servlet.ServletRequest; |
| import javax.servlet.ServletResponse; |
| import javax.servlet.ServletResponseWrapper; |
| |
| /* ------------------------------------------------------------ */ |
| /** |
| * Continuation. |
| * |
| * A continuation is a mechanism by which a HTTP Request can be suspended and |
| * restarted after a timeout or an asynchronous event has occurred. |
| * <p> |
| * The continuation mechanism is a portable mechanism that will work |
| * asynchronously without additional configuration of all jetty-7, |
| * jetty-8 and Servlet 3.0 containers. With the addition of |
| * the {@link ContinuationFilter}, the mechanism will also work |
| * asynchronously on jetty-6 and non-asynchronously on any |
| * servlet 2.5 container. |
| * <p> |
| * The Continuation API is a simplification of the richer async API |
| * provided by the servlet-3.0 and an enhancement of the continuation |
| * API that was introduced with jetty-6. |
| * </p> |
| * <h1>Continuation Usage</h1> |
| * <p> |
| * A continuation object is obtained for a request by calling the |
| * factory method {@link ContinuationSupport#getContinuation(ServletRequest)}. |
| * The continuation type returned will depend on the servlet container |
| * being used. |
| * </p> |
| * <p> |
| * There are two distinct style of operation of the continuation API. |
| * </p> |
| * <h3>Suspend/Resume Usage</h3> |
| * <p>The suspend/resume style is used when a servlet and/or |
| * filter is used to generate the response after a asynchronous wait that is |
| * terminated by an asynchronous handler. |
| * </p> |
| * <pre> |
| * <b>Filter/Servlet:</b> |
| * // if we need to get asynchronous results |
| * Object results = request.getAttribute("results); |
| * if (results==null) |
| * { |
| * Continuation continuation = ContinuationSupport.getContinuation(request); |
| * continuation.suspend(); |
| * myAsyncHandler.register(continuation); |
| * return; // or continuation.undispatch(); |
| * } |
| * |
| * async wait ... |
| * |
| * <b>Async Handler:</b> |
| * // when the waited for event happens |
| * continuation.setAttribute("results",event); |
| * continuation.resume(); |
| * |
| * <b>Filter/Servlet:</b> |
| * // when the request is redispatched |
| * if (results==null) |
| * { |
| * ... // see above |
| * } |
| * else |
| * { |
| * response.getOutputStream().write(process(results)); |
| * } |
| * </pre> |
| * <h3>Suspend/Complete Usage</h3> |
| * <p> |
| * The suspend/complete style is used when an asynchronous handler is used to |
| * generate the response: |
| * </p> |
| * <pre> |
| * <b>Filter/Servlet:</b> |
| * // when we want to enter asynchronous mode |
| * Continuation continuation = ContinuationSupport.getContinuation(request); |
| * continuation.suspend(response); // response may be wrapped |
| * myAsyncHandler.register(continuation); |
| * return; // or continuation.undispatch(); |
| * |
| * <b>Wrapping Filter:</b> |
| * // any filter that had wrapped the response should be implemented like: |
| * try |
| * { |
| * chain.doFilter(request,wrappedResponse); |
| * } |
| * finally |
| * { |
| * if (!continuation.isResponseWrapped()) |
| * wrappedResponse.finish() |
| * else |
| * continuation.addContinuationListener(myCompleteListener) |
| * } |
| * |
| * async wait ... |
| * |
| * <b>Async Handler:</b> |
| * // when the async event happens |
| * continuation.getServletResponse().getOutputStream().write(process(event)); |
| * continuation.complete() |
| * </pre> |
| * |
| * <h1>Continuation Timeout</h1> |
| * <p> |
| * If a continuation is suspended, but neither {@link #complete()} or {@link #resume()} is |
| * called during the period set by {@link #setTimeout(long)}, then the continuation will |
| * expire and {@link #isExpired()} will return true. |
| * </p> |
| * <p> |
| * When a continuation expires, the {@link ContinuationListener#onTimeout(Continuation)} |
| * method is called on any {@link ContinuationListener} that has been registered via the |
| * {@link #addContinuationListener(ContinuationListener)} method. The onTimeout handlers |
| * may write a response and call {@link #complete()}. If {@link #complete()} is not called, |
| * then the container will redispatch the request as if {@link #resume()} had been called, |
| * except that {@link #isExpired()} will be true and {@link #isResumed()} will be false. |
| * </p> |
| * |
| * @see ContinuationSupport |
| * @see ContinuationListener |
| * |
| */ |
| public interface Continuation |
| { |
| public final static String ATTRIBUTE = "org.eclipse.jetty.continuation"; |
| |
| /* ------------------------------------------------------------ */ |
| /** |
| * Set the continuation timeout. |
| * |
| * @param timeoutMs |
| * The time in milliseconds to wait before expiring this |
| * continuation after a call to {@link #suspend()} or {@link #suspend(ServletResponse)}. |
| * A timeout of <=0 means the continuation will never expire. |
| */ |
| void setTimeout(long timeoutMs); |
| |
| /* ------------------------------------------------------------ */ |
| /** |
| * Suspend the processing of the request and associated |
| * {@link ServletResponse}. |
| * |
| * <p> |
| * After this method has been called, the lifecycle of the request will be |
| * extended beyond the return to the container from the |
| * {@link Servlet#service(ServletRequest, ServletResponse)} method and |
| * {@link Filter#doFilter(ServletRequest, ServletResponse, FilterChain)} |
| * calls. When a suspended request is returned to the container after |
| * a dispatch, then the container will not commit the associated response |
| * (unless an exception other than {@link ContinuationThrowable} is thrown). |
| * </p> |
| * |
| * <p> |
| * When the thread calling the filter chain and/or servlet has returned to |
| * the container with a suspended request, the thread is freed for other |
| * tasks and the request is held until either: |
| * <ul> |
| * <li>a call to {@link #resume()}.</li> |
| * <li>a call to {@link #complete()}.</li> |
| * <li>the timeout expires.</li> |
| * </ul> |
| * <p> |
| * Typically suspend with no arguments is uses when a call to {@link #resume()} |
| * is expected. If a call to {@link #complete()} is expected, then the |
| * {@link #suspend(ServletResponse)} method should be used instead of this method. |
| * </p> |
| * |
| * @exception IllegalStateException |
| * If the request cannot be suspended |
| */ |
| void suspend(); |
| |
| |
| /* ------------------------------------------------------------ */ |
| /** |
| * Suspend the processing of the request and associated |
| * {@link ServletResponse}. |
| * |
| * <p> |
| * After this method has been called, the lifecycle of the request will be |
| * extended beyond the return to the container from the |
| * {@link Servlet#service(ServletRequest, ServletResponse)} method and |
| * {@link Filter#doFilter(ServletRequest, ServletResponse, FilterChain)} |
| * calls. When a suspended request is returned to the container after |
| * a dispatch, then the container will not commit the associated response |
| * (unless an exception other than {@link ContinuationThrowable} is thrown). |
| * </p> |
| * <p> |
| * When the thread calling the filter chain and/or servlet has returned to |
| * the container with a suspended request, the thread is freed for other |
| * tasks and the request is held until either: |
| * <ul> |
| * <li>a call to {@link #resume()}.</li> |
| * <li>a call to {@link #complete()}.</li> |
| * <li>the timeout expires.</li> |
| * </ul> |
| * <p> |
| * Typically suspend with a response argument is uses when a call to {@link #complete()} |
| * is expected. If a call to {@link #resume()} is expected, then the |
| * {@link #suspend()} method should be used instead of this method. |
| * </p> |
| * <p> |
| * Filters that may wrap the response object should check {@link #isResponseWrapped()} |
| * to decide if they should destroy/finish the wrapper. If {@link #isResponseWrapped()} |
| * returns true, then the wrapped request has been passed to the asynchronous |
| * handler and the wrapper should not be destroyed/finished until after a call to |
| * {@link #complete()} (potentially using a {@link ContinuationListener#onComplete(Continuation)} |
| * listener). |
| * |
| * @param response The response to return via a call to {@link #getServletResponse()} |
| * @exception IllegalStateException |
| * If the request cannot be suspended |
| */ |
| void suspend(ServletResponse response); |
| |
| /* ------------------------------------------------------------ */ |
| /** |
| * Resume a suspended request. |
| * |
| * <p> |
| * This method can be called by any thread that has been passed a reference |
| * to a continuation. When called the request is redispatched to the |
| * normal filter chain and servlet processing with {@link #isInitial()} false. |
| * </p> |
| * <p> |
| * If resume is called before a suspended request is returned to the |
| * container (ie the thread that called {@link #suspend()} is still |
| * within the filter chain and/or servlet service method), then the resume |
| * does not take effect until the call to the filter chain and/or servlet |
| * returns to the container. In this case both {@link #isSuspended()} and |
| * {@link #isResumed()} return true. Multiple calls to resume are ignored. |
| * </p> |
| * <p> |
| * Typically resume() is used after a call to {@link #suspend()} with |
| * no arguments. The dispatch after a resume call will use the original |
| * request and response objects, even if {@link #suspend(ServletResponse)} |
| * had been passed a wrapped response. |
| * </p> |
| * |
| * @see #suspend() |
| * @exception IllegalStateException if the request is not suspended. |
| * |
| */ |
| void resume(); |
| |
| /* ------------------------------------------------------------ */ |
| /** |
| * Complete a suspended request. |
| * |
| * <p> |
| * This method can be called by any thread that has been passed a reference |
| * to a suspended request. When a request is completed, the associated |
| * response object committed and flushed. The request is not redispatched. |
| * </p> |
| * |
| * <p> |
| * If complete is called before a suspended request is returned to the |
| * container (ie the thread that called {@link #suspend()} is still |
| * within the filter chain and/or servlet service method), then the complete |
| * does not take effect until the call to the filter chain and/or servlet |
| * returns to the container. In this case both {@link #isSuspended()} and |
| * {@link #isResumed()} return true. |
| * </p> |
| * |
| * <p> |
| * Typically resume() is used after a call to {@link #suspend(ServletResponse)} with |
| * a possibly wrapped response. The async handler should use the response |
| * provided by {@link #getServletResponse()} to write the response before |
| * calling {@link #complete()}. If the request was suspended with a |
| * call to {@link #suspend()} then no response object will be available via |
| * {@link #getServletResponse()}. |
| * </p> |
| * |
| * <p> |
| * Once complete has been called and any thread calling the filter chain |
| * and/or servlet chain has returned to the container, the request lifecycle |
| * is complete. The container is able to recycle request objects, so it is |
| * not valid hold a request or continuation reference after the end of the |
| * life cycle. |
| * |
| * @see #suspend() |
| * @exception IllegalStateException |
| * if the request is not suspended. |
| * |
| */ |
| void complete(); |
| |
| /* ------------------------------------------------------------ */ |
| /** |
| * @return true after {@link #suspend()} has been called and before the |
| * request has been redispatched due to being resumed, completed or |
| * timed out. |
| */ |
| boolean isSuspended(); |
| |
| /* ------------------------------------------------------------ */ |
| /** |
| * @return true if the request has been redispatched by a call to |
| * {@link #resume()}. Returns false after any subsequent call to |
| * suspend |
| */ |
| boolean isResumed(); |
| |
| /* ------------------------------------------------------------ */ |
| /** |
| * @return true after a request has been redispatched as the result of a |
| * timeout. Returns false after any subsequent call to suspend. |
| */ |
| boolean isExpired(); |
| |
| /* ------------------------------------------------------------ */ |
| /** |
| * @return true while the request is within the initial dispatch to the |
| * filter chain and/or servlet. Will return false once the calling |
| * thread has returned to the container after suspend has been |
| * called and during any subsequent redispatch. |
| */ |
| boolean isInitial(); |
| |
| /* ------------------------------------------------------------ */ |
| /** |
| * Is the suspended response wrapped. |
| * <p> |
| * Filters that wrap the response object should check this method to |
| * determine if they should destroy/finish the wrapped response. If |
| * the request was suspended with a call to {@link #suspend(ServletResponse)} |
| * that passed the wrapped response, then the filter should register |
| * a {@link ContinuationListener} to destroy/finish the wrapped response |
| * during a call to {@link ContinuationListener#onComplete(Continuation)}. |
| * @return True if {@link #suspend(ServletResponse)} has been passed a |
| * {@link ServletResponseWrapper} instance. |
| */ |
| boolean isResponseWrapped(); |
| |
| |
| /* ------------------------------------------------------------ */ |
| /** |
| * Get the suspended response. |
| * @return the {@link ServletResponse} passed to {@link #suspend(ServletResponse)}. |
| */ |
| ServletResponse getServletResponse(); |
| |
| /* ------------------------------------------------------------ */ |
| /** |
| * Add a ContinuationListener. |
| * |
| * @param listener |
| */ |
| void addContinuationListener(ContinuationListener listener); |
| |
| /* ------------------------------------------------------------ */ |
| /** Set a request attribute. |
| * This method is a convenience method to call the {@link ServletRequest#setAttribute(String, Object)} |
| * method on the associated request object. |
| * This is a thread safe call and may be called by any thread. |
| * @param name the attribute name |
| * @param attribute the attribute value |
| */ |
| public void setAttribute(String name, Object attribute); |
| |
| /* ------------------------------------------------------------ */ |
| /** Get a request attribute. |
| * This method is a convenience method to call the {@link ServletRequest#getAttribute(String)} |
| * method on the associated request object. |
| * This is a thread safe call and may be called by any thread. |
| * @param name the attribute name |
| * @return the attribute value |
| */ |
| public Object getAttribute(String name); |
| |
| /* ------------------------------------------------------------ */ |
| /** Remove a request attribute. |
| * This method is a convenience method to call the {@link ServletRequest#removeAttribute(String)} |
| * method on the associated request object. |
| * This is a thread safe call and may be called by any thread. |
| * @param name the attribute name |
| */ |
| public void removeAttribute(String name); |
| |
| /* ------------------------------------------------------------ */ |
| /** |
| * Undispatch the request. |
| * <p> |
| * This method can be called on a suspended continuation in order |
| * to exit the dispatch to the filter/servlet by throwing a {@link ContinuationThrowable} |
| * which is caught either by the container or the {@link ContinuationFilter}. |
| * This is an alternative to simply returning from the dispatch in the case |
| * where filters in the filter chain may not be prepared to handle a suspended |
| * request. |
| * </p> |
| * This method should only be used as a last resort and a normal return is a prefereable |
| * solution if filters can be updated to handle that case. |
| * |
| * @throws ContinuationThrowable thrown if the request is suspended. The instance of the |
| * exception may be reused on subsequent calls, so the stack frame may not be accurate. |
| */ |
| public void undispatch() throws ContinuationThrowable; |
| } |