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

Class DirectoryLayerDirectory

java.lang.Object

com.apple.foundationdb.record.provider.foundationdb.keyspace.KeySpaceDirectory

com.apple.foundationdb.record.provider.foundationdb.keyspace.DirectoryLayerDirectory

@API(value=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.

Nested Class Summary

Nested classes/interfaces inherited from class com.apple.foundationdb.record.provider.foundationdb.keyspace.KeySpaceDirectory

KeySpaceDirectory.KeyType

Field Summary

Fields inherited from class com.apple.foundationdb.record.provider.foundationdb.keyspace.KeySpaceDirectory

ANY_VALUE, DIRECTORY_NOT_FOR_KEY, keyType, name, parent, subdirs, subdirsByName, value, wrapper

Constructor Summary

Constructors

Constructor and Description
DirectoryLayerDirectory(String name) Constructor for DirectoryLayerDirectory.
DirectoryLayerDirectory(String name, Function<KeySpacePath,KeySpacePath> wrapper) Constructor for DirectoryLayerDirectory.
DirectoryLayerDirectory(String name, Function<KeySpacePath,KeySpacePath> wrapper, Function<FDBRecordContext,CompletableFuture<LocatableResolver>> scopeGenerator, ResolverCreateHooks createHooks) Constructor for DirectoryLayerDirectory.
DirectoryLayerDirectory(String name, Object value) Constructor for DirectoryLayerDirectory.
DirectoryLayerDirectory(String name, Object value, Function<KeySpacePath,KeySpacePath> wrapper) Constructor for DirectoryLayerDirectory.
DirectoryLayerDirectory(String name, Object value, Function<KeySpacePath,KeySpacePath> wrapper, Function<FDBRecordContext,CompletableFuture<LocatableResolver>> scopeGenerator, ResolverCreateHooks createHooks) Constructor for DirectoryLayerDirectory.

Method Summary

Modifier and Type	Method and Description
String	getNameInTree() When displaying the name of this directory in the tree output from KeySpaceDirectory.toString() allows the directory implementation to ornament the name in any fashion it sees fit.
protected boolean	isCompatible(KeySpaceDirectory parent, KeySpaceDirectory dir) 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.
protected CompletableFuture<Optional<ResolvedKeySpacePath>>	pathFromKey(FDBRecordContext context, ResolvedKeySpacePath parent, Tuple key, int keySize, int keyIndex) 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.
protected CompletableFuture<PathValue>	toTupleValueAsyncImpl(FDBRecordContext context, Object value) This method is called during the process of turning a KeySpacePath into a Tuple.
protected void	validateConstant(Object value) Called during creation to validate that the constant value provided is of a valid type for this directory.

Methods inherited from class com.apple.foundationdb.record.provider.foundationdb.keyspace.KeySpaceDirectory

addSubdirectory, areEqual, depth, findChildForKey, getKeyType, getName, getParent, getSubdirectories, getSubdirectory, getValue, isLeaf, listSubdirectoryAsync, listSubdirectoryAsync, nextChildForKey, toString, toTree, toTupleValue, toTupleValueAsync, validateResolvedValue, wrap

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DirectoryLayerDirectory

public DirectoryLayerDirectory(@Nonnull
                               String name)

Constructor for DirectoryLayerDirectory.

Parameters:

name - The logical name of the directory

DirectoryLayerDirectory

public DirectoryLayerDirectory(@Nonnull
                               String name,
                               Function<KeySpacePath,KeySpacePath> wrapper)

Constructor for DirectoryLayerDirectory.

Parameters:

name - The logical name of the directory

wrapper - Wrapper function, see: KeySpaceDirectory.KeySpaceDirectory(String, KeyType, Function)

DirectoryLayerDirectory

public DirectoryLayerDirectory(@Nonnull
                               String name,
                               @Nullable
                               Object value)

Constructor for DirectoryLayerDirectory.

Parameters:

name - The logical name of the directory

value - The value of the directory entry (the string which will be translated to an int by the resolver)

DirectoryLayerDirectory

public DirectoryLayerDirectory(@Nonnull
                               String name,
                               @Nullable
                               Object value,
                               @Nullable
                               Function<KeySpacePath,KeySpacePath> wrapper)

Constructor for DirectoryLayerDirectory. Sets the createHook to ResolverCreateHooks their default values.

Parameters:

name - The logical name of the directory

value - The value of the directory entry (the string which will be translated to an int by the resolver)

wrapper - Wrapper function, see: KeySpaceDirectory.KeySpaceDirectory(String, KeyType, Function)

DirectoryLayerDirectory

public DirectoryLayerDirectory(@Nonnull
                               String name,
                               @Nullable
                               Function<KeySpacePath,KeySpacePath> wrapper,
                               @Nonnull
                               Function<FDBRecordContext,CompletableFuture<LocatableResolver>> scopeGenerator,
                               @Nonnull
                               ResolverCreateHooks createHooks)

Constructor for DirectoryLayerDirectory.

Parameters:

name - The logical name of the directory

wrapper - Wrapper function, see: KeySpaceDirectory.KeySpaceDirectory(String, KeyType, Function)

scopeGenerator - A function which will be called with the context of a KeySpacePath which contains this directory. It returns a future (since it may need to read from the database) that completes with the LocatableResolver to use.

createHooks - The set of ResolverCreateHooks to run if, when getting a path through this directory, we need to create an entry in the LocatableResolver. These checks can be used to, for example, add metadata to resolver entries for this directory, or to transactionally verify that the LocatableResolver returned by the scopeGenerator is correct.

DirectoryLayerDirectory

public DirectoryLayerDirectory(@Nonnull
                               String name,
                               @Nullable
                               Object value,
                               @Nullable
                               Function<KeySpacePath,KeySpacePath> wrapper,
                               @Nonnull
                               Function<FDBRecordContext,CompletableFuture<LocatableResolver>> scopeGenerator,
                               @Nonnull
                               ResolverCreateHooks createHooks)

Constructor for DirectoryLayerDirectory.

Parameters:

name - The logical name of the directory

value - The value of the directory entry (the string which will be translated to an int by the resolver)

wrapper - Wrapper function, see: KeySpaceDirectory.KeySpaceDirectory(String, KeyType, Function)

scopeGenerator - A function which will be called with the context of a KeySpacePath which contains this directory. It returns a future (since it may need to read from the database) that completes with the LocatableResolver to use.

createHooks - The set of ResolverCreateHooks to run if, when getting a path through this directory, we need to create an entry in the LocatableResolver. These checks can be used to, for example, add metadata to resolver entries for this directory, or to transactionally verify that the LocatableResolver returned by the scopeGenerator is correct.

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

getNameInTree

@Nonnull
public String getNameInTree()

Description copied from class: KeySpaceDirectory

When displaying the name of this directory in the tree output from KeySpaceDirectory.toString() allows the directory implementation to ornament the name in any fashion it sees fit.

Overrides:

getNameInTree in class KeySpaceDirectory

Returns:

the display name of the directory in the tree output