org.apache.jackrabbit.oak.plugins.tree.impl

Class ImmutableTree

java.lang.Object

org.apache.jackrabbit.oak.plugins.tree.impl.AbstractTree

org.apache.jackrabbit.oak.plugins.tree.impl.ImmutableTree

All Implemented Interfaces:

Tree, ReadOnly, TreeTypeAware

public final class ImmutableTree
extends AbstractTree
implements TreeTypeAware, ReadOnly

Immutable implementation of the Tree interface in order to provide the much feature rich API functionality for a given NodeState.

Tree hierarchy

Due to the nature of this Tree implementation creating a proper hierarchical view of the tree structure is the responsibility of the caller. It is recommended to start with the state of the root node and build up the hierarchy by calling 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 isRoot(), getName() or getPath() will just make use of the hierarchy that has been create 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 ImmutableTree(ImmutableTree.ParentProvider, String, org.apache.jackrabbit.oak.spi.state.NodeState) an specify an appropriate 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:

• ImmutableTree.DefaultParentProvider: used with the default usage where the parent tree is passed to the constructor
• ImmutableTree.ParentProvider.ROOT_PROVIDER: the default parent provider for the root tree. All children will get ImmutableTree.DefaultParentProvider
• ImmutableTree.ParentProvider.UNSUPPORTED: throws UnsupportedOperationException upon hierarchy related methods like AbstractTree.getParent(), getPath()

Filtering 'hidden' items

This Tree implementation reflects the item hierarchy as exposed by the underlying NodeState. In contrast to the mutable implementations it does not filter out 'hidden' items as identified by org.apache.jackrabbit.oak.spi.state.NodeStateUtils#isHidden(String).

Equality and hash code

In contrast to AbstractMutableTree the ImmutableTree implements Object.equals(Object) and Object.hashCode(): Two ImmutableTrees are consider equal if their name and the underlying NodeStates are equal. Note however, that according to the contract defined in NodeState these objects are not expected to be used as hash keys.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ImmutableTree.DefaultParentProvider
static interface	ImmutableTree.ParentProvider

Nested classes/interfaces inherited from interface org.apache.jackrabbit.oak.api.Tree

Tree.Status

Field Summary

Fields inherited from interface org.apache.jackrabbit.oak.api.Tree

EMPTY_ARRAY

Constructor Summary

Constructors

Constructor and Description
ImmutableTree(ImmutableTree.ParentProvider parentProvider, String name, NodeState state)
ImmutableTree(ImmutableTree parent, String name, NodeState state)
ImmutableTree(NodeState rootState)

Method Summary

Modifier and Type	Method and Description
Tree	addChild(String name) Add a child with the given name.
protected ImmutableTree	createChild(String name) Factory method for creating child trees
boolean	equals(Object o)
ImmutableTree	getChild(String name) Get a possibly non existing child of this Tree.
protected String[]	getInternalNodeNames()
String	getName()
protected NodeBuilder	getNodeBuilder()
protected AbstractTree	getParentOrNull()
String	getPath()
TreeType	getType()
int	hashCode()
protected boolean	isHidden(String name) Determine whether an item should be hidden.
boolean	isRoot()
boolean	orderBefore(String name) Orders this Tree before the sibling tree with the given name.
boolean	remove() Remove this tree instance.
void	removeProperty(String name) Remove the property with the given name.
void	setOrderableChildren(boolean enable) Changes the nature of this tree such that the order of the children is kept stable.
void	setProperty(PropertyState property) Set a property state
<T> void	setProperty(String name, T value) Set a property state
<T> void	setProperty(String name, T value, Type<T> type) Set a property state
void	setType(TreeType type)

Methods inherited from class org.apache.jackrabbit.oak.plugins.tree.impl.AbstractTree

buildPath, exists, getChildNames, getChildren, getChildrenCount, getNodeState, getParent, getProperties, getProperty, getPropertyCount, getPropertyStatus, getStatus, hasChild, hasOrderableChildren, hasProperty, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ImmutableTree

public ImmutableTree(@Nonnull
                     NodeState rootState)

ImmutableTree

public ImmutableTree(@Nonnull
                     ImmutableTree parent,
                     @Nonnull
                     String name,
                     @Nonnull
                     NodeState state)

ImmutableTree

public ImmutableTree(@Nonnull
                     ImmutableTree.ParentProvider parentProvider,
                     @Nonnull
                     String name,
                     @Nonnull
                     NodeState state)

Method Detail

getType

@CheckForNull
public TreeType getType()

Specified by:

getType in interface TreeTypeAware

setType

public void setType(@Nonnull
                    TreeType type)

Specified by:

setType in interface TreeTypeAware

createChild

@Nonnull
protected ImmutableTree createChild(@Nonnull
                                              String name)

Description copied from class: AbstractTree

Factory method for creating child trees

Specified by:

createChild in class AbstractTree

Parameters:

name - name of the child tree

Returns:

child tree of this tree with the given name

isRoot

public boolean isRoot()

Specified by:

isRoot in interface Tree

Overrides:

isRoot in class AbstractTree

Returns:

true iff this is the root

getParentOrNull

@CheckForNull
protected AbstractTree getParentOrNull()

Specified by:

getParentOrNull in class AbstractTree

Returns:

the parent of this tree or null for the root

getNodeBuilder

@Nonnull
protected NodeBuilder getNodeBuilder()

Specified by:

getNodeBuilder in class AbstractTree

Returns:

The NodeBuilder for the underlying node state

isHidden

protected boolean isHidden(@Nonnull
                           String name)

Description copied from class: AbstractTree

Determine whether an item should be hidden. I.e. not exposed through this tree.

Overrides:

isHidden in class AbstractTree

Parameters:

name - name of an item

Returns:

true if the item is hidden, false otherwise.

getInternalNodeNames

@Nonnull
protected String[] getInternalNodeNames()

Overrides:

getInternalNodeNames in class AbstractTree

getName

@Nonnull
public String getName()

Specified by:

getName in interface Tree

Returns:

the name of this Tree instance.

getPath

@Nonnull
public String getPath()

Specified by:

getPath in interface Tree

Overrides:

getPath in class AbstractTree

Returns:

the absolute path of this Tree instance from its Root.

getChild

@Nonnull
public ImmutableTree getChild(@Nonnull
                                        String name)
                                 throws IllegalArgumentException

Description copied from interface: Tree

Get a possibly non existing child of this Tree.

Specified by:

getChild in interface Tree

Overrides:

getChild in class AbstractTree

Parameters:

name - The name of the child to retrieve.

Returns:

The child with the given name.

Throws:

IllegalArgumentException - if the given name is invalid

remove

public boolean remove()

Description copied from interface: Tree

Remove this tree instance. This operation never succeeds for the root tree.

Specified by:

remove in interface Tree

Returns:

true if the node was removed; false otherwise.

addChild

@Nonnull
public Tree addChild(@Nonnull
                               String name)

Description copied from interface: Tree

Add a child with the given name. Does nothing if such a child already exists.

Specified by:

addChild in interface Tree

Parameters:

name - name of the child. A valid name does not start with a colon, is not empty and does not contain a forward slash.

Returns:

the Tree instance of the child with the given name.

setOrderableChildren

public void setOrderableChildren(boolean enable)

Description copied from interface: Tree

Changes the nature of this tree such that the order of the children is kept stable. The expected behavior is as follows:

1. Calling setOrderableChildren(true) on a tree the first time will stabilize the order of existing children. Any subsequent Tree.addChild(String) call is guaranteed to insert the new tree and the end of the child list.
2. Calling setOrderableChildren(true) on a tree that already has its children ordered has no effect.
3. Calling setOrderableChildren(false) on a tree that doesn't have ordered children has not effect
4. Calling setOrderableChildren(false) on a tree with ordered children will remove the necessity to keep the child list stable. The order of children upon Tree.getChildren() is subsequently undefined.

Calling Tree.orderBefore(String) on a tree, implicitly enables orderable children on the parent tree.

Specified by:

setOrderableChildren in interface Tree

Parameters:

enable - Enable (or disable) orderable children for this tree.

orderBefore

public boolean orderBefore(@Nullable
                           String name)

Description copied from interface: Tree

Orders this Tree before the sibling tree with the given name. Calling this method for the first time on this Tree or any of its siblings will persist the current order of siblings and maintain it from this point on.

Specified by:

orderBefore in interface Tree

Parameters:

name - the name of the sibling node where this tree is ordered before. This tree will become the last sibling if name is null.

Returns:

false if there is no sibling with the given name or no reordering was performed; true otherwise.

setProperty

public void setProperty(@Nonnull
                        PropertyState property)

Description copied from interface: Tree

Set a property state

Specified by:

setProperty in interface Tree

Parameters:

property - The property state to set

setProperty

public <T> void setProperty(@Nonnull
                            String name,
                            @Nonnull
                            T value)

Description copied from interface: Tree

Set a property state

Specified by:

setProperty in interface Tree

Type Parameters:

T - The type of this property. Must be one of String, Blob, byte[], Long, Integer, Double, Boolean, BigDecimal

Parameters:

name - The name of this property. A valid name does not start with a colon, is not empty and does not contain a forward slash.

value - The value of this property

setProperty

public <T> void setProperty(@Nonnull
                            String name,
                            @Nonnull
                            T value,
                            @Nonnull
                            Type<T> type)

Description copied from interface: Tree

Set a property state

Specified by:

setProperty in interface Tree

Type Parameters:

T - The type of this property.

Parameters:

name - The name of this property. A valid name does not start with a colon, is not empty and does not contain a forward slash.

value - The value of this property

type - The type of this property.

removeProperty

public void removeProperty(@Nonnull
                           String name)

Description copied from interface: Tree

Remove the property with the given name. This method has no effect if a property of the given name does not exist.

Specified by:

removeProperty in interface Tree

Parameters:

name - The name of the property

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object