Update Javadoc of AsyncHandlerInterceptor
Issue: SPR-12608, SPR-12720
This commit is contained in:
parent
f06dffb714
commit
18039785ae
|
@ -1,5 +1,5 @@
|
||||||
/*
|
/*
|
||||||
* Copyright 2002-2012 the original author or authors.
|
* Copyright 2002-2015 the original author or authors.
|
||||||
*
|
*
|
||||||
* Licensed under the Apache License, Version 2.0 (the "License");
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
||||||
* you may not use this file except in compliance with the License.
|
* you may not use this file except in compliance with the License.
|
||||||
|
@ -22,20 +22,34 @@ import javax.servlet.http.HttpServletResponse;
|
||||||
import org.springframework.web.method.HandlerMethod;
|
import org.springframework.web.method.HandlerMethod;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Extends {@code HandlerInterceptor} with a callback method invoked during
|
* Extends {@code HandlerInterceptor} with a callback method invoked after the
|
||||||
* asynchronous request handling.
|
* start of asynchronous request handling.
|
||||||
*
|
*
|
||||||
* <p>When a handler starts asynchronous request handling, the DispatcherServlet
|
* <p>When a handler starts an asynchronous request, the DispatcherServlet
|
||||||
* exits without invoking {@code postHandle} and {@code afterCompletion}, as it
|
* exits without invoking {@code postHandle} and {@code afterCompletion} as it
|
||||||
* normally does, since the results of request handling (e.g. ModelAndView)
|
* normally does since the results of request handling (e.g. ModelAndView)
|
||||||
* will. be produced concurrently in another thread. In such scenarios,
|
* is likely not yet ready and will be produced concurrently from another thread.
|
||||||
* {@link #afterConcurrentHandlingStarted(HttpServletRequest, HttpServletResponse, Object)}
|
* In such scenarios, {@link #afterConcurrentHandlingStarted} is invoked instead
|
||||||
* is invoked instead allowing implementations to perform tasks such as cleaning
|
* allowing implementations to perform tasks such as cleaning up thread bound
|
||||||
* up thread bound attributes.
|
* attributes before releasing the thread to the Servlet container.
|
||||||
*
|
*
|
||||||
* <p>When asynchronous handling completes, the request is dispatched to the
|
* <p>When asynchronous handling completes, the request is dispatched to the
|
||||||
* container for further processing. At this stage the DispatcherServlet invokes
|
* container for further processing. At this stage the DispatcherServlet invokes
|
||||||
* {@code preHandle}, {@code postHandle} and {@code afterCompletion} as usual.
|
* {@code preHandle}, {@code postHandle} and {@code afterCompletion}.
|
||||||
|
* To distinguish between the initial request and the subsequent dispatch
|
||||||
|
* after asynchronous handling completes, interceptors can check whether the
|
||||||
|
* {@code javax.servlet.DispatcherType} of {@link javax.servlet.ServletRequest}
|
||||||
|
* is "REQUEST" or "ASYNC".
|
||||||
|
*
|
||||||
|
* <p>Note that {@code HandlerInterceptor} implementations may be need to do work
|
||||||
|
* when an async request times out or completes with a network error. For such
|
||||||
|
* cases the Servlet container does not dispatch and therefore the
|
||||||
|
* {@code postHandle} and {@code afterCompletion} methods will not be invoked.
|
||||||
|
* Instead interceptors can register to track an asynchronous request through
|
||||||
|
* the {@code registerCallbackInterceptor} and {@code registerDeferredResultInterceptor}
|
||||||
|
* methods on {@link org.springframework.web.context.request.async.WebAsyncManager
|
||||||
|
* WebAsyncManager}. This can be done proactively on every request from
|
||||||
|
* {@code preHandle} regardless of whether async request processing will start.
|
||||||
*
|
*
|
||||||
* @author Rossen Stoyanchev
|
* @author Rossen Stoyanchev
|
||||||
* @since 3.2
|
* @since 3.2
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
/*
|
/*
|
||||||
* Copyright 2002-2014 the original author or authors.
|
* Copyright 2002-2015 the original author or authors.
|
||||||
*
|
*
|
||||||
* Licensed under the Apache License, Version 2.0 (the "License");
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
||||||
* you may not use this file except in compliance with the License.
|
* you may not use this file except in compliance with the License.
|
||||||
|
@ -77,10 +77,16 @@ public interface HandlerInterceptor {
|
||||||
/**
|
/**
|
||||||
* Intercept the execution of a handler. Called after HandlerMapping determined
|
* Intercept the execution of a handler. Called after HandlerMapping determined
|
||||||
* an appropriate handler object, but before HandlerAdapter invokes the handler.
|
* an appropriate handler object, but before HandlerAdapter invokes the handler.
|
||||||
|
*
|
||||||
* <p>DispatcherServlet processes a handler in an execution chain, consisting
|
* <p>DispatcherServlet processes a handler in an execution chain, consisting
|
||||||
* of any number of interceptors, with the handler itself at the end.
|
* of any number of interceptors, with the handler itself at the end.
|
||||||
* With this method, each interceptor can decide to abort the execution chain,
|
* With this method, each interceptor can decide to abort the execution chain,
|
||||||
* typically sending a HTTP error or writing a custom response.
|
* typically sending a HTTP error or writing a custom response.
|
||||||
|
*
|
||||||
|
* <p><strong>Note:</strong> special considerations apply for asynchronous
|
||||||
|
* request processing. For more details see
|
||||||
|
* {@link org.springframework.web.servlet.AsyncHandlerInterceptor}.
|
||||||
|
*
|
||||||
* @param request current HTTP request
|
* @param request current HTTP request
|
||||||
* @param response current HTTP response
|
* @param response current HTTP response
|
||||||
* @param handler chosen handler to execute, for type and/or instance evaluation
|
* @param handler chosen handler to execute, for type and/or instance evaluation
|
||||||
|
@ -96,10 +102,16 @@ public interface HandlerInterceptor {
|
||||||
* Intercept the execution of a handler. Called after HandlerAdapter actually
|
* Intercept the execution of a handler. Called after HandlerAdapter actually
|
||||||
* invoked the handler, but before the DispatcherServlet renders the view.
|
* invoked the handler, but before the DispatcherServlet renders the view.
|
||||||
* Can expose additional model objects to the view via the given ModelAndView.
|
* Can expose additional model objects to the view via the given ModelAndView.
|
||||||
|
*
|
||||||
* <p>DispatcherServlet processes a handler in an execution chain, consisting
|
* <p>DispatcherServlet processes a handler in an execution chain, consisting
|
||||||
* of any number of interceptors, with the handler itself at the end.
|
* of any number of interceptors, with the handler itself at the end.
|
||||||
* With this method, each interceptor can post-process an execution,
|
* With this method, each interceptor can post-process an execution,
|
||||||
* getting applied in inverse order of the execution chain.
|
* getting applied in inverse order of the execution chain.
|
||||||
|
*
|
||||||
|
* <p><strong>Note:</strong> special considerations apply for asynchronous
|
||||||
|
* request processing. For more details see
|
||||||
|
* {@link org.springframework.web.servlet.AsyncHandlerInterceptor}.
|
||||||
|
*
|
||||||
* @param request current HTTP request
|
* @param request current HTTP request
|
||||||
* @param response current HTTP response
|
* @param response current HTTP response
|
||||||
* @param handler handler (or {@link HandlerMethod}) that started async
|
* @param handler handler (or {@link HandlerMethod}) that started async
|
||||||
|
@ -115,11 +127,18 @@ public interface HandlerInterceptor {
|
||||||
* Callback after completion of request processing, that is, after rendering
|
* Callback after completion of request processing, that is, after rendering
|
||||||
* the view. Will be called on any outcome of handler execution, thus allows
|
* the view. Will be called on any outcome of handler execution, thus allows
|
||||||
* for proper resource cleanup.
|
* for proper resource cleanup.
|
||||||
|
*
|
||||||
* <p>Note: Will only be called if this interceptor's {@code preHandle}
|
* <p>Note: Will only be called if this interceptor's {@code preHandle}
|
||||||
* method has successfully completed and returned {@code true}!
|
* method has successfully completed and returned {@code true}!
|
||||||
|
*
|
||||||
* <p>As with the {@code postHandle} method, the method will be invoked on each
|
* <p>As with the {@code postHandle} method, the method will be invoked on each
|
||||||
* interceptor in the chain in reverse order, so the first interceptor will be
|
* interceptor in the chain in reverse order, so the first interceptor will be
|
||||||
* the last to be invoked.
|
* the last to be invoked.
|
||||||
|
*
|
||||||
|
* <p><strong>Note:</strong> special considerations apply for asynchronous
|
||||||
|
* request processing. For more details see
|
||||||
|
* {@link org.springframework.web.servlet.AsyncHandlerInterceptor}.
|
||||||
|
*
|
||||||
* @param request current HTTP request
|
* @param request current HTTP request
|
||||||
* @param response current HTTP response
|
* @param response current HTTP response
|
||||||
* @param handler handler (or {@link HandlerMethod}) that started async
|
* @param handler handler (or {@link HandlerMethod}) that started async
|
||||||
|
|
Loading…
Reference in New Issue