Polishing

spring-core/src/main/java/org/springframework/core/annotation/AnnotationUtils.java

@@ -309,9 +309,9 @@ public abstract class AnnotationUtils {
 	 * compiler if the supplied element is a {@link Method}.
 	 * <p>Meta-annotations will be searched if the annotation is not
 	 * <em>present</em> on the supplied element.
-	 * @param annotatedElement the element to look for annotations on; never {@code null}
-	 * @param annotationType the annotation type to look for; never {@code null}
-	 * @return the annotations found or an empty set; never {@code null}
+	 * @param annotatedElement the element to look for annotations on
+	 * @param annotationType the annotation type to look for
+	 * @return the annotations found or an empty set (never {@code null})
 	 * @since 4.2
 	 * @see #getRepeatableAnnotations(AnnotatedElement, Class, Class)
 	 * @see #getDeclaredRepeatableAnnotations(AnnotatedElement, Class, Class)
@@ -339,13 +339,13 @@ public abstract class AnnotationUtils {
 	 * compiler if the supplied element is a {@link Method}.
 	 * <p>Meta-annotations will be searched if the annotation is not
 	 * <em>present</em> on the supplied element.
-	 * @param annotatedElement the element to look for annotations on; never {@code null}
-	 * @param annotationType the annotation type to look for; never {@code null}
+	 * @param annotatedElement the element to look for annotations on
+	 * @param annotationType the annotation type to look for
 	 * @param containerAnnotationType the type of the container that holds
 	 * the annotations; may be {@code null} if a container is not supported
 	 * or if it should be looked up via @{@link java.lang.annotation.Repeatable}
 	 * when running on Java 8 or higher
-	 * @return the annotations found or an empty set; never {@code null}
+	 * @return the annotations found or an empty set (never {@code null})
 	 * @since 4.2
 	 * @see #getRepeatableAnnotations(AnnotatedElement, Class)
 	 * @see #getDeclaredRepeatableAnnotations(AnnotatedElement, Class)
@@ -388,9 +388,9 @@ public abstract class AnnotationUtils {
 	 * compiler if the supplied element is a {@link Method}.
 	 * <p>Meta-annotations will be searched if the annotation is not
 	 * <em>present</em> on the supplied element.
-	 * @param annotatedElement the element to look for annotations on; never {@code null}
-	 * @param annotationType the annotation type to look for; never {@code null}
-	 * @return the annotations found or an empty set; never {@code null}
+	 * @param annotatedElement the element to look for annotations on
+	 * @param annotationType the annotation type to look for
+	 * @return the annotations found or an empty set (never {@code null})
 	 * @since 4.2
 	 * @see #getRepeatableAnnotations(AnnotatedElement, Class)
 	 * @see #getRepeatableAnnotations(AnnotatedElement, Class, Class)
@@ -419,13 +419,13 @@ public abstract class AnnotationUtils {
 	 * compiler if the supplied element is a {@link Method}.
 	 * <p>Meta-annotations will be searched if the annotation is not
 	 * <em>present</em> on the supplied element.
-	 * @param annotatedElement the element to look for annotations on; never {@code null}
-	 * @param annotationType the annotation type to look for; never {@code null}
+	 * @param annotatedElement the element to look for annotations on
+	 * @param annotationType the annotation type to look for
 	 * @param containerAnnotationType the type of the container that holds
 	 * the annotations; may be {@code null} if a container is not supported
 	 * or if it should be looked up via @{@link java.lang.annotation.Repeatable}
 	 * when running on Java 8 or higher
-	 * @return the annotations found or an empty set; never {@code null}
+	 * @return the annotations found or an empty set (never {@code null})
 	 * @since 4.2
 	 * @see #getRepeatableAnnotations(AnnotatedElement, Class)
 	 * @see #getRepeatableAnnotations(AnnotatedElement, Class, Class)
@@ -447,15 +447,15 @@ public abstract class AnnotationUtils {
 	 * compiler if the supplied element is a {@link Method}.
 	 * <p>Meta-annotations will be searched if the annotation is not
 	 * <em>present</em> on the supplied element.
-	 * @param annotatedElement the element to look for annotations on; never {@code null}
-	 * @param annotationType the annotation type to look for; never {@code null}
+	 * @param annotatedElement the element to look for annotations on
+	 * @param annotationType the annotation type to look for
 	 * @param containerAnnotationType the type of the container that holds
 	 * the annotations; may be {@code null} if a container is not supported
 	 * or if it should be looked up via @{@link java.lang.annotation.Repeatable}
 	 * when running on Java 8 or higher
 	 * @param declaredMode {@code true} if only declared annotations (i.e.,
 	 * directly or indirectly present) should be considered
-	 * @return the annotations found or an empty set; never {@code null}
+	 * @return the annotations found or an empty set (never {@code null})
 	 * @since 4.2
 	 * @see org.springframework.core.BridgeMethodResolver#findBridgedMethod
 	 * @see java.lang.annotation.Repeatable
@@ -497,8 +497,8 @@ public abstract class AnnotationUtils {
 	public static <A extends Annotation> A findAnnotation(AnnotatedElement annotatedElement, Class<A> annotationType) {
 		// Do NOT store result in the findAnnotationCache since doing so could break
 		// findAnnotation(Class, Class) and findAnnotation(Method, Class).
-		return synthesizeAnnotation(findAnnotation(annotatedElement, annotationType, new HashSet<Annotation>()),
-				annotatedElement);
+		return synthesizeAnnotation(
+				findAnnotation(annotatedElement, annotationType, new HashSet<Annotation>()), annotatedElement);
 	}
 
 	/**
@@ -660,7 +660,7 @@ public abstract class AnnotationUtils {
 	/**
 	 * Perform the actual work for {@link #findAnnotation(AnnotatedElement, Class)},
 	 * honoring the {@code synthesize} flag.
-	 * @param clazz the class to look for annotations on; never {@code null}
+	 * @param clazz the class to look for annotations on
 	 * @param annotationType the type of annotation to look for
 	 * @param synthesize {@code true} if the result should be
 	 * {@linkplain #synthesizeAnnotation(Annotation) synthesized}
@@ -860,7 +860,7 @@ public abstract class AnnotationUtils {
 	/**
 	 * Determine if an annotation of type {@code metaAnnotationType} is
 	 * <em>meta-present</em> on the supplied {@code annotationType}.
-	 * @param annotationType the annotation type to search on; never {@code null}
+	 * @param annotationType the annotation type to search on
 	 * @param metaAnnotationType the type of meta-annotation to search for
 	 * @return {@code true} if such an annotation is meta-present
 	 * @since 4.2.1
@@ -914,7 +914,7 @@ public abstract class AnnotationUtils {
 	 * However, the {@code Map} signature has been preserved for binary compatibility.
 	 * @param annotation the annotation to retrieve the attributes for
 	 * @return the Map of annotation attributes, with attribute names as keys and
-	 * corresponding attribute values as values; never {@code null}
+	 * corresponding attribute values as values (never {@code null})
 	 * @see #getAnnotationAttributes(AnnotatedElement, Annotation)
 	 * @see #getAnnotationAttributes(Annotation, boolean, boolean)
 	 * @see #getAnnotationAttributes(AnnotatedElement, Annotation, boolean, boolean)
@@ -934,7 +934,7 @@ public abstract class AnnotationUtils {
 	 * compatibility with {@link org.springframework.core.type.AnnotationMetadata})
 	 * or to preserve them as Class references
 	 * @return the Map of annotation attributes, with attribute names as keys and
-	 * corresponding attribute values as values; never {@code null}
+	 * corresponding attribute values as values (never {@code null})
 	 * @see #getAnnotationAttributes(Annotation, boolean, boolean)
 	 */
 	public static Map<String, Object> getAnnotationAttributes(Annotation annotation, boolean classValuesAsString) {
@@ -954,7 +954,7 @@ public abstract class AnnotationUtils {
 	 * {@link org.springframework.core.type.AnnotationMetadata}) or to preserve them as
 	 * {@code Annotation} instances
 	 * @return the annotation attributes (a specialized Map) with attribute names as keys
-	 * and corresponding attribute values as values; never {@code null}
+	 * and corresponding attribute values as values (never {@code null})
 	 * @since 3.1.1
 	 */
 	public static AnnotationAttributes getAnnotationAttributes(Annotation annotation, boolean classValuesAsString,
@@ -972,7 +972,7 @@ public abstract class AnnotationUtils {
 	 * may be {@code null} if unknown
 	 * @param annotation the annotation to retrieve the attributes for
 	 * @return the annotation attributes (a specialized Map) with attribute names as keys
-	 * and corresponding attribute values as values; never {@code null}
+	 * and corresponding attribute values as values (never {@code null})
 	 * @since 4.2
 	 * @see #getAnnotationAttributes(AnnotatedElement, Annotation, boolean, boolean)
 	 */
@@ -995,7 +995,7 @@ public abstract class AnnotationUtils {
 	 * {@link org.springframework.core.type.AnnotationMetadata}) or to preserve them as
 	 * {@code Annotation} instances
 	 * @return the annotation attributes (a specialized Map) with attribute names as keys
-	 * and corresponding attribute values as values; never {@code null}
+	 * and corresponding attribute values as values (never {@code null})
 	 * @since 4.2
 	 */
 	public static AnnotationAttributes getAnnotationAttributes(AnnotatedElement annotatedElement,
@@ -1037,7 +1037,7 @@ public abstract class AnnotationUtils {
 	 * @param mergeMode whether the annotation attributes should be created
 	 * using <em>merge mode</em>
 	 * @return the annotation attributes (a specialized Map) with attribute names as keys
-	 * and corresponding attribute values as values; never {@code null}
+	 * and corresponding attribute values as values (never {@code null})
 	 * @since 4.2
 	 * @see #postProcessAnnotationAttributes
 	 */
@@ -1296,7 +1296,7 @@ public abstract class AnnotationUtils {
 	 * {@link Map} that is an ideal candidate for this method's
 	 * {@code attributes} argument.
 	 * @param attributes the map of annotation attributes to synthesize
-	 * @param annotationType the type of annotation to synthesize; never {@code null}
+	 * @param annotationType the type of annotation to synthesize
 	 * @param annotatedElement the element that is annotated with the annotation
 	 * corresponding to the supplied attributes; may be {@code null} if unknown
 	 * @return the synthesized annotation, or {@code null} if the supplied attributes
@@ -1333,7 +1333,7 @@ public abstract class AnnotationUtils {
 	 * {@link #synthesizeAnnotation(Map, Class, AnnotatedElement)},
 	 * supplying an empty map for the source attribute values and {@code null}
 	 * for the {@link AnnotatedElement}.
-	 * @param annotationType the type of annotation to synthesize; never {@code null}
+	 * @param annotationType the type of annotation to synthesize
 	 * @return the synthesized annotation
 	 * @throws IllegalArgumentException if a required attribute is missing
 	 * @throws AnnotationConfigurationException if invalid configuration of
@@ -1422,7 +1422,7 @@ public abstract class AnnotationUtils {
 	 * <p>An empty return value implies that the annotation does not declare
 	 * any attribute aliases.
 	 * @param annotationType the annotation type to find attribute aliases in
-	 * @return a map containing attribute aliases; never {@code null}
+	 * @return a map containing attribute aliases (never {@code null})
 	 * @since 4.2
 	 */
 	static Map<String, List<String>> getAttributeAliasMap(Class<? extends Annotation> annotationType) {
@@ -1499,9 +1499,9 @@ public abstract class AnnotationUtils {
 	/**
 	 * Get the names of the aliased attributes configured via
 	 * {@link AliasFor @AliasFor} for the supplied annotation {@code attribute}.
-	 * @param attribute the attribute to find aliases for; never {@code null}
-	 * @return the names of the aliased attributes; never {@code null}, though
-	 * potentially <em>empty</em>
+	 * @param attribute the attribute to find aliases for
+	 * @return the names of the aliased attributes (never {@code null}, though
+	 * potentially <em>empty</em>)
 	 * @throws IllegalArgumentException if the supplied attribute method is
 	 * {@code null} or not from an annotation
 	 * @throws AnnotationConfigurationException if invalid configuration of
@@ -1549,7 +1549,7 @@ public abstract class AnnotationUtils {
 	 * @param annotationType the type in which to search for attribute methods;
 	 * never {@code null}
 	 * @return all annotation attribute methods in the specified annotation
-	 * type; never {@code null}, though potentially <em>empty</em>
+	 * type (never {@code null}, though potentially <em>empty</em>)
 	 * @since 4.2
 	 */
 	static List<Method> getAttributeMethods(Class<? extends Annotation> annotationType) {
@@ -1575,7 +1575,7 @@ public abstract class AnnotationUtils {
 	 * supplied {@code element}.
 	 * @param element the element to search on
 	 * @param annotationName the fully qualified class name of the annotation
-	 * type to find; never {@code null} or empty
+	 * type to find
 	 * @return the annotation if found; {@code null} otherwise
 	 * @since 4.2
 	 */
@@ -2126,10 +2126,10 @@ public abstract class AnnotationUtils {
 		 * one of the attributes has been declared while simultaneously ensuring
 		 * that at least one of the attributes has been declared.
 		 * @param aliasFor the {@code @AliasFor} annotation from which to retrieve
-		 * the aliased attribute name; never {@code null}
+		 * the aliased attribute name
 		 * @param attribute the attribute that is annotated with {@code @AliasFor},
-		 * used solely for building an exception message; never {@code null}
-		 * @return the name of the aliased attribute, never {@code null} or empty
+		 * used solely for building an exception message
+		 * @return the name of the aliased attribute (never {@code null} or empty)
 		 * @throws AnnotationConfigurationException if invalid configuration of
 		 * {@code @AliasFor} is detected
 		 * @since 4.2

spring-jdbc/src/main/java/org/springframework/jdbc/core/SqlParameter.java

 /*
- * 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.
@@ -43,7 +43,6 @@ public class SqlParameter {
 	/** Used for types that are user-named like: STRUCT, DISTINCT, JAVA_OBJECT, named array types */
 	private String typeName;
 
-
 	/** The scale to apply in case of a NUMERIC or DECIMAL type, if any */
 	private Integer scale;
 
@@ -126,7 +125,7 @@ public class SqlParameter {
 
 
 	/**
-	 * Return the name of the parameter.
+	 * Return the name of the parameter, or {@code null} if anonymous.
 	 */
 	public String getName() {
 		return this.name;

spring-jdbc/src/test/java/org/springframework/jdbc/core/simple/SimpleJdbcCallTests.java

@@ -105,8 +105,7 @@ public class SimpleJdbcCallTests {
 		adder.declareParameters(
 				new SqlParameter("amount", Types.INTEGER),
 				new SqlParameter("custid", Types.INTEGER),
-				new SqlOutParameter("newid",
-				Types.INTEGER));
+				new SqlOutParameter("newid", Types.INTEGER));
 		Number newId = adder.executeObject(Number.class, new MapSqlParameterSource().
 				addValue("amount", 1103).
 				addValue("custid", 3));
@@ -122,8 +121,7 @@ public class SimpleJdbcCallTests {
 		adder.declareParameters(
 				new SqlParameter("amount", Types.INTEGER),
 				new SqlParameter("custid", Types.INTEGER),
-				new SqlOutParameter("newid",
-				Types.INTEGER));
+				new SqlOutParameter("newid", Types.INTEGER));
 		Number newId = adder.executeObject(Number.class, 1103, 3);
 		assertEquals(4, newId.intValue());
 		verifyAddInvoiceWithoutMetaData(false);
@@ -230,12 +228,12 @@ public class SimpleJdbcCallTests {
 		verifyStatement(adder, "{call ADD_INVOICE(AMOUNT => ?, CUSTID => ?, NEWID => ?)}");
 	}
 
+
 	private void verifyStatement(SimpleJdbcCall adder, String expected) {
 		Assert.assertEquals("Incorrect call statement", expected, adder.getCallString());
 	}
 
-	private void initializeAddInvoiceWithoutMetaData(boolean isFunction)
-			throws SQLException {
+	private void initializeAddInvoiceWithoutMetaData(boolean isFunction) throws SQLException {
 		given(databaseMetaData.getDatabaseProductName()).willReturn("MyDB");
 		given(databaseMetaData.getUserName()).willReturn("me");
 		given(databaseMetaData.storesLowerCaseIdentifiers()).willReturn(true);
@@ -313,4 +311,5 @@ public class SimpleJdbcCallTests {
 		verify(proceduresResultSet).close();
 		verify(procedureColumnsResultSet).close();
 	}
+
 }

spring-messaging/src/main/java/org/springframework/messaging/handler/HandlerMethodSelector.java

 /*
- * Copyright 2002-2013 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.
@@ -37,8 +37,8 @@ import org.springframework.util.ReflectionUtils.MethodFilter;
 public abstract class HandlerMethodSelector {
 
 	/**
-	 * Selects handler methods for the given handler type. Callers of this method define handler methods
-	 * of interest through the {@link MethodFilter} parameter.
+	 * Select handler methods for the given handler type.
+	 * <p>Callers define handler methods of interest through the {@link MethodFilter} parameter.
 	 * @param handlerType the handler type to search handler methods on
 	 * @param handlerMethodFilter a {@link MethodFilter} to help recognize handler methods of interest
 	 * @return the selected methods, or an empty set

spring-messaging/src/main/java/org/springframework/messaging/handler/invocation/InvocableHandlerMethod.java

@@ -31,8 +31,8 @@ import org.springframework.messaging.handler.HandlerMethod;
 import org.springframework.util.ReflectionUtils;
 
 /**
- * Invokes the handler method for a given message after resolving its method argument
- * values through registered {@link HandlerMethodArgumentResolver}s.
+ * Provides a method for invoking the handler method for a given message after resolving its
+ * method argument values through registered {@link HandlerMethodArgumentResolver}s.
  *
  * <p>Use {@link #setMessageMethodArgumentResolvers(HandlerMethodArgumentResolver)}
  * to customize the list of argument resolvers.
@@ -94,18 +94,28 @@ public class InvocableHandlerMethod extends HandlerMethod {
 
 
 	/**
-	 * Invoke the method with the given message.
-	 * @throws Exception raised if no suitable argument resolver can be found,
-	 * or the method raised an exception
+	 * Invoke the method after resolving its argument values in the context of the given message.
+	 * <p>Argument values are commonly resolved through {@link HandlerMethodArgumentResolver}s.
+	 * The {@code providedArgs} parameter however may supply argument values to be used directly,
+	 * i.e. without argument resolution.
+	 * @param message the current message being processed
+	 * @param providedArgs "given" arguments matched by type, not resolved
+	 * @return the raw value returned by the invoked method
+	 * @exception Exception raised if no suitable argument resolver can be found,
+	 * or if the method raised an exception
 	 */
 	public Object invoke(Message<?> message, Object... providedArgs) throws Exception {
 		Object[] args = getMethodArgumentValues(message, providedArgs);
 		if (logger.isTraceEnabled()) {
-			logger.trace("Resolved arguments: " + Arrays.asList(args));
+			StringBuilder sb = new StringBuilder("Invoking [");
+			sb.append(getBeanType().getSimpleName()).append(".");
+			sb.append(getMethod().getName()).append("] method with arguments ");
+			sb.append(Arrays.asList(args));
+			logger.trace(sb.toString());
 		}
 		Object returnValue = doInvoke(args);
 		if (logger.isTraceEnabled()) {
-			logger.trace("Returned value: " + returnValue);
+			logger.trace("Method [" + getMethod().getName() + "] returned [" + returnValue + "]");
 		}
 		return returnValue;
 	}
@@ -137,8 +147,8 @@ public class InvocableHandlerMethod extends HandlerMethod {
 				}
 			}
 			if (args[i] == null) {
-				String error = getArgumentResolutionErrorMessage("No suitable resolver for argument", i);
-				throw new IllegalStateException(error);
+				String msg = getArgumentResolutionErrorMessage("No suitable resolver for argument", i);
+				throw new IllegalStateException(msg);
 			}
 		}
 		return args;
@@ -156,10 +166,11 @@ public class InvocableHandlerMethod extends HandlerMethod {
 	 * @param message error message to append the HandlerMethod details to
 	 */
 	protected String getDetailedErrorMessage(String message) {
-		return message + "\n" +
-				"HandlerMethod details: \n" +
-				"Controller [" + getBeanType().getName() + "]\n" +
-				"Method [" + getBridgedMethod().toGenericString() + "]\n";
+		StringBuilder sb = new StringBuilder(message).append("\n");
+		sb.append("HandlerMethod details: \n");
+		sb.append("Controller [").append(getBeanType().getName()).append("]\n");
+		sb.append("Method [").append(getBridgedMethod().toGenericString()).append("]\n");
+		return sb.toString();
 	}
 
 	/**

spring-web/src/main/java/org/springframework/web/method/support/InvocableHandlerMethod.java

@@ -56,17 +56,17 @@ public class InvocableHandlerMethod extends HandlerMethod {
 
 
 	/**
-	 * Create an instance from the given handler and method.
+	 * Create an instance from a {@code HandlerMethod}.
 	 */
-	public InvocableHandlerMethod(Object bean, Method method) {
-		super(bean, method);
+	public InvocableHandlerMethod(HandlerMethod handlerMethod) {
+		super(handlerMethod);
 	}
 
 	/**
-	 * Create an instance from a {@code HandlerMethod}.
+	 * Create an instance from a bean instance and a method.
 	 */
-	public InvocableHandlerMethod(HandlerMethod handlerMethod) {
-		super(handlerMethod);
+	public InvocableHandlerMethod(Object bean, Method method) {
+		super(bean, method);
 	}
 
 	/**
@@ -112,7 +112,7 @@ public class InvocableHandlerMethod extends HandlerMethod {
 	/**
 	 * Invoke the method after resolving its argument values in the context of the given request.
 	 * <p>Argument values are commonly resolved through {@link HandlerMethodArgumentResolver}s.
-	 * The {@code provideArgs} parameter however may supply argument values to be used directly,
+	 * The {@code providedArgs} parameter however may supply argument values to be used directly,
 	 * i.e. without argument resolution. Examples of provided argument values include a
 	 * {@link WebDataBinder}, a {@link SessionStatus}, or a thrown exception instance.
 	 * Provided argument values are checked before argument resolvers.
@@ -185,7 +185,8 @@ public class InvocableHandlerMethod extends HandlerMethod {
 	}
 
 	/**
-	 * Adds HandlerMethod details such as the controller type and method signature to the given error message.
+	 * Adds HandlerMethod details such as the controller type and method
+	 * signature to the given error message.
 	 * @param message error message to append the HandlerMethod details to
 	 */
 	protected String getDetailedErrorMessage(String message) {

spring-web/src/main/java/org/springframework/web/util/UriTemplate.java

 /*
- * 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.
@@ -29,10 +29,11 @@ import java.util.regex.Pattern;
 import org.springframework.util.Assert;
 
 /**
- * Represents a URI template. A URI template is a URI-like String that contains variables enclosed
- * by braces ({@code {}}), which can be expanded to produce an actual URI.
+ * Represents a URI template. A URI template is a URI-like String that contains variables
+ * enclosed by braces ({@code {}}), which can be expanded to produce an actual URI.
  *
- * <p>See {@link #expand(Map)}, {@link #expand(Object[])}, and {@link #match(String)} for example usages.
+ * <p>See {@link #expand(Map)}, {@link #expand(Object[])}, and {@link #match(String)}
+ * for example usages.
  *
  * @author Arjen Poutsma
  * @author Juergen Hoeller
@@ -48,6 +49,7 @@ public class UriTemplate implements Serializable {
 	/** Replaces template variables in the URI template. */
 	private static final String DEFAULT_VARIABLE_PATTERN = "(.*)";
 
+
 	private final UriComponents uriComponents;
 
 	private final List<String> variableNames;

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

@@ -119,6 +119,10 @@ public class ContentNegotiatingViewResolver extends WebApplicationObjectSupport
 		this.contentNegotiationManager = contentNegotiationManager;
 	}
 
+	/**
+	 * Return the {@link ContentNegotiationManager} to use to determine requested media types.
+	 * @since 4.1.9
+	 */
 	public ContentNegotiationManager getContentNegotiationManager() {
 		return this.contentNegotiationManager;
 	}