Polish Javadoc for MVC exception handling classes

spring-webmvc/src/main/java/org/springframework/web/servlet/HandlerExceptionResolver.java

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

spring-webmvc/src/main/java/org/springframework/web/servlet/handler/AbstractHandlerExceptionResolver.java

@@ -30,11 +30,13 @@ import org.springframework.web.servlet.ModelAndView;
 /**
  * Abstract base class for {@link HandlerExceptionResolver} implementations.
  *
- * <p>Provides a set of mapped handlers that the resolver should map to,
- * and the {@link Ordered} implementation.
+ * <p>Supports mapped {@linkplain #setMappedHandlers handlers} and
+ * {@linkplain #setMappedHandlerClasses handler classes} that the resolver
+ * should be applied to and implements the {@link Ordered} interface.
  *
  * @author Arjen Poutsma
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 3.0
  */
 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.
-	 * 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>The exception mappings and the default error view will only apply to the specified handlers.
+	 * <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
-	 * 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.
 	 */
 	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.
-	 * 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.
-	 * <p>If no handlers and handler classes are set, the exception mappings and the default error
+	 * <p>The exception mappings and the default error view will only apply to handlers of the
+	 * specified types; the specified types may be interfaces or superclasses of handlers as well.
+	 * <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
-	 * 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.
 	 */
 	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
-	 * 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.
 	 * <p>Default is warn logging using the {@link AbstractHandlerExceptionResolver} class name derived logger.
-	 * Set to {@code null} to disable warn logging.
-	 * Override the {@link #logException} method for custom logging.
+	 * <p>Set to {@code null} to disable warn logging.
+	 * <p>Override the {@link #logException} method for custom logging.
 	 * @see org.apache.commons.logging.LogFactory#getLog(String)
 	 * @see org.apache.log4j.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
-	 * by this HandlerExceptionResolver.
-	 * <p>Default is "false". Switch this to "true" in order to automatically
-	 * generate HTTP response headers that suppress response caching.
+	 * by this exception resolver.
+	 * <p>Default is {@code false}. Switch this to {@code true} in order to
+	 * automatically generate HTTP response headers that suppress response caching.
 	 */
 	public void setPreventResponseCaching(boolean preventResponseCaching) {
 		this.preventResponseCaching = preventResponseCaching;
 	}
 
-
 	/**
-	 * Checks whether this resolver is supposed to apply (i.e. the handler matches
-	 * in case of "mappedHandlers" having been specified), then delegates to the
-	 * {@link #doResolveException} template method.
+	 * Check whether this resolver is supposed to apply (i.e. if the supplied handler
+	 * matches any of the configured {@linkplain #setMappedHandlers handlers} or
+	 * {@linkplain #setMappedHandlerClasses handler classes}), and then delegate
+	 * to the {@link #doResolveException} template method.
 	 */
 	@Override
 	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.
-	 * <p>The default implementation checks against the specified mapped handlers
-	 * and handler classes, if any.
+	 * <p>The default implementation checks against the configured
+	 * {@linkplain #setMappedHandlers handlers} and
+	 * {@linkplain #setMappedHandlerClasses handler classes}, if any.
 	 * @param request current HTTP request
 	 * @param handler the executed handler, or {@code null} if none chosen
 	 * 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");
 	}
 
-
 	/**
-	 * Actually resolve the given exception that got thrown during on handler execution,
-	 * returning a ModelAndView that represents a specific error page if appropriate.
+	 * Actually resolve the given exception that got thrown during handler execution,
+	 * 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.
 	 * Note that this template method will be invoked <i>after</i> checking whether this
 	 * 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
 	 * of the exception (for example, if multipart resolution failed)
 	 * @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,
 			HttpServletResponse response, Object handler, Exception ex);

spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/JsonViewResponseBodyAdvice.java

@@ -32,7 +32,7 @@ import org.springframework.http.server.ServerHttpResponse;
  *
  * <p>The serialization view specified in the annotation will be passed in to the
  * {@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
  * be specified, the use for a response body advice is only supported with

spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/ResponseBodyAdvice.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.
@@ -24,7 +24,7 @@ import org.springframework.http.server.ServerHttpResponse;
 
 /**
  * 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}.
  *
  * <p>Implementations may be may be registered directly with

spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/ResponseEntityExceptionHandler.java

@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package org.springframework.web.servlet.mvc.method.annotation;
 
 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
  * {@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
  * {@link HttpMessageConverter message converters}. This is in contrast to
  * {@link org.springframework.web.servlet.mvc.support.DefaultHandlerExceptionResolver
  * DefaultHandlerExceptionResolver} which returns a {@code ModelAndView} instead.
  *
  * <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.
  *
  * <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
  * @since 3.2
  *
+ * @see #handleException(Exception, WebRequest)
  * @see org.springframework.web.servlet.mvc.support.DefaultHandlerExceptionResolver
  */
 public abstract class ResponseEntityExceptionHandler {
@@ -92,7 +94,7 @@ public abstract class ResponseEntityExceptionHandler {
 	 * @param ex the target exception
 	 * @param request the current request
 	 */
-	@ExceptionHandler(value={
+	@ExceptionHandler({
 			NoSuchRequestHandlingMethodException.class,
 			HttpRequestMethodNotSupportedException.class,
 			HttpMediaTypeNotSupportedException.class,
@@ -182,7 +184,7 @@ public abstract class ResponseEntityExceptionHandler {
 
 	/**
 	 * 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 body the body to use for 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.
-	 * This method logs a warning and delegates to
-	 * {@link #handleExceptionInternal(Exception, Object, HttpHeaders, HttpStatus, WebRequest)}.
+	 * <p>This method logs a warning and delegates to {@link #handleExceptionInternal}.
 	 * @param ex the exception
 	 * @param headers the headers to be written to the response
 	 * @param status the selected response status
@@ -219,8 +220,8 @@ public abstract class ResponseEntityExceptionHandler {
 
 	/**
 	 * Customize the response for HttpRequestMethodNotSupportedException.
-	 * This method logs a warning, sets the "Allow" header, and delegates to
-	 * {@link #handleExceptionInternal(Exception, Object, HttpHeaders, HttpStatus, WebRequest)}.
+	 * <p>This method logs a warning, sets the "Allow" header, and delegates to
+	 * {@link #handleExceptionInternal}.
 	 * @param ex the exception
 	 * @param headers the headers to be written to the response
 	 * @param status the selected response status
@@ -242,8 +243,8 @@ public abstract class ResponseEntityExceptionHandler {
 
 	/**
 	 * Customize the response for HttpMediaTypeNotSupportedException.
-	 * This method sets the "Accept" header and delegates to
-	 * {@link #handleExceptionInternal(Exception, Object, HttpHeaders, HttpStatus, WebRequest)}.
+	 * <p>This method sets the "Accept" header and delegates to
+	 * {@link #handleExceptionInternal}.
 	 * @param ex the exception
 	 * @param headers the headers to be written to the response
 	 * @param status the selected response status
@@ -263,7 +264,7 @@ public abstract class ResponseEntityExceptionHandler {
 
 	/**
 	 * 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 headers the headers to be written to the response
 	 * @param status the selected response status
@@ -278,7 +279,7 @@ public abstract class ResponseEntityExceptionHandler {
 
 	/**
 	 * 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 headers the headers to be written to the response
 	 * @param status the selected response status
@@ -294,7 +295,7 @@ public abstract class ResponseEntityExceptionHandler {
 
 	/**
 	 * 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 headers the headers to be written to the response
 	 * @param status the selected response status
@@ -309,7 +310,7 @@ public abstract class ResponseEntityExceptionHandler {
 
 	/**
 	 * 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 headers the headers to be written to the response
 	 * @param status the selected response status
@@ -324,7 +325,7 @@ public abstract class ResponseEntityExceptionHandler {
 
 	/**
 	 * 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 headers the headers to be written to the response
 	 * @param status the selected response status
@@ -339,7 +340,7 @@ public abstract class ResponseEntityExceptionHandler {
 
 	/**
 	 * 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 headers the headers to be written to the response
 	 * @param status the selected response status
@@ -354,7 +355,7 @@ public abstract class ResponseEntityExceptionHandler {
 
 	/**
 	 * 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 headers the headers to be written to the response
 	 * @param status the selected response status
@@ -369,7 +370,7 @@ public abstract class ResponseEntityExceptionHandler {
 
 	/**
 	 * 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 headers the headers to be written to the response
 	 * @param status the selected response status
@@ -384,7 +385,7 @@ public abstract class ResponseEntityExceptionHandler {
 
 	/**
 	 * 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 headers the headers to be written to the response
 	 * @param status the selected response status
@@ -399,7 +400,7 @@ public abstract class ResponseEntityExceptionHandler {
 
 	/**
 	 * 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 headers the headers to be written to the response
 	 * @param status the selected response status
@@ -414,7 +415,7 @@ public abstract class ResponseEntityExceptionHandler {
 
 	/**
 	 * 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 headers the headers to be written to the response
 	 * @param status the selected response status
@@ -429,7 +430,7 @@ public abstract class ResponseEntityExceptionHandler {
 
 	/**
 	 * 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 headers the headers to be written to the response
 	 * @param status the selected response status