Package com.apple.foundationdb.directory

Class 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.

    • 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

      • 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

      • 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:

        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:

        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:

        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

      • 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:

        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:

        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:

        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,
                                                                        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