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

## Class MvcUriComponentsBuilder

- java.lang.Object
- - org.springframework.web.util.UriComponentsBuilder
  - - org.springframework.web.servlet.mvc.method.annotation.MvcUriComponentsBuilder

-     public class MvcUriComponentsBuilder
      extends UriComponentsBuilder

  A UriComponentsBuilder that helps to build URIs to Spring MVC controllers and methods from their request mappings.
  Since:
    4.0
  Author:
    Oliver Gierke, Rossen Stoyanchev

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `MvcUriComponentsBuilder.MethodInvocationInfo`

  - ### 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
    Constructor and Description
    `MvcUriComponentsBuilder()`

  - ### Method Summary

    All Methods Static 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` | `fromMethod(Method method, Object... argumentValues)` Create a `UriComponentsBuilder` from the mapping of a controller method and an array of method argument values.
    `static UriComponentsBuilder` | `fromMethodCall(Object invocationInfo)` Create a `UriComponentsBuilder` by invoking a "mock" controller method.
    `static UriComponentsBuilder` | `fromMethodName(Class<?> controllerType, String methodName, Object... argumentValues)` Create a `UriComponentsBuilder` from the mapping of a controller method and an array of method argument values.
    `protected static CompositeUriComponentsContributor` | `getConfiguredUriComponentsContributor()`
    `static <T> T` | `on(Class<T> controllerType)` Return a "mock" controller instance.

    - ### Methods inherited from class org.springframework.web.util.UriComponentsBuilder

      `build, build, buildAndExpand, buildAndExpand, fragment, fromHttpUrl, fromPath, fromUri, fromUriString, host, newInstance, path, pathSegment, port, query, queryParam, queryParams, replacePath, replaceQuery, replaceQueryParam, scheme, schemeSpecificPart, uri, uriComponents, userInfo`

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

          public MvcUriComponentsBuilder()

  - ### Method Detail

    - #### 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.
      Parameters:
        `controllerType` - the controller to build a URI for
      Returns:
        a UriComponentsBuilder instance, never `null`

    - #### fromMethodName

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

      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
        `argumentValues` - the argument values
      Returns:
        a UriComponentsBuilder instance, never `null`
      Throws:
        `IllegalStateException` - if there is no matching or more than one matching method.

    - #### fromMethodCall

          public static UriComponentsBuilder fromMethodCall(Object invocationInfo)

      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(CustomerController.class).showAddresses("US")).buildAndExpand(1);

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

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

      Parameters:
        `invocationInfo` - either the value returned from a "mock" controller invocation or the "mock" controller itself after an invocation
      Returns:
        a UriComponents instance

    - #### fromMethod

          public static UriComponentsBuilder fromMethod(Method method,
                                                        Object... argumentValues)

      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:
        `method` - the controller method
        `argumentValues` - argument values for the controller method
      Returns:
        a UriComponentsBuilder instance, never `null`

    - #### getConfiguredUriComponentsContributor

          protected static CompositeUriComponentsContributor getConfiguredUriComponentsContributor()

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