Polishing

(cherry picked from commit dd7ddc0)

Author: jhoeller

spring-core/src/main/java/org/springframework/core/MethodParameter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 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.
@@ -67,20 +67,22 @@ public class MethodParameter {
 
 
 	/**
-	 * Create a new MethodParameter for the given method, with nesting level 1.
+	 * Create a new {@code MethodParameter} for the given method, with nesting level 1.
 	 * @param method the Method to specify a parameter for
-	 * @param parameterIndex the index of the parameter
+	 * @param parameterIndex the index of the parameter: -1 for the method
+	 * return type; 0 for the first method parameter; 1 for the second method
+	 * parameter, etc.
 	 */
 	public MethodParameter(Method method, int parameterIndex) {
 		this(method, parameterIndex, 1);
 	}
 
 	/**
-	 * Create a new MethodParameter for the given method.
+	 * Create a new {@code MethodParameter} for the given method.
 	 * @param method the Method to specify a parameter for
-	 * @param parameterIndex the index of the parameter
-	 * (-1 for the method return type; 0 for the first method parameter,
-	 * 1 for the second method parameter, etc)
+	 * @param parameterIndex the index of the parameter: -1 for the method
+	 * return type; 0 for the first method parameter; 1 for the second method
+	 * parameter, etc.
 	 * @param nestingLevel the nesting level of the target type
 	 * (typically 1; e.g. in case of a List of Lists, 1 would indicate the
 	 * nested List, whereas 2 would indicate the element of the nested List)
@@ -158,31 +160,31 @@ public Constructor<?> getConstructor() {
 	}
 
 	/**
-	 * Returns the wrapped member.
+	 * Return the class that declares the underlying Method or Constructor.
+	 */
+	public Class<?> getDeclaringClass() {
+		return getMember().getDeclaringClass();
+	}
+
+	/**
+	 * Return the wrapped member.
 	 * @return the Method or Constructor as Member
 	 */
 	private Member getMember() {
 		return (this.method != null ? this.method : this.constructor);
 	}
 
 	/**
-	 * Returns the wrapped annotated element.
+	 * Return the wrapped annotated element.
 	 * @return the Method or Constructor as AnnotatedElement
 	 */
 	private AnnotatedElement getAnnotatedElement() {
 		return (this.method != null ? this.method : this.constructor);
 	}
 
-	/**
-	 * Return the class that declares the underlying Method or Constructor.
-	 */
-	public Class<?> getDeclaringClass() {
-		return getMember().getDeclaringClass();
-	}
-
 	/**
 	 * Return the index of the method/constructor parameter.
-	 * @return the parameter index (never negative)
+	 * @return the parameter index (-1 in case of the return type)
 	 */
 	public int getParameterIndex() {
 		return this.parameterIndex;
@@ -216,6 +218,7 @@ public Class<?> getParameterType() {
 	/**
 	 * Return the generic type of the method/constructor parameter.
 	 * @return the parameter type (never {@code null})
+	 * @since 3.0
 	 */
 	public Type getGenericParameterType() {
 		if (this.genericParameterType == null) {
@@ -231,6 +234,12 @@ public Type getGenericParameterType() {
 		return this.genericParameterType;
 	}
 
+	/**
+	 * Return the nested type of the method/constructor parameter.
+	 * @return the parameter type (never {@code null})
+	 * @since 3.1
+	 * @see #getNestingLevel()
+	 */
 	public Class<?> getNestedParameterType() {
 		if (this.nestingLevel > 1) {
 			Type type = getGenericParameterType();

spring-core/src/main/java/org/springframework/core/convert/ConversionService.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 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.
@@ -64,19 +64,19 @@ public interface ConversionService {
 
 	/**
 	 * Convert the given {@code source} to the specified {@code targetType}.
-	 * @param source the source object to convert (may be null)
+	 * @param source the source object to convert (may be {@code null})
 	 * @param targetType the target type to convert to (required)
 	 * @return the converted object, an instance of targetType
 	 * @throws ConversionException if a conversion exception occurred
-	 * @throws IllegalArgumentException if targetType is null
+	 * @throws IllegalArgumentException if targetType is {@code null}
 	 */
 	<T> T convert(Object source, Class<T> targetType);
 
 	/**
 	 * Convert the given {@code source} to the specified {@code targetType}.
 	 * The TypeDescriptors provide additional context about the source and target locations
 	 * where conversion will occur, often object fields or property locations.
-	 * @param source the source object to convert (may be null)
+	 * @param source the source object to convert (may be {@code null})
 	 * @param sourceType context about the source type to convert from
 	 * (may be {@code null} if source is {@code null})
 	 * @param targetType context about the target type to convert to (required)

spring-webmvc/src/main/java/org/springframework/web/servlet/AsyncHandlerInterceptor.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.
@@ -39,7 +39,6 @@
  *
  * @author Rossen Stoyanchev
  * @since 3.2
- *
  * @see org.springframework.web.context.request.async.WebAsyncManager
  * @see org.springframework.web.context.request.async.CallableProcessingInterceptor
  * @see org.springframework.web.context.request.async.DeferredResultProcessingInterceptor
@@ -48,19 +47,17 @@ public interface AsyncHandlerInterceptor extends HandlerInterceptor {
 
 	/**
 	 * Called instead of {@code postHandle} and {@code afterCompletion}, when
-	 * the a handler is being executed concurrently. Implementations may use the
-	 * provided request and response but should avoid modifying them in ways
-	 * that would conflict with the concurrent execution of the handler. A
-	 * typical use of this method would be to clean thread local variables.
-	 *
+	 * the a handler is being executed concurrently. Implementations may use
+	 * the provided request and response but should avoid modifying them in
+	 * ways that would conflict with the concurrent execution of the handler.
+	 * A typical use of this method would be to clean thread local variables.
 	 * @param request the current request
 	 * @param response the current response
 	 * @param handler handler (or {@link HandlerMethod}) that started async
 	 * execution, for type and/or instance examination
 	 * @throws Exception in case of errors
 	 */
-	void afterConcurrentHandlingStarted(
-			HttpServletRequest request, HttpServletResponse response, Object handler)
+	void afterConcurrentHandlingStarted(HttpServletRequest request, HttpServletResponse response, Object handler)
 			throws Exception;
 
 }

spring-webmvc/src/main/java/org/springframework/web/servlet/HandlerInterceptor.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.
@@ -33,8 +33,8 @@
  * or common handler behavior like locale or theme changes. Its main purpose
  * is to allow for factoring out repetitive handler code.
  *
- * <p>In an async processing scenario, the handler may be executed in a separate
- * thread while the main thread exits without rendering or invoking the
+ * <p>In an asynchronous processing scenario, the handler may be executed in a
+ * separate thread while the main thread exits without rendering or invoking the
  * {@code postHandle} and {@code afterCompletion} callbacks. When concurrent
  * handler execution completes, the request is dispatched back in order to
  * proceed with rendering the model and all methods of this contract are invoked
@@ -48,7 +48,7 @@
  * in the application context, referenced by the mapping bean definition
  * via its "interceptors" property (in XML: a &lt;list&gt; of &lt;ref&gt;).
  *
- * <p>HandlerInterceptor is basically similar to a Servlet 2.3 Filter, but in
+ * <p>HandlerInterceptor is basically similar to a Servlet Filter, but in
  * contrast to the latter it just allows custom pre-processing with the option
  * of prohibiting the execution of the handler itself, and custom post-processing.
  * Filters are more powerful, for example they allow for exchanging the request
@@ -81,6 +81,9 @@ public interface HandlerInterceptor {
 	 * 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.
+	 * <p><strong>Note:</strong> 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
@@ -100,16 +103,18 @@ boolean preHandle(HttpServletRequest request, HttpServletResponse response, Obje
 	 * 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.
+	 * <p><strong>Note:</strong> 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
+	 * @param handler handler (or {@link HandlerMethod}) that started asynchronous
 	 * execution, for type and/or instance examination
 	 * @param modelAndView the {@code ModelAndView} that the handler returned
 	 * (can also be {@code null})
 	 * @throws Exception in case of errors
 	 */
-	void postHandle(
-			HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView)
+	void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView)
 			throws Exception;
 
 	/**
@@ -121,15 +126,17 @@ void postHandle(
 	 * <p>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.
+	 * <p><strong>Note:</strong> 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
+	 * @param handler handler (or {@link HandlerMethod}) that started asynchronous
 	 * execution, for type and/or instance examination
 	 * @param ex exception thrown on handler execution, if any
 	 * @throws Exception in case of errors
 	 */
-	void afterCompletion(
-			HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex)
+	void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex)
 			throws Exception;
 
 }

spring-webmvc/src/main/java/org/springframework/web/servlet/handler/AbstractHandlerMethodExceptionResolver.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.
@@ -34,7 +34,7 @@ public abstract class AbstractHandlerMethodExceptionResolver extends AbstractHan
 
 	/**
 	 * Checks if the handler is a {@link HandlerMethod} and then delegates to the
-	 * base class implementation of {@link #shouldApplyTo(HttpServletRequest, Object)}
+	 * base class implementation of {@code #shouldApplyTo(HttpServletRequest, Object)}
 	 * passing the bean of the {@code HandlerMethod}. Otherwise returns {@code false}.
 	 */
 	@Override
@@ -54,8 +54,7 @@ else if (handler instanceof HandlerMethod) {
 
 	@Override
 	protected final ModelAndView doResolveException(
-			HttpServletRequest request, HttpServletResponse response,
-			Object handler, Exception ex) {
+			HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
 
 		return doResolveHandlerMethodException(request, response, (HandlerMethod) handler, ex);
 	}
@@ -75,7 +74,6 @@ protected final ModelAndView doResolveException(
 	 * @return a corresponding ModelAndView to forward to, or {@code null} for default processing
 	 */
 	protected abstract ModelAndView doResolveHandlerMethodException(
-			HttpServletRequest request, HttpServletResponse response,
-			HandlerMethod handlerMethod, Exception ex);
+			HttpServletRequest request, HttpServletResponse response, HandlerMethod handlerMethod, Exception ex);
 
 }