[Java] Replace the C wrapper layer with the Panama API-based Java implementation

java/README.md

@@ -1,10 +1,10 @@
-# CuVS Java API
+# cuVS Java API
 
 
-CuVS Java API provides a Java based simple, efficient, and a robust vector search API.
+cuVS Java API provides a Java based simple, efficient, and a robust vector search API.
 
 > [!CAUTION]
-> CuVS 25.06 contains an experimental version and updates to this API are expected in the coming release.
+> This contains an experimental APIs and may change in upcoming releases.
 
 ## Prerequisites
 
@@ -21,7 +21,11 @@ The libcuvs C and C++ libraries are needed for this API. If libcuvs libraries ha
 Alternatively, if libcuvs libraries are already built and you just want to build this API, please
 do `./build.sh java` in the top level directory or just do `./build.sh` in this directory.
 
+## Testing
+
+Run `./build.sh --run-java-tests` from this directory.
+
 
 ## Examples
 
-A few starter examples of CAGRA, HNSW, and Bruteforce index are provided in the `examples` directory.
+A few starter examples of CAGRA, HNSW, and Bruteforce indexing and searching are provided in the `examples` directory.

java/build.sh

@@ -5,9 +5,9 @@ set -e -u -o pipefail
 ARGS="$*"
 NUMARGS=$#
 
+CURDIR=$(cd "$(dirname $0)"; pwd)
 VERSION="25.08.0" # Note: The version is updated automatically when ci/release/update-version.sh is invoked
 GROUP_ID="com.nvidia.cuvs"
-SO_FILE_PATH="./internal/build"
 
 if [ -z "${CMAKE_PREFIX_PATH:=}" ]; then
   CMAKE_PREFIX_PATH="$(pwd)/../cpp/build"
@@ -30,7 +30,12 @@ if ! hasArg --run-java-tests; then
 fi
 
 # Build the java layer
-mvn install:install-file -DgroupId=$GROUP_ID -DartifactId=cuvs-java-internal -Dversion=$VERSION -Dpackaging=so -Dfile=$SO_FILE_PATH/libcuvs_java.so \
-  && cd cuvs-java \
-  && mvn verify "${MAVEN_VERIFY_ARGS[@]}" \
+if [ -z ${LD_LIBRARY_PATH+x} ]
+then export LD_LIBRARY_PATH=${CURDIR}/../cpp/build
+else export LD_LIBRARY_PATH=${CURDIR}/../cpp/build:${LD_LIBRARY_PATH}
+fi
+
+export LD_LIBRARY_PATH=${CURDIR}/../cpp/build:${LD_LIBRARY_PATH}
+cd cuvs-java
+mvn verify "${MAVEN_VERIFY_ARGS[@]}" \
   && mvn install:install-file -Dfile=./target/cuvs-java-$VERSION-jar-with-dependencies.jar -DgroupId=$GROUP_ID -DartifactId=cuvs-java -Dversion=$VERSION -Dpackaging=jar

java/cuvs-java/pom.xml

@@ -156,35 +156,6 @@
                     </execution>
                 </executions>
             </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-dependency-plugin</artifactId>
-                <version>2.10</version>
-                <executions>
-                    <execution>
-                        <id>copy</id>
-                        <phase>compile</phase>
-                        <goals>
-                            <goal>copy</goal>
-                        </goals>
-                        <configuration>
-                            <artifactItems>
-                                <artifactItem>
-                                    <groupId>com.nvidia.cuvs</groupId>
-                                    <artifactId>cuvs-java-internal</artifactId>
-                                    <!-- NOTE: The version automatically gets updated when ci/release/update-version.sh is invoked. -->
-                                    <!--CUVS_JAVA#VERSION_UPDATE_MARKER_START--><version>25.08.0</version><!--CUVS_JAVA#VERSION_UPDATE_MARKER_END-->
-                                    <type>so</type>
-                                    <overWrite>false</overWrite>
-                                    <outputDirectory>
-                                        ${project.build.directory}/classes/META-INF/native/linux_x64</outputDirectory>
-                                    <destFileName>libcuvs_java.so</destFileName>
-                                </artifactItem>
-                            </artifactItems>
-                        </configuration>
-                    </execution>
-                </executions>
-            </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-assembly-plugin</artifactId>

java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraCompressionParams.java

@@ -23,7 +23,6 @@
  */
 public class CagraCompressionParams {
 
-  private CuVSResources resources;
   private final int pqBits;
   private final int pqDim;
   private final int vqNCenters;
@@ -35,7 +34,6 @@ public class CagraCompressionParams {
    * Constructs an instance of CagraCompressionParams with passed search
    * parameters.
    *
-   * @param resources                the resources instance to use
    * @param pqBits                   the bit length of the vector element after
    *                                 compression by PQ
    * @param pqDim                    the dimensionality of the vector after
@@ -49,9 +47,8 @@ public class CagraCompressionParams {
    * @param pqKmeansTrainsetFraction the fraction of data to use during iterative
    *                                 kmeans building (PQ phase)
    */
-  private CagraCompressionParams(CuVSResources resources, int pqBits, int pqDim, int vqNCenters, int kmeansNIters,
+  private CagraCompressionParams(int pqBits, int pqDim, int vqNCenters, int kmeansNIters,
       double vqKmeansTrainsetFraction, double pqKmeansTrainsetFraction) {
-    this.resources = resources;
     this.pqBits = pqBits;
     this.pqDim = pqDim;
     this.vqNCenters = vqNCenters;
@@ -132,16 +129,14 @@ public String toString() {
    */
   public static class Builder {
 
-    private CuVSResources resources;
     private int pqBits = 8;
     private int pqDim = 0;
     private int vqNCenters = 0;
     private int kmeansNIters = 25;
     private double vqKmeansTrainsetFraction = 0;
     private double pqKmeansTrainsetFraction = 0;
 
-    public Builder(CuVSResources resources) {
-      this.resources = resources;
+    public Builder() {
     }
 
     /**
@@ -230,7 +225,7 @@ public Builder withPqKmeansTrainsetFraction(double pqKmeansTrainsetFraction) {
      * @return an instance of {@link CagraCompressionParams}
      */
     public CagraCompressionParams build() {
-      return new CagraCompressionParams(resources, pqBits, pqDim, vqNCenters, kmeansNIters, vqKmeansTrainsetFraction,
+      return new CagraCompressionParams(pqBits, pqDim, vqNCenters, kmeansNIters, vqKmeansTrainsetFraction,
           pqKmeansTrainsetFraction);
     }
   }

java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java

@@ -243,15 +243,6 @@ interface Builder {
          */
         Builder withIndexParams(CagraIndexParams cagraIndexParameters);
 
-        /**
-         * Registers an instance of configured {@link CagraCompressionParams} with this
-         * Builder.
-         *
-         * @param cagraCompressionParams An instance of CagraCompressionParams.
-         * @return An instance of this Builder.
-         */
-        public Builder withCompressionParams(CagraCompressionParams cagraCompressionParams);
-
         /**
          * Builds and returns an instance of CagraIndex.
          *

java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java

@@ -30,6 +30,7 @@ public class CagraIndexParams {
   private final int nnDescentNiter;
   private final int numWriterThreads;
   private final CuVSIvfPqParams cuVSIvfPqParams;
+  private final CagraCompressionParams cagraCompressionParams;
 
   /**
    * Enum that denotes which ANN algorithm is used to build CAGRA graph.
@@ -251,14 +252,16 @@ private CudaDataType(int value) {
   }
 
   private CagraIndexParams(int intermediateGraphDegree, int graphDegree, CagraGraphBuildAlgo CuvsCagraGraphBuildAlgo,
-      int nnDescentNiter, int writerThreads, CuvsDistanceType cuvsDistanceType, CuVSIvfPqParams cuVSIvfPqParams) {
+      int nnDescentNiter, int writerThreads, CuvsDistanceType cuvsDistanceType, CuVSIvfPqParams cuVSIvfPqParams,
+      CagraCompressionParams cagraCompressionParams) {
     this.intermediateGraphDegree = intermediateGraphDegree;
     this.graphDegree = graphDegree;
     this.cuvsCagraGraphBuildAlgo = CuvsCagraGraphBuildAlgo;
     this.nnDescentNiter = nnDescentNiter;
     this.numWriterThreads = writerThreads;
     this.cuvsDistanceType = cuvsDistanceType;
     this.cuVSIvfPqParams = cuVSIvfPqParams;
+    this.cagraCompressionParams = cagraCompressionParams;
   }
 
   /**
@@ -315,12 +318,33 @@ public CuVSIvfPqParams getCuVSIvfPqParams() {
     return cuVSIvfPqParams;
   }
 
+  /**
+   * Gets the CAGRA build algorithm.
+   */
+  public CagraGraphBuildAlgo getCuvsCagraGraphBuildAlgo() {
+    return cuvsCagraGraphBuildAlgo;
+  }
+
+  /**
+   * Gets the number of Iterations to run.
+   */
+  public int getNnDescentNiter() {
+    return nnDescentNiter;
+  }
+
+  /**
+   * Gets the CAGRA compression parameters.
+   */
+  public CagraCompressionParams getCagraCompressionParams() {
+    return cagraCompressionParams;
+  }
+
   @Override
   public String toString() {
     return "CagraIndexParams [cuvsCagraGraphBuildAlgo=" + cuvsCagraGraphBuildAlgo + ", cuvsDistanceType="
         + cuvsDistanceType + ", intermediateGraphDegree=" + intermediateGraphDegree + ", graphDegree=" + graphDegree
         + ", nnDescentNiter=" + nnDescentNiter + ", numWriterThreads=" + numWriterThreads + ", cuVSIvfPqParams="
-        + cuVSIvfPqParams + "]";
+        + cuVSIvfPqParams + ", cagraCompressionParams=" + cagraCompressionParams + "]";
   }
 
   /**
@@ -335,6 +359,7 @@ public static class Builder {
     private int nnDescentNumIterations = 20;
     private int numWriterThreads = 2;
     private CuVSIvfPqParams cuVSIvfPqParams = new CuVSIvfPqParams.Builder().build();
+    private CagraCompressionParams cagraCompressionParams;
 
     public Builder() {
     }
@@ -418,14 +443,26 @@ public Builder withCuVSIvfPqParams(CuVSIvfPqParams cuVSIvfPqParams) {
       return this;
     }
 
+    /**
+     * Registers an instance of configured {@link CagraCompressionParams} with this
+     * Builder.
+     *
+     * @param cagraCompressionParams An instance of CagraCompressionParams.
+     * @return An instance of this Builder.
+     */
+    public Builder withCompressionParams(CagraCompressionParams cagraCompressionParams) {
+      this.cagraCompressionParams = cagraCompressionParams;
+      return this;
+    }
+
     /**
      * Builds an instance of {@link CagraIndexParams}.
      *
      * @return an instance of {@link CagraIndexParams}
      */
     public CagraIndexParams build() {
       return new CagraIndexParams(intermediateGraphDegree, graphDegree, cuvsCagraGraphBuildAlgo, nnDescentNumIterations,
-          numWriterThreads, cuvsDistanceType, cuVSIvfPqParams);
+          numWriterThreads, cuvsDistanceType, cuVSIvfPqParams, cagraCompressionParams);
     }
   }
 }