Package com.apple.foundationdb.record.provider.foundationdb.keyspace

Class DirectoryLayerDirectory

  • @API(MAINTAINED)
public class DirectoryLayerDirectory
extends KeySpaceDirectory
    A KeySpaceDirectory that maps a STRING value to a compact LONG value using the FDB directory layer. The DirectoryLayerDirectory may be used in one of two different fashions, either mapping a constant string value to a long, or being used to map any string value placed in the directory to a long. For example: 
         KeySpace keyspace = new KeySpace(
         new DirectoryLayerDirectory("library", "library")
             .addSubdirectory(new DirectoryLayerDirectory("book_title")));
    Defines a simple directory tree, in which the root of the path is a LONG value representing our application called "library", under which lives data for a set of books in the library stored under the title of the book ("book_title"), again represented as a LONG value by mapping the book title via the FDB directory layer.

    When creating a path through a directory layer directory, you may either specify the string name that you wish to place in the directory, like so: 

         keySpace.path("library").add("book_title", "Twenty Thousand Leagues Under the Sea").toTuple(context);
    or you may retrieve it by directory layer value: 
         keySpace.path("library").add(443L).toTuple(context);
    Retrieving by directory layer value will result in an exception if the value provided is either not a valid directory layer value, or it is not the value that corresponds to the constant name for this directory.

    • Method Detail

      • validateConstant

        protected void validateConstant​(@Nullable
                                Object value)
        Description copied from class: KeySpaceDirectory
        Called during creation to validate that the constant value provided is of a valid type for this directory.
        Overrides:
        validateConstant in class KeySpaceDirectory
        Parameters:
        value - constant value to validate

      • isCompatible

        protected boolean isCompatible​(@Nonnull
                               KeySpaceDirectory parent,
                               @Nonnull
                               KeySpaceDirectory dir)
        Description copied from class: KeySpaceDirectory
        When a subdirectory is being added to a directory and an existing subdirectory is found that stores the same data type but with a different constant value, this method will be called both on the directory being added as well as the existing subdirectory to allow them to determine if they are compatible with each other. A concrete example use case for this is the DirectoryLayerDirectory: let's say we had something like: 
            dir.addSubdirectory(new DirectoryLayerDirectory("dir1", "constValue"))
       .addSubdirectory(new KeySpaceDirectory("dir2", KeyType.LONG, 1)
        In this case, we are adding two directories which are of the same type, LONG (DirectorylayerDirectory is implicitly of type long) and, although, the two appear to have different constant values and, thus, should be compatible with each other, the DirectoryLayerDirectory dynamically converts it's "constValue" into a LONG and, thus, could end up colliding with the constant value of 1 used for "dir2". To prevent this, the DirectoryLayerDirectory must override this method to block any peer that isn't also a DirectorylayerDirectory. If this directory is being added to parent, then dir is the existing peer that has the same storage data type but a different constant value. If this directory already exists in parent, then dir is a new peer that is being added that has the same data type but a different constant value.
        Overrides:
        isCompatible in class KeySpaceDirectory
        Parameters:
        parent - the parent directory in which a subdirectory is being added
        dir - the existing peer directory
        Returns:
        true if the directories can co-exist, false otherwise

      • toTupleValueAsyncImpl

        @Nonnull
protected CompletableFuture<PathValue> toTupleValueAsyncImpl​(@Nonnull
                                                             FDBRecordContext context,
                                                             @Nullable
                                                             Object value)
        Description copied from class: KeySpaceDirectory
        This method is called during the process of turning a KeySpacePath into a Tuple. This method should never be directly invoked from anything other than toTupleValueAsync, it is purely intended for new KeySpaceDirectory implementations to override.
        Overrides:
        toTupleValueAsyncImpl in class KeySpaceDirectory
        Parameters:
        context - the context in which the tuple is being constructed
        value - the value that was provided to be stored in this directory
        Returns:
        a future that will result in the value to be physically stored for the provided input value

      • pathFromKey

        @Nonnull
protected CompletableFuture<Optional<ResolvedKeySpacePath>> pathFromKey​(@Nonnull
                                                                        FDBRecordContext context,
                                                                        @Nullable
                                                                        ResolvedKeySpacePath parent,
                                                                        @Nonnull
                                                                        Tuple key,
                                                                        int keySize,
                                                                        int keyIndex)
        Description copied from class: KeySpaceDirectory
        Given a position in a tuple, checks to see if this directory is compatible with the value at the position, returning either a path indicating that it was compatible or nothing if it was not compatible. This method allows overriding implementations to consume as much or as little of the tuple as necessary (for example, you could have a directory that needed two tuple elements to represent itself) or to have finer grained control over how the KeySpacePath for itself is constructed. If key size if less than the actual key length, the path remainder will reflect the left over key elements.
        Overrides:
        pathFromKey in class KeySpaceDirectory
        Parameters:
        context - the database context
        parent - the parent path element
        key - the tuple being parsed
        keySize - the logical key size.
        keyIndex - the position in the index being parsed
        Returns:
        the KeySpacePath representing the leaf-most path for the provided key or Optional.empty() if this directory is not compatible with the element at keyIndex position in the key