spring-framework/src/docs/asciidoc/web/web-uris.adoc

[[web-uricomponents]]
= UriComponents
[.small]#Spring MVC and Spring WebFlux#

`UriComponentsBuilder` helps to build URI's from URI templates with variables:

[source,java,indent=0]
[subs="verbatim,quotes"]
----
	String uriTemplate = "http://example.com/hotels/{hotel}";

	UriComponents uriComponents = UriComponentsBuilder.fromUriString(uriTemplate)  // <1>
			.queryParam("q", "{q}")  // <2>
			.encode() // <3>
			.build(); // <4>

	URI uri = uriComponents.expand("Westin", "123").toUri();  // <5>
----
<1> Static factory method with a URI template.
<2> Add and/or replace URI components.
<3> Request to have the URI template and URI variables encoded.
<4> Build a `UriComponents`.
<5> Expand variables, and obtain the `URI`.

The above can also be done in shorthand form:

[source,java,indent=0]
[subs="verbatim,quotes"]
----
	URI uri = UriComponentsBuilder.fromUriString(uriTemplate)
			.queryParam("q", "{q}")
			.encode()
			.buildAndExpand("Westin", "123")
			.toUri();
----


[[web-uribuilder]]
= UriBuilder
[.small]#Spring MVC and Spring WebFlux#

<<web-uricomponents,UriComponentsBuilder>> implements `UriBuilder`. A `UriBuilder` in turn
can be created with a `UriBuilderFactory`. Together `UriBuilderFactory` and `UriBuilder`
provide a pluggable mechanism to build URIs from URI templates, based on shared
configuration such as a base url, encoding preferences, and others.

The `RestTemplate` and the `WebClient` can be configured with a `UriBuilderFactory`
to customize the preparation of URIs. `DefaultUriBuilderFactory` is a default
implementation of `UriBuilderFactory` that uses `UriComponentsBuilder` internally and
exposes shared configuration options.

`RestTemplate` example:

[source,java,indent=0]
[subs="verbatim,quotes"]
----
	// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode;

	String baseUrl = "http://example.org";
	DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl);
	factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VARIABLES);

	RestTemplate restTemplate = new RestTemplate();
	restTemplate.setUriTemplateHandler(factory);
----

`WebClient` example:

[source,java,indent=0]
[subs="verbatim,quotes"]
----
	// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode;

	String baseUrl = "http://example.org";
	DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl);
	factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VARIABLES);

	WebClient client = WebClient.builder().uriBuilderFactory(factory).build();
----

In addition `DefaultUriBuilderFactory` can also be used directly. It is similar to using
`UriComponentsBuilder` but instead of static factory methods, it is an actual instance
that holds configuration and preferences:

[source,java,indent=0]
[subs="verbatim,quotes"]
----
	String baseUrl = "http://example.com";
	DefaultUriBuilderFactory uriBuilderFactory = new DefaultUriBuilderFactory(baseUrl);

	URI uri = uriBuilderFactory.uriString("/hotels/{hotel}")
			.queryParam("q", "{q}")
			.build("Westin", "123");
----


[[web-uri-encoding]]
= URI Encoding
[.small]#Spring MVC and Spring WebFlux#

`UriComponentsBuilder` exposes encoding options at 2 levels:

. {api-spring-framework}/web/util/UriComponentsBuilder.html#encode--[UriComponentsBuilder#encode()] -
pre-encodes the URI template first, then strictly encodes URI variables when expanded.
. {api-spring-framework}/web/util/UriComponents.html#encode--[UriComponents#encode()] -
encodes URI components _after_ URI variables are expanded.

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

[TIP]
====
Consider ";" which is legal in a path but has reserved meaning. Option 1 replaces
";" with "%3B" in URI variables but not in the URI template. By contrast, option 2 never
replaces ";" since it is a legal character in a path.
====

For most cases option 1 is likely to give the expected result because it treats URI
variables as opaque data to be fully encoded, while option 2 is useful only if
URI variables intentionally contain reserved characters.

Example usage using option 1:

[source,java,indent=0]
[subs="verbatim,quotes"]
----
	UriComponentsBuilder.fromPath("/hotel list/{city}")
			.queryParam("q", "{q}")
			.encode()
			.buildAndexpand("New York", "foo+bar")
			.toUriString();

	// Result is "/hotel%20list/New%20York?foo%2Bbar"
----

The `WebClient` and the `RestTemplate` expand and encode URI templates internally through
the `UriBuilderFactory` strategy. Both can be configured with a custom strategy:

[source,java,indent=0]
[subs="verbatim,quotes"]
----
	String baseUrl = "http://example.com";
	DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl)
	factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);

	// Customize the RestTemplate..
	RestTemplate restTemplate = new RestTemplate();
	restTemplate.setUriTemplateHandler(factory);

	// Customize the WebClient..
	WebClient client = WebClient.builder().uriBuilderFactory(factory).build();
----

The `DefaultUriBuilderFactory` implementation uses `UriComponentsBuilder` internally to
expand and encode URI templates. As a factory it provides a single place to configure
the approach to encoding based on one of the below encoding modes:

* `TEMPLATE_AND_VALUES` -- uses `UriComponentsBuilder#encode()`, corresponding to
option 1 above, to pre-encode the URI template and strictly encode URI variables when
expanded.
* `VALUES_ONLY` -- does not encode the URI template and instead applies strict encoding
to URI variables via `UriUtils#encodeUriUriVariables` prior to expanding them into the
template.
* `URI_COMPONENTS` -- uses `UriComponents#encode()`, corresponding to option 2 above, to
encode URI component value _after_ URI variables are expanded.
* `NONE` -- no encoding is applied.

Out of the box the `RestTemplate` is set to `EncodingMode.URI_COMPONENTS` for historic
reasons and for backwards compatibility. The `WebClient` relies on the default value
in `DefaultUriBuilderFactory` which was changed from `EncodingMode.URI_COMPONENTS` in
5.0.x to `EncodingMode.TEMPLATE_AND_VALUES` in 5.1.