PrefetchTreeNode (cayenne-doc: Cayenne Documentation 5.0-M2 API)
Description: declaration: package: org.apache.cayenne.query, class: PrefetchTreeNode

# 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 final int`
  `DISJOINT_BY_ID_PREFETCH_SEMANTICS`
  `static final int`
  `DISJOINT_PREFETCH_SEMANTICS`
  `protected String`
  `ejbqlPathEntityId`
  `protected String`
  `entityName`
  `static final int`
  `JOINT_PREFETCH_SEMANTICS`
  `protected String`
  `name`
  `protected PrefetchTreeNode`
  `parent`
  `protected boolean`
  `phantom`
  `protected int`
  `semantics`
  `static final 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

  Modifier and Type
  Method
  Description
  `void`
  `addChild(PrefetchTreeNode child)`
  `PrefetchTreeNode`
  `addPath(String path)`
  Adds a "path" with specified semantics to this prefetch node.
  `PrefetchTreeNode`
  `addPath(CayennePath 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 described by the dot-separated path.
  `PrefetchTreeNode`
  `getNode(CayennePath path)`
  Looks up an existing node in the tree described by the path.
  `PrefetchTreeNode`
  `getParent()`
  `CayennePath`
  `getPath()`
  Returns full prefetch path, that is a dot separated String of node names starting from root and up to and including this node.
  `CayennePath`
  `getPath(PrefetchTreeNode upTillParent)`
  Returns full prefetch path, that is a dot separated String of node names starting from root and up to and including this node.
  `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.
  `static PrefetchTreeNode`
  `withPath(CayennePath path, int semantics)`
  Creates and returns a prefetch tree spanning a single path.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### 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 Details

  - ### 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 Details

  - ### 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

  - ### withPath

    public static PrefetchTreeNode withPath(CayennePath 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:
      5.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 CayennePath 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.
    Returns:
      path from the root
    Since:
      5.0 returns `CayennePath` instead of a plain `String`

  - ### getPath

    public CayennePath getPath(PrefetchTreeNode upTillParent)
    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.
    Parameters:
      `upTillParent` - parent we need to stop at, if `null` returns path up to the root
    Returns:
      path from the specified parent node
    Since:
      5.0 returns `CayennePath` instead of a plain `String`

  - ### 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(CayennePath path)
    Looks up an existing node in the tree described by the path. Will return null if no matching child exists.
    Parameters:
      `path` - expression to look up node for
    Returns:
      found node or null if non exists
    Since:
      5.0

  - ### getNode

    public PrefetchTreeNode getNode(String path)
    Looks up an existing node in the tree described by the dot-separated path. Will return null if no matching child exists.
    Parameters:
      `path` - expression to look up node for
    Returns:
      found node or null if non exists

  - ### addPath

    public PrefetchTreeNode addPath(CayennePath 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.
    Since:
      5.0

  - ### 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`