repo/luan: src/org/eclipse/jetty/continuation/Continuation.java comparison

comparison 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

comparison

equal deleted inserted replaced

-:4de7f6e9c453
+:1fc8ee20cb18
 * @see ContinuationListener
 *
 */
 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.
+	 * Set the continuation timeout.
-*
+	 *
-* @param timeoutMs
+	 * @param timeoutMs
-*            The time in milliseconds to wait before expiring this
+	 *            The time in milliseconds to wait before expiring this
-*            continuation after a call to {@link #suspend()} or {@link #suspend(ServletResponse)}.
+	 *            continuation after a call to {@link #suspend()} or {@link #suspend(ServletResponse)}.
-*            A timeout of <=0 means the continuation will never expire.
+	 *            A timeout of <=0 means the continuation will never expire.
-*/
+	 */
-void setTimeout(long timeoutMs);
+	void setTimeout(long timeoutMs);
-/* ------------------------------------------------------------ */
+	/* ------------------------------------------------------------ */
-/**
+	/**
-* Suspend the processing of the request and associated
+	 * Suspend the processing of the request and associated
-* {@link ServletResponse}.
+	 * {@link ServletResponse}.
-*
+	 *
-* <p>
+	 * <p>
-* After this method has been called, the lifecycle of the request will be
+	 * After this method has been called, the lifecycle of the request will be
-* extended beyond the return to the container from the
+	 * extended beyond the return to the container from the
-* {@link Servlet#service(ServletRequest, ServletResponse)} method and
+	 * {@link Servlet#service(ServletRequest, ServletResponse)} method and
-* {@link Filter#doFilter(ServletRequest, ServletResponse, FilterChain)}
+	 * {@link Filter#doFilter(ServletRequest, ServletResponse, FilterChain)}
-* calls. When a suspended request is returned to the container after
+	 * calls. When a suspended request is returned to the container after
-* a dispatch, then the container will not commit the associated response
+	 * a dispatch, then the container will not commit the associated response
-* (unless an exception other than {@link ContinuationThrowable} is thrown).
+	 * (unless an exception other than {@link ContinuationThrowable} is thrown).
-* </p>
+	 * </p>
-*
+	 *
-* <p>
+	 * <p>
-* When the thread calling the filter chain and/or servlet has returned to
+	 * 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
+	 * the container with a suspended request, the thread is freed for other
-* tasks and the request is held until either:
+	 * tasks and the request is held until either:
-* <ul>
+	 * <ul>
-* <li>a call to {@link #resume()}.</li>
+	 * <li>a call to {@link #resume()}.</li>
-* <li>a call to {@link #complete()}.</li>
+	 * <li>a call to {@link #complete()}.</li>
-* <li>the timeout expires.</li>
+	 * <li>the timeout expires.</li>
-* </ul>
+	 * </ul>
-* <p>
+	 * <p>
-* Typically suspend with no arguments is uses when a call to {@link #resume()}
+	 * 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
+	 * is expected. If a call to {@link #complete()} is expected, then the
-* {@link #suspend(ServletResponse)} method should be used instead of this method.
+	 * {@link #suspend(ServletResponse)} method should be used instead of this method.
-* </p>
+	 * </p>
-*
+	 *
-* @exception IllegalStateException
+	 * @exception IllegalStateException
-*                If the request cannot be suspended
+	 *                If the request cannot be suspended
-*/
+	 */
-void suspend();
+//	void suspend();
-/* ------------------------------------------------------------ */
+	/* ------------------------------------------------------------ */
-/**
+	/**
-* Suspend the processing of the request and associated
+	 * Suspend the processing of the request and associated
-* {@link ServletResponse}.
+	 * {@link ServletResponse}.
-*
+	 *
-* <p>
+	 * <p>
-* After this method has been called, the lifecycle of the request will be
+	 * After this method has been called, the lifecycle of the request will be
-* extended beyond the return to the container from the
+	 * extended beyond the return to the container from the
-* {@link Servlet#service(ServletRequest, ServletResponse)} method and
+	 * {@link Servlet#service(ServletRequest, ServletResponse)} method and
-* {@link Filter#doFilter(ServletRequest, ServletResponse, FilterChain)}
+	 * {@link Filter#doFilter(ServletRequest, ServletResponse, FilterChain)}
-* calls. When a suspended request is returned to the container after
+	 * calls. When a suspended request is returned to the container after
-* a dispatch, then the container will not commit the associated response
+	 * a dispatch, then the container will not commit the associated response
-* (unless an exception other than {@link ContinuationThrowable} is thrown).
+	 * (unless an exception other than {@link ContinuationThrowable} is thrown).
-* </p>
+	 * </p>
-* <p>
+	 * <p>
-* When the thread calling the filter chain and/or servlet has returned to
+	 * 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
+	 * the container with a suspended request, the thread is freed for other
-* tasks and the request is held until either:
+	 * tasks and the request is held until either:
-* <ul>
+	 * <ul>
-* <li>a call to {@link #resume()}.</li>
+	 * <li>a call to {@link #resume()}.</li>
-* <li>a call to {@link #complete()}.</li>
+	 * <li>a call to {@link #complete()}.</li>
-* <li>the timeout expires.</li>
+	 * <li>the timeout expires.</li>
-* </ul>
+	 * </ul>
-* <p>
+	 * <p>
-* Typically suspend with a response argument is uses when a call to {@link #complete()}
+	 * 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
+	 * is expected. If a call to {@link #resume()} is expected, then the
-* {@link #suspend()} method should be used instead of this method.
+	 * {@link #suspend()} method should be used instead of this method.
-* </p>
+	 * </p>
-* <p>
+	 * <p>
-* Filters that may wrap the response object should check {@link #isResponseWrapped()}
+	 * Filters that may wrap the response object should check {@link #isResponseWrapped()}
-* to decide if they should destroy/finish the wrapper. If {@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
+	 * 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
+	 * handler and the wrapper should not be destroyed/finished until after a call to
-* {@link #complete()} (potentially using a {@link ContinuationListener#onComplete(Continuation)}
+	 * {@link #complete()} (potentially using a {@link ContinuationListener#onComplete(Continuation)}
-* listener).
+	 * listener).
-*
+	 *
-* @param response The response to return via a call to {@link #getServletResponse()}
+	 * @param response The response to return via a call to {@link #getServletResponse()}
-* @exception IllegalStateException
+	 * @exception IllegalStateException
-*                If the request cannot be suspended
+	 *                If the request cannot be suspended
-*/
+	 */
-void suspend(ServletResponse response);
+//	void suspend(ServletResponse response);
-/* ------------------------------------------------------------ */
+	/* ------------------------------------------------------------ */
-/**
+	/**
-* Resume a suspended request.
+	 * Resume a suspended request.
-*
+	 *
-* <p>
+	 * <p>
-* This method can be called by any thread that has been passed a reference
+	 * 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
+	 * to a continuation. When called the request is redispatched to the
-* normal filter chain and servlet processing with {@link #isInitial()} false.
+	 * normal filter chain and servlet processing with {@link #isInitial()} false.
-* </p>
+	 * </p>
-* <p>
+	 * <p>
-* If resume is called before a suspended request is returned to the
+	 * If resume is called before a suspended request is returned to the
-* container (ie the thread that called {@link #suspend()} is still
+	 * container (ie the thread that called {@link #suspend()} is still
-* within the filter chain and/or servlet service method), then the resume
+	 * 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
+	 * 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
+	 * returns to the container. In this case both {@link #isSuspended()} and
-* {@link #isResumed()} return true. Multiple calls to resume are ignored.
+	 * {@link #isResumed()} return true. Multiple calls to resume are ignored.
-* </p>
+	 * </p>
-* <p>
+	 * <p>
-* Typically resume() is used after a call to {@link #suspend()} with
+	 * Typically resume() is used after a call to {@link #suspend()} with
-* no arguments. The dispatch after a resume call will use the original
+	 * no arguments. The dispatch after a resume call will use the original
-* request and response objects, even if {@link #suspend(ServletResponse)}
+	 * request and response objects, even if {@link #suspend(ServletResponse)}
-* had been passed a wrapped response.
+	 * had been passed a wrapped response.
-* </p>
+	 * </p>
-*
+	 *
-* @see #suspend()
+	 * @see #suspend()
-* @exception IllegalStateException if the request is not suspended.
+	 * @exception IllegalStateException if the request is not suspended.
-*
+	 *
-*/
+	 */
-void resume();
+	void resume();
-/* ------------------------------------------------------------ */
+	/* ------------------------------------------------------------ */
-/**
+	/**
-* Complete a suspended request.
+	 * Complete a suspended request.
-*
+	 *
-* <p>
+	 * <p>
-* This method can be called by any thread that has been passed a reference
+	 * 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
+	 * to a suspended request. When a request is completed, the associated
-* response object committed and flushed. The request is not redispatched.
+	 * response object committed and flushed. The request is not redispatched.
-* </p>
+	 * </p>
-*
+	 *
-* <p>
+	 * <p>
-* If complete is called before a suspended request is returned to the
+	 * If complete is called before a suspended request is returned to the
-* container (ie the thread that called {@link #suspend()} is still
+	 * container (ie the thread that called {@link #suspend()} is still
-* within the filter chain and/or servlet service method), then the complete
+	 * 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
+	 * 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
+	 * returns to the container. In this case both {@link #isSuspended()} and
-* {@link #isResumed()} return true.
+	 * {@link #isResumed()} return true.
-* </p>
+	 * </p>
-*
+	 *
-* <p>
+	 * <p>
-* Typically resume() is used after a call to {@link #suspend(ServletResponse)} with
+	 * Typically resume() is used after a call to {@link #suspend(ServletResponse)} with
-* a possibly wrapped response. The async handler should use the response
+	 * a possibly wrapped response. The async handler should use the response
-* provided by {@link #getServletResponse()} to write the response before
+	 * provided by {@link #getServletResponse()} to write the response before
-* calling {@link #complete()}. If the request was suspended with a
+	 * calling {@link #complete()}. If the request was suspended with a
-* call to {@link #suspend()} then no response object will be available via
+	 * call to {@link #suspend()} then no response object will be available via
-* {@link #getServletResponse()}.
+	 * {@link #getServletResponse()}.
-* </p>
+	 * </p>
-*
+	 *
-* <p>
+	 * <p>
-* Once complete has been called and any thread calling the filter chain
+	 * Once complete has been called and any thread calling the filter chain
-* and/or servlet chain has returned to the container, the request lifecycle
+	 * 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
+	 * 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
+	 * not valid hold a request or continuation reference after the end of the
-* life cycle.
+	 * life cycle.
-*
+	 *
-* @see #suspend()
+	 * @see #suspend()
-* @exception IllegalStateException
+	 * @exception IllegalStateException
-*                if the request is not suspended.
+	 *                if the request is not suspended.
-*
+	 *
-*/
+	 */
-void complete();
+	void complete();
-/* ------------------------------------------------------------ */
+	/* ------------------------------------------------------------ */
-/**
+	/**
-* @return true after {@link #suspend()} has been called and before the
+	 * @return true after {@link #suspend()} has been called and before the
-*         request has been redispatched due to being resumed, completed or
+	 *         request has been redispatched due to being resumed, completed or
-*         timed out.
+	 *         timed out.
-*/
+	 */
-boolean isSuspended();
+	boolean isSuspended();
-/* ------------------------------------------------------------ */
+	/* ------------------------------------------------------------ */
-/**
+	/**
-* @return true if the request has been redispatched by a call to
+	 * @return true if the request has been redispatched by a call to
-*         {@link #resume()}. Returns false after any subsequent call to
+	 *         {@link #resume()}. Returns false after any subsequent call to
-*         suspend
+	 *         suspend
-*/
+	 */
-boolean isResumed();
+	boolean isResumed();
-/* ------------------------------------------------------------ */
+	/* ------------------------------------------------------------ */
-/**
+	/**
-* @return true after a request has been redispatched as the result of a
+	 * @return true after a request has been redispatched as the result of a
-*         timeout. Returns false after any subsequent call to suspend.
+	 *         timeout. Returns false after any subsequent call to suspend.
-*/
+	 */
-boolean isExpired();
+	boolean isExpired();
-/* ------------------------------------------------------------ */
+	/* ------------------------------------------------------------ */
-/**
+	/**
-* @return true while the request is within the initial dispatch to the
+	 * @return true while the request is within the initial dispatch to the
-*         filter chain and/or servlet. Will return false once the calling
+	 *         filter chain and/or servlet. Will return false once the calling
-*         thread has returned to the container after suspend has been
+	 *         thread has returned to the container after suspend has been
-*         called and during any subsequent redispatch.
+	 *         called and during any subsequent redispatch.
-*/
+	 */
-boolean isInitial();
+	boolean isInitial();
-/* ------------------------------------------------------------ */
+	/* ------------------------------------------------------------ */
-/**
+	/**
-* Is the suspended response wrapped.
+	 * Is the suspended response wrapped.
-* <p>
+	 * <p>
-* Filters that wrap the response object should check this method to
+	 * Filters that wrap the response object should check this method to
-* determine if they should destroy/finish the wrapped response. If
+	 * determine if they should destroy/finish the wrapped response. If
-* the request was suspended with a call to {@link #suspend(ServletResponse)}
+	 * the request was suspended with a call to {@link #suspend(ServletResponse)}
-* that passed the wrapped response, then the filter should register
+	 * that passed the wrapped response, then the filter should register
-* a {@link ContinuationListener} to destroy/finish the wrapped response
+	 * a {@link ContinuationListener} to destroy/finish the wrapped response
-* during a call to {@link ContinuationListener#onComplete(Continuation)}.
+	 * during a call to {@link ContinuationListener#onComplete(Continuation)}.
-* @return True if {@link #suspend(ServletResponse)} has been passed a
+	 * @return True if {@link #suspend(ServletResponse)} has been passed a
-* {@link ServletResponseWrapper} instance.
+	 * {@link ServletResponseWrapper} instance.
-*/
+	 */
-boolean isResponseWrapped();
+	boolean isResponseWrapped();
-/* ------------------------------------------------------------ */
+	/* ------------------------------------------------------------ */
-/**
+	/**
-* Get the suspended response.
+	 * Get the suspended response.
-* @return the {@link ServletResponse} passed to {@link #suspend(ServletResponse)}.
+	 * @return the {@link ServletResponse} passed to {@link #suspend(ServletResponse)}.
-*/
+	 */
-ServletResponse getServletResponse();
+	ServletResponse getServletResponse();
-/* ------------------------------------------------------------ */
+	/* ------------------------------------------------------------ */
-/**
+	/**
-* Add a ContinuationListener.
+	 * Add a ContinuationListener.
-*
+	 *
-* @param listener
+	 * @param listener
-*/
+	 */
-void addContinuationListener(ContinuationListener listener);
+	void addContinuationListener(ContinuationListener listener);
-/* ------------------------------------------------------------ */
+	/* ------------------------------------------------------------ */
-/** Set a request attribute.
+	/** Set a request attribute.
-* This method is a convenience method to call the {@link ServletRequest#setAttribute(String, Object)}
+	 * This method is a convenience method to call the {@link ServletRequest#setAttribute(String, Object)}
-* method on the associated request object.
+	 * method on the associated request object.
-* This is a thread safe call and may be called by any thread.
+	 * This is a thread safe call and may be called by any thread.
-* @param name the attribute name
+	 * @param name the attribute name
-* @param attribute the attribute value
+	 * @param attribute the attribute value
-*/
+	 */
-public void setAttribute(String name, Object attribute);
+	public void setAttribute(String name, Object attribute);
-/* ------------------------------------------------------------ */
+	/* ------------------------------------------------------------ */
-/** Get a request attribute.
+	/** Get a request attribute.
-* This method is a convenience method to call the {@link ServletRequest#getAttribute(String)}
+	 * This method is a convenience method to call the {@link ServletRequest#getAttribute(String)}
-* method on the associated request object.
+	 * method on the associated request object.
-* This is a thread safe call and may be called by any thread.
+	 * This is a thread safe call and may be called by any thread.
-* @param name the attribute name
+	 * @param name the attribute name
-* @return the attribute value
+	 * @return the attribute value
-*/
+	 */
-public Object getAttribute(String name);
+	public Object getAttribute(String name);
-/* ------------------------------------------------------------ */
+	/* ------------------------------------------------------------ */
-/** Remove a request attribute.
+	/** Remove a request attribute.
-* This method is a convenience method to call the {@link ServletRequest#removeAttribute(String)}
+	 * This method is a convenience method to call the {@link ServletRequest#removeAttribute(String)}
-* method on the associated request object.
+	 * method on the associated request object.
-* This is a thread safe call and may be called by any thread.
+	 * This is a thread safe call and may be called by any thread.
-* @param name the attribute name
+	 * @param name the attribute name
-*/
+	 */
-public void removeAttribute(String name);
+	public void removeAttribute(String name);
-/* ------------------------------------------------------------ */
+	/* ------------------------------------------------------------ */
-/**
+	/**
-* Undispatch the request.
+	 * Undispatch the request.
-* <p>
+	 * <p>
-* This method can be called on a suspended continuation in order
+	 * This method can be called on a suspended continuation in order
-* to exit the dispatch to the filter/servlet by throwing a {@link ContinuationThrowable}
+	 * to exit the dispatch to the filter/servlet by throwing a {@link ContinuationThrowable}
-* which is caught either by the container or the {@link ContinuationFilter}.
+	 * which is caught either by the container or the {@link ContinuationFilter}.
-* This is an alternative to simply returning from the dispatch in the case
+	 * 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
+	 * where filters in the filter chain may not be prepared to handle a suspended
-* request.
+	 * request.
-* </p>
+	 * </p>
-* This method should only be used as a last resort and a normal return is a prefereable
+	 * 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.
+	 * solution if filters can be updated to handle that case.
-*
+	 *
-* @throws ContinuationThrowable thrown if the request is suspended. The instance of the
+	 * @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.
+	 * exception may be reused on subsequent calls, so the stack frame may not be accurate.
-*/
+	 */
-public void undispatch() throws ContinuationThrowable;
+	public void undispatch() throws ContinuationThrowable;
 }

Mercurial Hosting > luan

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