com.apple.foundationdb.directory

## Interface Directory

All Known Implementing Classes:
  DirectoryLayer, DirectorySubspace

    public interface Directory

Represents a directory in the `DirectoryLayer`. A `Directory` stores the path at which it is located and the layer that was used to create it. The `Directory` interface contains methods to operate on itself and its subdirectories.

### Method Summary

All Methods Instance Methods Abstract Methods Default Methods
`default java.util.concurrent.CompletableFuture<DirectorySubspace>` `create(TransactionContext tcx, java.util.List<java.lang.String> subpath)` Creates a subdirectory of this `Directory` located at `subpath` (creating parent directories if necessary).
`default java.util.concurrent.CompletableFuture<DirectorySubspace>` `create(TransactionContext tcx, java.util.List<java.lang.String> subpath, byte[] layer)` Creates a subdirectory of this `Directory` located at `subpath` (creating parent directories if necessary).
`java.util.concurrent.CompletableFuture<DirectorySubspace>` `create(TransactionContext tcx, java.util.List<java.lang.String> subpath, byte[] layer, byte[] prefix)` Creates a subdirectory of this `Directory` located at `subpath` (creating parent directories if necessary).
`default java.util.concurrent.CompletableFuture<DirectorySubspace>` `createOrOpen(TransactionContext tcx, java.util.List<java.lang.String> subpath)` Creates or opens the subdirectory of this `Directory` located at `subpath` (creating parent directories, if necessary).
`java.util.concurrent.CompletableFuture<DirectorySubspace>` `createOrOpen(TransactionContext tcx, java.util.List<java.lang.String> subpath, byte[] layer)` Creates or opens the subdirectory of this `Directory` located at `subpath` (creating parent directories, if necessary).
`default java.util.concurrent.CompletableFuture<java.lang.Boolean>` `exists(ReadTransactionContext tcx)` Checks if this `Directory` exists.
`java.util.concurrent.CompletableFuture<java.lang.Boolean>` `exists(ReadTransactionContext tcx, java.util.List<java.lang.String> subpath)` Checks if the subdirectory of this `Directory` located at `subpath` exists.
`DirectoryLayer` `getDirectoryLayer()` Get the `DirectoryLayer` that was used to create this `Directory`.
`byte[]` `getLayer()` Gets the layer byte string that was stored when this `Directory` was created.
`java.util.List<java.lang.String>` `getPath()` Gets the path represented by this `Directory`.
`default java.util.concurrent.CompletableFuture<java.util.List<java.lang.String>>` `list(ReadTransactionContext tcx)` List the subdirectories of this directory.
`java.util.concurrent.CompletableFuture<java.util.List<java.lang.String>>` `list(ReadTransactionContext tcx, java.util.List<java.lang.String> subpath)` List the subdirectories of this directory at a given `subpath`.
`java.util.concurrent.CompletableFuture<DirectorySubspace>` `move(TransactionContext tcx, java.util.List<java.lang.String> oldSubpath, java.util.List<java.lang.String> newSubpath)` Moves the subdirectory of this `Directory` located at `oldSubpath` to `newSubpath`.
`java.util.concurrent.CompletableFuture<DirectorySubspace>` `moveTo(TransactionContext tcx, java.util.List<java.lang.String> newAbsolutePath)` Moves this `Directory` to the specified `newAbsolutePath`.
`default java.util.concurrent.CompletableFuture<DirectorySubspace>` `open(ReadTransactionContext tcx, java.util.List<java.lang.String> subpath)` Opens the subdirectory of this `Directory` located at `subpath`.
`java.util.concurrent.CompletableFuture<DirectorySubspace>` `open(ReadTransactionContext tcx, java.util.List<java.lang.String> subpath, byte[] layer)` Opens the subdirectory of this `Directory` located at `subpath`.
`default java.util.concurrent.CompletableFuture<java.lang.Void>` `remove(TransactionContext tcx)` Removes this `Directory` and all of its subdirectories, as well as all of their contents.
`java.util.concurrent.CompletableFuture<java.lang.Void>` `remove(TransactionContext tcx, java.util.List<java.lang.String> subpath)` Removes the subdirectory of this `Directory` located at `subpath` and all of its subdirectories, as well as all of their contents.
`default java.util.concurrent.CompletableFuture<java.lang.Boolean>` `removeIfExists(TransactionContext tcx)` Removes this `Directory` 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> subpath)` Removes the subdirectory of this `Directory` located at `subpath` and all of its subdirectories, as well as all of their contents.

### Method Detail

#### getPath

    java.util.List<java.lang.String> getPath()

Gets the path represented by this `Directory`.

Returns:
  this `Directory`'s path

#### getLayer

    byte[] getLayer()

Gets the layer byte string that was stored when this `Directory` was created.

Returns:
  this `Directory`'s layer byte string

#### getDirectoryLayer

    DirectoryLayer getDirectoryLayer()

Get the `DirectoryLayer` that was used to create this `Directory`.

Returns:
  the `DirectoryLayer` that created this `Directory`

#### createOrOpen

    default java.util.concurrent.CompletableFuture<DirectorySubspace> createOrOpen(TransactionContext tcx,
                                                                                   java.util.List<java.lang.String> subpath)

Creates or opens the subdirectory of this `Directory` located at `subpath` (creating parent directories, if necessary).

Parameters:
  `tcx` - the `TransactionContext` to execute this operation in
  `subpath` - a `List<String>` specifying a subpath of this `Directory`
Returns:
  a `CompletableFuture` which will be set to the created or opened `DirectorySubspace`

#### createOrOpen

    java.util.concurrent.CompletableFuture<DirectorySubspace> createOrOpen(TransactionContext tcx,
                                                                           java.util.List<java.lang.String> subpath,
                                                                           byte[] layer)

Creates or opens the subdirectory of this `Directory` located at `subpath` (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

Parameters:
  `tcx` - the `TransactionContext` to execute this operation in
  `subpath` - a `List<String>` specifying a subpath of this `Directory`
  `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

    default java.util.concurrent.CompletableFuture<DirectorySubspace> open(ReadTransactionContext tcx,
                                                                           java.util.List<java.lang.String> subpath)

Opens the subdirectory of this `Directory` located at `subpath`.

The returned `CompletableFuture` can be set to the following errors:

- `NoSuchDirectoryException` - if the directory does not exist

Parameters:
  `tcx` - the `ReadTransactionContext` to execute this operation in
  `subpath` - a `List<String>` specifying a subpath of this `Directory`
Returns:
  a `CompletableFuture` which will be set to the opened `DirectorySubspace`

#### open

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

Opens the subdirectory of this `Directory` located at `subpath`. 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

Parameters:
  `tcx` - the `ReadTransactionContext` to execute this operation in
  `subpath` - a `List<String>` specifying a subpath of this `Directory`
  `layer` - a `byte[]` specifying the expected layer
Returns:
  a `CompletableFuture` which will be set to the opened `DirectorySubspace`

#### create

    default java.util.concurrent.CompletableFuture<DirectorySubspace> create(TransactionContext tcx,
                                                                             java.util.List<java.lang.String> subpath)

Creates a subdirectory of this `Directory` located at `subpath` (creating parent directories if necessary).

The returned `CompletableFuture` can be set to the following errors:

- `DirectoryAlreadyExistsException` - if the given directory already exists

Parameters:
  `tcx` - the `TransactionContext` to execute this operation in
  `subpath` - a `List<String>` specifying a subpath of this `Directory`
Returns:
  a `CompletableFuture` which will be set to the created `DirectorySubspace`

#### create

    default java.util.concurrent.CompletableFuture<DirectorySubspace> create(TransactionContext tcx,
                                                                             java.util.List<java.lang.String> subpath,
                                                                             byte[] layer)

Creates a subdirectory of this `Directory` located at `subpath` (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 returned `CompletableFuture` can be set to the following errors:

- `DirectoryAlreadyExistsException` - if the given directory already exists

Parameters:
  `tcx` - the `TransactionContext` to execute this operation in
  `subpath` - a `List<String>` specifying a subpath of this `Directory`
  `layer` - a `byte[]` specifying a layer to set for the directory
Returns:
  a `CompletableFuture` which will be set to the created `DirectorySubspace`

#### create

    java.util.concurrent.CompletableFuture<DirectorySubspace> create(TransactionContext tcx,
                                                                     java.util.List<java.lang.String> subpath,
                                                                     byte[] layer,
                                                                     byte[] prefix)

Creates a subdirectory of this `Directory` located at `subpath` (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

Parameters:
  `tcx` - the `TransactionContext` to execute this operation in
  `subpath` - a `List<String>` specifying a subpath 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

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

Moves this `Directory` to the specified `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 `CompletableFuture` can be set to the following errors:

- `NoSuchDirectoryException` - if this `Directory` doesn't exist
- `DirectoryAlreadyExistsException` - if a directory already exists at `newAbsolutePath`
- `DirectoryMoveException` - if an invalid move location is specified

Parameters:
  `tcx` - the `TransactionContext` to execute this operation in
  `newAbsolutePath` - a `List<String>` specifying the new absolute path for this `Directory`
Returns:
  a `CompletableFuture` which will be set to the `DirectorySubspace` for this `Directory` at its new location.

#### move

    java.util.concurrent.CompletableFuture<DirectorySubspace> move(TransactionContext tcx,
                                                                   java.util.List<java.lang.String> oldSubpath,
                                                                   java.util.List<java.lang.String> newSubpath)

Moves the subdirectory of this `Directory` located at `oldSubpath` to `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 `CompletableFuture` can be set to the following errors:

- `NoSuchDirectoryException` - if no `Directory` exists at `oldSubpath`
- `DirectoryAlreadyExistsException` - if a directory already exists at `newSubpath`
- `DirectoryMoveException` - if an invalid move location is specified

Parameters:
  `tcx` - the `TransactionContext` to execute this operation in
  `oldSubpath` - a `List<String>` specifying the subpath of the directory to move
  `newSubpath` - a `List<String>` specifying the subpath to move to
Returns:
  a `CompletableFuture` which will be set to the `DirectorySubspace` for this `Directory` at its new location.

#### remove

    default java.util.concurrent.CompletableFuture<java.lang.Void> remove(TransactionContext tcx)

Removes this `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 `DirectoryException`.

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 this `Directory` doesn't exist
- `DirectoryException` - if this is called on the root directory

Parameters:
  `tcx` - the `TransactionContext` to execute this operation in
Returns:
  a `CompletableFuture` which will be set once this `Directory` has been removed

#### remove

    java.util.concurrent.CompletableFuture<java.lang.Void> remove(TransactionContext tcx,
                                                                  java.util.List<java.lang.String> subpath)

Removes the subdirectory of this `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.

The returned `CompletableFuture` can be set to the following errors:

- `NoSuchDirectoryException` - if no directory exists at `subpath`

Parameters:
  `tcx` - the `TransactionContext` to execute this operation in
  `subpath` - a `List<String>` specifying a subpath of this `Directory`
Returns:
  a `CompletableFuture` which will be set once the `Directory` has been removed

#### removeIfExists

    default java.util.concurrent.CompletableFuture<java.lang.Boolean> removeIfExists(TransactionContext tcx)

Removes this `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.

Parameters:
  `tcx` - the `TransactionContext` to execute this operation in
Returns:
  a `CompletableFuture` which will be set to true once this `Directory` has been removed, or false if it didn't exist.

#### removeIfExists

    java.util.concurrent.CompletableFuture<java.lang.Boolean> removeIfExists(TransactionContext tcx,
                                                                             java.util.List<java.lang.String> subpath)

Removes the subdirectory of this `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.

Parameters:
  `tcx` - the `TransactionContext` to execute this operation in
  `subpath` - a `List<String>` specifying a subpath of this `Directory`
Returns:
  a `CompletableFuture` which will be set to true once the `Directory` has been removed, or false if it didn't exist.

#### list

    default java.util.concurrent.CompletableFuture<java.util.List<java.lang.String>> list(ReadTransactionContext tcx)

List the subdirectories of this directory.

The returned `CompletableFuture` can be set to the following errors:

- `NoSuchDirectoryException` - if this `Directory` doesn't exists

Parameters:
  `tcx` - the `ReadTransactionContext` to execute this operation in
Returns:
  a `CompletableFuture` which will be set to a `List<String>` of names of the subdirectories of this `Directory`. Each name is a unicode string representing the last component of a subdirectory's path.

#### list

    java.util.concurrent.CompletableFuture<java.util.List<java.lang.String>> list(ReadTransactionContext tcx,
                                                                                  java.util.List<java.lang.String> subpath)

List the subdirectories of this directory at a given `subpath`.

The returned `CompletableFuture` can be set to the following errors:

- `NoSuchDirectoryException` - if no directory exists at `subpath`

Parameters:
  `tcx` - the `ReadTransactionContext` to execute this operation in
  `subpath` - a `List<String>` specifying a subpath of this `Directory`
Returns:
  a `CompletableFuture` which will be set to a `List<String>` of names of the subdirectories of the directory at `subpath`. Each name is a unicode string representing the last component of a subdirectory's path.

#### exists

    default java.util.concurrent.CompletableFuture<java.lang.Boolean> exists(ReadTransactionContext tcx)

Checks if this `Directory` exists.

Parameters:
  `tcx` - the `ReadTransactionContext` to execute this operation in
Returns:
  a `CompletableFuture` which will be set to `true` if this `Directory` exists, or `false` if it doesn't

#### exists

    java.util.concurrent.CompletableFuture<java.lang.Boolean> exists(ReadTransactionContext tcx,
                                                                     java.util.List<java.lang.String> subpath)

Checks if the subdirectory of this `Directory` located at `subpath` exists.

Parameters:
  `tcx` - the `TransactionContext` to execute this operation in
  `subpath` - a `List<String>` specifying a subpath of this `Directory`
Returns:
  a `CompletableFuture` which will be set to `true` if the specified subdirectory exists, or `false` if it doesn't