Class DirectoryLayerDirectory
- java.lang.Object
-
- com.apple.foundationdb.record.provider.foundationdb.keyspace.KeySpaceDirectory
-
- com.apple.foundationdb.record.provider.foundationdb.keyspace.DirectoryLayerDirectory
-
@API(MAINTAINED) public class DirectoryLayerDirectory extends KeySpaceDirectory
AKeySpaceDirectory
that maps aSTRING
value to a compactLONG
value using the FDB directory layer. TheDirectoryLayerDirectory
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 aLONG
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 aLONG
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 Description DirectoryLayerDirectory(String name)
Constructor forDirectoryLayerDirectory
.DirectoryLayerDirectory(String name, Object value)
Constructor forDirectoryLayerDirectory
.DirectoryLayerDirectory(String name, Object value, Function<KeySpacePath,KeySpacePath> wrapper)
Constructor forDirectoryLayerDirectory
.DirectoryLayerDirectory(String name, Object value, Function<KeySpacePath,KeySpacePath> wrapper, Function<FDBRecordContext,CompletableFuture<LocatableResolver>> scopeGenerator, ResolverCreateHooks createHooks)
Constructor forDirectoryLayerDirectory
.DirectoryLayerDirectory(String name, Function<KeySpacePath,KeySpacePath> wrapper)
Constructor forDirectoryLayerDirectory
.DirectoryLayerDirectory(String name, Function<KeySpacePath,KeySpacePath> wrapper, Function<FDBRecordContext,CompletableFuture<LocatableResolver>> scopeGenerator, ResolverCreateHooks createHooks)
Constructor forDirectoryLayerDirectory
.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description String
getNameInTree()
When displaying the name of this directory in the tree output fromKeySpaceDirectory.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 aKeySpacePath
into aTuple
.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, findChildForValue, getKeyType, getName, getParent, getSubdirectories, getSubdirectory, getValue, isLeaf, listSubdirectoryAsync, listSubdirectoryAsync, nextChildForKey, toPathString, toString, toTree, toTupleValue, toTupleValueAsync, validateResolvedValue, wrap
-
-
-
-
Constructor Detail
-
DirectoryLayerDirectory
public DirectoryLayerDirectory(@Nonnull String name)
Constructor forDirectoryLayerDirectory
.- Parameters:
name
- The logical name of the directory
-
DirectoryLayerDirectory
public DirectoryLayerDirectory(@Nonnull String name, Function<KeySpacePath,KeySpacePath> wrapper)
Constructor forDirectoryLayerDirectory
.- Parameters:
name
- The logical name of the directorywrapper
- Wrapper function, see:KeySpaceDirectory(String, KeyType, Function)
-
DirectoryLayerDirectory
public DirectoryLayerDirectory(@Nonnull String name, @Nullable Object value)
Constructor forDirectoryLayerDirectory
.- Parameters:
name
- The logical name of the directoryvalue
- 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 forDirectoryLayerDirectory
. Sets thecreateHook
toResolverCreateHooks
their default values.- Parameters:
name
- The logical name of the directoryvalue
- The value of the directory entry (the string which will be translated to an int by the resolver)wrapper
- Wrapper function, see: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 forDirectoryLayerDirectory
.- Parameters:
name
- The logical name of the directorywrapper
- Wrapper function, see:KeySpaceDirectory(String, KeyType, Function)
scopeGenerator
- A function which will be called with the context of aKeySpacePath
which contains this directory. It returns a future (since it may need to read from the database) that completes with theLocatableResolver
to use.createHooks
- The set ofResolverCreateHooks
to run if, when getting a path through this directory, we need to create an entry in theLocatableResolver
. These checks can be used to, for example, add metadata to resolver entries for this directory, or to transactionally verify that theLocatableResolver
returned by thescopeGenerator
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 forDirectoryLayerDirectory
.- Parameters:
name
- The logical name of the directoryvalue
- The value of the directory entry (the string which will be translated to an int by the resolver)wrapper
- Wrapper function, see:KeySpaceDirectory(String, KeyType, Function)
scopeGenerator
- A function which will be called with the context of aKeySpacePath
which contains this directory. It returns a future (since it may need to read from the database) that completes with theLocatableResolver
to use.createHooks
- The set ofResolverCreateHooks
to run if, when getting a path through this directory, we need to create an entry in theLocatableResolver
. These checks can be used to, for example, add metadata to resolver entries for this directory, or to transactionally verify that theLocatableResolver
returned by thescopeGenerator
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 classKeySpaceDirectory
- 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 theDirectoryLayerDirectory
: 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, theDirectoryLayerDirectory
dynamically converts it's"constValue"
into a LONG and, thus, could end up colliding with the constant value of1
used for"dir2"
. To prevent this, theDirectoryLayerDirectory
must override this method to block any peer that isn't also aDirectorylayerDirectory
. If this directory is being added toparent
, thendir
is the existing peer that has the same storage data type but a different constant value. If this directory already exists inparent
, thendir
is a new peer that is being added that has the same data type but a different constant value.- Overrides:
isCompatible
in classKeySpaceDirectory
- Parameters:
parent
- the parent directory in which a subdirectory is being addeddir
- 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 aKeySpacePath
into aTuple
. This method should never be directly invoked from anything other thantoTupleValueAsync
, it is purely intended for newKeySpaceDirectory
implementations to override.- Overrides:
toTupleValueAsyncImpl
in classKeySpaceDirectory
- Parameters:
context
- the context in which the tuple is being constructedvalue
- 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 theKeySpacePath
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 classKeySpaceDirectory
- Parameters:
context
- the database contextparent
- the parent path elementkey
- the tuple being parsedkeySize
- the logical key size.keyIndex
- the position in the index being parsed- Returns:
- the
KeySpacePath
representing the leaf-most path for the providedkey
orOptional.empty()
if this directory is not compatible with the element atkeyIndex
position in thekey
-
getNameInTree
@Nonnull public String getNameInTree()
Description copied from class:KeySpaceDirectory
When displaying the name of this directory in the tree output fromKeySpaceDirectory.toString()
allows the directory implementation to ornament the name in any fashion it sees fit.- Overrides:
getNameInTree
in classKeySpaceDirectory
- Returns:
- the display name of the directory in the tree output
-
-