Class KeySpace
- java.lang.Object
-
- com.apple.foundationdb.record.provider.foundationdb.keyspace.KeySpace
-
@API(MAINTAINED) public class KeySpace extends Object
AKeySpace
defines a logical directory structure for keys that comprise an FDB row key. Directories within aKeySpace
are defined by the following attributes:- name - Defines a logical name for the directory. As with a directory in a filesystem, Within a given directory no two sub-directories may have the same name
- type - Defines the datatype for the values stored at the directory's position within the FDB keyspace.
No two directories may have the same type unless they are defined with different constant values.
Note that
NULL
is considered a unique type, as such, all other types are implicitly non-null and any attempt to store a null value for those types will result in an error - constant - (optional) Defines a constant value for the directory within the FDB keyspace.
Put visually, the following directory structure:
/ (NULL) +- state (STRING) +- office_id (LONG) +- employees (STRING=E) | +- employee_id (LONG) +- inventory (STRING=I) | +- stock_id (LONG) +- sales (STRING=S) +- transaction_id (UUID) +- layaways (NULL) +- transaction_id (UUID)
defines a directory structure in which:- A
state
is represented by a string (presumably a value like * "CA", "NJ', "NY", etc.). - Within a
state
there are offices, each represented by a uniqueoffice_id
. - Within a given
office_id
, there are three categories of information:- A set of
employees
(contained within a directory represented by the string "E"). Each employee is keyed by a LONGemployee_id
value. - The inventory of the office (contained within a directory represented by the string "I"). Each
inventory item is keyed by a LONG
stock_id
value. - A list of sales transactions (contained within a directory represented by the string "S")
Each transaction is represented by a UUID
transaction_id
value. There is a special location stored until the NULL key to indicate transactions that are layaways (haven't been fully paid for yet).
- A set of
Such a directory structure would be constructed as:
KeySpace keySpace = new KeySpace( new KeySpaceDirectory("state", KeyType.STRING) .addSubdirectory(new KeySpaceDirectory("office_id", KeyType.LONG) .addSubdirectory(new KeySpaceDirectory("employees", KeyType.STRING, "E") .addSubdirectory(new KeySpaceDirectory("employee_id", KeyType.LONG))) .addSubdirectory(new KeySpaceDirectory("inventory", KeyType.STRING, "I") .addSubdirectory(new KeySpaceDirectory("stock_id", KeyType.LONG))) .addSubdirectory(new KeySpaceDirectory("sales", KeyType.STRING, "S") .addSubdirectory(new KeySpaceDirectory("transaction_id", KeyType.UUID)) .addSubdirectory(new KeySpaceDirectory( "layaways", KeyType.NULL)))));
Once defined, a
KeySpace
provides a convenient mechanism for constructing tuples that may then be used to form an FDB row key. For example:Tuple transactionKey = keySpace.path("state", "CA") .add("office_id", 1234) .add("sales") .add("transaction_id", UUID.randomUUID()) .toTuple(context);
Creates a row key suitable to store a new sales transaction in California in office 1234.Similarly, a
KeySpace
can be used to take a given FDB row key and logically turn it back into the path from which it came:KeySpacePath path = keySpace.pathFromKey(context, transactionKey); System.out.println(path.getDirectoryName()); // Displays "transaction_id=XXXX-XXXX-XXXX-XXX"" System.out.println(path.getParent().getDirectoryName()); // Displays "sales" System.out.println(path.getParent().getParent().getDirectoryName()); // Displays "office_id"
-
-
Constructor Summary
Constructors Constructor Description KeySpace(KeySpaceDirectory... rootDirectories)
KeySpace(String name, KeySpaceDirectory... rootDirectories)
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description List<KeySpaceDirectory>
getDirectories()
Returns the available root directories in theKeySpace
.KeySpaceDirectory
getDirectory(String name)
Retrieves a subdirectory.KeySpaceDirectory
getRoot()
Get the root of this key space.List<KeySpacePath>
list(FDBRecordContext context, String directory)
Deprecated.uselistDirectory(FDBRecordContext, String)
insteadList<KeySpacePath>
list(FDBRecordContext context, String directory, ScanProperties scanProperties)
Deprecated.RecordCursor<KeySpacePath>
listAsync(FDBRecordContext context, String subdirName, byte[] continuation, ScanProperties scanProperties)
Deprecated.List<ResolvedKeySpacePath>
listDirectory(FDBRecordContext context, String directory)
Synchronously list the available paths from a directory.List<ResolvedKeySpacePath>
listDirectory(FDBRecordContext context, String directory, byte[] continuation, ScanProperties scanProperties)
Synchronously list the available paths from a directory.List<ResolvedKeySpacePath>
listDirectory(FDBRecordContext context, String directory, ScanProperties scanProperties)
Synchronously list the available paths from a directory.RecordCursor<ResolvedKeySpacePath>
listDirectoryAsync(FDBRecordContext context, String directory, byte[] continuation, ScanProperties scanProperties)
List the available paths from a directory.KeySpacePath
path(String name)
Begin a path traversal from a root directory.KeySpacePath
path(String name, Object value)
Begin a path traversal from a root directory.KeySpacePath
pathFromKey(FDBRecordContext context, Tuple key)
Deprecated.useresolveFromKey(FDBRecordContext, Tuple)
insteadCompletableFuture<KeySpacePath>
pathFromKeyAsync(FDBRecordContext context, Tuple key)
Deprecated.useresolveFromKeyAsync(FDBRecordContext, Tuple)
insteadResolvedKeySpacePath
resolveFromKey(FDBRecordContext context, Tuple key)
Synchronous/blocking version ofresolveFromKeyAsync
.CompletableFuture<ResolvedKeySpacePath>
resolveFromKeyAsync(FDBRecordContext context, Tuple key)
Given a tuple from an FDB key, attempts to determine what path through this directory the tuple represents, returning aResolvedKeySpacePath
representing the leaf-most directory in the path.String
toString()
void
toTree(Writer out)
Creates a visually pleasing ASCII-art representation of the directory tree.
-
-
-
Constructor Detail
-
KeySpace
public KeySpace(@Nonnull KeySpaceDirectory... rootDirectories)
-
KeySpace
public KeySpace(@Nonnull String name, @Nonnull KeySpaceDirectory... rootDirectories)
-
-
Method Detail
-
getDirectory
@Nonnull public KeySpaceDirectory getDirectory(@Nonnull String name)
Retrieves a subdirectory.- Parameters:
name
- the name of the directory to return- Returns:
- the directory with the specified
name
- Throws:
NoSuchDirectoryException
- if the directory does not exist
-
getDirectories
@Nonnull public List<KeySpaceDirectory> getDirectories()
Returns the available root directories in theKeySpace
.- Returns:
- a list of root directories
-
path
@Nonnull public KeySpacePath path(@Nonnull String name)
Begin a path traversal from a root directory. This method may only be used for root directories defined with a constant value.- Parameters:
name
- the name of the root directory with which to begin the path- Returns:
- the path beginning at the specified root directory
- Throws:
NoSuchDirectoryException
- if the directory does not exist
-
path
@Nonnull public KeySpacePath path(@Nonnull String name, @Nullable Object value)
Begin a path traversal from a root directory.- Parameters:
name
- the name of the root directory with which to begin the pathvalue
- the value to use for the directory- Returns:
- the path beginning at the specified root directory
- Throws:
NoSuchDirectoryException
- if the directory does not existRecordCoreArgumentException
- if the value provided is incompatible with the data type declared for the directory
-
pathFromKeyAsync
@Deprecated @API(DEPRECATED) @Nonnull public CompletableFuture<KeySpacePath> pathFromKeyAsync(@Nonnull FDBRecordContext context, @Nonnull Tuple key)
Deprecated.useresolveFromKeyAsync(FDBRecordContext, Tuple)
insteadGiven a tuple from an FDB key, attempts to determine what path through this directory the tuple represents, returning aKeySpacePath
representing the leaf-most directory in the path. If entries remained in the tuple beyond the leaf directory, thenKeySpacePath.getRemainder()
can be used to fetch the remaining portion.- Parameters:
context
- context used, if needed, for any database operationskey
- the tuple to be decoded- Returns:
- a path entry representing the leaf directory entry that corresponds to a value in the provided tuple
- Throws:
RecordCoreArgumentException
- if the tuple provided does not correspond to any path through the directory structure at this point
-
pathFromKey
@Deprecated @API(DEPRECATED) @Nonnull public KeySpacePath pathFromKey(@Nonnull FDBRecordContext context, @Nonnull Tuple key)
Deprecated.useresolveFromKey(FDBRecordContext, Tuple)
insteadSynchronous/blocking version ofpathFromKeyAsync
.- Parameters:
context
- context used, if needed, for any database operationskey
- the tuple to be decoded- Returns:
- a path entry representing the leaf directory entry that corresponds to a value in the provided tuple
- Throws:
RecordCoreArgumentException
- if the tuple provided does not correspond to any path through the directory structure at this point
-
resolveFromKeyAsync
@Nonnull public CompletableFuture<ResolvedKeySpacePath> resolveFromKeyAsync(@Nonnull FDBRecordContext context, @Nonnull Tuple key)
Given a tuple from an FDB key, attempts to determine what path through this directory the tuple represents, returning aResolvedKeySpacePath
representing the leaf-most directory in the path. If entries remained in the tuple beyond the leaf directory, thenKeySpacePath.getRemainder()
can be used to fetch the remaining portion.- Parameters:
context
- context used, if needed, for any database operationskey
- the tuple to be decoded- Returns:
- a path entry representing the leaf directory entry that corresponds to a value in the provided tuple
- Throws:
RecordCoreArgumentException
- if the tuple provided does not correspond to any path through the directory structure at this point
-
resolveFromKey
@Nonnull public ResolvedKeySpacePath resolveFromKey(@Nonnull FDBRecordContext context, @Nonnull Tuple key)
Synchronous/blocking version ofresolveFromKeyAsync
.- Parameters:
context
- context used, if needed, for any database operationskey
- the tuple to be decoded- Returns:
- a path entry representing the leaf directory entry that corresponds to a value in the provided tuple
- Throws:
RecordCoreArgumentException
- if the tuple provided does not correspond to any path through the directory structure at this point
-
listAsync
@API(DEPRECATED) @Deprecated @Nonnull public RecordCursor<KeySpacePath> listAsync(@Nonnull FDBRecordContext context, @Nonnull String subdirName, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties)
Deprecated.List the available paths from a directory.- Parameters:
context
- the context in which to perform database accesssubdirName
- the name of the subdirectory to listcontinuation
- if non-null, provides a continuation from a previous listingscanProperties
- the properties to be used to control how the scan is performed- Returns:
- a cursor over the paths that were found
-
list
@API(DEPRECATED) @Deprecated @Nonnull public List<KeySpacePath> list(@Nonnull FDBRecordContext context, @Nonnull String directory, @Nonnull ScanProperties scanProperties)
Deprecated.Synchronously list the available paths from a directory.- Parameters:
context
- the context in which to perform database accessdirectory
- the path under which to listscanProperties
- the properties to be used to control how the scan is performed- Returns:
- a list of the paths that were found
-
list
@API(DEPRECATED) @Deprecated @Nonnull public List<KeySpacePath> list(@Nonnull FDBRecordContext context, @Nonnull String directory)
Deprecated.uselistDirectory(FDBRecordContext, String)
insteadSynchronously list the available paths from a directory.- Parameters:
context
- the context in which to perform database accessdirectory
- the path under which to list- Returns:
- a list of the paths that were found
-
listDirectoryAsync
@Nonnull public RecordCursor<ResolvedKeySpacePath> listDirectoryAsync(@Nonnull FDBRecordContext context, @Nonnull String directory, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties)
List the available paths from a directory.- Parameters:
context
- the context in which to perform database accessdirectory
- the name of the directory to listcontinuation
- if non-null, provides a continuation from a previous listingscanProperties
- the properties to be used to control how the scan is performed- Returns:
- a cursor over the paths that were found
-
listDirectory
@Nonnull public List<ResolvedKeySpacePath> listDirectory(@Nonnull FDBRecordContext context, @Nonnull String directory, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties)
Synchronously list the available paths from a directory.- Parameters:
context
- the context in which to perform database accessdirectory
- the path under which to listcontinuation
- if non-null, provides a continuation from a previous listingscanProperties
- the properties to be used to control how the scan is performed- Returns:
- a list of the paths that were found
-
listDirectory
@Nonnull public List<ResolvedKeySpacePath> listDirectory(@Nonnull FDBRecordContext context, @Nonnull String directory, @Nonnull ScanProperties scanProperties)
Synchronously list the available paths from a directory.- Parameters:
context
- the context in which to perform database accessdirectory
- the path under which to listscanProperties
- the properties to be used to control how the scan is performed- Returns:
- a list of the paths that were found
-
listDirectory
@Nonnull public List<ResolvedKeySpacePath> listDirectory(@Nonnull FDBRecordContext context, @Nonnull String directory)
Synchronously list the available paths from a directory.- Parameters:
context
- the context in which to perform database accessdirectory
- the path under which to list- Returns:
- a list of the paths that were found
-
getRoot
public KeySpaceDirectory getRoot()
Get the root of this key space.- Returns:
- the root key space
-
toTree
public void toTree(Writer out) throws IOException
Creates a visually pleasing ASCII-art representation of the directory tree.- Parameters:
out
- the print destination- Throws:
IOException
- if there is a problem writing to the destination
-
-