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, Juergen Hoeller

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

    All Methods Static Methods Instance Methods Concrete Methods
    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