Skip to content

Commit 6c4289e

Browse files
committed
Polish
1 parent 0bd7a36 commit 6c4289e

File tree

4 files changed

+63
-50
lines changed

4 files changed

+63
-50
lines changed

spring-web/src/main/java/org/springframework/web/util/DefaultUriBuilderFactory.java

Lines changed: 28 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -40,43 +40,44 @@
4040
*/
4141
public class DefaultUriBuilderFactory implements UriBuilderFactory {
4242

43-
4443
/**
45-
* Constants that represent different URI encoding strategies.
44+
* Enum to represent multiple URI encoding strategies.
4645
* @see #setEncodingMode
4746
*/
4847
public enum EncodingMode {
4948

5049
/**
51-
* Encode the URI template first, and URI variables later when expanded,
52-
* applying the following to each:
50+
* Pre-encode the URI template first, then strictly encode URI variables
51+
* when expanded, with the following rules:
5352
* <ul>
54-
* <li>URI template is encoded by quoting <em>only</em> illegal
55-
* characters within a given URI component type.
56-
* <li>URI variables are encoded strictly, by quoting both illegal
57-
* characters and characters with reserved meaning.
53+
* <li>For the URI template replace <em>only</em> non-ASCII and illegal
54+
* (within a given URI component type) characters with escaped octets.
55+
* <li>For URI variables do the same and also replace characters with
56+
* reserved meaning.
5857
* </ul>
59-
* <p>For most cases this should be the preferred encoding mode.
58+
* <p>For most cases, this mode is most likely to give the expected
59+
* result because in treats URI variables as opaque data to be fully
60+
* encoded, while {@link #URI_COMPONENT} by comparison is useful only
61+
* if intentionally expanding URI variables with reserved characters.
6062
* @since 5.0.8
6163
* @see UriComponentsBuilder#encode()
6264
*/
6365
TEMPLATE_AND_VALUES,
6466

6567
/**
66-
* Encode only URI variables strictly quoting both illegal characters
67-
* and characters with reserved meaning.
68+
* Does not encode the URI template and instead applies strict encoding
69+
* to URI variables via {@link UriUtils#encodeUriVariables} prior to
70+
* expanding them into the template.
6871
* @see UriUtils#encodeUriVariables(Object...)
6972
* @see UriUtils#encodeUriVariables(Map)
7073
*/
7174
VALUES_ONLY,
7275

7376
/**
74-
* Expand URI variables first, and then encode the expanded URI component
75-
* values, quoting <em>only</em> illegal characters within a given URI
76-
* component type, but not all characters with reserved meaning.
77-
* <p>This is the mode historically used in the {@code RestTemplate} but
78-
* as of 5.0.8 {@link #TEMPLATE_AND_VALUES} is the recommended encoding
79-
* mode to use instead.
77+
* Expand URI variables first, and then encode the resulting URI
78+
* component values, replacing <em>only</em> non-ASCII and illegal
79+
* (within a given URI component type) characters, but not characters
80+
* with reserved meaning.
8081
* @see UriComponents#encode()
8182
*/
8283
URI_COMPONENT,
@@ -129,13 +130,16 @@ public DefaultUriBuilderFactory(UriComponentsBuilder baseUri) {
129130

130131

131132
/**
132-
* Specify the {@link EncodingMode EncodingMode} to use to encode URIs.
133-
*
134-
* <p><strong>Note:</strong> in 5.1 the default value was changed from
135-
* {@link EncodingMode#URI_COMPONENT URI_COMPONENT} to the now recommended
136-
* {@link EncodingMode#TEMPLATE_AND_VALUES TEMPLATE_AND_VALUES} mode of
137-
* encoding.
138-
*
133+
* Set the encoding mode to use.
134+
* <p>By default this is set to {@link EncodingMode#TEMPLATE_AND_VALUES
135+
* EncodingMode.TEMPLATE_AND_VALUES}.
136+
* <p><strong>Note:</strong> In 5.1 the default was changed from
137+
* {@link EncodingMode#URI_COMPONENT EncodingMode.URI_COMPONENT}.
138+
* Consequently the {@code WebClient}, which relies on the built-in default
139+
* has also been switched to the new default. The {@code RestTemplate}
140+
* however sets this explicitly to {@link EncodingMode#URI_COMPONENT
141+
* EncodingMode.URI_COMPONENT} explicitly for historic and backwards
142+
* compatibility reasons.
139143
* @param encodingMode the encoding mode to use
140144
*/
141145
public void setEncodingMode(EncodingMode encodingMode) {

spring-web/src/main/java/org/springframework/web/util/UriComponents.java

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -132,9 +132,10 @@ public final String getFragment() {
132132
* Invoke this <em>after</em> expanding URI variables to encode the
133133
* resulting URI component values.
134134
* <p>In comparison to {@link UriComponentsBuilder#encode()}, this method
135-
* quotes <em>only</em> illegal characters within a given URI component type,
136-
* but not all characters with reserved meaning. For most cases, prefer
137-
* using {@link UriComponentsBuilder#encode()} over this method.
135+
* <em>only</em> replaces non-ASCII and illegal (within a given URI
136+
* component type) characters, but not characters with reserved meaning.
137+
* For most cases, {@link UriComponentsBuilder#encode()} is more likely
138+
* to give the expected result.
138139
* @see UriComponentsBuilder#encode()
139140
*/
140141
public final UriComponents encode() {

spring-web/src/main/java/org/springframework/web/util/UriComponentsBuilder.java

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -328,19 +328,21 @@ public static UriComponentsBuilder fromOriginHeader(String origin) {
328328
// Encode methods
329329

330330
/**
331-
* Request to have the URI template encoded first at build time, and
332-
* URI variables encoded later when expanded.
331+
* Request to have the URI template pre-encoded at build time, and
332+
* URI variables encoded separately when expanded.
333333
* <p>In comparison to {@link UriComponents#encode()}, this method has the
334334
* same effect on the URI template, i.e. each URI component is encoded by
335-
* quoting <em>only</em> illegal characters within that URI component type.
336-
* However URI variables are encoded more strictly, by quoting both illegal
337-
* characters and characters with reserved meaning.
338-
* <p>For most cases, prefer this method over {@link UriComponents#encode()}
339-
* which is useful only if intentionally expanding variables with reserved
340-
* characters. For example ';' is legal in a path, but also has reserved
341-
* meaning as a separator. When expanding a variable that contains ';' it
342-
* probably should be encoded, unless the intent is to insert path params
343-
* through the expanded variable.
335+
* replacing non-ASCII and illegal (within the URI component type) characters
336+
* with escaped octets. However URI variables are encoded more strictly, by
337+
* also escaping characters with reserved meaning.
338+
* <p>For most cases, this method is more likely to give the expected result
339+
* because in treats URI variables as opaque data to be fully encoded, while
340+
* {@link UriComponents#encode()} is useful only if intentionally expanding
341+
* URI variables that contain reserved characters.
342+
* <p>For example ';' is legal in a path but has reserved meaning. This
343+
* method replaces ";" with "%3B" in URI variables but not in the URI
344+
* template. By contrast, {@link UriComponents#encode()} never replaces ";"
345+
* since it is a legal character in a path.
344346
* @since 5.0.8
345347
*/
346348
public final UriComponentsBuilder encode() {

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

Lines changed: 18 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -116,9 +116,9 @@ Consider ";" which is legal in a path but has reserved meaning. Option 1 replace
116116
replaces ";" since it is a legal character in a path.
117117
====
118118

119-
For most cases option 1 is likely to give the expected result because in treats URI
119+
For most cases option 1 is likely to give the expected result because it treats URI
120120
variables as opaque data to be fully encoded, while option 2 is useful only if
121-
intentionally expanding URI variables that contain reserved characters.
121+
URI variables intentionally contain reserved characters.
122122

123123
Example usage using option 1:
124124

@@ -135,7 +135,7 @@ Example usage using option 1:
135135
----
136136

137137
The `WebClient` and the `RestTemplate` expand and encode URI templates internally through
138-
the `UriBuilderFactory` strategy. Both can be configured wiht a custom instance:
138+
the `UriBuilderFactory` strategy. Both can be configured with a custom strategy:
139139

140140
[source,java,indent=0]
141141
[subs="verbatim,quotes"]
@@ -144,23 +144,29 @@ the `UriBuilderFactory` strategy. Both can be configured wiht a custom instance:
144144
DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl)
145145
factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);
146146
147+
// Customize the RestTemplate..
147148
RestTemplate restTemplate = new RestTemplate();
148149
restTemplate.setUriTemplateHandler(factory);
149150
151+
// Customize the WebClient..
150152
WebClient client = WebClient.builder().uriBuilderFactory(factory).build();
151153
----
152154

153-
The `DefaultUriBuilderFactory` implementation shown above uses `UriComponentsBuilder`
154-
internally. The approach to encoding is controlled through one of the encoding modes
155-
listed below:
155+
The `DefaultUriBuilderFactory` implementation uses `UriComponentsBuilder` internally to
156+
expand and encode URI templates. As a factory it provides a single place to configure
157+
the approach to encoding based on one of the below encoding modes:
156158

157-
* `TEMPLATE_AND_VALUES` -- uses `UriComponentsBuilder#encode()`, corresponding to option
158-
1 above, to pre-encode the URI template and strictly encode URI variables when expanded.
159-
* `VALUES_ONLY` -- variant of `TEMPLATE_AND_VALUES` that does not encode the URI template.
159+
* `TEMPLATE_AND_VALUES` -- uses `UriComponentsBuilder#encode()`, corresponding to
160+
option 1 above, to pre-encode the URI template and strictly encode URI variables when
161+
expanded.
162+
* `VALUES_ONLY` -- does not encode the URI template and instead applies strict encoding
163+
to URI variables via `UriUtils#encodeUriUriVariables` prior to expanding them into the
164+
template.
160165
* `URI_COMPONENTS` -- uses `UriComponents#encode()`, corresponding to option 2 above, to
161166
encode URI component value _after_ URI variables are expanded.
162167
* `NONE` -- no encoding is applied.
163168

164-
Out of the box the `RestTemplate` uses `EncodingMode.URI_COMPONENTS` for historic reasons
165-
and for backwards compatibility. The `WebClient` uses `EncodingMode.TEMPLATE_AND_VALUES`
166-
starting in 5.1, and `EncodingMode.URI_COMPONENTS` in 5.0.x.
169+
Out of the box the `RestTemplate` is set to `EncodingMode.URI_COMPONENTS` for historic
170+
reasons and for backwards compatibility. The `WebClient` relies on the default value
171+
in `DefaultUriBuilderFactory` which was changed from `EncodingMode.URI_COMPONENTS` in
172+
5.0.x to `EncodingMode.TEMPLATE_AND_VALUES` in 5.1.

0 commit comments

Comments
 (0)