@API(value=MAINTAINED) public class KeySpace extends Object
KeySpace
defines a logical directory structure for keys that comprise an FDB row key.
Directories within a KeySpace
are defined by the following attributes:
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 errorPut 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:
state
is represented by a string (presumably a value like * "CA", "NJ', "NY", etc.).
state
there are offices, each represented by a unique office_id
.
office_id
, there are three categories of information:
employees
(contained within a directory represented by the string "E"). Each
employee is keyed by a LONG employee_id
value.stock_id
value.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).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 and Description |
---|
KeySpace(KeySpaceDirectory... rootDirectories) |
KeySpace(String name,
KeySpaceDirectory... rootDirectories) |
Modifier and Type | Method and Description |
---|---|
List<KeySpaceDirectory> |
getDirectories()
Returns the available root directories in the
KeySpace . |
KeySpaceDirectory |
getDirectory(String name)
Retrieves a subdirectory.
|
KeySpaceDirectory |
getRoot()
Get the root of this key space.
|
List<KeySpacePath> |
list(FDBRecordContext context,
String directory)
Deprecated.
use
listDirectory(FDBRecordContext, String) instead |
List<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.
use
resolveFromKey(FDBRecordContext, Tuple) instead |
CompletableFuture<KeySpacePath> |
pathFromKeyAsync(FDBRecordContext context,
Tuple key)
Deprecated.
use
resolveFromKeyAsync(FDBRecordContext, Tuple) instead |
ResolvedKeySpacePath |
resolveFromKey(FDBRecordContext context,
Tuple key)
Synchronous/blocking version of
resolveFromKeyAsync . |
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 a
ResolvedKeySpacePath 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.
|
public KeySpace(@Nonnull KeySpaceDirectory... rootDirectories)
public KeySpace(@Nonnull String name, @Nonnull KeySpaceDirectory... rootDirectories)
@Nonnull public KeySpaceDirectory getDirectory(@Nonnull String name)
name
- the name of the directory to returnname
NoSuchDirectoryException
- if the directory does not exist@Nonnull public List<KeySpaceDirectory> getDirectories()
KeySpace
.@Nonnull public KeySpacePath path(@Nonnull String name)
name
- the name of the root directory with which to begin the pathNoSuchDirectoryException
- if the directory does not exist@Nonnull public KeySpacePath path(@Nonnull String name, @Nullable Object value)
name
- the name of the root directory with which to begin the pathvalue
- the value to use for the directoryNoSuchDirectoryException
- if the directory does not existRecordCoreArgumentException
- if the value provided is incompatible with the data type declared
for the directory@Deprecated @API(value=DEPRECATED) @Nonnull public CompletableFuture<KeySpacePath> pathFromKeyAsync(@Nonnull FDBRecordContext context, @Nonnull Tuple key)
resolveFromKeyAsync(FDBRecordContext, Tuple)
insteadKeySpacePath
representing the leaf-most directory in the path.
If entries remained in the tuple beyond the leaf directory, then
KeySpacePath.getRemainder()
can be used to fetch the remaining portion.context
- context used, if needed, for any database operationskey
- the tuple to be decodedRecordCoreArgumentException
- if the tuple provided does not correspond to any path through
the directory structure at this point@Deprecated @API(value=DEPRECATED) @Nonnull public KeySpacePath pathFromKey(@Nonnull FDBRecordContext context, @Nonnull Tuple key)
resolveFromKey(FDBRecordContext, Tuple)
insteadpathFromKeyAsync
.context
- context used, if needed, for any database operationskey
- the tuple to be decodedRecordCoreArgumentException
- if the tuple provided does not correspond to any path through
the directory structure at this point@Nonnull public CompletableFuture<ResolvedKeySpacePath> resolveFromKeyAsync(@Nonnull FDBRecordContext context, @Nonnull Tuple key)
ResolvedKeySpacePath
representing the leaf-most directory in the path.
If entries remained in the tuple beyond the leaf directory, then KeySpacePath.getRemainder()
can be used to fetch the remaining portion.context
- context used, if needed, for any database operationskey
- the tuple to be decodedRecordCoreArgumentException
- if the tuple provided does not correspond to any path through
the directory structure at this point@Nonnull public ResolvedKeySpacePath resolveFromKey(@Nonnull FDBRecordContext context, @Nonnull Tuple key)
resolveFromKeyAsync
.context
- context used, if needed, for any database operationskey
- the tuple to be decodedRecordCoreArgumentException
- if the tuple provided does not correspond to any path through
the directory structure at this point@API(value=DEPRECATED) @Deprecated @Nonnull public RecordCursor<KeySpacePath> listAsync(@Nonnull FDBRecordContext context, @Nonnull String subdirName, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties)
listDirectoryAsync(FDBRecordContext, String, byte[], ScanProperties)
insteadcontext
- 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@API(value=DEPRECATED) @Deprecated @Nonnull public List<KeySpacePath> list(@Nonnull FDBRecordContext context, @Nonnull String directory, @Nonnull ScanProperties scanProperties)
listDirectoryAsync(FDBRecordContext, String, byte[], ScanProperties)
insteadcontext
- 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@API(value=DEPRECATED) @Deprecated @Nonnull public List<KeySpacePath> list(@Nonnull FDBRecordContext context, @Nonnull String directory)
listDirectory(FDBRecordContext, String)
insteadcontext
- the context in which to perform database accessdirectory
- the path under which to list@Nonnull public RecordCursor<ResolvedKeySpacePath> listDirectoryAsync(@Nonnull FDBRecordContext context, @Nonnull String directory, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties)
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@Nonnull public List<ResolvedKeySpacePath> listDirectory(@Nonnull FDBRecordContext context, @Nonnull String directory, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties)
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@Nonnull public List<ResolvedKeySpacePath> listDirectory(@Nonnull FDBRecordContext context, @Nonnull String directory, @Nonnull ScanProperties scanProperties)
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@Nonnull public List<ResolvedKeySpacePath> listDirectory(@Nonnull FDBRecordContext context, @Nonnull String directory)
context
- the context in which to perform database accessdirectory
- the path under which to listpublic KeySpaceDirectory getRoot()
public void toTree(Writer out) throws IOException
out
- the print destinationIOException
- if there is a problem writing to the destination