URI links

UriComponents

Spring MVC and Spring WebFlux

UriComponentsBuilder helps create URIs from URIs-templates with variables, as shown in the following example:

UriComponents uriComponents = UriComponentsBuilder
        .fromUriString("https://example.com/hotels/{hotel }") 
        .queryParam("q", "{q}") 
        .encode() 
        .build(); 
URI uri = uriComponents.expand("Westin", "123").toUri(); 

1. Static factory method with a URI template.
2. Add or replace URI components.
3. Request to encode a URI template and URI variables.
4. Collect UriComponents.
5. Expand the variables and get URI.

val uriComponents = UriComponentsBuilder
        .fromUriString("https://example.com/hotels/{hotel}") 
        .queryParam(" q", "{q}") 
        .encode() 
        .build() 
val uri = uriComponents.expand("Westin", "123").toUri() 

1. Static factory method with a URI template.
2. Add or replace URI components.
3. Request to encode a URI template and URI variables.
4. Collect UriComponents.
5. We expand the variables and get URI.

The code from the previous example can be combined into one chain and shortened using buildAndExpand, as shown in the following example:

URI uri = UriComponentsBuilder
        .fromUriString("https://example.com/hotels/{hotel}")
        .queryParam("q", "{q}")
        .encode()
        .buildAndExpand("Westin", "123")
        .toUri();

val uri = UriComponentsBuilder
        .fromUriString("https://example.com/hotels/{hotel}")
        .queryParam("q", "{q}")
        .encode()
        .buildAndExpand("Westin", "123")
        .toUri()

You can shorten it even further by going directly to the URI (which implies an encoding), as shown in the following example:

URI uri = UriComponentsBuilder
        .fromUriString("https://example.com/hotels/{hotel}")
        .queryParam("q", "{q}")
        .build("Westin", "123");

val uri = UriComponentsBuilder
        .fromUriString("https://example.com/hotels/{hotel}")
        .queryParam("q", "{q}")
        .build("Westin", "123")

You can shorten it even further using a full URI template, as shown in the following example:

URI uri = UriComponentsBuilder
        .fromUriString("https://example.com/hotels/{hotel}?q={q}")
        .build("Westin", "123");

val uri = UriComponentsBuilder
        .fromUriString("https://example.com/hotels/{hotel}?q={q}")
        .build("Westin", "123")

UriBuilder

Spring MVC and Spring WebFlux

UriComponentsBuilder implements UriBuilder. In turn, you can create a UriBuilder using UriBuilderFactory. Together, UriBuilderFactory and UriBuilder provide a plug-in mechanism for generating URIs from URI templates based on common configuration, such as the base URL, encoding options, and other details.

You can configure RestTemplate and WebClient using UriBuilderFactory to configure URI preparation. DefaultUriBuilderFactory is a default implementation of UriBuilderFactory that uses UriComponentsBuilder internally and exposes general configuration options.

In the following The example shows how to configure such a bean:

// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode;
String baseUrl = "https://example.org";
DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl);
factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);
RestTemplate restTemplate = new RestTemplate();
restTemplate.setUriTemplateHandler(factory);

// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode
val baseUrl = "https://example.org"
val factory = DefaultUriBuilderFactory(baseUrl)
factory.encodingMode = EncodingMode.TEMPLATE_AND_VALUES
val restTemplate = RestTemplate()
restTemplate.uriTemplateHandler = factory

The following example configures the WebClient:

// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode;
String baseUrl = "https://example.org";
DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl);
factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);
WebClient client = WebClient.builder().uriBuilderFactory(factory).build();

// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode
val baseUrl = "https://example.org"
val factory = DefaultUriBuilderFactory(baseUrl)
factory.encodingMode = EncodingMode.TEMPLATE_AND_VALUES
val client = WebClient.builder().uriBuilderFactory(factory).build()

Alternatively, you can use DefaultUriBuilderFactory directly. This is similar to using UriComponentsBuilder, but instead of static factory methods, it is an actual instance that stores configuration and parameters, as shown in the following example:

String baseUrl = "https://example.com";
DefaultUriBuilderFactory uriBuilderFactory = new DefaultUriBuilderFactory(baseUrl);
URI uri = uriBuilderFactory.uriString("/hotels/{hotel}")
        .queryParam("q", "{q}")
        .build("Westin", "123");

val baseUrl = "https://example.com"
val uriBuilderFactory = DefaultUriBuilderFactory(baseUrl)
val uri = uriBuilderFactory.uriString("/hotels/{hotel}")
        .queryParam("q", "{q}")
        .build("Westin", "123")

Encoding URIs

Spring MVC and Spring WebFlux

UriComponentsBuilder opens encoding options at two levels:

• UriComponentsBuilder#encode(): First pre-encodes the URI pattern, and then strictly encodes URI variables when expanded.

• UriComponents#encode(): Encodes URI components after URI variable expansion.

Both options replace non-ASCII and illegal characters with escaped octets. However, the first option also replaces characters with a reserved meaning that appear in URI variables.

In most cases, the first option will most likely produce the expected result because it takes URI identifier variables into account as opaque data that must be fully encoded, while the second option is useful if URI variables intentionally contain reserved characters. The second option also works if you don't expand URI variables at all, because then anything that happens to look like a URI variable is encoded.

The following example uses the first option:

URI uri = UriComponentsBuilder.fromPath("/hotel list/{city}")
        .queryParam("q", "{q}")
        .encode()
        .buildAndExpand ("New York", "foo+bar")
        .toUri();
// Result "/hotel%20list/New%20York?q=foo%2Bbar"

val uri = UriComponentsBuilder.fromPath("/hotel list/{city}")
        .queryParam("q", "{q}")
        .encode()
        .buildAndExpand("New York", "foo+bar")
        .toUri ()
// Result "/hotel%20list/New%20York?q=foo%2Bbar"

You can shorten the code in the previous example by going directly to A URI (which implies an encoding), as shown in the following example:

URI uri = UriComponentsBuilder.fromPath("/hotel list/{city}")
        .queryParam("q", "{q}")
        .build("New York", "foo+bar");

val uri = UriComponentsBuilder.fromPath("/hotel list/{city}")
        .queryParam("q", "{q}")
        .build("New York", "foo+bar")

You can shorten it even further by using a full URI wildcard, as shown in the following example:

URI uri = UriComponentsBuilder.fromUriString("/hotel list/{city}?q={q}")
        .build("New York", "foo+bar");

val uri = UriComponentsBuilder.fromUriString("/hotel list/{city}?q={q}")
        .build("New York", "foo+bar")

WebClient and RestTemplate expand and encode URI patterns internally using the UriBuilderFactory strategy. Both options can be configured using a custom strategy, as shown in the following example:

String baseUrl = "https://example.com";
DefaultUriBuilderFactory
factory = new DefaultUriBuilderFactory(baseUrl)
factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);
// Setting up RestTemplate...
RestTemplate restTemplate = new RestTemplate();
restTemplate.setUriTemplateHandler(factory);
// Configure WebClient...
WebClient client = WebClient.builder().uriBuilderFactory(factory).build();

val baseUrl = "https://example.com"
val factory = DefaultUriBuilderFactory(baseUrl).apply {
    encodingMode = EncodingMode.TEMPLATE_AND_VALUES
}
// Setting up the RestTemplate...
val restTemplate = RestTemplate().apply {
    uriTemplateHandler = factory
}
// Configure the WebClient...
val client = WebClient.builder().uriBuilderFactory(factory).build()

Implementation DefaultUriBuilderFactory uses UriComponentsBuilder internally to expand and encode URI patterns. As a factory, it provides a single place to configure an encoding approach based on one of the following encoding modes:

• TEMPLATE_AND_VALUES: Uses UriComponentsBuilder# encode(), corresponding to the first option in the previous list, to pre-encode the URI template and strictly encode URI variables when expanding.

• VALUES_ONLY: Does not encode the URI template and instead applies strict encoding to URI variables via UriUtils#encodeUriVariables before expanding them into the template.

• URI_COMPONENT: Uses UriComponents#encode(), corresponding to the second option in the previous list, to encode the component value of the URI after URI variable extensions.

• NONE: No encoding is applied.

RestTemplate is set to EncodingMode.URI_COMPONENT for historical reasons and for backward compatibility. WebClient accesses the default value in DefaultUriBuilderFactory, which was changed from EncodingMode.URI_COMPONENT in 5.0.x to EncodingMode.TEMPLATE_AND_VALUES in 5.1.

Servlet Relative Requests

You can use the ServletUriComponentsBuilder to create URIs relative to the current request, as shown in the following example:

HttpServletRequest request = ...
// Reuses scheme, host, port, path and query string...
URI uri = ServletUriComponentsBuilder.fromRequest(request)
        .replaceQueryParam("accountId", "{id}")
        .build("123");

val request: HttpServletRequest = ...
// Reuses scheme, host, port, path and query string...
val uri = ServletUriComponentsBuilder.fromRequest(request)
        .replaceQueryParam("accountId", "{id}")
        .build ("123")

You can create URIs relative to the context path, as shown in the following example:

HttpServletRequest request = ...
// Reuse scheme, host, port and context path...
URI uri = ServletUriComponentsBuilder.fromContextPath(request)
        .path("/accounts")
        .build()
        .toUri();

val request: HttpServletRequest = ...
// Reuse the schema, host, port and context path...
val uri = ServletUriComponentsBuilder.fromContextPath(request)
        .path("/accounts")
        .build()
        .toUri()

You can create URIs relative to the servlet (for example, /main/*), as shown in the following example:

HttpServletRequest request = ...
// Reuses the scheme, host, port, context path and servlet mapping prefix...
URI uri = ServletUriComponentsBuilder.fromServletMapping(request)
        .path("/accounts")
        .build()
        .toUri();

val request: HttpServletRequest = ...
// Reuses scheme, host, port , context path and servlet mapping prefix...
val uri = ServletUriComponentsBuilder.fromServletMapping(request)
        .path("/accounts")
        .build()
        .toUri()

Controller References

Spring MVC provides a mechanism for preparing references to controller methods. For example, the following MVC controller allows you to create links:

@Controller
@RequestMapping("/hotels/{hotel}")
public class BookingController {
    @GetMapping(" /bookings/{booking}")
    public ModelAndView getBooking(@PathVariable Long booking) {
        // ...
    }
}

@Controller
@RequestMapping("/hotels/{hotel}")
class BookingController {
    @GetMapping("/bookings/{booking}")
    fun getBooking(@PathVariable booking: Long): ModelAndView {
        // ...
    }
}

You can prepare a reference by accessing the method by name, as shown in the following example:

UriComponents uriComponents = MvcUriComponentsBuilder
    .fromMethodName(BookingController.class, "getBooking", 21).buildAndExpand(42);
URI uri = uriComponents.encode().toUri();

val uriComponents = MvcUriComponentsBuilder
    .fromMethodName (BookingController::class.java, "getBooking", 21).buildAndExpand(42)
val uri = uriComponents.encode().toUri()

In the previous example, we specify the actual values of the method arguments (in this case, the long value: 21) to be used as a path variable and inserted into the URL. Additionally, we specify the value 42 to populate any remaining URI variables, such as the hotel variable inherited from the type-level query mapping. If the method had more arguments, we could supply null for arguments not needed for the URL. In general, only arguments with the @PathVariable and @RequestParam annotations are meaningful for URL construction.

There are additional ways to use the MvcUriComponentsBuilder. For example, to avoid calling a controller method by name, as shown in the following example (the example assumes a static import of MvcUriComponentsBuilder.on), you can use a technique similar to testing using mock objects through a proxy:

UriComponents uriComponents = MvcUriComponentsBuilder
    .fromMethodCall(on(BookingController.class).getBooking(21)).buildAndExpand(42);
URI uri = uriComponents.encode().toUri();

val uriComponents = MvcUriComponentsBuilder
    .fromMethodCall (on(BookingController::class.java).getBooking(21)).buildAndExpand(42)
val uri = uriComponents.encode().toUri()

The previous examples use static methods in MvcUriComponentsBuilder. Internally, they call the ServletUriComponentsBuilder to prepare a base URL from the scheme, host, port, context path, and servlet path of the current request. This works great in most cases. However, sometimes this may not be enough. For example, you may be outside the context of the request (for example, in a batch process that prepares links), or you may need to insert a path prefix (for example, a locale prefix that was removed from the request path and needs to be inserted back into the links) .

For such cases, you can use static overloads of fromXxx methods that take a UriComponentsBuilder to use the base URL. Alternatively, you can instantiate MvcUriComponentsBuilder with a base URL, and then use withXxx methods based on the instance. For example, the following listing uses withMethodCall:

UriComponentsBuilder base = ServletUriComponentsBuilder.fromCurrentContextPath().path("/en");
MvcUriComponentsBuilder builder = MvcUriComponentsBuilder.relativeTo(base);
builder.withMethodCall(on(BookingController.class).getBooking(21)).buildAndExpand(42);
URI uri = uriComponents.encode().toUri();

val base = ServletUriComponentsBuilder.fromCurrentContextPath().path("/en")
val builder = MvcUriComponentsBuilder.relativeTo(base)
builder.withMethodCall(on(BookingController::class.java).getBooking(21)).buildAndExpand(42)
val uri = uriComponents.encode().toUri()

References in Views

In views such as Thymeleaf, FreeMarker, or JSP, you can form references to annotated controllers by referencing an implicitly or explicitly assigned name for each query mapping.

Consider the following example:

@RequestMapping("/people/{id}/addresses")
public class PersonAddressController {
    @RequestMapping("/{country}")
    public HttpEntity<PersonAddress> getAddress(@PathVariable String country) { ... }
}

@RequestMapping("/people/{id}/addresses")
class PersonAddressController {
    @RequestMapping("/{country}")
    fun getAddress(@PathVariable country: String): HttpEntity<PersonAddress> { ... }
}

Given the previous controller, you can prepare a link from JSP in the following form:

<%@ taglib uri="http://www.springframework.org/tags" prefix="s" %>
...
<a href="${s:mvcUrl('PAC#getAddress').arg(0,'US').buildAndExpand('123')}">Get Address</a>

In the previous example, we rely on the mvcUrl function declared in the Spring tag library (that is, META-INF/spring.tld), but Defining your own function or preparing a similar one for other templating technologies is also quite simple.

Here's how it works. When you run each @RequestMapping annotation, it is assigned a default name via the HandlerMethodMappingNamingStrategy strategy, the default implementation of which capitalizes the class and method name (for example, the getThing method in ThingController becomes "TC#getThing"). If the names do not match, you can use @RequestMapping(name="..") to assign an explicit name or implement your own naming strategy HandlerMethodMappingNamingStrategy.