org.apache.jackrabbit.oak.api

Interface Tree

public interface Tree

A tree instance represents a snapshot of the ContentRepository tree at the time the instance was acquired from a ContentSession. Tree instances may become invalid over time due to garbage collection of old content, at which point an outdated snapshot will start throwing IllegalStateExceptions to indicate that the snapshot is no longer available.

Order and orderability

The children of a Tree are generally unordered. That is, the sequence of the children returned by getChildren() may change over time as this Tree is modified either directly or through some other session. Calling orderBefore(String) will persist the current order and maintain the order as new children are added or removed. In this case a new child will be inserted after the last child as seen by getChildren().

State and state transitions

A tree instance belongs to the client and its state is only modified in response to method calls made by the client. The various accessors on this interface mirror these of the underlying NodeState interface. However, since instances of this class are mutable return values may change between invocations.

All tree instances created in the context of a content session become invalid after the content session is closed. Any method called on an invalid tree instance will throw an InvalidStateException.

Tree instances may become non existing after a call to Root.refresh(), Root.rebase() or Root.commit(). Any write access to non existing Tree instances will cause an InvalidStateException.

Thread safety

Tree instances are not thread-safe for write access, so writing clients need to ensure that they are not accessed concurrently from multiple threads. Instances are however thread-safe for read access, so implementations need to ensure that all reading clients see a coherent state.

Visibility and access control

The data returned by this class and intermediary objects such as are access controlled governed by the ContentSession instance from which the containing Root was obtained.

Existence and iterability of trees

The getChild(String) method is special in that it never returns a null value, even if the named tree does not exist. Instead a client should use the exists() method on the returned tree to check whether that tree exists.

The iterability of a tree is a related to existence. A node state is iterable if it is included in the return values of the getChildrenCount(long) and getChildren() methods. An iterable node is guaranteed to exist, though not all existing nodes are necessarily iterable.

Furthermore, a non-existing node is guaranteed to contain no properties or iterable child nodes. It can, however contain non-iterable children. Such scenarios are typically the result of access control restrictions.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Tree.Status Status of an item in a Tree

Field Summary

Fields

Modifier and Type	Field and Description
static Tree[]	EMPTY_ARRAY Empty array of trees.

Method Summary

Modifier and Type	Method and Description
@NotNull Tree	addChild(@NotNull java.lang.String name) Add a child with the given name.
boolean	exists() Determine whether this tree has been removed or does not exist otherwise (e.g.
@NotNull Tree	getChild(@NotNull java.lang.String name) Get a possibly non existing child of this Tree.
@NotNull java.lang.Iterable<Tree>	getChildren() All accessible children of this Tree instance.
long	getChildrenCount(long max) Determine the number of children of this Tree instance taking access restrictions into account.
@NotNull java.lang.String	getName()
@NotNull Tree	getParent()
@NotNull java.lang.String	getPath()
@NotNull java.lang.Iterable<? extends PropertyState>	getProperties() All accessible property states.
@Nullable PropertyState	getProperty(@NotNull java.lang.String name) Get a property state
long	getPropertyCount() Determine the number of properties accessible to the current content session.
@Nullable Tree.Status	getPropertyStatus(@NotNull java.lang.String name) Get the Status of a property state or null.
@NotNull Tree.Status	getStatus() Get the Status of this tree instance.
boolean	hasChild(@NotNull java.lang.String name) Determine if a child of this Tree instance exists.
boolean	hasProperty(@NotNull java.lang.String name) Determine if a property state exists and is accessible.
boolean	isRoot()
boolean	orderBefore(@Nullable java.lang.String name) Orders this Tree before the sibling tree with the given name.
boolean	remove() Remove this tree instance.
void	removeProperty(@NotNull java.lang.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(@NotNull PropertyState property) Set a property state
<T> void	setProperty(@NotNull java.lang.String name, T value) Set a property state
<T> void	setProperty(@NotNull java.lang.String name, T value, @NotNull Type<T> type) Set a property state

Field Detail

EMPTY_ARRAY

static final Tree[] EMPTY_ARRAY

Empty array of trees.

Method Detail

getName

@NotNull
@NotNull java.lang.String getName()

Returns:

the name of this Tree instance.

isRoot

boolean isRoot()

Returns:

true iff this is the root

getPath

@NotNull
@NotNull java.lang.String getPath()

Returns:

the absolute path of this Tree instance from its Root.

getStatus

@NotNull
@NotNull Tree.Status getStatus()

Get the Status of this tree instance.

Returns:

The status of this tree instance.

exists

boolean exists()

Determine whether this tree has been removed or does not exist otherwise (e.g. caused by a refresh, rebase or commit) or is not visible due to access control restriction or does not exist at all.

Returns:

true if this tree exists, false otherwise.

getParent

@NotNull
@NotNull Tree getParent()

Returns:

the possibly non existent parent of this Tree.

Throws:

java.lang.IllegalStateException - if called on the root tree.

getProperty

@Nullable
@Nullable PropertyState getProperty(@NotNull
                                              @NotNull java.lang.String name)

Get a property state

Parameters:

name - The name of the property state.

Returns:

the property state with the given name or null if no such property state exists or the property is not accessible.

getPropertyStatus

@Nullable
@Nullable Tree.Status getPropertyStatus(@NotNull
                                                  @NotNull java.lang.String name)

Get the Status of a property state or null.

Parameters:

name - The name of the property state.

Returns:

The status of the property state with the given name or null in no such property state exists or if the name refers to a property that is not accessible.

hasProperty

boolean hasProperty(@NotNull
                    @NotNull java.lang.String name)

Determine if a property state exists and is accessible.

Parameters:

name - The name of the property state

Returns:

true if and only if a property with the given name exists and is accessible.

getPropertyCount

long getPropertyCount()

Determine the number of properties accessible to the current content session.

Returns:

The number of accessible properties.

getProperties

@NotNull
@NotNull java.lang.Iterable<? extends PropertyState> getProperties()

All accessible property states. The returned Iterable has snapshot semantics. That is, it reflect the state of this Tree instance at the time of the call. Later changes to this instance are no visible to iterators obtained from the returned iterable.

Returns:

An Iterable for all accessible property states.

getChild

@NotNull
@NotNull Tree getChild(@NotNull
                                @NotNull java.lang.String name)
                         throws java.lang.IllegalArgumentException

Get a possibly non existing child of this Tree.

Parameters:

name - The name of the child to retrieve.

Returns:

The child with the given name.

Throws:

java.lang.IllegalArgumentException - if the given name is invalid

hasChild

boolean hasChild(@NotNull
                 @NotNull java.lang.String name)

Determine if a child of this Tree instance exists. If no child exists or an existing child isn't accessible this method returns false.

Parameters:

name - The name of the child

Returns:

true if and only if a child with the given name exists and is accessible for the current content session.

getChildrenCount

long getChildrenCount(long max)

Determine the number of children of this Tree instance taking access restrictions into account.

If an implementation does know the exact value, it returns it (even if the value is higher than max). If the implementation does not know the exact value, and the child node count is higher than max, it may return Long.MAX_VALUE. The cost of the operation is at most O(max).

Parameters:

max - the maximum value

Returns:

the number of accessible children.

getChildren

@NotNull
@NotNull java.lang.Iterable<Tree> getChildren()

All accessible children of this Tree instance. The returned Iterable has snapshot semantics. That is, it reflect the state of this Tree instance at the time of the call. Later changes to this instance are not visible to iterators obtained from the returned iterable.

Returns:

An Iterable for all accessible children

remove

boolean remove()

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

Returns:

true if the node was removed; false otherwise.

addChild

@NotNull
@NotNull Tree addChild(@NotNull
                                @NotNull java.lang.String name)
                         throws java.lang.IllegalArgumentException

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

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.

Throws:

java.lang.IllegalArgumentException - if name is not valid.

setOrderableChildren

void setOrderableChildren(boolean enable)

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 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 getChildren() is subsequently undefined.

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

Parameters:

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

orderBefore

boolean orderBefore(@Nullable
                    @Nullable java.lang.String name)

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.

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.

Throws:

java.lang.IllegalArgumentException - if the given name is invalid

setProperty

void setProperty(@NotNull
                 @NotNull PropertyState property)

Set a property state

Parameters:

property - The property state to set

Throws:

java.lang.IllegalArgumentException - if property has a non valid name. A valid name does not start with a colon, is not empty and does not contain a forward slash.

setProperty

<T> void setProperty(@NotNull
                     @NotNull java.lang.String name,
                     @NotNull
                     T value)
              throws java.lang.IllegalArgumentException

Set a property state

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

Throws:

java.lang.IllegalArgumentException - if T is not one of the above types or if name is not valid.

setProperty

<T> void setProperty(@NotNull
                     @NotNull java.lang.String name,
                     @NotNull
                     T value,
                     @NotNull
                     @NotNull Type<T> type)
              throws java.lang.IllegalArgumentException

Set a property state

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.

Throws:

java.lang.IllegalArgumentException - if name is not valid.

removeProperty

void removeProperty(@NotNull
                    @NotNull java.lang.String name)

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

Parameters:

name - The name of the property