Merge pull request #692 from apache/name_change_and_release_prep

Name Change and Release Preparation

Author: leerho

.github/workflows/javadoc.yml

@@ -1,41 +1,67 @@
-name: JavaDoc
+name: Deploy Versioned Javadoc (Manual Trigger)
+
+# Select the target TAG where to run the workflow from.
+# This TAG name becomes the subdirectory under branch gh-pages/docs/${TAG}
+#   where the javadocs will be copied to.
 
 on:
-  push:
-    branches: main
   workflow_dispatch:
-
-permissions:
-  contents: write
+    inputs:
+      tag_ref:
+        description: 'Existing Git Tag to deploy (e.g., 1.0.0)'
+        required: true
+        default: '1.0.0' # Default can be left blank or set to a placeholder
 
 jobs:
-  javadoc:
+  build-and-deploy-javadoc:
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+
+  steps:
+    - name: Checkout Code at Specified Tag
+      uses: actions/checkout@v5
+      with:
+        ref: ${{ github.event.inputs.tag_ref }}  # from manual trigger input
+        fetch-depth: 0 
+
+    - name: Set up JDK
+      uses: actions/setup-java@v4
+      with:
+        java-version: '25'
+        distribution: 'temurin'
+        cache: 'maven' 
+
+    - name: Build and Generate Javadoc
+      run: mvn javadoc:javadoc
+
+    - name: Deploy Javadoc to gh-pages/docs/${TAG}
+      env:
+        GH_PAGES_EMAIL: noreply@github.com
+        GH_PAGES_NAME: github-actions[bot]
+        GIT_TAG_NAME: ${{ github.event.inputs.tag_ref }}
+        TARGET_DIR: docs/${{ github.event.inputs.tag_ref }}
+      run: |
+        # 1. Configure Git user
+        git config user.email "${GH_PAGES_EMAIL}"
+        git config user.name "${GH_PAGES_NAME}"
+
+        # 2. Fetch and checkout the existing gh-pages branch
+        git fetch origin gh-pages:gh-pages
+        git checkout gh-pages
+
+        # 3. Clean up any previous documentation for this tag (optional, but safer)
+        rm -rf $TARGET_DIR
+
+        # 4. Create the versioned directory structure
+        mkdir -p $TARGET_DIR
+
+        # 5. Copy the generated Javadoc files into the versioned directory
+        cp -r target/reports/apidocs/* $TARGET_DIR/
 
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v5
-
-      - name: Setup Java
-        uses: actions/setup-java@v5
-        with:
-          java-version: '25'
-          distribution: 'temurin'
-
-      - name: Echo Java Version
-        run:  java -version
-
-      - name: Print Current workflow
-        run: >
-         cat .github/workflows/javadoc.yml
-
-      - name: Generate JavaDoc
-        run: mvn javadoc:javadoc
-
-      - name: Deploy JavaDoc
-        uses: JamesIves/github-pages-deploy-action@881db5376404c5c8d621010bcbec0310b58d5e29
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-          folder: target/reports/apidocs
-          target-folder: docs/${{ github.ref_name }}
-          branch: gh-pages
+        # 6. Add the new directory and files, commit, and push
+        git add $TARGET_DIR
+        git commit -m "Manual Javadoc deployment for tag ${GIT_TAG_NAME} into $TARGET_DIR"
+        git push origin gh-pages

README.md

@@ -27,34 +27,33 @@ This is the core Java component of the DataSketches library.  It contains all of
 
 This component is also a dependency of other components of the library that create adaptors for target systems, such as the [Apache Pig adaptor](https://github.com/apache/datasketches-pig), the [Apache Hive adaptor](https://github.com/apache/datasketches-hive), and others.
 
-Note that we have a parallel core component for C++, Python and GO implementations of many of the same sketch algorithms, 
-[datasketches-cpp](https://github.com/apache/datasketches-cpp), [datasketches-python](https://github.com/apache/datasketches-python), and 
-[datasketches-go](https://github.com/apache/datasketches-go).
+Note that we have parallel core library components for C++, Python and GO implementations of many of the same sketch algorithms:
+
+- [datasketches-cpp](https://github.com/apache/datasketches-cpp), 
+- [datasketches-python](https://github.com/apache/datasketches-python),
+- [datasketches-go](https://github.com/apache/datasketches-go).
 
 Please visit the main [DataSketches website](https://datasketches.apache.org) for more information.
 
 If you are interested in making contributions to this site please see our [Community](https://datasketches.apache.org/docs/Community/) page for how to contact us.
 
----
 
 ## Build & Runtime Dependencies
 
 ### Installation Directory Path
 **NOTE:** This component accesses resource files for testing. As a result, the directory elements of the full absolute path of the target installation directory must qualify as Java identifiers. In other words, the directory elements must not have any space characters (or non-Java identifier characters) in any of the path elements. This is required by the Oracle Java Specification in order to ensure location-independent access to resources: [See Oracle Location-Independent Access to Resources](https://docs.oracle.com/javase/8/docs/technotes/guides/lang/resources.html)
 
-### OpenJDK Version 24
-An OpenJDK-compatible build of Java 24, provided by one of the Open-Source JVM providers, such as Azul Systems, Red Hat, SAP, Eclipse Temurin, etc, is required.
-All of the testing of this release has been performed with an Eclipse Temurin build.
-
-This release uses the new Java Foreign Function & Memory (FFM) features that were made part of the Java Language in in Java 22.
+### OpenJDK Version 25
+At minimum, an OpenJDK-compatible build of Java 25, provided by one of the Open-Source JVM providers, such as *Azul Systems*, *Red Hat*, *SAP*, *Eclipse Temurin*, etc, is required.
+All of the testing of this release has been performed with the *Eclipse Temurin* build.
 
 ## Compilation and Test using Maven
 This DataSketches component is structured as a Maven project and Maven is the recommended tool for compile and test.
 
 #### A Toolchain is required
 
-* You must have a JDK type toolchain defined in location *~/.m2/toolchains.xml* that specifies where to find a locally installed OpenJDK-compatible version 24.
-* Your default \$JAVA\_HOME compiler must be OpenJDK compatible, specified in the toolchain, and may be a version greater than 24. Note that if your \$JAVA\_HOME is set to a Java version greater than 24, Maven will automatically use the Java 24 version specified in the toolchain instead. The included pom.xml specifies the necessary JVM flags, so no further action should be required.
+* You must have a JDK type toolchain defined in location *~/.m2/toolchains.xml* that specifies where to find a locally installed OpenJDK-compatible version 25.
+* Your default \$JAVA\_HOME compiler must be OpenJDK compatible, specified in the toolchain, and may be a version greater than 25. Note that if your \$JAVA\_HOME is set to a Java version greater than 25, Maven will automatically use the Java 25 version specified in the toolchain instead. The pom.xml specifies any necessary JVM flags, if required, so no further action is needed.
 * Note that the paths specified in the toolchain must be fully qualified direct paths to the OpenJDK version locations. Using environment variables will not work.
 
 #### To run normal unit tests:
@@ -79,3 +78,7 @@ This will create the following jars:
 
 * Make sure you configure SpotBugs with the /tools/FindBugsExcludeFilter.xml file. Otherwise, you may get a lot of false positive or low risk issues that we have examined and eliminated with this exclusion file.
 
+### Checkstyle
+
+* At the time of this writing, Checkstyle had not been upgraded to handle Java 25 features. 
+

pom.xml

@@ -33,11 +33,11 @@ under the License.
 
   <groupId>org.apache.datasketches</groupId>
   <artifactId>datasketches-java</artifactId>
-  <version>9.0.0-SNAPSHOT</version>
+  <version>9.0.1-SNAPSHOT</version>
   <packaging>jar</packaging>
 
   <name>${project.artifactId}</name>
-  <description>Core sketch algorithms used alone and by other Java repositories in the DataSketches library.</description>
+  <description>Core sketch algorithms used alone and by other Java repositories in the Apache DataSketches Project.</description>
   <url>https://datasketches.apache.org/</url>
   <inceptionYear>2015</inceptionYear>
 
@@ -92,6 +92,8 @@ under the License.
     <!-- System-wide properties -->
     <maven.version>3.9.11</maven.version>
     <java.version>25</java.version>
+    <!-- Reproducable Builds, arbitrary, fixed date 
+    <project.build.outputTimestamp>2025-12-01T00:00:00Z</project.build.outputTimestamp> -->
     <!-- removed: g -Duser.language=en -Duser.country=US -Dfile.encoding=UTF-8 -->
     <jvm.options>-Xmx4g</jvm.options> <!-- use space to separate args -->
     <charset.encoding>UTF-8</charset.encoding>
@@ -102,17 +104,17 @@ under the License.
 
     <!--  org.apache.maven plugins -->
     <maven-assembly-plugin.version>3.7.1</maven-assembly-plugin.version>
-    <maven-compiler-plugin.version>3.14.0</maven-compiler-plugin.version>
-    <maven-dependency-plugin.version>3.8.1</maven-dependency-plugin.version>
+    <maven-compiler-plugin.version>3.14.1</maven-compiler-plugin.version>
+    <maven-dependency-plugin.version>3.9.0</maven-dependency-plugin.version>
     <maven-deploy-plugin.version>3.1.4</maven-deploy-plugin.version>
-    <maven-enforcer-plugin.version>3.6.1</maven-enforcer-plugin.version>
+    <maven-enforcer-plugin.version>3.6.2</maven-enforcer-plugin.version>
     <maven-gpg-plugin.version>3.2.8</maven-gpg-plugin.version>
-    <maven-jar-plugin.version>3.4.2</maven-jar-plugin.version>
-    <maven-javadoc-plugin.version>3.11.3</maven-javadoc-plugin.version>
-    <maven-release-plugin.version>3.1.1</maven-release-plugin.version>
+    <maven-jar-plugin.version>3.4.2</maven-jar-plugin.version> <!--3.5.0 fails -->
+    <maven-javadoc-plugin.version>3.12.0</maven-javadoc-plugin.version>
+    <maven-release-plugin.version>3.2.0</maven-release-plugin.version>
     <maven-source-plugin.version>3.3.1</maven-source-plugin.version>
     <!-- for surefire, failsafe and surefire-report: -->
-    <maven-surefire-failsafe-plugins.version>3.5.3</maven-surefire-failsafe-plugins.version>
+    <maven-surefire-failsafe-plugins.version>3.5.4</maven-surefire-failsafe-plugins.version>
     <maven-toolchains-plugin.version>3.2.0</maven-toolchains-plugin.version>
     <!-- com.github plugins -->
     <git-commit-id-plugin.version>4.9.10</git-commit-id-plugin.version>
@@ -122,11 +124,12 @@ under the License.
     <coveralls-repo-token></coveralls-repo-token>
     <coveralls-maven-plugin.version>4.3.0</coveralls-maven-plugin.version>
     <!-- org.jacoco.maven plugins -->
-    <jacoco-maven-plugin.version>0.8.13</jacoco-maven-plugin.version>
+    <jacoco-maven-plugin.version>0.8.14</jacoco-maven-plugin.version>
     <!-- org.mojohaus plugins -->
-    <versions-maven-plugin.version>2.18.0</versions-maven-plugin.version>
+    <versions-maven-plugin.version>2.19.1</versions-maven-plugin.version>
     <!-- other -->
     <lifecycle-mapping.version>1.0.0</lifecycle-mapping.version>
+    <reproducible-build-maven-plugin.version>0.17</reproducible-build-maven-plugin.version>
   </properties>
 
   <dependencies>
@@ -393,6 +396,19 @@ under the License.
           <version>${git-commit-id-plugin.version}</version>
         </plugin>
 
+        <plugin>
+          <groupId>io.github.zlika</groupId>
+          <artifactId>reproducible-build-maven-plugin</artifactId>
+          <version>${reproducible-build-maven-plugin.version}</version>
+          <executions>
+            <execution>
+              <goals>
+                <goal>strip-jar</goal>
+              </goals>
+            </execution>
+          </executions>
+        </plugin>
+
       </plugins>
     </pluginManagement>
     <plugins>
@@ -460,6 +476,10 @@ under the License.
         <groupId>pl.project13.maven</groupId>
         <artifactId>git-commit-id-plugin</artifactId>
       </plugin>
+      <plugin>
+        <groupId>io.github.zlika</groupId>
+        <artifactId>reproducible-build-maven-plugin</artifactId>
+      </plugin>
     </plugins>
   </build>
 
@@ -506,7 +526,7 @@ under the License.
                 <includeOnlyProperties>
                   <includeProperty>git.branch</includeProperty>
                   <includeProperty>git.commit.id.full</includeProperty>
-                  <includeProperty>git.commit.time</includeProperty>
+                  <!-- <includeProperty>git.commit.time</includeProperty> remove for reproducible builds-->
                   <includeProperty>git.commit.user.email</includeProperty>
                   <includeProperty>git.tags</includeProperty>
                 </includeOnlyProperties>
@@ -610,8 +630,6 @@ under the License.
       </build>
     </profile>
 
-
-
     <profile>
       <id>generate-java-files</id>
       <build>

src/main/java/org/apache/datasketches/hll/BaseHllSketch.java

@@ -35,7 +35,7 @@
 
 /**
  * Although this class is package-private, it provides a single place to define and document
- * the common public API for both HllSketch and Union.
+ * the common public API for both HllSketch and HllUnion.
  * @author Lee Rhodes
  * @author Kevin Lang
  */
@@ -115,7 +115,7 @@ public static final int getSerializationVersion(final MemorySegment seg) {
    * Gets the current (approximate) Relative Error (RE) asymptotic values given several
    * parameters. This is used primarily for testing.
    * @param upperBound return the RE for the Upper Bound, otherwise for the Lower Bound.
-   * @param oooFlag set true if the sketch is the result of a non qualifying union operation.
+   * @param oooFlag set true if the sketch is the result of a non qualifying HllUnion operation.
    * @param lgConfigK the configured value for the sketch.
    * @param numStdDev the given number of Standard Deviations. This must be an integer between
    * 1 and 3, inclusive.
@@ -206,8 +206,8 @@ public boolean isEstimationMode() {
    * inquire of the sketch if it has, in fact, moved itself.
    *
    * @param seg the given MemorySegment
-   * @return true if the given MemorySegment refers to the same underlying resource as this sketch or
-   * union.
+   * @return true if the given MemorySegment refers to the same underlying resource as this HllSketch or
+   * HllUnion.
    */
   @Override
   public abstract boolean isSameResource(MemorySegment seg);
@@ -219,17 +219,17 @@ public boolean isEstimationMode() {
 
   /**
    * Serializes this sketch as a byte array in compact form. The compact form is smaller in size
-   * than the updatable form and read-only. It can be used in union operations as follows:
+   * than the updatable form and read-only. It can be used in HllUnion operations as follows:
    * <pre>{@code
-   *     Union union; HllSketch sk, sk2;
+   *     HllUnion union; HllSketch sk, sk2;
    *     int lgK = 12;
    *     sk = new HllSketch(lgK, TgtHllType.HLL_4); //can be 4, 6, or 8
    *     for (int i = 0; i < (2 << lgK); i++) { sk.update(i); }
    *     byte[] arr = HllSketch.toCompactByteArray();
    *     //...
-   *     union = Union.heapify(arr); //initializes the union using data from the array.
+   *     union = HllUnion.heapify(arr); //initializes the HllUnion using data from the array.
    *     //OR, if used in an off-heap environment:
-   *     union = Union.heapify(MemorySegment.ofArray(arr)); //same as above, except from MemorySegment object.
+   *     union = HllUnion.heapify(MemorySegment.ofArray(arr)); //same as above, except from MemorySegment object.
    *
    *     //To recover an updatable heap sketch:
    *     sk2 = HllSketch.heapify(arr);
@@ -250,17 +250,17 @@ public boolean isEstimationMode() {
   /**
    * Serializes this sketch as a byte array in an updatable form. The updatable form is larger than
    * the compact form. The use of this form is primarily in environments that support updating
-   * sketches in off-heap MemorySegment. If the sketch is constructed using HLL_8, sketch updating and
-   * union updating operations can actually occur in MemorySegment, which can be off-heap:
+   * sketches in off-heap MemorySegment. If the sketch is constructed using HLL_8, HllSketch updating and
+   * HllUnion updating operations can actually occur in MemorySegment, which can be off-heap:
    * <pre>{@code
-   *     Union union; HllSketch sk;
+   *     HllUnion union; HllSketch sk;
    *     int lgK = 12;
    *     sk = new HllSketch(lgK, TgtHllType.HLL_8) //must be 8
    *     for (int i = 0; i < (2 << lgK); i++) { sk.update(i); }
    *     byte[] arr = sk.toUpdatableByteArray();
    *     MemorySegment wseg = MemorySegment.wrap(arr);
    *     //...
-   *     union = Union.writableWrap(wseg); //no deserialization!
+   *     union = HllUnion.writableWrap(wseg); //no deserialization!
    * }</pre>
    * @return this sketch as an updatable byte array.
    */

src/main/java/org/apache/datasketches/hll/DirectHll4Array.java

@@ -136,7 +136,7 @@ void putNibble(final int slotNo, final int nibValue) {
   }
 
   @Override
-  //Would be used by Union, but not used because the gadget is always HLL8 type
+  //Would be used by HllUnion, but not used because the gadget is always HLL8 type
   void updateSlotNoKxQ(final int slotNo, final int newValue) {
     throw new SketchesStateException("Improper access.");
   }

src/main/java/org/apache/datasketches/hll/DirectHll6Array.java

@@ -83,7 +83,7 @@ void putNibble(final int slotNo, final int nibValue) {
   }
 
   @Override
-  //Would be used by Union, but not used because the gadget is always HLL8 type
+  //Would be used by HllUnion, but not used because the gadget is always HLL8 type
  void updateSlotNoKxQ(final int slotNo, final int newValue) {
     throw new SketchesStateException("Improper access.");
   }

src/main/java/org/apache/datasketches/hll/DirectHll8Array.java

@@ -86,7 +86,7 @@ void putNibble(final int slotNo, final int nibValue) {
   }
 
   @Override
-  //Used by Union when source is not HLL8
+  //Used by HllUnion when source is not HLL8
  void updateSlotNoKxQ(final int slotNo, final int newValue) {
     final int oldValue = getSlotValue(slotNo);
     if (newValue > oldValue) {

src/main/java/org/apache/datasketches/hll/Hll4Array.java

@@ -136,7 +136,7 @@ void putNibble(final int slotNo, final int nibValue) {
   }
 
   @Override
-  //Would be used by Union, but not used because the gadget is always HLL8 type
+  //Would be used by HllUnion, but not used because the gadget is always HLL8 type
   void updateSlotNoKxQ(final int slotNo, final int newValue) {
     throw new SketchesStateException("Improper access.");
   }

src/main/java/org/apache/datasketches/hll/Hll6Array.java

@@ -93,7 +93,7 @@ void putNibble(final int slotNo, final int nibValue) {
   }
 
   @Override
-  //Would be used by Union, but not used because the gadget is always HLL8 type
+  //Would be used by HllUnion, but not used because the gadget is always HLL8 type
  void updateSlotNoKxQ(final int slotNo, final int newValue) {
     throw new SketchesStateException("Improper access.");
   }

src/main/java/org/apache/datasketches/hll/Hll8Array.java

@@ -92,7 +92,7 @@ void putNibble(final int slotNo, final int nibValue) {
   }
 
   @Override
-  //Used by Union when source is not HLL8
+  //Used by HllUnion when source is not HLL8
  void updateSlotNoKxQ(final int slotNo, final int newValue) {
     final int oldValue = getSlotValue(slotNo);
     hllByteArr[slotNo] = (byte) Math.max(newValue, oldValue);