adressing comments and simplifying code

Author: normen662

fdb-extensions/src/main/java/com/apple/foundationdb/async/hnsw/AbstractNode.java

@@ -3,7 +3,7 @@
  *
  * This source file is part of the FoundationDB open source project
  *
- * Copyright 2015-2023 Apple Inc. and the FoundationDB project authors
+ * Copyright 2015-2025 Apple Inc. and the FoundationDB project authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -81,4 +81,25 @@ public Tuple getPrimaryKey() {
     public List<N> getNeighbors() {
         return neighbors;
     }
+
+
+    /**
+     * Converts this node into its {@link CompactNode} representation.
+     * <p>
+     * A {@code CompactNode} is a space-efficient implementation {@code Node}. This method provides the
+     * conversion logic to transform the current object into that compact form.
+     *
+     * @return a non-null {@link CompactNode} representing the current node.
+     */
+    @Nonnull
+    public abstract CompactNode asCompactNode();
+
+    /**
+     * Converts this node into its {@link InliningNode} representation.
+     * @return this object cast to an {@link InliningNode}; never {@code null}.
+     * @throws ClassCastException if this object is not actually an instance of
+     * {@link InliningNode}.
+     */
+    @Nonnull
+    public abstract InliningNode asInliningNode();
 }

fdb-extensions/src/main/java/com/apple/foundationdb/async/hnsw/AbstractStorageAdapter.java

@@ -3,7 +3,7 @@
  *
  * This source file is part of the FoundationDB open source project
  *
- * Copyright 2015-2023 Apple Inc. and the FoundationDB project authors
+ * Copyright 2015-2025 Apple Inc. and the FoundationDB project authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -48,7 +48,7 @@ abstract class AbstractStorageAdapter<N extends NodeReference> implements Storag
     private static final Logger logger = LoggerFactory.getLogger(AbstractStorageAdapter.class);
 
     @Nonnull
-    private final HNSW.Config config;
+    private final Config config;
     @Nonnull
     private final NodeFactory<N> nodeFactory;
     @Nonnull
@@ -73,7 +73,7 @@ abstract class AbstractStorageAdapter<N extends NodeReference> implements Storag
      * @param onWriteListener the listener to be called on write operations
      * @param onReadListener the listener to be called on read operations
      */
-    protected AbstractStorageAdapter(@Nonnull final HNSW.Config config, @Nonnull final NodeFactory<N> nodeFactory,
+    protected AbstractStorageAdapter(@Nonnull final Config config, @Nonnull final NodeFactory<N> nodeFactory,
                                      @Nonnull final Subspace subspace,
                                      @Nonnull final OnWriteListener onWriteListener,
                                      @Nonnull final OnReadListener onReadListener) {
@@ -88,11 +88,11 @@ protected AbstractStorageAdapter(@Nonnull final HNSW.Config config, @Nonnull fin
     /**
      * Returns the configuration used to build and search this HNSW graph.
      *
-     * @return the current {@link HNSW.Config} object, never {@code null}.
+     * @return the current {@link Config} object, never {@code null}.
      */
     @Override
     @Nonnull
-    public HNSW.Config getConfig() {
+    public Config getConfig() {
         return config;
     }
 
@@ -195,14 +195,14 @@ public OnReadListener getOnReadListener() {
      * @param layer the layer of the tree from which to fetch the node
      * @param primaryKey the non-null primary key that identifies the node to fetch
      *
-     * @return a {@link CompletableFuture} that will complete with the fetched {@link Node}
+     * @return a {@link CompletableFuture} that will complete with the fetched {@link AbstractNode}
      * once it has been read from storage and validated
      */
     @Nonnull
     @Override
-    public CompletableFuture<Node<N>> fetchNode(@Nonnull final ReadTransaction readTransaction,
-                                                @Nonnull final AffineOperator storageTransform,
-                                                int layer, @Nonnull Tuple primaryKey) {
+    public CompletableFuture<AbstractNode<N>> fetchNode(@Nonnull final ReadTransaction readTransaction,
+                                                        @Nonnull final AffineOperator storageTransform,
+                                                        int layer, @Nonnull Tuple primaryKey) {
         return fetchNodeInternal(readTransaction, storageTransform, layer, primaryKey).thenApply(this::checkNode);
 
     }
@@ -220,13 +220,13 @@ public CompletableFuture<Node<N>> fetchNode(@Nonnull final ReadTransaction readT
      * @param layer the layer index from which to fetch the node
      * @param primaryKey the primary key that uniquely identifies the node to be fetched; must not be {@code null}
      *
-     * @return a {@link CompletableFuture} that will be completed with the fetched {@link Node}.
+     * @return a {@link CompletableFuture} that will be completed with the fetched {@link AbstractNode}.
      * The future will complete with {@code null} if no node is found for the given key and layer.
      */
     @Nonnull
-    protected abstract CompletableFuture<Node<N>> fetchNodeInternal(@Nonnull ReadTransaction readTransaction,
-                                                                    @Nonnull AffineOperator storageTransform,
-                                                                    int layer, @Nonnull Tuple primaryKey);
+    protected abstract CompletableFuture<AbstractNode<N>> fetchNodeInternal(@Nonnull ReadTransaction readTransaction,
+                                                                            @Nonnull AffineOperator storageTransform,
+                                                                            int layer, @Nonnull Tuple primaryKey);
 
     /**
      * Method to perform basic invariant check(s) on a newly-fetched node.
@@ -237,7 +237,7 @@ protected abstract CompletableFuture<Node<N>> fetchNodeInternal(@Nonnull ReadTra
      * @return the node that was passed in
      */
     @Nullable
-    private Node<N> checkNode(@Nullable final Node<N> node) {
+    private <T extends Node<N>> T checkNode(@Nullable final T node) {
         return node;
     }
 
@@ -259,7 +259,7 @@ private Node<N> checkNode(@Nullable final Node<N> node) {
      */
     @Override
     public void writeNode(@Nonnull final Transaction transaction, @Nonnull final Quantizer quantizer,
-                          @Nonnull final Node<N> node, final int layer,
+                          @Nonnull final AbstractNode<N> node, final int layer,
                           @Nonnull final NeighborsChangeSet<N> changeSet) {
         writeNodeInternal(transaction, quantizer, node, layer, changeSet);
         if (logger.isTraceEnabled()) {
@@ -283,7 +283,7 @@ public void writeNode(@Nonnull final Transaction transaction, @Nonnull final Qua
      * removals of neighbor links
      */
     protected abstract void writeNodeInternal(@Nonnull Transaction transaction, @Nonnull Quantizer quantizer,
-                                              @Nonnull Node<N> node, int layer,
+                                              @Nonnull AbstractNode<N> node, int layer,
                                               @Nonnull NeighborsChangeSet<N> changeSet);
 
 }

fdb-extensions/src/main/java/com/apple/foundationdb/async/hnsw/AccessInfo.java

@@ -21,17 +21,34 @@
 package com.apple.foundationdb.async.hnsw;
 
 import com.apple.foundationdb.linear.RealVector;
+import com.google.common.base.Objects;
 
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
-import java.util.Objects;
 
+/**
+ * Class to capture the current state of this HNSW that cannot be expressed as metadata but that also is not the actual
+ * data that is inserted, organized and retrieved. For instance, an HNSW needs to keep track of the entry point that
+ * resides in the highest layer(currently). Another example is any information that pertains to coordinate system
+ * transformations that have to be carried out prior/posterior to inserting/retrieving an item into/from the HNSW.
+ */
 class AccessInfo {
+    /**
+     * The current entry point. All searches start here.
+     */
     @Nonnull
     private final EntryNodeReference entryNodeReference;
 
+    /**
+     * A seed that can be used to reconstruct a random rotator {@link com.apple.foundationdb.linear.FhtKacRotator} used
+     * in ({@link StorageTransform}.
+     */
     private final long rotatorSeed;
 
+    /**
+     * A centroid that is usually derived as an average over some vectors seen so far. It is used to create the
+     * {@link StorageTransform}.
+     */
     @Nullable
     private final RealVector centroid;
 
@@ -66,23 +83,19 @@ public AccessInfo withNewEntryNodeReference(@Nonnull final EntryNodeReference en
     }
 
     @Override
-    public final boolean equals(final Object o) {
+    public boolean equals(final Object o) {
         if (!(o instanceof AccessInfo)) {
             return false;
         }
-
         final AccessInfo that = (AccessInfo)o;
         return rotatorSeed == that.rotatorSeed &&
-                entryNodeReference.equals(that.entryNodeReference) &&
-                Objects.equals(centroid, that.centroid);
+                Objects.equal(entryNodeReference, that.entryNodeReference) &&
+                Objects.equal(centroid, that.centroid);
     }
 
     @Override
     public int hashCode() {
-        int result = entryNodeReference.hashCode();
-        result = 31 * result + Long.hashCode(rotatorSeed);
-        result = 31 * result + Objects.hashCode(centroid);
-        return result;
+        return Objects.hashCode(entryNodeReference, rotatorSeed, centroid);
     }
 
     @Nonnull

fdb-extensions/src/main/java/com/apple/foundationdb/async/hnsw/BaseNeighborsChangeSet.java

@@ -3,7 +3,7 @@
  *
  * This source file is part of the FoundationDB open source project
  *
- * Copyright 2015-2023 Apple Inc. and the FoundationDB project authors
+ * Copyright 2015-2025 Apple Inc. and the FoundationDB project authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -89,7 +89,7 @@ public List<N> merge() {
      */
     @Override
     public void writeDelta(@Nonnull final InliningStorageAdapter storageAdapter, @Nonnull final Transaction transaction,
-                           @Nonnull final Quantizer quantizer, final int layer, @Nonnull final Node<N> node,
+                           @Nonnull final Quantizer quantizer, final int layer, @Nonnull final AbstractNode<N> node,
                            @Nonnull final Predicate<Tuple> primaryKeyPredicate) {
         // nothing to be written
     }

fdb-extensions/src/main/java/com/apple/foundationdb/async/hnsw/CompactNode.java

@@ -3,7 +3,7 @@
  *
  * This source file is part of the FoundationDB open source project
  *
- * Copyright 2015-2023 Apple Inc. and the FoundationDB project authors
+ * Copyright 2015-2025 Apple Inc. and the FoundationDB project authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -47,8 +47,8 @@ class CompactNode extends AbstractNode<NodeReference> {
         @Nonnull
         @Override
         @SpotBugsSuppressWarnings("NP_PARAMETER_MUST_BE_NONNULL_BUT_MARKED_AS_NULLABLE")
-        public Node<NodeReference> create(@Nonnull final Tuple primaryKey, @Nullable final RealVector vector,
-                                          @Nonnull final List<? extends NodeReference> neighbors) {
+        public AbstractNode<NodeReference> create(@Nonnull final Tuple primaryKey, @Nullable final RealVector vector,
+                                                  @Nonnull final List<? extends NodeReference> neighbors) {
             return new CompactNode(primaryKey, Objects.requireNonNull(vector), (List<NodeReference>)neighbors);
         }