diff --git a/spring-web/src/main/java/org/springframework/web/client/RestTemplate.java b/spring-web/src/main/java/org/springframework/web/client/RestTemplate.java index ae32dfaefc..993a1b55f1 100644 --- a/spring-web/src/main/java/org/springframework/web/client/RestTemplate.java +++ b/spring-web/src/main/java/org/springframework/web/client/RestTemplate.java @@ -298,18 +298,16 @@ public class RestTemplate extends InterceptingHttpAccessor implements RestOperat } /** - * Configure the {@link UriTemplateHandler} to use to expand URI templates. - * By default the {@link DefaultUriBuilderFactory} is used which relies on - * Spring's URI template support and exposes several useful properties that - * customize its behavior for encoding and for pre-pending a common base URL. - * An alternative implementation may be used to plug an external URI - * template library. - *

Note: if switching from + * Customize how URI templates are expanded into URI instances. + *

By default {@link DefaultUriBuilderFactory} with default settings is + * used. You can supply a {@code DefaultUriBuilderFactory} configured + * differently, or an entirely different implementation, for example that + * plugs in a 3rd party URI template library. + *

Note: in 5.0 the switch from * {@link org.springframework.web.util.DefaultUriTemplateHandler - * DefaultUriTemplateHandler} (deprecated in 4.3) to - * {@link DefaultUriBuilderFactory} keep in mind that the - * {@link DefaultUriBuilderFactory} has a different default for the - * {@code parsePath} property (from false to true). + * DefaultUriTemplateHandler} (deprecated in 4.3), as the default to use, to + * {@link DefaultUriBuilderFactory} brings in a different default for the + * {@code parsePath} property (switching from false to true). * @param handler the URI template handler to use */ public void setUriTemplateHandler(UriTemplateHandler handler) { diff --git a/spring-web/src/main/java/org/springframework/web/util/DefaultUriBuilderFactory.java b/spring-web/src/main/java/org/springframework/web/util/DefaultUriBuilderFactory.java index 38b0e365d5..19451d5019 100644 --- a/spring-web/src/main/java/org/springframework/web/util/DefaultUriBuilderFactory.java +++ b/spring-web/src/main/java/org/springframework/web/util/DefaultUriBuilderFactory.java @@ -17,6 +17,7 @@ package org.springframework.web.util; import java.net.URI; +import java.nio.charset.Charset; import java.util.Collections; import java.util.HashMap; import java.util.List; @@ -28,11 +29,12 @@ import org.springframework.util.MultiValueMap; import org.springframework.util.ObjectUtils; /** - * Default implementation of {@link UriBuilderFactory} providing options to - * pre-configure all {@link UriBuilder} instances with common properties - * such as a base URI, encoding mode, and default URI variables. + * {@code UriBuilderFactory} that relies on {@link UriComponentsBuilder} for + * the actual building of the URI. + * + *

Provides options to create {@link UriBuilder} instances with a common + * base URI, alternative encoding mode strategies, among others. * - *

Uses {@link UriComponentsBuilder} for URI building. * * @author Rossen Stoyanchev * @since 5.0 @@ -40,7 +42,43 @@ import org.springframework.util.ObjectUtils; */ public class DefaultUriBuilderFactory implements UriBuilderFactory { - public enum EncodingMode {URI_COMPONENT, VALUES_ONLY, NONE} + + /** + * Constants that represent different URI encoding strategies. + * @see #setEncodingMode + */ + public enum EncodingMode { + + /** + * The default way of encoding that {@link UriComponents} supports: + *

    + *
  1. Expand URI variables. + *
  2. Encode individual URI components as described in + * {@link UriComponents#encode(Charset)}. + *
+ *

This mode does not encode all characters with + * reserved meaning but only the ones that are illegal within a given + * URI component as defined in RFC 396. This matches the way the + * multi-argument {@link URI} constructor does encoding. + */ + URI_COMPONENT, + + /** + * Comprehensive encoding of URI variable values prior to expanding: + *

    + *
  1. Apply {@link UriUtils#encode(String, Charset)} to each URI variable value. + *
  2. Expand URI variable values. + *
+ *

This mode encodes all characters with reserved meaning, therefore + * ensuring that expanded URI variable do not have any impact on the + * structure or meaning of the URI. + */ + VALUES_ONLY, + + /** + * No encoding should be applied. + */ + NONE } private final UriComponentsBuilder baseUri; @@ -103,20 +141,9 @@ public class DefaultUriBuilderFactory implements UriBuilderFactory { } /** - * Specify the encoding mode to use when building URIs: - *

- *

By default this is set to {@code "URI_COMPONENT"}. + * Specify the {@link EncodingMode EncodingMode} to use when building URIs. + *

By default set to + * {@link EncodingMode#URI_COMPONENT EncodingMode.URI_COMPONENT}. * @param encodingMode the encoding mode to use */ public void setEncodingMode(EncodingMode encodingMode) { diff --git a/spring-web/src/main/java/org/springframework/web/util/UriBuilderFactory.java b/spring-web/src/main/java/org/springframework/web/util/UriBuilderFactory.java index 926b7208fc..bd3096a62a 100644 --- a/spring-web/src/main/java/org/springframework/web/util/UriBuilderFactory.java +++ b/spring-web/src/main/java/org/springframework/web/util/UriBuilderFactory.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2017 the original author or authors. + * Copyright 2002-2018 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -16,8 +16,9 @@ package org.springframework.web.util; /** - * Factory to create {@link UriBuilder} instances pre-configured in a specific - * way such as sharing a common base URI across all builders. + * Factory to create {@link UriBuilder} instances with shared configuration + * such as a base URI, an encoding mode strategy, and others across all URI + * builder instances created through a factory. * * @author Rossen Stoyanchev * @since 5.0 @@ -25,15 +26,14 @@ package org.springframework.web.util; public interface UriBuilderFactory extends UriTemplateHandler { /** - * Create a builder from the given URI template string. - * Implementations may further combine the URI template with a base URI. + * Initialize a builder with the given URI template. * @param uriTemplate the URI template to use - * @return the builder instance + * @return the URI builder instance */ UriBuilder uriString(String uriTemplate); /** - * Create a builder with default settings. + * Create a URI builder with default settings. * @return the builder instance */ UriBuilder builder(); diff --git a/spring-web/src/main/java/org/springframework/web/util/UriTemplateHandler.java b/spring-web/src/main/java/org/springframework/web/util/UriTemplateHandler.java index d394d34f31..48b1333d89 100644 --- a/spring-web/src/main/java/org/springframework/web/util/UriTemplateHandler.java +++ b/spring-web/src/main/java/org/springframework/web/util/UriTemplateHandler.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2017 the original author or authors. + * Copyright 2002-2018 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -20,30 +20,27 @@ import java.net.URI; import java.util.Map; /** - * Strategy for expanding a URI template. - * - *

Supported as a property on the {@code RestTemplate} as well as the - * {@code AsyncRestTemplate}. + * Defines methods for expanding a URI template with variables. * * @author Rossen Stoyanchev * @since 4.2 - * @see DefaultUriBuilderFactory + * @see org.springframework.web.client.RestTemplate#setUriTemplateHandler(UriTemplateHandler) */ public interface UriTemplateHandler { /** - * Expand the given URI template from a map of URI variables. - * @param uriTemplate the URI template string - * @param uriVariables the URI variables - * @return the resulting URI + * Expand the given URI template with a map of URI variables. + * @param uriTemplate the URI template + * @param uriVariables variable values + * @return the created URI instance */ URI expand(String uriTemplate, Map uriVariables); /** - * Expand the given URI template from an array of URI variables. - * @param uriTemplate the URI template string - * @param uriVariables the URI variable values - * @return the resulting URI + * Expand the given URI template with an array of URI variables. + * @param uriTemplate the URI template + * @param uriVariables variable values + * @return the created URI instance */ URI expand(String uriTemplate, Object... uriVariables);