Help us improve by taking our short survey: https://www.hdfgroup.org/website-survey/

| HDF5 Last Updated on 2026-03-23 The HDF5 Field Guide

Loading...
Searching...
No Matches
Using HDF5 Maven Artifacts

Navigate back: Main / Cookbook

# Using HDF5 Java Bindings with Maven

Problem
  I want to use HDF5 Java bindings in my Maven project without building from source.

Solution
  HDF5 Java bindings are available as Maven artifacts with platform-specific JARs for both JNI and FFM implementations. Use the appropriate artifact and classifier for your platform and Java version.

## Maven Artifact Selection

HDF5 provides three main Maven artifacts:

Artifact ID | Java Version | Description | Status
--- | --- | --- | ---
hdf5-java-jni | Java 8+ | JNI implementation (default) | Production-ready
hdf5-java-ffm | Java 25+ | FFM implementation (future default) | Production-ready
hdf5-java-examples | Java 8+ | example programs | Platform-independent

Note: FFM will become the default implementation in the next major HDF5 release.

## Using JNI Implementation (Java 8+)

Basic Usage
  Add the following dependency to your `pom.xml`:

<dependency>
<groupId>org.hdfgroup</groupId>
<artifactId>hdf5-java-jni</artifactId>
<version>2.0.0</version>
<classifier>linux-x86_64</classifier>
</dependency>

Replace the classifier with your platform:

- `linux-x86_64` - Linux 64-bit
- `windows-x86_64` - Windows 64-bit
- `macos-x86_64` - macOS Intel
- `macos-aarch64` - macOS Apple Silicon

Java Code
  import hdf.hdf5lib.H5;
  import hdf.hdf5lib.HDF5Constants;
  public class MyHDF5App {
  public static void main(String[] args) throws Exception {
  // Initialize HDF5 library
  H5.H5open();
  // Your HDF5 operations here
  long file_id = H5.H5Fcreate("myfile.h5",
  HDF5Constants.H5F_ACC_TRUNC,
  HDF5Constants.H5P_DEFAULT,
  HDF5Constants.H5P_DEFAULT);
  // Clean up
  H5.H5Fclose(file_id);
  H5.H5close();
  }
  }
  H5
  Definition H5AbstractDs.cpp:33

## Using FFM Implementation (Java 25+)

Basic Usage
  Add the following dependency to your `pom.xml`:

<dependency>
<groupId>org.hdfgroup</groupId>
<artifactId>hdf5-java-ffm</artifactId>
<version>2.0.0</version>
<classifier>linux-x86_64</classifier>
</dependency>

Java Runtime Configuration
  FFM requires enabling native access:
  java --enable-native-access=ALL-UNNAMED -cp yourapp.jar com.example.Main

Or configure in `pom.xml`:

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<argLine>--enable-native-access=ALL-UNNAMED</argLine>
</configuration>
</plugin>

Java Code
  The API is identical to JNI - same code works with both implementations:
  import hdf.hdf5lib.H5;
  import hdf.hdf5lib.HDF5Constants;
  // Same code as JNI example above

## Using Java Examples

Adding Examples Artifact
  <dependency>
  <groupId>org.hdfgroup</groupId>
  <artifactId>hdf5-java-examples</artifactId>
  <version>2.0.0</version>
  </dependency>

The examples artifact contains 62 educational examples covering:

- File operations and dataset creation
- Compound datatypes and variable-length data
- Groups, attributes, and links
- Chunking, compression, and filters
- Parallel I/O examples

Running Examples
  # List available examples
  java -cp hdf5-java-examples-2.0.0.jar examples.intro.H5_CreateFile
  # Run a specific example
  java -cp "hdf5-java-jni-2.0.0-linux-x86_64.jar:hdf5-java-examples-2.0.0.jar" \
  examples.intro.H5_CreateFile
  hdf5
  Definition HDF5.F90:26

See `HDF5Examples/JAVA/README-MAVEN.md` for complete details.

## Maven Repositories

GitHub Packages (Current)
  HDF5 artifacts are published to GitHub Packages. Add this repository to your `pom.xml`:

<repositories>
<repository>
<id>github-hdfgroup</id>
<name>HDF Group GitHub Packages</name>
<url>https://maven.pkg.github.com/HDFGroup/hdf5</url>
</repository>
</repositories>

Note: GitHub Packages requires authentication even for public packages. Add credentials to your `~/.m2/settings.xml`:

<servers>
<server>
<id>github-hdfgroup</id>
<username>YOUR_GITHUB_USERNAME</username>
<password>YOUR_GITHUB_TOKEN</password>
</server>
</servers>

Generate a GitHub personal access token with `read:packages` permission.

Maven Central (Coming Soon)
  Future releases will be available on Maven Central, which does not require authentication:

<!-- Maven Central (future releases) -->
<dependency>
<groupId>org.hdfgroup</groupId>
<artifactId>hdf5-java-jni</artifactId>
<version>2.1.0</version>
<classifier>linux-x86_64</classifier>
</dependency>

## Troubleshooting

UnsatisfiedLinkError
  If you see `java.lang.UnsatisfiedLinkError`:
  - Verify you're using the correct platform classifier
  - Ensure only ONE HDF5 artifact (JNI or FFM) is on classpath
  - Check Java version matches implementation (Java 25+ for FFM)
  - Install HDF5 native libraries: `sudo apt-get install libhdf5-dev` (Linux) or `brew install hdf5` (macOS)

Native Access Error (FFM only)
  If you see `IllegalCallerException` with FFM:
  - Add `–enable-native-access=ALL-UNNAMED` to Java command
  - Or configure in build tool (Maven, Gradle)

Version Conflicts
  If you see dependency conflicts:
  - Use `<dependencyManagement>` to control versions
  - Exclude transitive HDF5 dependencies if needed
  - Ensure all HDF5 artifacts use the same version

## Migrating Between JNI and FFM

API Compatibility
  Both implementations use identical APIs:
  - Same package names: `hdf.hdf5lib.*`
  - Same class names: `H5, HDF5Constants`
  - Same method signatures
  - Same exception handling

Migration Steps
  1. Update artifact ID in `pom.xml`:
     - Change `hdf5-java-jni` to `hdf5-java-ffm`
     - Or vice versa
  2. For FFM: Add native access flag
     - `–enable-native-access=ALL-UNNAMED`
  3. Rebuild and test
     - No code changes required!

## Testing Maven Artifacts

Local Testing Scripts
  HDF5 provides test scripts to verify Maven artifacts work correctly:

cd HDF5Examples/JAVA
# Test JNI implementation
./test-maven-jni.sh 2.0.0
# Test FFM implementation
./test-maven-ffm.sh 2.0.0
# Test against custom repository
./test-maven-ffm.sh 2.0.0 https://maven.pkg.github.com/YOUR_FORK/hdf5

These scripts automatically:

- Configure GitHub authentication
- Download and verify JARs
- Compile and run example programs
- Report detailed test results

See `HDF5Examples/JAVA/README-MAVEN.md` for complete testing documentation.

See Also
  - CMake Presets Use Case: Java Bindings for building from source
  - release_docs/README.md for complete Maven documentation
  - HDF5Examples/JAVA/README-MAVEN.md for testing and examples with Maven
  - HDF5Examples/JAVA/test-maven-jni.sh for JNI artifact testing
  - HDF5Examples/JAVA/test-maven-ffm.sh for FFM artifact testing
  - https://github.com/HDFGroup/hdf5-examples for more examples

  Navigate back: Main / Cookbook