From e37af83459b79096f614add2df26a14a5e3aa571 Mon Sep 17 00:00:00 2001 From: Rossen Stoyanchev Date: Fri, 14 Jul 2017 16:51:12 +0200 Subject: [PATCH] Improve docs on on use of urlDecode=false Issue: SPR-15643 --- .../cors/UrlBasedCorsConfigurationSource.java | 13 +++------ .../web/util/UrlPathHelper.java | 27 ++++++++++++------- .../handler/AbstractHandlerMapping.java | 17 ++++-------- .../servlet/mvc/WebContentInterceptor.java | 11 ++------ .../DefaultRequestToViewNameTranslator.java | 11 ++------ src/docs/asciidoc/web/web-mvc.adoc | 3 ++- 6 files changed, 31 insertions(+), 51 deletions(-) diff --git a/spring-web/src/main/java/org/springframework/web/cors/UrlBasedCorsConfigurationSource.java b/spring-web/src/main/java/org/springframework/web/cors/UrlBasedCorsConfigurationSource.java index 6aedd0c829e..50ca5b1d3f7 100644 --- a/spring-web/src/main/java/org/springframework/web/cors/UrlBasedCorsConfigurationSource.java +++ b/spring-web/src/main/java/org/springframework/web/cors/UrlBasedCorsConfigurationSource.java @@ -57,10 +57,7 @@ public class UrlBasedCorsConfigurationSource implements CorsConfigurationSource } /** - * Set if URL lookup should always use the full path within the current servlet - * context. Else, the path within the current servlet mapping is used if applicable - * (that is, in the case of a ".../*" servlet mapping in web.xml). - *

Default is "false". + * Shortcut to same property on underlying {@link #setUrlPathHelper UrlPathHelper}. * @see org.springframework.web.util.UrlPathHelper#setAlwaysUseFullPath */ public void setAlwaysUseFullPath(boolean alwaysUseFullPath) { @@ -68,10 +65,7 @@ public class UrlBasedCorsConfigurationSource implements CorsConfigurationSource } /** - * Set if context path and request URI should be URL-decoded. Both are returned - * undecoded by the Servlet API, in contrast to the servlet path. - *

Uses either the request encoding or the default encoding according - * to the Servlet spec (ISO-8859-1). + * Shortcut to same property on underlying {@link #setUrlPathHelper UrlPathHelper}. * @see org.springframework.web.util.UrlPathHelper#setUrlDecode */ public void setUrlDecode(boolean urlDecode) { @@ -79,8 +73,7 @@ public class UrlBasedCorsConfigurationSource implements CorsConfigurationSource } /** - * Set if ";" (semicolon) content should be stripped from the request URI. - *

The default value is {@code true}. + * Shortcut to same property on underlying {@link #setUrlPathHelper UrlPathHelper}. * @see org.springframework.web.util.UrlPathHelper#setRemoveSemicolonContent(boolean) */ public void setRemoveSemicolonContent(boolean removeSemicolonContent) { 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 291f318ad11..6a89d8557af 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 @@ -22,6 +22,7 @@ import java.util.LinkedHashMap; import java.util.Map; import java.util.Map.Entry; import java.util.Properties; +import javax.servlet.ServletContext; import javax.servlet.http.HttpServletRequest; import org.apache.commons.logging.Log; @@ -70,22 +71,28 @@ public class UrlPathHelper { /** - * Set if URL lookup should always use full path within current servlet - * context. Else, the path within the current servlet mapping is used - * if applicable (i.e. in the case of a ".../*" servlet mapping in web.xml). - * Default is "false". + * Whether URL lookups should always use the full path within current + * application context, i.e. within {@link ServletContext#getContextPath()}. + *

If set to {@literal false} the path within the current servlet mapping + * is used instead if applicable (i.e. in the case of a prefix based Servlet + * mapping such as "/myServlet/*"). + *

By default this is set to "false". */ public void setAlwaysUseFullPath(boolean alwaysUseFullPath) { this.alwaysUseFullPath = alwaysUseFullPath; } /** - * Set if context path and request URI should be URL-decoded. - * Both are returned undecoded by the Servlet API, - * in contrast to the servlet path. - *

Uses either the request encoding or the default encoding according - * to the Servlet spec (ISO-8859-1). - *

Default is "true", as of Spring 2.5. + * Whether the context path and request URI should be decoded -- both of + * which are returned undecoded by the Servlet API, in contrast to + * the servlet path. + *

Either the request encoding or the default Servlet spec encoding + * (ISO-8859-1) is used when set to "true". + *

By default this is set to {@literal true}. + *

Note: Be aware the servlet path will not match when + * compared to encoded paths. Therefore use of {@code urlDecode=false} is + * not compatible with a prefix-based Servlet mappping and likewise implies + * also setting {@code alwaysUseFullPath=true}. * @see #getServletPath * @see #getContextPath * @see #getRequestUri diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/handler/AbstractHandlerMapping.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/handler/AbstractHandlerMapping.java index 39f590ec4fb..93a6fd904da 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/handler/AbstractHandlerMapping.java +++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/handler/AbstractHandlerMapping.java @@ -118,11 +118,8 @@ public abstract class AbstractHandlerMapping extends WebApplicationObjectSupport } /** - * Set if URL lookup should always use the full path within the current servlet - * context. Else, the path within the current servlet mapping is used if applicable - * (that is, in the case of a ".../*" servlet mapping in web.xml). - *

Default is "false". - * @see org.springframework.web.util.UrlPathHelper#setAlwaysUseFullPath + * Shortcut to same property on underlying {@link #setUrlPathHelper UrlPathHelper}. + * @see org.springframework.web.util.UrlPathHelper#setAlwaysUseFullPath(boolean) */ public void setAlwaysUseFullPath(boolean alwaysUseFullPath) { this.urlPathHelper.setAlwaysUseFullPath(alwaysUseFullPath); @@ -130,11 +127,8 @@ public abstract class AbstractHandlerMapping extends WebApplicationObjectSupport } /** - * Set if context path and request URI should be URL-decoded. Both are returned - * undecoded by the Servlet API, in contrast to the servlet path. - *

Uses either the request encoding or the default encoding according - * to the Servlet spec (ISO-8859-1). - * @see org.springframework.web.util.UrlPathHelper#setUrlDecode + * Shortcut to same property on underlying {@link #setUrlPathHelper UrlPathHelper}. + * @see org.springframework.web.util.UrlPathHelper#setUrlDecode(boolean) */ public void setUrlDecode(boolean urlDecode) { this.urlPathHelper.setUrlDecode(urlDecode); @@ -142,8 +136,7 @@ public abstract class AbstractHandlerMapping extends WebApplicationObjectSupport } /** - * Set if ";" (semicolon) content should be stripped from the request URI. - *

The default value is {@code true}. + * Shortcut to same property on underlying {@link #setUrlPathHelper UrlPathHelper}. * @see org.springframework.web.util.UrlPathHelper#setRemoveSemicolonContent(boolean) */ public void setRemoveSemicolonContent(boolean removeSemicolonContent) { diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/WebContentInterceptor.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/WebContentInterceptor.java index 0fc4fb62b48..659b4fe5cf3 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/WebContentInterceptor.java +++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/WebContentInterceptor.java @@ -69,10 +69,7 @@ public class WebContentInterceptor extends WebContentGenerator implements Handle /** - * Set if URL lookup should always use full path within current servlet - * context. Else, the path within the current servlet mapping is used - * if applicable (i.e. in the case of a ".../*" servlet mapping in web.xml). - * Default is "false". + * Shortcut to same property on underlying {@link #setUrlPathHelper UrlPathHelper}. *

Only relevant for the "cacheMappings" setting. * @see #setCacheMappings * @see org.springframework.web.util.UrlPathHelper#setAlwaysUseFullPath @@ -82,11 +79,7 @@ public class WebContentInterceptor extends WebContentGenerator implements Handle } /** - * Set if context path and request URI should be URL-decoded. - * Both are returned undecoded by the Servlet API, - * in contrast to the servlet path. - *

Uses either the request encoding or the default encoding according - * to the Servlet spec (ISO-8859-1). + * Shortcut to same property on underlying {@link #setUrlPathHelper UrlPathHelper}. *

Only relevant for the "cacheMappings" setting. * @see #setCacheMappings * @see org.springframework.web.util.UrlPathHelper#setUrlDecode diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/view/DefaultRequestToViewNameTranslator.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/view/DefaultRequestToViewNameTranslator.java index d4d79ec6a3b..7b7f850382c 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/view/DefaultRequestToViewNameTranslator.java +++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/view/DefaultRequestToViewNameTranslator.java @@ -124,10 +124,7 @@ public class DefaultRequestToViewNameTranslator implements RequestToViewNameTran } /** - * Set if URL lookup should always use the full path within the current servlet - * context. Else, the path within the current servlet mapping is used - * if applicable (i.e. in the case of a ".../*" servlet mapping in web.xml). - * Default is "false". + * Shortcut to same property on underlying {@link #setUrlPathHelper UrlPathHelper}. * @see org.springframework.web.util.UrlPathHelper#setAlwaysUseFullPath */ public void setAlwaysUseFullPath(boolean alwaysUseFullPath) { @@ -135,11 +132,7 @@ public class DefaultRequestToViewNameTranslator implements RequestToViewNameTran } /** - * Set if the context path and request URI should be URL-decoded. - * Both are returned undecoded by the Servlet API, - * in contrast to the servlet path. - *

Uses either the request encoding or the default encoding according - * to the Servlet spec (ISO-8859-1). + * Shortcut to same property on underlying {@link #setUrlPathHelper UrlPathHelper}. * @see org.springframework.web.util.UrlPathHelper#setUrlDecode */ public void setUrlDecode(boolean urlDecode) { diff --git a/src/docs/asciidoc/web/web-mvc.adoc b/src/docs/asciidoc/web/web-mvc.adoc index 5906d1446d6..5f88ba952ed 100644 --- a/src/docs/asciidoc/web/web-mvc.adoc +++ b/src/docs/asciidoc/web/web-mvc.adoc @@ -2690,7 +2690,8 @@ properties that you can use to customize their behavior: * `urlDecode` Defaults to `true`, as of Spring 2.5. If you prefer to compare encoded paths, set this flag to `false`. However, the `HttpServletRequest` always exposes the Servlet path in decoded form. Be aware that the Servlet path will not match when - compared with encoded paths. + compared with encoded paths so you cannot use `urlDecode=false` with prefix-based Servlet + mappings and likewise must also set `alwaysUseFullPath=true`. The following example shows how to configure an interceptor: