com.apple.foundationdb.directory

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 Subspaces. 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 and Description
static Subspace	DEFAULT_CONTENT_SUBSPACE The default content Subspace used by a DirectoryLayer when none is specified.
static Subspace	DEFAULT_NODE_SUBSPACE The default node Subspace used by a DirectoryLayer when none is specified.
static byte[]	PARTITION_LAYER The layer string to pass to Directory.createOrOpen(TransactionContext, List, byte[]) or Directory.create(TransactionContext, List, byte[]) to create a DirectoryPartition.

Constructor Summary

Constructors

Constructor and Description
DirectoryLayer() Constructor for a DirectoryLayer formed with default node and content subspaces.
DirectoryLayer(boolean allowManualPrefixes) Constructor for a DirectoryLayer formed with default node and content subspaces.
DirectoryLayer(Subspace nodeSubspace, Subspace contentSubspace) Constructor for a DirectoryLayer formed with a specified node subspace and specified content subspace.
DirectoryLayer(Subspace nodeSubspace, Subspace contentSubspace, boolean allowManualPrefixes) Constructor for a DirectoryLayer formed with a specified node subspace and specified content subspace.

Method Summary

Modifier and Type	Method and Description
java.util.concurrent.CompletableFuture<DirectorySubspace>	create(TransactionContext tcx, java.util.List<java.lang.String> path, byte[] layer, byte[] prefix) Creates a directory located at path (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 at path(creating parent directories, if necessary).
static Directory	createWithContentSubspace(Subspace contentSubspace) Creates a new DirectoryLayer formed with a default node subspace and specified content subspace.
static Directory	createWithNodeSubspace(Subspace nodeSubspace) Creates a new DirectoryLayer formed with a specified node subspace and default content subspace.
boolean	equals(java.lang.Object rhs) Tests whether this DirectoryLayer is equal to rhs.
java.util.concurrent.CompletableFuture<java.lang.Boolean>	exists(ReadTransactionContext tcx) Returns true.
java.util.concurrent.CompletableFuture<java.lang.Boolean>	exists(ReadTransactionContext tcx, java.util.List<java.lang.String> path) Checks if the directory located at path exists.
static DirectoryLayer	getDefault() Gets the default instance of the DirectoryLayer.
DirectoryLayer	getDirectoryLayer() Returns this.
byte[]	getLayer() Returns the layer byte string for this DirectoryLayer, which is always an empty array.
java.util.List<java.lang.String>	getPath() Gets the path for the root node of this DirectoryLayer.
int	hashCode() Produces a hash of this DirectoryLayer 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 given path.
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 at oldPath to newPath.
java.util.concurrent.CompletableFuture<DirectorySubspace>	moveTo(TransactionContext tcx, java.util.List<java.lang.String> newAbsolutePath) This method should not be called on a DirectoryLayer.
java.util.concurrent.CompletableFuture<DirectorySubspace>	open(ReadTransactionContext tcx, java.util.List<java.lang.String> path, byte[] layer) Opens the directory located at path.
java.util.concurrent.CompletableFuture<java.lang.Void>	remove(TransactionContext tcx, java.util.List<java.lang.String> path) Removes the directory located at path 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 at subpath 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 node Subspace used by a DirectoryLayer when none is specified.

DEFAULT_CONTENT_SUBSPACE

public static final Subspace DEFAULT_CONTENT_SUBSPACE

The default content Subspace used by a DirectoryLayer when none is specified.

PARTITION_LAYER

public static final byte[] PARTITION_LAYER

The layer string to pass to Directory.createOrOpen(TransactionContext, List, byte[]) or Directory.create(TransactionContext, List, byte[]) to create a DirectoryPartition.

Constructor Detail

DirectoryLayer

public DirectoryLayer()

Constructor for a DirectoryLayer formed with default node and content subspaces. A DirectoryLayer 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 to Directory.create(TransactionContext, List, byte[], byte[]).

See Also:

getDefault()

DirectoryLayer

public DirectoryLayer(boolean allowManualPrefixes)

Constructor for a DirectoryLayer formed with default node and content subspaces. A DirectoryLayer 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 to Directory.create(TransactionContext, List, byte[], byte[])

DirectoryLayer

public DirectoryLayer(Subspace nodeSubspace,
                      Subspace contentSubspace)

Constructor for a DirectoryLayer formed with a specified node subspace and specified content subspace. A DirectoryLayer 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 to Directory.create(TransactionContext, List, byte[], byte[]).

Parameters:

nodeSubspace - a Subspace used to store directory metadata

contentSubspace - a Subspace used to store directory content

DirectoryLayer

public DirectoryLayer(Subspace nodeSubspace,
                      Subspace contentSubspace,
                      boolean allowManualPrefixes)

Constructor for a DirectoryLayer formed with a specified node subspace and specified content subspace. A DirectoryLayer 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 - a Subspace used to store directory metadata

contentSubspace - a Subspace used to store directory content

allowManualPrefixes - whether or not prefixes can be specified in calls to Directory.create(TransactionContext, List, byte[], byte[])

Method Detail

createWithNodeSubspace

public static Directory createWithNodeSubspace(Subspace nodeSubspace)

Creates a new DirectoryLayer formed with a specified node subspace and default content subspace. Prefixes can not be specified in calls to Directory.create(TransactionContext, List, byte[], byte[]).

Parameters:

nodeSubspace - a Subspace used to store directory metadata

Returns:

a DirectoryLayer formed with nodeSubspace and a default content subspace

createWithContentSubspace

public static Directory createWithContentSubspace(Subspace contentSubspace)

Creates a new DirectoryLayer formed with a default node subspace and specified content subspace. Prefixes can not be specified in calls to Directory.create(TransactionContext, List, byte[], byte[]).

Parameters:

contentSubspace - a Subspace used to store directory content

Returns:

a DirectoryLayer formed with a contentSubspace 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 to Directory.create(TransactionContext, List, byte[], byte[]).

Returns:

the default DirectoryLayer

equals

public boolean equals(java.lang.Object rhs)

Tests whether this DirectoryLayer is equal to rhs. Two DirectoryLayers are equal if they have the same node subspace, content subspace, and path.

Overrides:

equals in class java.lang.Object

Parameters:

rhs - the object to check for equality

Returns:

true if this DirectoryLayer and rhs are equal

hashCode

public int hashCode()

Produces a hash of this DirectoryLayer 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 class java.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 this DirectoryLayer. Normally constructed DirectoryLayers have an empty path, but DirectoryLayers returned by Directory.getDirectoryLayer() for Directorys inside of a partition could have non-empty paths.

Specified by:

getPath in interface Directory

Returns:

the path for the root node of this DirectoryLayer

getLayer

public byte[] getLayer()

Returns the layer byte string for this DirectoryLayer, which is always an empty array.

Specified by:

getLayer in interface Directory

Returns:

an empty byte array

getDirectoryLayer

public DirectoryLayer getDirectoryLayer()

Returns this.

Specified by:

getDirectoryLayer in interface Directory

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 at path(creating parent directories, if necessary). If the directory is new, then the layer byte string will be recorded as its layer. If the directory already exists, the layer byte string will be compared against the layer 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 different layer byte string

Specified by:

createOrOpen in interface Directory

Parameters:

tcx - the TransactionContext to execute this operation in

path - a List<String> specifying a path

layer - a byte[] 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 opened DirectorySubspace

open

public java.util.concurrent.CompletableFuture<DirectorySubspace> open(ReadTransactionContext tcx,
                                                                      java.util.List<java.lang.String> path,
                                                                      byte[] layer)

Opens the directory located at path. The layer byte string will be compared against the layer set when the directory was created.

The returned CompletableFuture can be set to the following errors:

• MismatchedLayerException - if the directory was created with a different layer byte string
• NoSuchDirectoryException - if the directory does not exist

Specified by:

open in interface Directory

Parameters:

tcx - the TransactionContext to execute this operation in

path - a List<String> specifying a path

layer - a byte[] specifying the expected layer

Returns:

a CompletableFuture which will be set to the opened DirectorySubspace

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 at path (creating parent directories if necessary). The layer byte string will be recorded as the new directory's layer and checked by future calls to open(ReadTransactionContext, List, byte[]). The specified prefix 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 interface Directory

Parameters:

tcx - the TransactionContext to execute this operation in

path - a List<String> specifying a path of this Directory

layer - a byte[] specifying a layer to set for the directory

prefix - a byte[] specifying the key prefix to use for the directory's contents

Returns:

a CompletableFuture which will be set to the created DirectorySubspace

moveTo

public java.util.concurrent.CompletableFuture<DirectorySubspace> moveTo(TransactionContext tcx,
                                                                        java.util.List<java.lang.String> newAbsolutePath)

This method should not be called on a DirectoryLayer. Calling this method will result in the returned CompletableFuture being set to a DirectoryMoveException.

The returned CompletableFuture can be set to the following errors:

• DirectoryMoveException

Specified by:

moveTo in interface Directory

Parameters:

tcx - the TransactionContext to execute this operation in

newAbsolutePath - a List<String> specifying a path

Returns:

a CompletableFuture which will be set to a DirectoryMoveException

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 at oldPath to newPath.

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 no Directory exists at oldPath
• DirectoryAlreadyExistsException - if a directory already exists at newPath
• DirectoryMoveException - if an invalid move location is specified

Specified by:

move in interface Directory

Parameters:

tcx - the TransactionContext to execute this operation in

oldPath - a List<String> specifying the path of the directory to move

newPath - a List<String> specifying the path to move to

Returns:

a CompletableFuture which will be set to the DirectorySubspace for this Directory 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 at path 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 at path

Specified by:

remove in interface Directory

Parameters:

tcx - the TransactionContext to execute this operation in

path - a List<String> specifying a path

Returns:

a CompletableFuture which will be set once the Directory 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 at 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.

Specified by:

removeIfExists in interface Directory

Parameters:

tcx - the TransactionContext to execute this operation in

path - a List<String> specifying a path

Returns:

a CompletableFuture which will be set to true once the Directory 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 given path.

The returned CompletableFuture can be set to the following errors:

• NoSuchDirectoryException - if no directory exists at path

Specified by:

list in interface Directory

Parameters:

tcx - the ReadTransactionContext to execute this operation in

path - a List<String> specifying a path

Returns:

a CompletableFuture which will be set to a List<String> of names of the subdirectories of the directory at path. 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)

Returns true.

Specified by:

exists in interface Directory

Parameters:

tcx - the TransactionContext 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 at path exists.

Specified by:

exists in interface Directory

Parameters:

tcx - the TransactionContext to execute this operation in

path - a List<String> specifying a path of this Directory

Returns:

a CompletableFuture which will be set to true if the specified directory exists, or false if it doesn't