Package 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: As of 5.1, methods in this class do not extract `"Forwarded"` and `"X-Forwarded-*"` headers that specify the client-originated address. Please, use `ForwardedHeaderFilter`, or similar from the underlying server, to extract and use such headers, or to discard them.

Since:
  4.0
Author:
  Oliver Gierke, Rossen Stoyanchev, Sam Brannen, Juergen Hoeller

## Nested Class Summary

Nested Classes
Modifier and Type
Class
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
Description
`static final String`
`MVC_URI_COMPONENTS_CONTRIBUTOR_BEAN_NAME`
Well-known name for the `CompositeUriComponentsContributor` object in the bean factory.

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`MvcUriComponentsBuilder(org.springframework.web.util.UriComponentsBuilder baseUrl)`
Default constructor.

## Method Summary

Modifier and Type
Method
Description
`static <T> T`
`controller(Class<T> controllerType)`
Return a "mock" controller instance.
`static org.springframework.web.util.UriComponentsBuilder`
`fromController(Class<?> controllerType)`
Create a `UriComponentsBuilder` from the mapping of a controller class and current request information including Servlet mapping.
`static org.springframework.web.util.UriComponentsBuilder`
`fromController(org.springframework.web.util.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(org.springframework.web.util.UriComponentsBuilder builder, String name)`
An alternative to `fromMappingName(String)` that accepts a `UriComponentsBuilder` representing the base URL.
`static org.springframework.web.util.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 org.springframework.web.util.UriComponentsBuilder`
`fromMethod(org.springframework.web.util.UriComponentsBuilder baseUrl, Class<?> controllerType, Method method, Object... args)`
An alternative to `fromMethod(Class, Method, Object...)` that accepts a `UriComponentsBuilder` representing the base URL.
`static org.springframework.web.util.UriComponentsBuilder`
`fromMethodCall(Object info)`
Create a `UriComponentsBuilder` by invoking a "mock" controller method.
`static org.springframework.web.util.UriComponentsBuilder`
`fromMethodCall(org.springframework.web.util.UriComponentsBuilder builder, Object info)`
An alternative to `fromMethodCall(Object)` that accepts a `UriComponentsBuilder` representing the base URL.
`static org.springframework.web.util.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 org.springframework.web.util.UriComponentsBuilder`
`fromMethodName(org.springframework.web.util.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(org.springframework.web.util.UriComponentsBuilder baseUrl)`
Create an instance of this class with a base URL.
`org.springframework.web.util.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)`.
`org.springframework.web.util.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)`.
`org.springframework.web.util.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)`.
`org.springframework.web.util.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 Details

### 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 Details

### MvcUriComponentsBuilder

protected MvcUriComponentsBuilder(org.springframework.web.util.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 Details

### relativeTo

public static MvcUriComponentsBuilder relativeTo(org.springframework.web.util.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 org.springframework.web.util.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.

Parameters:
  `controllerType` - the controller to build a URI for
Returns:
  a UriComponentsBuilder instance (never `null`)

### fromController

public static org.springframework.web.util.UriComponentsBuilder fromController(@Nullable org.springframework.web.util.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.

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 org.springframework.web.util.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...)`.

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 org.springframework.web.util.UriComponentsBuilder fromMethodName(org.springframework.web.util.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.

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 org.springframework.web.util.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`.

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 org.springframework.web.util.UriComponentsBuilder fromMethod(org.springframework.web.util.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.

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 org.springframework.web.util.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 {

       @GetMapping("/{country}")
       public HttpEntity<Void> getAddressesForCountry(@PathVariable String country) { ... }

       @PostMapping
       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
See Also:
  - `on(Class)`
  - `controller(Class)`

### fromMethodCall

public static org.springframework.web.util.UriComponentsBuilder fromMethodCall(org.springframework.web.util.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.

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();

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);

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`).

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 org.springframework.web.util.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.

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 org.springframework.web.util.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)`.

Since:
  4.2

### withMethodName

public org.springframework.web.util.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)`.

Since:
  4.2

### withMethodCall

public org.springframework.web.util.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)`.

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)`.

Since:
  4.2

### withMethod

public org.springframework.web.util.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)`.

Since:
  4.2