DirectoryLayer (FoundationDB Java Client API)

java.lang.Object
- com.foundationdb.directory.DirectoryLayer

All Implemented Interfaces:

Directory
```
public class DirectoryLayer
extends 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.

In the present release, multiple directories may not be concurrently created within a single transaction. This restriction will be removed in a future release.

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

Methods
Modifier and Type	Method and Description
`Future<DirectorySubspace>`	`create(TransactionContext tcx, List<String> path)` Creates a directory located at `path` (creating parent directories if necessary).
`Future<DirectorySubspace>`	`create(TransactionContext tcx, List<String> path, byte[] layer)` Creates a directory located at `path` (creating parent directories if necessary).
`Future<DirectorySubspace>`	`create(TransactionContext tcx, List<String> path, byte[] layer, byte[] prefix)` Creates a directory located at `path` (creating parent directories if necessary).
`Future<DirectorySubspace>`	`createOrOpen(TransactionContext tcx, List<String> path)` Creates or opens the directory located at `path` (creating parent directories, if necessary).
`Future<DirectorySubspace>`	`createOrOpen(TransactionContext tcx, List<String> path, byte[] layer)` Creates or opens the directory located at `path`(creating parent directories, if necessary).
`static Directory`	`createWithContentSubspace(Subspace content_subspace)` Creates a new `DirectoryLayer` formed with a default node subspace and specified content subspace.
`static Directory`	`createWithNodeSubspace(Subspace node_subspace)` Creates a new `DirectoryLayer` formed with a specified node subspace and default content subspace.
`boolean`	`equals(Object rhs)` Tests whether this `DirectoryLayer` is equal to `rhs`.
`Future<Boolean>`	`exists(ReadTransactionContext tcx)` Returns `true`.
`Future<Boolean>`	`exists(ReadTransactionContext tcx, List<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.
`List<String>`	`getPath()` Gets the path for the root node of this `DirectoryLayer`.
`Future<List<String>>`	`list(ReadTransactionContext tcx)` List the subdirectories of the root directory.
`Future<List<String>>`	`list(ReadTransactionContext tcx, List<String> path)` List the subdirectories of the directory at a given `path`.
`Future<DirectorySubspace>`	`move(TransactionContext tcx, List<String> oldPath, List<String> newPath)` Moves the directory located at `oldPath` to `newPath`.
`Future<DirectorySubspace>`	`moveTo(TransactionContext tcx, List<String> newAbsolutePath)` This method should not be called on a `DirectoryLayer`.
`Future<DirectorySubspace>`	`open(ReadTransactionContext tcx, List<String> path)` Opens the directory located at `path`.
`Future<DirectorySubspace>`	`open(ReadTransactionContext tcx, List<String> path, byte[] layer)` Opens the directory located at `path`.
`Future<Void>`	`remove(TransactionContext tcx)` This method should not be called on the root directory.
`Future<Void>`	`remove(TransactionContext tcx, List<String> path)` Removes the directory located at `path` and all of its subdirectories, as well as all of their contents.
`Future<Boolean>`	`removeIfExists(TransactionContext tcx)` This method should not be called on the root directory.
`Future<Boolean>`	`removeIfExists(TransactionContext tcx, List<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, hashCode, notify, notifyAll, toString, wait, wait, wait

- 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 node_subspace)
```
    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:
    node_subspace - a Subspace used to store directory metadata
    
    Returns:
    a DirectoryLayer formed with node_subspace and a default content subspace
  - createWithContentSubspace
```
public static Directory createWithContentSubspace(Subspace content_subspace)
```
    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:
    content_subspace - a Subspace used to store directory content
    
    Returns:
    a DirectoryLayer formed with a content_subspace 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(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 Object
    
    Parameters:
    rhs - the object to check for equality
    
    Returns:
    true if this DirectoryLayer and rhs are equal
  - getPath
```
public List<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 Future<DirectorySubspace> createOrOpen(TransactionContext tcx,
                                     List<String> path)
```
    Creates or opens the directory located at path (creating parent directories, if necessary).
    
    Specified by:
    
    createOrOpen in interface Directory
    
    Parameters:
    tcx - the TransactionContext to execute this operation in
    path - a List<String> specifying a path
    
    Returns:
    a Future which will be set to the created or opened DirectorySubspace
  - createOrOpen
```
public Future<DirectorySubspace> createOrOpen(TransactionContext tcx,
                                     List<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 Future 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 Future which will be set to the created or opened DirectorySubspace
  - open
```
public Future<DirectorySubspace> open(ReadTransactionContext tcx,
                             List<String> path)
```
    Opens the directory located at path.
    The returned Future can be set to the following errors:
    - NoSuchDirectoryException - if the directory does not exist
    Specified by:
    
    open in interface Directory
    
    Parameters:
    tcx - the ReadTransactionContext to execute this operation in
    path - a List<String> specifying a path
    
    Returns:
    a Future which will be set to the opened DirectorySubspace
  - open
```
public Future<DirectorySubspace> open(ReadTransactionContext tcx,
                             List<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 Future 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 Future which will be set to the opened DirectorySubspace
  - create
```
public Future<DirectorySubspace> create(TransactionContext tcx,
                               List<String> path)
```
    Creates a directory located at path (creating parent directories if necessary).
    The returned Future 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
    
    Returns:
    a Future which will be set to the created DirectorySubspace
  - create
```
public Future<DirectorySubspace> create(TransactionContext tcx,
                               List<String> path,
                               byte[] layer)
```
    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 returned Future 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
    
    Returns:
    a Future which will be set to the created DirectorySubspace
  - create
```
public Future<DirectorySubspace> create(TransactionContext tcx,
                               List<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 Future 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 Future which will be set to the created DirectorySubspace
  - moveTo
```
public Future<DirectorySubspace> moveTo(TransactionContext tcx,
                               List<String> newAbsolutePath)
```
    This method should not be called on a DirectoryLayer. Calling this method will result in the returned Future being set to a DirectoryMoveException.
    The returned Future 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 Future which will be set to a DirectoryMoveException
  - move
```
public Future<DirectorySubspace> move(TransactionContext tcx,
                             List<String> oldPath,
                             List<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 Future 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 Future which will be set to the DirectorySubspace for this Directory at its new location.
  - remove
```
public Future<Void> remove(TransactionContext tcx)
```
    This method should not be called on the root directory. Calling this method will result in the returned Future being set to a DirectoryException.
    The returned Future can be set to the following errors:
    - DirectoryException
    Specified by:
    
    remove in interface Directory
    
    Parameters:
    tcx - the TransactionContext to execute this operation in
    
    Returns:
    a Future which will be set to a DirectoryException
  - remove
```
public Future<Void> remove(TransactionContext tcx,
                  List<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 Future 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 Future which will be set once the Directory has been removed
  - removeIfExists
```
public Future<Boolean> removeIfExists(TransactionContext tcx)
```
    This method should not be called on the root directory. Calling this method will result in the returned Future being set to a DirectoryException.
    The returned Future can be set to the following errors:
    - DirectoryException
    Specified by:
    
    removeIfExists in interface Directory
    
    Parameters:
    tcx - the TransactionContext to execute this operation in
    
    Returns:
    a Future which will be set to a DirectoryException
  - removeIfExists
```
public Future<Boolean> removeIfExists(TransactionContext tcx,
                             List<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 Future which will be set to true once the Directory has been removed, or false if it didn't exist.
  - list
```
public Future<List<String>> list(ReadTransactionContext tcx)
```
    List the subdirectories of the root directory.
    
    Specified by:
    
    list in interface Directory
    
    Parameters:
    tcx - the ReadTransactionContext to execute this operation in
    
    Returns:
    a Future which will be set to a List<String> of names of the subdirectories of the root directory. Each name is a unicode string representing the last component of a subdirectory's path.
  - list
```
public Future<List<String>> list(ReadTransactionContext tcx,
                        List<String> path)
```
    List the subdirectories of the directory at a given path.
    The returned Future 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 Future 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 Future<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 Future<Boolean> exists(ReadTransactionContext tcx,
                     List<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 Future which will be set to true if the specified directory exists, or false if it doesn't

Class DirectoryLayer

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_NODE_SUBSPACE

DEFAULT_CONTENT_SUBSPACE

PARTITION_LAYER

Constructor Detail

DirectoryLayer

DirectoryLayer

DirectoryLayer

DirectoryLayer

Method Detail

createWithNodeSubspace

createWithContentSubspace

getDefault

equals

getPath

getLayer

getDirectoryLayer

createOrOpen

createOrOpen

open

open

create

create

create

moveTo

move

remove

remove

removeIfExists

removeIfExists

list

list

exists

exists