org.apache.myfaces.trinidad.component.visit

## Class VisitContext

- java.lang.Object
- - org.apache.myfaces.trinidad.component.visit.VisitContext

- Direct Known Subclasses:
    UIXCollection.NoColumnFacetsVisitContext, VisitContextWrapper

      public abstract class VisitContext
      extends Object

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

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

  See Also:
    `UIXComponent.visitTree()`, `VisitCallback`

- - ### Field Summary

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

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `VisitContext()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract javax.faces.context.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 javax.faces.event.PhaseId` | `getPhaseId()` Returns the PhaseId, if any that, that this visit is ocurring under
    `abstract Collection<String>` | `getSubtreeIdsToVisit(javax.faces.component.UIComponent component)` Given a NamingContainer component, returns the client ids of any components underneath the NamingContainer that should be visited.
    `abstract VisitResult` | `invokeVisitCallback(javax.faces.component.UIComponent component, VisitCallback callback)` Called by `UIXComponent.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 VisitContext.getIdsToVisit() and getSubtreeIdsToVisit( in cases where all ids should be visited.

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

  - ### Constructor Detail

    - #### VisitContext

          public VisitContext()

  - ### Method Detail

    - #### getFacesContext

          public abstract javax.faces.context.FacesContext getFacesContext()

      Returns the FacesContext for the current request.

    - #### getPhaseId

          public abstract javax.faces.event.PhaseId getPhaseId()

      Returns the PhaseId, if any that, that this visit is ocurring under

      Returns:
        the current PhaseId

    - #### 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 being performed, returns a modifiable collection containing the client ids of the components that should be visited.

      Returns:
        `VisitContext.ALL_IDS`, or a modifiable Collection of client ids.

    - #### getSubtreeIdsToVisit

          public abstract Collection<String> getSubtreeIdsToVisit(javax.faces.component.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(javax.faces.component.UIComponent component,
                                        VisitCallback callback)

      Called by `UIXComponent.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

Copyright © 2001-2016 The Apache Software Foundation. All Rights Reserved.