When a handler starts asynchronous request handling, the DispatcherServlet - * exits without invoking {@code postHandle} and {@code afterCompletion}, as it - * normally does, since the results of request handling (e.g. ModelAndView) - * will. be produced concurrently in another thread. In such scenarios, - * {@link #afterConcurrentHandlingStarted(HttpServletRequest, HttpServletResponse, Object)} - * is invoked instead allowing implementations to perform tasks such as cleaning - * up thread bound attributes. + *
When a handler starts an asynchronous request, the DispatcherServlet + * exits without invoking {@code postHandle} and {@code afterCompletion} as it + * normally does since the results of request handling (e.g. ModelAndView) + * is likely not yet ready and will be produced concurrently from another thread. + * In such scenarios, {@link #afterConcurrentHandlingStarted} is invoked instead + * allowing implementations to perform tasks such as cleaning up thread bound + * attributes before releasing the thread to the Servlet container. * *
When asynchronous handling completes, the request is dispatched to the * 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". + * + *
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 * @since 3.2 diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/HandlerInterceptor.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/HandlerInterceptor.java index 29c2721a6c1..efaacd335bf 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/HandlerInterceptor.java +++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/HandlerInterceptor.java @@ -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"); * 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 * an appropriate handler object, but before HandlerAdapter invokes the handler. + * *
DispatcherServlet processes a handler in an execution chain, consisting * of any number of interceptors, with the handler itself at the end. * With this method, each interceptor can decide to abort the execution chain, * typically sending a HTTP error or writing a custom response. + * + *
Note: special considerations apply for asynchronous + * request processing. For more details see + * {@link org.springframework.web.servlet.AsyncHandlerInterceptor}. + * * @param request current HTTP request * @param response current HTTP response * @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 * invoked the handler, but before the DispatcherServlet renders the view. * Can expose additional model objects to the view via the given ModelAndView. + * *
DispatcherServlet processes a handler in an execution chain, consisting * of any number of interceptors, with the handler itself at the end. * With this method, each interceptor can post-process an execution, * getting applied in inverse order of the execution chain. + * + *
Note: special considerations apply for asynchronous + * request processing. For more details see + * {@link org.springframework.web.servlet.AsyncHandlerInterceptor}. + * * @param request current HTTP request * @param response current HTTP response * @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 * the view. Will be called on any outcome of handler execution, thus allows * for proper resource cleanup. + * *
Note: Will only be called if this interceptor's {@code preHandle} * method has successfully completed and returned {@code true}! + * *
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 * the last to be invoked. + * + *
Note: special considerations apply for asynchronous + * request processing. For more details see + * {@link org.springframework.web.servlet.AsyncHandlerInterceptor}. + * * @param request current HTTP request * @param response current HTTP response * @param handler handler (or {@link HandlerMethod}) that started async