Package 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 `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
`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
`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

All Methods Static Methods Instance Methods Concrete Methods
`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 `DirectoryLayer`s 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 `DirectoryLayer`s have an empty path, but `DirectoryLayer`s returned by `Directory.getDirectoryLayer()` for `Directory`s 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