FacesContext (Java(TM) EE 7 Specification APIs)

java.lang.Object
- javax.faces.context.FacesContext

Direct Known Subclasses:

FacesContextWrapper
```
public abstract class FacesContext
extends Object
```
FacesContext contains all of the per-request state information related to the processing of a single JavaServer 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 servlet container executing this web application utilizes for the processing of this request.

Constructor Summary

Constructors
Constructor and Description

FacesContext()

Constructors
Constructor and Description
`FacesContext()`

Method Summary

Methods
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 `Map` representing the attributes associated wth this `FacesContext` instance.
`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 `FacesContext` instance for the request that is being processed by the current thread.
`PhaseId`	`getCurrentPhaseId()` Return the value last set on this `FacesContext` instance when `setCurrentPhaseId(javax.faces.event.PhaseId)` was called.
`ELContext`	`getELContext()` Return the `ELContext` instance for this `FacesContext` instance.
`ExceptionHandler`	`getExceptionHandler()` Return the `ExceptionHandler` for this request.
`abstract ExternalContext`	`getExternalContext()` Return the `ExternalContext` instance for this `FacesContext` instance.
`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`.
`List<FacesMessage>`	`getMessageList()` Like `getMessages()`, but returns a `List<FacesMessage>`, enabling use from EL expressions.
`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`.
`abstract 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 Iterator<FacesMessage>`	`getMessages(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 `UINamingContainer.getSeparatorChar(javax.faces.context.FacesContext)`, passing `this` as the argument.
`PartialViewContext`	`getPartialViewContext()` Return the `PartialViewContext` for this request.
`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 `ResponseStateManager.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)` Return `true` if the current `ProjectStage` as returned by the `Application` instance is equal to `stage`, otherwise return `false`
`boolean`	`isReleased()` Return a flag indicating if the resources associated with this `FacesContext` instance have been released.
`boolean`	`isValidationFailed()` Return `true` if the `validationFailed()` method has been called for the current request.
`abstract void`	`release()` Release any resources associated with this `FacesContext` instance.
`abstract void`	`renderResponse()` Signal the JavaServer 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 JavaServer 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 `ExceptionHandler` for this request.
`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.
`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.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - FacesContext
```
public FacesContext()
```
- Method Detail
  - getApplication
```
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.
    
    Throws:
    
    IllegalStateException - if this method is called after this instance has been released
  - getAttributes
```
public 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 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.
    
    Throws:
    
    IllegalStateException - if this method is called after this instance has been released
    Since:
    
    2.0
  - getPartialViewContext
```
public 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.
    
    Throws:
    
    IllegalStateException - if this method is called after this instance has been released
    Since:
    
    2.0
  - getClientIdsWithMessages
```
public 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).
    
    Throws:
    
    IllegalStateException - if this method is called after this instance has been released
  - getELContext
```
public 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.
    Throws:
    
    IllegalStateException - if this method is called after this instance has been released
    Since:
    
    1.2
  - getExceptionHandler
```
public ExceptionHandler getExceptionHandler()
```
    Return the ExceptionHandler for this request.
  - setExceptionHandler
```
public void setExceptionHandler(ExceptionHandler exceptionHandler)
```
    Set the ExceptionHandler for this request.
    
    Parameters:
    exceptionHandler - the ExceptionHandler for this request.
  - getExternalContext
```
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.
    
    Throws:
    
    IllegalStateException - if this method is called after this instance has been released
  - getMaximumSeverity
```
public 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.
    
    Throws:
    
    IllegalStateException - if this method is called after this instance has been released
  - getMessages
```
public 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).
    
    Throws:
    
    IllegalStateException - if this method is called after this instance has been released
  - getMessageList
```
public List<FacesMessage> getMessageList()
```
    Like getMessages(), but returns a List<FacesMessage>, enabling use from EL 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
```
public 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.
    
    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
```
public 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).
    
    Parameters:
    clientId - The client identifier for which messages are requested, or null for messages not associated with any client identifier
    
    Throws:
    
    IllegalStateException - if this method is called after this instance has been released
  - getNamingContainerSeparatorChar
```
public 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 EL expression #{facesContext.namingContainerSeparatorChar}.
  - getRenderKit
```
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.
    
    Throws:
    
    IllegalStateException - if this method is called after this instance has been released
  - getRenderResponse
```
public abstract boolean getRenderResponse()
```
    Return true if the renderResponse() method has been called for the current request.
    
    Throws:
    
    IllegalStateException - if this method is called after this instance has been released
  - getResponseComplete
```
public abstract boolean getResponseComplete()
```
    Return true if the responseComplete() method has been called for the current request.
    
    Throws:
    
    IllegalStateException - if this method is called after this instance has been released
  - getResourceLibraryContracts
```
public 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.
    
    Throws:
    
    IllegalStateException - if this method is called after this instance has been released
    Since:
    
    2.2
  - setResourceLibraryContracts
```
public 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.
    
    Parameters:
    contracts - The new contracts to be returned, as an immutable List. from a subsequent call to getResourceLibraryContracts().
    
    Throws:
    
    IllegalStateException - if this method is called after this instance has been released
  - isValidationFailed
```
public boolean isValidationFailed()
```
    Return true 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
```
public 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.
    
    Throws:
    
    IllegalStateException - if this method is called after this instance has been released
  - setResponseStream
```
public abstract void setResponseStream(ResponseStream responseStream)
```
    Set the ResponseStream to which components should direct their binary output.
    
    Parameters:
    responseStream - The new ResponseStream for this response
    
    Throws:
    
    NullPointerException - if responseStream is null
    
    IllegalStateException - if this method is called after this instance has been released
  - getResponseWriter
```
public 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.
    
    Throws:
    
    IllegalStateException - if this method is called after this instance has been released
  - setResponseWriter
```
public abstract void setResponseWriter(ResponseWriter responseWriter)
```
    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 released
    
    NullPointerException - if responseWriter is null
  - getViewRoot
```
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().
    
    Throws:
    
    IllegalStateException - if this method is called after this instance has been released
  - setViewRoot
```
public 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().
    
    Parameters:
    root - The new component UIViewRoot component
    
    Throws:
    
    IllegalStateException - if this method is called after this instance has been released
    
    NullPointerException - if root is null
  - addMessage
```
public 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.
    
    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 released
    
    NullPointerException - if message is null
  - 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 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.
    
    Throws:
    
    IllegalStateException - if this method is called after this instance has been released
  - renderResponse
```
public abstract void renderResponse()
```
    Signal the JavaServer 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.
    
    Throws:
    
    IllegalStateException - if this method is called after this instance has been released
    Since:
    
    2.0
  - responseComplete
```
public abstract void responseComplete()
```
    Signal the JavaServer 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
```
public PhaseId getCurrentPhaseId()
```
    Return the value last set on this FacesContext instance when setCurrentPhaseId(javax.faces.event.PhaseId) was called.
    
    Throws:
    
    IllegalStateException - if this method is called after this instance has been released
    Since:
    
    2.0
  - setCurrentPhaseId
```
public 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.
    
    Parameters:
    currentPhaseId - The PhaseId 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) or Application.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, otherwise false
  - isProjectStage
```
public boolean isProjectStage(ProjectStage stage)
```
    Return true if the current ProjectStage as returned by the Application instance is equal to stage, otherwise return false
    
    Parameters:
    stage - the ProjectStage to check
    
    Throws:
    
    IllegalStateException - if this method is called after this instance has been released
    
    NullPointerException - if stage is null
  - getCurrentInstance
```
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.
  - setCurrentInstance
```
protected static void setCurrentInstance(FacesContext context)
```
    Set the FacesContext instance for the request that is being processed by the current thread.
    
    Parameters:
    context - The FacesContext instance for the current thread, or null if this thread no longer has a FacesContext instance.

Class FacesContext

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

FacesContext

Method Detail

getApplication

getAttributes

getPartialViewContext

getClientIdsWithMessages

getELContext

getExceptionHandler

setExceptionHandler

getExternalContext

getMaximumSeverity

getMessages

getMessageList

getMessageList

getMessages

getNamingContainerSeparatorChar

getRenderKit

getRenderResponse

getResponseComplete

getResourceLibraryContracts

setResourceLibraryContracts

isValidationFailed

getResponseStream

setResponseStream

getResponseWriter

setResponseWriter

getViewRoot

setViewRoot

addMessage

isReleased

release

renderResponse

isPostback

responseComplete

validationFailed

getCurrentPhaseId

setCurrentPhaseId

setProcessingEvents

isProcessingEvents

isProjectStage

getCurrentInstance

setCurrentInstance