org.jsecurity.web
Class WebUtils

java.lang.Object
  org.jsecurity.web.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

Author:

Les Hazlewood, Jeremy Haile, Rod Johnson, Juergen Hoeller

Field Summary

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 jsecuritySavedRequest.
static String	SERVLET_REQUEST_KEY
static String	SERVLET_RESPONSE_KEY

Constructor Summary

WebUtils()

Method Summary

static void	bind(ServletRequest servletRequest) Convenience method that simplifies binding a ServletRequest to the current thread (via the ThreadContext).
static void	bind(ServletResponse servletResponse) Convenience method that simplifies binding a ServletResponse to the thread via the ThreadContext.
static void	bindInetAddressToThread(ServletRequest request)
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	getContextPath(HttpServletRequest request) Return the context path for the given request, detecting an include request URL if called within a RequestDispatcher include.
static InetAddress	getInetAddress(ServletRequest request) Returns the InetAddress associated with the current request, or null if the address cannot be resolved/determined.
static String	getPathWithinApplication(HttpServletRequest request) Return the path within the web application for the given request.
static String	getRequestUri(HttpServletRequest request) Return the request URI for the given request, detecting an include request URL if called within a RequestDispatcher include.
static ServletRequest	getRequiredServletRequest() Convenience method that simplifies retrieval of a required thread-bound ServletRequest.
static ServletResponse	getRequiredServletResponse() Convenience method that simplifies retrieval of a required thread-bound ServletResponse.
static SavedRequest	getSavedRequest(ServletRequest request)
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 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.
static void	unbindInetAddressFromThread()
static ServletRequest	unbindServletRequest() Convenience method that simplifies removal of a thread-local ServletRequest from the thread.
static ServletResponse	unbindServletResponse() Convenience method that simplifies removal of a thread-local ServletResponse from the thread.

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

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

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

public static 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 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

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

getInetAddress

public static InetAddress getInetAddress(ServletRequest request)

Returns the InetAddress associated with the current request, or null if the address cannot be resolved/determined.

This implementation returns the InetAddress resolved from the request's remoteHost value. The returned String is resolved to an InetAddress by calling InetAddress.getByName(remoteHost). If the remote host is null or getByName(remoteHost) throws an exception, null is returned.

Parameters:

request - the incoming ServletRequest

Returns:

the InetAddress associated with the current request, or null if the address cannot be resolved/determined.

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.

bindInetAddressToThread

public static void bindInetAddressToThread(ServletRequest request)

unbindInetAddressFromThread

public static void unbindInetAddressFromThread()

getRequiredServletRequest

public static ServletRequest getRequiredServletRequest()
                                                throws IllegalStateException

Convenience method that simplifies retrieval of a required thread-bound ServletRequest. If there is no ServletRequest bound to the thread when this method is called, an IllegalStateException is thrown.

This method is basically a convenient wrapper for the following:

(ServletRequest)ThreadContext.get( SERVLET_REQUEST_KEY );

But throws an IllegalStateException if the value is not bound to the ThreadContext.

This method only returns the bound value if it exists - it does not remove it from the thread. To remove it, one must call unbindServletRequest instead.

Returns:

the ServletRequest bound to the thread. Never returns null.

Throws:

IllegalStateException - if no servlet request is bound in the ThreadContext.

bind

public static void bind(ServletRequest servletRequest)

Convenience method that simplifies binding a ServletRequest to the current thread (via the ThreadContext).

The method's existence is to help reduce casting in your own code and to simplify remembering of ThreadContext key names. The implementation is simple in that, if the servletRequest is not null, it binds it to the thread, i.e.:

 if (servletRequest != null) {
     ThreadContext.put( SERVLET_REQUEST_KEY, servletRequest );
 }

Parameters:

servletRequest - the ServletRequest object to bind to the thread. If the argument is null, nothing will be done.

unbindServletRequest

public static ServletRequest unbindServletRequest()

Convenience method that simplifies removal of a thread-local ServletRequest from the thread.

The implementation just helps reduce casting and remembering of the ThreadContext key name, i.e it is merely a conveient wrapper for the following:

return (ServletRequest)ThreadContext.remove( SERVLET_REQUEST_KEY );

If you wish to just retrieve the object from the thread without removing it (so it can be retrieved later during thread execution), you should use the getRequiredServletRequest() method for that purpose.

Returns:

the Session object previously bound to the thread, or null if there was none bound.

getRequiredServletResponse

public static ServletResponse getRequiredServletResponse()
                                                  throws IllegalStateException

Convenience method that simplifies retrieval of a required thread-bound ServletResponse. If there is no ServletResponse bound to the thread when this method is called, an IllegalStateException is thrown.

This method is basically a convenient wrapper for the following:

return (ServletResponse)ThreadContext.get( SERVLET_RESPONSE_KEY );

But throws an IllegalStateException if the value is not bound to the ThreadContext.

This method only returns the bound value if it exists - it does not remove it from the thread. To remove it, one must call unbindServletResponse instead.

Returns:

the ServletResponse bound to the thread. Never returns null.

Throws:

IllegalStateException - if no ServletResponse> is bound in the ThreadContext

bind

public static void bind(ServletResponse servletResponse)

Convenience method that simplifies binding a ServletResponse to the thread via the ThreadContext.

The method's existence is to help reduce casting in your own code and to simplify remembering of ThreadContext key names. The implementation is simple in that, if the servletResponse is not null, it binds it to the thread, i.e.:

 if (servletResponse != null) {
     ThreadContext.put( SERVLET_RESPONSE_KEY, servletResponse );
 }

Parameters:

servletResponse - the ServletResponse object to bind to the thread. If the argument is null, nothing will be done.

unbindServletResponse

public static ServletResponse unbindServletResponse()

Convenience method that simplifies removal of a thread-local ServletResponse from the thread.

The implementation just helps reduce casting and remembering of the ThreadContext key name, i.e it is merely a conveient wrapper for the following:

return (ServletResponse)ThreadContext.remove( SERVLET_RESPONSE_KEY );

If you wish to just retrieve the object from the thread without removing it (so it can be retrieved later during thread execution), you should use the getRequiredServletResponse() method for that purpose.

Returns:

the Session object previously bound to the thread, or null if there was none bound.

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.

saveRequest

public static void saveRequest(ServletRequest request)

getAndClearSavedRequest

public static SavedRequest getAndClearSavedRequest(ServletRequest request)

getSavedRequest

public static SavedRequest getSavedRequest(ServletRequest request)