Minor polishing for URI encoding docs
This commit is contained in:
parent
0b64bcd319
commit
0c669def4f
|
@ -104,29 +104,24 @@ An example of using the `DefaultUriBuilderFactory`:
|
||||||
= URI Encoding
|
= URI Encoding
|
||||||
[.small]#Spring MVC and Spring WebFlux#
|
[.small]#Spring MVC and Spring WebFlux#
|
||||||
|
|
||||||
The default way of encoding URIs in `UriComponents` works as follows:
|
By default `UriComponents` encodes only characters that are illegal within a given URI
|
||||||
|
component, but not all characters with reserved meaning. More specifically `UriComponents`
|
||||||
|
does the following:
|
||||||
|
|
||||||
. URI variables are expanded.
|
. Expand URI variables.
|
||||||
. Each URI component (path, query, etc) is encoded individually.
|
. Encode each URI component (path, query, etc) individually, by applying percent encoding
|
||||||
|
to illegal characters such as non-US-ASCII characters as well as any characters that are
|
||||||
|
illegal within the URI component, as per RFC 3986.
|
||||||
|
|
||||||
The rules for encoding are as follows: within a URI component, apply percent encoding to
|
This is comparable to the way the `java.net.URI` multi-argument constructor works and is
|
||||||
all illegal characters, including non-US-ASCII characters, and all other characters that
|
described in the "Escaped octets, quotation, encoding, and decoding" section of its Javadoc.
|
||||||
are illegal within the URI component, as defined in RFC 3986.
|
|
||||||
|
|
||||||
[TIP]
|
In some cases, you may want to ensure that expanded URI variables do not impact the
|
||||||
====
|
structure and meaning of the URI. That means encoding not only illegal characters but also
|
||||||
The encoding in `UriComponents` is comparable to the multi-argument constructor of
|
all characters with reserved meaning in a URI.
|
||||||
`java.net.URI`, as described in the "Escaped octets, quotation, encoding, and decoding"
|
|
||||||
section of its class-level Javadoc.
|
|
||||||
====
|
|
||||||
|
|
||||||
The above default encoding strategy *does not* encode all characters with reserved
|
The `WebClient` and the `RestTemplate` can be switched to a different encoding mode
|
||||||
meaning, but only the ones that are illegal within a given URI component. If this is not
|
through the <<web-uribuilder,UriBuilderFactory>> strategy:
|
||||||
what you expect, you can use the alternative strategy described next.
|
|
||||||
|
|
||||||
When using <<web-uribuilder,DefaultUriBuilderFactory>> -- plugged into the `WebClient`,
|
|
||||||
`RestTemplate`, or used directly, you can switch to an alternative encoding strategy as
|
|
||||||
shown below:
|
|
||||||
|
|
||||||
[source,java,indent=0]
|
[source,java,indent=0]
|
||||||
[subs="verbatim,quotes"]
|
[subs="verbatim,quotes"]
|
||||||
|
@ -135,11 +130,13 @@ shown below:
|
||||||
DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl)
|
DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl)
|
||||||
factory.setEncodingMode(EncodingMode.VALUES_ONLY);
|
factory.setEncodingMode(EncodingMode.VALUES_ONLY);
|
||||||
|
|
||||||
// ...
|
WebClient client = WebClient.builder().uriBuilderFactory(factory).build();
|
||||||
|
|
||||||
|
RestTemplate restTemplate = new RestTemplate();
|
||||||
|
restTemplate.setUriTemplateHandler(factory);
|
||||||
----
|
----
|
||||||
|
|
||||||
This alternative encoding strategy applies `UriUtils.encode(String, Charset)` to each URI
|
Internally `DefaultUriBuilderFactory` delegates to `UriUtils.encode(String, Charset)` to
|
||||||
variable value prior to expanding it, effectively encoding all non-US-ASCII characters,
|
encode each URI variable value prior to expanding it, effectively encoding both all
|
||||||
and *all* characters with reserved meaning in a URI, which ensures that the expanded URI
|
non-US-ASCII characters, and characters with reserved meaning in a URI.
|
||||||
variables do not have any impact on the structure or meaning of the URI.
|
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue