com.apple.foundationdb.directory.Directory Maven / Gradle / Ivy
/*
* Directory.java
*
* This source file is part of the FoundationDB open source project
*
* Copyright 2013-2018 Apple Inc. and the FoundationDB project authors
*
* Licensed 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 com.apple.foundationdb.directory;
import static com.apple.foundationdb.directory.DirectoryLayer.EMPTY_BYTES;
import static com.apple.foundationdb.directory.DirectoryLayer.EMPTY_PATH;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import com.apple.foundationdb.ReadTransactionContext;
import com.apple.foundationdb.TransactionContext;
/**
* Represents a directory in the {@code DirectoryLayer}. A {@code Directory} stores the path
* at which it is located and the layer that was used to create it.
*
* The {@code Directory} interface contains methods to operate on itself and its
* subdirectories.
*/
public interface Directory {
/**
* Gets the path represented by this {@code Directory}.
*
* @return this {@code Directory}'s path
*/
List getPath();
/**
* Gets the layer byte string that was stored when this {@code Directory}
* was created.
*
* @return this {@code Directory}'s layer byte string
*/
byte[] getLayer();
/**
* Get the {@link DirectoryLayer} that was used to create this {@code Directory}.
*
* @return the {@link DirectoryLayer} that created this {@link Directory}
*/
DirectoryLayer getDirectoryLayer();
/**
* Creates or opens the subdirectory of this {@code Directory} located at {@code subpath}
* (creating parent directories, if necessary).
*
* @param tcx the {@link TransactionContext} to execute this operation in
* @param subpath a {@code List} specifying a subpath of this {@code Directory}
* @return a {@link CompletableFuture} which will be set to the created or opened {@link DirectorySubspace}
*/
default CompletableFuture createOrOpen(TransactionContext tcx, List subpath) {
return createOrOpen(tcx, subpath, EMPTY_BYTES);
}
/**
* Creates or opens the subdirectory of this {@code Directory} located at {@code subpath}
* (creating parent directories, if necessary). If the directory is new, then the {@code layer}
* byte string will be recorded as its layer. If the directory already exists, the {@code layer}
* byte string will be compared against the {@code layer} set when the directory was created.
*
* The returned {@link CompletableFuture} can be set to the following errors:
*
* - {@link MismatchedLayerException} - if the directory has already been created with a different {@code layer} byte string
*
*
* @param tcx the {@link TransactionContext} to execute this operation in
* @param subpath a {@code List} specifying a subpath of this {@code Directory}
* @param layer a {@code byte[]} specifying a layer to set on a new directory or check for on an existing directory
* @return a {@link CompletableFuture} which will be set to the created or opened {@link DirectorySubspace}
*/
CompletableFuture createOrOpen(TransactionContext tcx, List subpath, byte[] layer);
/**
* Opens the subdirectory of this {@code Directory} located at {@code subpath}.
*
* The returned {@link CompletableFuture} can be set to the following errors:
*
* - {@link NoSuchDirectoryException} - if the directory does not exist
*
*
* @param tcx the {@link ReadTransactionContext} to execute this operation in
* @param subpath a {@code List} specifying a subpath of this {@code Directory}
* @return a {@link CompletableFuture} which will be set to the opened {@link DirectorySubspace}
*/
default CompletableFuture open(ReadTransactionContext tcx, List subpath) {
return open(tcx, subpath, EMPTY_BYTES);
}
/**
* Opens the subdirectory of this {@code Directory} located at {@code subpath}.
* The {@code layer} byte string will be compared against the {@code layer} set when
* the directory was created.
*
* The returned {@link CompletableFuture} can be set to the following errors:
*
* - {@link MismatchedLayerException} - if the directory was created with a different {@code layer} byte string
* - {@link NoSuchDirectoryException} - if the directory does not exist
*
*
* @param tcx the {@link ReadTransactionContext} to execute this operation in
* @param subpath a {@code List} specifying a subpath of this {@code Directory}
* @param layer a {@code byte[]} specifying the expected layer
* @return a {@link CompletableFuture} which will be set to the opened {@link DirectorySubspace}
*/
CompletableFuture open(ReadTransactionContext tcx, List subpath, byte[] layer);
/**
* Creates a subdirectory of this {@code Directory} located at {@code subpath}
* (creating parent directories if necessary).
*
* The returned {@link CompletableFuture} can be set to the following errors:
*
* - {@link DirectoryAlreadyExistsException} - if the given directory already exists
*
*
* @param tcx the {@link TransactionContext} to execute this operation in
* @param subpath a {@code List} specifying a subpath of this {@code Directory}
* @return a {@link CompletableFuture} which will be set to the created {@link DirectorySubspace}
*/
default CompletableFuture create(TransactionContext tcx, List subpath) {
return create(tcx, subpath, EMPTY_BYTES);
}
/**
* Creates a subdirectory of this {@code Directory} located at {@code subpath}
* (creating parent directories if necessary). The {@code layer} byte string will be recorded as
* the new directory's layer and checked by future calls to {@link #open(ReadTransactionContext, List, byte[])}.
*
* The returned {@link CompletableFuture} can be set to the following errors:
*
* - {@link DirectoryAlreadyExistsException} - if the given directory already exists
*
*
* @param tcx the {@link TransactionContext} to execute this operation in
* @param subpath a {@code List} specifying a subpath of this {@code Directory}
* @param layer a {@code byte[]} specifying a layer to set for the directory
* @return a {@link CompletableFuture} which will be set to the created {@link DirectorySubspace}
*/
default CompletableFuture create(TransactionContext tcx, List subpath, byte[] layer) {
return create(tcx, subpath, layer, null);
}
/**
* Creates a subdirectory of this {@code Directory} located at {@code subpath}
* (creating parent directories if necessary). The {@code layer} byte string will be recorded as
* the new directory's layer and checked by future calls to {@link #open(ReadTransactionContext, List, byte[])}.
* The specified {@code prefix} will be used for this directory's contents instead of allocating a
* prefix automatically.
*
* The returned {@link CompletableFuture} can be set to the following errors:
*
* - {@link DirectoryAlreadyExistsException} - if the given directory already exists
*
*
* @param tcx the {@link TransactionContext} to execute this operation in
* @param subpath a {@code List} specifying a subpath of this {@code Directory}
* @param layer a {@code byte[]} specifying a layer to set for the directory
* @param prefix a {@code byte[]} specifying the key prefix to use for the directory's contents
* @return a {@link CompletableFuture} which will be set to the created {@link DirectorySubspace}
*/
CompletableFuture create(TransactionContext tcx, List subpath, byte[] layer, byte[] prefix);
/**
* Moves this {@code Directory} to the specified {@code newAbsolutePath}.
*
* There is no effect on the physical prefix of the given directory, or on clients that already
* have the directory open.
*
*
* It is invalid to move a directory to:
*
*
* - A location where a directory already exists
* - A location whose parent does not exist
* - A subdirectory of itself
* - A different partition
*
*
*
* The returned {@link CompletableFuture} can be set to the following errors:
*
* - {@link NoSuchDirectoryException} - if this {@code Directory} doesn't exist
* - {@link DirectoryAlreadyExistsException} - if a directory already exists at {@code newAbsolutePath}
* - {@link DirectoryMoveException} - if an invalid move location is specified
*
*
* @param tcx the {@link TransactionContext} to execute this operation in
* @param newAbsolutePath a {@code List} specifying the new absolute path for this {@code Directory}
* @return a {@link CompletableFuture} which will be set to the {@link DirectorySubspace} for this {@code Directory}
* at its new location.
*/
CompletableFuture moveTo(TransactionContext tcx, List newAbsolutePath);
/**
* Moves the subdirectory of this {@code Directory} located at {@code oldSubpath} to {@code newSubpath}.
*
*
* There is no effect on the physical prefix of the given directory, or on clients that already
* have the directory open.
*
*
* It is invalid to move a directory to:
*
*
* - A location where a directory already exists
* - A location whose parent does not exist
* - A subdirectory of itself
* - A different partition
*
*
*
* The returned {@link CompletableFuture} can be set to the following errors:
*
* - {@link NoSuchDirectoryException} - if no {@code Directory} exists at {@code oldSubpath}
* - {@link DirectoryAlreadyExistsException} - if a directory already exists at {@code newSubpath}
* - {@link DirectoryMoveException} - if an invalid move location is specified
*
*
* @param tcx the {@link TransactionContext} to execute this operation in
* @param oldSubpath a {@code List} specifying the subpath of the directory to move
* @param newSubpath a {@code List} specifying the subpath to move to
* @return a {@link CompletableFuture} which will be set to the {@link DirectorySubspace} for this {@code Directory}
* at its new location.
*/
CompletableFuture move(TransactionContext tcx, List oldSubpath, List newSubpath);
/**
* Removes this {@code Directory} and all of its subdirectories, as well as all of their contents.
* This should not be called on the root directory, or it will result in the returned future being
* set to a {@link DirectoryException}.
*
*
* Warning: Clients that have already opened the directory might
* still insert data into its contents after it is removed.
*
*
* The returned {@link CompletableFuture} can be set to the following errors:
*
* - {@link NoSuchDirectoryException} - if this {@code Directory} doesn't exist
* - {@link DirectoryException} - if this is called on the root directory
*
*
* @param tcx the {@link TransactionContext} to execute this operation in
* @return a {@link CompletableFuture} which will be set once this {@code Directory} has been removed
*/
default CompletableFuture remove(TransactionContext tcx) {
return remove(tcx, EMPTY_PATH);
}
/**
* Removes the subdirectory of this {@code Directory} located at {@code subpath} and all of its subdirectories,
* as well as all of their contents.
*
*
* Warning: Clients that have already opened the directory might
* still insert data into its contents after it is removed.
*
*
* The returned {@link CompletableFuture} can be set to the following errors:
*
* - {@link NoSuchDirectoryException} - if no directory exists at {@code subpath}
*
*
* @param tcx the {@link TransactionContext} to execute this operation in
* @param subpath a {@code List} specifying a subpath of this {@code Directory}
* @return a {@link CompletableFuture} which will be set once the {@code Directory} has been removed
*/
CompletableFuture remove(TransactionContext tcx, List subpath);
/**
* Removes this {@code Directory} and all of its subdirectories, as well as all of their contents.
*
*
* Warning: Clients that have already opened the directory might
* still insert data into its contents after it is removed.
*
*
* @param tcx the {@link TransactionContext} to execute this operation in
* @return a {@link CompletableFuture} which will be set to true once this {@code Directory} has been removed,
* or false if it didn't exist.
*/
default CompletableFuture removeIfExists(TransactionContext tcx) {
return removeIfExists(tcx, EMPTY_PATH);
}
/**
* Removes the subdirectory of this {@code Directory} located at {@code subpath} and all of its subdirectories,
* as well as all of their contents.
*
*
* Warning: Clients that have already opened the directory might
* still insert data into its contents after it is removed.
*
*
* @param tcx the {@link TransactionContext} to execute this operation in
* @param subpath a {@code List} specifying a subpath of this {@code Directory}
* @return a {@link CompletableFuture} which will be set to true once the {@code Directory} has been removed,
* or false if it didn't exist.
*/
CompletableFuture removeIfExists(TransactionContext tcx, List subpath);
/**
* List the subdirectories of this directory.
*
* The returned {@link CompletableFuture} can be set to the following errors:
*
* - {@link NoSuchDirectoryException} - if this {@code Directory} doesn't exists
*
*
* @param tcx the {@link ReadTransactionContext} to execute this operation in
* @return a {@link CompletableFuture} which will be set to a {@code List} of names of the subdirectories
* of this {@code Directory}. Each name is a unicode string representing the last component of a
* subdirectory's path.
*/
default CompletableFuture> list(ReadTransactionContext tcx) {
return list(tcx, EMPTY_PATH);
}
/**
* List the subdirectories of this directory at a given {@code subpath}.
*
* The returned {@link CompletableFuture} can be set to the following errors:
*
* - {@link NoSuchDirectoryException} - if no directory exists at {@code subpath}
*
*
* @param tcx the {@link ReadTransactionContext} to execute this operation in
* @param subpath a {@code List} specifying a subpath of this {@code Directory}
* @return a {@link CompletableFuture} which will be set to a {@code List} of names of the subdirectories
* of the directory at {@code subpath}. Each name is a unicode string representing the last component
* of a subdirectory's path.
*/
CompletableFuture> list(ReadTransactionContext tcx, List subpath);
/**
* Checks if this {@code Directory} exists.
*
* @param tcx the {@link ReadTransactionContext} to execute this operation in
* @return a {@link CompletableFuture} which will be set to {@code true} if this {@code Directory} exists, or {@code false} if it
* doesn't
*/
default CompletableFuture exists(ReadTransactionContext tcx) {
return exists(tcx, EMPTY_PATH);
}
/**
* Checks if the subdirectory of this {@code Directory} located at {@code subpath} exists.
*
* @param tcx the {@link TransactionContext} to execute this operation in
* @param subpath a {@code List} specifying a subpath of this {@code Directory}
* @return a {@link CompletableFuture} which will be set to {@code true} if the specified subdirectory exists, or {@code false} if it
* doesn't
*/
CompletableFuture exists(ReadTransactionContext tcx, List subpath);
}