Add utility JNI function for 1.10 style references (#1888)

* Add utility JNI function for 1.10 style references

* Clarify text

* Correct signature

* Committing clang-format changes

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

java/src/hdf/hdf5lib/H5.java

@@ -11410,6 +11410,29 @@ public class H5 implements java.io.Serializable {
                                                        long size)
         throws HDF5LibraryException, NullPointerException, IllegalArgumentException;
 
+    /**
+     * H5Rget_name_string retrieves a name for the object identified by ref.
+     *
+     * @param loc_id
+     *            IN: Identifier for the dataset containing the reference or for the group that dataset is in.
+     * @param ref_type
+     *            IN: Type of reference.
+     * @param ref
+     *            IN: An object or dataset region reference.
+     *
+     * @return Returns the name if successful, returning null if no name is associated with
+     *         the identifier.
+     *
+     * @exception HDF5LibraryException
+     *            Error from the HDF-5 Library.
+     * @exception NullPointerException
+     *            size is null.
+     * @exception IllegalArgumentException
+     *            Argument is illegal.
+     **/
+    public synchronized static native String H5Rget_name_string(long loc_id, int ref_type, byte[] ref)
+        throws HDF5LibraryException, NullPointerException, IllegalArgumentException;
+
     /**
      * H5Rget_obj_type Given a reference to an object ref, H5Rget_obj_type returns the type of the object
      * pointed to.

java/src/jni/h5rImp.c

@@ -877,6 +877,67 @@ done:
     return ret_val;
 } /* end Java_hdf_hdf5lib_H5_H5Rget_1name */
 
+/*
+ * Class:     hdf_hdf5lib_H5
+ * Method:    H5Rget_name_string
+ * Signature: (JI[B)Ljava/lang/String;
+ */
+JNIEXPORT jstring JNICALL
+Java_hdf_hdf5lib_H5_H5Rget_1name_1string(JNIEnv *env, jclass clss, jlong loc_id, jint ref_type,
+                                         jbyteArray ref)
+{
+    jboolean isCopy;
+    jstring  str;
+    jsize    refBufLen;
+    jbyte *  refBuf   = NULL;
+    char *   aName    = NULL;
+    ssize_t  buf_size = -1;
+    jlong    ret_val  = -1;
+
+    UNUSED(clss);
+
+    if (NULL == ref)
+        H5_NULL_ARGUMENT_ERROR(ENVONLY, "H5Rget_name: reference buffer is NULL");
+
+    if ((refBufLen = ENVPTR->GetArrayLength(ENVONLY, ref)) < 0) {
+        CHECK_JNI_EXCEPTION(ENVONLY, JNI_TRUE);
+        H5_BAD_ARGUMENT_ERROR(ENVONLY, "H5Rget_name: ref array length < 0");
+    }
+
+    if ((H5R_OBJECT == ref_type) && (refBufLen != H5R_OBJ_REF_BUF_SIZE))
+        H5_BAD_ARGUMENT_ERROR(ENVONLY, "H5Rget_name: reference input array length != H5R_OBJ_REF_BUF_SIZE");
+    else if ((H5R_DATASET_REGION == ref_type) && (refBufLen != H5R_DSET_REG_REF_BUF_SIZE))
+        H5_BAD_ARGUMENT_ERROR(
+            ENVONLY, "H5Rget_name: region reference input array length != H5R_DSET_REG_REF_BUF_SIZE");
+    else if ((H5R_OBJECT != ref_type) && (H5R_DATASET_REGION != ref_type))
+        H5_BAD_ARGUMENT_ERROR(ENVONLY, "H5Rget_name: unknown reference type");
+
+    PIN_BYTE_ARRAY(ENVONLY, ref, refBuf, &isCopy, "H5Rget_name: reference buffer not pinned");
+
+    /* Get the length of the name */
+    if ((buf_size = H5Rget_name((hid_t)loc_id, (H5R_type_t)ref_type, refBuf, NULL, 0)) < 0)
+        H5_LIBRARY_ERROR(ENVONLY);
+
+    if (NULL == (aName = HDmalloc(sizeof(char) * (size_t)buf_size + 1)))
+        H5_OUT_OF_MEMORY_ERROR(ENVONLY, "H5Rget_name: failed to allocate referenced object name buffer");
+
+    if ((ret_val = (jlong)H5Rget_name((hid_t)loc_id, (H5R_type_t)ref_type, refBuf, aName,
+                                      (size_t)buf_size + 1)) < 0)
+        H5_LIBRARY_ERROR(ENVONLY);
+    aName[(size_t)buf_size] = '\0';
+
+    if (NULL == (str = ENVPTR->NewStringUTF(ENVONLY, aName)))
+        CHECK_JNI_EXCEPTION(ENVONLY, JNI_FALSE);
+
+done:
+    if (aName)
+        HDfree(aName);
+    if (refBuf)
+        UNPIN_BYTE_ARRAY(ENVONLY, ref, refBuf, JNI_ABORT);
+
+    return str;
+} /* end Java_hdf_hdf5lib_H5_H5Rget_1name_1string */
+
 #ifdef __cplusplus
 } /* end extern "C" */
 #endif /* __cplusplus */

java/src/jni/h5rImp.h

@@ -170,6 +170,13 @@ JNIEXPORT jint JNICALL Java_hdf_hdf5lib_H5_H5Rget_1obj_1type2(JNIEnv *, jclass,
 JNIEXPORT jlong JNICALL Java_hdf_hdf5lib_H5_H5Rget_1name(JNIEnv *, jclass, jlong, jint, jbyteArray,
                                                          jobjectArray, jlong);
 
+/*
+ * Class:     hdf_hdf5lib_H5
+ * Method:    H5Rget_name_string
+ * Signature: (JI[B)Ljava/lang/String;
+ */
+JNIEXPORT jstring JNICALL Java_hdf_hdf5lib_H5_H5Rget_1name_1string(JNIEnv *, jclass, jlong, jint, jbyteArray);
+
 #ifdef __cplusplus
 } /* end extern "C" */
 #endif /* __cplusplus */

release_docs/RELEASE.txt

@@ -89,6 +89,13 @@ New Features
 
     Java Library:
     -------------
+    - Added version of H5Rget_name to return the name as a Java string.
+
+      Other functions that get_name process the get_size then get the name
+      within the JNI implementation. Now H5Rget_name has a H5Rget_name_string.
+
+      (ADB - 2022/07/12)
+
     - Added reference support to H5A and H5D read write vlen JNI functions.
 
       Added the implementation to handle VL references as an Array of Lists