diff --git a/spring-web/src/main/java/org/springframework/web/util/HierarchicalUriComponents.java b/spring-web/src/main/java/org/springframework/web/util/HierarchicalUriComponents.java index ddd1faa3cf..d34f9b51ad 100644 --- a/spring-web/src/main/java/org/springframework/web/util/HierarchicalUriComponents.java +++ b/spring-web/src/main/java/org/springframework/web/util/HierarchicalUriComponents.java @@ -374,10 +374,6 @@ final class HierarchicalUriComponents extends UriComponents { return result; } - /** - * Normalize the path removing sequences like "path/..". - * @see StringUtils#cleanPath(String) - */ @Override public UriComponents normalize() { String normalizedPath = StringUtils.cleanPath(getPath()); @@ -388,9 +384,6 @@ final class HierarchicalUriComponents extends UriComponents { // Other functionality - /** - * Returns a URI String from this {@code UriComponents} instance. - */ @Override public String toUriString() { StringBuilder uriBuilder = new StringBuilder(); @@ -431,9 +424,6 @@ final class HierarchicalUriComponents extends UriComponents { return uriBuilder.toString(); } - /** - * Returns a {@code URI} from this {@code UriComponents} instance. - */ @Override public URI toUri() { try { @@ -448,8 +438,7 @@ final class HierarchicalUriComponents extends UriComponents { path = PATH_DELIMITER + path; } } - return new URI(getScheme(), getUserInfo(), getHost(), getPort(), path, getQuery(), - getFragment()); + return new URI(getScheme(), getUserInfo(), getHost(), getPort(), path, getQuery(), getFragment()); } } catch (URISyntaxException ex) { diff --git a/spring-web/src/main/java/org/springframework/web/util/UriComponents.java b/spring-web/src/main/java/org/springframework/web/util/UriComponents.java index 89c83626fb..8bb328b11f 100644 --- a/spring-web/src/main/java/org/springframework/web/util/UriComponents.java +++ b/spring-web/src/main/java/org/springframework/web/util/UriComponents.java @@ -128,21 +128,23 @@ public abstract class UriComponents implements Serializable { /** - * Encode all URI components using their specific encoding rules, and returns the - * result as a new {@code UriComponents} instance. This method uses UTF-8 to encode. - * @return the encoded URI components + * A variant of {@link #encode(Charset)} that uses "UTF-8" as the charset. + * @return a new {@code UriComponents} instance with encoded values */ public final UriComponents encode() { return encode(StandardCharsets.UTF_8); } /** - * Encode all URI components using their specific encoding rules, and - * returns the result as a new {@code UriComponents} instance. + * Encode each URI component by percent encoding illegal characters, which + * includes non-US-ASCII characters, and also characters that are otherwise + * illegal within a given URI component type, as defined in RFC 3986. The + * effect of this method, with regards to encoding, is comparable to using + * the multi-argument constructor of {@link URI}. * @param charset the encoding of the values contained in this map - * @return the encoded URI components + * @return a new {@code UriComponents} instance with encoded values */ - public abstract UriComponents encode(Charset charset) ; + public abstract UriComponents encode(Charset charset); /** * Replace all URI template variables with the values from a given map. @@ -187,23 +189,36 @@ public abstract class UriComponents implements Serializable { abstract UriComponents expandInternal(UriTemplateVariables uriVariables); /** - * Normalize the path removing sequences like "path/..". Note that calling this method will - * combine all path segments into a full path before doing the actual normalisation, i.e. - * individual path segments will not be normalized individually. + * Normalize the path removing sequences like "path/..". Note that + * normalization is applied to the full path, and not to individual path + * segments. * @see org.springframework.util.StringUtils#cleanPath(String) */ public abstract UriComponents normalize(); /** - * Return a URI String from this {@code UriComponents} instance. + * Concatenate all URI components to return the fully formed URI String. + *

This method does nothing more than a simple concatenation based on + * current values. That means it could produce different results if invoked + * before vs after methods that can change individual values such as + * {@code encode}, {@code expand}, or {@code normalize}. */ public abstract String toUriString(); /** - * Return a {@code URI} from this {@code UriComponents} instance. + * Create a {@link URI} from this instance as follows: + *

If the current instance is {@link #encode() encoded}, form the full + * URI String via {@link #toUriString()}, and then pass it to the single + * argument {@link URI} constructor which preserves percent encoding. + *

If not yet encoded, pass individual URI component values to the + * multi-argument {@link URI} constructor which quotes illegal characters + * that cannot appear in their respective URI component. */ public abstract URI toUri(); + /** + * A simple pass-through to {@link #toUriString()}. + */ @Override public final String toString() { return toUriString(); diff --git a/spring-web/src/main/java/org/springframework/web/util/UriUtils.java b/spring-web/src/main/java/org/springframework/web/util/UriUtils.java index 90bf8828ba..b5a0848ec7 100644 --- a/spring-web/src/main/java/org/springframework/web/util/UriUtils.java +++ b/spring-web/src/main/java/org/springframework/web/util/UriUtils.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,31 +16,35 @@ package org.springframework.web.util; -import java.io.UnsupportedEncodingException; +import java.net.URI; import java.nio.charset.Charset; import java.nio.charset.StandardCharsets; import java.util.Arrays; import java.util.LinkedHashMap; import java.util.Map; -import java.util.stream.Collectors; import org.springframework.lang.Nullable; import org.springframework.util.StringUtils; /** - * Utility class for URI encoding and decoding based on RFC 3986. - * Offers encoding methods for the various URI components. + * Utility methods for URI encoding and decoding based on RFC 3986. * - *

All {@code encode*(String, String)} methods in this class operate in a similar way: + *

There are two types of encode methods: *

* * @author Arjen Poutsma * @author Juergen Hoeller + * @author Rossen Stoyanchev * @since 3.0 * @see RFC 3986 */ @@ -51,10 +55,9 @@ public abstract class UriUtils { * @param scheme the scheme to be encoded * @param encoding the character encoding to encode to * @return the encoded scheme - * @throws UnsupportedEncodingException when the given encoding parameter is not supported */ - public static String encodeScheme(String scheme, String encoding) throws UnsupportedEncodingException { - return HierarchicalUriComponents.encodeUriComponent(scheme, encoding, HierarchicalUriComponents.Type.SCHEME); + public static String encodeScheme(String scheme, String encoding) { + return encode(scheme, encoding, HierarchicalUriComponents.Type.SCHEME); } /** @@ -65,7 +68,7 @@ public abstract class UriUtils { * @since 5.0 */ public static String encodeScheme(String scheme, Charset charset) { - return HierarchicalUriComponents.encodeUriComponent(scheme, charset, HierarchicalUriComponents.Type.SCHEME); + return encode(scheme, charset, HierarchicalUriComponents.Type.SCHEME); } /** @@ -73,10 +76,9 @@ public abstract class UriUtils { * @param authority the authority to be encoded * @param encoding the character encoding to encode to * @return the encoded authority - * @throws UnsupportedEncodingException when the given encoding parameter is not supported */ - public static String encodeAuthority(String authority, String encoding) throws UnsupportedEncodingException { - return HierarchicalUriComponents.encodeUriComponent(authority, encoding, HierarchicalUriComponents.Type.AUTHORITY); + public static String encodeAuthority(String authority, String encoding) { + return encode(authority, encoding, HierarchicalUriComponents.Type.AUTHORITY); } /** @@ -87,7 +89,7 @@ public abstract class UriUtils { * @since 5.0 */ public static String encodeAuthority(String authority, Charset charset) { - return HierarchicalUriComponents.encodeUriComponent(authority, charset, HierarchicalUriComponents.Type.AUTHORITY); + return encode(authority, charset, HierarchicalUriComponents.Type.AUTHORITY); } /** @@ -95,10 +97,9 @@ public abstract class UriUtils { * @param userInfo the user info to be encoded * @param encoding the character encoding to encode to * @return the encoded user info - * @throws UnsupportedEncodingException when the given encoding parameter is not supported */ - public static String encodeUserInfo(String userInfo, String encoding) throws UnsupportedEncodingException { - return HierarchicalUriComponents.encodeUriComponent(userInfo, encoding, HierarchicalUriComponents.Type.USER_INFO); + public static String encodeUserInfo(String userInfo, String encoding) { + return encode(userInfo, encoding, HierarchicalUriComponents.Type.USER_INFO); } /** @@ -109,7 +110,7 @@ public abstract class UriUtils { * @since 5.0 */ public static String encodeUserInfo(String userInfo, Charset charset) { - return HierarchicalUriComponents.encodeUriComponent(userInfo, charset, HierarchicalUriComponents.Type.USER_INFO); + return encode(userInfo, charset, HierarchicalUriComponents.Type.USER_INFO); } /** @@ -117,10 +118,9 @@ public abstract class UriUtils { * @param host the host to be encoded * @param encoding the character encoding to encode to * @return the encoded host - * @throws UnsupportedEncodingException when the given encoding parameter is not supported */ - public static String encodeHost(String host, String encoding) throws UnsupportedEncodingException { - return HierarchicalUriComponents.encodeUriComponent(host, encoding, HierarchicalUriComponents.Type.HOST_IPV4); + public static String encodeHost(String host, String encoding) { + return encode(host, encoding, HierarchicalUriComponents.Type.HOST_IPV4); } /** @@ -131,7 +131,7 @@ public abstract class UriUtils { * @since 5.0 */ public static String encodeHost(String host, Charset charset) { - return HierarchicalUriComponents.encodeUriComponent(host, charset, HierarchicalUriComponents.Type.HOST_IPV4); + return encode(host, charset, HierarchicalUriComponents.Type.HOST_IPV4); } /** @@ -139,10 +139,9 @@ public abstract class UriUtils { * @param port the port to be encoded * @param encoding the character encoding to encode to * @return the encoded port - * @throws UnsupportedEncodingException when the given encoding parameter is not supported */ - public static String encodePort(String port, String encoding) throws UnsupportedEncodingException { - return HierarchicalUriComponents.encodeUriComponent(port, encoding, HierarchicalUriComponents.Type.PORT); + public static String encodePort(String port, String encoding) { + return encode(port, encoding, HierarchicalUriComponents.Type.PORT); } /** @@ -153,7 +152,7 @@ public abstract class UriUtils { * @since 5.0 */ public static String encodePort(String port, Charset charset) { - return HierarchicalUriComponents.encodeUriComponent(port, charset, HierarchicalUriComponents.Type.PORT); + return encode(port, charset, HierarchicalUriComponents.Type.PORT); } /** @@ -161,10 +160,9 @@ public abstract class UriUtils { * @param path the path to be encoded * @param encoding the character encoding to encode to * @return the encoded path - * @throws UnsupportedEncodingException when the given encoding parameter is not supported */ - public static String encodePath(String path, String encoding) throws UnsupportedEncodingException { - return HierarchicalUriComponents.encodeUriComponent(path, encoding, HierarchicalUriComponents.Type.PATH); + public static String encodePath(String path, String encoding) { + return encode(path, encoding, HierarchicalUriComponents.Type.PATH); } /** @@ -175,7 +173,7 @@ public abstract class UriUtils { * @since 5.0 */ public static String encodePath(String path, Charset charset) { - return HierarchicalUriComponents.encodeUriComponent(path, charset, HierarchicalUriComponents.Type.PATH); + return encode(path, charset, HierarchicalUriComponents.Type.PATH); } /** @@ -183,10 +181,9 @@ public abstract class UriUtils { * @param segment the segment to be encoded * @param encoding the character encoding to encode to * @return the encoded segment - * @throws UnsupportedEncodingException when the given encoding parameter is not supported */ - public static String encodePathSegment(String segment, String encoding) throws UnsupportedEncodingException { - return HierarchicalUriComponents.encodeUriComponent(segment, encoding, HierarchicalUriComponents.Type.PATH_SEGMENT); + public static String encodePathSegment(String segment, String encoding) { + return encode(segment, encoding, HierarchicalUriComponents.Type.PATH_SEGMENT); } /** @@ -197,7 +194,7 @@ public abstract class UriUtils { * @since 5.0 */ public static String encodePathSegment(String segment, Charset charset) { - return HierarchicalUriComponents.encodeUriComponent(segment, charset, HierarchicalUriComponents.Type.PATH_SEGMENT); + return encode(segment, charset, HierarchicalUriComponents.Type.PATH_SEGMENT); } /** @@ -205,10 +202,9 @@ public abstract class UriUtils { * @param query the query to be encoded * @param encoding the character encoding to encode to * @return the encoded query - * @throws UnsupportedEncodingException when the given encoding parameter is not supported */ - public static String encodeQuery(String query, String encoding) throws UnsupportedEncodingException { - return HierarchicalUriComponents.encodeUriComponent(query, encoding, HierarchicalUriComponents.Type.QUERY); + public static String encodeQuery(String query, String encoding) { + return encode(query, encoding, HierarchicalUriComponents.Type.QUERY); } /** @@ -219,7 +215,7 @@ public abstract class UriUtils { * @since 5.0 */ public static String encodeQuery(String query, Charset charset) { - return HierarchicalUriComponents.encodeUriComponent(query, charset, HierarchicalUriComponents.Type.QUERY); + return encode(query, charset, HierarchicalUriComponents.Type.QUERY); } /** @@ -227,13 +223,10 @@ public abstract class UriUtils { * @param queryParam the query parameter to be encoded * @param encoding the character encoding to encode to * @return the encoded query parameter - * @throws UnsupportedEncodingException when the given encoding parameter is not supported */ - public static String encodeQueryParam(String queryParam, String encoding) - throws UnsupportedEncodingException { + public static String encodeQueryParam(String queryParam, String encoding) { - return HierarchicalUriComponents.encodeUriComponent( - queryParam, encoding, HierarchicalUriComponents.Type.QUERY_PARAM); + return encode(queryParam, encoding, HierarchicalUriComponents.Type.QUERY_PARAM); } /** @@ -244,8 +237,7 @@ public abstract class UriUtils { * @since 5.0 */ public static String encodeQueryParam(String queryParam, Charset charset) { - return HierarchicalUriComponents.encodeUriComponent( - queryParam, charset, HierarchicalUriComponents.Type.QUERY_PARAM); + return encode(queryParam, charset, HierarchicalUriComponents.Type.QUERY_PARAM); } /** @@ -253,13 +245,9 @@ public abstract class UriUtils { * @param fragment the fragment to be encoded * @param encoding the character encoding to encode to * @return the encoded fragment - * @throws UnsupportedEncodingException when the given encoding parameter is not supported */ - public static String encodeFragment(String fragment, String encoding) - throws UnsupportedEncodingException { - - return HierarchicalUriComponents.encodeUriComponent( - fragment, encoding, HierarchicalUriComponents.Type.FRAGMENT); + public static String encodeFragment(String fragment, String encoding) { + return encode(fragment, encoding, HierarchicalUriComponents.Type.FRAGMENT); } /** @@ -270,40 +258,76 @@ public abstract class UriUtils { * @since 5.0 */ public static String encodeFragment(String fragment, Charset charset) { - return HierarchicalUriComponents.encodeUriComponent(fragment, charset, HierarchicalUriComponents.Type.FRAGMENT); + return encode(fragment, charset, HierarchicalUriComponents.Type.FRAGMENT); } /** - * Encode characters outside the unreserved character set as defined in - * RFC 3986 Section 2. - *

This can be used to ensure the given String will not contain any - * characters with reserved URI meaning regardless of URI component. + * Variant of {@link #decode(String, Charset)} with a String charset. * @param source the String to be encoded * @param encoding the character encoding to encode to * @return the encoded String - * @throws UnsupportedEncodingException when the given encoding parameter is not supported */ - public static String encode(String source, String encoding) throws UnsupportedEncodingException { - HierarchicalUriComponents.Type type = HierarchicalUriComponents.Type.URI; - return HierarchicalUriComponents.encodeUriComponent(source, encoding, type); + public static String encode(String source, String encoding) { + return encode(source, encoding, HierarchicalUriComponents.Type.URI); } /** - * Encode characters outside the unreserved character set as defined in - * RFC 3986 Section 2. - *

This can be used to ensure the given String will not contain any - * characters with reserved URI meaning regardless of URI component. + * Encode all characters that are either illegal, or have any reserved + * meaning, anywhere within a URI, as defined in + * RFC 3986. + * This is useful to ensure that the given String will be preserved as-is + * and will not have any o impact on the structure or meaning of the URI. * @param source the String to be encoded * @param charset the character encoding to encode to * @return the encoded String * @since 5.0 */ public static String encode(String source, Charset charset) { - HierarchicalUriComponents.Type type = HierarchicalUriComponents.Type.URI; - return HierarchicalUriComponents.encodeUriComponent(source, charset, type); + return encode(source, charset, HierarchicalUriComponents.Type.URI); + } + + /** + * Convenience method to apply {@link #encode(String, Charset)} to all + * given URI variable values. + * @param uriVariables the URI variable values to be encoded + * @return the encoded String + * @since 5.0 + */ + public static Map encodeUriVariables(Map uriVariables) { + Map result = new LinkedHashMap<>(uriVariables.size()); + uriVariables.forEach((key, value) -> { + String stringValue = (value != null ? value.toString() : ""); + result.put(key, encode(stringValue, StandardCharsets.UTF_8)); + }); + return result; } + /** + * Convenience method to apply {@link #encode(String, Charset)} to all + * given URI variable values. + * @param uriVariables the URI variable values to be encoded + * @return the encoded String + * @since 5.0 + */ + public static Object[] encodeUriVariables(Object... uriVariables) { + return Arrays.stream(uriVariables) + .map(value -> { + String stringValue = (value != null ? value.toString() : ""); + return encode(stringValue, StandardCharsets.UTF_8); + }) + .toArray(); + } + + private static String encode(String scheme, String encoding, HierarchicalUriComponents.Type type) { + return HierarchicalUriComponents.encodeUriComponent(scheme, encoding, type); + } + + private static String encode(String scheme, Charset charset, HierarchicalUriComponents.Type type) { + return HierarchicalUriComponents.encodeUriComponent(scheme, charset, type); + } + + /** * Decode the given encoded URI component. *

See {@link StringUtils#uriDecode(String, Charset)} for the decoding rules. @@ -311,11 +335,10 @@ public abstract class UriUtils { * @param encoding the character encoding to use * @return the decoded value * @throws IllegalArgumentException when the given source contains invalid encoded sequences - * @throws UnsupportedEncodingException when the given encoding parameter is not supported * @see StringUtils#uriDecode(String, Charset) * @see java.net.URLDecoder#decode(String, String) */ - public static String decode(String source, String encoding) throws UnsupportedEncodingException { + public static String decode(String source, String encoding) { return StringUtils.uriDecode(source, Charset.forName(encoding)); } @@ -360,37 +383,4 @@ public abstract class UriUtils { return null; } - - /** - * Apply {@link #encode(String, String)} to the values in the given URI - * variables and return a new Map containing the encoded values. - * @param uriVariables the URI variable values to be encoded - * @return the encoded String - * @since 5.0 - */ - public static Map encodeUriVariables(Map uriVariables) { - Map result = new LinkedHashMap<>(uriVariables.size()); - uriVariables.forEach((key, value) -> { - String stringValue = (value != null ? value.toString() : ""); - result.put(key, encode(stringValue, StandardCharsets.UTF_8)); - }); - return result; - } - - /** - * Apply {@link #encode(String, String)} to the values in the given URI - * variables and return a new array containing the encoded values. - * @param uriVariables the URI variable values to be encoded - * @return the encoded String - * @since 5.0 - */ - public static Object[] encodeUriVariables(Object... uriVariables) { - return Arrays.stream(uriVariables) - .map(value -> { - String stringValue = (value != null ? value.toString() : ""); - return encode(stringValue, StandardCharsets.UTF_8); - }) - .collect(Collectors.toList()).toArray(); - } - } diff --git a/spring-web/src/main/java/org/springframework/web/util/UrlPathHelper.java b/spring-web/src/main/java/org/springframework/web/util/UrlPathHelper.java index 5e46df7fba..99ec0f1d23 100644 --- a/spring-web/src/main/java/org/springframework/web/util/UrlPathHelper.java +++ b/spring-web/src/main/java/org/springframework/web/util/UrlPathHelper.java @@ -18,6 +18,7 @@ package org.springframework.web.util; import java.io.UnsupportedEncodingException; import java.net.URLDecoder; +import java.nio.charset.UnsupportedCharsetException; import java.util.LinkedHashMap; import java.util.Map; import java.util.Map.Entry; @@ -467,7 +468,7 @@ public class UrlPathHelper { try { return UriUtils.decode(source, enc); } - catch (UnsupportedEncodingException ex) { + catch (UnsupportedCharsetException ex) { if (logger.isWarnEnabled()) { logger.warn("Could not decode request string [" + source + "] with encoding '" + enc + "': falling back to platform default encoding; exception message: " + ex.getMessage());