Package org.apache.cayenne.query

## Class PrefetchTreeNode

- java.lang.Object
- - org.apache.cayenne.query.PrefetchTreeNode

- All Implemented Interfaces:
    `Serializable`, `XMLSerializable`

      public class PrefetchTreeNode
      extends Object
      implements Serializable, XMLSerializable

  Defines a node in a prefetch tree.
  Since:
    1.2
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected Collection<PrefetchTreeNode>` | `children` |
    `static int` | `DISJOINT_BY_ID_PREFETCH_SEMANTICS` |
    `static int` | `DISJOINT_PREFETCH_SEMANTICS` |
    `protected String` | `ejbqlPathEntityId` |
    `protected String` | `entityName` |
    `static int` | `JOINT_PREFETCH_SEMANTICS` |
    `protected String` | `name` |
    `protected PrefetchTreeNode` | `parent` |
    `protected boolean` | `phantom` |
    `protected int` | `semantics` |
    `static int` | `UNDEFINED_SEMANTICS` |

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `` | `PrefetchTreeNode()` | Creates a root node of the prefetch tree.
    `protected` | `PrefetchTreeNode​(PrefetchTreeNode parent, String name)` | Creates a phantom PrefetchTreeNode, initializing it with parent node and a name of a relationship segment connecting this node with the parent.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addChild​(PrefetchTreeNode child)` |
    `PrefetchTreeNode` | `addPath​(String path)` | Adds a "path" with specified semantics to this prefetch node.
    `Collection<PrefetchTreeNode>` | `adjacentJointNodes()` | Returns a subset of nodes with "joint" semantics that are to be prefetched in the same query as the current node.
    `PrefetchTreeNode` | `cloneJointSubtree()` | Returns a clone of subtree that includes all joint children starting from this node itself and till the first occurrence of non-joint node
    `Collection<PrefetchTreeNode>` | `disjointByIdNodes()` | Returns a collection of PrefetchTreeNodes with disjoint semantics
    `Collection<PrefetchTreeNode>` | `disjointNodes()` | Returns a collection of PrefetchTreeNodes with disjoint semantics.
    `void` | `encodeAsXML​(XMLEncoder encoder, ConfigurationNodeVisitor delegate)` | Prints itself as XML to the provided XMLEncoder.
    `protected PrefetchTreeNode` | `getChild​(String segment)` |
    `Collection<PrefetchTreeNode>` | `getChildren()` | Returns an unmodifiable collection of children.
    `String` | `getEjbqlPathEntityId()` |
    `String` | `getEntityName()` |
    `String` | `getName()` |
    `PrefetchTreeNode` | `getNode​(String path)` | Looks up an existing node in the tree desribed by the dot-separated path.
    `PrefetchTreeNode` | `getParent()` |
    `String` | `getPath()` | Returns full prefetch path, that is a dot separated String of node names starting from root and up to and including this node.
    `String` | `getPath​(PrefetchTreeNode upTillParent)` |
    `PrefetchTreeNode` | `getRoot()` | Returns the root of the node tree.
    `int` | `getSemantics()` |
    `boolean` | `hasChildren()` |
    `boolean` | `isDisjointByIdPrefetch()` |
    `boolean` | `isDisjointPrefetch()` |
    `boolean` | `isJointPrefetch()` |
    `boolean` | `isPhantom()` |
    `Collection<PrefetchTreeNode>` | `jointNodes()` | Returns a collection of PrefetchTreeNodes in this tree with joint semantics.
    `void` | `merge​(PrefetchTreeNode node)` | Merges `PrefetchTreeNode` into the current prefetch tree, cloning the nodes added to this tree.
    `Collection<PrefetchTreeNode>` | `nonPhantomNodes()` | Returns a collection of PrefetchTreeNodes that are not phantoms.
    `protected Object` | `readResolve()` |
    `protected void` | `removeChild​(String segment)` |
    `void` | `removeChild​(PrefetchTreeNode child)` |
    `void` | `removePath​(String path)` | Removes or makes phantom a node defined by this path.
    `void` | `setEjbqlPathEntityId​(String ejbqlPathEntityId)` |
    `void` | `setEntityName​(String entityName)` |
    `void` | `setPhantom​(boolean phantom)` |
    `void` | `setSemantics​(int semantics)` |
    `void` | `traverse​(PrefetchProcessor processor)` | Traverses the tree depth-first, invoking callback methods of the processor when passing through the nodes.
    `static PrefetchTreeNode` | `withPath​(String path, int semantics)` | Creates and returns a prefetch tree spanning a single path.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### UNDEFINED_SEMANTICS

          public static final int UNDEFINED_SEMANTICS

      See Also:
        Constant Field Values

    - #### JOINT_PREFETCH_SEMANTICS

          public static final int JOINT_PREFETCH_SEMANTICS

      See Also:
        Constant Field Values

    - #### DISJOINT_PREFETCH_SEMANTICS

          public static final int DISJOINT_PREFETCH_SEMANTICS

      See Also:
        Constant Field Values

    - #### DISJOINT_BY_ID_PREFETCH_SEMANTICS

          public static final int DISJOINT_BY_ID_PREFETCH_SEMANTICS

      See Also:
        Constant Field Values

    - #### name

          protected String name

    - #### phantom

          protected boolean phantom

    - #### semantics

          protected int semantics

    - #### ejbqlPathEntityId

          protected String ejbqlPathEntityId

    - #### entityName

          protected String entityName

    - #### parent

          protected transient PrefetchTreeNode parent

    - #### children

          protected Collection<PrefetchTreeNode> children

  - ### Constructor Detail

    - #### PrefetchTreeNode

          public PrefetchTreeNode()

      Creates a root node of the prefetch tree. Children can be added to the parent by calling "addPath".

    - #### PrefetchTreeNode

          protected PrefetchTreeNode​(PrefetchTreeNode parent,
                                     String name)

      Creates a phantom PrefetchTreeNode, initializing it with parent node and a name of a relationship segment connecting this node with the parent.

  - ### Method Detail

    - #### withPath

          public static PrefetchTreeNode withPath​(String path,
                                                  int semantics)

      Creates and returns a prefetch tree spanning a single path. The tree is made of phantom nodes, up to the leaf node, which is non-phantom and has specified semantics.
      Since:
        4.0

    - #### encodeAsXML

          public void encodeAsXML​(XMLEncoder encoder,
                                  ConfigurationNodeVisitor delegate)

      Description copied from interface: `XMLSerializable`
      Prints itself as XML to the provided XMLEncoder.
      Specified by:
        `encodeAsXML` in interface `XMLSerializable`

    - #### getRoot

          public PrefetchTreeNode getRoot()

      Returns the root of the node tree. Root is the topmost parent node that itself has no parent set.

    - #### getPath

          public String getPath()

      Returns full prefetch path, that is a dot separated String of node names starting from root and up to and including this node. Note that root "name" is considered to be an empty string.

    - #### getPath

          public String getPath​(PrefetchTreeNode upTillParent)

    - #### adjacentJointNodes

          public Collection<PrefetchTreeNode> adjacentJointNodes()

      Returns a subset of nodes with "joint" semantics that are to be prefetched in the same query as the current node. Result excludes this node, regardless of its semantics.

    - #### jointNodes

          public Collection<PrefetchTreeNode> jointNodes()

      Returns a collection of PrefetchTreeNodes in this tree with joint semantics.

    - #### disjointNodes

          public Collection<PrefetchTreeNode> disjointNodes()

      Returns a collection of PrefetchTreeNodes with disjoint semantics.

    - #### disjointByIdNodes

          public Collection<PrefetchTreeNode> disjointByIdNodes()

      Returns a collection of PrefetchTreeNodes with disjoint semantics
      Since:
        3.1

    - #### nonPhantomNodes

          public Collection<PrefetchTreeNode> nonPhantomNodes()

      Returns a collection of PrefetchTreeNodes that are not phantoms.

    - #### cloneJointSubtree

          public PrefetchTreeNode cloneJointSubtree()

      Returns a clone of subtree that includes all joint children starting from this node itself and till the first occurrence of non-joint node
      Since:
        3.1

    - #### traverse

          public void traverse​(PrefetchProcessor processor)

      Traverses the tree depth-first, invoking callback methods of the processor when passing through the nodes.

    - #### getNode

          public PrefetchTreeNode getNode​(String path)

      Looks up an existing node in the tree desribed by the dot-separated path. Will return null if no matching child exists.

    - #### addPath

          public PrefetchTreeNode addPath​(String path)

      Adds a "path" with specified semantics to this prefetch node. All yet non-existent nodes in the created path will be marked as phantom.
      Returns:
        the last segment in the created path.

    - #### merge

          public void merge​(PrefetchTreeNode node)

      Merges `PrefetchTreeNode` into the current prefetch tree, cloning the nodes added to this tree. Merged nodes semantics (if defined) and non-phantom status are applied to the nodes of this tree.
      Parameters:
        `node` - a root node of a tree to merge into this tree. The path of the merged node within the resulting tree is determined from its name.
      Since:
        4.0

    - #### removePath

          public void removePath​(String path)

      Removes or makes phantom a node defined by this path. If the node for this path doesn't have any children, it is removed, otherwise it is made phantom.

    - #### addChild

          public void addChild​(PrefetchTreeNode child)

    - #### removeChild

          public void removeChild​(PrefetchTreeNode child)

    - #### removeChild

          protected void removeChild​(String segment)

    - #### getChild

          protected PrefetchTreeNode getChild​(String segment)

    - #### getParent

          public PrefetchTreeNode getParent()

    - #### getChildren

          public Collection<PrefetchTreeNode> getChildren()

      Returns an unmodifiable collection of children.

    - #### hasChildren

          public boolean hasChildren()

    - #### getName

          public String getName()

    - #### isPhantom

          public boolean isPhantom()

    - #### setPhantom

          public void setPhantom​(boolean phantom)

    - #### getSemantics

          public int getSemantics()

    - #### setSemantics

          public void setSemantics​(int semantics)

    - #### isJointPrefetch

          public boolean isJointPrefetch()

    - #### isDisjointPrefetch

          public boolean isDisjointPrefetch()

    - #### isDisjointByIdPrefetch

          public boolean isDisjointByIdPrefetch()

    - #### getEjbqlPathEntityId

          public String getEjbqlPathEntityId()

    - #### setEjbqlPathEntityId

          public void setEjbqlPathEntityId​(String ejbqlPathEntityId)

    - #### getEntityName

          public String getEntityName()

    - #### setEntityName

          public void setEntityName​(String entityName)

    - #### readResolve

          protected Object readResolve()
                                throws ObjectStreamException

      Throws:
        `ObjectStreamException`