com.apple.foundationdb.directory

## Class DirectorySubspace

- java.lang.Object
- - com.apple.foundationdb.subspace.Subspace
  - - com.apple.foundationdb.directory.DirectorySubspace

All Implemented Interfaces:
  Directory

    public class DirectorySubspace
    extends Subspace
    implements Directory

A DirectorySubspace represents the contents of a directory, but it also remembers the path with which it was opened and offers convenience methods to operate on the directory at that path.

An instance of DirectorySubspace can be used for all the usual subspace operations. It can also be used to operate on the directory with which it was opened.

### Method Summary

All Methods Instance Methods Concrete Methods
`java.util.concurrent.CompletableFuture<DirectorySubspace>` `create(TransactionContext tcx, java.util.List<java.lang.String> subpath, byte[] otherLayer, byte[] prefix)` Creates a 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[] otherLayer)` Creates or opens the subdirectory of this `Directory` located at `subpath` (creating parent directories, if necessary).
`boolean` `equals(java.lang.Object rhs)` Returns whether this `DirectorySubspace` is equal to `rhs`.
`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`.
`int` `hashCode()` Computes a hash code compatible with the `equals()` method of this class.
`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`.
`java.util.concurrent.CompletableFuture<DirectorySubspace>` `open(ReadTransactionContext tcx, java.util.List<java.lang.String> subpath, byte[] otherLayer)` Opens the subdirectory of this `Directory` located at `subpath`.
`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.
`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.
`java.lang.String` `toString()` Create a human-readable string representation of this subspace.

### Methods inherited from class com.apple.foundationdb.subspace.Subspace

`contains, get, get, getKey, pack, pack, pack, packWithVersionstamp, range, range, subspace, unpack`

### Methods inherited from class java.lang.Object

`getClass, notify, notifyAll, wait, wait, wait`

### Methods inherited from interface com.apple.foundationdb.directory.Directory

`create, create, createOrOpen, exists, list, open, remove, removeIfExists`

### Method Detail

#### toString

    public java.lang.String toString()

Description copied from class: `Subspace`
Create a human-readable string representation of this subspace. This is really only useful for debugging purposes, but it includes information on what raw prefix the subspace is using.

Overrides:
  `toString` in class `Subspace`
Returns:
  a printable representation of this `DirectorySubspace`

#### equals

    public boolean equals(java.lang.Object rhs)

Returns whether this `DirectorySubspace` is equal to `rhs`. Two `DirectorySubspace`s are equal if they were created by the same `DirectoryLayer` and have the same path, layer, and subspace prefix.

Overrides:
  `equals` in class `Subspace`
Parameters:
  `rhs` - the Object to test for equality
Returns:
  true if this is equal to `rhs`

#### hashCode

    public int hashCode()

Computes a hash code compatible with the `equals()` method of this class. In particular, it will produce a hash code that is based off of the hashes of its path, its layer, and its subspace prefix.

Overrides:
  `hashCode` in class `Subspace`
Returns:
  a hash compatible with this class's `equals()` method

#### getPath

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

Description copied from interface: `Directory`
Gets the path represented by this `Directory`.

Specified by:
  `getPath` in interface `Directory`
Returns:
  this `Directory`'s path

#### getLayer

    public byte[] getLayer()

Description copied from interface: `Directory`
Gets the layer byte string that was stored when this `Directory` was created.

Specified by:
  `getLayer` in interface `Directory`
Returns:
  this `Directory`'s layer byte string

#### getDirectoryLayer

    public DirectoryLayer getDirectoryLayer()

Description copied from interface: `Directory`
Get the `DirectoryLayer` that was used to create this `Directory`.

Specified by:
  `getDirectoryLayer` in interface `Directory`
Returns:
  the `DirectoryLayer` that created this `Directory`

#### createOrOpen

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

Description copied from interface: `Directory`
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

Specified by:
  `createOrOpen` in interface `Directory`
Parameters:
  `tcx` - the `TransactionContext` to execute this operation in
  `subpath` - a `List<String>` specifying a subpath of this `Directory`
  `otherLayer` - 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> subpath,
                                                                          byte[] otherLayer)

Description copied from interface: `Directory`
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

Specified by:
  `open` in interface `Directory`
Parameters:
  `tcx` - the `ReadTransactionContext` to execute this operation in
  `subpath` - a `List<String>` specifying a subpath of this `Directory`
  `otherLayer` - 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> subpath,
                                                                            byte[] otherLayer,
                                                                            byte[] prefix)

Description copied from interface: `Directory`
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 `Directory.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
  `subpath` - a `List<String>` specifying a subpath of this `Directory`
  `otherLayer` - 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`

#### list

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

Description copied from interface: `Directory`
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`

Specified by:
  `list` in interface `Directory`
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.

#### move

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

Description copied from interface: `Directory`
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

Specified by:
  `move` in interface `Directory`
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.

#### moveTo

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

Description copied from interface: `Directory`
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

Specified by:
  `moveTo` in interface `Directory`
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.

#### remove

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

Description copied from interface: `Directory`
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`

Specified by:
  `remove` in interface `Directory`
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

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

Description copied from interface: `Directory`
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.

Specified by:
  `removeIfExists` in interface `Directory`
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.

#### exists

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

Description copied from interface: `Directory`
Checks if the subdirectory of this `Directory` located at `subpath` exists.

Specified by:
  `exists` in interface `Directory`
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