This is an automated email from the ASF dual-hosted git repository.
leerho pushed a commit to branch update_7.0.X
in repository https://gitbox.apache.org/repos/asf/datasketches-memory.git
The following commit(s) were added to refs/heads/update_7.0.X by this push:
new 0b39d36e Update README
0b39d36e is described below
commit 0b39d36e9458376a697cfa877fe1852d006bb63c
Author: Lee Rhodes <[email protected]>
AuthorDate: Mon Jun 1 15:57:41 2026 -0700
Update README
---
README.md | 76 +++++++++++++++++++++++++++++++++++----------------------------
1 file changed, 42 insertions(+), 34 deletions(-)
diff --git a/README.md b/README.md
index ce8c68c6..f4ebd2fe 100644
--- a/README.md
+++ b/README.md
@@ -49,7 +49,7 @@ Meanwhile, the Java Panama project, which had the potential
to provide all the a
Unfortunately, the DataSketches Memory Project releases 4.X, 5.X and 6.X for
Java 17 and 21 were developed using the Incubation and Preview versions of FFM
not realizing that Incubation and Preview codes are only available until the
next java version is released, after which they are no longer available.
-The actual LTS release of FFM did not occur until Java 25 was released on
September 16, 2025. Since Java 17 was released on September 14, 2021, there is
a gap of 4 years where Oracle had blocked access to internals of the JVM
without providing a LTS release API with comparable capabilities. This means
that for the LTS Java versions 17 and 21, the DataSketches Memory Project could
not provide access to file-mapped memory. Nonetheless, it is still possible to
provide these capabilities:
+The actual LTS release of FFM did not occur until Java 25 was released on
September 16, 2025. Since Java 17 was released on September 14, 2021, there is
a gap of 4 years where Oracle had blocked access to internals of the JVM
without providing a LTS release API with comparable capabilities. This means
that for the LTS Java versions 17 and 21, the DataSketches Memory Project can
not provide access to file-mapped memory. Nonetheless, it is still possible to
provide these capabilities:
## Capability Set B:
* Wrapping of Java primitive arrays as a region.
@@ -64,17 +64,17 @@ In addition, with this release the build code has been
completely refactored:
* New GitHub Actions Workflows that test this project in matrix of 3 OSs
(Windows, MacOS, Ubuntu) and 3 Java versions (11, 17, 21).
* All code jar files, including the test jars, can be successfully run as jars.
* The Apache release source is a multi-module Maven project
-* The the release to Maven Central is two jar sets as two new artifacts:
+* The release to Maven Central is two jar sets as two new artifacts:
* datasketches-memory-java11
* datasketches-memory-java17_21
* All documentation has been brought up-to-date.
-Because the FFM capabilities built into Java 25 (released September, 2025) are
a major superset of this Memory Project's capabilities (open sourced in 2015),
all of these capabilities are now available directly from the Java Language.
There is little reason to continue to provide new releases of this project.
Alas, this project must come to an end. Any further releases will only be for
bug fixes. Nonetheless, we were able to provide these fast, low-level, off-heap
memory capabilities for [...]
+Because the FFM capabilities built into Java 25 (released September, 2025) are
a major superset of this Memory Project's capabilities (open sourced in 2015),
all of these capabilities are now available directly from the Java Language.
There is little reason to continue to provide new releases of this project.
Alas, this project must come to an end. Any further releases will only be for
bug fixes. Nonetheless, we were able to provide these fast, low-level, off-heap
memory capabilities for [...]
## Comments about ByteBuffer
Although the ByteBuffer provides similar capabilities, it has some severe
limitations.
-* The deallocation is governed by the Garbage Collector. In large systems this
delay can lead to out-of-memory failures.
+* The deallocation of a ByteBuffer is governed by the Garbage Collector. In
large systems this delay can lead to out-of-memory failures.
* The addressing is limited to 2^31 -1 elements.
* Reading and writing multi-byte primitive arrays require recasting the
ByteBuffer to a <*type*>Buffer where the alignment becomes modulo the *type*.
This severely complicates the creation of packed structs.
* The API has some serious footguns, which can catch even experienced
programmers and can be challenging to debug:
@@ -93,7 +93,7 @@ The 3.X set of releases will be the last that support Java 8.
Deprecated with the 7.X releases.
### Releases 7.X (THIS RELEASE)
-* This release no longer uses JPMS but the jar manifests do provide an
Automatic Module Name.
+* This release no longer uses JPMS but the default jar manifests do provide an
Automatic Module Name.
* In addition to the source code obtained from Apache, this release provides
two sets of jars in Maven Central based on two artifacts:
#### Artifact: datasketches-memory-java11 (Capability Set A)
@@ -108,7 +108,7 @@ This artifact only supports Java 17 and Java 21
In this environment, the user is using the Jars from Maven Central as a
library dependency and not attempting to build this Memory Project from the
source code.
-### If you are running Java 11 you must use artifact
*datasketches-memory-java11*
+### If you are running Java 11 you must use artifact
*`datasketches-memory-java11`*
You will need to add these java modular arguments to your JVM:
* --add-exports=java.base/jdk.internal.misc=ALL-UNNAMED
@@ -116,7 +116,7 @@ You will need to add these java modular arguments to your
JVM:
* --add-opens=java.base/java.nio=ALL-UNNAMED
* --add-opens=java.base/sun.nio.ch=ALL-UNNAMED
-### If you are running Java 17 or Java 21 you must use artifact
*datasketches-memory-java17_21*
+### If you are running Java 17 or Java 21 you must use artifact
*`datasketches-memory-java17_21`*
You will need to add these java modular arguments to your JVM:
* --add-exports=java.base/jdk.internal.misc=ALL-UNNAMED
@@ -127,8 +127,10 @@ In this environment the developer needs to build the
Memory component from sourc
* Fork this project at https://github.com/apache/datasketches-memory into your
own GitHub development site. The 7.0.X releases will be located in the branch
7.0.X.
* Provide a
[toolchains.xml](https://maven.apache.org/guides/mini/guide-using-toolchains.html)
in your local system at `~/.m2/toolchains.xml` and configured with at least
JDK versions 11, 17 and 21.
-* You must have gpg-agent running in your terminal.
-* Your local machine JAVA_HOME should be set to at least Java 8, but Java 17
or higher is recommended.
+ * This project uses the maven-toolchains-plugin to ensure that each module
is strictly compiled against its target Java release version, regardless of
your default JAVA_HOME.
+* You must have `gpg-agent` running in your terminal.
+ * Note: The Maven release plugins run GPG in batch mode. Ensure your
`gpg-agent.conf` is configured with a long cache TTL, or signing will fail with
a no pinentry error during longer builds.
+* Your local machine JAVA_HOME should be set to at least Java 8, but Java 17
or higher is recommended. This is just to run Maven, the `pom.xml` files along
with the `toolchains.xml` determine the JDK version used to compile the
projects.
### Maven Build Instructions
__NOTES:__
@@ -137,38 +139,42 @@ __NOTES:__
__TESTS:__
-* There are two types of tests: unit tests and continuous integration (CI)
tests.
+* There are two types of tests: unit tests and continuous integration (CI)
tests run from GitHub Actions workflows.
The CI tests target the released jars and run all the unit tests against Java
versions 11, 17 and 21 and three different OSs, Windows, MacOS and Ubuntu.
To run normal unit tests on the forked site:
-* mvn clean test
-* The test results can be found in `/target/test-output`
+
+* `mvn clean test`
+ * The test results can be found in `/target/test-output`
To run javadoc on this multi-module project, use:
-* mvn clean javadoc:javadoc -DskipTests=true
-* The javadocs will be located in `/target/site/apidocs/`
+
+* `mvn clean javadoc:javadoc -DskipTests=true`
+ * The javadocs will be located in `/target/site/apidocs/`
To install the jars in ~/.m2
-* mvn clean install -DskipTests=true
-
-This will create the following sets of Jars and POM, with associated GPG .asc
signatures in the folder `~/.m2/repository/org/apache/datasketches/` and under
-
-`datasketches-memory-java11/X.Y.Z/`:
-* datasketches-memory-java11-X.Y.Z.jar
-* datasketches-memory-java11-X.Y.Z-tests.jar
-* datasketches-memory-java11-X.Y.Z-sources.jar
-* datasketches-memory-java11-X.Y.Z-test-sources.jar
-* datasketches-memory-java11-X.Y.Z-javadoc.jar
-* datasketches-memory-java11-X.Y.Z-pom
-
-And under:
-`datasketches-memory-java17_21/X.Y.Z/`:
-* datasketches-memory-java17_21-X.Y.Z.jar
-* datasketches-memory-java17_21-X.Y.Z-tests.jar
-* datasketches-memory-java17_21-X.Y.Z-sources.jar
-* datasketches-memory-java17_21-X.Y.Z-test-sources.jar
-* datasketches-memory-java17_21-X.Y.Z-javadoc.jar
-* datasketches-memory-java17_21-X.Y.Z-pom
+
+* `mvn clean install -DskipTests=true -Pnexus-jars`
+ * The `-Pnexus-jars` is required to generage the GPG signatures.
+
+This will create the following sets of Jars and POMs, with associated GPG .asc
signatures (not listed here) in the folder
`~/.m2/repository/org/apache/datasketches/` and under
+
+* `datasketches-memory-java11/X.Y.Z/`:
+
+ * datasketches-memory-java11-X.Y.Z.jar
+ * datasketches-memory-java11-X.Y.Z-tests.jar
+ * datasketches-memory-java11-X.Y.Z-sources.jar
+ * datasketches-memory-java11-X.Y.Z-test-sources.jar
+ * datasketches-memory-java11-X.Y.Z-javadoc.jar
+ * datasketches-memory-java11-X.Y.Z-pom
+
+* `datasketches-memory-java17_21/X.Y.Z/`:
+ * datasketches-memory-java17_21-X.Y.Z.jar
+ * datasketches-memory-java17_21-X.Y.Z-tests.jar
+ * datasketches-memory-java17_21-X.Y.Z-sources.jar
+ * datasketches-memory-java17_21-X.Y.Z-test-sources.jar
+ * datasketches-memory-java17_21-X.Y.Z-javadoc.jar
+ * datasketches-memory-java17_21-X.Y.Z-pom
---
@@ -176,3 +182,5 @@ Please visit the main [DataSketches
website](https://datasketches.apache.org) fo
If you are interested in making contributions to this Memory Project or to any
of the other DataSketches Projects please visit our
[Community](https://datasketches.apache.org/docs/Community/) page.
+
+/- LR
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
