Interface KeySpacePath
-
- All Known Implementing Classes:
KeySpacePathWrapper
@API(MAINTAINED) public interface KeySpacePath
AKeySpacePath
represents a discrete path through a directory tree defined by aKeySpace
. AKeySpacePath
is started viaKeySpace.path(String)
, and a specific path may be traced down through the directory structure via successive calls toadd(String, Object)
. Once a desired path has been fully constructed,toTuple(FDBRecordContext)
is used to turn the resulting path into aTuple
to represent the FDB row key.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method Description KeySpacePath
add(String dirName)
Adds the constant value for subdirectorydirName
to the directory path.KeySpacePath
add(String dirName, Object value)
Adds avalue
for a specific subdirectorydirName
to the directory path.default void
deleteAllData(FDBRecordContext context)
Synchronous version ofdeleteAllDataAsync(FDBRecordContext)
.CompletableFuture<Void>
deleteAllDataAsync(FDBRecordContext context)
Delete all data from this path.List<KeySpacePath>
flatten()
Flattens the path into a list ofKeySpacePath
entries, with the root of the path located at position 0.KeySpaceDirectory
getDirectory()
Returns the directory that corresponds to this path entry.String
getDirectoryName()
Returns the directory name for this path element.KeySpacePath
getParent()
Returns the parent of this entry or null if this is the root of the path.Tuple
getRemainder()
Deprecated.PathValue
getStoredValue()
Deprecated.Object
getValue()
Returns the value that was provided when toadd(String, Object)
when this path was constructed.default boolean
hasData(FDBRecordContext context)
Synchronous version ofhasDataAsync(FDBRecordContext)
.CompletableFuture<Boolean>
hasDataAsync(FDBRecordContext context)
Check whether data exists for this path.boolean
hasStoredValue()
Deprecated.useKeySpace.resolveFromKey(FDBRecordContext, Tuple)
insteaddefault List<KeySpacePath>
list(FDBRecordContext context, String subdirName)
Deprecated.uselistSubdirectory(FDBRecordContext, String)
insteaddefault List<KeySpacePath>
list(FDBRecordContext context, String subdirName, ScanProperties scanProperties)
Deprecated.default List<KeySpacePath>
list(FDBRecordContext context, String subdirName, ValueRange<?> range, byte[] continuation, ScanProperties scanProperties)
Deprecated.default RecordCursor<KeySpacePath>
listAsync(FDBRecordContext context, String subdirName, byte[] continuation, ScanProperties scanProperties)
Deprecated.RecordCursor<KeySpacePath>
listAsync(FDBRecordContext context, String subdirName, ValueRange<?> range, byte[] continuation, ScanProperties scanProperties)
Deprecated.default List<ResolvedKeySpacePath>
listSubdirectory(FDBRecordContext context, String subdirName)
Synchronous/blocking version oflistSubdirectoryAsync
.default List<ResolvedKeySpacePath>
listSubdirectory(FDBRecordContext context, String subdirName, ScanProperties scanProperties)
Synchronous/blocking version oflistSubdirectoryAsync
.default List<ResolvedKeySpacePath>
listSubdirectory(FDBRecordContext context, String subdirName, ValueRange<?> range, byte[] continuation, ScanProperties scanProperties)
Synchronous/blocking version oflistSubdirectoryAsync
.default List<ResolvedKeySpacePath>
listSubdirectory(FDBRecordContext context, String subdirName, ValueRange<?> range, ScanProperties scanProperties)
Synchronous/blocking version oflistSubdirectoryAsync
.default RecordCursor<ResolvedKeySpacePath>
listSubdirectoryAsync(FDBRecordContext context, String subdirName, byte[] continuation, ScanProperties scanProperties)
For a given subdirectory from this path element, return a list of paths for all available keys in the FDB keyspace for that directory.RecordCursor<ResolvedKeySpacePath>
listSubdirectoryAsync(FDBRecordContext context, String subdirName, ValueRange<?> range, byte[] continuation, ScanProperties scanProperties)
For a given subdirectory from this path element, return a list of paths for all available keys in the FDB keyspace for that directory.CompletableFuture<PathValue>
resolveAsync(FDBRecordContext context)
Retrieve the value that is to be stored for this directory entry.default int
size()
Get the length of the path.default ResolvedKeySpacePath
toResolvedPath(FDBRecordContext context)
Resolves the path into aResolvedKeySpacePath
, a form the retains all of the information about the path itself along with the value to which each path entry is resolved.CompletableFuture<ResolvedKeySpacePath>
toResolvedPathAsync(FDBRecordContext context)
Resolves the path into aResolvedKeySpacePath
, a form the retains all of the information about the path itself along with the value to which each path entry is resolved.String
toString(Tuple tuple)
String representation of thisKeySpacePath
that shows correspondences between original and resolved directory values in accordance with the inputTuple
.default Subspace
toSubspace(FDBRecordContext context)
Converts the tuple produced for this path to a subspace.default CompletableFuture<Subspace>
toSubspaceAsync(FDBRecordContext context)
Converts the tuple produced for this path to a subspace.default Tuple
toTuple(FDBRecordContext context)
Converts this path into a tuple.CompletableFuture<Tuple>
toTupleAsync(FDBRecordContext context)
Converts this path into a tuple.
-
-
-
Method Detail
-
size
default int size()
Get the length of the path.- Returns:
- the length of the path
-
add
@Nonnull KeySpacePath add(@Nonnull String dirName)
Adds the constant value for subdirectorydirName
to the directory path.- Parameters:
dirName
- the name of the subdirectory to add to the path- Returns:
- this path
- Throws:
NoSuchDirectoryException
- if the specified subdirectory does not existRecordCoreArgumentException
- if the subdirectory does not have a constant value
-
add
@Nonnull KeySpacePath add(@Nonnull String dirName, @Nullable Object value)
Adds avalue
for a specific subdirectorydirName
to the directory path.- Parameters:
dirName
- the name of the subdirectory to add to the pathvalue
- the value to use for the subdirectory- Returns:
- this path
- Throws:
NoSuchDirectoryException
- if the specified subdirectory does not existRecordCoreArgumentException
- if the type of the value is not appropriate for the provided directory or differs from the constant value specified for the directory
-
getRemainder
@API(DEPRECATED) @Deprecated @Nullable Tuple getRemainder()
Deprecated.If this path was created viaKeySpace.pathFromKey(FDBRecordContext, Tuple)
, this returns any remaining portion of the input tuple that was not used to construct the path.- Returns:
- the remaining portion of the original input tuple or
null
-
getParent
@Nullable KeySpacePath getParent()
Returns the parent of this entry or null if this is the root of the path.- Returns:
- the parent keyspace path
-
getDirectoryName
@Nonnull String getDirectoryName()
Returns the directory name for this path element.- Returns:
- the directory name
-
getDirectory
@Nonnull KeySpaceDirectory getDirectory()
Returns the directory that corresponds to this path entry.- Returns:
- returns the directory that corresponds to this path entry
-
getValue
@Nullable Object getValue()
Returns the value that was provided when toadd(String, Object)
when this path was constructed. Note that for some directory types, such asDirectoryLayerDirectory
, this may not be the value that is actually stored at this path element. For that, useresolveAsync(FDBRecordContext)
.- Returns:
- the path value
-
resolveAsync
@Nonnull CompletableFuture<PathValue> resolveAsync(@Nonnull FDBRecordContext context)
Retrieve the value that is to be stored for this directory entry. For example, if the directory associated with this entry is aDirectoryLayerDirectory
the value returned will be the number assigned by the directory layer for this path entry's value.- Parameters:
context
- the context in which to resolve the value- Returns:
- future that will resolve to value to be store for this path element. Note that if the path
was produced via
KeySpace.pathFromKeyAsync(FDBRecordContext, Tuple)
orlistAsync(FDBRecordContext, String, byte[], ScanProperties)
, then the future that is returned will have already been completed (i.e it is safe to retrieve the value without blocking)
-
getStoredValue
@API(DEPRECATED) @Deprecated @Nonnull PathValue getStoredValue()
Deprecated.If this path was created via a call topathFromKey
orlistAsync
(or their blocking variants), this method may be used to determine what the underlying value was physically stored in the key.- Returns:
- the value that was stored for the path element
- Throws:
IllegalStateException
- if this path element was not produced from one of the above method calls
-
hasStoredValue
@API(DEPRECATED) @Deprecated boolean hasStoredValue()
Deprecated.useKeySpace.resolveFromKey(FDBRecordContext, Tuple)
instead- Returns:
- true if it is legal to call
getStoredValue()
.
-
toTuple
@Nonnull default Tuple toTuple(@Nonnull FDBRecordContext context)
Converts this path into a tuple. During this process the value that was provided for the directory, or was resolved by the directory implementation, is validated to ensure that it is a valid type for the directory.- Parameters:
context
- the context in which to resolve the path- Returns:
- the tuple form of this path
- Throws:
RecordCoreArgumentException
- if the value generated for a position in the path is not valid for that particular position
-
toTupleAsync
@Nonnull CompletableFuture<Tuple> toTupleAsync(@Nonnull FDBRecordContext context)
Converts this path into a tuple. During this process the value that was provided for the directory, or was resolved by the directory implementation, is validated to ensure that it is a valid type for the directory.- Parameters:
context
- the context in which the path is to be resolved- Returns:
- a future that will complete to the tuple representation of this path
-
toResolvedPathAsync
@Nonnull CompletableFuture<ResolvedKeySpacePath> toResolvedPathAsync(@Nonnull FDBRecordContext context)
Resolves the path into aResolvedKeySpacePath
, a form the retains all of the information about the path itself along with the value to which each path entry is resolved.- Parameters:
context
- the context in which the path is to be resolved- Returns:
- the resolved path
-
toResolvedPath
@Nonnull default ResolvedKeySpacePath toResolvedPath(@Nonnull FDBRecordContext context)
Resolves the path into aResolvedKeySpacePath
, a form the retains all of the information about the path itself along with the value to which each path entry is resolved.- Parameters:
context
- the context in which the path is to be resolved- Returns:
- the resolved path
-
toSubspace
default Subspace toSubspace(FDBRecordContext context)
Converts the tuple produced for this path to a subspace.- Parameters:
context
- the context in which to resolve the path- Returns:
- The subspace from the resolved path.
-
toSubspaceAsync
@Nonnull default CompletableFuture<Subspace> toSubspaceAsync(@Nonnull FDBRecordContext context)
Converts the tuple produced for this path to a subspace.- Parameters:
context
- the context in which to resolve the path- Returns:
- a future that completes with the subspace for this path
-
flatten
@Nonnull List<KeySpacePath> flatten()
Flattens the path into a list ofKeySpacePath
entries, with the root of the path located at position 0.- Returns:
- this path as a list
-
hasDataAsync
@Nonnull CompletableFuture<Boolean> hasDataAsync(FDBRecordContext context)
Check whether data exists for this path.- Parameters:
context
- the context in which the path is resolved and a scan is performed looking for data- Returns:
- a future that evaluates to
true
if data exists for this path
-
hasData
default boolean hasData(@Nonnull FDBRecordContext context)
Synchronous version ofhasDataAsync(FDBRecordContext)
.- Parameters:
context
- the context in which the path is resolved and a scan is performed looking for data- Returns:
true
if data exists for this path
-
deleteAllDataAsync
@Nonnull CompletableFuture<Void> deleteAllDataAsync(@Nonnull FDBRecordContext context)
Delete all data from this path. Use with care.Note that as it is possible that one or more record stores saved underneath this path might have cacheable meta-data, this method will reset the database's FDBRecordContext.getMetaDataVersionStampAsync(com.apple.foundationdb.record.IsolationLevel) meta-data version-stamp}. This can result in clients which are caching store state having to invalidate their caches.
- Parameters:
context
- the context in which the path is resolved and the delete operation takes place- Returns:
- a future that will delete all data underneath of this path
-
deleteAllData
default void deleteAllData(@Nonnull FDBRecordContext context)
Synchronous version ofdeleteAllDataAsync(FDBRecordContext)
.- Parameters:
context
- the context in which the path is resolved and the delete operation takes place
-
listAsync
@API(DEPRECATED) @Deprecated @Nonnull default RecordCursor<KeySpacePath> listAsync(@Nonnull FDBRecordContext context, @Nonnull String subdirName, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties)
Deprecated.For a given subdirectory from this path element, return a list of paths for all available keys in the FDB keyspace for that directory. For example, given the tree:root +- node +- leaf
Performing alistAsync
from a givennode
, will result in a list of paths, one for eachleaf
that is available within thenode
's scope.The listing is performed by reading the first key of the data type (and possibly constant value) for the subdirectory and, if a key is found, skipping to the next available value after the first one that was found, and so on, each time resulting in an additional
KeySpacePath
that is returned. In each case, the returnedKeySpacePath
may contain a remainder (seegetRemainder()
) of the portion of the key tuple that was read.- Parameters:
context
- the transaction in which to perform the listingsubdirName
- the name of the subdirectory that is to be listedcontinuation
- an optional continuation from a previous list attemptscanProperties
- details for how the scan should be performed- Returns:
- a list of fully qualified paths for each value contained within this directory
- Throws:
NoSuchDirectoryException
- if the subdirectory name provided does not existRecordCoreException
- if a key found during the listing process did not correspond to the directory tree
-
listAsync
@API(DEPRECATED) @Deprecated @Nonnull RecordCursor<KeySpacePath> listAsync(@Nonnull FDBRecordContext context, @Nonnull String subdirName, @Nullable ValueRange<?> range, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties)
Deprecated.For a given subdirectory from this path element, return a list of paths for all available keys in the FDB keyspace for that directory. For example, given the tree:root +- node +- leaf
Performing alistAsync
from a givennode
, will result in a list of paths, one for eachleaf
that is available within thenode
's scope.The listing is performed by reading the first key of the data type (and possibly constant value) for the subdirectory and, if a key is found, skipping to the next available value after the first one that was found, and so on, each time resulting in an additional
KeySpacePath
that is returned. In each case, the returnedKeySpacePath
may contain a remainder (seegetRemainder()
) of the portion of the key tuple that was read.- Parameters:
context
- the transaction in which to perform the listingsubdirName
- the name of the subdirectory that is to be listedrange
- the range of the subdirectory values to be listed. All will be listed if it isnull
. If the directory is restricted to a specific constant value, it has to benull
continuation
- an optional continuation from a previous list attemptscanProperties
- details for how the scan should be performed- Returns:
- a list of fully qualified paths for each value contained within this directory
- Throws:
NoSuchDirectoryException
- if the subdirectory name provided does not existRecordCoreException
- if a key found during the listing process did not correspond to the directory tree
-
list
@API(DEPRECATED) @Deprecated @Nonnull default List<KeySpacePath> list(@Nonnull FDBRecordContext context, @Nonnull String subdirName, @Nonnull ScanProperties scanProperties)
Deprecated.Synchronous version oflistAsync
.- Parameters:
context
- the transaction in which to perform the listingsubdirName
- the name of the subdirectory that is to be listedscanProperties
- details for how the scan should be performed- Returns:
- a list of fully qualified paths for each value contained within this directory
-
list
@API(DEPRECATED) @Deprecated @Nonnull default List<KeySpacePath> list(@Nonnull FDBRecordContext context, @Nonnull String subdirName, @Nullable ValueRange<?> range, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties)
Deprecated.Synchronous version oflistAsync
.- Parameters:
context
- the transaction in which to perform the listingsubdirName
- the name of the subdirectory that is to be listedrange
- the range of the subdirectory values to be listed. All will be listed if it isnull
. If the directory is restricted to a specific constant value, it has to benull
continuation
- an optional continuation from a previous list attemptscanProperties
- details for how the scan should be performed- Returns:
- a list of fully qualified paths for each value contained within this directory
-
list
@API(DEPRECATED) @Deprecated @Nonnull default List<KeySpacePath> list(@Nonnull FDBRecordContext context, @Nonnull String subdirName)
Deprecated.uselistSubdirectory(FDBRecordContext, String)
insteadSynchronous version oflistAsync
that performs a forward, serializable scan.- Parameters:
context
- the transaction in which to perform the listingsubdirName
- the name of the subdirectory that is to be listed- Returns:
- a list of fully qualified paths for each value contained within this directory
-
listSubdirectoryAsync
@Nonnull RecordCursor<ResolvedKeySpacePath> listSubdirectoryAsync(@Nonnull FDBRecordContext context, @Nonnull String subdirName, @Nullable ValueRange<?> range, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties)
For a given subdirectory from this path element, return a list of paths for all available keys in the FDB keyspace for that directory. For example, given the tree:root +- dirA +- dirB +- dirC
Performing alistSubdirectoryAsync
fromdirA
for subdirectorydirB
will path to each distinct value ofdirB
.The listing is performed by reading the first key of the data type (and possibly constant value) for the subdirectory and, if a key is found, skipping to the next available value after the first one that was found, and so on, each time resulting in an additional
ResolvedKeySpacePath
that is returned. In each case, the returnedResolvedKeySpacePath
may contain a remainder (seeResolvedKeySpacePath.getRemainder()
) of the portion of the key tuple that was read. In the above example, each unique value ofdirB
would contain a remainderTuple
of the first value ofdirC
.- Parameters:
context
- the transaction in which to perform the listingsubdirName
- the name of the subdirectory that is to be listedrange
- the range of the subdirectory values to be listed. All will be listed if it isnull
. If the directory is restricted to a specific constant value, it has to benull
continuation
- an optional continuation from a previous list attemptscanProperties
- details for how the scan should be performed- Returns:
- a list of fully qualified paths for each value contained within this directory
- Throws:
NoSuchDirectoryException
- if the subdirectory name provided does not existRecordCoreException
- if a key found during the listing process did not correspond to the directory tree
-
listSubdirectoryAsync
@Nonnull default RecordCursor<ResolvedKeySpacePath> listSubdirectoryAsync(@Nonnull FDBRecordContext context, @Nonnull String subdirName, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties)
For a given subdirectory from this path element, return a list of paths for all available keys in the FDB keyspace for that directory. For example, given the tree:root +- dirA +- dirB +- dirC
Performing alistSubdirectoryAsync
fromdirA
for subdirectorydirB
will path to each distinct value ofdirB
.The listing is performed by reading the first key of the data type (and possibly constant value) for the subdirectory and, if a key is found, skipping to the next available value after the first one that was found, and so on, each time resulting in an additional
ResolvedKeySpacePath
that is returned. In each case, the returnedResolvedKeySpacePath
may contain a remainder (seeResolvedKeySpacePath.getRemainder()
) of the portion of the key tuple that was read. In the above example, each unique value ofdirB
would contain a remainderTuple
of the first value ofdirC
.- Parameters:
context
- the transaction in which to perform the listingsubdirName
- the name of the subdirectory that is to be listedcontinuation
- an optional continuation from a previous list attemptscanProperties
- details for how the scan should be performed- Returns:
- a list of fully qualified paths for each value contained within this directory
- Throws:
NoSuchDirectoryException
- if the subdirectory name provided does not existRecordCoreException
- if a key found during the listing process did not correspond to the directory tree
-
listSubdirectory
@Nonnull default List<ResolvedKeySpacePath> listSubdirectory(@Nonnull FDBRecordContext context, @Nonnull String subdirName, @Nullable ValueRange<?> range, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties)
Synchronous/blocking version oflistSubdirectoryAsync
.- Parameters:
context
- the transaction in which to perform the listingsubdirName
- the name of the subdirectory that is to be listedrange
- the range of the subdirectory values to be listed. All will be listed if it isnull
. If the directory is restricted to a specific constant value, it has to benull
continuation
- an optional continuation from a previous list attemptscanProperties
- details for how the scan should be performed- Returns:
- a list of fully qualified paths for each value contained within this directory
-
listSubdirectory
@Nonnull default List<ResolvedKeySpacePath> listSubdirectory(@Nonnull FDBRecordContext context, @Nonnull String subdirName, @Nullable ValueRange<?> range, @Nonnull ScanProperties scanProperties)
Synchronous/blocking version oflistSubdirectoryAsync
.- Parameters:
context
- the transaction in which to perform the listingsubdirName
- the name of the subdirectory that is to be listedrange
- the range of the subdirectory values to be listed. All will be listed if it isnull
. If the directory is restricted to a specific constant value, it has to benull
scanProperties
- details for how the scan should be performed- Returns:
- a list of fully qualified paths for each value contained within this directory
-
listSubdirectory
@Nonnull default List<ResolvedKeySpacePath> listSubdirectory(@Nonnull FDBRecordContext context, @Nonnull String subdirName, @Nonnull ScanProperties scanProperties)
Synchronous/blocking version oflistSubdirectoryAsync
.- Parameters:
context
- the transaction in which to perform the listingsubdirName
- the name of the subdirectory that is to be listedscanProperties
- details for how the scan should be performed- Returns:
- a list of fully qualified paths for each value contained within this directory
-
listSubdirectory
@Nonnull default List<ResolvedKeySpacePath> listSubdirectory(@Nonnull FDBRecordContext context, @Nonnull String subdirName)
Synchronous/blocking version oflistSubdirectoryAsync
.- Parameters:
context
- the transaction in which to perform the listingsubdirName
- the name of the subdirectory that is to be listed- Returns:
- a list of fully qualified paths for each value contained within this directory
-
toString
@API(UNSTABLE) String toString(@Nonnull Tuple tuple)
String representation of thisKeySpacePath
that shows correspondences between original and resolved directory values in accordance with the inputTuple
.- Parameters:
tuple
- representing the directory values of this path in resolved form- Returns:
- a string representation of the path that shows both original and resolved directory values
-
-