Expose chunk-level HDF5 APIs (H5Dchunk_iter, direct chunk I/O) to Java (JNI + FFM)

java/hdf/hdf5lib/CMakeLists.txt

@@ -19,6 +19,8 @@ set (HDF5_JAVA_HDF_HDF5_CALLBACKS_SOURCES
     callbacks/H5A_iterate_t.java
     callbacks/H5D_append_cb.java
     callbacks/H5D_append_t.java
+    callbacks/H5D_chunk_iter_cb.java
+    callbacks/H5D_chunk_iter_t.java
     callbacks/H5D_iterate_cb.java
     callbacks/H5D_iterate_t.java
     callbacks/H5E_walk_cb.java
@@ -85,6 +87,7 @@ set (HDF5_JAVA_HDF_HDF5_STRUCTS_SOURCES
     structs/H5_ih_info_t.java
     structs/H5A_info_t.java
     structs/H5AC_cache_config_t.java
+    structs/H5D_chunk_info_t.java
     structs/H5E_error2_t.java
     structs/H5F_info2_t.java
     structs/H5G_info_t.java

java/hdf/hdf5lib/HDF5Constants.java

@@ -127,6 +127,16 @@ public class HDF5Constants {
     /** */
     public static final int H5D_CHUNK_IDX_BTREE = H5D_CHUNK_IDX_BTREE();
     /** */
+    public static final int H5D_CHUNK_IDX_SINGLE = H5D_CHUNK_IDX_SINGLE();
+    /** */
+    public static final int H5D_CHUNK_IDX_NONE = H5D_CHUNK_IDX_NONE();
+    /** */
+    public static final int H5D_CHUNK_IDX_FARRAY = H5D_CHUNK_IDX_FARRAY();
+    /** */
+    public static final int H5D_CHUNK_IDX_EARRAY = H5D_CHUNK_IDX_EARRAY();
+    /** */
+    public static final int H5D_CHUNK_IDX_BT2 = H5D_CHUNK_IDX_BT2();
+    /** */
     public static final int H5D_ALLOC_TIME_DEFAULT = H5D_ALLOC_TIME_DEFAULT();
     /** */
     public static final int H5D_ALLOC_TIME_EARLY = H5D_ALLOC_TIME_EARLY();

java/hdf/hdf5lib/callbacks/H5D_chunk_iter_cb.java

@@ -0,0 +1,50 @@
+/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+ * Copyright by The HDF Group.                                               *
+ * All rights reserved.                                                      *
+ *                                                                           *
+ * This file is part of HDF5.  The full HDF5 copyright notice, including     *
+ * terms governing use, modification, and redistribution, is contained in    *
+ * the LICENSE file, which can be found at the root of the source code       *
+ * distribution tree, or in https://www.hdfgroup.org/licenses.               *
+ * If you do not have access to either file, you may request a copy from     *
+ * help@hdfgroup.org.                                                        *
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+
+package hdf.hdf5lib.callbacks;
+
+import static org.hdfgroup.javahdf5.hdf5_h.*;
+
+import java.lang.foreign.MemorySegment;
+
+import org.hdfgroup.javahdf5.*;
+
+/**
+ * Information class for the chunk iterator callback for H5Dchunk_iter.
+ *
+ */
+public interface H5D_chunk_iter_cb extends org.hdfgroup.javahdf5.H5D_chunk_iter_op_t.Function {
+    /**
+     * @ingroup JCALLBK
+     *
+     *  application callback for each chunk of a chunked dataset
+     *
+     *  @param offset      the logical position of the chunk's first element in units of dataset
+     *                     elements, as a view over native memory owned by the underlying H5Dchunk_iter
+     *                     call. It is only valid for the duration of this callback invocation -- read
+     *                     the values out (e.g. via offset.toArray(ValueLayout.JAVA_LONG)) if they need
+     *                     to be retained after the callback returns.
+     *  @param filter_mask  bitmask indicating the filters used when the chunk was written
+     *  @param addr        the chunk address in the file, taking the user block (if any) into account
+     *  @param size        the chunk size in bytes, 0 if the chunk does not exist
+     *  @param op_data     the operator data passed in to H5Dchunk_iter
+     *
+     *  @return operation status
+     *      A. Zero causes the iterator to continue, returning zero when all
+     *          chunks have been processed.
+     *      B. Positive causes the iterator to immediately return that positive
+     *          value, indicating short-circuit success.
+     *      C. Negative causes the iterator to immediately return that value,
+     *          indicating failure.
+     */
+    int apply(MemorySegment offset, int filter_mask, long addr, long size, MemorySegment op_data);
+}

java/hdf/hdf5lib/callbacks/H5D_chunk_iter_t.java

@@ -0,0 +1,24 @@
+/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+ * Copyright by The HDF Group.                                               *
+ * All rights reserved.                                                      *
+ *                                                                           *
+ * This file is part of HDF5.  The full HDF5 copyright notice, including     *
+ * terms governing use, modification, and redistribution, is contained in    *
+ * the LICENSE file, which can be found at the root of the source code       *
+ * distribution tree, or in https://www.hdfgroup.org/licenses.               *
+ * If you do not have access to either file, you may request a copy from     *
+ * help@hdfgroup.org.                                                        *
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+
+package hdf.hdf5lib.callbacks;
+
+/**
+ * Data class for chunk iterator callback for H5Dchunk_iter.
+ *
+ */
+public interface H5D_chunk_iter_t {
+    /**
+     * public ArrayList iterdata = new ArrayList();
+     * Any derived interfaces must define the single public variable as above.
+     */
+}

java/hdf/hdf5lib/structs/H5D_chunk_info_t.java

@@ -0,0 +1,61 @@
+/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+ * Copyright by The HDF Group.                                               *
+ * All rights reserved.                                                      *
+ *                                                                           *
+ * This file is part of HDF5.  The full HDF5 copyright notice, including     *
+ * terms governing use, modification, and redistribution, is contained in    *
+ * the LICENSE file, which can be found at the root of the source code       *
+ * distribution tree, or in https://www.hdfgroup.org/licenses.               *
+ * If you do not have access to either file, you may request a copy from     *
+ * help@hdfgroup.org.                                                        *
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+
+package hdf.hdf5lib.structs;
+
+import java.io.Serializable;
+
+/**
+ * Bulk result of H5Dchunk_iter_all(), holding information about every chunk of a chunked dataset.
+ *
+ * To avoid one Java object allocation per chunk, the per-chunk fields are stored as parallel
+ * primitive arrays rather than an array of per-chunk objects; use {@link #getOffset(int, int)} to
+ * read a single chunk's offset coordinate.
+ *
+ */
+public class H5D_chunk_info_t implements Serializable {
+    private static final long serialVersionUID = -8091628506238589401L;
+
+    /** Number of dimensions (rank) of the dataset; used to interpret offset. */
+    public final int rank;
+    /** Flattened chunk offsets: chunk i's coordinate in dimension d is offset[i * rank + d]. */
+    public final long[] offset;
+    /** Bitmask indicating the filters used when each chunk was written; filterMask[i] for chunk i. */
+    public final int[] filterMask;
+    /** Chunk address in the file for each chunk; addr[i] for chunk i. */
+    public final long[] addr;
+    /** Chunk size in bytes for each chunk, 0 if the chunk does not exist; size[i] for chunk i. */
+    public final long[] size;
+
+    public H5D_chunk_info_t(int rank, long[] offset, int[] filterMask, long[] addr, long[] size)
+    {
+        this.rank       = rank;
+        this.offset     = offset;
+        this.filterMask = filterMask;
+        this.addr       = addr;
+        this.size       = size;
+    }
+
+    /**
+     * @return the number of chunks described by this object.
+     */
+    public int getNumChunks() { return filterMask.length; }
+
+    /**
+     * @param chunkIndex
+     *            index of the chunk, between 0 and getNumChunks() - 1.
+     * @param dim
+     *            dimension, between 0 and rank - 1.
+     * @return the logical position of the given chunk's first element in dimension dim.
+     */
+    public long getOffset(int chunkIndex, int dim) { return offset[chunkIndex * rank + dim]; }
+}

java/src-jni/hdf/hdf5lib/CMakeLists.txt

@@ -20,6 +20,8 @@ set (HDF5_JAVA_HDF_HDF5_CALLBACKS_SOURCES
     callbacks/H5A_iterate_t.java
     callbacks/H5D_append_cb.java
     callbacks/H5D_append_t.java
+    callbacks/H5D_chunk_iter_cb.java
+    callbacks/H5D_chunk_iter_t.java
     callbacks/H5D_iterate_cb.java
     callbacks/H5D_iterate_t.java
     callbacks/H5E_walk_cb.java
@@ -86,6 +88,7 @@ set (HDF5_JAVA_HDF_HDF5_STRUCTS_SOURCES
     structs/H5_ih_info_t.java
     structs/H5A_info_t.java
     structs/H5AC_cache_config_t.java
+    structs/H5D_chunk_info_t.java
     structs/H5E_error2_t.java
     structs/H5F_info2_t.java
     structs/H5FD_ros3_fapl_t.java