Add hdf5-native Maven JARs and SciJava native-lib-loader integration

[matteodg]

Fixes #6355

I created this with Cursor, as my knowledge of CMake is basically zero: I tried to do it myself, but I was not able. I tested this in Linux x86_64 and Windows x86_64 and it is creating the proper jar and pom.xml file, that I can install in my local Maven repository and depend on them from an example application. This was there is not need of installing HDF5 library or setting up LD_LIBRARY_PATH anymore.

This will be useful for the future of HDFView as well.

[brtnfld]

Must Fix:
FFM H5.java static block lacks try-catch around Hdf5NativeLoader call -- NoClassDefFoundError will permanently break H5 if the native-lib-loader JAR is missing

The FFM [H5.java:314] calls Hdf5NativeLoader.loadBundledNativesIfPresent(false) with no try-catch in the static block. If native-lib-loader-2.5.0.jar is missing from the classpath, loading Hdf5NativeLoader will throw NoClassDefFoundError (because it imports org.scijava.nativelib.NativeLoader), which will cause an ExceptionInInitializerError that permanently prevents H5 from being used in that JVM.

The JNI [H5.java:366-374] correctly wraps the call in catch (Throwable err), which handles this. The FFM version does not. The FFM path should have the same protection.

Nice to have:

• Partial-load when JNI bridge fails but hdf5 succeeds -- works correctly but worth a comment
• [docs] Transitive native deps (zlib, szip) not bundled -- "zero-install" doesn't hold if HDF5 was built with external filters

Moderate:

• Duplicate POM profiles across two pom.xml.in files -- The 5 OS-activated profiles (~70 lines each) in pom.xml.in and pom-jni.xml.in) are nearly identical (JNI version adds hdf5-jni-native dependency). This is a lot of duplicated XML that will need to be kept in sync. Not easily avoidable with Maven profiles though.
  HDF5JavaNativeBundles.cmake is include()'d, not add_subdirectory() -- This means all its variables leak into the parent scope. The leading underscores help, but it's still a code smell. Consider using add_subdirectory() or wrapping in a function.

Low Severity

• Regex in validate-maven-artifacts.sh is getting unwieldy ([line 30]

grep -qE "<artifactId>hdf5-java(-ffm|-jni)?</artifactId>|<artifactId>hdf5-native</artifactId>|<artifactId>hdf5-jni-native</artifactId>|<artifactId>hdf5-java-examples</artifactId>"

Consider using a simpler pattern like hdf5-(java|native|jni-native) or an array-based check.

• find with -exec cp {} may clobber files -- In ctest.yml and maven-staging.yml, multiple POM files with different names (pom.xml, pom-hdf5-native.xml, etc.) are copied to a flat directory. If there are multiple pom.xml files from different build directories, later ones overwrite earlier ones. This was a pre-existing issue but is now slightly more likely to bite.

• The _np and _jp variable names in maven-deploy.yml ([lines 112-116] are cryptic. Minor, but NATIVE_POM / JNI_NATIVE_POM would be clearer.

• RELEASE_PROCESS.md change crams a lot of information into a single bullet point that's now very long and hard to parse.

Verify:

• Vendored JAR should be checksum-verified against Maven Central; license acknowledged

[brtnfld]

"Must Fix" needs to be addressed.

[brtnfld]

• Replace err.printStackTrace() with proper logging

In both java/hdf/hdf5lib/H5.java (FFM) and java/src-jni/hdf/hdf5lib/H5.java (JNI), replace:

catch (Throwable err) {
    err.printStackTrace();
}

with:

catch (Throwable err) {
    log.debug("Bundled HDF5 native library not loaded: " + err.getMessage());
}

• Remove the unused _HDF5JAVA_NATIVE_POM_DATE variable

In java/cmake/HDF5JavaNativeBundles.cmake:

string (TIMESTAMP _HDF5JAVA_NATIVE_POM_DATE "%Y-%m-%d %H:%M:%S UTC" UTC)
This is computed at configure time but never used anywhere in the file

Nice to have:

• Add trailing newline to both new POM template files

java/cmake/pom-native.xml.in and java/cmake/pom-jni-native.xml.in both end without a newline (\ No newline at end of file). Add a newline at the end of each.

• Clarify isHdf5LibraryLoaded dual semantics
  File: java/src-jni/hdf/hdf5lib/H5.java

The problem: isHdf5LibraryLoaded is set in two unrelated places with different meanings:

In the bundled loader block — means "bundled hdf5 loaded"
At H5.H5dont_atexit() — means "hdf5 is confirmed loaded by any means"
A reader maintaining this code later will think the second assignment is a copy-paste error and delete it.

— split the flag's responsibilities):

Replace the two flags with three, each with a single clear meaning:

private static boolean isHdf5LibraryLoaded     = false; // bundled hdf5 load succeeded
private static boolean isHdf5JavaLibraryLoaded = false; // hdf5_java load succeeded
private static boolean isInitialized           = false; // full loadH5Lib() completed

Change the early-exit guard from:

if (isHdf5LibraryLoaded && isHdf5JavaLibraryLoaded)
    return;

to:

if (isInitialized)
    return;

Change the H5.H5dont_atexit() block from:

        try {
            H5.H5dont_atexit();
            isHdf5LibraryLoaded = true;
        }
        catch (HDF5LibraryException e) {
            System.exit(1);
        }

to:

        try {
            H5.H5dont_atexit();
            isInitialized = true;
        }
        catch (HDF5LibraryException e) {
            System.exit(1);
        }

This way isHdf5LibraryLoaded tracks only the bundled load result, isHdf5JavaLibraryLoaded tracks only the JNI bridge load result, and isInitialized guards against redundant re-entry.

[mkitti]

The Formatting Check CI job is failing due to clang-format line-wrapping in the new Hdf5NativeLoader.java doc comments (unrelated to the javadoc/#6504 issue discussed elsewhere on this PR). Posted the two suggested reflows below — they match exactly what clang-format17 --style=file produces for this file.

[mkitti]

Via Copilot:

CI is failing in Maven Staging Repository Test during CPack install, not compilation. The packaging step tries to install java/src-jni/hdf/hdf5lib/javadoc/hdf5_java_doc, but that file doesn’t exist, so file INSTALL aborts.

Minimal fix: guard the Javadoc install rule with if(EXISTS ...) or ensure the Javadoc output is generated before packaging. This should unblock CPack without affecting the native JAR packaging.

if (EXISTS "${CMAKE_CURRENT_BINARY_DIR}/javadoc/hdf5_java_doc")
  install(
    FILES "${CMAKE_CURRENT_BINARY_DIR}/javadoc/hdf5_java_doc"
    DESTINATION ${HDF5_INSTALL_JAR_DIR}
    COMPONENT maven
  )
endif()

I will take a look and see if I make the fix into a suggestion.

[mkitti]

Suggested change

	include (${HDF5_SOURCE_DIR}/java/cmake/HDF5JavaJavadoc.cmake)
	hdf5_java_add_javadoc_target (
	"${HDF5_JAVA_LOGGING_JAR};${HDF5_JAVA_NATIVE_LIB_LOADER_JAR}"
	)
	include (${HDF5_SOURCE_DIR}/java/cmake/HDF5JavaJavadoc.cmake)
	hdf5_java_add_javadoc_target (
	"${HDF5_JAVA_LOGGING_JAR};${HDF5_JAVA_NATIVE_LIB_LOADER_JAR}"
	)
	if (EXISTS "${CMAKE_CURRENT_BINARY_DIR}/javadoc/hdf5_java_doc")
	install(
	FILES "${CMAKE_CURRENT_BINARY_DIR}/javadoc/hdf5_java_doc"
	DESTINATION ${HDF5_INSTALL_JAR_DIR}
	COMPONENT maven
	)
	endif()