Polish Javadoc for MVC exception handling classes

Author: sbrannen

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,32 +20,32 @@
 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
  */
 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
 	 * @param response current HTTP response
 	 * @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 @@
 /**
  * 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 int getOrder() {
 
 	/**
 	 * 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 void setMappedHandlers(Set<?> mappedHandlers) {
 
 	/**
 	 * 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 void setMappedHandlerClasses(Class<?>[] mappedHandlerClasses) {
 
 	/**
 	 * 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 void setWarnLogCategory(String loggerName) {
 
 	/**
 	 * 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 ModelAndView resolveException(HttpServletRequest request, HttpServletResp
 
 	/**
 	 * 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 @@ protected void preventCaching(HttpServletResponse response) {
 		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 @@ protected void preventCaching(HttpServletResponse response) {
 	 * @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 @@
  *
  * <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 @@
 
 /**
  * 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