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 five special methods related to JSF without needing a FacesContext
:
getFacesLifecycle(ServletContext)
which returns the JSF lifecycle, allowing you a.o. to
programmatically register JSF application's phase listeners.
isFacesAjaxRequest(HttpServletRequest)
which is capable of checking if the current request is a JSF
ajax request.
isFacesResourceRequest(HttpServletRequest)
which is capable of checking if the current request is a
JSF resource request.
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...)
.
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.
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 Lifecycle |
getFacesLifecycle(ServletContext context)
Returns The
Lifecycle associated with current Faces application. |
static String |
getForwardRequestQueryString(HttpServletRequest request)
Deprecated.
Since 2.4. Use
getRequestQueryString(HttpServletRequest) instead. |
static String |
getForwardRequestURI(HttpServletRequest request)
Deprecated.
Since 2.4. Use
getRequestURI(HttpServletRequest) instead. |
static String |
getForwardRequestURIWithQueryString(HttpServletRequest request)
Deprecated.
Since 2.4. Use
getRequestURIWithQueryString(HttpServletRequest) instead. |
static String |
getRemoteAddr(HttpServletRequest request)
Returns the Internet Protocol (IP) address of the client that sent the request.
|
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 String |
getRequestPathInfo(HttpServletRequest request)
Returns the HTTP request path info, taking into account whether FacesViews is used with MultiViews enabled.
|
static String |
getRequestQueryString(HttpServletRequest request)
Returns the HTTP request query string, regardless of any forward.
|
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, regardless of any forward.
|
static String |
getRequestRelativeURIWithoutPathParameters(HttpServletRequest request)
Returns the HTTP request URI relative to the context root without path parameters, regardless of any forward.
|
static String |
getRequestURI(HttpServletRequest request)
Returns the HTTP request URI, regardless of any forward or error dispatch.
|
static String |
getRequestURIWithQueryString(HttpServletRequest request)
Returns the HTTP request URI with query string, regardless of any forward.
|
static String |
getRequestURL(HttpServletRequest request)
Returns the HTTP request URL with query string, regardless of any forward.
|
static String |
getRequestURLWithQueryString(HttpServletRequest request)
Returns the HTTP request URL with query string.
|
static String |
getSubmittedFileName(Part part)
Returns the submitted file name of the given part, making sure that any path is stripped off.
|
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.
|
public static String getRequestHostname(HttpServletRequest request)
ServletRequest.getServerName()
as its
outcome can be influenced by proxies.request
- The involved HTTP servlet request.IllegalArgumentException
- When the URL is malformed. This is however unexpected as the request would
otherwise not have hit the server at all.HttpServletRequest.getRequestURL()
public static String getRequestDomainURL(HttpServletRequest request)
request
- The involved HTTP servlet request.HttpServletRequest.getRequestURL()
,
HttpServletRequest.getRequestURI()
public static String getRequestBaseURL(HttpServletRequest request)
<base>
tag.request
- The involved HTTP servlet request.HttpServletRequest.getRequestURL()
,
HttpServletRequest.getRequestURI()
,
HttpServletRequest.getContextPath()
public static String getRequestURI(HttpServletRequest request)
request
- The involved HTTP servlet request.HttpServletRequest.getRequestURI()
,
RequestDispatcher.FORWARD_REQUEST_URI
,
RequestDispatcher.ERROR_REQUEST_URI
public static String getRequestPathInfo(HttpServletRequest request)
/faces/*
), then this returns the whole part after the prefix
mapping, with a leading slash. If the resource is suffix mapped (e.g. *.xhtml
), then this returns
null
.request
- The involved HTTP servlet request.HttpServletRequest.getPathInfo()
,
FacesViews.FACES_VIEWS_ORIGINAL_PATH_INFO
public static String getRequestQueryString(HttpServletRequest request)
request
- The involved HTTP servlet request.HttpServletRequest.getRequestURI()
,
RequestDispatcher.FORWARD_QUERY_STRING
public static Map<String,List<String>> getRequestQueryStringMap(HttpServletRequest request)
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.request
- The involved HTTP servlet request.public static String getRequestURIWithQueryString(HttpServletRequest request)
request
- The involved HTTP servlet request.getRequestURI(HttpServletRequest)
,
getRequestQueryString(HttpServletRequest)
public static String getRequestRelativeURI(HttpServletRequest request)
request
- The involved HTTP servlet request.public static String getRequestRelativeURIWithoutPathParameters(HttpServletRequest request)
request
- The involved HTTP servlet request.public static String getRequestURL(HttpServletRequest request)
request
- The involved HTTP servlet request.HttpServletRequest.getRequestURL()
public static String getRequestURLWithQueryString(HttpServletRequest request)
request
- The involved HTTP servlet request.HttpServletRequest.getRequestURL()
,
HttpServletRequest.getQueryString()
@Deprecated public static String getForwardRequestURI(HttpServletRequest request)
getRequestURI(HttpServletRequest)
instead.request
- The involved HTTP servlet request.@Deprecated public static String getForwardRequestQueryString(HttpServletRequest request)
getRequestQueryString(HttpServletRequest)
instead.request
- The involved HTTP servlet request.@Deprecated public static String getForwardRequestURIWithQueryString(HttpServletRequest request)
getRequestURIWithQueryString(HttpServletRequest)
instead.request
- The involved HTTP servlet request.public static Map<String,List<String>> toParameterMap(String queryString)
queryString
- The request query string.public static String toQueryString(Map<String,List<String>> parameterMap)
parameterMap
- The request parameter values map.public static String toQueryString(List<ParamHolder> params)
params
- The parameter values list.public static String getRemoteAddr(HttpServletRequest request)
X-Forwarded-For
request header and if it's present, then return its first IP address, else just
return ServletRequest.getRemoteAddr()
unmodified.request
- The involved HTTP servlet request.ServletRequest.getRemoteAddr()
public static String getSubmittedFileName(Part part)
part
- The part of a multipart/form-data request.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)
.
response
- The HTTP servlet response to set the headers on.expires
- The expire time in seconds (not milliseconds!).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
response
- The HTTP servlet response to set the headers on.public static String getRequestCookie(HttpServletRequest request, String name)
request
- The involved HTTP servlet request.name
- The HTTP request cookie name.UnsupportedOperationException
- When this platform does not support UTF-8.HttpServletRequest.getCookies()
public static void addResponseCookie(HttpServletRequest request, HttpServletResponse response, String name, String value, int maxAge)
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.UnsupportedOperationException
- When this platform does not support UTF-8.HttpServletResponse.addCookie(Cookie)
public static void addResponseCookie(HttpServletRequest request, HttpServletResponse response, String name, String value, String path, int maxAge)
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.UnsupportedOperationException
- When this platform does not support UTF-8.HttpServletResponse.addCookie(Cookie)
public static void addResponseCookie(HttpServletRequest request, HttpServletResponse response, String name, String value, String domain, String path, int maxAge)
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.UnsupportedOperationException
- When this platform does not support UTF-8.HttpServletResponse.addCookie(Cookie)
public static void removeResponseCookie(HttpServletRequest request, HttpServletResponse response, String name, String path)
request
- The involved HTTP servlet request.response
- The involved HTTP servlet response.name
- The cookie name.path
- The cookie path.HttpServletResponse.addCookie(Cookie)
public static <T> T getApplicationAttribute(ServletContext context, String name)
T
- The expected return type.context
- The servlet context used for looking up the attribute.name
- The application scope attribute name.ClassCastException
- When T
is of wrong type.ServletContext.getAttribute(String)
public static Lifecycle getFacesLifecycle(ServletContext context)
Lifecycle
associated with current Faces application.context
- The involved servlet context.Lifecycle
associated with current Faces application.LifecycleFactory.getLifecycle(String)
public static boolean isFacesAjaxRequest(HttpServletRequest request)
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.request
- The involved HTTP servlet request.true
if the given HTTP servlet request is a JSF ajax request.public static boolean isFacesResourceRequest(HttpServletRequest request)
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.request
- The involved HTTP servlet request.true
if the given HTTP servlet request is a JSF resource request.ResourceHandler.RESOURCE_IDENTIFIER
public static boolean isFacesDevelopment(ServletContext context)
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
.context
- The involved servlet context.true
if we're in development stage, otherwise false
.Application.getProjectStage()
public static void facesRedirect(HttpServletRequest request, HttpServletResponse response, String url, String... paramValues) throws IOException
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);
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.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.Copyright © 2012–2016 OmniFaces. All rights reserved.