Package 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 Description
      static class  Tree.Status
      Status of an item in a Tree

    • Field Summary

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

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method 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.
      <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
      void setProperty​(@NotNull PropertyState property)
      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