Expand Authors Top

If you have a few years of experience in the Java ecosystem and you’d like to share that with the community, have a look at our Contribution Guidelines.

Expanded Audience – Frontegg – Security (partner)
announcement - icon User management is very complex, when implemented properly. No surprise here.

Not having to roll all of that out manually, but instead integrating a mature, fully-fledged solution - yeah, that makes a lot of sense.
That's basically what Frontegg is - User Management for your application. It's focused on making your app scalable, secure and enjoyable for your users.
From signup to authentication, it supports simple scenarios all the way to complex and custom application logic.

Have a look:

>> Elegant User Management, Tailor-made for B2B SaaS

November Discount Launch 2022 – Top
We’re finally running a Black Friday launch. All Courses are 30% off until end-of-day today:


NPI – Lightrun – Spring (partner)

We rely on other people’s code in our own work. Every day. It might be the language you’re writing in, the framework you’re building on, or some esoteric piece of software that does one thing so well you never found the need to implement it yourself.

The problem is, of course, when things fall apart in production - debugging the implementation of a 3rd party library you have no intimate knowledge of is, to say the least, tricky. It’s difficult to understand what talks to what and, specifically, which part of the underlying library is at fault.

Lightrun is a new kind of debugger.

It's one geared specifically towards real-life production environments. Using Lightrun, you can drill down into running applications, including 3rd party dependencies, with real-time logs, snapshots, and metrics. No hotfixes, redeployments, or restarts required.

Learn more in this quick, 5-minute Lightrun tutorial:

>> The Essential List of Spring Boot Annotations and Their Use Cases

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:


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:

public void constructUri() {
    UriComponents uriComponents = UriComponentsBuilder.newInstance()

    assertEquals("/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:

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

    assertEquals("/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:

public void constructUriFromTemplate() {
    UriComponents uriComponents = UriComponentsBuilder.newInstance()

    assertEquals("/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:

public void constructUriWithQueryParameter() {
    UriComponents uriComponents = UriComponentsBuilder.newInstance()

     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:

public void expandWithRegexVar() {
    String template = "/myurl/{name:[a-z]{1,5}}/show";
    UriComponents uriComponents = UriComponentsBuilder.fromUriString(template)
    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.

November Discount Launch 2022 – Bottom
We’re finally running a Black Friday launch. All Courses are 30% off until end-of-day today:


Generic footer banner
Comments are closed on this article!