Class DirectoryLayer
- java.lang.Object
-
- com.apple.foundationdb.directory.DirectoryLayer
-
- All Implemented Interfaces:
Directory
public class DirectoryLayer extends java.lang.Object implements Directory
Provides a class for managing directories in FoundationDB.The FoundationDB API provides directories as a tool for managing related
Subspace
s. Directories are a recommended approach for administering applications. Each application should create or open at least one directory to manage its subspaces. For general guidance on directory usage, see the discussion in the Developer Guide.Directories are identified by hierarchical paths analogous to the paths in a Unix-like file system. A path is represented as a List of strings. Each directory has an associated subspace used to store its content. The layer maps each path to a short prefix used for the corresponding subspace. In effect, directories provide a level of indirection for access to subspaces.
-
-
Field Summary
Fields Modifier and Type Field Description static Subspace
DEFAULT_CONTENT_SUBSPACE
The default contentSubspace
used by aDirectoryLayer
when none is specified.static Subspace
DEFAULT_NODE_SUBSPACE
The default nodeSubspace
used by aDirectoryLayer
when none is specified.static byte[]
PARTITION_LAYER
The layer string to pass toDirectory.createOrOpen(TransactionContext, List, byte[])
orDirectory.create(TransactionContext, List, byte[])
to create aDirectoryPartition
.
-
Constructor Summary
Constructors Constructor Description DirectoryLayer()
Constructor for aDirectoryLayer
formed with default node and content subspaces.DirectoryLayer(boolean allowManualPrefixes)
Constructor for aDirectoryLayer
formed with default node and content subspaces.DirectoryLayer(Subspace nodeSubspace, Subspace contentSubspace)
Constructor for aDirectoryLayer
formed with a specified node subspace and specified content subspace.DirectoryLayer(Subspace nodeSubspace, Subspace contentSubspace, boolean allowManualPrefixes)
Constructor for aDirectoryLayer
formed with a specified node subspace and specified content subspace.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description java.util.concurrent.CompletableFuture<DirectorySubspace>
create(TransactionContext tcx, java.util.List<java.lang.String> path, byte[] layer, byte[] prefix)
Creates a directory located atpath
(creating parent directories if necessary).java.util.concurrent.CompletableFuture<DirectorySubspace>
createOrOpen(TransactionContext tcx, java.util.List<java.lang.String> path, byte[] layer)
Creates or opens the directory located atpath
(creating parent directories, if necessary).static Directory
createWithContentSubspace(Subspace contentSubspace)
Creates a newDirectoryLayer
formed with a default node subspace and specified content subspace.static Directory
createWithNodeSubspace(Subspace nodeSubspace)
Creates a newDirectoryLayer
formed with a specified node subspace and default content subspace.boolean
equals(java.lang.Object rhs)
Tests whether thisDirectoryLayer
is equal torhs
.java.util.concurrent.CompletableFuture<java.lang.Boolean>
exists(ReadTransactionContext tcx)
Returnstrue
.java.util.concurrent.CompletableFuture<java.lang.Boolean>
exists(ReadTransactionContext tcx, java.util.List<java.lang.String> path)
Checks if the directory located atpath
exists.static DirectoryLayer
getDefault()
Gets the default instance of the DirectoryLayer.DirectoryLayer
getDirectoryLayer()
Returnsthis
.byte[]
getLayer()
Returns the layer byte string for thisDirectoryLayer
, which is always an empty array.java.util.List<java.lang.String>
getPath()
Gets the path for the root node of thisDirectoryLayer
.int
hashCode()
Produces a hash of thisDirectoryLayer
based on its path and subspaces.java.util.concurrent.CompletableFuture<java.util.List<java.lang.String>>
list(ReadTransactionContext tcx, java.util.List<java.lang.String> path)
List the subdirectories of the directory at a givenpath
.java.util.concurrent.CompletableFuture<DirectorySubspace>
move(TransactionContext tcx, java.util.List<java.lang.String> oldPath, java.util.List<java.lang.String> newPath)
Moves the directory located atoldPath
tonewPath
.java.util.concurrent.CompletableFuture<DirectorySubspace>
moveTo(TransactionContext tcx, java.util.List<java.lang.String> newAbsolutePath)
This method should not be called on aDirectoryLayer
.java.util.concurrent.CompletableFuture<DirectorySubspace>
open(ReadTransactionContext tcx, java.util.List<java.lang.String> path, byte[] layer)
Opens the directory located atpath
.java.util.concurrent.CompletableFuture<java.lang.Void>
remove(TransactionContext tcx, java.util.List<java.lang.String> path)
Removes the directory located atpath
and all of its subdirectories, as well as all of their contents.java.util.concurrent.CompletableFuture<java.lang.Boolean>
removeIfExists(TransactionContext tcx, java.util.List<java.lang.String> path)
Removes the directory located atsubpath
and all of its subdirectories, as well as all of their contents.-
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, toString, wait, wait, wait
-
Methods inherited from interface com.apple.foundationdb.directory.Directory
create, create, createOrOpen, list, open, remove, removeIfExists
-
-
-
-
Field Detail
-
DEFAULT_NODE_SUBSPACE
public static final Subspace DEFAULT_NODE_SUBSPACE
The default nodeSubspace
used by aDirectoryLayer
when none is specified.
-
DEFAULT_CONTENT_SUBSPACE
public static final Subspace DEFAULT_CONTENT_SUBSPACE
The default contentSubspace
used by aDirectoryLayer
when none is specified.
-
PARTITION_LAYER
public static final byte[] PARTITION_LAYER
The layer string to pass toDirectory.createOrOpen(TransactionContext, List, byte[])
orDirectory.create(TransactionContext, List, byte[])
to create aDirectoryPartition
.
-
-
Constructor Detail
-
DirectoryLayer
public DirectoryLayer()
Constructor for aDirectoryLayer
formed with default node and content subspaces. ADirectoryLayer
defines a new root directory. The node subspace and content subspace control where the directory metadata and contents, respectively, are stored. The default root directory has a node subspace with raw prefix\xFE
and a content subspace with no prefix. Prefixes can not be specified in calls toDirectory.create(TransactionContext, List, byte[], byte[])
.- See Also:
getDefault()
-
DirectoryLayer
public DirectoryLayer(boolean allowManualPrefixes)
Constructor for aDirectoryLayer
formed with default node and content subspaces. ADirectoryLayer
defines a new root directory. The node subspace and content subspace control where the directory metadata and contents, respectively, are stored. The default root directory has a node subspace with raw prefix\xFE
and a content subspace with no prefix.- Parameters:
allowManualPrefixes
- whether or not prefixes can be specified in calls toDirectory.create(TransactionContext, List, byte[], byte[])
-
DirectoryLayer
public DirectoryLayer(Subspace nodeSubspace, Subspace contentSubspace)
Constructor for aDirectoryLayer
formed with a specified node subspace and specified content subspace. ADirectoryLayer
defines a new root directory. The node subspace and content subspace control where the directory metadata and contents, respectively, are stored. The default root directory has a node subspace with raw prefix\xFE
and a content subspace with no prefix. Specifying more restrictive values for the node subspace and content subspace will allow using the directory layer alongside other content in a database. Prefixes can not be specified in calls toDirectory.create(TransactionContext, List, byte[], byte[])
.
-
DirectoryLayer
public DirectoryLayer(Subspace nodeSubspace, Subspace contentSubspace, boolean allowManualPrefixes)
Constructor for aDirectoryLayer
formed with a specified node subspace and specified content subspace. ADirectoryLayer
defines a new root directory. The node subspace and content subspace control where the directory metadata and contents, respectively, are stored. The default root directory has a node subspace with raw prefix\xFE
and a content subspace with no prefix. Specifying more restrictive values for the node subspace and content subspace will allow using the directory layer alongside other content in a database.- Parameters:
nodeSubspace
- aSubspace
used to store directory metadatacontentSubspace
- aSubspace
used to store directory contentallowManualPrefixes
- whether or not prefixes can be specified in calls toDirectory.create(TransactionContext, List, byte[], byte[])
-
-
Method Detail
-
createWithNodeSubspace
public static Directory createWithNodeSubspace(Subspace nodeSubspace)
Creates a newDirectoryLayer
formed with a specified node subspace and default content subspace. Prefixes can not be specified in calls toDirectory.create(TransactionContext, List, byte[], byte[])
.- Parameters:
nodeSubspace
- aSubspace
used to store directory metadata- Returns:
- a
DirectoryLayer
formed withnodeSubspace
and a default content subspace
-
createWithContentSubspace
public static Directory createWithContentSubspace(Subspace contentSubspace)
Creates a newDirectoryLayer
formed with a default node subspace and specified content subspace. Prefixes can not be specified in calls toDirectory.create(TransactionContext, List, byte[], byte[])
.- Parameters:
contentSubspace
- aSubspace
used to store directory content- Returns:
- a
DirectoryLayer
formed with acontentSubspace
and a default node subspace
-
getDefault
public static DirectoryLayer getDefault()
Gets the default instance of the DirectoryLayer. The default instance is created with the default node and content subspaces. Prefixes can not be specified in calls toDirectory.create(TransactionContext, List, byte[], byte[])
.- Returns:
- the default
DirectoryLayer
-
equals
public boolean equals(java.lang.Object rhs)
Tests whether thisDirectoryLayer
is equal torhs
. TwoDirectoryLayer
s are equal if they have the same node subspace, content subspace, and path.- Overrides:
equals
in classjava.lang.Object
- Parameters:
rhs
- the object to check for equality- Returns:
true
if thisDirectoryLayer
andrhs
are equal
-
hashCode
public int hashCode()
Produces a hash of thisDirectoryLayer
based on its path and subspaces. This satisfies the necessary requirements to allow this class to be used as keys in hash tables or as values in hash-based sets.- Overrides:
hashCode
in classjava.lang.Object
- Returns:
- a hash based on the path and subspaces of this
DirectoryLayer
-
getPath
public java.util.List<java.lang.String> getPath()
Gets the path for the root node of thisDirectoryLayer
. Normally constructedDirectoryLayer
s have an empty path, butDirectoryLayer
s returned byDirectory.getDirectoryLayer()
forDirectory
s inside of a partition could have non-empty paths.
-
getLayer
public byte[] getLayer()
Returns the layer byte string for thisDirectoryLayer
, which is always an empty array.
-
getDirectoryLayer
public DirectoryLayer getDirectoryLayer()
Returnsthis
.- Specified by:
getDirectoryLayer
in interfaceDirectory
- Returns:
this
-
createOrOpen
public java.util.concurrent.CompletableFuture<DirectorySubspace> createOrOpen(TransactionContext tcx, java.util.List<java.lang.String> path, byte[] layer)
Creates or opens the directory located atpath
(creating parent directories, if necessary). If the directory is new, then thelayer
byte string will be recorded as its layer. If the directory already exists, thelayer
byte string will be compared against thelayer
set when the directory was created.The returned
CompletableFuture
can be set to the following errors:MismatchedLayerException
- if the directory has already been created with a differentlayer
byte string
- Specified by:
createOrOpen
in interfaceDirectory
- Parameters:
tcx
- theTransactionContext
to execute this operation inpath
- aList<String>
specifying a pathlayer
- abyte[]
specifying a layer to set on a new directory or check for on an existing directory- Returns:
- a
CompletableFuture
which will be set to the created or openedDirectorySubspace
-
open
public java.util.concurrent.CompletableFuture<DirectorySubspace> open(ReadTransactionContext tcx, java.util.List<java.lang.String> path, byte[] layer)
Opens the directory located atpath
. Thelayer
byte string will be compared against thelayer
set when the directory was created.The returned
CompletableFuture
can be set to the following errors:MismatchedLayerException
- if the directory was created with a differentlayer
byte stringNoSuchDirectoryException
- if the directory does not exist
- Specified by:
open
in interfaceDirectory
- Parameters:
tcx
- theTransactionContext
to execute this operation inpath
- aList<String>
specifying a pathlayer
- abyte[]
specifying the expected layer- Returns:
- a
CompletableFuture
which will be set to the openedDirectorySubspace
-
create
public java.util.concurrent.CompletableFuture<DirectorySubspace> create(TransactionContext tcx, java.util.List<java.lang.String> path, byte[] layer, byte[] prefix)
Creates a directory located atpath
(creating parent directories if necessary). Thelayer
byte string will be recorded as the new directory's layer and checked by future calls toopen(ReadTransactionContext, List, byte[])
. The specifiedprefix
will be used for this directory's contents instead of allocating a prefix automatically.The returned
CompletableFuture
can be set to the following errors:DirectoryAlreadyExistsException
- if the given directory already exists
- Specified by:
create
in interfaceDirectory
- Parameters:
tcx
- theTransactionContext
to execute this operation inpath
- aList<String>
specifying a path of thisDirectory
layer
- abyte[]
specifying a layer to set for the directoryprefix
- abyte[]
specifying the key prefix to use for the directory's contents- Returns:
- a
CompletableFuture
which will be set to the createdDirectorySubspace
-
moveTo
public java.util.concurrent.CompletableFuture<DirectorySubspace> moveTo(TransactionContext tcx, java.util.List<java.lang.String> newAbsolutePath)
This method should not be called on aDirectoryLayer
. Calling this method will result in the returnedCompletableFuture
being set to aDirectoryMoveException
.The returned
CompletableFuture
can be set to the following errors:- Specified by:
moveTo
in interfaceDirectory
- Parameters:
tcx
- theTransactionContext
to execute this operation innewAbsolutePath
- aList<String>
specifying a path- Returns:
- a
CompletableFuture
which will be set to aDirectoryMoveException
-
move
public java.util.concurrent.CompletableFuture<DirectorySubspace> move(TransactionContext tcx, java.util.List<java.lang.String> oldPath, java.util.List<java.lang.String> newPath)
Moves the directory located atoldPath
tonewPath
.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
CompletableFuture
can be set to the following errors:NoSuchDirectoryException
- if noDirectory
exists atoldPath
DirectoryAlreadyExistsException
- if a directory already exists atnewPath
DirectoryMoveException
- if an invalid move location is specified
- Specified by:
move
in interfaceDirectory
- Parameters:
tcx
- theTransactionContext
to execute this operation inoldPath
- aList<String>
specifying the path of the directory to movenewPath
- aList<String>
specifying the path to move to- Returns:
- a
CompletableFuture
which will be set to theDirectorySubspace
for thisDirectory
at its new location.
-
remove
public java.util.concurrent.CompletableFuture<java.lang.Void> remove(TransactionContext tcx, java.util.List<java.lang.String> path)
Removes the directory located atpath
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
CompletableFuture
can be set to the following errors:NoSuchDirectoryException
- if no directory exists atpath
- Specified by:
remove
in interfaceDirectory
- Parameters:
tcx
- theTransactionContext
to execute this operation inpath
- aList<String>
specifying a path- Returns:
- a
CompletableFuture
which will be set once theDirectory
has been removed
-
removeIfExists
public java.util.concurrent.CompletableFuture<java.lang.Boolean> removeIfExists(TransactionContext tcx, java.util.List<java.lang.String> path)
Removes the directory located atsubpath
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.
- Specified by:
removeIfExists
in interfaceDirectory
- Parameters:
tcx
- theTransactionContext
to execute this operation inpath
- aList<String>
specifying a path- Returns:
- a
CompletableFuture
which will be set to true once theDirectory
has been removed, or false if it didn't exist.
-
list
public java.util.concurrent.CompletableFuture<java.util.List<java.lang.String>> list(ReadTransactionContext tcx, java.util.List<java.lang.String> path)
List the subdirectories of the directory at a givenpath
.The returned
CompletableFuture
can be set to the following errors:NoSuchDirectoryException
- if no directory exists atpath
- Specified by:
list
in interfaceDirectory
- Parameters:
tcx
- theReadTransactionContext
to execute this operation inpath
- aList<String>
specifying a path- Returns:
- a
CompletableFuture
which will be set to aList<String>
of names of the subdirectories of the directory atpath
. Each name is a unicode string representing the last component of a subdirectory's path.
-
exists
public java.util.concurrent.CompletableFuture<java.lang.Boolean> exists(ReadTransactionContext tcx)
Returnstrue
.- Specified by:
exists
in interfaceDirectory
- Parameters:
tcx
- theTransactionContext
to execute this operation in- Returns:
true
-
exists
public java.util.concurrent.CompletableFuture<java.lang.Boolean> exists(ReadTransactionContext tcx, java.util.List<java.lang.String> path)
Checks if the directory located atpath
exists.- Specified by:
exists
in interfaceDirectory
- Parameters:
tcx
- theTransactionContext
to execute this operation inpath
- aList<String>
specifying a path of thisDirectory
- Returns:
- a
CompletableFuture
which will be set totrue
if the specified directory exists, orfalse
if it doesn't
-
-