|
40 | 40 | */
|
41 | 41 | public class DefaultUriBuilderFactory implements UriBuilderFactory {
|
42 | 42 |
|
43 |
| - |
44 | 43 | /**
|
45 |
| - * Constants that represent different URI encoding strategies. |
| 44 | + * Enum to represent multiple URI encoding strategies. |
46 | 45 | * @see #setEncodingMode
|
47 | 46 | */
|
48 | 47 | public enum EncodingMode {
|
49 | 48 |
|
50 | 49 | /**
|
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: |
53 | 52 | * <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. |
58 | 57 | * </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. |
60 | 62 | * @since 5.0.8
|
61 | 63 | * @see UriComponentsBuilder#encode()
|
62 | 64 | */
|
63 | 65 | TEMPLATE_AND_VALUES,
|
64 | 66 |
|
65 | 67 | /**
|
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. |
68 | 71 | * @see UriUtils#encodeUriVariables(Object...)
|
69 | 72 | * @see UriUtils#encodeUriVariables(Map)
|
70 | 73 | */
|
71 | 74 | VALUES_ONLY,
|
72 | 75 |
|
73 | 76 | /**
|
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. |
80 | 81 | * @see UriComponents#encode()
|
81 | 82 | */
|
82 | 83 | URI_COMPONENT,
|
@@ -129,13 +130,16 @@ public DefaultUriBuilderFactory(UriComponentsBuilder baseUri) {
|
129 | 130 |
|
130 | 131 |
|
131 | 132 | /**
|
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. |
139 | 143 | * @param encodingMode the encoding mode to use
|
140 | 144 | */
|
141 | 145 | public void setEncodingMode(EncodingMode encodingMode) {
|
|
0 commit comments