org.apache.jackrabbit.oak.api.Root Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.jackrabbit.oak.api;
import java.io.IOException;
import java.io.InputStream;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import org.apache.jackrabbit.oak.spi.commit.CommitHook;
/**
* A {@code Root} instance serves as a container for a {@link Tree}. It is
* obtained from a {@link ContentSession}, which governs accessibility and
* visibility of the {@code 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 {@code InvalidStateException}.
*
* {@link Tree} instances may become non existing after a call to
* {@link #refresh()}, {@link #rebase()} or {@link #commit(CommitHook... hooks)}.
* Any write access to non existing {@code Tree} instances will cause an
* {@code InvalidStateException}.
* @see Tree Existence and iterability of trees
*/
public interface Root {
/**
* Move the child located at {@code sourcePath} to a child at {@code destPath}.
* Both paths must be absolute and resolve to a child located beneath this
* root.
*
* This method does nothing and returns {@code false} if
*
* - the tree at {@code sourcePath} does not exist or is not accessible,
* - the parent of the tree at {@code destinationPath} does not exist or is not accessible,
* - a tree already exists at {@code destinationPath}.
*
* If a tree at {@code destinationPath} exists but is not accessible to the
* editing content session this method succeeds but a subsequent
* {@link #commit(CommitHook... hooks)} will detect the violation and fail.
*
* @param sourcePath The source path
* @param destPath The destination path
* @return {@code true} on success, {@code false} otherwise.
*/
boolean move(String sourcePath, String destPath);
/**
* Copy the child located at {@code sourcePath} to a child at {@code destPath}.
* Both paths must be absolute and resolve to a child located in this root.
*
* This method does nothing an returns {@code false} if
*
* - The tree at {@code sourcePath} does exist or is not accessible,
* - the parent of the tree at {@code destinationPath} does not exist or is not accessible,
* - a tree already exists at {@code destinationPath}.
*
* If a tree at {@code destinationPath} exists but is not accessible to the
* editing content session this method succeeds but a subsequent
* {@link #commit(CommitHook... hooks)} will detect the violation and fail.
*
* @param sourcePath source path
* @param destPath destination path
* @return {@code true} on success, {@code false} otherwise.
*/
boolean copy(String sourcePath, String destPath);
/**
* Retrieve the possible non existing {@code Tree} at the given absolute {@code path}.
* The path must resolve to a tree in this root.
*
* @param path absolute path to the tree
* @return tree at the given path.
*/
@Nonnull
Tree getTree(@Nonnull String path);
/**
* Rebase this root instance to the latest revision. After a call to this method,
* trees obtained through {@link #getTree(String)} may become non existing.
*/
void rebase();
/**
* Reverts all changes made to this root and refreshed to the latest trunk.
* After a call to this method, trees obtained through {@link #getTree(String)}
* may become non existing.
*/
void refresh();
/**
* Atomically persists all changes made to the tree attached to this root
* at the given {@code path}. An implementations may throw a
* {@code CommitFailedException} if there are changes outside of the subtree
* designated by {@code path} and the implementation does not support
* such partial commits. However all implementation must handler the
* case where a {@code path} designates a subtree that contains all
* unpersisted changes.
*
* The message string (if given) 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
* {@link #refresh() refreshed}, such that trees previously obtained
* through {@link #getTree(String)} may become non existing.
*
* @param message custom message to be associated with this commit
* @param path of the subtree to commit
* @throws CommitFailedException if the commit failed
*/
void commit(@Nullable String message, @Nullable String path)
throws CommitFailedException;
/**
* Atomically persists all changes made to the tree attached to this root.
* Calling this method is equivalent to calling the
* {@link #commit(String, String)} method with {@code null} parameters for
* {@code message} and {@code path}.
*
* @throws CommitFailedException if the commit failed
*/
void commit() throws CommitFailedException;
/**
* Determine whether there are changes on this tree
* @return {@code true} iff this tree was modified
*/
boolean hasPendingChanges();
/**
* Get the query engine.
*
* @return the query engine
*/
@Nonnull
QueryEngine getQueryEngine();
/**
* Reads (and closes) the given stream and returns a {@link Blob} that
* contains that binary. The returned blob will remain valid at least
* until the {@link 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 {@link #commit()}
* that includes the blob, but the blob will become visible to other
* sessions only after such a commit.
*
* @param stream the stream for reading the binary
* @return the blob that was created
* @throws IOException if the stream could not be read
*/
@Nonnull
Blob createBlob(@Nonnull InputStream stream) throws IOException;
/**
* Get the {@code ContentSession} from which this root was acquired
*
* @return the associated ContentSession
*
* @throws UnsupportedOperationException
*/
@Nonnull
ContentSession getContentSession();
}