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 and Description | 
|---|
FacesContext()  | 
| Modifier and Type | Method and Description | 
|---|---|
abstract void | 
addMessage(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. | 
Map<Object,Object> | 
getAttributes()
Return a mutable   | 
abstract Iterator<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
  
FacesMessages that has been queued, whether or not they are
 associated with any specific UIComponent. | 
List<FacesMessage> | 
getMessageList()
Like   | 
List<FacesMessage> | 
getMessageList(String clientId)
Like   | 
abstract Iterator<FacesMessage> | 
getMessages()
Return an  
Iterator over the FacesMessages
 that have been queued, whether or not they are associated with any
 specific client identifier. | 
abstract Iterator<FacesMessage> | 
getMessages(String clientId)
Return an  
Iterator over the FacesMessages that
 have been queued that are associated with the specified client identifier
 (if clientId is not null), or over the
 FacesMessages 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. | 
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()
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(List<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.IllegalStateException - if this method is called after
  this instance has been releasedpublic Map<Object,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.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.IllegalStateException - if this method is called after
  this instance has been releasedpublic abstract Iterator<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, javax.faces.application.FacesMessage).
Iterator over the client identifiers for
        which at least one FacesMessage has been queued.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(javax.el.ELContextEvent) method.
ELContext.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.
ExternalContextIllegalStateException - if this method is called after
  this instance has been releasedpublic abstract FacesMessage.Severity getMaximumSeverity()
Return the maximum severity level recorded on any
 FacesMessages that has been queued, whether or not they are
 associated with any specific UIComponent.  If no such messages
 have been queued, return null.
IllegalStateException - if this method is called after
  this instance has been releasedpublic abstract Iterator<FacesMessage> getMessages()
Return an Iterator over the FacesMessages
 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, javax.faces.application.FacesMessage).
Iterator over the FacesMessages
                that have been queued.IllegalStateException - if this method is called after
  this instance has been releasedpublic 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.IllegalStateException - if this method is called after
  this instance has been releasedpublic List<FacesMessage> getMessageList(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.IllegalStateException - if this method is called after
  this instance has been releasedpublic abstract Iterator<FacesMessage> getMessages(String clientId)
Return an Iterator over the FacesMessages that
 have been queued that are associated with the specified client identifier
 (if clientId is not null), or over the
 FacesMessages 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, javax.faces.application.FacesMessage).
clientId - The client identifier for which messages are
  requested, or null for messages not associated with
  any client identifierIterator over the FacesMessages.IllegalStateException - if this method is called after
  this instance has been releasedpublic char getNamingContainerSeparatorChar()
Return the result of calling UINamingContainer.getSeparatorChar(javax.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.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.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.IllegalStateException - if this method is called after
  this instance has been releasedpublic 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. 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.
IllegalStateException - if this method is called after
  this instance has been releasedpublic void setResourceLibraryContracts(List<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(javax.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().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 requestIllegalStateException - 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.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 responseNullPointerException - if responseStream
  is nullIllegalStateException - 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.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 responseIllegalStateException - if this method is called after
  this instance has been releasedNullPointerException - if responseWriter
  is nullpublic 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.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 componentIllegalStateException - if this method is called after
  this instance has been releasedNullPointerException - if root
  is nullpublic abstract void addMessage(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 appendedIllegalStateException - if this method is called after
  this instance has been releasedNullPointerException - if message
  is nullpublic 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(javax.faces.context.FacesContext)
 passing null to remove the association between this
 thread and this dead FacesContext instance.
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.
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.
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.
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().
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(javax.faces.event.PhaseId)
 was called.
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.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
  falsepublic 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 checkIllegalStateException - if this method is called after
  this instance has been releasedNullPointerException - if stage is nullpublic 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.Copyright © 2019 Eclipse Foundation.
Use is subject to license terms.