javax.faces.context
Class FacesContext

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

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	addFacesEvent(FacesEvent event) Append a FacesEvent to the set of events that should be processed at the end of the current phase of the request processing lifecycle.
abstract void	addMessage(UIComponent component, Message message) Append a Message to the set of messages associated with the specified UIComponent, if component is not null.
static FacesContext	getCurrentInstance() Return the FacesContext instance for the request that is being processed by the current thread.
abstract ExternalContext	getExternalContext()
abstract java.util.Iterator	getFacesEvents() Return an Iterator over the FacesEvents that have been queued, in the order that they were queued.
abstract java.util.Locale	getLocale() Return the Locale to be used in localizing the response being created for this FacesContext.
abstract int	getMaximumSeverity() Return the maximum severity level recorded on any Messages that has been queued, whether or not they are associated with any specific UIComponent.
abstract java.util.Iterator	getMessages() Return an Iterator over the Messages that have been queued, whether or not they are associated with any specific UIComponent.
abstract java.util.Iterator	getMessages(UIComponent component) Return an Iterator over the Messages that have been queued that are associated with the specified UIComponent, (if component is not null), or over the Messages that have been queued that are not associated with any specific UIComponent (if component is null).
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 Tree	getTree() Return the component Tree that is associated with the this request.
abstract void	release() Release any resources associated with this FacesContext instance.
abstract void	renderResponse() Signal the JavaSerer 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.
abstract void	setLocale(java.util.Locale locale) Set the Locale to be used in localizing the response being created for this FacesContext.
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	setTree(Tree tree) Set the component Tree that is associated with this request.

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

getFacesEvents

public abstract java.util.Iterator getFacesEvents()

Return an Iterator over the FacesEvents that have been queued, in the order that they were queued. The Iterator returned by this method must support the following functionality:

• The remove() operation may be utilized by the JSF implementation to remove the current event when it has been completely handled.
• Event handlers may add new events to the list while it is being iterated over, by calling addFacesEvent().

If no events have been queued, an empty Iterator must be returned.

getLocale

public abstract java.util.Locale getLocale()

Return the Locale to be used in localizing the response being created for this FacesContext.

setLocale

public abstract void setLocale(java.util.Locale locale)

Set the Locale to be used in localizing the response being created for this FacesContext. If not set, the default Locale for our servlet container will be used.

Parameters:

locale - The new localization Locale

getMaximumSeverity

public abstract int getMaximumSeverity()

Return the maximum severity level recorded on any Messages that has been queued, whether or not they are associated with any specific UIComponent. If no such messages have been queued, return a value less than Message.SEVERITY_INFO.

getMessages

public abstract java.util.Iterator getMessages()

Return an Iterator over the Messages that have been queued, whether or not they are associated with any specific UIComponent. If no such messages have been queued, return an empty Iterator.

getMessages

public abstract java.util.Iterator getMessages(UIComponent component)

Return an Iterator over the Messages that have been queued that are associated with the specified UIComponent, (if component is not null), or over the Messages that have been queued that are not associated with any specific UIComponent (if component is null). If no such messages have been queued, return an empty Iterator.

Parameters:

component - The UIComponent for which messages are requested, or null for messages not associated with any component

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.

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

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.

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.NullPointerException - if responseWriter is null

getTree

public abstract Tree getTree()

Return the component Tree that is associated with the this request.

setTree

public abstract void setTree(Tree tree)

Set the component Tree that is associated with this request. This method can only be called by the application handler (or a class that the handler calls), and only during the Invoke Application phase of the request processing lifecycle.

Parameters:

tree - The new component tree

Throws:

java.lang.IllegalStateException - if this method is called more than once without a call to release() in beween

java.lang.NullPointerException - if tree is null

addFacesEvent

public abstract void addFacesEvent(FacesEvent event)

Append a FacesEvent to the set of events that should be processed at the end of the current phase of the request processing lifecycle.

Parameters:

event - The event to be queued

Throws:

java.lang.NullPointerException - if event is null

addMessage

public abstract void addMessage(UIComponent component,
                                Message message)

Append a Message to the set of messages associated with the specified UIComponent, if component is not null. If component is null, this Message is assumed to not be associated with any specific component instance.

Parameters:

component - The component with which this message is associated (if any)

message - The message to be appended

Throws:

java.lang.NullPointerException - if message is null

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.

renderResponse

public abstract void renderResponse()

Signal the JavaSerer 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.

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.

getExternalContext

public abstract ExternalContext getExternalContext()

getCurrentInstance

public static FacesContext getCurrentInstance()

Return the FacesContext instance for the request that is being processed by the current thread.

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