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

Class MvcUriComponentsBuilder

java.lang.Object

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

public class MvcUriComponentsBuilder
extends Object

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

There are several groups of methods:

• Static fromXxx(...) methods to prepare links using information from the current request as determined by a call to ServletUriComponentsBuilder.fromCurrentServletMapping().
• Static fromXxx(UriComponentsBuilder,...) methods can be given a baseUrl when operating outside the context of a request.
• Instance-based withXxx(...) methods where an instance of MvcUriComponentsBuilder is created with a baseUrl via relativeTo(org.springframework.web.util.UriComponentsBuilder).

Note: This class uses values from "Forwarded" (RFC 7239), "X-Forwarded-Host", "X-Forwarded-Port", and "X-Forwarded-Proto" headers, if present, in order to reflect the client-originated protocol and address. Consider using the ForwardedHeaderFilter in order to choose from a central place whether to extract and use, or to discard such headers. See the Spring Framework reference for more on this filter.

Since:

4.0

Author:

Oliver Gierke, Rossen Stoyanchev, Sam Brannen

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MvcUriComponentsBuilder.MethodArgumentBuilder Builder class to create URLs for method arguments.
static interface	MvcUriComponentsBuilder.MethodInvocationInfo Method invocation information.

Field Summary

Fields

Modifier and Type	Field and Description
static String	MVC_URI_COMPONENTS_CONTRIBUTOR_BEAN_NAME Well-known name for the CompositeUriComponentsContributor object in the bean factory.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
static <T> T	controller(Class<T> controllerType) Return a "mock" controller instance.
static UriComponentsBuilder	fromController(Class<?> controllerType) Create a UriComponentsBuilder from the mapping of a controller class and current request information including Servlet mapping.
static UriComponentsBuilder	fromController(UriComponentsBuilder builder, Class<?> controllerType) An alternative to fromController(Class) that accepts a UriComponentsBuilder representing the base URL.
static MvcUriComponentsBuilder.MethodArgumentBuilder	fromMappingName(String mappingName) Create a URL from the name of a Spring MVC controller method's request mapping.
static MvcUriComponentsBuilder.MethodArgumentBuilder	fromMappingName(UriComponentsBuilder builder, String name) An alternative to fromMappingName(String) that accepts a UriComponentsBuilder representing the base URL.
static UriComponentsBuilder	fromMethod(Class<?> controllerType, Method method, Object... args) Create a UriComponentsBuilder from the mapping of a controller method and an array of method argument values.
static UriComponentsBuilder	fromMethod(UriComponentsBuilder baseUrl, Class<?> controllerType, Method method, Object... args) An alternative to fromMethod(Class, Method, Object...) that accepts a UriComponentsBuilder representing the base URL.
static UriComponentsBuilder	fromMethodCall(Object info) Create a UriComponentsBuilder by invoking a "mock" controller method.
static UriComponentsBuilder	fromMethodCall(UriComponentsBuilder builder, Object info) An alternative to fromMethodCall(Object) that accepts a UriComponentsBuilder representing the base URL.
static UriComponentsBuilder	fromMethodName(Class<?> controllerType, String methodName, Object... args) Create a UriComponentsBuilder from the mapping of a controller method and an array of method argument values.
static UriComponentsBuilder	fromMethodName(UriComponentsBuilder builder, Class<?> controllerType, String methodName, Object... args) An alternative to fromMethodName(Class, String, Object...) that accepts a UriComponentsBuilder representing the base URL.
static <T> T	on(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(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(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(Class<?> controllerType, Method method, 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(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(Class<?> controllerType, String methodName, 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 String MVC_URI_COMPONENTS_CONTRIBUTOR_BEAN_NAME

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

See Also:

Constant Field Values

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(Class, 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(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.

Note: This method extracts values from "Forwarded" and "X-Forwarded-*" headers if found. See class-level docs.

Parameters:

controllerType - the controller to build a URI for

Returns:

a UriComponentsBuilder instance (never null)

fromController

public static UriComponentsBuilder fromController(@Nullable
                                                  UriComponentsBuilder builder,
                                                  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.

Note: This method extracts values from "Forwarded" and "X-Forwarded-*" headers if found. See class-level docs.

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(Class<?> controllerType,
                                                  String methodName,
                                                  Object... args)

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

Note: This method extracts values from "Forwarded" and "X-Forwarded-*" headers if found. See class-level docs.

Parameters:

controllerType - the controller

methodName - the method name

args - the argument values

Returns:

a UriComponentsBuilder instance, never null

Throws:

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

fromMethodName

public static UriComponentsBuilder fromMethodName(UriComponentsBuilder builder,
                                                  Class<?> controllerType,
                                                  String methodName,
                                                  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.

Note: This method extracts values from "Forwarded" and "X-Forwarded-*" headers if found. See class-level docs.

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:

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

fromMethod

public static UriComponentsBuilder fromMethod(Class<?> controllerType,
                                              Method method,
                                              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.

Note: This method extracts values from "Forwarded" and "X-Forwarded-*" headers if found. See class-level docs.

Parameters:

controllerType - the controller type

method - the controller method

args - argument values for the controller method

Returns:

a UriComponentsBuilder instance, never null

Since:

4.2

fromMethod

public static UriComponentsBuilder fromMethod(UriComponentsBuilder baseUrl,
                                              @Nullable
                                              Class<?> controllerType,
                                              Method method,
                                              Object... args)

An alternative to fromMethod(Class, 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.

Note: This method extracts values from "Forwarded" and "X-Forwarded-*" headers if found. See class-level docs.

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)

Since:

4.2

fromMethodCall

public static UriComponentsBuilder fromMethodCall(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(Class, Method, Object...).

For example, given this controller:

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

   @RequestMapping("/{country}")
   public HttpEntity<Void> 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);
 

Note: This method extracts values from "Forwarded" and "X-Forwarded-*" headers if found. See class-level docs.

Parameters:

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

Returns:

a UriComponents instance

See Also:

on(Class), controller(Class)

fromMethodCall

public static UriComponentsBuilder fromMethodCall(UriComponentsBuilder builder,
                                                  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.

Note: This method extracts values from "Forwarded" and "X-Forwarded-*" headers if found. See class-level docs.

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

on

public static <T> T on(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();
 

Note: This method extracts values from "Forwarded" and "X-Forwarded-*" headers if found. See class-level docs.

Parameters:

controllerType - the target controller

controller

public static <T> T controller(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);
 

Note: This method extracts values from "Forwarded" and "X-Forwarded-*" headers if found. See class-level docs.

Parameters:

controllerType - the target controller

fromMappingName

public static MvcUriComponentsBuilder.MethodArgumentBuilder fromMappingName(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<Void> 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).

Note: This method extracts values from "Forwarded" and "X-Forwarded-*" headers if found. See class-level docs.

Parameters:

mappingName - the mapping name

Returns:

a builder to prepare the URI String

Throws:

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

Since:

4.1

fromMappingName

public static MvcUriComponentsBuilder.MethodArgumentBuilder fromMappingName(@Nullable
                                                                            UriComponentsBuilder builder,
                                                                            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.

Note: This method extracts values from "Forwarded" and "X-Forwarded-*" headers if found. See class-level docs.

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 prepare the URI String

Throws:

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

Since:

4.2

withController

public UriComponentsBuilder withController(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).

Note: This method extracts values from "Forwarded" and "X-Forwarded-*" headers if found. See class-level docs.

Since:

4.2

withMethodName

public UriComponentsBuilder withMethodName(Class<?> controllerType,
                                           String methodName,
                                           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).

Note: This method extracts values from "Forwarded" and "X-Forwarded-*" headers if found. See class-level docs.

Since:

4.2

withMethodCall

public UriComponentsBuilder withMethodCall(Object invocationInfo)

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

Note: This method extracts values from "Forwarded" and "X-Forwarded-*" headers if found. See class-level docs.

Since:

4.2

withMappingName

public MvcUriComponentsBuilder.MethodArgumentBuilder withMappingName(String mappingName)

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

Note: This method extracts values from "Forwarded" and "X-Forwarded-*" headers if found. See class-level docs.

Since:

4.2

withMethod

public UriComponentsBuilder withMethod(Class<?> controllerType,
                                       Method method,
                                       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).

Note: This method extracts values from "Forwarded" and "X-Forwarded-*" headers if found. See class-level docs.

Since:

4.2