Fix javadoc issue in ResponseEntityExceptionHandler

Issue: SPR-13869
(cherry picked from commit 73df50d)

Author: rstoyanchev

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2016 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.
@@ -13,13 +13,15 @@
  * 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;
 import java.util.Set;
 
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
+
 import org.springframework.beans.ConversionNotSupportedException;
 import org.springframework.beans.TypeMismatchException;
 import org.springframework.http.HttpHeaders;
@@ -43,53 +45,59 @@
 import org.springframework.web.context.request.WebRequest;
 import org.springframework.web.multipart.support.MissingServletRequestPartException;
 import org.springframework.web.servlet.mvc.multiaction.NoSuchRequestHandlingMethodException;
+import org.springframework.web.util.WebUtils;
 
 /**
  * A convenient base class for {@link ControllerAdvice @ControllerAdvice} classes
  * 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
- * Spring MVC exceptions that returns a {@code ResponseEntity} to be written with
- * {@link HttpMessageConverter message converters}. This is in contrast to
+ * <p>This base class provides an {@code @ExceptionHandler} method for handling
+ * internal Spring MVC exceptions. This method returns a {@code ResponseEntity}
+ * for writing to the response with a {@link HttpMessageConverter message converter}.
+ * in contrast to
  * {@link org.springframework.web.servlet.mvc.support.DefaultHandlerExceptionResolver
- * DefaultHandlerExceptionResolver} which returns a {@code ModelAndView} instead.
+ * DefaultHandlerExceptionResolver} which returns a
+ * {@link org.springframework.web.servlet.ModelAndView ModelAndView}.
  *
- * <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
- * {@code DefaultHandlerExceptionResolver} instead.
+ * <p>If there is no need to write error content to the response body, or when
+ * using view resolution (e.g., via {@code ContentNegotiatingViewResolver}),
+ * then {@code DefaultHandlerExceptionResolver} is good enough.
  *
  * <p>Note that in order for an {@code @ControllerAdvice} sub-class to be
  * detected, {@link ExceptionHandlerExceptionResolver} must be configured.
  *
  * @author Rossen Stoyanchev
  * @since 3.2
- *
+ * @see #handleException(Exception, WebRequest)
  * @see org.springframework.web.servlet.mvc.support.DefaultHandlerExceptionResolver
  */
 public abstract class ResponseEntityExceptionHandler {
 
-	protected final Log logger = LogFactory.getLog(getClass());
-
 	/**
 	 * Log category to use when no mapped handler is found for a request.
 	 * @see #pageNotFoundLogger
 	 */
 	public static final String PAGE_NOT_FOUND_LOG_CATEGORY = "org.springframework.web.servlet.PageNotFound";
 
 	/**
-	 * Additional logger to use when no mapped handler is found for a request.
+	 * Specific logger to use when no mapped handler is found for a request.
 	 * @see #PAGE_NOT_FOUND_LOG_CATEGORY
 	 */
 	protected static final Log pageNotFoundLogger = LogFactory.getLog(PAGE_NOT_FOUND_LOG_CATEGORY);
 
+	/**
+	 * Common logger for use in subclasses.
+	 */
+	protected final Log logger = LogFactory.getLog(getClass());
+
 
 	/**
 	 * Provides handling for standard Spring MVC exceptions.
 	 * @param ex the target exception
 	 * @param request the current request
 	 */
-	@ExceptionHandler(value={
+	@ExceptionHandler({
 			NoSuchRequestHandlingMethodException.class,
 			HttpRequestMethodNotSupportedException.class,
 			HttpMediaTypeNotSupportedException.class,
@@ -105,9 +113,7 @@ public abstract class ResponseEntityExceptionHandler {
 			BindException.class
 		})
 	public final ResponseEntity<Object> handleException(Exception ex, WebRequest request) {
-
 		HttpHeaders headers = new HttpHeaders();
-
 		if (ex instanceof NoSuchRequestHandlingMethodException) {
 			HttpStatus status = HttpStatus.NOT_FOUND;
 			return handleNoSuchRequestHandlingMethod((NoSuchRequestHandlingMethodException) ex, headers, status, request);
@@ -169,27 +175,27 @@ else if (ex instanceof BindException) {
 
 	/**
 	 * A single place to customize the response body of all Exception types.
-	 * This method returns {@code null} by default.
+	 * <p>The default implementation sets the {@link WebUtils#ERROR_EXCEPTION_ATTRIBUTE}
+	 * request attribute and creates a {@link ResponseEntity} from the given
+	 * body, headers, and status.
 	 * @param ex the exception
-	 * @param body the body to use for the response
-	 * @param headers the headers to be written to the response
-	 * @param status the selected response status
+	 * @param body the body for the response
+	 * @param headers the headers for the response
+	 * @param status the response status
 	 * @param request the current request
 	 */
 	protected ResponseEntity<Object> handleExceptionInternal(Exception ex, Object body,
 			HttpHeaders headers, HttpStatus status, WebRequest request) {
 
 		if (HttpStatus.INTERNAL_SERVER_ERROR.equals(status)) {
-			request.setAttribute("javax.servlet.error.exception", ex, WebRequest.SCOPE_REQUEST);
+			request.setAttribute(WebUtils.ERROR_EXCEPTION_ATTRIBUTE, ex, WebRequest.SCOPE_REQUEST);
 		}
-
 		return new ResponseEntity<Object>(body, headers, status);
 	}
 
 	/**
 	 * 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
@@ -206,8 +212,8 @@ protected ResponseEntity<Object> handleNoSuchRequestHandlingMethod(NoSuchRequest
 
 	/**
 	 * 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
@@ -223,14 +229,13 @@ protected ResponseEntity<Object> handleHttpRequestMethodNotSupported(HttpRequest
 		if (!supportedMethods.isEmpty()) {
 			headers.setAllow(supportedMethods);
 		}
-
 		return handleExceptionInternal(ex, null, headers, status, request);
 	}
 
 	/**
 	 * 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
@@ -250,7 +255,7 @@ protected ResponseEntity<Object> handleHttpMediaTypeNotSupported(HttpMediaTypeNo
 
 	/**
 	 * 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
@@ -265,7 +270,7 @@ protected ResponseEntity<Object> handleHttpMediaTypeNotAcceptable(HttpMediaTypeN
 
 	/**
 	 * 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
@@ -280,7 +285,7 @@ protected ResponseEntity<Object> handleMissingServletRequestParameter(MissingSer
 
 	/**
 	 * 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
@@ -295,7 +300,7 @@ protected ResponseEntity<Object> handleServletRequestBindingException(ServletReq
 
 	/**
 	 * 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
@@ -310,7 +315,7 @@ protected ResponseEntity<Object> handleConversionNotSupported(ConversionNotSuppo
 
 	/**
 	 * 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
@@ -325,7 +330,7 @@ protected ResponseEntity<Object> handleTypeMismatch(TypeMismatchException ex, Ht
 
 	/**
 	 * 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
@@ -340,7 +345,7 @@ protected ResponseEntity<Object> handleHttpMessageNotReadable(HttpMessageNotRead
 
 	/**
 	 * 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
@@ -355,7 +360,7 @@ protected ResponseEntity<Object> handleHttpMessageNotWritable(HttpMessageNotWrit
 
 	/**
 	 * 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
@@ -370,7 +375,7 @@ protected ResponseEntity<Object> handleMethodArgumentNotValid(MethodArgumentNotV
 
 	/**
 	 * 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
@@ -385,7 +390,7 @@ protected ResponseEntity<Object> handleMissingServletRequestPart(MissingServletR
 
 	/**
 	 * 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