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

Class MvcUriComponentsBuilder

  • java.lang.Object
    • org.springframework.web.servlet.mvc.method.annotation.MvcUriComponentsBuilder


  • public class MvcUriComponentsBuilder
    extends java.lang.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
    • 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(java.lang.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,
                                                          java.lang.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(java.lang.Class<?> controllerType,
                                                          java.lang.String methodName,
                                                          java.lang.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:
        java.lang.IllegalArgumentException - if there is no matching or if there is more than one matching method
      • fromMethodName

        public static UriComponentsBuilder fromMethodName(UriComponentsBuilder builder,
                                                          java.lang.Class<?> controllerType,
                                                          java.lang.String methodName,
                                                          java.lang.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:
        java.lang.IllegalArgumentException - if there is no matching or if there is more than one matching method
      • fromMethod

        public static UriComponentsBuilder fromMethod(java.lang.Class<?> controllerType,
                                                      java.lang.reflect.Method method,
                                                      java.lang.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
                                                      java.lang.Class<?> controllerType,
                                                      java.lang.reflect.Method method,
                                                      java.lang.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(java.lang.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,
                                                          java.lang.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(java.lang.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(java.lang.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(java.lang.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:
        java.lang.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,
                                                                                    java.lang.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:
        java.lang.IllegalArgumentException - if the mapping name is not found or if there is no unique match
        Since:
        4.2