Polish Javadoc for MVC exception handling classes

This commit is contained in:
Sam Brannen 2015-10-06 17:30:45 +02:00
parent 3db62d5494
commit 28c07a6d38
5 changed files with 65 additions and 62 deletions

View File

@ -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.
@ -20,13 +20,13 @@ import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse; import javax.servlet.http.HttpServletResponse;
/** /**
* Interface to be implemented by objects than can resolve exceptions thrown * Interface to be implemented by objects that can resolve exceptions thrown during
* during handler mapping or execution, in the typical case to error views. * handler mapping or execution, in the typical case to error views. Implementors are
* Implementors are typically registered as beans in the application context. * typically registered as beans in the application context.
* *
* <p>Error views are analogous to the error page JSPs, but can be used with * <p>Error views are analogous to JSP error pages but can be used with any kind of
* any kind of exception including any checked exception, with potentially * exception including any checked exception, with potentially fine-grained mappings for
* fine-granular mappings for specific handlers. * specific handlers.
* *
* @author Juergen Hoeller * @author Juergen Hoeller
* @since 22.11.2003 * @since 22.11.2003
@ -34,9 +34,9 @@ import javax.servlet.http.HttpServletResponse;
public interface HandlerExceptionResolver { public interface HandlerExceptionResolver {
/** /**
* Try to resolve the given exception that got thrown during on handler execution, * Try to resolve the given exception that got thrown during handler execution,
* returning a ModelAndView that represents a specific error page if appropriate. * returning a {@link ModelAndView} that represents a specific error page if appropriate.
* <p>The returned ModelAndView may be {@linkplain ModelAndView#isEmpty() empty} * <p>The returned {@code ModelAndView} may be {@linkplain ModelAndView#isEmpty() empty}
* to indicate that the exception has been resolved successfully but that no view * to indicate that the exception has been resolved successfully but that no view
* should be rendered, for instance by setting a status code. * should be rendered, for instance by setting a status code.
* @param request current HTTP request * @param request current HTTP request
@ -44,8 +44,8 @@ public interface HandlerExceptionResolver {
* @param handler the executed handler, or {@code null} if none chosen at the * @param handler the executed handler, or {@code null} if none chosen at the
* time of the exception (for example, if multipart resolution failed) * time of the exception (for example, if multipart resolution failed)
* @param ex the exception that got thrown during handler execution * @param ex the exception that got thrown during handler execution
* @return a corresponding ModelAndView to forward to, * @return a corresponding {@code ModelAndView} to forward to, or {@code null}
* or {@code null} for default processing * for default processing
*/ */
ModelAndView resolveException( ModelAndView resolveException(
HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex); HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex);

View File

@ -30,11 +30,13 @@ import org.springframework.web.servlet.ModelAndView;
/** /**
* Abstract base class for {@link HandlerExceptionResolver} implementations. * Abstract base class for {@link HandlerExceptionResolver} implementations.
* *
* <p>Provides a set of mapped handlers that the resolver should map to, * <p>Supports mapped {@linkplain #setMappedHandlers handlers} and
* and the {@link Ordered} implementation. * {@linkplain #setMappedHandlerClasses handler classes} that the resolver
* should be applied to and implements the {@link Ordered} interface.
* *
* @author Arjen Poutsma * @author Arjen Poutsma
* @author Juergen Hoeller * @author Juergen Hoeller
* @author Sam Brannen
* @since 3.0 * @since 3.0
*/ */
public abstract class AbstractHandlerExceptionResolver implements HandlerExceptionResolver, Ordered { public abstract class AbstractHandlerExceptionResolver implements HandlerExceptionResolver, Ordered {
@ -67,10 +69,10 @@ public abstract class AbstractHandlerExceptionResolver implements HandlerExcepti
/** /**
* Specify the set of handlers that this exception resolver should apply to. * Specify the set of handlers that this exception resolver should apply to.
* The exception mappings and the default error view will only apply to the specified handlers. * <p>The exception mappings and the default error view will only apply to the specified handlers.
* <p>If no handlers and handler classes are set, the exception mappings and the default error * <p>If no handlers or handler classes are set, the exception mappings and the default error
* view will apply to all handlers. This means that a specified default error view will be used * view will apply to all handlers. This means that a specified default error view will be used
* as fallback for all exceptions; any further HandlerExceptionResolvers in the chain will be * as a fallback for all exceptions; any further HandlerExceptionResolvers in the chain will be
* ignored in this case. * ignored in this case.
*/ */
public void setMappedHandlers(Set<?> mappedHandlers) { public void setMappedHandlers(Set<?> mappedHandlers) {
@ -79,11 +81,11 @@ public abstract class AbstractHandlerExceptionResolver implements HandlerExcepti
/** /**
* Specify the set of classes that this exception resolver should apply to. * Specify the set of classes that this exception resolver should apply to.
* The exception mappings and the default error view will only apply to handlers of the * <p>The exception mappings and the default error view will only apply to handlers of the
* specified type; the specified types may be interfaces and superclasses of handlers as well. * specified types; the specified types may be interfaces or superclasses of handlers as well.
* <p>If no handlers and handler classes are set, the exception mappings and the default error * <p>If no handlers or handler classes are set, the exception mappings and the default error
* view will apply to all handlers. This means that a specified default error view will be used * view will apply to all handlers. This means that a specified default error view will be used
* as fallback for all exceptions; any further HandlerExceptionResolvers in the chain will be * as a fallback for all exceptions; any further HandlerExceptionResolvers in the chain will be
* ignored in this case. * ignored in this case.
*/ */
public void setMappedHandlerClasses(Class<?>[] mappedHandlerClasses) { public void setMappedHandlerClasses(Class<?>[] mappedHandlerClasses) {
@ -92,11 +94,11 @@ public abstract class AbstractHandlerExceptionResolver implements HandlerExcepti
/** /**
* Set the log category for warn logging. The name will be passed to the underlying logger * Set the log category for warn logging. The name will be passed to the underlying logger
* implementation through Commons Logging, getting interpreted as log category according * implementation through Commons Logging, getting interpreted as a log category according
* to the logger's configuration. * to the logger's configuration.
* <p>Default is warn logging using the {@link AbstractHandlerExceptionResolver} class name derived logger. * <p>Default is warn logging using the {@link AbstractHandlerExceptionResolver} class name derived logger.
* Set to {@code null} to disable warn logging. * <p>Set to {@code null} to disable warn logging.
* Override the {@link #logException} method for custom logging. * <p>Override the {@link #logException} method for custom logging.
* @see org.apache.commons.logging.LogFactory#getLog(String) * @see org.apache.commons.logging.LogFactory#getLog(String)
* @see org.apache.log4j.Logger#getLogger(String) * @see org.apache.log4j.Logger#getLogger(String)
* @see java.util.logging.Logger#getLogger(String) * @see java.util.logging.Logger#getLogger(String)
@ -107,19 +109,19 @@ public abstract class AbstractHandlerExceptionResolver implements HandlerExcepti
/** /**
* Specify whether to prevent HTTP response caching for any view resolved * Specify whether to prevent HTTP response caching for any view resolved
* by this HandlerExceptionResolver. * by this exception resolver.
* <p>Default is "false". Switch this to "true" in order to automatically * <p>Default is {@code false}. Switch this to {@code true} in order to
* generate HTTP response headers that suppress response caching. * automatically generate HTTP response headers that suppress response caching.
*/ */
public void setPreventResponseCaching(boolean preventResponseCaching) { public void setPreventResponseCaching(boolean preventResponseCaching) {
this.preventResponseCaching = preventResponseCaching; this.preventResponseCaching = preventResponseCaching;
} }
/** /**
* Checks whether this resolver is supposed to apply (i.e. the handler matches * Check whether this resolver is supposed to apply (i.e. if the supplied handler
* in case of "mappedHandlers" having been specified), then delegates to the * matches any of the configured {@linkplain #setMappedHandlers handlers} or
* {@link #doResolveException} template method. * {@linkplain #setMappedHandlerClasses handler classes}), and then delegate
* to the {@link #doResolveException} template method.
*/ */
@Override @Override
public ModelAndView resolveException(HttpServletRequest request, HttpServletResponse response, public ModelAndView resolveException(HttpServletRequest request, HttpServletResponse response,
@ -145,8 +147,9 @@ public abstract class AbstractHandlerExceptionResolver implements HandlerExcepti
/** /**
* Check whether this resolver is supposed to apply to the given handler. * Check whether this resolver is supposed to apply to the given handler.
* <p>The default implementation checks against the specified mapped handlers * <p>The default implementation checks against the configured
* and handler classes, if any. * {@linkplain #setMappedHandlers handlers} and
* {@linkplain #setMappedHandlerClasses handler classes}, if any.
* @param request current HTTP request * @param request current HTTP request
* @param handler the executed handler, or {@code null} if none chosen * @param handler the executed handler, or {@code null} if none chosen
* at the time of the exception (for example, if multipart resolution failed) * at the time of the exception (for example, if multipart resolution failed)
@ -222,10 +225,9 @@ public abstract class AbstractHandlerExceptionResolver implements HandlerExcepti
response.addHeader(HEADER_CACHE_CONTROL, "no-store"); response.addHeader(HEADER_CACHE_CONTROL, "no-store");
} }
/** /**
* Actually resolve the given exception that got thrown during on handler execution, * Actually resolve the given exception that got thrown during handler execution,
* returning a ModelAndView that represents a specific error page if appropriate. * returning a {@link ModelAndView} that represents a specific error page if appropriate.
* <p>May be overridden in subclasses, in order to apply specific exception checks. * <p>May be overridden in subclasses, in order to apply specific exception checks.
* Note that this template method will be invoked <i>after</i> checking whether this * Note that this template method will be invoked <i>after</i> checking whether this
* resolved applies ("mappedHandlers" etc), so an implementation may simply proceed * resolved applies ("mappedHandlers" etc), so an implementation may simply proceed
@ -235,7 +237,7 @@ public abstract class AbstractHandlerExceptionResolver implements HandlerExcepti
* @param handler the executed handler, or {@code null} if none chosen at the time * @param handler the executed handler, or {@code null} if none chosen at the time
* of the exception (for example, if multipart resolution failed) * of the exception (for example, if multipart resolution failed)
* @param ex the exception that got thrown during handler execution * @param ex the exception that got thrown during handler execution
* @return a corresponding ModelAndView to forward to, or {@code null} for default processing * @return a corresponding {@code ModelAndView} to forward to, or {@code null} for default processing
*/ */
protected abstract ModelAndView doResolveException(HttpServletRequest request, protected abstract ModelAndView doResolveException(HttpServletRequest request,
HttpServletResponse response, Object handler, Exception ex); HttpServletResponse response, Object handler, Exception ex);

View File

@ -32,7 +32,7 @@ import org.springframework.http.server.ServerHttpResponse;
* *
* <p>The serialization view specified in the annotation will be passed in to the * <p>The serialization view specified in the annotation will be passed in to the
* {@link org.springframework.http.converter.json.MappingJackson2HttpMessageConverter} * {@link org.springframework.http.converter.json.MappingJackson2HttpMessageConverter}
* which will then use it to serialize the response body with. * which will then use it to serialize the response body.
* *
* <p>Note that despite {@code @JsonView} allowing for more than one class to * <p>Note that despite {@code @JsonView} allowing for more than one class to
* be specified, the use for a response body advice is only supported with * be specified, the use for a response body advice is only supported with

View File

@ -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.
@ -24,7 +24,7 @@ import org.springframework.http.server.ServerHttpResponse;
/** /**
* Allows customizing the response after the execution of an {@code @ResponseBody} * Allows customizing the response after the execution of an {@code @ResponseBody}
* or an {@code ResponseEntity} controller method but before the body is written * or a {@code ResponseEntity} controller method but before the body is written
* with an {@code HttpMessageConverter}. * with an {@code HttpMessageConverter}.
* *
* <p>Implementations may be may be registered directly with * <p>Implementations may be may be registered directly with

View File

@ -13,6 +13,7 @@
* See the License for the specific language governing permissions and * See the License for the specific language governing permissions and
* limitations under the License. * limitations under the License.
*/ */
package org.springframework.web.servlet.mvc.method.annotation; package org.springframework.web.servlet.mvc.method.annotation;
import java.util.List; import java.util.List;
@ -52,14 +53,14 @@ import org.springframework.web.servlet.mvc.multiaction.NoSuchRequestHandlingMeth
* that wish to provide centralized exception handling across all * that wish to provide centralized exception handling across all
* {@code @RequestMapping} methods through {@code @ExceptionHandler} methods. * {@code @RequestMapping} methods through {@code @ExceptionHandler} methods.
* *
* <p>This base class provides an {@code @ExceptionHandler} for handling standard * <p>This base class provides an {@code @ExceptionHandler} method for handling standard
* Spring MVC exceptions that returns a {@code ResponseEntity} to be written with * Spring MVC exceptions that returns a {@code ResponseEntity} to be written with
* {@link HttpMessageConverter message converters}. This is in contrast to * {@link HttpMessageConverter message converters}. This is in contrast to
* {@link org.springframework.web.servlet.mvc.support.DefaultHandlerExceptionResolver * {@link org.springframework.web.servlet.mvc.support.DefaultHandlerExceptionResolver
* DefaultHandlerExceptionResolver} which returns a {@code ModelAndView} instead. * DefaultHandlerExceptionResolver} which returns a {@code ModelAndView} instead.
* *
* <p>If there is no need to write error content to the response body, or if using * <p>If there is no need to write error content to the response body, or if using
* view resolution, e.g. {@code ContentNegotiatingViewResolver}, then use * view resolution (e.g., via {@code ContentNegotiatingViewResolver}), then use
* {@code DefaultHandlerExceptionResolver} instead. * {@code DefaultHandlerExceptionResolver} instead.
* *
* <p>Note that in order for an {@code @ControllerAdvice} sub-class to be * <p>Note that in order for an {@code @ControllerAdvice} sub-class to be
@ -68,6 +69,7 @@ import org.springframework.web.servlet.mvc.multiaction.NoSuchRequestHandlingMeth
* @author Rossen Stoyanchev * @author Rossen Stoyanchev
* @since 3.2 * @since 3.2
* *
* @see #handleException(Exception, WebRequest)
* @see org.springframework.web.servlet.mvc.support.DefaultHandlerExceptionResolver * @see org.springframework.web.servlet.mvc.support.DefaultHandlerExceptionResolver
*/ */
public abstract class ResponseEntityExceptionHandler { public abstract class ResponseEntityExceptionHandler {
@ -92,7 +94,7 @@ public abstract class ResponseEntityExceptionHandler {
* @param ex the target exception * @param ex the target exception
* @param request the current request * @param request the current request
*/ */
@ExceptionHandler(value={ @ExceptionHandler({
NoSuchRequestHandlingMethodException.class, NoSuchRequestHandlingMethodException.class,
HttpRequestMethodNotSupportedException.class, HttpRequestMethodNotSupportedException.class,
HttpMediaTypeNotSupportedException.class, HttpMediaTypeNotSupportedException.class,
@ -182,7 +184,7 @@ public abstract class ResponseEntityExceptionHandler {
/** /**
* A single place to customize the response body of all Exception types. * A single place to customize the response body of all Exception types.
* This method returns {@code null} by default. * <p>This method returns {@code null} by default.
* @param ex the exception * @param ex the exception
* @param body the body to use for the response * @param body the body to use for the response
* @param headers the headers to be written to the response * @param headers the headers to be written to the response
@ -201,8 +203,7 @@ public abstract class ResponseEntityExceptionHandler {
/** /**
* Customize the response for NoSuchRequestHandlingMethodException. * Customize the response for NoSuchRequestHandlingMethodException.
* This method logs a warning and delegates to * <p>This method logs a warning and delegates to {@link #handleExceptionInternal}.
* {@link #handleExceptionInternal(Exception, Object, HttpHeaders, HttpStatus, WebRequest)}.
* @param ex the exception * @param ex the exception
* @param headers the headers to be written to the response * @param headers the headers to be written to the response
* @param status the selected response status * @param status the selected response status
@ -219,8 +220,8 @@ public abstract class ResponseEntityExceptionHandler {
/** /**
* Customize the response for HttpRequestMethodNotSupportedException. * Customize the response for HttpRequestMethodNotSupportedException.
* This method logs a warning, sets the "Allow" header, and delegates to * <p>This method logs a warning, sets the "Allow" header, and delegates to
* {@link #handleExceptionInternal(Exception, Object, HttpHeaders, HttpStatus, WebRequest)}. * {@link #handleExceptionInternal}.
* @param ex the exception * @param ex the exception
* @param headers the headers to be written to the response * @param headers the headers to be written to the response
* @param status the selected response status * @param status the selected response status
@ -242,8 +243,8 @@ public abstract class ResponseEntityExceptionHandler {
/** /**
* Customize the response for HttpMediaTypeNotSupportedException. * Customize the response for HttpMediaTypeNotSupportedException.
* This method sets the "Accept" header and delegates to * <p>This method sets the "Accept" header and delegates to
* {@link #handleExceptionInternal(Exception, Object, HttpHeaders, HttpStatus, WebRequest)}. * {@link #handleExceptionInternal}.
* @param ex the exception * @param ex the exception
* @param headers the headers to be written to the response * @param headers the headers to be written to the response
* @param status the selected response status * @param status the selected response status
@ -263,7 +264,7 @@ public abstract class ResponseEntityExceptionHandler {
/** /**
* Customize the response for HttpMediaTypeNotAcceptableException. * Customize the response for HttpMediaTypeNotAcceptableException.
* This method delegates to {@link #handleExceptionInternal(Exception, Object, HttpHeaders, HttpStatus, WebRequest)}. * <p>This method delegates to {@link #handleExceptionInternal}.
* @param ex the exception * @param ex the exception
* @param headers the headers to be written to the response * @param headers the headers to be written to the response
* @param status the selected response status * @param status the selected response status
@ -278,7 +279,7 @@ public abstract class ResponseEntityExceptionHandler {
/** /**
* Customize the response for MissingPathVariableException. * Customize the response for MissingPathVariableException.
* This method delegates to {@link #handleExceptionInternal(Exception, Object, HttpHeaders, HttpStatus, WebRequest)}. * <p>This method delegates to {@link #handleExceptionInternal}.
* @param ex the exception * @param ex the exception
* @param headers the headers to be written to the response * @param headers the headers to be written to the response
* @param status the selected response status * @param status the selected response status
@ -294,7 +295,7 @@ public abstract class ResponseEntityExceptionHandler {
/** /**
* Customize the response for MissingServletRequestParameterException. * Customize the response for MissingServletRequestParameterException.
* This method delegates to {@link #handleExceptionInternal(Exception, Object, HttpHeaders, HttpStatus, WebRequest)}. * <p>This method delegates to {@link #handleExceptionInternal}.
* @param ex the exception * @param ex the exception
* @param headers the headers to be written to the response * @param headers the headers to be written to the response
* @param status the selected response status * @param status the selected response status
@ -309,7 +310,7 @@ public abstract class ResponseEntityExceptionHandler {
/** /**
* Customize the response for ServletRequestBindingException. * Customize the response for ServletRequestBindingException.
* This method delegates to {@link #handleExceptionInternal(Exception, Object, HttpHeaders, HttpStatus, WebRequest)}. * <p>This method delegates to {@link #handleExceptionInternal}.
* @param ex the exception * @param ex the exception
* @param headers the headers to be written to the response * @param headers the headers to be written to the response
* @param status the selected response status * @param status the selected response status
@ -324,7 +325,7 @@ public abstract class ResponseEntityExceptionHandler {
/** /**
* Customize the response for ConversionNotSupportedException. * Customize the response for ConversionNotSupportedException.
* This method delegates to {@link #handleExceptionInternal(Exception, Object, HttpHeaders, HttpStatus, WebRequest)}. * <p>This method delegates to {@link #handleExceptionInternal}.
* @param ex the exception * @param ex the exception
* @param headers the headers to be written to the response * @param headers the headers to be written to the response
* @param status the selected response status * @param status the selected response status
@ -339,7 +340,7 @@ public abstract class ResponseEntityExceptionHandler {
/** /**
* Customize the response for TypeMismatchException. * Customize the response for TypeMismatchException.
* This method delegates to {@link #handleExceptionInternal(Exception, Object, HttpHeaders, HttpStatus, WebRequest)}. * <p>This method delegates to {@link #handleExceptionInternal}.
* @param ex the exception * @param ex the exception
* @param headers the headers to be written to the response * @param headers the headers to be written to the response
* @param status the selected response status * @param status the selected response status
@ -354,7 +355,7 @@ public abstract class ResponseEntityExceptionHandler {
/** /**
* Customize the response for HttpMessageNotReadableException. * Customize the response for HttpMessageNotReadableException.
* This method delegates to {@link #handleExceptionInternal(Exception, Object, HttpHeaders, HttpStatus, WebRequest)}. * <p>This method delegates to {@link #handleExceptionInternal}.
* @param ex the exception * @param ex the exception
* @param headers the headers to be written to the response * @param headers the headers to be written to the response
* @param status the selected response status * @param status the selected response status
@ -369,7 +370,7 @@ public abstract class ResponseEntityExceptionHandler {
/** /**
* Customize the response for HttpMessageNotWritableException. * Customize the response for HttpMessageNotWritableException.
* This method delegates to {@link #handleExceptionInternal(Exception, Object, HttpHeaders, HttpStatus, WebRequest)}. * <p>This method delegates to {@link #handleExceptionInternal}.
* @param ex the exception * @param ex the exception
* @param headers the headers to be written to the response * @param headers the headers to be written to the response
* @param status the selected response status * @param status the selected response status
@ -384,7 +385,7 @@ public abstract class ResponseEntityExceptionHandler {
/** /**
* Customize the response for MethodArgumentNotValidException. * Customize the response for MethodArgumentNotValidException.
* This method delegates to {@link #handleExceptionInternal(Exception, Object, HttpHeaders, HttpStatus, WebRequest)}. * <p>This method delegates to {@link #handleExceptionInternal}.
* @param ex the exception * @param ex the exception
* @param headers the headers to be written to the response * @param headers the headers to be written to the response
* @param status the selected response status * @param status the selected response status
@ -399,7 +400,7 @@ public abstract class ResponseEntityExceptionHandler {
/** /**
* Customize the response for MissingServletRequestPartException. * Customize the response for MissingServletRequestPartException.
* This method delegates to {@link #handleExceptionInternal(Exception, Object, HttpHeaders, HttpStatus, WebRequest)}. * <p>This method delegates to {@link #handleExceptionInternal}.
* @param ex the exception * @param ex the exception
* @param headers the headers to be written to the response * @param headers the headers to be written to the response
* @param status the selected response status * @param status the selected response status
@ -414,7 +415,7 @@ public abstract class ResponseEntityExceptionHandler {
/** /**
* Customize the response for BindException. * Customize the response for BindException.
* This method delegates to {@link #handleExceptionInternal(Exception, Object, HttpHeaders, HttpStatus, WebRequest)}. * <p>This method delegates to {@link #handleExceptionInternal}.
* @param ex the exception * @param ex the exception
* @param headers the headers to be written to the response * @param headers the headers to be written to the response
* @param status the selected response status * @param status the selected response status
@ -429,7 +430,7 @@ public abstract class ResponseEntityExceptionHandler {
/** /**
* Customize the response for NoHandlerFoundException. * Customize the response for NoHandlerFoundException.
* This method delegates to {@link #handleExceptionInternal(Exception, Object, HttpHeaders, HttpStatus, WebRequest)}. * <p>This method delegates to {@link #handleExceptionInternal}.
* @param ex the exception * @param ex the exception
* @param headers the headers to be written to the response * @param headers the headers to be written to the response
* @param status the selected response status * @param status the selected response status