Package 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	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	Description
ImmutableTree(@NotNull ImmutableTree.ParentProvider parentProvider, @NotNull String name, @NotNull NodeState state)
ImmutableTree(@NotNull ImmutableTree parent, @NotNull String name, @NotNull NodeState state)
ImmutableTree(@NotNull NodeState rootState)

Method Summary

Modifier and Type	Method	Description
@NotNull Tree	addChild(@NotNull String name)	Add a child with the given name.
protected @NotNull ImmutableTree	createChild(@NotNull String name)	Factory method for creating child trees
boolean	equals(Object o)
@NotNull ImmutableTree	getChild(@NotNull String name)	Get a possibly non existing child of this Tree.
protected @NotNull String[]	getInternalNodeNames()
@NotNull String	getName()
protected @NotNull NodeBuilder	getNodeBuilder()
protected @Nullable AbstractTree	getParentOrNull()
@NotNull String	getPath()
@Nullable TreeType	getType()
int	hashCode()
protected boolean	isHidden(@NotNull String name)	Determine whether an item should be hidden.
boolean	isRoot()
boolean	orderBefore(@Nullable String name)	Orders this Tree before the sibling tree with the given name.
boolean	remove()	Remove this tree instance.
void	removeProperty(@NotNull 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.
<T> void	setProperty(@NotNull String name, T value)	Set a property state
<T> void	setProperty(@NotNull String name, T value, @NotNull Type<T> type)	Set a property state
void	setProperty(@NotNull PropertyState property)	Set a property state
void	setType(@NotNull 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(@NotNull
                     @NotNull NodeState rootState)

ImmutableTree

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

ImmutableTree

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

Method Detail

getType

@Nullable
public @Nullable TreeType getType()

Specified by:

getType in interface TreeTypeAware

setType

public void setType(@NotNull
                    @NotNull TreeType type)

Specified by:

setType in interface TreeTypeAware

createChild

@NotNull
protected @NotNull ImmutableTree createChild(@NotNull
                                             @NotNull 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

@Nullable
protected @Nullable AbstractTree getParentOrNull()

Specified by:

getParentOrNull in class AbstractTree

Returns:

the parent of this tree or null for the root

getNodeBuilder

@NotNull
protected @NotNull NodeBuilder getNodeBuilder()

Specified by:

getNodeBuilder in class AbstractTree

Returns:

The NodeBuilder for the underlying node state

isHidden

protected boolean isHidden(@NotNull
                           @NotNull 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

@NotNull
protected @NotNull String[] getInternalNodeNames()

Overrides:

getInternalNodeNames in class AbstractTree

getName

@NotNull
public @NotNull String getName()

Specified by:

getName in interface Tree

Returns:

the name of this Tree instance.

getPath

@NotNull
public @NotNull 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

@NotNull
public @NotNull ImmutableTree getChild(@NotNull
                                       @NotNull 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

@NotNull
public @NotNull Tree addChild(@NotNull
                              @NotNull 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
                           @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(@NotNull
                        @NotNull 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(@NotNull
                            @NotNull String name,
                            @NotNull
                            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(@NotNull
                            @NotNull String name,
                            @NotNull
                            T value,
                            @NotNull
                            @NotNull 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(@NotNull
                           @NotNull 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