public abstract class FacesContext
extends java.lang.Object
FacesContext contains all of the per-request state information related to the processing of a single Jakarta Server Faces request, and the rendering of the corresponding response. It is passed to, and potentially modified by, each phase of the request processing lifecycle.
A FacesContext
instance is associated with a particular request at the beginning of request processing, by a
call to the getFacesContext()
method of the FacesContextFactory
instance associated with the
current web application. The instance remains active until its release()
method is called, after which
no further references to this instance are allowed. While a FacesContext
instance is active, it must not be
referenced from any thread other than the one upon which the Jakarta Servlet container executing this web application
utilizes for the processing of this request.
A FacesContext can be injected into a request scoped bean using @Inject FacesContext facesContext;
Constructor and Description |
---|
FacesContext() |
Modifier and Type | Method and Description |
---|---|
abstract void |
addMessage(java.lang.String clientId,
FacesMessage message)
Append a
FacesMessage to the set of messages associated with the specified client
identifier, if clientId is not null . |
abstract Application |
getApplication()
Return the
Application instance associated with this web
application. |
java.util.Map<java.lang.Object,java.lang.Object> |
getAttributes()
Return a mutable |
abstract java.util.Iterator<java.lang.String> |
getClientIdsWithMessages()
Return an
Iterator over the client identifiers for which at least one
FacesMessage has been queued. |
static FacesContext |
getCurrentInstance()
Return the |
PhaseId |
getCurrentPhaseId()
Return the value last set on this |
ELContext |
getELContext()
Return the
ELContext instance for this FacesContext instance. |
ExceptionHandler |
getExceptionHandler()
Return the |
abstract ExternalContext |
getExternalContext()
|
abstract FacesMessage.Severity |
getMaximumSeverity()
Return the maximum severity level recorded on any
FacesMessage s that has been
queued, whether or not they are associated with any specific UIComponent . |
java.util.List<FacesMessage> |
getMessageList()
Like |
java.util.List<FacesMessage> |
getMessageList(java.lang.String clientId)
Like |
abstract java.util.Iterator<FacesMessage> |
getMessages()
Return an
Iterator over the FacesMessage s that have been queued,
whether or not they are associated with any specific client identifier. |
abstract java.util.Iterator<FacesMessage> |
getMessages(java.lang.String clientId)
Return an
Iterator over the FacesMessage s that have been queued that
are associated with the specified client identifier (if clientId is not null ), or over the
FacesMessage s that have been queued that are not associated with any specific
client identifier (if clientId is null ). |
char |
getNamingContainerSeparatorChar()
Return the result of calling |
PartialViewContext |
getPartialViewContext()
Return the |
abstract RenderKit |
getRenderKit()
Return the
RenderKit instance for the render kit identifier specified on our UIViewRoot , if there is
one. |
abstract boolean |
getRenderResponse()
Return
true if the renderResponse() method has been called for the current request. |
java.util.List<java.lang.String> |
getResourceLibraryContracts()
Return the list of resource library contracts that have been calculated to be appropriate for use with this view, or an empty list if there are no such resource library contracts. |
abstract boolean |
getResponseComplete()
Return
true if the responseComplete() method has been called for the current request. |
abstract ResponseStream |
getResponseStream()
Return the
ResponseStream to which components should direct their binary output. |
abstract ResponseWriter |
getResponseWriter()
Return the
ResponseWriter to which components should direct their character-based output. |
abstract UIViewRoot |
getViewRoot()
Return the root component that is associated with the this request.
|
boolean |
isPostback()
This utility method simply returns the result of
|
boolean |
isProcessingEvents()
Returns a flag indicating whether or not the runtime should publish events when asked to do so. |
boolean |
isProjectStage(ProjectStage stage)
Return |
boolean |
isReleased()
Return a flag indicating if the resources associated with this |
boolean |
isValidationFailed()
Return |
abstract void |
release()
Release any resources associated with this
FacesContext
instance. |
abstract void |
renderResponse()
Signal the Jakarta Server Faces implementation that, as soon as the current phase of the request processing lifecycle
has been completed, control should be passed to the Render Response phase, bypassing any phases that have
not been executed yet.
|
abstract void |
responseComplete()
Signal the Jakarta Server Faces implementation that the HTTP response for this request has already been generated
(such as an HTTP redirect), and that the request processing lifecycle should be terminated as soon as the current
phase is completed.
|
protected static void |
setCurrentInstance(FacesContext context)
Set the
FacesContext instance for the request that is being processed by the current thread. |
void |
setCurrentPhaseId(PhaseId currentPhaseId)
The implementation must call this method at the earliest possble point in time after entering into a new phase in the request processing lifecycle. |
void |
setExceptionHandler(ExceptionHandler exceptionHandler)
Set the |
void |
setProcessingEvents(boolean processingEvents)
Allows control of wheter or not the runtime will publish events when
|
void |
setResourceLibraryContracts(java.util.List<java.lang.String> contracts)
Set the resource library contracts calculated as valid to use with this view. |
abstract void |
setResponseStream(ResponseStream responseStream)
Set the
ResponseStream to which components should direct their binary output. |
abstract void |
setResponseWriter(ResponseWriter responseWriter)
Set the
ResponseWriter to which components should direct their character-based output. |
abstract void |
setViewRoot(UIViewRoot root)
Set the root component that is associated with this
request.
|
void |
validationFailed()
Sets a flag which indicates that a conversion or validation error occurred while processing the inputs. |
public abstract Application getApplication()
Return the Application
instance associated with this web
application.
It is valid to call this method during application startup or shutdown. If called during application startup or
shutdown, returns the correct current Application
instance.
Application
instance associated with this web application.java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic java.util.Map<java.lang.Object,java.lang.Object> getAttributes()
Return a mutable Map
representing the attributes associated wth this FacesContext
instance.
This Map
is useful to store attributes that you want to go out of scope when the Faces lifecycle for the
current request ends, which is not always the same as the request ending, especially in the case of Jakarta Servlet
filters that are invoked after the Faces lifecycle for this request completes. Accessing this
Map
does not cause any events to fire, as is the case with the other maps: for request, session, and
application scope. When release()
is invoked, the attributes must be cleared.
The Map
returned by this method is not associated with the request. If you would like to get or set
request attributes, see ExternalContext.getRequestMap()
.
The default implementation throws UnsupportedOperationException
and is provided for the sole purpose of
not breaking existing applications that extend this class.
Map
representing the attributes associated wth this FacesContext
instance.java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic PartialViewContext getPartialViewContext()
Return the PartialViewContext
for this request. The PartialViewContext
is used to control the
processing of specified components during the execute portion of the request processing lifecycle (known as partial
processing) and the rendering of specified components (known as partial rendering). This method must return a new
PartialViewContext
if one does not already exist.
PartialViewContext
for this request.java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic abstract java.util.Iterator<java.lang.String> getClientIdsWithMessages()
Return an Iterator
over the client identifiers for which at least one
FacesMessage
has been queued. If there are no such client identifiers, an empty
Iterator
is returned. If any messages have been queued that were not associated with any specific client
identifier, a null
value will be included in the iterated values. The elements in the
Iterator
must be returned in the order in which they were added with addMessage(java.lang.String, jakarta.faces.application.FacesMessage)
.
Iterator
over the client identifiers for which at least one
FacesMessage
has been queued.java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic ELContext getELContext()
Return the ELContext
instance for this FacesContext
instance. This ELContext
instance has the same lifetime and scope as the FacesContext
instance with which it is associated, and
may be created lazily the first time this method is called for a given FacesContext
instance. Upon
creation of the ELContext instance, the implementation must take the following action:
Call the ELContext.putContext(java.lang.Class<?>, java.lang.Object)
method on the instance, passing in FacesContext.class
and the
this
reference for the FacesContext
instance itself.
If the Collection
returned by Application.getELContextListeners()
is
non-empty, create an instance of ELContextEvent
and pass it to each
ELContextListener
instance in the Collection
by calling the
ELContextListener.contextCreated(jakarta.el.ELContextEvent)
method.
ELContext
.java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic ExceptionHandler getExceptionHandler()
Return the ExceptionHandler
for this request.
ExceptionHandler
.public void setExceptionHandler(ExceptionHandler exceptionHandler)
Set the ExceptionHandler
for this request.
exceptionHandler
- the ExceptionHandler
for this request.public abstract ExternalContext getExternalContext()
Return the ExternalContext
instance for this
FacesContext
instance.
It is valid to call this method during application startup or shutdown. If called during application startup or
shutdown, this method returns an ExternalContext
instance with the special behaviors indicated in the javadoc
for that class. Methods document as being valid to call during application startup or shutdown must be supported.
ExternalContext
java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic abstract FacesMessage.Severity getMaximumSeverity()
Return the maximum severity level recorded on any FacesMessage
s that has been
queued, whether or not they are associated with any specific UIComponent
. If no such
messages have been queued, return null
.
java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic abstract java.util.Iterator<FacesMessage> getMessages()
Return an Iterator
over the FacesMessage
s that have been queued,
whether or not they are associated with any specific client identifier. If no such messages have been queued, return
an empty Iterator
. The elements of the Iterator
must be returned in the order in which they
were added with calls to addMessage(java.lang.String, jakarta.faces.application.FacesMessage)
.
Iterator
over the FacesMessage
s that have been queued.java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic java.util.List<FacesMessage> getMessageList()
Like getMessages()
, but returns a List<FacesMessage>
, enabling use from Jakarta Expression
Language expressions.
The default implementation throws UnsupportedOperationException
and is provided for the sole purpose of
not breaking existing applications that extend this class.
List
which is effectively a snapshot of the messages present at the time of
invocation.java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic java.util.List<FacesMessage> getMessageList(java.lang.String clientId)
Like getMessages(java.lang.String)
, but returns a List<FacesMessage>
of messages for the
component with client id matching argument clientId
.
The default implementation throws UnsupportedOperationException
and is provided for the sole purpose of
not breaking existing applications that extend this class.
clientId
- the client id of a component.List
which is effectively a snapshot of the messages present at the time of
invocation.java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic abstract java.util.Iterator<FacesMessage> getMessages(java.lang.String clientId)
Return an Iterator
over the FacesMessage
s that have been queued that
are associated with the specified client identifier (if clientId
is not null
), or over the
FacesMessage
s that have been queued that are not associated with any specific
client identifier (if clientId
is null
). If no such messages have been queued, return an
empty Iterator
. The elements of the Iterator
must be returned in the order in which they
were added with calls to addMessage(java.lang.String, jakarta.faces.application.FacesMessage)
.
clientId
- The client identifier for which messages are requested, or null
for messages not
associated with any client identifierIterator
over the FacesMessage
s.java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic char getNamingContainerSeparatorChar()
Return the result of calling UINamingContainer.getSeparatorChar(jakarta.faces.context.FacesContext)
, passing this
as the argument.
Note that this enables accessing the value of this property from the Jakarta Expression Language expression
#{facesContext.namingContainerSeparatorChar}
.
public abstract RenderKit getRenderKit()
Return the RenderKit
instance for the render kit identifier specified on our UIViewRoot
, if there is
one. If there is no current UIViewRoot
, if the UIViewRoot
does not have a specified
renderKitId
, or if there is no RenderKit
for the specified identifier, return null
instead.
RenderKit
associated with the UIViewRoot
.java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic abstract boolean getRenderResponse()
Return true
if the renderResponse()
method has been called for the current request.
renderResponse()
has been called.java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic abstract boolean getResponseComplete()
Return true
if the responseComplete()
method has been called for the current request.
responseComplete()
method has been called.java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic java.util.List<java.lang.String> getResourceLibraryContracts()
Return the list of resource library contracts that have been calculated to be appropriate for use with this view, or an empty list if there are no such resource library contracts. The list returned by this method must be immutable. For backward compatibility with implementations of the specification prior to when this method was introduced, an implementation is provided that returns an empty list. Implementations compliant with the version in which this method was introduced must implement this method as specified.
java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic void setResourceLibraryContracts(java.util.List<java.lang.String> contracts)
Set the resource library contracts calculated as valid to use with this view. The implementation must copy the
contents of the incoming List
into an immutable List
for return from
getResourceLibraryContracts()
. If the argument is null
or empty, the action taken is the same as if
the argument is null
: a subsequent call to getResourceLibraryContracts
returns null
. This
method may only be called during the processing of ViewDeclarationLanguage.createView(jakarta.faces.context.FacesContext, java.lang.String)
and
during the VDL tag handler for the tag corresponding to an instance of UIViewRoot
. For backward compatibility
with implementations of the specification prior to when this method was introduced, an implementation is provided
that takes no action. Implementations compliant with the version in which this method was introduced must implement
this method as specified.
contracts
- The new contracts to be returned, as an immutable List
. from a subsequent call to
getResourceLibraryContracts()
.java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic boolean isValidationFailed()
Return true
if the validationFailed()
method has been called for the current request.
validationFailed()
method has been called for the current requestjava.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic abstract ResponseStream getResponseStream()
Return the ResponseStream
to which components should direct their binary output. Within a given response,
components can use either the ResponseStream or the ResponseWriter, but not both.
ResponseStream
instance.java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic abstract void setResponseStream(ResponseStream responseStream)
Set the ResponseStream
to which components should direct their binary output.
responseStream
- The new ResponseStream for this responsejava.lang.NullPointerException
- if responseStream
is null
java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic abstract ResponseWriter getResponseWriter()
Return the ResponseWriter
to which components should direct their character-based output. Within a given
response, components can use either the ResponseStream or the ResponseWriter, but not both.
ResponseWriter
instance.java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic abstract void setResponseWriter(ResponseWriter responseWriter)
Set the ResponseWriter
to which components should direct their character-based output.
responseWriter
- The new ResponseWriter for this responsejava.lang.IllegalStateException
- if this method is called after this instance has been releasedjava.lang.NullPointerException
- if responseWriter
is null
public abstract UIViewRoot getViewRoot()
Return the root component that is associated with the this request.
It is valid to call this method during application startup or shutdown. If called during application startup or
shutdown, this method returns a new UIViewRoot
with its locale set to Locale.getDefault()
.
UIViewRoot
instance.java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic abstract void setViewRoot(UIViewRoot root)
Set the root component that is associated with this request.
This method can be called by the application handler (or a class that the handler calls), during the Invoke Application phase of the request processing lifecycle and during the Restore View phase of the request processing lifecycle (especially when a new root component is created). In the present version of the specification, implementations are not required to enforce this restriction, though a future version of the specification may require enforcement.
If the current UIViewRoot
is non-null
, and calling equals()
on the argument
root
, passing the current UIViewRoot
returns false
, the clear
method must be called on the Map
returned from UIViewRoot.getViewMap()
.
root
- The new component UIViewRoot
componentjava.lang.IllegalStateException
- if this method is called after this instance has been releasedjava.lang.NullPointerException
- if root
is null
public abstract void addMessage(java.lang.String clientId, FacesMessage message)
Append a FacesMessage
to the set of messages associated with the specified client
identifier, if clientId
is not null
. If clientId
is null
, this
FacesMessage
is assumed to not be associated with any specific component instance.
clientId
- The client identifier with which this message is associated (if any)message
- The message to be appendedjava.lang.IllegalStateException
- if this method is called after this instance has been releasedjava.lang.NullPointerException
- if message
is null
public boolean isReleased()
Return a flag indicating if the resources associated with this FacesContext
instance have been released.
true
if the resources have been released.public abstract void release()
Release any resources associated with this FacesContext
instance. Faces implementations may choose to pool instances in the associated FacesContextFactory
to avoid
repeated object creation and garbage collection. After release()
is called on a
FacesContext
instance (until the FacesContext
instance has been recycled by the
implementation for re-use), calling any other methods will cause an IllegalStateException
to be thrown.
If a call was made to getAttributes()
during the processing for this request, the implementation must call
clear()
on the Map
returned from getAttributes()
, and then de-allocate the
data-structure behind that Map
.
The implementation must call setCurrentInstance(jakarta.faces.context.FacesContext)
passing null
to remove the association between
this thread and this dead FacesContext
instance.
java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic abstract void renderResponse()
Signal the Jakarta Server Faces implementation that, as soon as the current phase of the request processing lifecycle has been completed, control should be passed to the Render Response phase, bypassing any phases that have not been executed yet.
java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic boolean isPostback()
This utility method simply returns the result of
ResponseStateManager.isPostback(FacesContext)
.
The default implementation throws UnsupportedOperationException
and is provided for the sole purpose of
not breaking existing applications that extend this class.
java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic abstract void responseComplete()
Signal the Jakarta Server Faces implementation that the HTTP response for this request has already been generated (such as an HTTP redirect), and that the request processing lifecycle should be terminated as soon as the current phase is completed.
java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic void validationFailed()
Sets a flag which indicates that a conversion or validation error occurred while processing the inputs. Inputs
consist of either page parameters or form bindings. This flag can be read using isValidationFailed()
.
java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic PhaseId getCurrentPhaseId()
Return the value last set on this FacesContext
instance when setCurrentPhaseId(jakarta.faces.event.PhaseId)
was called.
java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic void setCurrentPhaseId(PhaseId currentPhaseId)
The implementation must call this method at the earliest possble point in time after entering into a new phase in the request processing lifecycle.
currentPhaseId
- The PhaseId
for the current phase.java.lang.IllegalStateException
- if this method is called after this instance has been releasedpublic void setProcessingEvents(boolean processingEvents)
Allows control of wheter or not the runtime will publish events when
Application.publishEvent(FacesContext, Class, Object)
or
Application.publishEvent(FacesContext, Class, Class, Object)
is called.
processingEvents
- flag indicating events should be processed or notpublic boolean isProcessingEvents()
Returns a flag indicating whether or not the runtime should publish events when asked to do so.
true
if events should be published, otherwise false
public boolean isProjectStage(ProjectStage stage)
Return true
if the current ProjectStage
as returned by the Application
instance is equal
to stage
, otherwise return false
stage
- the ProjectStage
to checkjava.lang.IllegalStateException
- if this method is called after this instance has been releasedjava.lang.NullPointerException
- if stage
is null
public static FacesContext getCurrentInstance()
Return the FacesContext
instance for the request that is being processed by the current thread. If called
during application initialization or shutdown, any method documented as "valid to call this method during application
startup or shutdown" must be supported during application startup or shutdown time. The result of calling a method
during application startup or shutdown time that does not have this designation is undefined.
FacesContext
.protected static void setCurrentInstance(FacesContext context)
Set the FacesContext
instance for the request that is being processed by the current thread.
context
- The FacesContext
instance for the current thread, or null
if this thread no
longer has a FacesContext
instance.