jakarta.faces.component.visit

Class VisitContext

java.lang.Object

jakarta.faces.component.visit.VisitContext

Direct Known Subclasses:

VisitContextWrapper

public abstract class VisitContext
extends Object

A context object that is used to hold state relating to performing a component tree visit.

Component tree visits are initiated by calling UIComponent.visitTree(jakarta.faces.component.visit.VisitContext, jakarta.faces.component.visit.VisitCallback), at which point both a VisitContext and a VisitCallback must be provided.

Since:

2.0

See Also:

UIComponent.visitTree(), VisitCallback

Field Summary

Fields

Modifier and Type	Field and Description
static Collection<String>	ALL_IDS This unmodifiable Collection is returned by getIdsToVisit() and getSubtreeIdsToVisit() in cases where all ids should be visited.

Constructor Summary

Constructors

Constructor and Description
VisitContext()

Method Summary

Modifier and Type	Method and Description
static VisitContext	createVisitContext(FacesContext context) Creates a VisitContext instance for use with UIComponent.visitTree().
static VisitContext	createVisitContext(FacesContext context, Collection<String> ids, Set<VisitHint> hints) Returns a VisitContext instance that is initialized with the specified ids and hintsfor use with UIComponent.visitTree(jakarta.faces.component.visit.VisitContext, jakarta.faces.component.visit.VisitCallback).
abstract FacesContext	getFacesContext() Returns the FacesContext for the current request.
abstract Set<VisitHint>	getHints() Returns hints that influence the behavior of the tree visit.
abstract Collection<String>	getIdsToVisit() Returns the ids of the components to visit.
abstract Collection<String>	getSubtreeIdsToVisit(UIComponent component) Given a NamingContainer component, returns the client ids of any components underneath the NamingContainer that should be visited.
abstract VisitResult	invokeVisitCallback(UIComponent component, VisitCallback callback) Called by UIComponent.visitTree() to visit a single component.

Methods inherited from class java.lang.Object

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

Field Detail

ALL_IDS

public static final Collection<String> ALL_IDS

This unmodifiable Collection is returned by getIdsToVisit() and getSubtreeIdsToVisit() in cases where all ids should be visited.

To simplify logic for visitTree() implementations, this Collection always returns false for isEmpty. All other methods throw UnsupportedOperationException.

Since:

2.0

Constructor Detail

VisitContext

public VisitContext()

Method Detail

getFacesContext

public abstract FacesContext getFacesContext()

Returns the FacesContext for the current request.

Returns:

the FacesContext.

Since:

2.0

getIdsToVisit

public abstract Collection<String> getIdsToVisit()

Returns the ids of the components to visit.

In the case of a full tree visit, this method returns the ALL_IDS collection. Otherwise, if a partial visit is beign performed, returns a modifiable collection containing the client ids of the components that should be visited.

Returns:

the ids of the components to visit

getSubtreeIdsToVisit

public abstract Collection<String> getSubtreeIdsToVisit(UIComponent component)

Given a NamingContainer component, returns the client ids of any components underneath the NamingContainer that should be visited.

This method is called by NamingContainer visitTree() implementations to determine whether the NamingContainer contains components to be visited. In the case where no such components exist, the NamingContainer can short-circuit the tree visit and avoid descending into child subtrees.

In addition, iterating components such as UIData may be able to use the returned ids to determine which iterated states (ie. rows) need to be visited. This allows the visit traversal to be contstrained such only those rows that contain visit targets need to be traversed.

Parameters:

component - a NamingContainer component

Returns:

an unmodifiable Collection containing the client ids of any components underneath the NamingContainer that are known to be targets of the tree visit. If no such components exist, returns an empty Collection. If all components underneath the NamingContainer should be visited, returns the VisitContext.ALL_IDS collection.

Throws:

IllegalArgumentException - if component is not an instance of NamingContainer

invokeVisitCallback

public abstract VisitResult invokeVisitCallback(UIComponent component,
                                                VisitCallback callback)

Called by UIComponent.visitTree() to visit a single component.

Parameters:

component - the component to visit

callback - the VisitCallback to call

Returns:

a VisitResult value that indicates whether to continue visiting the component's subtree, skip visiting the component's subtree or abort the visit altogether.

getHints

public abstract Set<VisitHint> getHints()

Returns hints that influence the behavior of the tree visit.

Interested parties, such as UIComponent.visitTree() implementations, may check to see whether a particular hint is present by calling VisitContext.getHints().contains(), passing in one of the hints defined by VisitHint.

Returns:

a non-empty, unmodifiable collection of VisitHints

createVisitContext

public static VisitContext createVisitContext(FacesContext context,
                                              Collection<String> ids,
                                              Set<VisitHint> hints)

Returns a VisitContext instance that is initialized with the specified ids and hintsfor use with UIComponent.visitTree(jakarta.faces.component.visit.VisitContext, jakarta.faces.component.visit.VisitCallback).

Parameters:

context - the FacesContext for the current request

ids - the client ids of the components to visit. If null, all components will be visited.

hints - the VisitHints to apply to the visit. If null, no hints are applied.

Returns:

a VisitContext instance that is initialized with the specified ids and hints.

createVisitContext

public static VisitContext createVisitContext(FacesContext context)

Creates a VisitContext instance for use with UIComponent.visitTree(). This method can be used to obtain a VisitContext instance when all components should be visited with the default visit hints.

Parameters:

context - the FacesContext for the current request

Returns:

a VisitContext instance