Package jakarta.faces.component

Class UIViewRoot

java.lang.Object

jakarta.faces.component.UIComponent

jakarta.faces.component.UIComponentBase

jakarta.faces.component.UIViewRoot

All Implemented Interfaces:

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

public class UIViewRoot
extends UIComponentBase
implements UniqueIdVendor

UIViewRoot is the UIComponent that represents the root of the UIComponent tree. This component renders markup as the response to Ajax requests. It also serves as the root of the component tree, and as a place to hang per-view PhaseListeners.

For each of the following lifecycle phase methods:

• processDecodes(jakarta.faces.context.FacesContext)

• processValidators(jakarta.faces.context.FacesContext)

• processUpdates(jakarta.faces.context.FacesContext)

• processApplication(jakarta.faces.context.FacesContext)

• RenderResponse, via encodeBegin(jakarta.faces.context.FacesContext) and encodeEnd(jakarta.faces.context.FacesContext)

Take the following action regarding PhaseListeners.

Initialize a state flag to false.

If getBeforePhaseListener() returns non-null, invoke the listener, passing in the correct corresponding PhaseId for this phase.

Upon return from the listener, call FacesContext.getResponseComplete() and FacesContext.getRenderResponse(). If either return true set the internal state flag to true.

If or one or more listeners have been added by a call to addPhaseListener(jakarta.faces.event.PhaseListener), invoke the beforePhase method on each one whose PhaseListener.getPhaseId() matches the current phaseId, passing in the same PhaseId as in the previous step.

Upon return from each listener, call FacesContext.getResponseComplete() and FacesContext.getRenderResponse(). If either return true set the internal state flag to true.

Execute any processing for this phase if the internal state flag was not set.

If getAfterPhaseListener() returns non-null, invoke the listener, passing in the correct corresponding PhaseId for this phase.

If or one or more listeners have been added by a call to addPhaseListener(jakarta.faces.event.PhaseListener), invoke the afterPhase method on each one whose PhaseListener.getPhaseId() matches the current phaseId, passing in the same PhaseId as in the previous step.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	COMPONENT_FAMILY	The standard component family for this component.
static final String	COMPONENT_TYPE	The standard component type for this component.
static final String	METADATA_FACET_NAME
static final String	UNIQUE_ID_PREFIX	The prefix that will be used for identifiers generated by the createUniqueId() method.
static final String	VIEW_PARAMETERS_KEY	The key in the value set of the view metadata BeanDescriptor, the value of which is a List<UIViewParameter.Reference>.
static final String	VIEWROOT_PHASE_LISTENER_QUEUES_EXCEPTIONS_PARAM_NAME	If this param is set, and calling toLowerCase().equals("true") on a String representation of its value returns true, exceptions thrown by PhaseListeners installed on the UIViewRoot are queued to the ExceptionHandler instead of being logged and swallowed.

Fields inherited from class jakarta.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	Description
UIViewRoot()	Create a new UIViewRoot instance with default property values.

Method Summary

Modifier and Type	Method	Description
void	addComponentResource(FacesContext context, UIComponent componentResource)	Add argument component, which is assumed to represent a resource instance, as a resource to this view.
void	addComponentResource(FacesContext context, UIComponent componentResource, String target)	Add argument component, which is assumed to represent a resource instance, as a resource to this view.
void	addPhaseListener(PhaseListener newPhaseListener)	Add the argument newPhaseListener to the list of PhaseListeners on this UIViewRoot.
void	broadcastEvents(FacesContext context, PhaseId phaseId)	Broadcast any events that have been queued.
String	createUniqueId()	Generate an identifier for a component.
String	createUniqueId(FacesContext context, String seed)	Generate an identifier for a component.
void	encodeBegin(FacesContext context)	Override the default UIComponentBase.encodeBegin(jakarta.faces.context.FacesContext) behavior.
void	encodeChildren(FacesContext context)	If PartialViewContext.isAjaxRequest() returns true, perform partial rendering by calling PartialViewContext.processPartial(jakarta.faces.event.PhaseId) with PhaseId.RENDER_RESPONSE.
void	encodeEnd(FacesContext context)	If getAfterPhaseListener() returns non-null, invoke it, passing a PhaseEvent for the PhaseId.RENDER_RESPONSE phase.
MethodExpression	getAfterPhaseListener()	Return the MethodExpression that will be invoked after this view is rendered.
MethodExpression	getBeforePhaseListener()	Return the MethodExpression that will be invoked before this view is rendered.
List<UIComponent>	getComponentResources(FacesContext context)	Return an unmodifiable ordered List of all UIComponent resources of all supported targets.
List<UIComponent>	getComponentResources(FacesContext context, String target)	Return an unmodifiable List of UIComponents for the provided target agrument.
String	getFamily()	Return the identifier of the component family to which this component belongs.
Locale	getLocale()	Return the Locale to be used in localizing the response being created for this view.
List<PhaseListener>	getPhaseListeners()	Return an unmodifiable list of the PhaseListener instances attached to this UIViewRoot instance.
String	getRenderKitId()	Return the render kit identifier of the RenderKit associated with this view.
boolean	getRendersChildren()	Call UIComponentBase.getRendersChildren() If PartialViewContext.isAjaxRequest() returns true this method must return true.
String	getViewId()	Return the view identifier for this view.
List<SystemEventListener>	getViewListenersForEventClass(Class<? extends SystemEvent> systemEvent)	Return the SystemEventListener instances registered on this UIComponent instance that are interested in events of type eventClass.
Map<String,Object>	getViewMap()	This implementation simply calls through to getViewMap(boolean), passing true as the argument, and returns the result.
Map<String,Object>	getViewMap(boolean create)	Returns a Map that acts as the interface to the data store that is the "view scope", or, if this instance does not have such a Map and the create argument is true, creates one and returns it.
boolean	isInView()	Override superclass method to always return true because a UIViewRoot is defined to always be in a view.
void	processApplication(FacesContext context)	Broadcast any events that have been queued for the Invoke Application phase of the request processing lifecycle and to clear out any events for later phases if the event processing for this phase caused FacesContext.renderResponse() or FacesContext.responseComplete() to be called.
void	processDecodes(FacesContext context)
void	processEvent(ComponentSystemEvent event)	If the argument event is an instance of PostRestoreStateEvent and PartialViewContext.isPartialRequest() returns true, then loop over all component resources and call ResourceHandler.markResourceRendered(FacesContext, String, String) for each of them.
void	processRestoreState(FacesContext context, Object state)	The default implementation must call UIComponentBase.processRestoreState(jakarta.faces.context.FacesContext, java.lang.Object) from within a try block.
void	processUpdates(FacesContext context)
void	processValidators(FacesContext context)
void	queueEvent(FacesEvent event)	Override the default UIComponentBase.queueEvent(jakarta.faces.event.FacesEvent) behavior to accumulate the queued events for later broadcasting.
void	removeComponentResource(FacesContext context, UIComponent componentResource)	Remove argument component, which is assumed to represent a resource instance, as a resource to this view.
void	removeComponentResource(FacesContext context, UIComponent componentResource, String target)	Remove argument component, which is assumed to represent a resource instance, as a resource to this view.
void	removePhaseListener(PhaseListener toRemove)	If the argument toRemove is in the list of PhaseListeners for this instance, it must be removed.
void	resetValues(FacesContext context, Collection<String> clientIds)	Visit the clientIds and, if the component is an instance of EditableValueHolder, call its EditableValueHolder.resetValue() method.
void	restoreState(FacesContext context, Object state)	Perform any processing required to restore the state from the entries in the state Object.
void	restoreViewScopeState(FacesContext context, Object state)	Restore ViewScope state.
Object	saveState(FacesContext context)	Gets the state of the instance as a Serializable Object.
void	setAfterPhaseListener(MethodExpression newAfterPhase)	Allow an arbitrary method to be called for the "afterPhase" event as the UIViewRoot runs through its lifecycle.
void	setBeforePhaseListener(MethodExpression newBeforePhase)	Allow an arbitrary method to be called for the "beforePhase" event as the UIViewRoot runs through its lifecycle.
void	setInView(boolean isInView)	Overridden to take no action.
void	setLocale(Locale locale)	Set the Locale to be used in localizing the response being created for this view.
void	setRenderKitId(String renderKitId)	Set the render kit identifier of the RenderKit associated with this view.
void	setViewId(String viewId)	Set the view identifier for this view.
void	subscribeToViewEvent(Class<? extends SystemEvent> systemEvent, SystemEventListener listener)	Install the listener instance referenced by argument listener into the UIViewRoot as a listener for events of type systemEventClass.
void	unsubscribeFromViewEvent(Class<? extends SystemEvent> systemEvent, SystemEventListener listener)	Remove the listener instance referenced by argument listener from the UIViewRoot as a listener for events of type systemEventClass.

Methods inherited from class jakarta.faces.component.UIComponentBase

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

Methods inherited from class jakarta.faces.component.UIComponent

encodeAll, getClientId, getCompositeComponentParent, getContainerClientId, getCurrentComponent, getCurrentCompositeComponent, getNamingContainer, getPassThroughAttributes, getResourceBundleMap, getStateHelper, getStateHelper, getTransientStateHelper, getTransientStateHelper, getValueExpression, initialStateMarked, isCompositeComponent, isVisitable, popComponentFromEL, pushComponentToEL, restoreTransientState, saveTransientState, setValueExpression, visitTree

Methods inherited from class java.lang.Object

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

Field Details

METADATA_FACET_NAME

public static final String METADATA_FACET_NAME

See Also:

• Constant Field Values

VIEW_PARAMETERS_KEY

public static final String VIEW_PARAMETERS_KEY

The key in the value set of the view metadata BeanDescriptor, the value of which is a List<UIViewParameter.Reference>.

Since:

2.0

See Also:

• Constant Field Values

COMPONENT_TYPE

public static final String COMPONENT_TYPE

The standard component type for this component.

See Also:

• Constant Field Values

COMPONENT_FAMILY

public static final String COMPONENT_FAMILY

The standard component family for this component.

See Also:

• Constant Field Values

VIEWROOT_PHASE_LISTENER_QUEUES_EXCEPTIONS_PARAM_NAME

public static final String VIEWROOT_PHASE_LISTENER_QUEUES_EXCEPTIONS_PARAM_NAME

If this param is set, and calling toLowerCase().equals("true") on a String representation of its value returns true, exceptions thrown by PhaseListeners installed on the UIViewRoot are queued to the ExceptionHandler instead of being logged and swallowed.

Since:

2.3

See Also:

• Constant Field Values

UNIQUE_ID_PREFIX

public static final String UNIQUE_ID_PREFIX

The prefix that will be used for identifiers generated by the createUniqueId() method.

See Also:

• Constant Field Values

Constructor Details

UIViewRoot

public UIViewRoot()

Create a new UIViewRoot instance with default property values.

Method Details

isInView

public boolean isInView()

Override superclass method to always return true because a UIViewRoot is defined to always be in a view.

Overrides:

isInView in class UIComponent

Returns:

true if within a view hierarchy, false otherwise.

Since:

2.0

setInView

public void setInView(boolean isInView)

Overridden to take no action.

Overrides:

setInView in class UIComponent

Parameters:

isInView - ignore the value.

Since:

2.0

getFamily

public String getFamily()

Description copied from class: UIComponent

Return the identifier of the component family to which this component belongs. This identifier, in conjunction with the value of the rendererType property, may be used to select the appropriate Renderer for this component instance. Note this method should NOT return null

Specified by:

getFamily in class UIComponent

Returns:

the component family (not null).

See Also:

• UIComponent.getFamily()

getRenderKitId

public String getRenderKitId()

Return the render kit identifier of the RenderKit associated with this view. Unless explicitly set, as in ViewHandler.createView(jakarta.faces.context.FacesContext, java.lang.String), the returned value will be null.

Returns:

the render kit id, or null.

setRenderKitId

public void setRenderKitId(String renderKitId)

Set the render kit identifier of the RenderKit associated with this view. This method may be called at any time between the end of Apply Request Values phase of the request processing lifecycle (i.e. when events are being broadcast) and the beginning of the Render Response phase.

Parameters:

renderKitId - The new RenderKit identifier, or null to disassociate this view with any specific RenderKit instance

getViewId

public String getViewId()

Return the view identifier for this view.

Returns:

the view id.

setViewId

public void setViewId(String viewId)

Set the view identifier for this view.

Parameters:

viewId - The new view identifier

getBeforePhaseListener

public MethodExpression getBeforePhaseListener()

Return the MethodExpression that will be invoked before this view is rendered.

Returns:

the MethodExpression that will be invoked before this view is rendered.

Since:

1.2

setBeforePhaseListener

public void setBeforePhaseListener(MethodExpression newBeforePhase)

Allow an arbitrary method to be called for the "beforePhase" event as the UIViewRoot runs through its lifecycle. This method will be called for all phases except PhaseId.RESTORE_VIEW. Unlike a true PhaseListener, this approach doesn't allow for only receiving PhaseEvents for a given phase.

The method must conform to the signature of PhaseListener.beforePhase(jakarta.faces.event.PhaseEvent).

Parameters:

newBeforePhase - the MethodExpression that will be invoked before this view is rendered.

Since:

1.2

getAfterPhaseListener

public MethodExpression getAfterPhaseListener()

Return the MethodExpression that will be invoked after this view is rendered.

Returns:

the MethodExpression that will be invoked after this view is rendered.

Since:

1.2

setAfterPhaseListener

public void setAfterPhaseListener(MethodExpression newAfterPhase)

Allow an arbitrary method to be called for the "afterPhase" event as the UIViewRoot runs through its lifecycle. This method will be called for all phases including PhaseId.RESTORE_VIEW. Unlike a true PhaseListener, this approach doesn't allow for only receiving PhaseEvents for a given phase.

The method must conform to the signature of PhaseListener.afterPhase(jakarta.faces.event.PhaseEvent).

Parameters:

newAfterPhase - the MethodExpression that will be invoked after this view is rendered.

Since:

1.2

removePhaseListener

public void removePhaseListener(PhaseListener toRemove)

If the argument toRemove is in the list of PhaseListeners for this instance, it must be removed.

Parameters:

toRemove - the PhaseListener to remove.

Since:

1.2

addPhaseListener

public void addPhaseListener(PhaseListener newPhaseListener)

Add the argument newPhaseListener to the list of PhaseListeners on this UIViewRoot.

Parameters:

newPhaseListener - the PhaseListener to add

Since:

1.2

getPhaseListeners

public List<PhaseListener> getPhaseListeners()

Return an unmodifiable list of the PhaseListener instances attached to this UIViewRoot instance.

Returns:

the list of phase listeners.

Since:

2.0

addComponentResource

public void addComponentResource(FacesContext context,
 UIComponent componentResource)

Add argument component, which is assumed to represent a resource instance, as a resource to this view. A resource instance is rendered by a resource Renderer, as described in the Standard HTML RenderKit. The default implementation must call through to addComponentResource(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent, java.lang.String).

Parameters:

context - FacesContext for the current request

componentResource - The UIComponent representing a Resource instance

Since:

2.0

addComponentResource

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

Add argument component, which is assumed to represent a resource instance, as a resource to this view. A resource instance is rendered by a resource Renderer, as described in the Standard HTML RenderKit.

The component must be added using the following algorithm:

• If the target argument is null, look for a target attribute on the component. If there is no target attribute, set target to be the default value head

• Call getComponentResources(jakarta.faces.context.FacesContext, java.lang.String) to obtain the child list for the given target.

• If the component ID of componentResource matches the the ID of a resource that has allready been added, remove the old resource.

• Add the component resource to the list.

The resource Renderer must ensure of the following:

• Do not render when ResourceHandler.isResourceRendered(FacesContext, String, String) returns true.
• After rendering, call ResourceHandler.markResourceRendered(FacesContext, String, String).

Parameters:

context - FacesContext for the current request

componentResource - The UIComponent representing a Resource instance

target - The name of the facet for which the UIComponent will be added

Since:

2.0

getComponentResources

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

Return an unmodifiable List of UIComponents for the provided target agrument. Each component in the List is assumed to represent a resource instance.

The default implementation must use an algorithm equivalent to the the following.

• Locate the facet for the component by calling getFacet() using target as the argument.
• If the facet is not found, create the facet by calling context.getApplication().createComponent(). The argument to this method must refer to a component that extends UIPanel and overrides the encodeAll() method to take no action. This is necessary to prevent component resources from being inadvertently rendered.
  • Set the id of the facet to be a string created by prepending the literal string “jakarta_faces_location_” (without the quotes) to the value of the target argument
  • Add the facet to the facets Map using target as the key
• return the children of the facet

Parameters:

context - the Faces context.

target - The name of the facet for which the components will be returned.

Returns:

A List of UIComponent children of the facet with the name target. If no children are found for the facet, return Collections.emptyList().

Throws:

NullPointerException - if target or context is null

Since:

2.0

getComponentResources

public List<UIComponent> getComponentResources(FacesContext context)

Return an unmodifiable ordered List of all UIComponent resources of all supported targets. Each component in the List is assumed to represent a resource instance. The ordering is the same as the resources would appear in the component tree.

Parameters:

context - The Faces context.

Returns:

A List of all UIComponent resources of all supported targets. If no resources are found, return an empty List.

Throws:

NullPointerException - If context is null.

Since:

2.3

removeComponentResource

public void removeComponentResource(FacesContext context,
 UIComponent componentResource)

Remove argument component, which is assumed to represent a resource instance, as a resource to this view.

Parameters:

context - FacesContext for the current request

componentResource - The UIComponent representing a Resource instance

Since:

2.0

removeComponentResource

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

Remove argument component, which is assumed to represent a resource instance, as a resource to this view. A resource instance is rendered by a resource Renderer, as described in the Standard HTML RenderKit.

The component must be removed using the following algorithm:

• If the target argument is null, look for a target attribute on the component.
  If there is no target attribute, set target to be the default value head
• Call getComponentResources(jakarta.faces.context.FacesContext, java.lang.String) to obtain the child list for the given target.
• Remove the component resource from the child list.

Parameters:

context - FacesContext for the current request

componentResource - The UIComponent representing a Resource instance

target - The name of the facet for which the UIComponent will be added

Since:

2.0

queueEvent

public void queueEvent(FacesEvent event)

Override the default UIComponentBase.queueEvent(jakarta.faces.event.FacesEvent) behavior to accumulate the queued events for later broadcasting.

Overrides:

queueEvent in class UIComponentBase

Parameters:

event - FacesEvent to be queued

Throws:

IllegalStateException - if this component is not a descendant of a UIViewRoot

NullPointerException - if event is null

broadcastEvents

public void broadcastEvents(FacesContext context,
 PhaseId phaseId)

Broadcast any events that have been queued. First broadcast events that have been queued for PhaseId.ANY_PHASE. Then broadcast ane events that have been queued for the current phase. In both cases, UIComponent.pushComponentToEL(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent) must be called before the event is broadcast, and UIComponent.popComponentFromEL(jakarta.faces.context.FacesContext) must be called after the return from the broadcast, even in the case of an exception.

Parameters:

context - FacesContext for the current request

phaseId - PhaseId of the current phase

Since:

2.0

processRestoreState

public void processRestoreState(FacesContext context,
 Object state)

The default implementation must call UIComponentBase.processRestoreState(jakarta.faces.context.FacesContext, java.lang.Object) from within a try block. The try block must have a finally block that ensures that no FacesEvents remain in the event queue.

Overrides:

processRestoreState in class UIComponentBase

Parameters:

context - the FacesContext for this requets

state - the opaque state object obtained from the StateManager

processEvent

public void processEvent(ComponentSystemEvent event)
                  throws AbortProcessingException

If the argument event is an instance of PostRestoreStateEvent and PartialViewContext.isPartialRequest() returns true, then loop over all component resources and call ResourceHandler.markResourceRendered(FacesContext, String, String) for each of them. Finally, delegate to super.

Specified by:

processEvent in interface ComponentSystemEventListener

Overrides:

processEvent in class UIComponent

Parameters:

event - the ComponentSystemEvent instance that is being processed.

Throws:

AbortProcessingException - if lifecycle processing should cease for this request.

processDecodes

public void processDecodes(FacesContext context)

Perform partial processing by calling PartialViewContext.processPartial(jakarta.faces.event.PhaseId) with PhaseId.APPLY_REQUEST_VALUES if:

• PartialViewContext.isPartialRequest() returns true and we don't have a request to process all components in the view (PartialViewContext.isExecuteAll() returns false)

Perform full processing by calling UIComponentBase.processDecodes(jakarta.faces.context.FacesContext) if one of the following conditions are met:

• PartialViewContext.isPartialRequest() returns true and we have a request to process all components in the view (PartialViewContext.isExecuteAll() returns true)
• PartialViewContext.isPartialRequest() returns false

Override the default UIComponentBase.processDecodes(jakarta.faces.context.FacesContext) behavior to broadcast any queued events after the default processing or partial processing has been completed and to clear out any events for later phases if the event processing for this phase caused FacesContext.renderResponse() or FacesContext.responseComplete() to be called.

Overrides:

processDecodes in class UIComponentBase

Parameters:

context - FacesContext for the request we are processing

Throws:

NullPointerException - if context is null

resetValues

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

Visit the clientIds and, if the component is an instance of EditableValueHolder, call its EditableValueHolder.resetValue() method. Use UIComponent.visitTree(jakarta.faces.component.visit.VisitContext, jakarta.faces.component.visit.VisitCallback) to do the visiting.

Parameters:

context - the FacesContext for the request we are processing.

clientIds - The client ids to be visited, on which the described action will be taken.

Since:

2.2

encodeBegin

public void encodeBegin(FacesContext context)
                 throws IOException

Override the default UIComponentBase.encodeBegin(jakarta.faces.context.FacesContext) behavior. If getBeforePhaseListener() returns non-null, invoke it, passing a PhaseEvent for the PhaseId.RENDER_RESPONSE phase. If the internal list populated by calls to addPhaseListener(jakarta.faces.event.PhaseListener) is non-empty, any listeners in that list must have their PhaseListener.beforePhase(jakarta.faces.event.PhaseEvent) method called, passing the PhaseEvent. Any Exceptions that occur during invocation of any of the beforePhase listeners must be logged and swallowed, unless the VIEWROOT_PHASE_LISTENER_QUEUES_EXCEPTIONS_PARAM_NAME parameter is set. In that case, the Exception must be passed to the ExceptionHandler as well.

Overrides:

encodeBegin in class UIComponentBase

Parameters:

context - FacesContext for the response we are creating

Throws:

IOException - if an input/output error occurs while rendering

encodeChildren

public void encodeChildren(FacesContext context)
                    throws IOException

If PartialViewContext.isAjaxRequest() returns true, perform partial rendering by calling PartialViewContext.processPartial(jakarta.faces.event.PhaseId) with PhaseId.RENDER_RESPONSE. If PartialViewContext.isAjaxRequest() returns false, delegate to the parent UIComponentBase.encodeChildren(jakarta.faces.context.FacesContext) method.

If this UIViewRoot is an instance of NamingContainer, then the Jakarta Server Faces implementation must ensure that all encoded POST request parameter names are prefixed with UIComponent.getContainerClientId(FacesContext) as per rules of UIComponent.getClientId(FacesContext). This also covers all predefined POST request parameters which are listed below:

• ResponseStateManager.VIEW_STATE_PARAM
• ResponseStateManager.CLIENT_WINDOW_PARAM
• ResponseStateManager.RENDER_KIT_ID_PARAM
• ClientBehaviorContext.BEHAVIOR_SOURCE_PARAM_NAME
• ClientBehaviorContext.BEHAVIOR_EVENT_PARAM_NAME
• PartialViewContext.PARTIAL_EVENT_PARAM_NAME
• PartialViewContext.PARTIAL_EXECUTE_PARAM_NAME
• PartialViewContext.PARTIAL_RENDER_PARAM_NAME
• PartialViewContext.RESET_VALUES_PARAM_NAME

Overrides:

encodeChildren in class UIComponentBase

Parameters:

context - FacesContext for the response we are creating

Throws:

IOException - if an input/output error occurs while rendering

Since:

2.0

encodeEnd

public void encodeEnd(FacesContext context)
               throws IOException

If getAfterPhaseListener() returns non-null, invoke it, passing a PhaseEvent for the PhaseId.RENDER_RESPONSE phase. Any Exceptions that occur during invocation of the afterPhase listener must be logged and swallowed, unless the VIEWROOT_PHASE_LISTENER_QUEUES_EXCEPTIONS_PARAM_NAME parameter is set. In that case, the Exception must be passed to the ExceptionHandler as well.. If the current view has view parameters, as indicated by a non-empty and non-UnsupportedOperationException throwing return from ViewDeclarationLanguage.getViewMetadata(jakarta.faces.context.FacesContext, String), call UIViewParameter.encodeAll(jakarta.faces.context.FacesContext) on each parameter. If calling getViewParameters() causes UnsupportedOperationException to be thrown, the exception must be silently swallowed.

Overrides:

encodeEnd in class UIComponentBase

Parameters:

context - FacesContext for the response we are creating

Throws:

IOException - if an input/output error occurs while rendering

getRendersChildren

public boolean getRendersChildren()

Call UIComponentBase.getRendersChildren() If PartialViewContext.isAjaxRequest() returns true this method must return true.

Overrides:

getRendersChildren in class UIComponentBase

Returns:

true if the component renders its children, false otherwise.

Since:

2.0

processValidators

public void processValidators(FacesContext context)

Perform partial processing by calling PartialViewContext.processPartial(jakarta.faces.event.PhaseId) with PhaseId.PROCESS_VALIDATIONS if:

• PartialViewContext.isPartialRequest() returns true and we don't have a request to process all components in the view (PartialViewContext.isExecuteAll() returns false)

Perform full processing by calling UIComponentBase.processValidators(jakarta.faces.context.FacesContext) if one of the following conditions are met:

• PartialViewContext.isPartialRequest() returns true and we have a request to process all components in the view (PartialViewContext.isExecuteAll() returns true)
• PartialViewContext.isPartialRequest() returns false

Override the default UIComponentBase.processValidators(jakarta.faces.context.FacesContext) behavior to broadcast any queued events after the default processing or partial processing has been completed and to clear out any events for later phases if the event processing for this phase caused FacesContext.renderResponse() or FacesContext.responseComplete() to be called.

Overrides:

processValidators in class UIComponentBase

Parameters:

context - FacesContext for the request we are processing

Throws:

NullPointerException - if context is null

See Also:

• PreValidateEvent
• PostValidateEvent

processUpdates

public void processUpdates(FacesContext context)

Perform partial processing by calling PartialViewContext.processPartial(jakarta.faces.event.PhaseId) with PhaseId.UPDATE_MODEL_VALUES if:

• PartialViewContext.isPartialRequest() returns true and we don't have a request to process all components in the view (PartialViewContext.isExecuteAll() returns false)

Perform full processing by calling UIComponentBase.processUpdates(jakarta.faces.context.FacesContext) if one of the following conditions are met:

• PartialViewContext.isPartialRequest() returns true and we have a request to process all components in the view (PartialViewContext.isExecuteAll() returns true)
• PartialViewContext.isPartialRequest() returns false

Override the default UIComponentBase behavior to broadcast any queued events after the default processing or partial processing has been completed and to clear out any events for later phases if the event processing for this phase caused FacesContext.renderResponse() or FacesContext.responseComplete() to be called.

Overrides:

processUpdates in class UIComponentBase

Parameters:

context - FacesContext for the request we are processing

Throws:

NullPointerException - if context is null

processApplication

public void processApplication(FacesContext context)

Broadcast any events that have been queued for the Invoke Application phase of the request processing lifecycle and to clear out any events for later phases if the event processing for this phase caused FacesContext.renderResponse() or FacesContext.responseComplete() to be called.

Parameters:

context - FacesContext for the request we are processing

Throws:

NullPointerException - if context is null

createUniqueId

public String createUniqueId()

Generate an identifier for a component. The identifier will be prefixed with UNIQUE_ID_PREFIX, and will be unique within the non-NamingContainer child sub-trees of this UIViewRoot.

Returns:

the identifier.

createUniqueId

public String createUniqueId(FacesContext context,
 String seed)

Generate an identifier for a component. The identifier will be prefixed with UNIQUE_ID_PREFIX, and will be unique within this UIViewRoot. Optionally, a unique seed value can be supplied by component creators which should be included in the generated unique id.

Specified by:

createUniqueId in interface UniqueIdVendor

Parameters:

context - FacesContext

seed - an optional seed value - e.g. based on the position of the component in the VDL-template

Returns:

a unique-id in this component-container

getLocale

public Locale getLocale()

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

Algorithm:

If we have a locale ivar, return it. If we have a value expression for "locale", get its value. If the value is null, return the result of calling ViewHandler.calculateLocale(jakarta.faces.context.FacesContext). If the value is an instance of java.util.Locale return it. If the value is a String, convert it to a java.util.Locale and return it. If there is no value expression for "locale", return the result of calling ViewHandler.calculateLocale(jakarta.faces.context.FacesContext).

Returns:

The current Locale obtained by executing the above algorithm.

setLocale

public void setLocale(Locale locale)

Set the Locale to be used in localizing the response being created for this view.

Parameters:

locale - The new localization Locale

getViewMap

public Map<String,Object> getViewMap()

This implementation simply calls through to getViewMap(boolean), passing true as the argument, and returns the result.

Returns:

the view map, or null.

Since:

2.0

getViewMap

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

Returns a Map that acts as the interface to the data store that is the "view scope", or, if this instance does not have such a Map and the create argument is true, creates one and returns it. This map must be instantiated lazily and cached for return from subsequent calls to this method on this UIViewRoot instance. Application.publishEvent(jakarta.faces.context.FacesContext, java.lang.Class<? extends jakarta.faces.event.SystemEvent>, java.lang.Object) must be called, passing the current FacesContext as the first argument, PostConstructViewMapEvent.class as the second argument, UIViewRoot.class as the third argument and this UIViewRoot instance as the fourth argument. It is necessary to pass the UIViewRoot.class argument to account for cases when the UIViewRoot has been extended with a custom class.

The returned Map must be implemented such that calling clear() on the Map causes Application.publishEvent(jakarta.faces.context.FacesContext, java.lang.Class<? extends jakarta.faces.event.SystemEvent>, java.lang.Object) to be called, passing PreDestroyViewMapEvent.class as the first argument and this UIViewRoot instance as the second argument.

Depending upon application configuration, objects stored in the view map may need to be Serializable. In general, it is a good idea to ensure that any objects stored in the view map are Serializable.

For reasons made clear in ViewScoped, this map must ultimately be stored in the session. For this reason, a true value for the create argument will force the session to be created with a call to ExternalContext.getSession(boolean).

See FacesContext.setViewRoot(jakarta.faces.component.UIViewRoot) for the specification of when the clear() method must be called.

Parameters:

create - true to create a new Map for this instance if necessary; false to return null if there's no current Map.

Returns:

the view map, or null.

Since:

2.0

subscribeToViewEvent

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

Install the listener instance referenced by argument listener into the UIViewRoot as a listener for events of type systemEventClass.

Note that installed listeners are not maintained as part of the UIViewRoot's state.

Parameters:

systemEvent - the Class of event for which listener must be fired.

listener - the implementation of SystemEventListener whose SystemEventListener.processEvent(jakarta.faces.event.SystemEvent) method must be called when events of type systemEventClass are fired.

Throws:

NullPointerException - if systemEventClass or listener are null.

Since:

2.0

unsubscribeFromViewEvent

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

Remove the listener instance referenced by argument listener from the UIViewRoot as a listener for events of type systemEventClass.

Parameters:

systemEvent - the Class of event for which listener must be fired.

listener - the implementation of SystemEventListener whose SystemEventListener.processEvent(jakarta.faces.event.SystemEvent) method must be called when events of type systemEventClass are fired.

Throws:

NullPointerException - if systemEventClass or listener are null.

Since:

2.0

getViewListenersForEventClass

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

Return the SystemEventListener instances registered on this UIComponent instance that are interested in events of type eventClass.

Parameters:

systemEvent - the Class of event for which the listeners must be returned.

Returns:

Collection of view listeners.

Throws:

NullPointerException - if argument systemEvent is null.

Since:

2.0

restoreViewScopeState

public void restoreViewScopeState(FacesContext context,
 Object state)

Restore ViewScope state. This is needed to allow the use of view scoped beans for EL-expressions in the template from which the component tree is built. For example: <ui:include src="#{viewScopedBean.includeFileName}"/>.

Parameters:

context - current FacesContext.

state - the state object.

saveState

public Object saveState(FacesContext context)

Description copied from interface: StateHolder

Gets the state of the instance as a Serializable Object.

If the class that implements this interface has references to instances that implement StateHolder (such as a UIComponent with event handlers, validators, etc.) this method must call the StateHolder.saveState(jakarta.faces.context.FacesContext) method on all those instances as well. This method must not save the state of children and facets. That is done via the StateManager

This method must not alter the state of the implementing object. In other words, after executing this code:

 
 Object state = component.saveState(facesContext);
 
 

component should be the same as before executing it.

The return from this method must be Serializable

Specified by:

saveState in interface StateHolder

Overrides:

saveState in class UIComponentBase

Parameters:

context - the Faces context.

Returns:

the saved state.

restoreState

public void restoreState(FacesContext context,
 Object state)

Description copied from interface: StateHolder

Perform any processing required to restore the state from the entries in the state Object.

If the class that implements this interface has references to instances that also implement StateHolder (such as a UIComponent with event handlers, validators, etc.) this method must call the StateHolder.restoreState(jakarta.faces.context.FacesContext, java.lang.Object) method on all those instances as well.

If the state argument is null, take no action and return.

Specified by:

restoreState in interface StateHolder

Overrides:

restoreState in class UIComponentBase

Parameters:

context - the Faces context.

state - the state.