org.springframework.web.servlet.mvc.method.annotation

Class MvcUriComponentsBuilder

java.lang.Object

org.springframework.web.servlet.mvc.method.annotation.MvcUriComponentsBuilder

public class MvcUriComponentsBuilder
extends java.lang.Object

Creates instances of UriComponentsBuilder by pointing to Spring MVC controllers and @RequestMapping methods.

The static fromXxx(...) methods prepare links relative to the current request as determined by a call to ServletUriComponentsBuilder.fromCurrentServletMapping().

The static fromXxx(UriComponentsBuilder,...) methods can be given the baseUrl when operating outside the context of a request.

You can also create an MvcUriComponentsBuilder instance with a baseUrl via relativeTo(org.springframework.web.util.UriComponentsBuilder) and then use the non-static withXxx(...) method variants.

Since:

4.0

Author:

Oliver Gierke, Rossen Stoyanchev, Sam Brannen

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static class	MvcUriComponentsBuilder.ControllerMethodInvocationInterceptor
static class	MvcUriComponentsBuilder.MethodArgumentBuilder
static interface	MvcUriComponentsBuilder.MethodInvocationInfo

Field Summary

Fields

Modifier and Type	Field and Description
private UriComponentsBuilder	baseUrl
private static CompositeUriComponentsContributor	defaultUriComponentsContributor
private static Log	logger
static java.lang.String	MVC_URI_COMPONENTS_CONTRIBUTOR_BEAN_NAME Well-known name for the CompositeUriComponentsContributor object in the bean factory.
private static SpringObjenesis	objenesis
private static ParameterNameDiscoverer	parameterNameDiscoverer
private static PathMatcher	pathMatcher

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	MvcUriComponentsBuilder(UriComponentsBuilder baseUrl) Default constructor.

Method Summary

Modifier and Type	Method and Description
private static UriComponents	applyContributors(UriComponentsBuilder builder, java.lang.reflect.Method method, java.lang.Object... args)
static <T> T	controller(java.lang.Class<T> controllerType) Return a "mock" controller instance.
static UriComponentsBuilder	fromController(java.lang.Class<?> controllerType) Create a UriComponentsBuilder from the mapping of a controller class and current request information including Servlet mapping.
static UriComponentsBuilder	fromController(UriComponentsBuilder builder, java.lang.Class<?> controllerType) An alternative to fromController(Class) that accepts a UriComponentsBuilder representing the base URL.
static MvcUriComponentsBuilder.MethodArgumentBuilder	fromMappingName(java.lang.String mappingName) Create a URL from the name of a Spring MVC controller method's request mapping.
static MvcUriComponentsBuilder.MethodArgumentBuilder	fromMappingName(UriComponentsBuilder builder, java.lang.String name) An alternative to fromMappingName(String) that accepts a UriComponentsBuilder representing the base URL.
static UriComponentsBuilder	fromMethod(java.lang.Class<?> controllerType, java.lang.reflect.Method method, java.lang.Object... args) Create a UriComponentsBuilder from the mapping of a controller method and an array of method argument values.
static UriComponentsBuilder	fromMethod(java.lang.reflect.Method method, java.lang.Object... args) Deprecated. as of 4.2 this is deprecated in favor of the overloaded method that also accepts a controllerType.
static UriComponentsBuilder	fromMethod(UriComponentsBuilder baseUrl, java.lang.Class<?> controllerType, java.lang.reflect.Method method, java.lang.Object... args) An alternative to fromMethod(java.lang.reflect.Method, Object...) that accepts a UriComponentsBuilder representing the base URL.
static UriComponentsBuilder	fromMethodCall(java.lang.Object info) Create a UriComponentsBuilder by invoking a "mock" controller method.
static UriComponentsBuilder	fromMethodCall(UriComponentsBuilder builder, java.lang.Object info) An alternative to fromMethodCall(Object) that accepts a UriComponentsBuilder representing the base URL.
private static UriComponentsBuilder	fromMethodInternal(UriComponentsBuilder baseUrl, java.lang.Class<?> controllerType, java.lang.reflect.Method method, java.lang.Object... args)
static UriComponentsBuilder	fromMethodName(java.lang.Class<?> controllerType, java.lang.String methodName, java.lang.Object... args) Create a UriComponentsBuilder from the mapping of a controller method and an array of method argument values.
static UriComponentsBuilder	fromMethodName(UriComponentsBuilder builder, java.lang.Class<?> controllerType, java.lang.String methodName, java.lang.Object... args) An alternative to fromMethodName(Class, String, Object...) that accepts a UriComponentsBuilder representing the base URL.
private static UriComponentsBuilder	getBaseUrlToUse(UriComponentsBuilder baseUrl)
private static CompositeUriComponentsContributor	getConfiguredUriComponentsContributor()
private static java.lang.reflect.Method	getMethod(java.lang.Class<?> controllerType, java.lang.String methodName, java.lang.Object... args)
private static java.lang.String	getMethodRequestMapping(java.lang.reflect.Method method)
private static RequestMappingInfoHandlerMapping	getRequestMappingInfoHandlerMapping()
private static java.lang.String	getTypeRequestMapping(java.lang.Class<?> controllerType)
private static WebApplicationContext	getWebApplicationContext()
private static <T> T	initProxy(java.lang.Class<?> type, MvcUriComponentsBuilder.ControllerMethodInvocationInterceptor interceptor)
static <T> T	on(java.lang.Class<T> controllerType) Return a "mock" controller instance.
static MvcUriComponentsBuilder	relativeTo(UriComponentsBuilder baseUrl) Create an instance of this class with a base URL.
UriComponentsBuilder	withController(java.lang.Class<?> controllerType) An alternative to fromController(Class) for use with an instance of this class created via a call to relativeTo(org.springframework.web.util.UriComponentsBuilder).
MvcUriComponentsBuilder.MethodArgumentBuilder	withMappingName(java.lang.String mappingName) An alternative to fromMappingName(String) for use with an instance of this class created via relativeTo(org.springframework.web.util.UriComponentsBuilder).
UriComponentsBuilder	withMethod(java.lang.Class<?> controllerType, java.lang.reflect.Method method, java.lang.Object... args) An alternative to fromMethod(Class, Method, Object...) for use with an instance of this class created via relativeTo(org.springframework.web.util.UriComponentsBuilder).
UriComponentsBuilder	withMethodCall(java.lang.Object invocationInfo) An alternative to fromMethodCall(Object) for use with an instance of this class created via relativeTo(org.springframework.web.util.UriComponentsBuilder).
UriComponentsBuilder	withMethodName(java.lang.Class<?> controllerType, java.lang.String methodName, java.lang.Object... args) An alternative to fromMethodName(Class, String, Object...)} for use with an instance of this class created via relativeTo(org.springframework.web.util.UriComponentsBuilder).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MVC_URI_COMPONENTS_CONTRIBUTOR_BEAN_NAME

public static final java.lang.String MVC_URI_COMPONENTS_CONTRIBUTOR_BEAN_NAME

Well-known name for the CompositeUriComponentsContributor object in the bean factory.

See Also:

Constant Field Values

logger

private static final Log logger

objenesis

private static final SpringObjenesis objenesis

pathMatcher

private static final PathMatcher pathMatcher

parameterNameDiscoverer

private static final ParameterNameDiscoverer parameterNameDiscoverer

defaultUriComponentsContributor

private static final CompositeUriComponentsContributor defaultUriComponentsContributor

baseUrl

private final UriComponentsBuilder baseUrl

Constructor Detail

MvcUriComponentsBuilder

protected MvcUriComponentsBuilder(UriComponentsBuilder baseUrl)

Default constructor. Protected to prevent direct instantiation.

See Also:

fromController(Class), fromMethodName(Class, String, Object...), fromMethodCall(Object), fromMappingName(String), fromMethod(java.lang.reflect.Method, Object...)

Method Detail

relativeTo

public static MvcUriComponentsBuilder relativeTo(UriComponentsBuilder baseUrl)

Create an instance of this class with a base URL. After that calls to one of the instance based withXxx(...} methods will create URLs relative to the given base URL.

fromController

public static UriComponentsBuilder fromController(java.lang.Class<?> controllerType)

Create a UriComponentsBuilder from the mapping of a controller class and current request information including Servlet mapping. If the controller contains multiple mappings, only the first one is used.

Parameters:

controllerType - the controller to build a URI for

Returns:

a UriComponentsBuilder instance (never null)

fromController

public static UriComponentsBuilder fromController(UriComponentsBuilder builder,
                                                  java.lang.Class<?> controllerType)

An alternative to fromController(Class) that accepts a UriComponentsBuilder representing the base URL. This is useful when using MvcUriComponentsBuilder outside the context of processing a request or to apply a custom baseUrl not matching the current request.

Parameters:

builder - the builder for the base URL; the builder will be cloned and therefore not modified and may be re-used for further calls.

controllerType - the controller to build a URI for

Returns:

a UriComponentsBuilder instance (never null)

fromMethodName

public static UriComponentsBuilder fromMethodName(java.lang.Class<?> controllerType,
                                                  java.lang.String methodName,
                                                  java.lang.Object... args)

Create a UriComponentsBuilder from the mapping of a controller method and an array of method argument values. This method delegates to fromMethod(java.lang.reflect.Method, Object...).

Parameters:

controllerType - the controller

methodName - the method name

args - the argument values

Returns:

a UriComponentsBuilder instance, never null

Throws:

java.lang.IllegalArgumentException - if there is no matching or if there is more than one matching method

fromMethodName

public static UriComponentsBuilder fromMethodName(UriComponentsBuilder builder,
                                                  java.lang.Class<?> controllerType,
                                                  java.lang.String methodName,
                                                  java.lang.Object... args)

An alternative to fromMethodName(Class, String, Object...) that accepts a UriComponentsBuilder representing the base URL. This is useful when using MvcUriComponentsBuilder outside the context of processing a request or to apply a custom baseUrl not matching the current request.

Parameters:

builder - the builder for the base URL; the builder will be cloned and therefore not modified and may be re-used for further calls.

controllerType - the controller

methodName - the method name

args - the argument values

Returns:

a UriComponentsBuilder instance, never null

Throws:

java.lang.IllegalArgumentException - if there is no matching or if there is more than one matching method

fromMethodCall

public static UriComponentsBuilder fromMethodCall(java.lang.Object info)

Create a UriComponentsBuilder by invoking a "mock" controller method. The controller method and the supplied argument values are then used to delegate to fromMethod(java.lang.reflect.Method, Object...).

For example, given this controller:

 @RequestMapping("/people/{id}/addresses")
 class AddressController {

   @RequestMapping("/{country}")
   public HttpEntity getAddressesForCountry(@PathVariable String country) { ... }

   @RequestMapping(value="/", method=RequestMethod.POST)
   public void addAddress(Address address) { ... }
 }
 

A UriComponentsBuilder can be created:

 // Inline style with static import of "MvcUriComponentsBuilder.on"

 MvcUriComponentsBuilder.fromMethodCall(
                on(AddressController.class).getAddressesForCountry("US")).buildAndExpand(1);

 // Longer form useful for repeated invocation (and void controller methods)

 AddressController controller = MvcUriComponentsBuilder.on(AddressController.class);
 controller.addAddress(null);
 builder = MvcUriComponentsBuilder.fromMethodCall(controller);
 controller.getAddressesForCountry("US")
 builder = MvcUriComponentsBuilder.fromMethodCall(controller);
 

Parameters:

info - either the value returned from a "mock" controller invocation or the "mock" controller itself after an invocation

Returns:

a UriComponents instance

fromMethodCall

public static UriComponentsBuilder fromMethodCall(UriComponentsBuilder builder,
                                                  java.lang.Object info)

An alternative to fromMethodCall(Object) that accepts a UriComponentsBuilder representing the base URL. This is useful when using MvcUriComponentsBuilder outside the context of processing a request or to apply a custom baseUrl not matching the current request.

Parameters:

builder - the builder for the base URL; the builder will be cloned and therefore not modified and may be re-used for further calls.

info - either the value returned from a "mock" controller invocation or the "mock" controller itself after an invocation

Returns:

a UriComponents instance

fromMappingName

public static MvcUriComponentsBuilder.MethodArgumentBuilder fromMappingName(java.lang.String mappingName)

Create a URL from the name of a Spring MVC controller method's request mapping.

The configured HandlerMethodMappingNamingStrategy determines the names of controller method request mappings at startup. By default all mappings are assigned a name based on the capital letters of the class name, followed by "#" as separator, and then the method name. For example "PC#getPerson" for a class named PersonController with method getPerson. In case the naming convention does not produce unique results, an explicit name may be assigned through the name attribute of the @RequestMapping annotation.

This is aimed primarily for use in view rendering technologies and EL expressions. The Spring URL tag library registers this method as a function called "mvcUrl".

For example, given this controller:

 @RequestMapping("/people")
 class PersonController {

   @RequestMapping("/{id}")
   public HttpEntity getPerson(@PathVariable String id) { ... }

 }
 

A JSP can prepare a URL to the controller method as follows:

 <%@ taglib uri="http://www.springframework.org/tags" prefix="s" %>

 <a href="${s:mvcUrl('PC#getPerson').arg(0,"123").build()}">Get Person</a>
 

Note that it's not necessary to specify all arguments. Only the ones required to prepare the URL, mainly @RequestParam and @PathVariable).

Parameters:

mappingName - the mapping name

Returns:

a builder to to prepare the URI String

Throws:

java.lang.IllegalArgumentException - if the mapping name is not found or if there is no unique match

Since:

4.1

fromMappingName

public static MvcUriComponentsBuilder.MethodArgumentBuilder fromMappingName(UriComponentsBuilder builder,
                                                                            java.lang.String name)

An alternative to fromMappingName(String) that accepts a UriComponentsBuilder representing the base URL. This is useful when using MvcUriComponentsBuilder outside the context of processing a request or to apply a custom baseUrl not matching the current request.

Parameters:

builder - the builder for the base URL; the builder will be cloned and therefore not modified and may be re-used for further calls.

name - the mapping name

Returns:

a builder to to prepare the URI String

Throws:

java.lang.IllegalArgumentException - if the mapping name is not found or if there is no unique match

Since:

4.2

fromMethod

public static UriComponentsBuilder fromMethod(java.lang.Class<?> controllerType,
                                              java.lang.reflect.Method method,
                                              java.lang.Object... args)

Create a UriComponentsBuilder from the mapping of a controller method and an array of method argument values. The array of values must match the signature of the controller method. Values for @RequestParam and @PathVariable are used for building the URI (via implementations of UriComponentsContributor) while remaining argument values are ignored and can be null.

Parameters:

controllerType - the controller type

method - the controller method

args - argument values for the controller method

Returns:

a UriComponentsBuilder instance, never null

fromMethod

public static UriComponentsBuilder fromMethod(UriComponentsBuilder baseUrl,
                                              java.lang.Class<?> controllerType,
                                              java.lang.reflect.Method method,
                                              java.lang.Object... args)

An alternative to fromMethod(java.lang.reflect.Method, Object...) that accepts a UriComponentsBuilder representing the base URL. This is useful when using MvcUriComponentsBuilder outside the context of processing a request or to apply a custom baseUrl not matching the current request.

Parameters:

baseUrl - the builder for the base URL; the builder will be cloned and therefore not modified and may be re-used for further calls.

controllerType - the controller type

method - the controller method

args - argument values for the controller method

Returns:

a UriComponentsBuilder instance, never null

fromMethod

@Deprecated
public static UriComponentsBuilder fromMethod(java.lang.reflect.Method method,
                                                          java.lang.Object... args)

Deprecated. as of 4.2 this is deprecated in favor of the overloaded method that also accepts a controllerType.

See fromMethod(Class, Method, Object...).

fromMethodInternal

private static UriComponentsBuilder fromMethodInternal(UriComponentsBuilder baseUrl,
                                                       java.lang.Class<?> controllerType,
                                                       java.lang.reflect.Method method,
                                                       java.lang.Object... args)

getBaseUrlToUse

private static UriComponentsBuilder getBaseUrlToUse(UriComponentsBuilder baseUrl)

getTypeRequestMapping

private static java.lang.String getTypeRequestMapping(java.lang.Class<?> controllerType)

getMethodRequestMapping

private static java.lang.String getMethodRequestMapping(java.lang.reflect.Method method)

getMethod

private static java.lang.reflect.Method getMethod(java.lang.Class<?> controllerType,
                                                  java.lang.String methodName,
                                                  java.lang.Object... args)

applyContributors

private static UriComponents applyContributors(UriComponentsBuilder builder,
                                               java.lang.reflect.Method method,
                                               java.lang.Object... args)

getConfiguredUriComponentsContributor

private static CompositeUriComponentsContributor getConfiguredUriComponentsContributor()

getRequestMappingInfoHandlerMapping

private static RequestMappingInfoHandlerMapping getRequestMappingInfoHandlerMapping()

getWebApplicationContext

private static WebApplicationContext getWebApplicationContext()

on

public static <T> T on(java.lang.Class<T> controllerType)

Return a "mock" controller instance. When an @RequestMapping method on the controller is invoked, the supplied argument values are remembered and the result can then be used to create a UriComponentsBuilder via fromMethodCall(Object).

Note that this is a shorthand version of controller(Class) intended for inline use (with a static import), for example:

 MvcUriComponentsBuilder.fromMethodCall(on(FooController.class).getFoo(1)).build();
 

Parameters:

controllerType - the target controller

controller

public static <T> T controller(java.lang.Class<T> controllerType)

Return a "mock" controller instance. When an @RequestMapping method on the controller is invoked, the supplied argument values are remembered and the result can then be used to create UriComponentsBuilder via fromMethodCall(Object).

This is a longer version of on(Class). It is needed with controller methods returning void as well for repeated invocations.

 FooController fooController = controller(FooController.class);

 fooController.saveFoo(1, null);
 builder = MvcUriComponentsBuilder.fromMethodCall(fooController);

 fooController.saveFoo(2, null);
 builder = MvcUriComponentsBuilder.fromMethodCall(fooController);
 

Parameters:

controllerType - the target controller

initProxy

private static <T> T initProxy(java.lang.Class<?> type,
                               MvcUriComponentsBuilder.ControllerMethodInvocationInterceptor interceptor)

withController

public UriComponentsBuilder withController(java.lang.Class<?> controllerType)

An alternative to fromController(Class) for use with an instance of this class created via a call to relativeTo(org.springframework.web.util.UriComponentsBuilder).

withMethodName

public UriComponentsBuilder withMethodName(java.lang.Class<?> controllerType,
                                           java.lang.String methodName,
                                           java.lang.Object... args)

An alternative to fromMethodName(Class, String, Object...)} for use with an instance of this class created via relativeTo(org.springframework.web.util.UriComponentsBuilder).

withMethodCall

public UriComponentsBuilder withMethodCall(java.lang.Object invocationInfo)

An alternative to fromMethodCall(Object) for use with an instance of this class created via relativeTo(org.springframework.web.util.UriComponentsBuilder).

withMappingName

public MvcUriComponentsBuilder.MethodArgumentBuilder withMappingName(java.lang.String mappingName)

An alternative to fromMappingName(String) for use with an instance of this class created via relativeTo(org.springframework.web.util.UriComponentsBuilder).

withMethod

public UriComponentsBuilder withMethod(java.lang.Class<?> controllerType,
                                       java.lang.reflect.Method method,
                                       java.lang.Object... args)

An alternative to fromMethod(Class, Method, Object...) for use with an instance of this class created via relativeTo(org.springframework.web.util.UriComponentsBuilder).