README.md

Apache OpenDAL™ Java Bindings

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.

Useful Links

• Documentation
• Upgrade Guide

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.