Immutable implementation of the {@code Tree} interface in order to providethe much feature rich API functionality for a given {@code NodeState}.
Tree hierarchy
Due to the nature of this {@code Tree} implementation creating a properhierarchical view of the tree structure is the responsibility of the caller. It is recommended to start with the state of the {@link #ImmutableTree(org.apache.jackrabbit.oak.spi.state.NodeState) root node}and build up the hierarchy by calling {@link #ImmutableTree(ImmutableTree,String,org.apache.jackrabbit.oak.spi.state.NodeState)}for every subsequent child state. Note, that this implementation will not perform any kind of validation of the passed state and methods like {@link #isRoot()}, {@link #getName()} or {@link #getPath()} will just make use of the hierarchy that has beencreate by that sequence. In order to create a disconnected individual tree in cases where the hierarchy information is not (yet) need or known it is suggested to use {@link #ImmutableTree(ImmutableTree.ParentProvider,String,org.apache.jackrabbit.oak.spi.state.NodeState)}an specify an appropriate {@code ParentProvider} implementation.
ParentProvider
Apart from create the tree hierarchy in traversal mode this tree implementation allows to instantiate disconnected trees that depending on the use may never or on demand retrieve hierarchy information. The following default implementations of this internal interface are present:
- {@link DefaultParentProvider}: used with the default usage where the parent tree is passed to the constructor
- {@link ParentProvider#ROOT_PROVIDER}: the default parent provider for the root tree. All children will get {@link DefaultParentProvider}
- {@link ParentProvider#UNSUPPORTED}: throws {@code UnsupportedOperationException}upon hierarchy related methods like {@link #getParent()}, {@link #getPath()}
Equality and hash code
In contrast to {@link org.apache.jackrabbit.oak.core.MutableTree} the {@code ImmutableTree} implements{@link Object#equals(Object)} and {@link Object#hashCode()}: Two {@code ImmutableTree}s are consider equal if their name and the underlying {@code NodeState}s are equal. Note however, that according to the contract defined in {@code NodeState} theseobjects are not expected to be used as hash keys.