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

Polish UriBuilderFactory and implementation 

Issue: SPR-16422
This commit is contained in:
Rossen Stoyanchev 2017-11-02 15:03:26 -04:00
parent 3d20db1e49
commit 4db0d999af
4 changed files with 73 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
spring-web/src/main/java/org/springframework/web/client/RestTemplate.java
View File

@ -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.
* <p><strong>Note:</strong> if switching from
* Customize how URI templates are expanded into URI instances.
* <p>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.
* <p><strong>Note:</strong> 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) {

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

@ -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.
*
* <p>Provides options to create {@link UriBuilder} instances with a common
* base URI, alternative encoding mode strategies, among others.
*
* <p>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:
* <ol>
* <li>Expand URI variables.
* <li>Encode individual URI components as described in
* {@link UriComponents#encode(Charset)}.
* </ol>
* <p>This mode <strong>does not</strong> 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:
* <ol>
* <li>Apply {@link UriUtils#encode(String, Charset)} to each URI variable value.
* <li>Expand URI variable values.
* </ol>
* <p>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:
* <ul>
* <li>URI_COMPONENT -- expand the URI variables first and then encode all URI
* component (e.g. host, path, query, etc) according to the encoding rules
* for each individual component.
* <li>VALUES_ONLY -- encode URI variable values only, prior to expanding
* them, using a "strict" encoding mode, i.e. encoding all characters
* outside the unreserved set as defined in
* <a href="https://tools.ietf.org/html/rfc3986#section-2">RFC 3986 Section 2</a>.
* This ensures a URI variable value will not contain any characters with a
* reserved purpose.
* <li>NONE -- in this mode no encoding is performed.
* </ul>
* <p>By default this is set to {@code "URI_COMPONENT"}.
* Specify the {@link EncodingMode EncodingMode} to use when building URIs.
* <p>By default set to
* {@link EncodingMode#URI_COMPONENT EncodingMode.URI_COMPONENT}.
* @param encodingMode the encoding mode to use
*/
public void setEncodingMode(EncodingMode encodingMode) {

14
spring-web/src/main/java/org/springframework/web/util/UriBuilderFactory.java
View File

@ -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();

25
spring-web/src/main/java/org/springframework/web/util/UriTemplateHandler.java
View File

@ -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.
*
* <p>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<String, ?> 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);