root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 6 Packages Projects Releases Wiki Activity

Minor polishing for URI encoding docs

This commit is contained in:
Rossen Stoyanchev 2018-06-12 10:14:35 -04:00
parent 0b64bcd319
commit 0c669def4f
1 changed files with 21 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
src/docs/asciidoc/web/web-uris.adoc
View File

@ -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.