WebUtils (Apache Shiro 1.13.0 API)

java.lang.Object
- org.apache.shiro.web.util.WebUtils

```
public class WebUtils
extends Object
```
Simple utility class for operations used across multiple class hierarchies in the web framework code.
Some methods in this class were copied from the Spring Framework so we didn't have to re-invent the wheel, and in these cases, we have retained all license, copyright and author information.

Since:

0.9

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`ALLOW_BACKSLASH`
`static String`	`DEFAULT_CHARACTER_ENCODING` Default character encoding to use when `request.getCharacterEncoding` returns `null`, according to the Servlet spec.
`static String`	`FORWARD_CONTEXT_PATH_ATTRIBUTE`
`static String`	`FORWARD_PATH_INFO_ATTRIBUTE`
`static String`	`FORWARD_QUERY_STRING_ATTRIBUTE`
`static String`	`FORWARD_REQUEST_URI_ATTRIBUTE` Standard Servlet 2.4+ spec request attributes for forward URI and paths.
`static String`	`FORWARD_SERVLET_PATH_ATTRIBUTE`
`static String`	`INCLUDE_CONTEXT_PATH_ATTRIBUTE`
`static String`	`INCLUDE_PATH_INFO_ATTRIBUTE`
`static String`	`INCLUDE_QUERY_STRING_ATTRIBUTE`
`static String`	`INCLUDE_REQUEST_URI_ATTRIBUTE` Standard Servlet 2.3+ spec request attributes for include URI and paths.
`static String`	`INCLUDE_SERVLET_PATH_ATTRIBUTE`
`static String`	`SAVED_REQUEST_KEY` `Session` key used to save a request and later restore it, for example when redirecting to a requested page after login, equal to `shiroSavedRequest`.
`static String`	`SERVLET_REQUEST_KEY`
`static String`	`SERVLET_RESPONSE_KEY`

Constructor Summary

Constructors
Constructor and Description

WebUtils()

Constructors
Constructor and Description
`WebUtils()`

Method Summary

All Methods Static Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`static boolean`	`_isSessionCreationEnabled(Object requestPairSource)` Returns `true` if a session is allowed to be created for a subject-associated request, `false` otherwise.
`static boolean`	`_isSessionCreationEnabled(ServletRequest request)` Returns `true` if a session is allowed to be created for a subject-associated request, `false` otherwise.
`static String`	`decodeRequestString(HttpServletRequest request, String source)` Decode the given source string with a URLDecoder.
`protected static String`	`determineEncoding(HttpServletRequest request)` Determine the encoding for the given request.
`static SavedRequest`	`getAndClearSavedRequest(ServletRequest request)`
`static String`	`getCleanParam(ServletRequest request, String paramName)` Convenience method that returns a request parameter value, first running it through `StringUtils.clean(String)`.
`static String`	`getCleanParam(ServletRequest request, String paramName, boolean trim)` Convenience method that returns a request parameter value, first running it through `StringUtils.clean(String)`.
`static String`	`getContextPath(HttpServletRequest request)` Return the context path for the given request, detecting an include request URL if called within a RequestDispatcher include.
`static HttpServletRequest`	`getHttpRequest(Object requestPairSource)`
`static HttpServletResponse`	`getHttpResponse(Object requestPairSource)`
`static String`	`getPathWithinApplication(HttpServletRequest request)` Return the path within the web application for the given request.
`static ServletRequest`	`getRequest(Object requestPairSource)`
`static String`	`getRequestUri(HttpServletRequest request)` Deprecated. use getPathWithinApplication() to get the path minus the context path, or call HttpServletRequest.getRequestURI() directly from your code.
`static WebEnvironment`	`getRequiredWebEnvironment(ServletContext sc)` Find the Shiro `WebEnvironment` for this web application, which is typically loaded via the `EnvironmentLoaderListener`.
`static ServletResponse`	`getResponse(Object requestPairSource)`
`static SavedRequest`	`getSavedRequest(ServletRequest request)`
`static WebEnvironment`	`getWebEnvironment(ServletContext sc)` Find the Shiro `WebEnvironment` for this web application, which is typically loaded via `EnvironmentLoaderListener`.
`static WebEnvironment`	`getWebEnvironment(ServletContext sc, String attrName)` Find the Shiro `WebEnvironment` for this web application.
`static boolean`	`isHttp(Object requestPairSource)`
`static void`	`issueRedirect(ServletRequest request, ServletResponse response, String url)` Redirects the current request to a new URL based on the given parameters and default values for unspecified parameters.
`static void`	`issueRedirect(ServletRequest request, ServletResponse response, String url, Map queryParams)` Redirects the current request to a new URL based on the given parameters and default values for unspecified parameters.
`static void`	`issueRedirect(ServletRequest request, ServletResponse response, String url, Map queryParams, boolean contextRelative)` Redirects the current request to a new URL based on the given parameters and default values for unspecified parameters.
`static void`	`issueRedirect(ServletRequest request, ServletResponse response, String url, Map queryParams, boolean contextRelative, boolean http10Compatible)` Redirects the current request to a new URL based on the given parameters.
`static boolean`	`isTrue(ServletRequest request, String paramName)` Checks to see if a request param is considered true using a loose matching strategy for general values that indicate that something is true or enabled, etc.
`static boolean`	`isWeb(Object requestPairSource)`
`static String`	`normalize(String path)` Normalize a relative URI path that may have relative values ("/./", "/../", and so on ) it it.
`static void`	`redirectToSavedRequest(ServletRequest request, ServletResponse response, String fallbackUrl)` Redirects the to the request url from a previously `saved` request, or if there is no saved request, redirects the end user to the specified `fallbackUrl`.
`static void`	`saveRequest(ServletRequest request)`
`static HttpServletRequest`	`toHttp(ServletRequest request)` A convenience method that merely casts the incoming `ServletRequest` to an `HttpServletRequest`: `return (HttpServletRequest)request;` Logic could be changed in the future for logging or throwing an meaningful exception in non HTTP request environments (e.g.
`static HttpServletResponse`	`toHttp(ServletResponse response)` A convenience method that merely casts the incoming `ServletResponse` to an `HttpServletResponse`: `return (HttpServletResponse)response;` Logic could be changed in the future for logging or throwing an meaningful exception in non HTTP request environments (e.g.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - SERVLET_REQUEST_KEY
```
public static final String SERVLET_REQUEST_KEY
```
  - SERVLET_RESPONSE_KEY
```
public static final String SERVLET_RESPONSE_KEY
```
  - ALLOW_BACKSLASH
```
public static final String ALLOW_BACKSLASH
```
    See Also:
    
    Constant Field Values
  - SAVED_REQUEST_KEY
```
public static final String SAVED_REQUEST_KEY
```
    Session key used to save a request and later restore it, for example when redirecting to a requested page after login, equal to shiroSavedRequest.
    
    See Also:
    
    Constant Field Values
  - INCLUDE_REQUEST_URI_ATTRIBUTE
```
public static final String INCLUDE_REQUEST_URI_ATTRIBUTE
```
    Standard Servlet 2.3+ spec request attributes for include URI and paths.
    If included via a RequestDispatcher, the current resource will see the originating request. Its own URI and paths are exposed as request attributes.
    
    See Also:
    
    Constant Field Values
  - INCLUDE_CONTEXT_PATH_ATTRIBUTE
```
public static final String INCLUDE_CONTEXT_PATH_ATTRIBUTE
```
    See Also:
    
    Constant Field Values
  - INCLUDE_SERVLET_PATH_ATTRIBUTE
```
public static final String INCLUDE_SERVLET_PATH_ATTRIBUTE
```
    See Also:
    
    Constant Field Values
  - INCLUDE_PATH_INFO_ATTRIBUTE
```
public static final String INCLUDE_PATH_INFO_ATTRIBUTE
```
    See Also:
    
    Constant Field Values
  - INCLUDE_QUERY_STRING_ATTRIBUTE
```
public static final String INCLUDE_QUERY_STRING_ATTRIBUTE
```
    See Also:
    
    Constant Field Values
  - FORWARD_REQUEST_URI_ATTRIBUTE
```
public static final String FORWARD_REQUEST_URI_ATTRIBUTE
```
    Standard Servlet 2.4+ spec request attributes for forward URI and paths.
    If forwarded to via a RequestDispatcher, the current resource will see its own URI and paths. The originating URI and paths are exposed as request attributes.
    
    See Also:
    
    Constant Field Values
  - FORWARD_CONTEXT_PATH_ATTRIBUTE
```
public static final String FORWARD_CONTEXT_PATH_ATTRIBUTE
```
    See Also:
    
    Constant Field Values
  - FORWARD_SERVLET_PATH_ATTRIBUTE
```
public static final String FORWARD_SERVLET_PATH_ATTRIBUTE
```
    See Also:
    
    Constant Field Values
  - FORWARD_PATH_INFO_ATTRIBUTE
```
public static final String FORWARD_PATH_INFO_ATTRIBUTE
```
    See Also:
    
    Constant Field Values
  - FORWARD_QUERY_STRING_ATTRIBUTE
```
public static final String FORWARD_QUERY_STRING_ATTRIBUTE
```
    See Also:
    
    Constant Field Values
  - DEFAULT_CHARACTER_ENCODING
```
public static final String DEFAULT_CHARACTER_ENCODING
```
    Default character encoding to use when request.getCharacterEncoding returns null, according to the Servlet spec.
    
    See Also:
    
    ServletRequest.getCharacterEncoding(), Constant Field Values
- Constructor Detail
  - WebUtils
```
public WebUtils()
```
- Method Detail
  - getPathWithinApplication
```
public static 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.
    For example, for a request to URL
    http://www.somehost.com/myapp/my/url.jsp,
    for an application deployed to /mayapp (the application's context path), this method would return
    /my/url.jsp.
    
    Parameters:
    
    request - current HTTP request
    
    Returns:
    
    the path within the web application
  - getRequestUri
```
@Deprecated
public static String getRequestUri(HttpServletRequest request)
```
    Deprecated. use getPathWithinApplication() to get the path minus the context path, or call HttpServletRequest.getRequestURI() directly from your code.
    
    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
  - normalize
```
public static String normalize(String path)
```
    Normalize a relative URI path that may have relative values ("/./", "/../", and so on ) it it. WARNING - This method is useful only for normalizing application-generated paths. It does not try to perform security checks for malicious input. Normalize operations were was happily taken from org.apache.catalina.util.RequestUtil in Tomcat trunk, r939305
    
    Parameters:
    
    path - Relative path to be normalized
    
    Returns:
    
    normalized path
  - getContextPath
```
public static 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
  - getRequiredWebEnvironment
```
public static WebEnvironment getRequiredWebEnvironment(ServletContext sc)
                                                throws IllegalStateException
```
    Find the Shiro WebEnvironment for this web application, which is typically loaded via the EnvironmentLoaderListener.
    This implementation rethrows an exception that happened on environment startup to differentiate between a failed environment startup and no environment at all.
    
    Parameters:
    
    sc - ServletContext to find the web application context for
    
    Returns:
    
    the root WebApplicationContext for this web app
    
    Throws:
    
    IllegalStateException - if the root WebApplicationContext could not be found
    
    Since:
    
    1.2
    
    See Also:
    
    EnvironmentLoader.ENVIRONMENT_ATTRIBUTE_KEY
  - getWebEnvironment
```
public static WebEnvironment getWebEnvironment(ServletContext sc)
```
    Find the Shiro WebEnvironment for this web application, which is typically loaded via EnvironmentLoaderListener.
    This implementation rethrows an exception that happened on environment startup to differentiate between a failed environment startup and no environment at all.
    
    Parameters:
    
    sc - ServletContext to find the web application context for
    
    Returns:
    
    the root WebApplicationContext for this web app, or null if none
    
    Since:
    
    1.2
    
    See Also:
    
    EnvironmentLoader.ENVIRONMENT_ATTRIBUTE_KEY
  - getWebEnvironment
```
public static WebEnvironment getWebEnvironment(ServletContext sc,
                                               String attrName)
```
    Find the Shiro WebEnvironment for this web application.
    
    Parameters:
    
    sc - ServletContext to find the web application context for
    
    attrName - the name of the ServletContext attribute to look for
    
    Returns:
    
    the desired WebEnvironment for this web app, or null if none
    
    Since:
    
    1.2
  - decodeRequestString
```
public static 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:
    
    DEFAULT_CHARACTER_ENCODING, ServletRequest.getCharacterEncoding(), URLDecoder.decode(String, String), URLDecoder.decode(String)
  - determineEncoding
```
protected static String determineEncoding(HttpServletRequest request)
```
    Determine the encoding for the given request. Can be overridden in subclasses.
    The default implementation checks the request's character encoding, and if that null, falls back to the DEFAULT_CHARACTER_ENCODING.
    
    Parameters:
    
    request - current HTTP request
    
    Returns:
    
    the encoding for the request (never null)
    
    See Also:
    
    ServletRequest.getCharacterEncoding()
  - isWeb
```
public static boolean isWeb(Object requestPairSource)
```
  - isHttp
```
public static boolean isHttp(Object requestPairSource)
```
  - getRequest
```
public static ServletRequest getRequest(Object requestPairSource)
```
  - getResponse
```
public static ServletResponse getResponse(Object requestPairSource)
```
  - getHttpRequest
```
public static HttpServletRequest getHttpRequest(Object requestPairSource)
```
  - getHttpResponse
```
public static HttpServletResponse getHttpResponse(Object requestPairSource)
```
  - _isSessionCreationEnabled
```
public static boolean _isSessionCreationEnabled(Object requestPairSource)
```
    Returns true if a session is allowed to be created for a subject-associated request, false otherwise.
    This method exists for Shiro's internal framework needs and should never be called by Shiro end-users. It could be changed/removed at any time.
    
    Parameters:
    
    requestPairSource - a RequestPairSource instance, almost always a WebSubject instance.
    
    Returns:
    
    true if a session is allowed to be created for a subject-associated request, false otherwise.
  - _isSessionCreationEnabled
```
public static boolean _isSessionCreationEnabled(ServletRequest request)
```
    Returns true if a session is allowed to be created for a subject-associated request, false otherwise.
    This method exists for Shiro's internal framework needs and should never be called by Shiro end-users. It could be changed/removed at any time.
    
    Parameters:
    
    request - incoming servlet request.
    
    Returns:
    
    true if a session is allowed to be created for a subject-associated request, false otherwise.
  - toHttp
```
public static HttpServletRequest toHttp(ServletRequest request)
```
    A convenience method that merely casts the incoming ServletRequest to an HttpServletRequest:
    return (HttpServletRequest)request;
    Logic could be changed in the future for logging or throwing an meaningful exception in non HTTP request environments (e.g. Portlet API).
    
    Parameters:
    
    request - the incoming ServletRequest
    
    Returns:
    
    the request argument casted to an HttpServletRequest.
  - toHttp
```
public static HttpServletResponse toHttp(ServletResponse response)
```
    A convenience method that merely casts the incoming ServletResponse to an HttpServletResponse:
    return (HttpServletResponse)response;
    Logic could be changed in the future for logging or throwing an meaningful exception in non HTTP request environments (e.g. Portlet API).
    
    Parameters:
    
    response - the outgoing ServletResponse
    
    Returns:
    
    the response argument casted to an HttpServletResponse.
  - issueRedirect
```
public static void issueRedirect(ServletRequest request,
                                 ServletResponse response,
                                 String url,
                                 Map queryParams,
                                 boolean contextRelative,
                                 boolean http10Compatible)
                          throws IOException
```
    Redirects the current request to a new URL based on the given parameters.
    
    Parameters:
    
    request - the servlet request.
    
    response - the servlet response.
    
    url - the URL to redirect the user to.
    
    queryParams - a map of parameters that should be set as request parameters for the new request.
    
    contextRelative - true if the URL is relative to the servlet context path, or false if the URL is absolute.
    
    http10Compatible - whether to stay compatible with HTTP 1.0 clients.
    
    Throws:
    
    IOException - if thrown by response methods.
  - issueRedirect
```
public static void issueRedirect(ServletRequest request,
                                 ServletResponse response,
                                 String url)
                          throws IOException
```
    Redirects the current request to a new URL based on the given parameters and default values for unspecified parameters.
    
    Parameters:
    
    request - the servlet request.
    
    response - the servlet response.
    
    url - the URL to redirect the user to.
    
    Throws:
    
    IOException - if thrown by response methods.
  - issueRedirect
```
public static void issueRedirect(ServletRequest request,
                                 ServletResponse response,
                                 String url,
                                 Map queryParams)
                          throws IOException
```
    Redirects the current request to a new URL based on the given parameters and default values for unspecified parameters.
    
    Parameters:
    
    request - the servlet request.
    
    response - the servlet response.
    
    url - the URL to redirect the user to.
    
    queryParams - a map of parameters that should be set as request parameters for the new request.
    
    Throws:
    
    IOException - if thrown by response methods.
  - issueRedirect
```
public static void issueRedirect(ServletRequest request,
                                 ServletResponse response,
                                 String url,
                                 Map queryParams,
                                 boolean contextRelative)
                          throws IOException
```
    Redirects the current request to a new URL based on the given parameters and default values for unspecified parameters.
    
    Parameters:
    
    request - the servlet request.
    
    response - the servlet response.
    
    url - the URL to redirect the user to.
    
    queryParams - a map of parameters that should be set as request parameters for the new request.
    
    contextRelative - true if the URL is relative to the servlet context path, or false if the URL is absolute.
    
    Throws:
    
    IOException - if thrown by response methods.
  - isTrue
```
public static boolean isTrue(ServletRequest request,
                             String paramName)
```
    Checks to see if a request param is considered true using a loose matching strategy for general values that indicate that something is true or enabled, etc.
    
    Values that are considered "true" include (case-insensitive): true, t, 1, enabled, y, yes, on.
    
    Parameters:
    
    request - the servlet request
    
    paramName - @return true if the param value is considered true or false if it isn't.
    
    Returns:
    
    true if the given parameter is considered "true" - false otherwise.
  - getCleanParam
```
public static String getCleanParam(ServletRequest request,
                                   String paramName)
```
    Convenience method that returns a request parameter value, first running it through StringUtils.clean(String).
    
    Parameters:
    
    request - the servlet request.
    
    paramName - the parameter name.
    
    Returns:
    
    the clean param value, or null if the param does not exist or is empty.
  - getCleanParam
```
public static String getCleanParam(ServletRequest request,
                                   String paramName,
                                   boolean trim)
```
    Convenience method that returns a request parameter value, first running it through StringUtils.clean(String).
    
    Parameters:
    
    request - the servlet request.
    
    paramName - the parameter name.
    
    trim - specifies whether the parameter value should be trimmed or not
    
    Returns:
    
    the clean param value, or null if the param does not exist or is empty.
  - saveRequest
```
public static void saveRequest(ServletRequest request)
```
  - getAndClearSavedRequest
```
public static SavedRequest getAndClearSavedRequest(ServletRequest request)
```
  - getSavedRequest
```
public static SavedRequest getSavedRequest(ServletRequest request)
```
  - redirectToSavedRequest
```
public static void redirectToSavedRequest(ServletRequest request,
                                          ServletResponse response,
                                          String fallbackUrl)
                                   throws IOException
```
    Redirects the to the request url from a previously saved request, or if there is no saved request, redirects the end user to the specified fallbackUrl. If there is no saved request or fallback url, this method throws an IllegalStateException.
    This method is primarily used to support a common login scenario - if an unauthenticated user accesses a page that requires authentication, it is expected that request is saved first and then redirected to the login page. Then, after a successful login, this method can be called to redirect them back to their originally requested URL, a nice usability feature.
    
    Parameters:
    
    request - the incoming request
    
    response - the outgoing response
    
    fallbackUrl - the fallback url to redirect to if there is no saved request available.
    
    Throws:
    
    IllegalStateException - if there is no saved request and the fallbackUrl is null.
    
    IOException - if there is an error redirecting
    
    Since:
    
    1.0

Class WebUtils

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SERVLET_REQUEST_KEY

SERVLET_RESPONSE_KEY

ALLOW_BACKSLASH

SAVED_REQUEST_KEY

INCLUDE_REQUEST_URI_ATTRIBUTE

INCLUDE_CONTEXT_PATH_ATTRIBUTE

INCLUDE_SERVLET_PATH_ATTRIBUTE

INCLUDE_PATH_INFO_ATTRIBUTE

INCLUDE_QUERY_STRING_ATTRIBUTE

FORWARD_REQUEST_URI_ATTRIBUTE

FORWARD_CONTEXT_PATH_ATTRIBUTE

FORWARD_SERVLET_PATH_ATTRIBUTE

FORWARD_PATH_INFO_ATTRIBUTE

FORWARD_QUERY_STRING_ATTRIBUTE

DEFAULT_CHARACTER_ENCODING

Constructor Detail

WebUtils

Method Detail

getPathWithinApplication

getRequestUri

normalize

getContextPath

getRequiredWebEnvironment

getWebEnvironment

getWebEnvironment

decodeRequestString

determineEncoding

isWeb

isHttp

getRequest

getResponse

getHttpRequest

getHttpResponse

_isSessionCreationEnabled

_isSessionCreationEnabled

toHttp

toHttp

issueRedirect

issueRedirect

issueRedirect

issueRedirect

isTrue

getCleanParam

getCleanParam

saveRequest

getAndClearSavedRequest

getSavedRequest

redirectToSavedRequest