diff src/org/eclipse/jetty/continuation/Continuation.java @ 917:1fc8ee20cb18

remove doSuspend
author Franklin Schmidt <fschmidt@gmail.com>
date Sun, 09 Oct 2016 03:23:55 -0600
parents 3428c60d7cfc
children a5af9ee7cf91
line wrap: on
line diff
--- a/src/org/eclipse/jetty/continuation/Continuation.java	Sun Oct 09 02:08:40 2016 -0600
+++ b/src/org/eclipse/jetty/continuation/Continuation.java	Sun Oct 09 03:23:55 2016 -0600
@@ -144,277 +144,277 @@
  */
 public interface Continuation
 {
-    public final static String ATTRIBUTE = "org.eclipse.jetty.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);
+	/* ------------------------------------------------------------ */
+	/**
+	 * 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);
+	/* ------------------------------------------------------------ */
+	/**
+	 * 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();
+	/* ------------------------------------------------------------ */
+	/**
+	 * 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();
+	/* ------------------------------------------------------------ */
+	/**
+	 * 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 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 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 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();
+	/* ------------------------------------------------------------ */
+	/**
+	 * @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();
+	/* ------------------------------------------------------------ */
+	/**
+	 * 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;
+	/* ------------------------------------------------------------ */
+	/**
+	 * 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;
 }