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(org.apache.jackrabbit.oak.core.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()}
TreeTypeProvider
For optimization purpose an Immutable tree will be associated with a {@code TreeTypeProvider} that allows for fast detection of the following typesof Trees:
- {@link TreeTypeProvider#TYPE_HIDDEN}: a hidden tree whose name starts with ":". Please note that the whole subtree of a hidden node is considered hidden.
- {@link TreeTypeProvider#TYPE_AC}: A tree that stores access control content and requires special access {@link org.apache.jackrabbit.oak.spi.security.authorization.permission.Permissions#READ_ACCESS_CONTROL permissions}.
- {@link TreeTypeProvider#TYPE_VERSION}: if a given tree is located within any of the version related stores defined by JSR 283. Depending on the permission evaluation implementation those items require special treatment.
- {@link TreeTypeProvider#TYPE_DEFAULT}: the default type for trees that don't match any of the upper types.
Equality and hash code
In contrast to {@link 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.