Class DirectoryLayer
- All Implemented Interfaces:
Directory
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
FieldsModifier and TypeFieldDescriptionstatic final Subspace
The default contentSubspace
used by aDirectoryLayer
when none is specified.static final Subspace
The default nodeSubspace
used by aDirectoryLayer
when none is specified.static final byte[]
The layer string to pass toDirectory.createOrOpen(TransactionContext, List, byte[])
orDirectory.create(TransactionContext, List, byte[])
to create aDirectoryPartition
. -
Constructor Summary
ConstructorsConstructorDescriptionConstructor 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
Modifier and TypeMethodDescriptioncreate
(TransactionContext tcx, List<String> path, byte[] layer, byte[] prefix) Creates a directory located atpath
(creating parent directories if necessary).createOrOpen
(TransactionContext tcx, List<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
Tests whether thisDirectoryLayer
is equal torhs
.Returnstrue
.exists
(ReadTransactionContext tcx, List<String> path) Checks if the directory located atpath
exists.static DirectoryLayer
Gets the default instance of the DirectoryLayer.Returnsthis
.byte[]
getLayer()
Returns the layer byte string for thisDirectoryLayer
, which is always an empty array.getPath()
Gets the path for the root node of thisDirectoryLayer
.int
hashCode()
Produces a hash of thisDirectoryLayer
based on its path and subspaces.list
(ReadTransactionContext tcx, List<String> path) List the subdirectories of the directory at a givenpath
.Moves the directory located atoldPath
tonewPath
.moveTo
(TransactionContext tcx, List<String> newAbsolutePath) This method should not be called on aDirectoryLayer
.open
(ReadTransactionContext tcx, List<String> path, byte[] layer) Opens the directory located atpath
.remove
(TransactionContext tcx, List<String> path) Removes the directory located atpath
and all of its subdirectories, as well as all of their contents.removeIfExists
(TransactionContext tcx, List<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
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface com.apple.foundationdb.directory.Directory
create, create, createOrOpen, list, open, remove, removeIfExists
-
Field Details
-
DEFAULT_NODE_SUBSPACE
The default nodeSubspace
used by aDirectoryLayer
when none is specified. -
DEFAULT_CONTENT_SUBSPACE
The default contentSubspace
used by aDirectoryLayer
when none is specified. -
PARTITION_LAYER
public static final byte[] PARTITION_LAYERThe layer string to pass toDirectory.createOrOpen(TransactionContext, List, byte[])
orDirectory.create(TransactionContext, List, byte[])
to create aDirectoryPartition
.
-
-
Constructor Details
-
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:
-
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
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
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 Details
-
createWithNodeSubspace
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
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
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
Tests whether thisDirectoryLayer
is equal torhs
. TwoDirectoryLayer
s are equal if they have the same node subspace, content subspace, and path. -
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. -
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
Returnsthis
.- Specified by:
getDirectoryLayer
in interfaceDirectory
- Returns:
this
-
createOrOpen
public CompletableFuture<DirectorySubspace> createOrOpen(TransactionContext tcx, List<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 CompletableFuture<DirectorySubspace> open(ReadTransactionContext tcx, List<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 CompletableFuture<DirectorySubspace> create(TransactionContext tcx, List<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 CompletableFuture<DirectorySubspace> moveTo(TransactionContext tcx, List<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 CompletableFuture<DirectorySubspace> move(TransactionContext tcx, List<String> oldPath, List<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
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
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
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
Returnstrue
.- Specified by:
exists
in interfaceDirectory
- Parameters:
tcx
- theTransactionContext
to execute this operation in- Returns:
true
-
exists
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
-