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:

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

  • Field Details

  • Constructor Details

  • Method Details

    • 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:

    • 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