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

Interface KeySpacePath

  • All Known Implementing Classes:
    KeySpacePathWrapper
    @API(MAINTAINED)
public interface KeySpacePath
    A KeySpacePath represents a discrete path through a directory tree defined by a KeySpace. A KeySpacePath is started via KeySpace.path(String), and a specific path may be traced down through the directory structure via successive calls to add(String, Object). Once a desired path has been fully constructed, toTuple(FDBRecordContext) is used to turn the resulting path into a Tuple to represent the FDB row key.

    • 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,
                 @Nullable
                 Object value)
        Adds a value for a specific subdirectory dirName to the directory path.
        Parameters:
        dirName - the name of the subdirectory to add to the path
        value - the value to use for the subdirectory
        Returns:
        this path
        Throws:
        NoSuchDirectoryException - if the specified subdirectory does not exist
        RecordCoreArgumentException - if the type of the value is not appropriate for the provided directory or differs from the constant value specified for the directory

      • 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

      • 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

      • toResolvedPath

        @Nonnull
default ResolvedKeySpacePath toResolvedPath​(@Nonnull
                                            FDBRecordContext context)
        Resolves the path into a ResolvedKeySpacePath, 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 of KeySpacePath 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 of hasDataAsync(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

      • listAsync

        @API(DEPRECATED)
@Deprecated
@Nonnull
default RecordCursor<KeySpacePath> listAsync​(@Nonnull
                                             FDBRecordContext context,
                                             @Nonnull
                                             String subdirName,
                                             @Nullable
                                             byte[] continuation,
                                             @Nonnull
                                             ScanProperties scanProperties)
        Deprecated.
        use listSubdirectoryAsync(FDBRecordContext, String, byte[], ScanProperties) instead
        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 a listAsync from a given node, will result in a list of paths, one for each leaf that is available within the node'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 returned KeySpacePath may contain a remainder (see getRemainder()) of the portion of the key tuple that was read.

        Parameters:
        context - the transaction in which to perform the listing
        subdirName - the name of the subdirectory that is to be listed
        continuation - an optional continuation from a previous list attempt
        scanProperties - 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 exist
        RecordCoreException - 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.
        use listSubdirectoryAsync(FDBRecordContext, String, ValueRange, byte[], ScanProperties) instead
        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 a listAsync from a given node, will result in a list of paths, one for each leaf that is available within the node'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 returned KeySpacePath may contain a remainder (see getRemainder()) of the portion of the key tuple that was read.

        Parameters:
        context - the transaction in which to perform the listing
        subdirName - the name of the subdirectory that is to be listed
        range - the range of the subdirectory values to be listed. All will be listed if it is null. If the directory is restricted to a specific constant value, it has to be null
        continuation - an optional continuation from a previous list attempt
        scanProperties - 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 exist
        RecordCoreException - if a key found during the listing process did not correspond to the directory tree

      • 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 a listSubdirectoryAsync from dirA for subdirectory dirB will path to each distinct value of dirB.

        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 returned ResolvedKeySpacePath may contain a remainder (see ResolvedKeySpacePath.getRemainder()) of the portion of the key tuple that was read. In the above example, each unique value of dirB would contain a remainder Tuple of the first value of dirC.

        Parameters:
        context - the transaction in which to perform the listing
        subdirName - the name of the subdirectory that is to be listed
        range - the range of the subdirectory values to be listed. All will be listed if it is null. If the directory is restricted to a specific constant value, it has to be null
        continuation - an optional continuation from a previous list attempt
        scanProperties - 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 exist
        RecordCoreException - 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 a listSubdirectoryAsync from dirA for subdirectory dirB will path to each distinct value of dirB.

        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 returned ResolvedKeySpacePath may contain a remainder (see ResolvedKeySpacePath.getRemainder()) of the portion of the key tuple that was read. In the above example, each unique value of dirB would contain a remainder Tuple of the first value of dirC.

        Parameters:
        context - the transaction in which to perform the listing
        subdirName - the name of the subdirectory that is to be listed
        continuation - an optional continuation from a previous list attempt
        scanProperties - 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 exist
        RecordCoreException - 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 of listSubdirectoryAsync.
        Parameters:
        context - the transaction in which to perform the listing
        subdirName - the name of the subdirectory that is to be listed
        range - the range of the subdirectory values to be listed. All will be listed if it is null. If the directory is restricted to a specific constant value, it has to be null
        continuation - an optional continuation from a previous list attempt
        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,
                                                    @Nullable
                                                    ValueRange<?> range,
                                                    @Nonnull
                                                    ScanProperties scanProperties)
        Synchronous/blocking version of listSubdirectoryAsync.
        Parameters:
        context - the transaction in which to perform the listing
        subdirName - the name of the subdirectory that is to be listed
        range - the range of the subdirectory values to be listed. All will be listed if it is null. If the directory is restricted to a specific constant value, it has to be null
        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 of listSubdirectoryAsync.
        Parameters:
        context - the transaction in which to perform the listing
        subdirName - the name of the subdirectory that is to be listed
        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)
        Synchronous/blocking version of listSubdirectoryAsync.
        Parameters:
        context - the transaction in which to perform the listing
        subdirName - 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 this KeySpacePath that shows correspondences between original and resolved directory values in accordance with the input Tuple.
        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