Introduced MvcUriComponentsBuilder to create URIs pointing to controller methods.

MvcUriComponentsBuilder allows creating URIs that point to Spring MVC
controller methods annotated with @RequestMapping. It builds them by
exposing a mock method invocation API similar to Mockito, records the
method invocations and thus builds up the URI by inspecting the mapping
annotations and the parameters handed into the method invocations.

Introduced a new SPI UriComponentsContributor that should be implemented 
by HandlerMethodArgumentResolvers that actually contribute path segments 
or query parameters to a URI. While the newly introduced 
MvcUriComponentsBuilder looks up those UriComponentsContributor instances 
from the MVC configuration.

The MvcUriComponentsBuilderFactory (name to be discussed - MvcUris maybe?) 
prevents the multiple lookups by keeping the UriComponentsBuilder 
instances in an instance variable. So an instance of the factory could 
be exposed as Spring bean or through a HandlerMethodArgumentResolver to 
be injected into Controller methods.

Issue: SPR-10665, SPR-8826

Author: odrotbohm

build.gradle

@@ -640,6 +640,7 @@ project("spring-webmvc") {
 
 	dependencies {
 		compile(project(":spring-core"))
+		compile(files(project(":spring-core").objenesisRepackJar))
 		compile(project(":spring-expression"))
 		compile(project(":spring-beans"))
 		compile(project(":spring-web"))

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

@@ -0,0 +1,125 @@
+/*
+ * Copyright 2012-2013 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.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.core;
+
+import java.lang.annotation.Annotation;
+import java.lang.reflect.AnnotatedElement;
+import java.lang.reflect.Method;
+
+import org.springframework.core.annotation.AnnotationUtils;
+import org.springframework.util.Assert;
+
+/**
+ * Simply helper to reference a dedicated attribute of an {@link Annotation}.
+ * 
+ * @author Oliver Gierke
+ */
+public class AnnotationAttribute {
+
+	private final Class<? extends Annotation> annotationType;
+
+	private final String attributeName;
+
+	/**
+	 * Creates a new {@link AnnotationAttribute} to the {@code value} attribute of the
+	 * given {@link Annotation} type.
+	 * 
+	 * @param annotationType must not be {@literal null}.
+	 */
+	public AnnotationAttribute(Class<? extends Annotation> annotationType) {
+		this(annotationType, null);
+	}
+
+	/**
+	 * Creates a new {@link AnnotationAttribute} for the given {@link Annotation} type and
+	 * annotation attribute name.
+	 * 
+	 * @param annotationType must not be {@literal null}.
+	 * @param attributeName can be {@literal null}, defaults to {@code value}.
+	 */
+	public AnnotationAttribute(Class<? extends Annotation> annotationType,
+			String attributeName) {
+
+		Assert.notNull(annotationType);
+
+		this.annotationType = annotationType;
+		this.attributeName = attributeName;
+	}
+
+	/**
+	 * Returns the annotation type.
+	 * 
+	 * @return the annotationType
+	 */
+	public Class<? extends Annotation> getAnnotationType() {
+		return annotationType;
+	}
+
+	/**
+	 * Reads the {@link Annotation} attribute's value from the given
+	 * {@link MethodParameter}.
+	 * 
+	 * @param parameter must not be {@literal null}.
+	 * @return
+	 */
+	public Object getValueFrom(MethodParameter parameter) {
+
+		Assert.notNull(parameter, "MethodParameter must not be null!");
+		Annotation annotation = parameter.getParameterAnnotation(annotationType);
+		return annotation == null ? null : getValueFrom(annotation);
+	}
+
+	/**
+	 * Reads the {@link Annotation} attribute's value from the given type.
+	 * 
+	 * @param type must not be {@literal null}.
+	 * @return
+	 */
+	public Object findValueOn(Class<?> type) {
+
+		Assert.notNull(type, "Type must not be null!");
+		Annotation annotation = AnnotationUtils.findAnnotation(type, annotationType);
+		return annotation == null ? null : getValueFrom(annotation);
+	}
+
+	public Object findValueOn(Method method) {
+
+		Assert.notNull(method, "Method must nor be null!");
+		Annotation annotation = AnnotationUtils.findAnnotation(method, annotationType);
+		return annotation == null ? null : getValueFrom(annotation);
+	}
+
+	public Object getValueFrom(AnnotatedElement element) {
+
+		Assert.notNull(element, "Annotated element must not be null!");
+		Annotation annotation = AnnotationUtils.getAnnotation(element, annotationType);
+		return annotation == null ? null : getValueFrom(annotation);
+	}
+
+	/**
+	 * Returns the {@link Annotation} attribute's value from the given {@link Annotation}.
+	 * 
+	 * @param annotation must not be {@literal null}.
+	 * @return
+	 */
+	public Object getValueFrom(Annotation annotation) {
+
+		Assert.notNull(annotation, "Annotation must not be null!");
+		return attributeName == null ? AnnotationUtils.getValue(annotation)
+				: AnnotationUtils.getValue(annotation, attributeName);
+	}
+}

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

@@ -0,0 +1,170 @@
+/*
+ * Copyright 2012-2013 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.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.core;
+
+import java.lang.annotation.Annotation;
+import java.lang.reflect.Method;
+import java.util.ArrayList;
+import java.util.List;
+
+import org.springframework.util.Assert;
+
+/**
+ * Value object to represent {@link MethodParameters} to allow to easily find the ones
+ * with a given annotation.
+ * 
+ * @author Oliver Gierke
+ */
+public class MethodParameters {
+
+	private static final ParameterNameDiscoverer DISCOVERER = new LocalVariableTableParameterNameDiscoverer();
+
+	private final List<MethodParameter> parameters;
+
+	/**
+	 * Creates a new {@link MethodParameters} from the given {@link Method}.
+	 * 
+	 * @param method must not be {@literal null}.
+	 */
+	public MethodParameters(Method method) {
+		this(method, null);
+	}
+
+	/**
+	 * Creates a new {@link MethodParameters} for the given {@link Method} and
+	 * {@link AnnotationAttribute}. If the latter is given, method parameter names will be
+	 * looked up from the annotation attribute if present.
+	 * 
+	 * @param method must not be {@literal null}.
+	 * @param namingAnnotation can be {@literal null}.
+	 */
+	public MethodParameters(Method method, AnnotationAttribute namingAnnotation) {
+
+		Assert.notNull(method);
+		this.parameters = new ArrayList<MethodParameter>();
+
+		for (int i = 0; i < method.getParameterTypes().length; i++) {
+
+			MethodParameter parameter = new AnnotationNamingMethodParameter(method, i,
+					namingAnnotation);
+			parameter.initParameterNameDiscovery(DISCOVERER);
+			parameters.add(parameter);
+		}
+	}
+
+	/**
+	 * Returns all {@link MethodParameter}s.
+	 * 
+	 * @return
+	 */
+	public List<MethodParameter> getParameters() {
+		return parameters;
+	}
+
+	/**
+	 * Returns the {@link MethodParameter} with the given name or {@literal null} if none
+	 * found.
+	 * 
+	 * @param name must not be {@literal null} or empty.
+	 * @return
+	 */
+	public MethodParameter getParameter(String name) {
+
+		Assert.hasText(name, "Parameter name must not be null!");
+
+		for (MethodParameter parameter : parameters) {
+			if (name.equals(parameter.getParameterName())) {
+				return parameter;
+			}
+		}
+
+		return null;
+	}
+
+	/**
+	 * Returns all {@link MethodParameter}s annotated with the given annotation type.
+	 * 
+	 * @param annotation must not be {@literal null}.
+	 * @return
+	 */
+	public List<MethodParameter> getParametersWith(Class<? extends Annotation> annotation) {
+
+		Assert.notNull(annotation);
+		List<MethodParameter> result = new ArrayList<MethodParameter>();
+
+		for (MethodParameter parameter : getParameters()) {
+			if (parameter.hasParameterAnnotation(annotation)) {
+				result.add(parameter);
+			}
+		}
+
+		return result;
+	}
+
+	/**
+	 * Custom {@link MethodParameter} extension that will favor the name configured in the
+	 * {@link AnnotationAttribute} if set over discovering it.
+	 * 
+	 * @author Oliver Gierke
+	 */
+	private static class AnnotationNamingMethodParameter extends MethodParameter {
+
+		private final AnnotationAttribute attribute;
+
+		private String name;
+
+		/**
+		 * Creates a new {@link AnnotationNamingMethodParameter} for the given
+		 * {@link Method}'s parameter with the given index.
+		 * 
+		 * @param method must not be {@literal null}.
+		 * @param parameterIndex
+		 * @param attribute can be {@literal null}
+		 */
+		public AnnotationNamingMethodParameter(Method method, int parameterIndex,
+				AnnotationAttribute attribute) {
+
+			super(method, parameterIndex);
+			this.attribute = attribute;
+
+		}
+
+		/*
+		 * (non-Javadoc)
+		 * 
+		 * @see org.springframework.core.MethodParameter#getParameterName()
+		 */
+		@Override
+		public String getParameterName() {
+
+			if (name != null) {
+				return name;
+			}
+
+			if (attribute != null) {
+				Object foundName = attribute.getValueFrom(this);
+				if (foundName != null) {
+					name = foundName.toString();
+					return name;
+				}
+			}
+
+			name = super.getParameterName();
+			return name;
+		}
+	}
+}

spring-core/src/test/java/org/springframework/core/AnnotationAttributeUnitTests.java

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2002-2013 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.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.core;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+import org.junit.Test;
+
+import static org.hamcrest.CoreMatchers.*;
+import static org.junit.Assert.*;
+
+/**
+ * Unit tests for {@link AnnotationAttribute}.
+ * 
+ * @author Oliver Gierke
+ */
+public class AnnotationAttributeUnitTests {
+
+	AnnotationAttribute valueAttribute = new AnnotationAttribute(MyAnnotation.class);
+
+	AnnotationAttribute nonValueAttribute = new AnnotationAttribute(MyAnnotation.class,
+			"nonValue");
+
+	@Test
+	public void readsAttributesFromType() {
+
+		assertThat(valueAttribute.findValueOn(Sample.class), is((Object) "foo"));
+		assertThat(nonValueAttribute.findValueOn(Sample.class), is((Object) "bar"));
+	}
+
+	@Test
+	public void findsAttributesFromSubType() {
+		assertThat(valueAttribute.findValueOn(SampleSub.class), is((Object) "foo"));
+	}
+
+	@Test
+	public void doesNotGetValueFromSubTyp() {
+		assertThat(valueAttribute.getValueFrom(SampleSub.class), is(nullValue()));
+	}
+
+	@Retention(RetentionPolicy.RUNTIME)
+	public static @interface MyAnnotation {
+
+		String value() default "";
+
+		String nonValue() default "";
+	}
+
+	@MyAnnotation(value = "foo", nonValue = "bar")
+	static class Sample {
+
+	}
+
+	static class SampleSub extends Sample {
+
+	}
+}