Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.faces.context
Class FacesContext

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

Direct Known Subclasses:
  FacesContextWrapper

    public abstract class FacesContext

extends java.lang.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
`FacesContext()`

Method Summary
`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 `Map` representing the attributes associated wth this `FacesContext` instance.
`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 `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.
`javax.el.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`.
`java.util.List<FacesMessage>` | `getMessageList()` Like `getMessages()`, but returns a `List<FacesMessage>`, enabling use from EL expressions.
`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`.
`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`).
`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.
`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.
`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:
    `java.lang.IllegalStateException` - if this method is called after this instance has been released

### getAttributes

    public 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 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:
    `java.lang.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:
    `java.lang.IllegalStateException` - if this method is called after this instance has been released
  Since:
    2.0

### getClientIdsWithMessages

    public 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, javax.faces.application.FacesMessage)`.

  Throws:
    `java.lang.IllegalStateException` - if this method is called after this instance has been released

### getELContext

    public javax.el.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:
    `java.lang.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:
    `java.lang.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 `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`.

  Throws:
    `java.lang.IllegalStateException` - if this method is called after this instance has been released

### getMessages

    public 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, javax.faces.application.FacesMessage)`.

  Throws:
    `java.lang.IllegalStateException` - if this method is called after this instance has been released

### getMessageList

    public java.util.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:
    `java.lang.IllegalStateException` - if this method is called after this instance has been released
  Since:
    2.0

### getMessageList

    public 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.

  Returns:
    an immutable `List` which is effectively a snapshot of the messages present at the time of invocation.
  Throws:
    `java.lang.IllegalStateException` - if this method is called after this instance has been released
  Since:
    2.0

### getMessages

    public 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, 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:
    `java.lang.IllegalStateException` - if this method is called after this instance has been released

### 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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.NullPointerException` - if `responseStream` is `null`
    `java.lang.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:
    `java.lang.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:
    `java.lang.IllegalStateException` - if this method is called after this instance has been released
    `java.lang.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:
    `java.lang.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:
    `java.lang.IllegalStateException` - if this method is called after this instance has been released
    `java.lang.NullPointerException` - if `root` is `null`

### addMessage

    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.

  Parameters:
    `clientId` - The client identifier with which this message is associated (if any)
    `message` - The message to be appended
  Throws:
    `java.lang.IllegalStateException` - if this method is called after this instance has been released
    `java.lang.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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.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:
    `java.lang.IllegalStateException` - if this method is called after this instance has been released
    `java.lang.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.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright 2002-2010 Oracle America Inc, Inc. All Rights Reserved.