Remove deprecated KeySpacePath methods related to caching the resolved value, and associated list methods on KeySpace (#3702)

Shortly before ResolvedKeySpacePath was introduced, `KeySpacePathImpl`
would store the resolved tuple and remainder in itself.
The methods around this have been deprecated for years.
More pressingly, what having this value means is that if you have a
KeySpacePath that is generated from `KeySpaceDirectory`s and call
toTuple or toSubspace it will resolve in the context that you provide,
but if that `KeySpacePath` came from resolving a key then toTuple /
toSubspace will contain the original directory-layer mappings, which
could be problematic if the provided context is not on the same cluster.

Author: ScottDugas

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/provider/foundationdb/keyspace/DirectoryLayerDirectory.java

@@ -258,8 +258,7 @@ protected CompletableFuture<Optional<ResolvedKeySpacePath>> pathFromKey(@Nonnull
 
                         // Make sure that the path is constructed with the text-name from the directory layer.
                         ResolvedKeySpacePath myPath = new ResolvedKeySpacePath(parent,
-                                KeySpacePathImpl.newPath(parentPath, this, directoryString,
-                                        true, pathValue, remainder),
+                                KeySpacePathImpl.newPath(parentPath, this, directoryString),
                                 pathValue, remainder);
 
                         // We are finished if there are no more subdirectories or no more tuple to consume

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/provider/foundationdb/keyspace/KeySpace.java

@@ -180,55 +180,14 @@ public KeySpacePath path(@Nonnull String name) {
     @Nonnull
     public KeySpacePath path(@Nonnull String name, @Nullable Object value) {
         KeySpaceDirectory dir = root.getSubdirectory(name);
-        return KeySpacePathImpl.newPath(null, dir, value, false, null, null);
-    }
-
-    /**
-     * Given a tuple from an FDB key, attempts to determine what path through this directory the tuple
-     * represents, returning a <code>KeySpacePath</code> representing the leaf-most directory in the path.
-     * If entries remained in the tuple beyond the leaf directory, then
-     *   {@link KeySpacePath#getRemainder()} can be used to fetch the remaining portion.
-     *
-     * @param context context used, if needed, for any database operations
-     * @param key the tuple to be decoded
-     * @return 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
-     *
-     * @deprecated use {@link #resolveFromKeyAsync(FDBRecordContext, Tuple)} instead
-     */
-    @Deprecated
-    @API(API.Status.DEPRECATED)
-    @Nonnull
-    public CompletableFuture<KeySpacePath> pathFromKeyAsync(@Nonnull FDBRecordContext context, @Nonnull Tuple key) {
-        return root.findChildForKey(context, null, key, key.size(), 0).thenApply(ResolvedKeySpacePath::toPath);
-    }
-
-    /**
-     * Synchronous/blocking version of <code>pathFromKeyAsync</code>.
-     *
-     * @param context context used, if needed, for any database operations
-     * @param key the tuple to be decoded
-     * @return 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
-     *
-     * @deprecated use {@link #resolveFromKey(FDBRecordContext, Tuple)} instead
-     */
-    @Deprecated
-    @API(API.Status.DEPRECATED)
-    @Nonnull
-    public KeySpacePath pathFromKey(@Nonnull FDBRecordContext context, @Nonnull Tuple key) {
-        return context.asyncToSync(FDBStoreTimer.Waits.WAIT_KEYSPACE_PATH_RESOLVE, pathFromKeyAsync(context, key));
+        return KeySpacePathImpl.newPath(null, dir, value);
     }
 
     /**
      * Given a tuple from an FDB key, attempts to determine what path through this directory the tuple
      * represents, returning a <code>ResolvedKeySpacePath</code> representing the leaf-most directory in the path.
      * <p>
-     *     If entries remained in the tuple beyond the leaf directory, then {@link KeySpacePath#getRemainder()} can be
+     *     If entries remained in the tuple beyond the leaf directory, then {@link ResolvedKeySpacePath#getRemainder()} can be
      *     used to fetch the remaining portion.
      *     See also {@link KeySpacePath#toResolvedPathAsync(FDBRecordContext, byte[])} if you need to resolve and you
      *     know that it is part of a given path.

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/provider/foundationdb/keyspace/KeySpaceDirectory.java

@@ -103,7 +103,7 @@ public class KeySpaceDirectory {
      * type may be stored in the directory, otherwise specifies a constant value that represents the
      * directory
      * @param wrapper if non-null, specifies a function that may be used to wrap any <code>KeySpacePath</code>
-     * objects return from {@link KeySpace#pathFromKey(FDBRecordContext, Tuple)}
+     * objects return from {@link KeySpace#resolveFromKeyAsync(FDBRecordContext, Tuple)}.
      *
      * @throws RecordCoreArgumentException if the provided value constant value is not valid for the
      * type of directory being created
@@ -130,7 +130,7 @@ public KeySpaceDirectory(@Nonnull String name, @Nonnull KeyType keyType, @Nullab
      * @param name the name of the directory
      * @param keyType the data type of the values that may be contained within the directory
      * @param wrapper if non-null, specifies a function that may be used to wrap any <code>KeySpacePath</code>
-     * objects returned from {@link KeySpace#pathFromKey(FDBRecordContext, Tuple)}
+     * objects returned from {@link KeySpace#resolveFromKeyAsync(FDBRecordContext, Tuple)}
      */
     public KeySpaceDirectory(@Nonnull String name, @Nonnull KeyType keyType, @Nullable Function<KeySpacePath, KeySpacePath> wrapper) {
         this(name, keyType, keyType.getAnyValue(), wrapper);
@@ -213,14 +213,12 @@ protected CompletableFuture<Optional<ResolvedKeySpacePath>> pathFromKey(@Nonnull
             // Have we hit the leaf of the tree or run out of tuple to process?
             if (subdirs.isEmpty() || keyIndex + 1 == keySize) {
                 final Tuple remainder = (keyIndex + 1 == key.size()) ? null : TupleHelpers.subTuple(key, keyIndex + 1, key.size());
-                final KeySpacePath path = KeySpacePathImpl.newPath(parentPath, this, tupleValue,
-                        true, resolvedValue, remainder);
+                final KeySpacePath path = KeySpacePathImpl.newPath(parentPath, this, tupleValue);
 
                 return CompletableFuture.completedFuture(
                         Optional.of(new ResolvedKeySpacePath(parent, path, new PathValue(tupleValue), remainder)));
             } else {
-                final KeySpacePath path = KeySpacePathImpl.newPath(parentPath, this, tupleValue,
-                        true, resolvedValue, null);
+                final KeySpacePath path = KeySpacePathImpl.newPath(parentPath, this, tupleValue);
                 return findChildForKey(context,
                         new ResolvedKeySpacePath(parent, path, pathValue, null),
                         key, keySize, keyIndex + 1).thenApply(Optional::of);

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/provider/foundationdb/keyspace/KeySpacePath.java

@@ -80,19 +80,6 @@ default int size() {
     @Nonnull
     KeySpacePath add(@Nonnull String dirName, @Nullable Object value);
 
-    /**
-     * If this path was created via {@link KeySpace#pathFromKey(FDBRecordContext, Tuple)}, this returns
-     * any remaining portion of the input tuple that was not used to construct the path.
-     * @return the remaining portion of the original input tuple or <code>null</code>
-     *
-     * @deprecated use {@link KeySpace#resolveFromKey(FDBRecordContext, Tuple)} and
-     *     {@link ResolvedKeySpacePath#getRemainder()} instead
-     */
-    @API(API.Status.DEPRECATED)
-    @Deprecated
-    @Nullable
-    Tuple getRemainder();
-
     /**
      * Returns the parent of this entry or null if this is the root of the path.
      * @return the parent keyspace path
@@ -129,39 +116,11 @@ default int size() {
      * by the directory layer for this path entry's value.
      *
      * @param context the context in which to resolve the value
-     * @return future that will resolve to value to be store for this path element.  Note that if the path
-     *   was produced via {@link KeySpace#pathFromKeyAsync(FDBRecordContext, Tuple)} or {@link #listAsync(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)
+     * @return future that will resolve to value to be store for this path element.
      */
     @Nonnull
     CompletableFuture<PathValue> resolveAsync(@Nonnull FDBRecordContext context);
 
-    /**
-     * If this path was created via a call to <code>pathFromKey</code> or <code>listAsync</code> (or their blocking
-     * variants), this method may be used to determine what the underlying value was physically stored in the key.
-     *
-     * @return 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
-     *
-     * @deprecated use {@link KeySpace#resolveFromKey(FDBRecordContext, Tuple)} and
-     *     {@link ResolvedKeySpacePath#getResolvedPathValue()} instead
-     */
-    @API(API.Status.DEPRECATED)
-    @Deprecated
-    @Nonnull
-    PathValue getStoredValue();
-
-    /**
-     * Whether it is legal to ask this key space path for the underlying value stored in the key.
-     * @return true if it is legal to call {@link #getStoredValue()}.
-     * @see #getStoredValue()
-     * @deprecated use {@link KeySpace#resolveFromKey(FDBRecordContext, Tuple)} instead
-     */
-    @API(API.Status.DEPRECATED)
-    @Deprecated
-    boolean hasStoredValue();
-
     /**
      * 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
@@ -202,7 +161,7 @@ default Tuple toTuple(@Nonnull FDBRecordContext context) {
      * Given a tuple from an FDB key, attempts to determine what sub-path through this directory the tuple
      * represents, returning a <code>ResolvedKeySpacePath</code> representing the leaf-most directory in the path.
      * <p>
-     *     If entries remained in the tuple beyond the leaf directory, then {@link KeySpacePath#getRemainder()}
+     *     If entries remained in the tuple beyond the leaf directory, then {@link ResolvedKeySpacePath#getRemainder()}
      *     can be used to fetch the remaining portion.
      *     See also {@link KeySpace#resolveFromKeyAsync(FDBRecordContext, Tuple)} if you need to resolve from the root.
      * </p>
@@ -302,139 +261,6 @@ default void deleteAllData(@Nonnull FDBRecordContext context) {
         context.asyncToSync(FDBStoreTimer.Waits.WAIT_KEYSPACE_CLEAR, deleteAllDataAsync(context));
     }
 
-    /**
-     * 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:
-     * <pre>
-     * root
-     *   +- node
-     *       +- leaf
-     * </pre>
-     * Performing a <code>listAsync</code> from a given <code>node</code>, will result in a list of paths, one for
-     * each <code>leaf</code> that is available within the <code>node</code>'s scope.
-     *
-     * <p>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 <code>KeySpacePath</code> that is returned.  In each case,
-     * the returned <code>KeySpacePath</code> may contain a remainder (see {@link #getRemainder()}) of the portion
-     * of the key tuple that was read.
-     *
-     * @param context the transaction in which to perform the listing
-     * @param subdirName the name of the subdirectory that is to be listed
-     * @param continuation an optional continuation from a previous list attempt
-     * @param scanProperties details for how the scan should be performed
-     * @return a list of fully qualified paths for each value contained within this directory
-     * @throws NoSuchDirectoryException if the subdirectory name provided does not exist
-     * @throws com.apple.foundationdb.record.RecordCoreException if a key found during the listing process did not correspond to
-     *    the directory tree
-     *
-     * @deprecated use {@link #listSubdirectoryAsync(FDBRecordContext, String, byte[], ScanProperties)} instead
-     */
-    @API(API.Status.DEPRECATED)
-    @Deprecated
-    @Nonnull
-    default RecordCursor<KeySpacePath> listAsync(@Nonnull FDBRecordContext context,
-                                                 @Nonnull String subdirName, @Nullable byte[] continuation,
-                                                 @Nonnull ScanProperties scanProperties) {
-        return listAsync(context, subdirName, null, continuation, 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:
-     * <pre>
-     * root
-     *   +- node
-     *       +- leaf
-     * </pre>
-     * Performing a <code>listAsync</code> from a given <code>node</code>, will result in a list of paths, one for
-     * each <code>leaf</code> that is available within the <code>node</code>'s scope.
-     *
-     * <p>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 <code>KeySpacePath</code> that is returned.  In each case,
-     * the returned <code>KeySpacePath</code> may contain a remainder (see {@link #getRemainder()}) of the portion
-     * of the key tuple that was read.
-     *
-     * @param context the transaction in which to perform the listing
-     * @param subdirName the name of the subdirectory that is to be listed
-     * @param range the range of the subdirectory values to be listed. All will be listed if it is <code>null</code>.
-     *     If the directory is restricted to a specific constant value, it has to be <code>null</code>
-     * @param continuation an optional continuation from a previous list attempt
-     * @param scanProperties details for how the scan should be performed
-     * @return a list of fully qualified paths for each value contained within this directory
-     * @throws NoSuchDirectoryException if the subdirectory name provided does not exist
-     * @throws com.apple.foundationdb.record.RecordCoreException if a key found during the listing process did not correspond to
-     *    the directory tree
-     *
-     * @deprecated use {@link #listSubdirectoryAsync(FDBRecordContext, String, ValueRange, byte[], ScanProperties)} instead
-     */
-    @API(API.Status.DEPRECATED)
-    @Deprecated
-    @Nonnull
-    RecordCursor<KeySpacePath> listAsync(@Nonnull FDBRecordContext context, 
-                                         @Nonnull String subdirName, 
-                                         @Nullable ValueRange<?> range,
-                                         @Nullable byte[] continuation,
-                                         @Nonnull ScanProperties scanProperties);
-
-    /**
-     * Synchronous version of <code>listAsync</code>.
-     *
-     * @param context the transaction in which to perform the listing
-     * @param subdirName the name of the subdirectory that is to be listed
-     * @param scanProperties details for how the scan should be performed
-     * @return a list of fully qualified paths for each value contained within this directory
-     *
-     * @deprecated use {@link #listSubdirectory(FDBRecordContext, String, ScanProperties)} instead
-     */
-    @API(API.Status.DEPRECATED)
-    @Deprecated
-    @Nonnull
-    default List<KeySpacePath> list(@Nonnull FDBRecordContext context, @Nonnull String subdirName,
-                                    @Nonnull ScanProperties scanProperties) {
-        return context.asyncToSync(FDBStoreTimer.Waits.WAIT_KEYSPACE_LIST, listAsync(context, subdirName, null, scanProperties).asList());
-    }
-
-    /**
-     * Synchronous version of <code>listAsync</code>.
-     *
-     * @param context the transaction in which to perform the listing
-     * @param subdirName the name of the subdirectory that is to be listed
-     * @param range the range of the subdirectory values to be listed. All will be listed if it is <code>null</code>.
-     *     If the directory is restricted to a specific constant value, it has to be <code>null</code>
-     * @param continuation an optional continuation from a previous list attempt
-     * @param scanProperties details for how the scan should be performed
-     * @return a list of fully qualified paths for each value contained within this directory
-     *
-     * @deprecated use {@link #listSubdirectory(FDBRecordContext, String, ValueRange, byte[], ScanProperties)} instead
-     */
-    @API(API.Status.DEPRECATED)
-    @Deprecated
-    @Nonnull
-    default List<KeySpacePath> list(@Nonnull FDBRecordContext context, @Nonnull String subdirName,
-                                    @Nullable ValueRange<?> range,
-                                    @Nullable byte[] continuation,
-                                    @Nonnull ScanProperties scanProperties) {
-        return context.asyncToSync(FDBStoreTimer.Waits.WAIT_KEYSPACE_LIST, listAsync(context, subdirName, range, continuation, scanProperties).asList());
-    }
-
-    /**
-     * Synchronous version of <code>listAsync</code> that performs a forward, serializable scan.
-     *
-     * @param context the transaction in which to perform the listing
-     * @param subdirName the name of the subdirectory that is to be listed
-     * @return a list of fully qualified paths for each value contained within this directory
-     *
-     * @deprecated use {@link #listSubdirectory(FDBRecordContext, String)} instead
-     */
-    @API(API.Status.DEPRECATED)
-    @Deprecated
-    @Nonnull
-    default List<KeySpacePath> list(@Nonnull FDBRecordContext context, @Nonnull String subdirName) {
-        return list(context, subdirName, ScanProperties.FORWARD_SCAN);
-    }
-
     /**
      * 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: