public final class Faces
extends java.lang.Object
FacesContext
. In effects, it 'flattens' the hierarchy of nested objects.
Do note that using the hierarchy is actually a better software design practice, but can lead to verbose code.
In addition, note that there's normally a small overhead in obtaining the thread local FacesContext
. In case
client code needs to call methods in this class multiple times it's expected that performance will be slightly better
if instead the FacesContext
is obtained once and the required methods called on that.
Modifier and Type | Method and Description |
---|---|
static void |
addResponseCookie(java.lang.String name,
java.lang.String value,
java.lang.String path,
int maxAge)
Add a cookie with given name, value, path and maxage to the HTTP response.
|
static void |
addResponseHeader(java.lang.String name,
java.lang.String value)
Add a header with given name and value to the HTTP response.
|
static <T> T |
evaluateExpressionGet(java.lang.String expression)
Programmatically evaluate the given EL expression and return the evaluated value.
|
static javax.faces.application.Application |
getApplication()
Returns the application singleton.
|
static <T> T |
getApplicationAttribute(java.lang.String name)
Returns the application scope attribute value associated with the given name.
|
static java.util.Map<java.lang.String,java.lang.Object> |
getApplicationMap()
Returns the application scope map.
|
static javax.faces.context.FacesContext |
getContext()
Returns the current faces context.
|
static javax.faces.event.PhaseId |
getCurrentPhaseId()
Returns the current phase ID.
|
static java.util.Locale |
getDefaultLocale()
Returns the default locale, or
null if there is none. |
static javax.faces.context.ExternalContext |
getExternalContext()
Returns the current external context.
|
static javax.faces.context.Flash |
getFlash()
Returns the flash scope.
|
static <T> T |
getFlashAttribute(java.lang.String name)
Returns the flash scope attribute value associated with the given name.
|
static java.lang.String |
getImplInfo()
Returns the implementation information of currently loaded JSF implementation.
|
static java.util.Locale |
getLocale()
Returns the current locale.
|
static java.lang.String |
getMapping()
Determines and returns the faces servlet mapping used in the current request.
|
static java.lang.String |
getMimeType(java.lang.String name)
Returns the mime type for the given file name.
|
static java.lang.String |
getRemoteUser()
Returns the name of the logged-in user for container managed FORM based authentication, if any.
|
static javax.servlet.http.HttpServletRequest |
getRequest()
Returns the HTTP servlet request.
|
static <T> T |
getRequestAttribute(java.lang.String name)
Returns the request scope attribute value associated with the given name.
|
static java.lang.String |
getRequestBaseURL()
Returns the HTTP request base URL, this is the full URL from the scheme, domain until with context path,
including the trailing slash.
|
static java.lang.String |
getRequestContextPath()
Returns the HTTP request context path.
|
static java.lang.String |
getRequestCookie(java.lang.String name)
Returns the value of the HTTP request cookie associated with the given name.
|
static java.lang.String |
getRequestHeader(java.lang.String name)
Returns the HTTP request header value associated with the given name.
|
static java.util.Map<java.lang.String,java.lang.String> |
getRequestHeaderMap()
Returns the HTTP request header map.
|
static java.lang.String[] |
getRequestHeaderValues(java.lang.String name)
Returns the HTTP request header values associated with the given name.
|
static java.util.Map<java.lang.String,java.lang.String[]> |
getRequestHeaderValuesMap()
Returns the HTTP request header values map.
|
static java.util.Map<java.lang.String,java.lang.Object> |
getRequestMap()
Returns the request scope map.
|
static java.lang.String |
getRequestParameter(java.lang.String name)
Returns the HTTP request parameter value associated with the given name.
|
static java.util.Map<java.lang.String,java.lang.String> |
getRequestParameterMap()
Returns the HTTP request parameter map.
|
static java.lang.String[] |
getRequestParameterValues(java.lang.String name)
Returns the HTTP request parameter values associated with the given name.
|
static java.util.Map<java.lang.String,java.lang.String[]> |
getRequestParameterValuesMap()
Returns the HTTP request parameter values map.
|
static java.lang.String |
getRequestPathInfo()
Returns the HTTP request path info.
|
static java.lang.String |
getRequestServletPath()
Returns the HTTP request servlet path.
|
static java.io.InputStream |
getResourceAsStream(java.lang.String path)
Returns an input stream for an application resource mapped to the specified path, if it exists; otherwise,
return
null . |
static java.util.Set<java.lang.String> |
getResourcePaths(java.lang.String path)
Returns a set of available application resource paths matching the specified path.
|
static javax.servlet.http.HttpServletResponse |
getResponse()
Returns the HTTP servlet response.
|
static java.lang.String |
getServerInfo()
Returns the server information of currently running application server implementation.
|
static javax.servlet.ServletContext |
getServletContext()
Returns the servlet context.
|
static javax.servlet.http.HttpSession |
getSession()
Returns the HTTP session and creates one if one doesn't exist.
|
static javax.servlet.http.HttpSession |
getSession(boolean create)
Returns the HTTP session and creates one if one doesn't exist and
create argument is
true , otherwise don't create one and return null . |
static <T> T |
getSessionAttribute(java.lang.String name)
Returns the session scope attribute value associated with the given name.
|
static java.util.Map<java.lang.String,java.lang.Object> |
getSessionMap()
Returns the session scope map.
|
static java.util.List<java.util.Locale> |
getSupportedLocales()
Returns a list of all supported locales on this application, with the default locale as the first item, if any.
|
static <T> T |
getViewAttribute(java.lang.String name)
Returns the view scope attribute value associated with the given name.
|
static java.lang.String |
getViewId()
Returns the ID of the current view root, or
null if there is no view. |
static java.util.Map<java.lang.String,java.lang.Object> |
getViewMap()
Returns the view scope map.
|
static java.util.Collection<javax.faces.component.UIViewParameter> |
getViewParameters()
Returns the view parameters of the current view, or an empty collection if there is no view.
|
static javax.faces.component.UIViewRoot |
getViewRoot()
Returns the current view root.
|
static void |
invalidateSession()
Invalidates the current HTTP session.
|
static boolean |
isAjaxRequest()
Returns whether the current request is an ajax request.
|
static boolean |
isDevelopment()
Returns true if we're in development stage.
|
static boolean |
isPostback()
Returns whether the current request is a postback.
|
static boolean |
isPrefixMapping()
Returns true if the faces servlet mapping used in the current request is a prefix mapping, otherwise false.
|
static boolean |
isPrefixMapping(java.lang.String mapping)
Returns true if the given mapping is a prefix mapping, otherwise false.
|
static boolean |
isUserInRole(java.lang.String role)
Returns
true if the currently logged-in user has the given role, otherwise false . |
static boolean |
isValidationFailed()
Returns whether the validations phase of the current request has failed.
|
static void |
login(java.lang.String username,
java.lang.String password)
Perform programmatic login for container managed FORM based authentication.
|
static void |
logout()
Perform programmatic logout for container managed FORM based authentication.
|
static void |
navigate(java.lang.String outcome)
Perform the JSF navigation to the given outcome.
|
static java.lang.String |
normalizeViewId(java.lang.String path)
Normalize the given path as a valid view ID based on the current mapping, if necessary.
|
static void |
redirect(java.lang.String url)
Sends a temporary (302) redirect to the given URL.
|
static void |
redirectPermanent(java.lang.String url)
Sends a permanent (301) redirect to the given URL.
|
static void |
removeResponseCookie(java.lang.String name,
java.lang.String path)
Remove the cookie with given name and path from the HTTP response.
|
static void |
responseSendError(int status,
java.lang.String message)
Sends a HTTP response error with the given status and message.
|
static void |
sendFile(byte[] content,
java.lang.String filename,
boolean attachment)
Send the given byte array as a file to the response.
|
static void |
sendFile(java.io.File file,
boolean attachment)
Send the given file to the response.
|
static void |
sendFile(java.io.InputStream content,
java.lang.String filename,
boolean attachment)
Send the given input stream as a file to the response.
|
static void |
setApplicationAttribute(java.lang.String name,
java.lang.Object value)
Sets the application scope attribute value associated with the given name.
|
static void |
setFlashAttribute(java.lang.String name,
java.lang.Object value)
Sets the flash scope attribute value associated with the given name.
|
static void |
setRequestAttribute(java.lang.String name,
java.lang.Object value)
Sets the request scope attribute value associated with the given name.
|
static void |
setSessionAttribute(java.lang.String name,
java.lang.Object value)
Sets the session scope attribute value associated with the given name.
|
static void |
setViewAttribute(java.lang.String name,
java.lang.Object value)
Sets the view scope attribute value associated with the given name.
|
public static javax.faces.context.FacesContext getContext()
FacesContext.getCurrentInstance()
public static javax.faces.context.ExternalContext getExternalContext()
FacesContext.getExternalContext()
public static javax.faces.application.Application getApplication()
FacesContext.getApplication()
public static java.lang.String getImplInfo()
Package.getImplementationTitle()
,
Package.getImplementationVersion()
public static java.lang.String getServerInfo()
ServletContext.getServerInfo()
public static boolean isDevelopment()
Application.getProjectStage()
public static java.lang.String getMapping()
null
, then it is definitely a suffix (extension) mapping like *.xhtml, else it is
definitely a prefix (path) mapping like /faces/* as available by the servlet path.public static boolean isPrefixMapping()
public static boolean isPrefixMapping(java.lang.String mapping)
isPrefixMapping()
when you already have obtained the mapping from getMapping()
so that the
mapping won't be calculated twice.mapping
- The mapping to be tested.java.lang.NullPointerException
- When mapping is null
.public static javax.faces.event.PhaseId getCurrentPhaseId()
FacesContext.getCurrentPhaseId()
public static <T> T evaluateExpressionGet(java.lang.String expression)
T
- The expected return type.expression
- The EL expression to be evaluated.java.lang.ClassCastException
- When T
is of wrong type.Application.evaluateExpressionGet(FacesContext, String, Class)
public static javax.faces.component.UIViewRoot getViewRoot()
FacesContext.getViewRoot()
public static java.lang.String getViewId()
null
if there is no view.null
if there is no view.UIViewRoot.getViewId()
public static java.lang.String normalizeViewId(java.lang.String path)
path
- The path to be normalized as a valid view ID based on the current mapping.public static java.util.Collection<javax.faces.component.UIViewParameter> getViewParameters()
ViewMetadata.getViewParameters(UIViewRoot)
public static java.util.Locale getLocale()
UIViewRoot.getLocale()
,
ExternalContext.getRequestLocale()
,
Application.getDefaultLocale()
,
Locale.getDefault()
public static java.util.Locale getDefaultLocale()
null
if there is none.null
if there is none.Application.getDefaultLocale()
public static java.util.List<java.util.Locale> getSupportedLocales()
Application.getDefaultLocale()
,
Application.getSupportedLocales()
public static void navigate(java.lang.String outcome)
outcome
- The navigation outcome.Application.getNavigationHandler()
,
NavigationHandler.handleNavigation(FacesContext, String, String)
public static javax.servlet.http.HttpServletRequest getRequest()
ExternalContext.getRequest()
public static boolean isAjaxRequest()
PartialViewContext.isAjaxRequest()
public static boolean isPostback()
FacesContext.isPostback()
public static boolean isValidationFailed()
FacesContext.isValidationFailed()
public static java.util.Map<java.lang.String,java.lang.String> getRequestParameterMap()
ExternalContext.getRequestParameterMap()
public static java.lang.String getRequestParameter(java.lang.String name)
name
- The HTTP request parameter name.ExternalContext.getRequestParameterMap()
public static java.util.Map<java.lang.String,java.lang.String[]> getRequestParameterValuesMap()
ExternalContext.getRequestParameterValuesMap()
public static java.lang.String[] getRequestParameterValues(java.lang.String name)
name
- The HTTP request parameter name.ExternalContext.getRequestParameterValuesMap()
public static java.util.Map<java.lang.String,java.lang.String> getRequestHeaderMap()
ExternalContext.getRequestHeaderMap()
public static java.lang.String getRequestHeader(java.lang.String name)
name
- The HTTP request header name.ExternalContext.getRequestHeaderMap()
public static java.util.Map<java.lang.String,java.lang.String[]> getRequestHeaderValuesMap()
ExternalContext.getRequestHeaderValuesMap()
public static java.lang.String[] getRequestHeaderValues(java.lang.String name)
name
- The HTTP request header name.ExternalContext.getRequestHeaderValuesMap()
public static java.lang.String getRequestContextPath()
ExternalContext.getRequestContextPath()
public static java.lang.String getRequestServletPath()
ExternalContext.getRequestServletPath()
public static java.lang.String getRequestPathInfo()
ExternalContext.getRequestPathInfo()
public static java.lang.String getRequestBaseURL()
<base>
tag.HttpServletRequest.getRequestURL()
,
HttpServletRequest.getRequestURI()
,
HttpServletRequest.getContextPath()
public static javax.servlet.http.HttpServletResponse getResponse()
ExternalContext.getResponse()
public static void redirect(java.lang.String url) throws java.io.IOException
url
- The URL to redirect the current response to.java.io.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.ExternalContext.redirect(String)
public static void redirectPermanent(java.lang.String url) throws java.io.IOException
url
- The URL to redirect the current response to.java.io.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.ExternalContext.setResponseStatus(int)
,
ExternalContext.setResponseHeader(String, String)
public static void responseSendError(int status, java.lang.String message) throws java.io.IOException
<error-page>
whose <error-code>
matches the given status, or in a servlet
container specific default error page if there is none. The message will be available in the error page as a
request attribute with name javax.servlet.error.message. The FacesContext.responseComplete()
will implicitly be called after sending the error.status
- The HTTP response status which is supposed to be in the range 4nn-5nn. You can use the constant
field values of HttpServletResponse
for this.message
- The message which is supposed to be available in the error page.java.io.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.ExternalContext.responseSendError(int, String)
public static void addResponseHeader(java.lang.String name, java.lang.String value)
name
- The header name.value
- The header value.ExternalContext.addResponseHeader(String, String)
public static void login(java.lang.String username, java.lang.String password) throws javax.servlet.ServletException
username
- The login username.password
- The login password.javax.servlet.ServletException
- When the login is invalid, or when container managed FORM based authentication is not
enabled.HttpServletRequest.login(String, String)
public static void logout() throws javax.servlet.ServletException
invalidateSession()
instead. Note
that the user principal is still present in the response of the current request, it's recommendable to send a
redirect after logout()
or invalidateSession()
.javax.servlet.ServletException
- When the logout has failed.HttpServletRequest.logout()
public static java.lang.String getRemoteUser()
ExternalContext.getRemoteUser()
public static boolean isUserInRole(java.lang.String role)
true
if the currently logged-in user has the given role, otherwise false
.role
- The role to be checked on the currently logged-in user.true
if the currently logged-in user has the given role, otherwise false
.ExternalContext.isUserInRole(String)
public static java.lang.String getRequestCookie(java.lang.String name)
name
- The HTTP request cookie name.java.lang.UnsupportedOperationException
- If UTF-8 is not supported on this machine.ExternalContext.getRequestCookieMap()
public static void addResponseCookie(java.lang.String name, java.lang.String value, java.lang.String path, int maxAge)
name
- The cookie name.value
- The cookie value.path
- The cookie 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.java.lang.UnsupportedOperationException
- If UTF-8 is not supported on this machine.ExternalContext.addResponseCookie(String, String, Map)
public static void removeResponseCookie(java.lang.String name, java.lang.String path)
name
- The cookie name.path
- The cookie path.ExternalContext.addResponseCookie(String, String, Map)
public static javax.servlet.http.HttpSession getSession()
ExternalContext.getSession(boolean)
public static javax.servlet.http.HttpSession getSession(boolean create)
create
argument is
true
, otherwise don't create one and return null
.ExternalContext.getSession(boolean)
public static void invalidateSession()
ExternalContext.invalidateSession()
public static javax.servlet.ServletContext getServletContext()
ExternalContext.getContext()
public static java.lang.String getMimeType(java.lang.String name)
<mime-mapping>
entries in web.xml. When the mime type is unknown,
then a default of application/octet-stream will be returned.name
- The file name to return the mime type for.ExternalContext.getMimeType(String)
public static java.io.InputStream getResourceAsStream(java.lang.String path)
null
.path
- The application resource path to return an input stream for.ExternalContext.getResourceAsStream(String)
public static java.util.Set<java.lang.String> getResourcePaths(java.lang.String path)
path
- The partial application resource path used to return matching resource paths.ServletContext.getResourcePaths(String)
public static java.util.Map<java.lang.String,java.lang.Object> getRequestMap()
ExternalContext.getRequestMap()
public static <T> T getRequestAttribute(java.lang.String name)
name
- The request scope attribute name.java.lang.ClassCastException
- When T
is of wrong type.ExternalContext.getRequestMap()
public static void setRequestAttribute(java.lang.String name, java.lang.Object value)
name
- The request scope attribute name.value
- The request scope attribute value.ExternalContext.getRequestMap()
public static javax.faces.context.Flash getFlash()
Flash
implements Map<String, Object>
, so you
can just treat it like a Map<String, Object>
.ExternalContext.getFlash()
public static <T> T getFlashAttribute(java.lang.String name)
name
- The flash scope attribute name.java.lang.ClassCastException
- When T
is of wrong type.ExternalContext.getFlash()
public static void setFlashAttribute(java.lang.String name, java.lang.Object value)
name
- The flash scope attribute name.value
- The flash scope attribute value.ExternalContext.getFlash()
public static java.util.Map<java.lang.String,java.lang.Object> getViewMap()
UIViewRoot.getViewMap()
public static <T> T getViewAttribute(java.lang.String name)
name
- The view scope attribute name.java.lang.ClassCastException
- When T
is of wrong type.UIViewRoot.getViewMap()
public static void setViewAttribute(java.lang.String name, java.lang.Object value)
name
- The view scope attribute name.value
- The view scope attribute value.UIViewRoot.getViewMap()
public static java.util.Map<java.lang.String,java.lang.Object> getSessionMap()
ExternalContext.getSessionMap()
public static <T> T getSessionAttribute(java.lang.String name)
name
- The session scope attribute name.java.lang.ClassCastException
- When T
is of wrong type.ExternalContext.getSessionMap()
public static void setSessionAttribute(java.lang.String name, java.lang.Object value)
name
- The session scope attribute name.value
- The session scope attribute value.ExternalContext.getSessionMap()
public static java.util.Map<java.lang.String,java.lang.Object> getApplicationMap()
ExternalContext.getApplicationMap()
public static <T> T getApplicationAttribute(java.lang.String name)
name
- The application scope attribute name.java.lang.ClassCastException
- When T
is of wrong type.ExternalContext.getApplicationMap()
public static void setApplicationAttribute(java.lang.String name, java.lang.Object value)
name
- The application scope attribute name.value
- The application scope attribute value.ExternalContext.getApplicationMap()
public static void sendFile(java.io.File file, boolean attachment) throws java.io.IOException
FacesContext.responseComplete()
will implicitly be called
after successful streaming.file
- The file to be sent to the response.attachment
- Whether the file should be provided as attachment, or just inline.java.io.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.public static void sendFile(byte[] content, java.lang.String filename, boolean attachment) throws java.io.IOException
FacesContext.responseComplete()
will
implicitly be called after successful streaming.content
- The file content as byte array.filename
- The file name which should appear in content disposition header.attachment
- Whether the file should be provided as attachment, or just inline.java.io.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.public static void sendFile(java.io.InputStream content, java.lang.String filename, boolean attachment) throws java.io.IOException
InputStream.close()
will implicitly be called after streaming, regardless of whether an exception is
been thrown or not. The FacesContext.responseComplete()
will implicitly be called after successful
streaming.content
- The file content as input stream.filename
- The file name which should appear in content disposition header.attachment
- Whether the file should be provided as attachment, or just inline.java.io.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.