Class FacesContext
- Direct Known Subclasses:
FacesContextImpl
,FacesContextWrapper
,NoOpFacesContext
public abstract class FacesContext extends 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 Summary
Constructors Constructor Description FacesContext()
-
Method Summary
Modifier and Type Method Description abstract void
addMessage(String clientId, FacesMessage message)
Append aFacesMessage
to the set of messages associated with the specified client identifier, ifclientId
is notnull
.abstract Application
getApplication()
Return theApplication
instance associated with this web application.Map<Object,Object>
getAttributes()
Return a mutableMap
representing the attributes associated wth thisFacesContext
instance.abstract Iterator<String>
getClientIdsWithMessages()
Return anIterator
over the client identifiers for which at least oneFacesMessage
has been queued.static FacesContext
getCurrentInstance()
Return theFacesContext
instance for the request that is being processed by the current thread.PhaseId
getCurrentPhaseId()
Return the value last set on thisFacesContext
instance whensetCurrentPhaseId(jakarta.faces.event.PhaseId)
was called.jakarta.el.ELContext
getELContext()
Return theELContext
instance for thisFacesContext
instance.ExceptionHandler
getExceptionHandler()
Return theExceptionHandler
for this request.abstract ExternalContext
getExternalContext()
abstract FacesMessage.Severity
getMaximumSeverity()
Return the maximum severity level recorded on anyFacesMessage
s that has been queued, whether or not they are associated with any specificUIComponent
.List<FacesMessage>
getMessageList()
LikegetMessages()
, but returns aList<FacesMessage>
, enabling use from Jakarta Expression Language expressions.List<FacesMessage>
getMessageList(String clientId)
LikegetMessages(java.lang.String)
, but returns aList<FacesMessage>
of messages for the component with client id matching argumentclientId
.abstract Iterator<FacesMessage>
getMessages()
Return anIterator
over theFacesMessage
s that have been queued, whether or not they are associated with any specific client identifier.abstract Iterator<FacesMessage>
getMessages(String clientId)
Return anIterator
over theFacesMessage
s that have been queued that are associated with the specified client identifier (ifclientId
is notnull
), or over theFacesMessage
s that have been queued that are not associated with any specific client identifier (ifclientId
isnull
).char
getNamingContainerSeparatorChar()
Return the result of callingUINamingContainer.getSeparatorChar(jakarta.faces.context.FacesContext)
, passingthis
as the argument.PartialViewContext
getPartialViewContext()
Return thePartialViewContext
for this request.abstract RenderKit
getRenderKit()
Return theRenderKit
instance for the render kit identifier specified on ourUIViewRoot
, if there is one.abstract boolean
getRenderResponse()
Returntrue
if therenderResponse()
method has been called for the current request.List<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()
Returntrue
if theresponseComplete()
method has been called for the current request.abstract ResponseStream
getResponseStream()
Return theResponseStream
to which components should direct their binary output.abstract ResponseWriter
getResponseWriter()
Return theResponseWriter
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 ofResponseStateManager.isPostback(FacesContext)
.boolean
isProcessingEvents()
Returns a flag indicating whether or not the runtime should publish events when asked to do so.boolean
isProjectStage(ProjectStage stage)
Returntrue
if the currentProjectStage
as returned by theApplication
instance is equal tostage
, otherwise returnfalse
boolean
isReleased()
Return a flag indicating if the resources associated with thisFacesContext
instance have been released.boolean
isValidationFailed()
Returntrue
if thevalidationFailed()
method has been called for the current request.abstract void
release()
Release any resources associated with thisFacesContext
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 theFacesContext
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 theExceptionHandler
for this request.void
setProcessingEvents(boolean processingEvents)
Allows control of wheter or not the runtime will publish events whenApplication.publishEvent(FacesContext, Class, Object)
orApplication.publishEvent(FacesContext, Class, Class, Object)
is called.void
setResourceLibraryContracts(List<String> contracts)
Set the resource library contracts calculated as valid to use with this view.abstract void
setResponseStream(ResponseStream responseStream)
Set theResponseStream
to which components should direct their binary output.abstract void
setResponseWriter(ResponseWriter responseWriter)
Set theResponseWriter
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.
-
Constructor Details
-
FacesContext
public FacesContext()
-
-
Method Details
-
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.- Returns:
- the
Application
instance associated with this web application. - Throws:
IllegalStateException
- if this method is called after this instance has been released
-
getAttributes
Return a mutable
Map
representing the attributes associated wth thisFacesContext
instance. ThisMap
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 thisMap
does not cause any events to fire, as is the case with the other maps: for request, session, and application scope. Whenrelease()
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, seeExternalContext.getRequestMap()
.The default implementation throws
UnsupportedOperationException
and is provided for the sole purpose of not breaking existing applications that extend this class.- Returns:
- mutable
Map
representing the attributes associated wth thisFacesContext
instance. - Throws:
IllegalStateException
- if this method is called after this instance has been released- Since:
- 2.0
-
getPartialViewContext
Return the
PartialViewContext
for this request. ThePartialViewContext
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 newPartialViewContext
if one does not already exist.- Returns:
- the instance of
PartialViewContext
for this request. - Throws:
IllegalStateException
- if this method is called after this instance has been released- Since:
- 2.0
-
getClientIdsWithMessages
Return an
Iterator
over the client identifiers for which at least oneFacesMessage
has been queued. If there are no such client identifiers, an emptyIterator
is returned. If any messages have been queued that were not associated with any specific client identifier, anull
value will be included in the iterated values. The elements in theIterator
must be returned in the order in which they were added withaddMessage(java.lang.String, jakarta.faces.application.FacesMessage)
.- Returns:
- the
Iterator
over the client identifiers for which at least oneFacesMessage
has been queued. - Throws:
IllegalStateException
- if this method is called after this instance has been released
-
getELContext
public jakarta.el.ELContext getELContext()Return the
ELContext
instance for thisFacesContext
instance. ThisELContext
instance has the same lifetime and scope as theFacesContext
instance with which it is associated, and may be created lazily the first time this method is called for a givenFacesContext
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 inFacesContext.class
and thethis
reference for theFacesContext
instance itself. -
If the
Collection
returned byApplication.getELContextListeners()
is non-empty, create an instance ofELContextEvent
and pass it to eachELContextListener
instance in theCollection
by calling theELContextListener.contextCreated(jakarta.el.ELContextEvent)
method.
- Returns:
- instance of
ELContext
. - Throws:
IllegalStateException
- if this method is called after this instance has been released- Since:
- 1.2
-
-
getExceptionHandler
Return the
ExceptionHandler
for this request.- Returns:
- instance of
ExceptionHandler
.
-
setExceptionHandler
Set the
ExceptionHandler
for this request.- Parameters:
exceptionHandler
- theExceptionHandler
for this request.
-
getExternalContext
Return the
ExternalContext
instance for thisFacesContext
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.- Returns:
- instance of
ExternalContext
- Throws:
IllegalStateException
- if this method is called after this instance has been released
-
getMaximumSeverity
Return the maximum severity level recorded on any
FacesMessage
s that has been queued, whether or not they are associated with any specificUIComponent
. If no such messages have been queued, returnnull
.- Returns:
- the maximum severity level.
- Throws:
IllegalStateException
- if this method is called after this instance has been released
-
getMessages
Return an
Iterator
over theFacesMessage
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 emptyIterator
. The elements of theIterator
must be returned in the order in which they were added with calls toaddMessage(java.lang.String, jakarta.faces.application.FacesMessage)
.- Returns:
Iterator
over theFacesMessage
s that have been queued.- Throws:
IllegalStateException
- if this method is called after this instance has been released
-
getMessageList
Like
getMessages()
, but returns aList<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.- Returns:
- an immutable
List
which is effectively a snapshot of the messages present at the time of invocation. - Throws:
IllegalStateException
- if this method is called after this instance has been released- Since:
- 2.0
-
getMessageList
Like
getMessages(java.lang.String)
, but returns aList<FacesMessage>
of messages for the component with client id matching argumentclientId
.The default implementation throws
UnsupportedOperationException
and is provided for the sole purpose of not breaking existing applications that extend this class.- Parameters:
clientId
- the client id of a component.- Returns:
- an immutable
List
which is effectively a snapshot of the messages present at the time of invocation. - Throws:
IllegalStateException
- if this method is called after this instance has been released- Since:
- 2.0
-
getMessages
Return an
Iterator
over theFacesMessage
s that have been queued that are associated with the specified client identifier (ifclientId
is notnull
), or over theFacesMessage
s that have been queued that are not associated with any specific client identifier (ifclientId
isnull
). If no such messages have been queued, return an emptyIterator
. The elements of theIterator
must be returned in the order in which they were added with calls toaddMessage(java.lang.String, jakarta.faces.application.FacesMessage)
.- Parameters:
clientId
- The client identifier for which messages are requested, ornull
for messages not associated with any client identifier- Returns:
Iterator
over theFacesMessage
s.- Throws:
IllegalStateException
- if this method is called after this instance has been released
-
getNamingContainerSeparatorChar
public char getNamingContainerSeparatorChar()Return the result of calling
UINamingContainer.getSeparatorChar(jakarta.faces.context.FacesContext)
, passingthis
as the argument. Note that this enables accessing the value of this property from the Jakarta Expression Language expression#{facesContext.namingContainerSeparatorChar}
.- Returns:
- the separator char.
-
getRenderKit
Return the
RenderKit
instance for the render kit identifier specified on ourUIViewRoot
, if there is one. If there is no currentUIViewRoot
, if theUIViewRoot
does not have a specifiedrenderKitId
, or if there is noRenderKit
for the specified identifier, returnnull
instead.- Returns:
- instance of
RenderKit
associated with theUIViewRoot
. - Throws:
IllegalStateException
- if this method is called after this instance has been released
-
getRenderResponse
public abstract boolean getRenderResponse()Return
true
if therenderResponse()
method has been called for the current request.- Returns:
- flag indicating whether the
renderResponse()
has been called. - Throws:
IllegalStateException
- if this method is called after this instance has been released
-
getResponseComplete
public abstract boolean getResponseComplete()Return
true
if theresponseComplete()
method has been called for the current request.- Returns:
- the boolean indicating whether
responseComplete()
method has been called. - Throws:
IllegalStateException
- if this method is called after this instance has been released
-
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.
- Returns:
- the list of resource library contracts.
- Throws:
IllegalStateException
- if this method is called after this instance has been released- Since:
- 2.2
-
setResourceLibraryContracts
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 immutableList
for return fromgetResourceLibraryContracts()
. If the argument isnull
or empty, the action taken is the same as if the argument isnull
: a subsequent call togetResourceLibraryContracts
returnsnull
. This method may only be called during the processing ofViewDeclarationLanguage.createView(jakarta.faces.context.FacesContext, java.lang.String)
and during the VDL tag handler for the tag corresponding to an instance ofUIViewRoot
. 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.- Parameters:
contracts
- The new contracts to be returned, as an immutableList
. from a subsequent call togetResourceLibraryContracts()
.- Throws:
IllegalStateException
- if this method is called after this instance has been released- Since:
- 2.2
-
isValidationFailed
public boolean isValidationFailed()Return
true
if thevalidationFailed()
method has been called for the current request.- Returns:
- boolean indicating if the
validationFailed()
method has been called for the current request - Throws:
IllegalStateException
- if this method is called after this instance has been released
-
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.- Returns:
ResponseStream
instance.- Throws:
IllegalStateException
- if this method is called after this instance has been released
-
setResponseStream
Set the
ResponseStream
to which components should direct their binary output.- Parameters:
responseStream
- The new ResponseStream for this response- Throws:
NullPointerException
- ifresponseStream
isnull
IllegalStateException
- if this method is called after this instance has been released
-
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.- Returns:
ResponseWriter
instance.- Throws:
IllegalStateException
- if this method is called after this instance has been released
-
setResponseWriter
Set the
ResponseWriter
to which components should direct their character-based output.- Parameters:
responseWriter
- The new ResponseWriter for this response- Throws:
IllegalStateException
- if this method is called after this instance has been releasedNullPointerException
- ifresponseWriter
isnull
-
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 toLocale.getDefault()
.- Returns:
UIViewRoot
instance.- Throws:
IllegalStateException
- if this method is called after this instance has been released
-
setViewRoot
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 callingequals()
on the argumentroot
, passing the currentUIViewRoot
returnsfalse
, theclear
method must be called on theMap
returned fromUIViewRoot.getViewMap()
.- Parameters:
root
- The new componentUIViewRoot
component- Throws:
IllegalStateException
- if this method is called after this instance has been releasedNullPointerException
- ifroot
isnull
-
addMessage
Append a
FacesMessage
to the set of messages associated with the specified client identifier, ifclientId
is notnull
. IfclientId
isnull
, thisFacesMessage
is assumed to not be associated with any specific component instance.- Parameters:
clientId
- The client identifier with which this message is associated (if any)message
- The message to be appended- Throws:
IllegalStateException
- if this method is called after this instance has been releasedNullPointerException
- ifmessage
isnull
-
isReleased
public boolean isReleased()Return a flag indicating if the resources associated with this
FacesContext
instance have been released.- Returns:
true
if the resources have been released.- Since:
- 2.1
-
release
public abstract void release()Release any resources associated with this
FacesContext
instance. Faces implementations may choose to pool instances in the associatedFacesContextFactory
to avoid repeated object creation and garbage collection. Afterrelease()
is called on aFacesContext
instance (until theFacesContext
instance has been recycled by the implementation for re-use), calling any other methods will cause anIllegalStateException
to be thrown.If a call was made to
getAttributes()
during the processing for this request, the implementation must callclear()
on theMap
returned fromgetAttributes()
, and then de-allocate the data-structure behind thatMap
.The implementation must call
setCurrentInstance(jakarta.faces.context.FacesContext)
passingnull
to remove the association between this thread and this deadFacesContext
instance.- Throws:
IllegalStateException
- if this method is called after this instance has been released
-
renderResponse
public 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.
- Throws:
IllegalStateException
- if this method is called after this instance has been released
-
isPostback
public 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.- Returns:
- the boolean indicating whether this request is a post one.
- Throws:
IllegalStateException
- if this method is called after this instance has been released- Since:
- 2.0
-
responseComplete
public 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.
- Throws:
IllegalStateException
- if this method is called after this instance has been released
-
validationFailed
public 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()
.- Throws:
IllegalStateException
- if this method is called after this instance has been released
-
getCurrentPhaseId
Return the value last set on this
FacesContext
instance whensetCurrentPhaseId(jakarta.faces.event.PhaseId)
was called.- Returns:
- the current phase id.
- Throws:
IllegalStateException
- if this method is called after this instance has been released- Since:
- 2.0
-
setCurrentPhaseId
The implementation must call this method at the earliest possble point in time after entering into a new phase in the request processing lifecycle.
- Parameters:
currentPhaseId
- ThePhaseId
for the current phase.- Throws:
IllegalStateException
- if this method is called after this instance has been released- Since:
- 2.0
-
setProcessingEvents
public void setProcessingEvents(boolean processingEvents)Allows control of wheter or not the runtime will publish events when
Application.publishEvent(FacesContext, Class, Object)
orApplication.publishEvent(FacesContext, Class, Class, Object)
is called.- Parameters:
processingEvents
- flag indicating events should be processed or not
-
isProcessingEvents
public boolean isProcessingEvents()Returns a flag indicating whether or not the runtime should publish events when asked to do so.
- Returns:
true
if events should be published, otherwisefalse
-
isProjectStage
Return
true
if the currentProjectStage
as returned by theApplication
instance is equal tostage
, otherwise returnfalse
- Parameters:
stage
- theProjectStage
to check- Returns:
- boolean indicating whether the application has the same stage.
- Throws:
IllegalStateException
- if this method is called after this instance has been releasedNullPointerException
- ifstage
isnull
-
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.- Returns:
- the instance of
FacesContext
.
-
setCurrentInstance
Set the
FacesContext
instance for the request that is being processed by the current thread.- Parameters:
context
- TheFacesContext
instance for the current thread, ornull
if this thread no longer has aFacesContext
instance.
-