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 31454e52 Add package-info detail
31454e52 is described below
commit 31454e52e75298496f5f475fea93d6450d4f681f
Author: Lee Rhodes <[email protected]>
AuthorDate: Tue Jun 2 11:34:09 2026 -0700
Add package-info detail
---
.github/workflows/auto-jdk-os-matrix.yml | 12 ++--
.github/workflows/stageReleaseSources.yml | 4 +-
.../apache/datasketches/memory/package-info.java | 80 +++++++++++++++++++++-
.../apache/datasketches/memory/package-info.java | 80 +++++++++++++++++++++-
4 files changed, 164 insertions(+), 12 deletions(-)
diff --git a/.github/workflows/auto-jdk-os-matrix.yml
b/.github/workflows/auto-jdk-os-matrix.yml
index ffa710fd..0942a084 100644
--- a/.github/workflows/auto-jdk-os-matrix.yml
+++ b/.github/workflows/auto-jdk-os-matrix.yml
@@ -1,12 +1,12 @@
name: JDK & OS Matrix Test
on:
-# push:
-# paths-ignore: [ '**/*.html', '**/*.md', '**/*.txt', '**/LICENSE',
'**/NOTICE' ]
-# branches: [ 'main', '[0-9]+.[0-9]+.[Xx]', 'v[0-9]+.[0-9]+.[Xx]']
-# pull_request:
-# paths-ignore: [ '**/*.html', '**/*.md', '**/*.txt', '**/LICENSE',
'**/NOTICE' ]
-# branches: [ 'main', '[0-9]+.[0-9]+.[Xx]', 'v[0-9]+.[0-9]+.[Xx]']
+ push:
+ paths-ignore: [ '**/*.html', '**/*.md', '**/*.txt', '**/LICENSE',
'**/NOTICE' ]
+ branches: [ 'main', '[0-9]+.[0-9]+.[Xx]', 'v[0-9]+.[0-9]+.[Xx]']
+ pull_request:
+ paths-ignore: [ '**/*.html', '**/*.md', '**/*.txt', '**/LICENSE',
'**/NOTICE' ]
+ branches: [ 'main', '[0-9]+.[0-9]+.[Xx]', 'v[0-9]+.[0-9]+.[Xx]']
workflow_dispatch:
concurrency:
diff --git a/.github/workflows/stageReleaseSources.yml
b/.github/workflows/stageReleaseSources.yml
index a0d4985c..d2386f43 100644
--- a/.github/workflows/stageReleaseSources.yml
+++ b/.github/workflows/stageReleaseSources.yml
@@ -1,4 +1,4 @@
-name: Stage Release Candidate Source Assets (Manual Trigger)
+name: Stage Release Sources (Manual Trigger)
# This workflow acts as Phase 1 of your official Release Candidate process.
# It handles the clean compilation, license verification, and source packaging
@@ -61,7 +61,7 @@ jobs:
- name: 5. Build Apache Source Release Archive
run: |
echo "Assembling project distribution ZIP..."
- mvn clean assembly:single
+ mvn clean assembly:single -N
# 6. Relocate and calculate the SHA-512 cryptographic checksum string
- name: 6. Stage Deliverables and Compute Checksums
diff --git
a/datasketches-memory-java11/src/main/java/org/apache/datasketches/memory/package-info.java
b/datasketches-memory-java11/src/main/java/org/apache/datasketches/memory/package-info.java
index cec46800..904b492e 100644
---
a/datasketches-memory-java11/src/main/java/org/apache/datasketches/memory/package-info.java
+++
b/datasketches-memory-java11/src/main/java/org/apache/datasketches/memory/package-info.java
@@ -18,7 +18,85 @@
*/
/**
- * <b>This package defines the interfaces for the DataSketches-Memory project
for Java 11.</b>
+ * <b>This package defines the interfaces for the DataSketches-Memory project
for Java 17 and Java 21.</b>
+ *
+ * <p>This project provides high performance primitive and primitive array
access to
+ * direct (native) off-heap memory and memory-mapped file resources, and
consistent views into
+ * {@link java.nio.ByteBuffer}, and on-heap primitive arrays. It can be used
as a more
+ * comprehensive and flexible replacement for {@link java.nio.ByteBuffer}.
+ *
+ * <p>In addition, this project provides:</p>
+ *
+ * <ul><li>Two different access APIs: read-only {@link
org.apache.datasketches.memory.Memory} and
+ * {@link org.apache.datasketches.memory.WritableMemory} for absolute offset
access,
+ * and read-only {@link org.apache.datasketches.memory.Buffer} and
+ * {@link org.apache.datasketches.memory.WritableBuffer}
+ * for relative positional access that is similar to ByteBuffer.</li>
+ *
+ * <li>Clean separation of Read-only API from Writable API, which makes
writable versus read-only
+ * resources detectable at compile time.</li>
+ *
+ * <li>The conversion from Writable to read-only is just a cast, so no
unnecessary objects are
+ * created. For example:
+ * <blockquote><pre>
+ * WritableMemory wMem = ...
+ * Memory mem = wMem;
+ * </pre></blockquote>
+ * </li>
+ *
+ * <li> {@link java.lang.AutoCloseable} for the external resources that
require it,
+ * which enables compile-time checks for non-closed resources.</li>
+ *
+ * <li>Immediate invalidation of all downstream references of an AutoCloseable
+ * resource when that resource is closed, either manually or by the JVM.
+ * This virtually eliminates the possibility of accidentally writing into the
memory space
+ * previously owned by a closed resource.</li>
+ *
+ * <li>Improved performance over previous implementations.</li>
+ *
+ * <li>No external runtime dependencies, which makes it simple to install in
virtually any Java environment.</li>
+ * </ul>
+ *
+ * <p>More specifically, this package provides access to four different types
of resources using
+ * two different access APIs. These resources are contiguous blobs of bytes
that provide at least
+ * byte-level read and write access. The four resources are:</p>
+ *
+ * <ul><li>Direct (a.k.a. Native) off-heap memory allocated by the user.</li>
+ * <li>Memory-mapped files, both writable and read-only.</li>
+ * <li>{@code ByteBuffers}, both heap-based and direct, writable and
read-only.</li>
+ * <li>Heap-based primitive arrays, which can be accessed as writable or
read-only.</li>
+ * </ul>
+ *
+ * <p>The two different access APIs are:</p>
+ * <ul><li><i>Memory, WritableMemory</i>: Absolute offset addressing into a
resource.</li>
+ * <li><i>Buffer, WritableBuffer</i>: Position relative addressing into a
resource.</li>
+ * </ul>
+ *
+ * <p>In addition, all combinations of access APIs and backing resources can
be accessed via
+ * multibyte primitive methods (e.g.
+ * <i>getLong(...), getLongArray(...), putLong(...), putLongArray(...)</i>) as
either
+ * {@link java.nio.ByteOrder#BIG_ENDIAN} or {@link
java.nio.ByteOrder#LITTLE_ENDIAN}.</p>
+ *
+ * <p>The resources don't know or care about the access APIs, and the access
+ * APIs don't really know or care what resource they are accessing.</p>
+ *
+ * <p>An access API is joined with a resource with a static factory method.
+ *
+ *<p>Moving back and forth between <i>Memory</i> and <i>Buffer</i>:</p>
+ *<blockquote><pre>
+ * Memory mem = ...
+ * Buffer buf = mem.asBuffer();
+ * ...
+ * Memory mem2 = buf.asMemory();
+ * ...
+ * </pre></blockquote>
+ *
+ * <p>Hierarchical memory regions can be easily created:</p>
+ * <blockquote><pre>
+ * WritableMemory wMem = ...
+ * WritableMemory wReg = wMem.writableRegion(offset, length); //OR
+ * Memory region = wMem.region(offset, length);
+ * </pre></blockquote>
*
* @author Lee Rhodes
*/
diff --git
a/datasketches-memory-java17_21/src/main/java/org/apache/datasketches/memory/package-info.java
b/datasketches-memory-java17_21/src/main/java/org/apache/datasketches/memory/package-info.java
index 17bc4916..2562abb1 100644
---
a/datasketches-memory-java17_21/src/main/java/org/apache/datasketches/memory/package-info.java
+++
b/datasketches-memory-java17_21/src/main/java/org/apache/datasketches/memory/package-info.java
@@ -18,10 +18,84 @@
*/
/**
- * <b>This package defines the interfaces for the DataSketches-Memory project
- * for Java 17 and Java 21.</b>
+ * <b>This package defines the interfaces for the DataSketches-Memory project
for Java 11.</b>
*
- * Note: Memory Mapping is disabled for this product.
+ * <p>This project provides high performance primitive and primitive array
access to
+ * direct (native) off-heap memory, and consistent views into
+ * {@link java.nio.ByteBuffer}, and on-heap primitive arrays. It can be used
as a more
+ * comprehensive and flexible replacement for {@link java.nio.ByteBuffer}.
+ *
+ * <p>In addition, this project provides:</p>
+ *
+ * <ul><li>Two different access APIs: read-only {@link
org.apache.datasketches.memory.Memory} and
+ * {@link org.apache.datasketches.memory.WritableMemory} for absolute offset
access,
+ * and read-only {@link org.apache.datasketches.memory.Buffer} and
+ * {@link org.apache.datasketches.memory.WritableBuffer}
+ * for relative positional access that is similar to ByteBuffer.</li>
+ *
+ * <li>Clean separation of Read-only API from Writable API, which makes
writable versus read-only
+ * resources detectable at compile time.</li>
+ *
+ * <li>The conversion from Writable to read-only is just a cast, so no
unnecessary objects are
+ * created. For example:
+ * <blockquote><pre>
+ * WritableMemory wMem = ...
+ * Memory mem = wMem;
+ * </pre></blockquote>
+ * </li>
+ *
+ * <li> {@link java.lang.AutoCloseable} for the external resources that
require it,
+ * which enables compile-time checks for non-closed resources.</li>
+ *
+ * <li>Immediate invalidation of all downstream references of an AutoCloseable
+ * resource when that resource is closed, either manually or by the JVM.
+ * This virtually eliminates the possibility of accidentally writing into the
memory space
+ * previously owned by a closed resource.</li>
+ *
+ * <li>Improved performance over previous implementations.</li>
+ *
+ * <li>No external runtime dependencies, which makes it simple to install in
virtually any Java environment.</li>
+ * </ul>
+ *
+ * <p>More specifically, this package provides access to three different types
of resources using
+ * two different access APIs. These resources are contiguous blobs of bytes
that provide at least
+ * byte-level read and write access. The three resources are:</p>
+ *
+ * <ul><li>Direct (a.k.a. Native) off-heap memory allocated by the user.</li>
+ * <li>{@code ByteBuffers}, both heap-based and direct, writable and
read-only.</li>
+ * <li>Heap-based primitive arrays, which can be accessed as writable or
read-only.</li>
+ * </ul>
+ *
+ * <p>The two different access APIs are:</p>
+ * <ul><li><i>Memory, WritableMemory</i>: Absolute offset addressing into a
resource.</li>
+ * <li><i>Buffer, WritableBuffer</i>: Position relative addressing into a
resource.</li>
+ * </ul>
+ *
+ * <p>In addition, all combinations of access APIs and backing resources can
be accessed via
+ * multibyte primitive methods (e.g.
+ * <i>getLong(...), getLongArray(...), putLong(...), putLongArray(...)</i>) as
either
+ * {@link java.nio.ByteOrder#BIG_ENDIAN} or {@link
java.nio.ByteOrder#LITTLE_ENDIAN}.</p>
+ *
+ * <p>The resources don't know or care about the access APIs, and the access
+ * APIs don't really know or care what resource they are accessing.</p>
+ *
+ * <p>An access API is joined with a resource with a static factory method.
+ *
+ *<p>Moving back and forth between <i>Memory</i> and <i>Buffer</i>:</p>
+ *<blockquote><pre>
+ * Memory mem = ...
+ * Buffer buf = mem.asBuffer();
+ * ...
+ * Memory mem2 = buf.asMemory();
+ * ...
+ * </pre></blockquote>
+ *
+ * <p>Hierarchical memory regions can be easily created:</p>
+ * <blockquote><pre>
+ * WritableMemory wMem = ...
+ * WritableMemory wReg = wMem.writableRegion(offset, length); //OR
+ * Memory region = wMem.region(offset, length);
+ * </pre></blockquote>
*
* @author Lee Rhodes
*/
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
