Skip to main content

Java

Apache OpenDAL™ Java Bindings

Maven Central Website

Note: This binding has its own independent version number, which may differ from the Rust core version. When checking for updates or compatibility, always refer to this binding's version rather than the core version.

Example​

import java.util.HashMap;
import java.util.Map;
import org.apache.opendal.AsyncOperator;
import org.apache.opendal.Operator;

public class Main {
  public static void main(String[] args) {
    final Map<String, String> conf = new HashMap<>();
    conf.put("root", "/tmp");

    try (AsyncOperator op = AsyncOperator.of("fs", conf)) {
      op.write("/path/to/data", "Hello world").join();
      System.out.println(new String(op.read("/path/to/data").join()));
    }
  }
}

Getting Started​

This project is built upon the native OpenDAL lib. And it is released for multiple platforms that you can use a classifier to specify the platform you are building the application on.

Maven​

Generally, you can first add the os-maven-plugin for automatically detect the classifier based on your platform:

<build>
<extensions>
  <extension>
    <groupId>kr.motd.maven</groupId>
    <artifactId>os-maven-plugin</artifactId>
    <version>1.7.0</version>
  </extension>
</extensions>
</build>

Then add the dependency to opendal as following:

<dependencies>
  <dependency>
    <groupId>org.apache.opendal</groupId>
    <artifactId>opendal</artifactId>
    <version>${opendal.version}</version>
  </dependency>
  <dependency>
    <groupId>org.apache.opendal</groupId>
    <artifactId>opendal</artifactId>
    <version>${opendal.version}</version>
    <classifier>${os.detected.classifier}</classifier>
  </dependency>
</dependencies>

Gradle​

For Gradle, you can first add the com.google.osdetector for automatically detect the classifier based on your platform:

plugins {
    id "com.google.osdetector" version "1.7.3"
}

Then add the dependency to `opendal as following:

dependencies {
    implementation "org.apache.opendal:opendal:$opendalVersion"
    implementation "org.apache.opendal:opendal:$opendalVersion:$osdetector.classifier"
}

Classified library​

Note that the dependency without classifier ships all classes and resources except the "opendal_java" shared library. And those with classifier bundle only the shared library.

For downstream usage, it's recommended:

  • Depend on the one without classifier to write code;
  • Depend on the classified ones with "test" for testing.

To load the shared library correctly, you can choose one of the following approaches:

  • Append the classified JARs to the classpath at the runtime;
  • Depend on the classified JARs and build a fat JAR (You may need to depend on all the provided classified JARs for running on multiple platforms);
  • Build your own "opendal_java" shared library and specify "-Djava.library.path" to the folder containing that shared library.

Build​

This project provides OpenDAL Java bindings with artifact name opendal. It depends on JDK 8 or later.

You can use Maven to build both Rust dynamic lib and JAR files with one command now:

./mvnw clean package -DskipTests=true

Run tests​

Currently, all tests are written in Java.

You can run the base tests with the following command:

./mvnw clean verify

Code style​

This project uses spotless for code formatting so that all developers share a consistent code style without bikeshedding on it.

You can apply the code style with the following command::

./mvnw spotless:apply

Run behavior tests​

Services behavior tests read necessary configs from env vars or the .env file.

You can copy .env.example to ${project.rootdir}/.env and change the values on need, or directly set env vars with export KEY=VALUE.

Take fs for example, we need to enable bench on fs on /tmp/:

OPENDAL_TEST=fs
OPENDAL_FS_ROOT=/tmp/

You can run service behavior tests of enabled with the following command:

./mvnw test -Dtest="behavior.*Test"

Remember to enable the necessary features via -Dcargo-build.features=services-xxx when running specific service test:

export OPENDAL_TEST=redis
export OPENDAL_REDIS_ENDPOINT=tcp://127.0.0.1:6379
export OPENDAL_REDIS_ROOT=/
export OPENDAL_REDIS_DB=0
./mvnw test -Dtest="behavior.*Test" -Dcargo-build.features=services-redis

Used by​

Check out the users list for more details on who is using OpenDAL.

License and Trademarks​

Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0

Apache OpenDAL, OpenDAL, and Apache are either registered trademarks or trademarks of the Apache Software Foundation.