org.springframework.web.util

## Class UrlPathHelper

- java.lang.Object
- - org.springframework.web.util.UrlPathHelper

-     public class UrlPathHelper
      extends Object

  Helper class for URL path matching. Provides support for URL paths in `RequestDispatcher` includes and support for consistent URL decoding.

  Used by `AbstractUrlHandlerMapping` and `RequestContext` for path matching and/or URI determination.

  Since:
    14.01.2004
  Author:
    Juergen Hoeller, Rob Harrop, Rossen Stoyanchev
  See Also:
    `getLookupPathForRequest(javax.servlet.http.HttpServletRequest, java.lang.String)`, `RequestDispatcher`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static UrlPathHelper` | `defaultInstance` Shared, read-only instance with defaults.
    `static String` | `PATH_ATTRIBUTE` Name of Servlet request attribute that holds a `resolved` lookupPath.
    `static UrlPathHelper` | `rawPathInstance` Shared, read-only instance for the full, encoded path.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `UrlPathHelper()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `MultiValueMap<String,String>` | `decodeMatrixVariables(HttpServletRequest request, MultiValueMap<String,String> vars)` Decode the given matrix variables via `decodeRequestString(javax.servlet.http.HttpServletRequest, java.lang.String)` unless `setUrlDecode(boolean)` is set to `true` in which case it is assumed the URL path from which the variables were extracted is already decoded through a call to `getLookupPathForRequest(HttpServletRequest)`.
    `Map<String,String>` | `decodePathVariables(HttpServletRequest request, Map<String,String> vars)` Decode the given URI path variables via `decodeRequestString(javax.servlet.http.HttpServletRequest, java.lang.String)` unless `setUrlDecode(boolean)` is set to `true` in which case it is assumed the URL path from which the variables were extracted is already decoded through a call to `getLookupPathForRequest(HttpServletRequest)`.
    `String` | `decodeRequestString(HttpServletRequest request, String source)` Decode the given source string with a URLDecoder.
    `protected String` | `determineEncoding(HttpServletRequest request)` Determine the encoding for the given request.
    `String` | `getContextPath(HttpServletRequest request)` Return the context path for the given request, detecting an include request URL if called within a RequestDispatcher include.
    `protected String` | `getDefaultEncoding()` Return the default character encoding to use for URL decoding.
    `String` | `getLookupPathForRequest(HttpServletRequest request)` Return the mapping lookup path for the given request, within the current servlet mapping if applicable, else within the web application.
    `String` | `getLookupPathForRequest(HttpServletRequest request, String name)` Deprecated. as of 5.3 in favor of using `resolveAndCacheLookupPath(HttpServletRequest)` and `getResolvedLookupPath(ServletRequest)`.
    `String` | `getOriginatingContextPath(HttpServletRequest request)` Return the context path for the given request, detecting an include request URL if called within a RequestDispatcher include.
    `String` | `getOriginatingQueryString(HttpServletRequest request)` Return the query string part of the given request's URL.
    `String` | `getOriginatingRequestUri(HttpServletRequest request)` Return the request URI for the given request.
    `String` | `getOriginatingServletPath(HttpServletRequest request)` Return the servlet path for the given request, detecting an include request URL if called within a RequestDispatcher include.
    `String` | `getPathWithinApplication(HttpServletRequest request)` Return the path within the web application for the given request.
    `String` | `getPathWithinServletMapping(HttpServletRequest request)` Return the path within the servlet mapping for the given request, i.e.
    `protected String` | `getPathWithinServletMapping(HttpServletRequest request, String pathWithinApp)` Return the path within the servlet mapping for the given request, i.e.
    `String` | `getRequestUri(HttpServletRequest request)` Return the request URI for the given request, detecting an include request URL if called within a RequestDispatcher include.
    `static String` | `getResolvedLookupPath(ServletRequest request)` Return a previously `resolved` lookupPath.
    `String` | `getServletPath(HttpServletRequest request)` Return the servlet path for the given request, regarding an include request URL if called within a RequestDispatcher include.
    `boolean` | `isUrlDecode()` Whether to decode the request URI when determining the lookup path.
    `String` | `removeSemicolonContent(String requestUri)` Remove ";" (semicolon) content from the given request URI if the removeSemicolonContent property is set to "true".
    `String` | `resolveAndCacheLookupPath(HttpServletRequest request)` `Resolve` the lookupPath and cache it in a request attribute with the key `PATH_ATTRIBUTE` for subsequent access via `getResolvedLookupPath(ServletRequest)`.
    `void` | `setAlwaysUseFullPath(boolean alwaysUseFullPath)` Whether URL lookups should always use the full path within the current web application context, i.e.
    `void` | `setDefaultEncoding(String defaultEncoding)` Set the default character encoding to use for URL decoding.
    `void` | `setRemoveSemicolonContent(boolean removeSemicolonContent)` Set if ";" (semicolon) content should be stripped from the request URI.
    `void` | `setUrlDecode(boolean urlDecode)` 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.
    `boolean` | `shouldRemoveSemicolonContent()` Whether configured to remove ";" (semicolon) content from the request URI.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### PATH_ATTRIBUTE

          public static final String PATH_ATTRIBUTE

      Name of Servlet request attribute that holds a `resolved` lookupPath.
      Since:
        5.3

    - #### defaultInstance

          public static final UrlPathHelper defaultInstance

      Shared, read-only instance with defaults. The following apply:
      - `alwaysUseFullPath=false`
      - `urlDecode=true`
      - `removeSemicolon=true`
      - `defaultEncoding=``WebUtils.DEFAULT_CHARACTER_ENCODING`

    - #### rawPathInstance

          public static final UrlPathHelper rawPathInstance

      Shared, read-only instance for the full, encoded path. The following apply:
      - `alwaysUseFullPath=true`
      - `urlDecode=false`
      - `removeSemicolon=false`
      - `defaultEncoding=``WebUtils.DEFAULT_CHARACTER_ENCODING`

  - ### Constructor Detail

    - #### UrlPathHelper

          public UrlPathHelper()

  - ### Method Detail

    - #### setAlwaysUseFullPath

          public void setAlwaysUseFullPath(boolean alwaysUseFullPath)

      Whether URL lookups should always use the full path within the current web application context, i.e. within `ServletContext.getContextPath()`.

      If set to 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".

    - #### setUrlDecode

          public void setUrlDecode(boolean urlDecode)

      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 true.

      Note: Be aware the servlet path will not match when compared to encoded paths. Therefore use of `urlDecode=false` is not compatible with a prefix-based Servlet mapping and likewise implies also setting `alwaysUseFullPath=true`.

      See Also:
        `getServletPath(javax.servlet.http.HttpServletRequest)`, `getContextPath(javax.servlet.http.HttpServletRequest)`, `getRequestUri(javax.servlet.http.HttpServletRequest)`, `WebUtils.DEFAULT_CHARACTER_ENCODING`, `ServletRequest.getCharacterEncoding()`, `URLDecoder.decode(String, String)`

    - #### isUrlDecode

          public boolean isUrlDecode()

      Whether to decode the request URI when determining the lookup path.
      Since:
        4.3.13

    - #### setRemoveSemicolonContent

          public void setRemoveSemicolonContent(boolean removeSemicolonContent)

      Set if ";" (semicolon) content should be stripped from the request URI.

      Default is "true".

    - #### shouldRemoveSemicolonContent

          public boolean shouldRemoveSemicolonContent()

      Whether configured to remove ";" (semicolon) content from the request URI.

    - #### setDefaultEncoding

          public void setDefaultEncoding(String defaultEncoding)

      Set the default character encoding to use for URL decoding. Default is ISO-8859-1, according to the Servlet spec.

      If the request specifies a character encoding itself, the request encoding will override this setting. This also allows for generically overriding the character encoding in a filter that invokes the `ServletRequest.setCharacterEncoding` method.

      Parameters:
        `defaultEncoding` - the character encoding to use
      See Also:
        `determineEncoding(javax.servlet.http.HttpServletRequest)`, `ServletRequest.getCharacterEncoding()`, `ServletRequest.setCharacterEncoding(String)`, `WebUtils.DEFAULT_CHARACTER_ENCODING`

    - #### getDefaultEncoding

          protected String getDefaultEncoding()

      Return the default character encoding to use for URL decoding.

    - #### resolveAndCacheLookupPath

          public String resolveAndCacheLookupPath(HttpServletRequest request)

      `Resolve` the lookupPath and cache it in a request attribute with the key `PATH_ATTRIBUTE` for subsequent access via `getResolvedLookupPath(ServletRequest)`.
      Parameters:
        `request` - the current request
      Returns:
        the resolved path
      Since:
        5.3

    - #### getResolvedLookupPath

          public static String getResolvedLookupPath(ServletRequest request)

      Return a previously `resolved` lookupPath.
      Parameters:
        `request` - the current request
      Returns:
        the previously resolved lookupPath
      Throws:
        `IllegalArgumentException` - if the lookup path is not found
      Since:
        5.3

    - #### getLookupPathForRequest

          @Deprecated
          public String getLookupPathForRequest(HttpServletRequest request,
                                                            @Nullable
                                                            String name)

      Deprecated. as of 5.3 in favor of using `resolveAndCacheLookupPath(HttpServletRequest)` and `getResolvedLookupPath(ServletRequest)`.
      Variant of `getLookupPathForRequest(HttpServletRequest)` that automates checking for a previously computed lookupPath saved as a request attribute. The attribute is only used for lookup purposes.
      Parameters:
        `request` - current HTTP request
        `name` - the request attribute that holds the lookupPath
      Returns:
        the lookup path
      Since:
        5.2

    - #### getLookupPathForRequest

          public String getLookupPathForRequest(HttpServletRequest request)

      Return the mapping lookup path for the given request, within the current servlet mapping if applicable, else within the web application.

      Detects include request URL if called within a RequestDispatcher include.

      Parameters:
        `request` - current HTTP request
      Returns:
        the lookup path
      See Also:
        `getPathWithinServletMapping(javax.servlet.http.HttpServletRequest)`, `getPathWithinApplication(javax.servlet.http.HttpServletRequest)`

    - #### getPathWithinServletMapping

          public String getPathWithinServletMapping(HttpServletRequest request)

      Return the path within the servlet mapping for the given request, i.e. the part of the request's URL beyond the part that called the servlet, or "" if the whole URL has been used to identify the servlet.
      Parameters:
        `request` - current HTTP request
      Returns:
        the path within the servlet mapping, or ""
      See Also:
        `getPathWithinServletMapping(HttpServletRequest, String)`

    - #### getPathWithinServletMapping

          protected String getPathWithinServletMapping(HttpServletRequest request,
                                                       String pathWithinApp)

      Return the path within the servlet mapping for the given request, i.e. the part of the request's URL beyond the part that called the servlet, or "" if the whole URL has been used to identify the servlet.

      Detects include request URL if called within a RequestDispatcher include.

      E.g.: servlet mapping = "/*"; request URI = "/test/a" → "/test/a".

      E.g.: servlet mapping = "/"; request URI = "/test/a" → "/test/a".

      E.g.: servlet mapping = "/test/*"; request URI = "/test/a" → "/a".

      E.g.: servlet mapping = "/test"; request URI = "/test" → "".

      E.g.: servlet mapping = "/*.test"; request URI = "/a.test" → "".

      Parameters:
        `request` - current HTTP request
        `pathWithinApp` - a precomputed path within the application
      Returns:
        the path within the servlet mapping, or ""
      Since:
        5.2.9
      See Also:
        `getLookupPathForRequest(javax.servlet.http.HttpServletRequest, java.lang.String)`

    - #### getPathWithinApplication

          public String getPathWithinApplication(HttpServletRequest request)

      Return the path within the web application for the given request.

      Detects include request URL if called within a RequestDispatcher include.

      Parameters:
        `request` - current HTTP request
      Returns:
        the path within the web application
      See Also:
        `getLookupPathForRequest(javax.servlet.http.HttpServletRequest, java.lang.String)`

    - #### getRequestUri

          public String getRequestUri(HttpServletRequest request)

      Return the request URI for the given request, detecting an include request URL if called within a RequestDispatcher include.

      As the value returned by `request.getRequestURI()` is not decoded by the servlet container, this method will decode it.

      The URI that the web container resolves should be correct, but some containers like JBoss/Jetty incorrectly include ";" strings like ";jsessionid" in the URI. This method cuts off such incorrect appendices.

      Parameters:
        `request` - current HTTP request
      Returns:
        the request URI

    - #### getContextPath

          public String getContextPath(HttpServletRequest request)

      Return the context path for the given request, detecting an include request URL if called within a RequestDispatcher include.

      As the value returned by `request.getContextPath()` is not decoded by the servlet container, this method will decode it.

      Parameters:
        `request` - current HTTP request
      Returns:
        the context path

    - #### getServletPath

          public String getServletPath(HttpServletRequest request)

      Return the servlet path for the given request, regarding an include request URL if called within a RequestDispatcher include.

      As the value returned by `request.getServletPath()` is already decoded by the servlet container, this method will not attempt to decode it.

      Parameters:
        `request` - current HTTP request
      Returns:
        the servlet path

    - #### getOriginatingRequestUri

          public String getOriginatingRequestUri(HttpServletRequest request)

      Return the request URI for the given request. If this is a forwarded request, correctly resolves to the request URI of the original request.

    - #### getOriginatingContextPath

          public String getOriginatingContextPath(HttpServletRequest request)

      Return the context path for the given request, detecting an include request URL if called within a RequestDispatcher include.

      As the value returned by `request.getContextPath()` is not decoded by the servlet container, this method will decode it.

      Parameters:
        `request` - current HTTP request
      Returns:
        the context path

    - #### getOriginatingServletPath

          public String getOriginatingServletPath(HttpServletRequest request)

      Return the servlet path for the given request, detecting an include request URL if called within a RequestDispatcher include.
      Parameters:
        `request` - current HTTP request
      Returns:
        the servlet path

    - #### getOriginatingQueryString

          public String getOriginatingQueryString(HttpServletRequest request)

      Return the query string part of the given request's URL. If this is a forwarded request, correctly resolves to the query string of the original request.
      Parameters:
        `request` - current HTTP request
      Returns:
        the query string

    - #### decodeRequestString

          public String decodeRequestString(HttpServletRequest request,
                                            String source)

      Decode the given source string with a URLDecoder. The encoding will be taken from the request, falling back to the default "ISO-8859-1".

      The default implementation uses `URLDecoder.decode(input, enc)`.

      Parameters:
        `request` - current HTTP request
        `source` - the String to decode
      Returns:
        the decoded String
      See Also:
        `WebUtils.DEFAULT_CHARACTER_ENCODING`, `ServletRequest.getCharacterEncoding()`, `URLDecoder.decode(String, String)`, `URLDecoder.decode(String)`

    - #### determineEncoding

          protected String determineEncoding(HttpServletRequest request)

      Determine the encoding for the given request. Can be overridden in subclasses.

      The default implementation checks the request encoding, falling back to the default encoding specified for this resolver.

      Parameters:
        `request` - current HTTP request
      Returns:
        the encoding for the request (never `null`)
      See Also:
        `ServletRequest.getCharacterEncoding()`, `setDefaultEncoding(java.lang.String)`

    - #### removeSemicolonContent

          public String removeSemicolonContent(String requestUri)

      Remove ";" (semicolon) content from the given request URI if the removeSemicolonContent property is set to "true". Note that "jsessionid" is always removed.
      Parameters:
        `requestUri` - the request URI string to remove ";" content from
      Returns:
        the updated URI string

    - #### decodePathVariables

          public Map<String,String> decodePathVariables(HttpServletRequest request,
                                                        Map<String,String> vars)

      Decode the given URI path variables via `decodeRequestString(javax.servlet.http.HttpServletRequest, java.lang.String)` unless `setUrlDecode(boolean)` is set to `true` in which case it is assumed the URL path from which the variables were extracted is already decoded through a call to `getLookupPathForRequest(HttpServletRequest)`.
      Parameters:
        `request` - current HTTP request
        `vars` - the URI variables extracted from the URL path
      Returns:
        the same Map or a new Map instance

    - #### decodeMatrixVariables

          public MultiValueMap<String,String> decodeMatrixVariables(HttpServletRequest request,
                                                                    MultiValueMap<String,String> vars)

      Decode the given matrix variables via `decodeRequestString(javax.servlet.http.HttpServletRequest, java.lang.String)` unless `setUrlDecode(boolean)` is set to `true` in which case it is assumed the URL path from which the variables were extracted is already decoded through a call to `getLookupPathForRequest(HttpServletRequest)`.
      Parameters:
        `request` - current HTTP request
        `vars` - the URI variables extracted from the URL path
      Returns:
        the same Map or a new Map instance