javax.faces.component

Class UIViewRoot

java.lang.Object

javax.faces.component.UIComponent

javax.faces.component.UIComponentBase

javax.faces.component.UIViewRoot

All Implemented Interfaces:

EventListener, PartialStateHolder, StateHolder, TransientStateHolder, UniqueIdVendor, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder

@JSFComponent(name="f:view",
              bodyContent="JSP",
              tagClass="org.apache.myfaces.taglib.core.ViewTag")
 @JSFJspProperty(name="binding",
                returnType="java.lang.String",
                tagExcluded=true)
public class UIViewRoot
extends UIComponentBase
implements UniqueIdVendor

Creates a JSF View, which is a container that holds all of the components that are part of the view.

Unless otherwise specified, all attributes accept static values or EL expressions.

See the javadoc for this class in the JSF Specification for further details.

Field Summary

Fields

Modifier and Type	Field and Description
static String	COMPONENT_FAMILY
static String	COMPONENT_TYPE
static String	METADATA_FACET_NAME
static String	UNIQUE_ID_PREFIX
static String	VIEW_PARAMETERS_KEY
static String	VIEWROOT_PHASE_LISTENER_QUEUES_EXCEPTIONS_PARAM_NAME

Fields inherited from class javax.faces.component.UIComponent

ATTRS_WITH_DECLARED_DEFAULT_VALUES, BEANINFO_KEY, bindings, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, CURRENT_COMPONENT, CURRENT_COMPOSITE_COMPONENT, FACETS_KEY, HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME, VIEW_LOCATION_KEY

Constructor Summary

Constructors

Constructor and Description
UIViewRoot() Construct an instance of the UIViewRoot.

Method Summary

Modifier and Type	Method and Description
void	addComponentResource(FacesContext context, UIComponent componentResource)
void	addComponentResource(FacesContext context, UIComponent componentResource, String target)
void	addPhaseListener(PhaseListener phaseListener) Adds a The phaseListeners attached to ViewRoot.
void	broadcastEvents(FacesContext context, PhaseId phaseId)
String	createUniqueId() Provides a unique id for this component instance.
String	createUniqueId(FacesContext context, String seed)
void	encodeBegin(FacesContext context)
void	encodeChildren(FacesContext context)
void	encodeEnd(FacesContext context)
javax.el.MethodExpression	getAfterPhaseListener() MethodBinding pointing to a method that takes a javax.faces.event.PhaseEvent and returns void, called after every phase except for restore view.
Map<String,Object>	getAttributes() Get a map through which all the UIComponent's properties, value-bindings and non-property attributes can be read and written.
javax.el.MethodExpression	getBeforePhaseListener() MethodBinding pointing to a method that takes a javax.faces.event.PhaseEvent and returns void, called before every phase except for restore view.
List<UIComponent>	getComponentResources(FacesContext context)
List<UIComponent>	getComponentResources(FacesContext context, String target)
String	getFamily()
Locale	getLocale() The locale for this view.
List<PhaseListener>	getPhaseListeners()
String	getRenderKitId() Defines what renderkit should be used to render this view.
boolean	getRendersChildren() Indicates whether this component or its renderer manages the invocation of the rendering methods of its child components.
String	getViewId() A unique identifier for the "template" from which this view was generated.
List<SystemEventListener>	getViewListenersForEventClass(Class<? extends SystemEvent> systemEvent)
Map<String,Object>	getViewMap()
Map<String,Object>	getViewMap(boolean create)
boolean	isInView() Indicate if this component is inside a view, or in other words is contained by an UIViewRoot instance (which represents the view).
void	processApplication(FacesContext context)
void	processDecodes(FacesContext context)
void	processRestoreState(FacesContext context, Object state)
void	processUpdates(FacesContext context) This isn't an input component, so just pass on the processUpdates call to child components and facets that might be input components.
void	processValidators(FacesContext context)
void	queueEvent(FacesEvent event)
void	removeComponentResource(FacesContext context, UIComponent componentResource)
void	removeComponentResource(FacesContext context, UIComponent componentResource, String target)
void	removePhaseListener(PhaseListener phaseListener) Removes a The phaseListeners attached to ViewRoot.
void	resetValues(FacesContext context, Collection<String> clientIds)
void	restoreState(FacesContext facesContext, Object state) Invoked in the "restore view" phase, this initialises this object's members from the values saved previously into the provided state object.
void	restoreViewScopeState(FacesContext facesContext, Object state)
Object	saveState(FacesContext facesContext) Invoked after the render phase has completed, this method returns an object which can be passed to the restoreState of some other instance of UIComponentBase to reset that object's state to the same values as this object currently has.
void	setAfterPhaseListener(javax.el.MethodExpression afterPhaseListener) Sets
void	setBeforePhaseListener(javax.el.MethodExpression beforePhaseListener) Sets
void	setId(String id) Set an identifier for this component which is unique within the scope of the nearest ancestor NamingContainer component.
void	setInView(boolean isInView) Define if the component is on the view or not.
void	setLocale(Locale locale)
void	setRendered(boolean state) DO NOT USE.
void	setRenderKitId(String renderKitId)
void	setViewId(String viewId)
void	subscribeToViewEvent(Class<? extends SystemEvent> systemEvent, SystemEventListener listener)
void	unsubscribeFromViewEvent(Class<? extends SystemEvent> systemEvent, SystemEventListener listener)

Methods inherited from class javax.faces.component.UIComponentBase

addClientBehavior, addFacesListener, broadcast, clearInitialState, decode, encodeAll, findComponent, getChildCount, getChildren, getClientBehaviors, getClientId, getDefaultEventName, getEventNames, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getParent, getPassThroughAttributes, getRenderer, getRendererType, getValueBinding, invokeOnComponent, isRendered, isTransient, markInitialState, processSaveState, removeFacesListener, restoreAttachedState, saveAttachedState, setParent, setRendererType, setTransient, setValueBinding, visitTree

Methods inherited from class javax.faces.component.UIComponent

getClientId, getCompositeComponentParent, getContainerClientId, getCurrentComponent, getCurrentCompositeComponent, getListenersForEventClass, getNamingContainer, getPassThroughAttributes, getResourceBundleMap, getStateHelper, getStateHelper, getTransientStateHelper, getTransientStateHelper, getValueExpression, initialStateMarked, isCompositeComponent, isVisitable, popComponentFromEL, processEvent, pushComponentToEL, restoreTransientState, saveTransientState, setValueExpression, subscribeToEvent, unsubscribeFromEvent

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

COMPONENT_FAMILY

public static final String COMPONENT_FAMILY

See Also:

Constant Field Values

COMPONENT_TYPE

public static final String COMPONENT_TYPE

See Also:

Constant Field Values

METADATA_FACET_NAME

public static final String METADATA_FACET_NAME

See Also:

Constant Field Values

UNIQUE_ID_PREFIX

public static final String UNIQUE_ID_PREFIX

See Also:

Constant Field Values

VIEW_PARAMETERS_KEY

public static final String VIEW_PARAMETERS_KEY

See Also:

Constant Field Values

VIEWROOT_PHASE_LISTENER_QUEUES_EXCEPTIONS_PARAM_NAME

@JSFWebConfigParam(defaultValue="false",
                   expectedValues="true, false",
                   since="2.3")
public static final String VIEWROOT_PHASE_LISTENER_QUEUES_EXCEPTIONS_PARAM_NAME

Since:

2.3

See Also:

Constant Field Values

Constructor Detail

UIViewRoot

public UIViewRoot()

Construct an instance of the UIViewRoot.

Method Detail

addComponentResource

public void addComponentResource(FacesContext context,
                                 UIComponent componentResource)

Since:

2.0

addComponentResource

public void addComponentResource(FacesContext context,
                                 UIComponent componentResource,
                                 String target)

Since:

2.0

addPhaseListener

public void addPhaseListener(PhaseListener phaseListener)

Adds a The phaseListeners attached to ViewRoot.

broadcastEvents

public void broadcastEvents(FacesContext context,
                            PhaseId phaseId)

Since:

2.0

createUniqueId

public String createUniqueId()

Provides a unique id for this component instance.

createUniqueId

public String createUniqueId(FacesContext context,
                             String seed)

Specified by:

createUniqueId in interface UniqueIdVendor

Since:

2.0

encodeBegin

public void encodeBegin(FacesContext context)
                 throws IOException

Overrides:

encodeBegin in class UIComponentBase

Throws:

IOException

encodeChildren

public void encodeChildren(FacesContext context)
                    throws IOException

Overrides:

encodeChildren in class UIComponentBase

Throws:

IOException

Since:

2.0

encodeEnd

public void encodeEnd(FacesContext context)
               throws IOException

Overrides:

encodeEnd in class UIComponentBase

Throws:

IOException

getAfterPhaseListener

@JSFProperty(returnSignature="void",
             methodSignature="javax.faces.event.PhaseEvent",
             jspName="afterPhase",
             stateHolder=true)
public javax.el.MethodExpression getAfterPhaseListener()

MethodBinding pointing to a method that takes a javax.faces.event.PhaseEvent and returns void, called after every phase except for restore view.

Returns:

the new afterPhaseListener value

getBeforePhaseListener

@JSFProperty(returnSignature="void",
             methodSignature="javax.faces.event.PhaseEvent",
             jspName="beforePhase",
             stateHolder=true)
public javax.el.MethodExpression getBeforePhaseListener()

MethodBinding pointing to a method that takes a javax.faces.event.PhaseEvent and returns void, called before every phase except for restore view.

Returns:

the new beforePhaseListener value

getComponentResources

public List<UIComponent> getComponentResources(FacesContext context,
                                               String target)

Since:

2.0

getComponentResources

public List<UIComponent> getComponentResources(FacesContext context)

Parameters:

context -

Returns:

Since:

2.3

getFamily

public String getFamily()

Specified by:

getFamily in class UIComponent

getLocale

@JSFProperty
public Locale getLocale()

The locale for this view.

Defaults to the default locale specified in the faces configuration file.

getPhaseListeners

public List<PhaseListener> getPhaseListeners()

Since:

2.0

getRenderKitId

@JSFProperty
public String getRenderKitId()

Defines what renderkit should be used to render this view.

getRendersChildren

public boolean getRendersChildren()

Description copied from class: UIComponentBase

Indicates whether this component or its renderer manages the invocation of the rendering methods of its child components. When this is true:

• This component's encodeBegin method will only be called after all the child components have been created and added to this component.
• This component's encodeChildren method will be called after its encodeBegin method. Components for which this method returns false do not get this method invoked at all.
• No rendering methods will be called automatically on child components; this component is required to invoke the encodeBegin/encodeEnd/etc on them itself.

Overrides:

getRendersChildren in class UIComponentBase

Since:

2.0

getViewId

@JSFProperty(tagExcluded=true)
public String getViewId()

A unique identifier for the "template" from which this view was generated.

Typically this is the filesystem path to the template file, but the exact details are the responsibility of the current ViewHandler implementation.

getViewMap

public Map<String,Object> getViewMap()

Since:

2.0

getViewMap

public Map<String,Object> getViewMap(boolean create)

Since:

2.0

isInView

public boolean isInView()

Indicate if this component is inside a view, or in other words is contained by an UIViewRoot instance (which represents the view). If this component is a UIViewRoot instance, the components "always" is on the view. By default it is false but for UIViewRoot instances is true.

Overrides:

isInView in class UIComponent

Returns:

processApplication

public void processApplication(FacesContext context)

processDecodes

public void processDecodes(FacesContext context)

Overrides:

processDecodes in class UIComponentBase

processRestoreState

public void processRestoreState(FacesContext context,
                                Object state)

Overrides:

processRestoreState in class UIComponentBase

Since:

2.0

queueEvent

public void queueEvent(FacesEvent event)

Overrides:

queueEvent in class UIComponentBase

processValidators

public void processValidators(FacesContext context)

Overrides:

processValidators in class UIComponentBase

processUpdates

public void processUpdates(FacesContext context)

Description copied from class: UIComponentBase

This isn't an input component, so just pass on the processUpdates call to child components and facets that might be input components.

Components that were never rendered can't possibly be receiving update data (no corresponding fields were ever put into the response) so if this component is not rendered then this method does not invoke processUpdates on its children.

Overrides:

processUpdates in class UIComponentBase

setLocale

public void setLocale(Locale locale)

setRenderKitId

public void setRenderKitId(String renderKitId)

setRendered

@JSFProperty(tagExcluded=true)
public void setRendered(boolean state)

DO NOT USE.

This inherited property is disabled. Although this class extends a base-class that defines a read/write rendered property, this particular subclass does not support setting it. Yes, this is broken OO design: direct all complaints to the JSF spec group.

Overrides:

setRendered in class UIComponentBase

setId

@JSFProperty(tagExcluded=true)
public void setId(String id)

Description copied from class: UIComponentBase

Set an identifier for this component which is unique within the scope of the nearest ancestor NamingContainer component. The id is not necessarily unique across all components in the current view.

The id must start with an underscore if it is generated by the JSF framework, and must not start with an underscore if it has been specified by the user (eg in a JSP tag).

The first character of the id must be an underscore or letter. Following characters may be letters, digits, underscores or dashes.

Null is allowed as a parameter, and will reset the id to null.

The clientId of this component is reset by this method; see getClientId for more info.

Overrides:

setId in class UIComponentBase

setInView

public void setInView(boolean isInView)

Define if the component is on the view or not.

This value is set in the following conditions:

• Component / Facet added: if the parent isInView = true, set it to true and all their children or facets, otherwise take no action
• Component / Facet removed: if the parent isInView = false, set it to false and all their children or facets, otherwise take no action

Overrides:

setInView in class UIComponent

removeComponentResource

public void removeComponentResource(FacesContext context,
                                    UIComponent componentResource)

removeComponentResource

public void removeComponentResource(FacesContext context,
                                    UIComponent componentResource,
                                    String target)

setViewId

public void setViewId(String viewId)

removePhaseListener

public void removePhaseListener(PhaseListener phaseListener)

Removes a The phaseListeners attached to ViewRoot.

setBeforePhaseListener

public void setBeforePhaseListener(javax.el.MethodExpression beforePhaseListener)

Sets

Parameters:

beforePhaseListener - the new beforePhaseListener value

setAfterPhaseListener

public void setAfterPhaseListener(javax.el.MethodExpression afterPhaseListener)

Sets

Parameters:

afterPhaseListener - the new afterPhaseListener value

getAttributes

public Map<String,Object> getAttributes()

Description copied from class: UIComponentBase

Get a map through which all the UIComponent's properties, value-bindings and non-property attributes can be read and written.

When writing to the returned map:

• If this component has an explicit property for the specified key then the setter method is called. An IllegalArgumentException is thrown if the property is read-only. If the property is readable then the old value is returned, otherwise null is returned.
• Otherwise the key/value pair is stored in a map associated with the component.

Note that value-bindings are not written by put calls to this map. Writing to the attributes map using a key for which a value-binding exists will just store the value in the attributes map rather than evaluating the binding, effectively "hiding" the value-binding from later attributes.get calls. Setter methods on components commonly do not evaluate a binding of the same name; they just store the provided value directly on the component.

When reading from the returned map:

• If this component has an explicit property for the specified key then the getter method is called. If the property exists, but is read-only (ie only a setter method is defined) then an IllegalArgumentException is thrown.
• If the attribute map associated with the component has an entry with the specified key, then that is returned.
• If this component has a value-binding for the specified key, then the value-binding is evaluated to fetch the value.
• Otherwise, null is returned.

Note that components commonly define getter methods such that they evaluate a value-binding of the same name if there isn't yet a local property.

Assigning values to the map which are not explicit properties on the underlying component can be used to "tunnel" attributes from the JSP tag (or view-specific equivalent) to the associated renderer without modifying the component itself.

Any value-bindings and non-property attributes stored in this map are automatically serialized along with the component when the view is serialized.

Overrides:

getAttributes in class UIComponentBase

resetValues

public void resetValues(FacesContext context,
                        Collection<String> clientIds)

Parameters:

context -

clientIds -

Since:

2.2

saveState

public Object saveState(FacesContext facesContext)

Description copied from class: UIComponentBase

Invoked after the render phase has completed, this method returns an object which can be passed to the restoreState of some other instance of UIComponentBase to reset that object's state to the same values as this object currently has.

Specified by:

saveState in interface StateHolder

Overrides:

saveState in class UIComponentBase

restoreState

public void restoreState(FacesContext facesContext,
                         Object state)

Description copied from class: UIComponentBase

Invoked in the "restore view" phase, this initialises this object's members from the values saved previously into the provided state object.

Specified by:

restoreState in interface StateHolder

Overrides:

restoreState in class UIComponentBase

state - is an object previously returned by the saveState method of this class.

restoreViewScopeState

public void restoreViewScopeState(FacesContext facesContext,
                                  Object state)

Parameters:

facesContext -

state -

Since:

2.2

getViewListenersForEventClass

public List<SystemEventListener> getViewListenersForEventClass(Class<? extends SystemEvent> systemEvent)

subscribeToViewEvent

public void subscribeToViewEvent(Class<? extends SystemEvent> systemEvent,
                                 SystemEventListener listener)

unsubscribeFromViewEvent

public void unsubscribeFromViewEvent(Class<? extends SystemEvent> systemEvent,
                                     SystemEventListener listener)