Guide to UriComponentsBuilder in Spring

1. Introduction

In this tutorial, we are going to focus on the Spring UriComponentsBuilder. More specifically, we’ll describe various practical implementation examples.

The builder works in conjunction with the UriComponents class – an immutable container for URI components.

A new UriComponentsBuilder class helps to create UriComponents instances by providing fine-grained control over all aspects of preparing a URI including construction, expansion from template variables, and encoding.

2. Maven Dependencies

In order to use the builder, we need to include the following section in the dependencies of our pom.xml:

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-web</artifactId>
    <version>4.3.4.RELEASE</version>
</dependency>

The latest version can be found here.

This dependency only covers Spring Web so don’t forget to add spring-context for a full web application.

We of course also need to set up logging for the project – more on that here.

3. Use Cases

There are many practical use cases for the UriComponentsBuilder, starting from a contextual encoding of characters not permitted in the corresponding URI component, finishing on replacing parts of the URL dynamically.

One of the biggest advantages of UriComponentsBuilder is that we can inject it right into a controller method:

@RequestMapping(method = RequestMethod.POST)
public ResponseEntity createCustomer(UriComponentsBuilder builder) {
    // implementation
}

Let’s start describing useful examples one by one. We’ll use the JUnit framework to test our implementations immediately.

3.1. Constructing a URI

Let’s start with the simplest one. We want to use UriComponentsBuilder just to create simple link:

@Test
public void constructUri() {
    UriComponents uriComponents = UriComponentsBuilder.newInstance()
      .scheme("http").host("www.baeldung.com").path("/junit-5").build();

    assertEquals("http://www.baeldung.com/junit-5", uriComponents.toUriString());
}

As we may observe, we created a new instance of UriComponentsBuilder, then we provided scheme type, host, and a path to the request destination.

This simple example might be useful when we want to perform a redirect to other part/link of our website.

3.2. Constructing an Encoded URI

In addition to creating a simple link, we may want to encode the final result. Let’s see this in practice:

@Test
public void constructUriEncoded() {
    UriComponents uriComponents = UriComponentsBuilder.newInstance()
      .scheme("http").host("www.baeldung.com").path("/junit 5").build().encode();

    assertEquals("http://www.baeldung.com/junit%205", uriComponents.toUriString());
}

The difference in this example is that we want to add space between the word junit and number 5. Accordingly to the RFC 3986, it would not be possible. We need to encode the link to achieve the valid result, using encode() method.

3.3. Constructing a URI from a Template

URI templates are allowed in the most components of a URI but their value is restricted to a particular element, that we indicate as a template. Let’s see the example to clarify:

@Test
public void constructUriFromTemplate() {
    UriComponents uriComponents = UriComponentsBuilder.newInstance()
      .scheme("http").host("www.baeldung.com").path("/{article-name}")
      .buildAndExpand("junit-5");

    assertEquals("http://www.baeldung.com/junit-5", uriComponents.toUriString());
}

The difference in this example is in the way we declare the path and how we build the final URI. Template that will be replaced by keywords is indicated by brackets – {…}, inside the path() method. The keyword that is used to generate the final link is used in the method named buildAndExpand(…).

Please note, that there might be more than one keyword to be replaced. Also, the path to the URI can be relative.

This example will be very helpful when we would like to pass model objects to the Spring Controller based on which we’ll build a URI.

3.4. Constructing a URI with Query Parameters

Another very useful case is to create URI with query parameters.

We need to use query() from UriComponentsBuilder to specify URI query parameters. Let’s see the following example:

@Test
public void constructUriWithQueryParameter() {
    UriComponents uriComponents = UriComponentsBuilder.newInstance()
      .scheme("http").host("www.google.com")
      .path("/").query("q={keyword}").buildAndExpand("baeldung");

     assertEquals("http://www.google.com/?q=baeldung", uriComponents.toUriString());
}

The query will be added to the main part of the link. We can provide multiple query parameters, using brackets {…}. They will be replaced by keywords in the method named buildAndExpand(…).

This implementation of UriComponentsBuilder might be used to build – for example – a query language for a REST API.

3.5. Expanding a URI with Regular Expressions

The last example is showing a construction of a URI with regex validation. We’ll be able to expand the uriComponents only if regex validation will be successful:

@Test
public void expandWithRegexVar() {
    String template = "/myurl/{name:[a-z]{1,5}}/show";
    UriComponents uriComponents = UriComponentsBuilder.fromUriString(template)
      .build();
    uriComponents = uriComponents.expand(Collections.singletonMap("name", "test"));
 
    assertEquals("/myurl/test/show", uriComponents.getPath());
}

In the above-mentioned example, we can see that the middle part of the link needs to have only letters from a-z and the length in a range between 1-5.

Also, we’re using singletonMap, to replace keyword name with value test.

This example is particularly useful when we enable a user to specify links dynamically, but we want to provide a sort of security where only valid links work in our web application.

4. Conclusion

This tutorial presents useful examples of the UriComponentsBuilder.

The main advantages of UriComponentsBuilder are the flexibility of using URI template variables, and a possibility of injecting it directly into Spring Controller methods.

All examples and configurations are available here on GitHub.