Package org.apache.jackrabbit.oak.api

Interface Root

public interface Root
A Root instance serves as a container for a Tree. It is obtained from a ContentSession, which governs accessibility and visibility of the Tree and its sub trees.

All root instances created by a content session become invalid after the content session is closed. Any method called on an invalid root instance will throw an InvalidStateException.

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

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    COMMIT_PATH
    Name of the entry of the commit path in the info map in commit(java.util.Map)

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    commit()
    Atomically persists all changes made to the tree attached to this root.
    void
    commit(@NotNull Map<String,Object> info)
    Atomically persists all changes made to the tree attached to this root.
    @NotNull Blob
    createBlob(@NotNull InputStream stream)
    Reads (and closes) the given stream and returns a Blob that contains that binary.
    @Nullable Blob
    getBlob(@NotNull String reference)
    Get a blob by its reference.
    @NotNull ContentSession
    getContentSession()
    Get the ContentSession from which this root was acquired
    @NotNull QueryEngine
    getQueryEngine()
    Get the query engine.
    @NotNull Tree
    getTree(@NotNull String path)
    Retrieve the possible non existing Tree at the given absolute path.
    boolean
    hasPendingChanges()
    Determine whether there are changes on this tree
    boolean
    move(String sourcePath, String destPath)
    Move the child located at sourcePath to a child at destPath.
    void
    rebase()
    Rebase this root instance to the latest revision.
    void
    refresh()
    Reverts all changes made to this root and refreshed to the latest trunk.

  • Field Details

  • Method Details

    • move

      boolean move(String sourcePath, String destPath)
      Move the child located at sourcePath to a child at destPath. Both paths must be absolute and resolve to a child located beneath this root.
      This method does nothing and returns false if
      • the tree at sourcePath does not exist or is not accessible,
      • the parent of the tree at destinationPath does not exist or is not accessible,
      • a tree already exists at destinationPath.
      If a tree at destinationPath exists but is not accessible to the editing content session this method succeeds but a subsequent commit() will detect the violation and fail.
      Parameters:
      sourcePath - The source path
      destPath - The destination path
      Returns:
      true on success, false otherwise.

    • getTree

      @NotNull @NotNull Tree getTree(@NotNull @NotNull String path)
      Retrieve the possible non existing Tree at the given absolute path. The path must resolve to a tree in this root.
      Parameters:
      path - absolute path to the tree
      Returns:
      tree at the given path.

    • rebase

      void rebase()
      Rebase this root instance to the latest revision. After a call to this method, trees obtained through getTree(String) may become non existing.

    • refresh

      void refresh()
      Reverts all changes made to this root and refreshed to the latest trunk. After a call to this method, trees obtained through getTree(String) may become non existing.

    • commit

      void commit(@NotNull @NotNull Map<String,Object> info) throws CommitFailedException
      Atomically persists all changes made to the tree attached to this root.

      If info contains a mapping for COMMIT_PATH and the associated value is a string, implementations may throw a CommitFailedException if there are changes outside of the subtree designated by that path and the implementation does not support such partial commits. However all implementation must handler the case where a path designates a subtree that contains all unpersisted changes.

      The info map is passed to the underlying storage as a part of the internal commit information attached to this commit. The commit information will be made available to local observers but will not be visible to observers on other cluster nodes.

      After a successful operation the root is automatically refreshed, such that trees previously obtained through getTree(String) may become non existing.

      Parameters:
      info - commit information
      Throws:
      CommitFailedException - if the commit failed

    • commit

      void commit() throws CommitFailedException
      Atomically persists all changes made to the tree attached to this root. Calling this method is equivalent to calling the commit(Map info) method with an empty info map.
      Throws:
      CommitFailedException - if the commit failed

    • hasPendingChanges

      boolean hasPendingChanges()
      Determine whether there are changes on this tree
      Returns:
      true iff this tree was modified

    • getQueryEngine

      @NotNull @NotNull QueryEngine getQueryEngine()
      Get the query engine.
      Returns:
      the query engine

    • createBlob

      @NotNull @NotNull Blob createBlob(@NotNull @NotNull InputStream stream) throws IOException
      Reads (and closes) the given stream and returns a Blob that contains that binary. The returned blob will remain valid at least until the ContentSession of this root is closed, or longer if it has been committed as a part of a content update.

      The implementation may decide to persist the blob at any point during or between this method method call and a commit() that includes the blob, but the blob will become visible to other sessions only after such a commit.

      Parameters:
      stream - the stream for reading the binary
      Returns:
      the blob that was created
      Throws:
      IOException - if the stream could not be read

    • getBlob

      @Nullable @Nullable Blob getBlob(@NotNull @NotNull String reference)
      Get a blob by its reference.
      Parameters:
      reference - reference to the blob
      Returns:
      blob or null if the reference does not resolve to a blob.
      See Also:

    • getContentSession

      @NotNull @NotNull ContentSession getContentSession()
      Get the ContentSession from which this root was acquired
      Returns:
      the associated ContentSession
      Throws:
      UnsupportedOperationException