org.omnifaces.util

Class Servlets

java.lang.Object

org.omnifaces.util.Servlets

public final class Servlets
extends Object

Collection of utility methods for the Servlet API in general. Most of them are internally used by Faces and FacesLocal, however they may also be useful in a "plain vanilla" servlet or servlet filter.

There are as of now also four special methods related to JSF without needing a FacesContext:

• The isFacesAjaxRequest(HttpServletRequest) which is capable of checking if the current request is a JSF ajax request.
• The isFacesResourceRequest(HttpServletRequest) which is capable of checking if the current request is a JSF resource request.
• The facesRedirect(HttpServletRequest, HttpServletResponse, String, String...) which is capable of distinguishing JSF ajax requests from regular requests and altering the redirect logic on it, exactly like as ExternalContext.redirect(String) does. In other words, this method behaves exactly the same as Faces.redirect(String, String...).
• The isFacesDevelopment(ServletContext) which is capable of checking if the current JSF application configuration is set to development project stage.

Those methods can be used in for example a servlet filter.

Since:

1.6

Author:

Arjan Tijms, Bauke Scholtz

Method Summary

Modifier and Type	Method and Description
static void	addResponseCookie(HttpServletRequest request, HttpServletResponse response, String name, String value, int maxAge) Add a cookie with given name, value and maxage to the HTTP response.
static void	addResponseCookie(HttpServletRequest request, HttpServletResponse response, String name, String value, String path, int maxAge) Add a cookie with given name, value, path and maxage to the HTTP response.
static void	addResponseCookie(HttpServletRequest request, HttpServletResponse response, String name, String value, String domain, String path, int maxAge) Add a cookie with given name, value, domain, path and maxage to the HTTP response.
static void	facesRedirect(HttpServletRequest request, HttpServletResponse response, String url, String... paramValues) Sends a temporary (302) JSF redirect to the given URL, supporting JSF ajax requests.
static <T> T	getApplicationAttribute(ServletContext context, String name) Returns the application scope attribute value associated with the given name.
static String	getForwardRequestQueryString(HttpServletRequest request) Returns the original HTTP request query string behind this forwarded request, if any.
static String	getForwardRequestURI(HttpServletRequest request) Returns the original HTTP request URI behind this forwarded request, if any.
static String	getForwardRequestURIWithQueryString(HttpServletRequest request) Returns the original HTTP request URI with query string behind this forwarded request, if any.
static String	getRequestBaseURL(HttpServletRequest request) Returns the HTTP request base URL.
static String	getRequestCookie(HttpServletRequest request, String name) Returns the value of the HTTP request cookie associated with the given name.
static String	getRequestDomainURL(HttpServletRequest request) Returns the HTTP request domain URL.
static String	getRequestHostname(HttpServletRequest request) Returns the HTTP request hostname.
static Map<String,List<String>>	getRequestQueryStringMap(HttpServletRequest request) Returns the HTTP request query string as parameter values map.
static String	getRequestRelativeURI(HttpServletRequest request) Returns the HTTP request URI relative to the context root of a web application.
static String	getRequestRelativeURIWithoutPathParameters(HttpServletRequest request) Returns the HTTP request URI relative to the context root of a web application.
static String	getRequestURIWithQueryString(HttpServletRequest request) Returns the HTTP request URI with query string.
static String	getRequestURLWithQueryString(HttpServletRequest request) Returns the HTTP request URL with query string.
static boolean	isFacesAjaxRequest(HttpServletRequest request) Returns true if the given HTTP servlet request is a JSF ajax request.
static boolean	isFacesDevelopment(ServletContext context) Returns true if we're in JSF development stage.
static boolean	isFacesResourceRequest(HttpServletRequest request) Returns true if the given HTTP servlet request is a JSF resource request.
static void	removeResponseCookie(HttpServletRequest request, HttpServletResponse response, String name, String path) Remove the cookie with given name and path from the HTTP response.
static void	setCacheHeaders(HttpServletResponse response, long expires) Set the cache headers.
static void	setNoCacheHeaders(HttpServletResponse response) Set the no-cache headers.
static Map<String,List<String>>	toParameterMap(String queryString) Converts the given request query string to request parameter values map.
static String	toQueryString(List<ParamHolder> params) Converts the given parameter values list to request query string.
static String	toQueryString(Map<String,List<String>> parameterMap) Converts the given request parameter values map to request query string.

Methods inherited from class java.lang.Object

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

Method Detail

getRequestHostname

public static String getRequestHostname(HttpServletRequest request)

Returns the HTTP request hostname. This is the entire domain, without any scheme and slashes. Noted should be that this value is extracted from the request URL, not from ServletRequest.getServerName() as its outcome can be influenced by proxies.

Parameters:

request - The involved HTTP servlet request.

Returns:

The HTTP request hostname.

Throws:

IllegalArgumentException - When the URL is malformed. This is however unexpected as the request would otherwise not have hit the server at all.

See Also:

HttpServletRequest.getRequestURL()

getRequestDomainURL

public static String getRequestDomainURL(HttpServletRequest request)

Returns the HTTP request domain URL. This is the URL with the scheme and domain, without any trailing slash.

Parameters:

request - The involved HTTP servlet request.

Returns:

The HTTP request domain URL.

See Also:

HttpServletRequest.getRequestURL(), HttpServletRequest.getRequestURI()

getRequestBaseURL

public static String getRequestBaseURL(HttpServletRequest request)

Returns the HTTP request base URL. This is the URL from the scheme, domain until with context path, including the trailing slash. This is the value you could use in HTML <base> tag.

Parameters:

request - The involved HTTP servlet request.

Returns:

The HTTP request base URL.

See Also:

HttpServletRequest.getRequestURL(), HttpServletRequest.getRequestURI(), HttpServletRequest.getContextPath()

getRequestRelativeURI

public static String getRequestRelativeURI(HttpServletRequest request)

Returns the HTTP request URI relative to the context root of a web application. This is the request URI minus the context path. Note that this includes path parameters.

Parameters:

request - The involved HTTP servlet request.

Returns:

the request URI relative to the context root

Since:

1.8

getRequestRelativeURIWithoutPathParameters

public static String getRequestRelativeURIWithoutPathParameters(HttpServletRequest request)

Returns the HTTP request URI relative to the context root of a web application. This is the servlet path plus the path info (if any).

Parameters:

request - The involved HTTP servlet request.

Returns:

the request URI relative to the context root

Since:

1.8

getRequestURLWithQueryString

public static String getRequestURLWithQueryString(HttpServletRequest request)

Returns the HTTP request URL with query string. This is the full request URL with query string as the enduser sees in browser address bar.

Parameters:

request - The involved HTTP servlet request.

Returns:

The HTTP request URL with query string.

See Also:

HttpServletRequest.getRequestURL(), HttpServletRequest.getQueryString()

getRequestURIWithQueryString

public static String getRequestURIWithQueryString(HttpServletRequest request)

Returns the HTTP request URI with query string. This is the part after the domain in the request URL, including the leading slash and the request query string.

Parameters:

request - The involved HTTP servlet request.

Returns:

The HTTP request URI with query string.

See Also:

HttpServletRequest.getRequestURI(), HttpServletRequest.getQueryString()

getRequestQueryStringMap

public static Map<String,List<String>> getRequestQueryStringMap(HttpServletRequest request)

Returns the HTTP request query string as parameter values map. Note this method returns only the request URL (GET) parameters, as opposed to ServletRequest.getParameterMap(), which contains both the request URL (GET) parameters and and the request body (POST) parameters. The map entries are in the same order as they appear in the query string.

Parameters:

request - The request for which the base URL is computed.

Returns:

The HTTP request query string as parameter values map.

getForwardRequestURI

public static String getForwardRequestURI(HttpServletRequest request)

Returns the original HTTP request URI behind this forwarded request, if any. This does not include the request query string.

Parameters:

request - The involved HTTP servlet request.

Returns:

The original HTTP request URI behind this forwarded request, if any.

Since:

1.8

getForwardRequestQueryString

public static String getForwardRequestQueryString(HttpServletRequest request)

Returns the original HTTP request query string behind this forwarded request, if any.

Parameters:

request - The involved HTTP servlet request.

Returns:

The original HTTP request query string behind this forwarded request, if any.

Since:

1.8

getForwardRequestURIWithQueryString

public static String getForwardRequestURIWithQueryString(HttpServletRequest request)

Returns the original HTTP request URI with query string behind this forwarded request, if any.

Parameters:

request - The involved HTTP servlet request.

Returns:

The original HTTP request URI with query string behind this forwarded request, if any.

Since:

1.8

toParameterMap

public static Map<String,List<String>> toParameterMap(String queryString)

Converts the given request query string to request parameter values map.

Parameters:

queryString - The request query string.

Returns:

The request query string as request parameter values map.

Since:

1.7

toQueryString

public static String toQueryString(Map<String,List<String>> parameterMap)

Converts the given request parameter values map to request query string. Empty names and null values will be skipped.

Parameters:

parameterMap - The request parameter values map.

Returns:

The request parameter values map as request query string.

Since:

2.0

toQueryString

public static String toQueryString(List<ParamHolder> params)

Converts the given parameter values list to request query string. Empty names and null values will be skipped.

Parameters:

params - The parameter values list.

Returns:

The parameter values list as request query string.

Since:

2.2

setCacheHeaders

public static void setCacheHeaders(HttpServletResponse response,
                                   long expires)

Set the cache headers. If the expires argument is larger than 0 seconds, then the following headers will be set:

• Cache-Control: public,max-age=[expiration time in seconds],must-revalidate
• Expires: [expiration date of now plus expiration time in seconds]

Else the method will delegate to setNoCacheHeaders(HttpServletResponse).

Parameters:

response - The HTTP servlet response to set the headers on.

expires - The expire time in seconds (not milliseconds!).

Since:

2.2

setNoCacheHeaders

public static void setNoCacheHeaders(HttpServletResponse response)

Set the no-cache headers. The following headers will be set:

• Cache-Control: no-cache,no-store,must-revalidate
• Expires: [expiration date of 0]
• Pragma: no-cache

Set the no-cache headers.

Parameters:

response - The HTTP servlet response to set the headers on.

Since:

2.2

getRequestCookie

public static String getRequestCookie(HttpServletRequest request,
                                      String name)

Returns the value of the HTTP request cookie associated with the given name. The value is implicitly URL-decoded with a charset of UTF-8.

Parameters:

request - The involved HTTP servlet request.

name - The HTTP request cookie name.

Returns:

The value of the HTTP request cookie associated with the given name.

Throws:

UnsupportedOperationException - When this platform does not support UTF-8.

Since:

2.0

See Also:

HttpServletRequest.getCookies()

addResponseCookie

public static void addResponseCookie(HttpServletRequest request,
                                     HttpServletResponse response,
                                     String name,
                                     String value,
                                     int maxAge)

Add a cookie with given name, value and maxage to the HTTP response. The cookie value will implicitly be URL-encoded with UTF-8 so that any special characters can be stored in the cookie. The cookie will implicitly be set to secure when the current request is secure (i.e. when the current request is a HTTPS request). The cookie will implicitly be set in the domain and path of the current request URL.

Parameters:

request - The involved HTTP servlet request.

response - The involved HTTP servlet response.

name - The cookie name.

value - The cookie value.

maxAge - The maximum age of the cookie, in seconds. If this is 0, then the cookie will be removed. Note that the name and path must be exactly the same as it was when the cookie was created. If this is -1 then the cookie will become a session cookie and thus live as long as the established HTTP session.

Throws:

UnsupportedOperationException - When this platform does not support UTF-8.

Since:

2.0

See Also:

HttpServletResponse.addCookie(Cookie)

addResponseCookie

public static void addResponseCookie(HttpServletRequest request,
                                     HttpServletResponse response,
                                     String name,
                                     String value,
                                     String path,
                                     int maxAge)

Add a cookie with given name, value, path and maxage to the HTTP response. The cookie value will implicitly be URL-encoded with UTF-8 so that any special characters can be stored in the cookie. The cookie will implicitly be set to secure when the current request is secure (i.e. when the current request is a HTTPS request). The cookie will implicitly be set in the domain of the current request URL.

Parameters:

request - The involved HTTP servlet request.

response - The involved HTTP servlet response.

name - The cookie name.

value - The cookie value.

path - The cookie path. If this is /, then the cookie is available in all pages of the webapp. If this is /somespecificpath, then the cookie is only available in pages under the specified path.

maxAge - The maximum age of the cookie, in seconds. If this is 0, then the cookie will be removed. Note that the name and path must be exactly the same as it was when the cookie was created. If this is -1 then the cookie will become a session cookie and thus live as long as the established HTTP session.

Throws:

UnsupportedOperationException - When this platform does not support UTF-8.

Since:

2.0

See Also:

HttpServletResponse.addCookie(Cookie)

addResponseCookie

public static void addResponseCookie(HttpServletRequest request,
                                     HttpServletResponse response,
                                     String name,
                                     String value,
                                     String domain,
                                     String path,
                                     int maxAge)

Add a cookie with given name, value, domain, path and maxage to the HTTP response. The cookie value will implicitly be URL-encoded with UTF-8 so that any special characters can be stored in the cookie. The cookie will implicitly be set to secure when the current request is secure (i.e. when the current request is a HTTPS request).

Parameters:

request - The involved HTTP servlet request.

response - The involved HTTP servlet response.

name - The cookie name.

value - The cookie value.

domain - The cookie domain. You can use .example.com (with a leading period) if you'd like the cookie to be available to all subdomains of the domain. Note that you cannot set it to a different domain.

path - The cookie path. If this is /, then the cookie is available in all pages of the webapp. If this is /somespecificpath, then the cookie is only available in pages under the specified path.

maxAge - The maximum age of the cookie, in seconds. If this is 0, then the cookie will be removed. Note that the name and path must be exactly the same as it was when the cookie was created. If this is -1 then the cookie will become a session cookie and thus live as long as the established HTTP session.

Throws:

UnsupportedOperationException - When this platform does not support UTF-8.

Since:

2.0

See Also:

HttpServletResponse.addCookie(Cookie)

removeResponseCookie

public static void removeResponseCookie(HttpServletRequest request,
                                        HttpServletResponse response,
                                        String name,
                                        String path)

Remove the cookie with given name and path from the HTTP response. Note that the name and path must be exactly the same as it was when the cookie was created.

Parameters:

request - The involved HTTP servlet request.

response - The involved HTTP servlet response.

name - The cookie name.

path - The cookie path.

Since:

2.0

See Also:

HttpServletResponse.addCookie(Cookie)

getApplicationAttribute

public static <T> T getApplicationAttribute(ServletContext context,
                                            String name)

Returns the application scope attribute value associated with the given name.

Type Parameters:

T - The expected return type.

Parameters:

context - The servlet context used for looking up the attribute.

name - The application scope attribute name.

Returns:

The application scope attribute value associated with the given name.

Throws:

ClassCastException - When T is of wrong type.

See Also:

ServletContext.getAttribute(String)

isFacesAjaxRequest

public static boolean isFacesAjaxRequest(HttpServletRequest request)

Returns true if the given HTTP servlet request is a JSF ajax request. This does exactly the same as Faces.isAjaxRequest(), but then without the need for a FacesContext. The major advantage is that you can perform the job inside a servlet filter, where the FacesContext is normally not available.

Parameters:

request - The involved HTTP servlet request.

Returns:

true if the given HTTP servlet request is a JSF ajax request.

Since:

2.0

isFacesResourceRequest

public static boolean isFacesResourceRequest(HttpServletRequest request)

Returns true if the given HTTP servlet request is a JSF resource request. I.e. this request will trigger the JSF ResourceHandler for among others CSS/JS/image resources.

Parameters:

request - The involved HTTP servlet request.

Returns:

true if the given HTTP servlet request is a JSF resource request.

Since:

2.0

See Also:

ResourceHandler.RESOURCE_IDENTIFIER

isFacesDevelopment

public static boolean isFacesDevelopment(ServletContext context)

Returns true if we're in JSF development stage. This will be the case when the javax.faces.PROJECT_STAGE context parameter in web.xml is set to Development.

Parameters:

context - The involved servlet context.

Returns:

true if we're in development stage, otherwise false.

Since:

2.1

See Also:

Application.getProjectStage()

facesRedirect

public static void facesRedirect(HttpServletRequest request,
                                 HttpServletResponse response,
                                 String url,
                                 String... paramValues)
                          throws IOException

Sends a temporary (302) JSF redirect to the given URL, supporting JSF ajax requests. This does exactly the same as Faces.redirect(String, String...), but without the need for a FacesContext. The major advantage is that you can perform the job inside a servlet filter or even a plain vanilla servlet, where the FacesContext is normally not available. This method also recognizes JSF ajax requests which requires a special XML response in order to successfully perform the redirect.

If the given URL does not start with http://, https:// or /, then the request context path will be prepended, otherwise it will be the unmodified redirect URL. So, when redirecting to another page in the same web application, always specify the full path from the context root on (which in turn does not need to start with /).

 Servlets.facesRedirect(request, response, "some.xhtml");
 

You can use String.format(String, Object...) placeholder %s in the redirect URL to represent placeholders for any request parameter values which needs to be URL-encoded. Here's a concrete example:

 Servlets.facesRedirect(request, response, "some.xhtml?foo=%s&bar=%s", foo, bar);
 

Parameters:

request - The involved HTTP servlet request.

response - The involved HTTP servlet response.

url - The URL to redirect the current response to.

paramValues - The request parameter values which you'd like to put URL-encoded in the given URL.

Throws:

IOException - Whenever something fails at I/O level. The caller should preferably not catch it, but just redeclare it in the action method. The servletcontainer will handle it.

Since:

2.0