Revised validation javadoc

Issue: SPR-12655

Author: jhoeller

spring-web/src/main/java/org/springframework/web/method/annotation/ModelAttributeMethodProcessor.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.
@@ -21,6 +21,7 @@
 
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
+
 import org.springframework.beans.BeanUtils;
 import org.springframework.core.MethodParameter;
 import org.springframework.core.annotation.AnnotationUtils;
@@ -54,10 +55,11 @@
  */
 public class ModelAttributeMethodProcessor implements HandlerMethodArgumentResolver, HandlerMethodReturnValueHandler {
 
-	protected Log logger = LogFactory.getLog(this.getClass());
+	protected final Log logger = LogFactory.getLog(getClass());
 
 	private final boolean annotationNotRequired;
 
+
 	/**
 	 * @param annotationNotRequired if "true", non-simple method arguments and
 	 * return values are considered model attributes with or without a
@@ -67,10 +69,12 @@ public ModelAttributeMethodProcessor(boolean annotationNotRequired) {
 		this.annotationNotRequired = annotationNotRequired;
 	}
 
+
 	/**
-	 * @return true if the parameter is annotated with {@link ModelAttribute}
-	 * or in default resolution mode also if it is not a simple type.
+	 * Returns {@code true} if the parameter is annotated with {@link ModelAttribute}
+	 * or in default resolution mode, and also if it is not a simple type.
 	 */
+	@Override
 	public boolean supportsParameter(MethodParameter parameter) {
 		if (parameter.hasParameterAnnotation(ModelAttribute.class)) {
 			return true;
@@ -92,18 +96,16 @@ else if (this.annotationNotRequired) {
 	 * and the next method parameter is not of type {@link Errors}.
 	 * @throws Exception if WebDataBinder initialization fails.
 	 */
-	public final Object resolveArgument(
-			MethodParameter parameter, ModelAndViewContainer mavContainer,
-			NativeWebRequest request, WebDataBinderFactory binderFactory)
-			throws Exception {
+	public final Object resolveArgument(MethodParameter parameter, ModelAndViewContainer mavContainer,
+			NativeWebRequest webRequest, WebDataBinderFactory binderFactory) throws Exception {
 
 		String name = ModelFactory.getNameForParameter(parameter);
-		Object attribute = (mavContainer.containsAttribute(name)) ?
-				mavContainer.getModel().get(name) : createAttribute(name, parameter, binderFactory, request);
+		Object attribute = (mavContainer.containsAttribute(name) ?
+				mavContainer.getModel().get(name) : createAttribute(name, parameter, binderFactory, webRequest));
 
-		WebDataBinder binder = binderFactory.createBinder(request, attribute, name);
+		WebDataBinder binder = binderFactory.createBinder(webRequest, attribute, name);
 		if (binder.getTarget() != null) {
-			bindRequestParameters(binder, request);
+			bindRequestParameters(binder, webRequest);
 			validateIfApplicable(binder, parameter);
 			if (binder.getBindingResult().hasErrors()) {
 				if (isBindExceptionRequired(binder, parameter)) {
@@ -113,7 +115,6 @@ public final Object resolveArgument(
 		}
 
 		// Add resolved attribute and BindingResult at the end of the model
-
 		Map<String, Object> bindingResultModel = binder.getBindingResult().getModel();
 		mavContainer.removeAttributes(bindingResultModel);
 		mavContainer.addAllAttributes(bindingResultModel);
@@ -124,16 +125,16 @@ public final Object resolveArgument(
 	/**
 	 * Extension point to create the model attribute if not found in the model.
 	 * The default implementation uses the default constructor.
-	 * @param attributeName the name of the attribute, never {@code null}
-	 * @param parameter the method parameter
+	 * @param attributeName the name of the attribute (never {@code null})
+	 * @param methodParam the method parameter
 	 * @param binderFactory for creating WebDataBinder instance
 	 * @param request the current request
-	 * @return the created model attribute, never {@code null}
+	 * @return the created model attribute (never {@code null})
 	 */
-	protected Object createAttribute(String attributeName, MethodParameter parameter,
-			WebDataBinderFactory binderFactory,  NativeWebRequest request) throws Exception {
+	protected Object createAttribute(String attributeName, MethodParameter methodParam,
+			WebDataBinderFactory binderFactory, NativeWebRequest request) throws Exception {
 
-		return BeanUtils.instantiateClass(parameter.getParameterType());
+		return BeanUtils.instantiateClass(methodParam.getParameterType());
 	}
 
 	/**
@@ -147,15 +148,17 @@ protected void bindRequestParameters(WebDataBinder binder, NativeWebRequest requ
 
 	/**
 	 * Validate the model attribute if applicable.
-	 * <p>The default implementation checks for {@code @javax.validation.Valid}.
+	 * <p>The default implementation checks for {@code @javax.validation.Valid},
+	 * Spring's {@link org.springframework.validation.annotation.Validated},
+	 * and custom annotations whose name starts with "Valid".
 	 * @param binder the DataBinder to be used
-	 * @param parameter the method parameter
+	 * @param methodParam the method parameter
 	 */
-	protected void validateIfApplicable(WebDataBinder binder, MethodParameter parameter) {
-		Annotation[] annotations = parameter.getParameterAnnotations();
-		for (Annotation annot : annotations) {
-			if (annot.annotationType().getSimpleName().startsWith("Valid")) {
-				Object hints = AnnotationUtils.getValue(annot);
+	protected void validateIfApplicable(WebDataBinder binder, MethodParameter methodParam) {
+		Annotation[] annotations = methodParam.getParameterAnnotations();
+		for (Annotation ann : annotations) {
+			if (ann.annotationType().getSimpleName().startsWith("Valid")) {
+				Object hints = AnnotationUtils.getValue(ann);
 				binder.validate(hints instanceof Object[] ? (Object[]) hints : new Object[] {hints});
 				break;
 			}
@@ -165,14 +168,13 @@ protected void validateIfApplicable(WebDataBinder binder, MethodParameter parame
 	/**
 	 * Whether to raise a {@link BindException} on validation errors.
 	 * @param binder the data binder used to perform data binding
-	 * @param parameter the method argument
-	 * @return {@code true} if the next method argument is not of type {@link Errors}.
+	 * @param methodParam the method argument
+	 * @return {@code true} if the next method argument is not of type {@link Errors}
 	 */
-	protected boolean isBindExceptionRequired(WebDataBinder binder, MethodParameter parameter) {
-		int i = parameter.getParameterIndex();
-		Class<?>[] paramTypes = parameter.getMethod().getParameterTypes();
+	protected boolean isBindExceptionRequired(WebDataBinder binder, MethodParameter methodParam) {
+		int i = methodParam.getParameterIndex();
+		Class<?>[] paramTypes = methodParam.getMethod().getParameterTypes();
 		boolean hasBindingResult = (paramTypes.length > (i + 1) && Errors.class.isAssignableFrom(paramTypes[i + 1]));
-
 		return !hasBindingResult;
 	}
 
@@ -195,14 +197,13 @@ else if (this.annotationNotRequired) {
 	/**
 	 * Add non-null return values to the {@link ModelAndViewContainer}.
 	 */
-	public void handleReturnValue(
-			Object returnValue, MethodParameter returnType,
-			ModelAndViewContainer mavContainer, NativeWebRequest webRequest)
-			throws Exception {
+	public void handleReturnValue(Object returnValue, MethodParameter returnType,
+			ModelAndViewContainer mavContainer, NativeWebRequest webRequest) throws Exception {
 
 		if (returnValue != null) {
 			String name = ModelFactory.getNameForReturnValue(returnValue, returnType);
 			mavContainer.addAttribute(name, returnValue);
 		}
 	}
+
 }

spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/AbstractMessageConverterMethodArgumentResolver.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.
@@ -25,11 +25,11 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
-
 import javax.servlet.http.HttpServletRequest;
 
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
+
 import org.springframework.core.GenericTypeResolver;
 import org.springframework.core.MethodParameter;
 import org.springframework.http.HttpInputMessage;
@@ -59,12 +59,14 @@ public abstract class AbstractMessageConverterMethodArgumentResolver implements
 
 	protected final List<MediaType> allSupportedMediaTypes;
 
+
 	public AbstractMessageConverterMethodArgumentResolver(List<HttpMessageConverter<?>> messageConverters) {
 		Assert.notEmpty(messageConverters, "'messageConverters' must not be empty");
 		this.messageConverters = messageConverters;
 		this.allSupportedMediaTypes = getAllSupportedMediaTypes(messageConverters);
 	}
 
+
 	/**
 	 * Return the media types supported by all provided message converters sorted
 	 * by specificity via {@link MediaType#sortBySpecificity(List)}.
@@ -79,10 +81,10 @@ private static List<MediaType> getAllSupportedMediaTypes(List<HttpMessageConvert
 		return Collections.unmodifiableList(result);
 	}
 
+
 	/**
-	 * Creates the method argument value of the expected parameter type by
+	 * Create the method argument value of the expected parameter type by
 	 * reading from the given request.
-	 *
 	 * @param <T> the expected type of the argument value to be created
 	 * @param webRequest the current request
 	 * @param methodParam the method argument
@@ -99,9 +101,8 @@ protected <T> Object readWithMessageConverters(NativeWebRequest webRequest,
 	}
 
 	/**
-	 * Creates the method argument value of the expected parameter type by reading
+	 * Create the method argument value of the expected parameter type by reading
 	 * from the given HttpInputMessage.
-	 *
 	 * @param <T> the expected type of the argument value to be created
 	 * @param inputMessage the HTTP input message representing the current request
 	 * @param methodParam the method argument
@@ -123,43 +124,41 @@ protected <T> Object readWithMessageConverters(HttpInputMessage inputMessage,
 		catch (InvalidMediaTypeException ex) {
 			throw new HttpMediaTypeNotSupportedException(ex.getMessage());
 		}
-
 		if (contentType == null) {
 			contentType = MediaType.APPLICATION_OCTET_STREAM;
 		}
 
-				Class<?> contextClass = methodParam.getDeclaringClass();
-				Map<TypeVariable, Type> map = GenericTypeResolver.getTypeVariableMap(contextClass);
-				Class<T> targetClass = (Class<T>) GenericTypeResolver.resolveType(targetType, map);
-
-				for (HttpMessageConverter<?> converter : this.messageConverters) {
-					if (converter instanceof GenericHttpMessageConverter) {
-						GenericHttpMessageConverter genericConverter = (GenericHttpMessageConverter) converter;
-						if (genericConverter.canRead(targetType, contextClass, contentType)) {
-							if (logger.isDebugEnabled()) {
-								logger.debug("Reading [" + targetType + "] as \"" +
-										contentType + "\" using [" + converter + "]");
-							}
-							return genericConverter.read(targetType, contextClass, inputMessage);
-						}
+		Class<?> contextClass = methodParam.getDeclaringClass();
+		Map<TypeVariable, Type> map = GenericTypeResolver.getTypeVariableMap(contextClass);
+		Class<T> targetClass = (Class<T>) GenericTypeResolver.resolveType(targetType, map);
+
+		for (HttpMessageConverter<?> converter : this.messageConverters) {
+			if (converter instanceof GenericHttpMessageConverter) {
+				GenericHttpMessageConverter genericConverter = (GenericHttpMessageConverter) converter;
+				if (genericConverter.canRead(targetType, contextClass, contentType)) {
+					if (logger.isDebugEnabled()) {
+						logger.debug("Reading [" + targetType + "] as \"" +
+								contentType + "\" using [" + converter + "]");
 					}
-					if (targetClass != null) {
-						if (converter.canRead(targetClass, contentType)) {
-							if (logger.isDebugEnabled()) {
-								logger.debug("Reading [" + targetClass.getName() + "] as \"" +
-										contentType + "\" using [" + converter + "]");
-							}
-							return ((HttpMessageConverter<T>) converter).read(targetClass, inputMessage);
-						}
+					return genericConverter.read(targetType, contextClass, inputMessage);
+				}
+			}
+			if (targetClass != null) {
+				if (converter.canRead(targetClass, contentType)) {
+					if (logger.isDebugEnabled()) {
+						logger.debug("Reading [" + targetClass.getName() + "] as \"" +
+								contentType + "\" using [" + converter + "]");
 					}
+					return ((HttpMessageConverter<T>) converter).read(targetClass, inputMessage);
 				}
-
-				throw new HttpMediaTypeNotSupportedException(contentType, allSupportedMediaTypes);
 			}
+		}
+
+		throw new HttpMediaTypeNotSupportedException(contentType, this.allSupportedMediaTypes);
+	}
 
 	/**
-	 * Creates a new {@link HttpInputMessage} from the given {@link NativeWebRequest}.
-	 *
+	 * Create a new {@link HttpInputMessage} from the given {@link NativeWebRequest}.
 	 * @param webRequest the web request to create an input message from
 	 * @return the input message
 	 */