docs(bindings/java): for BlockingOperator

.github/workflows/bindings_java.yml

@@ -40,6 +40,20 @@ permissions:
   contents: read
 
 jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up JDK 17
+        uses: actions/setup-java@v3
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+          cache: 'maven'
+      - name: Build and test
+        working-directory: bindings/java
+        run: mvn spotless:check
+
   test:
     runs-on: ubuntu-latest
     steps:

bindings/java/README.md

@@ -57,3 +57,11 @@ You can run tests with the following command:
 ```shell
 mvn clean verify
 ```
+
+Additionally, this project uses [spotless](https://github.com/diffplug/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::
+
+```shell
+mvn spotless:apply
+```

bindings/java/pom.xml

@@ -60,6 +60,7 @@
 
         <maven-surefire-plugin.version>3.0.0</maven-surefire-plugin.version>
         <exec-maven-plugin.version>3.1.0</exec-maven-plugin.version>
+        <spotless.version>2.37.0</spotless.version>
     </properties>
 
     <dependencyManagement>
@@ -196,6 +197,26 @@
                     </execution>
                 </executions>
             </plugin>
+
+            <plugin>
+                <groupId>com.diffplug.spotless</groupId>
+                <artifactId>spotless-maven-plugin</artifactId>
+                <version>${spotless.version}</version>
+                <configuration>
+                    <java>
+                        <palantirJavaFormat>
+                            <version>2.30.0</version>
+                        </palantirJavaFormat>
+                        <!-- static imports first, then others, no blank lines  -->
+                        <importOrder>
+                            <order>\#|</order>
+                        </importOrder>
+                        <removeUnusedImports/>
+                        <trimTrailingWhitespace/>
+                        <endWithNewline/>
+                    </java>
+                </configuration>
+            </plugin>
         </plugins>
     </build>
 </project>

bindings/java/src/blocking_operator.rs

@@ -70,17 +70,17 @@ pub unsafe extern "system" fn Java_org_apache_opendal_BlockingOperator_read(
     mut env: JNIEnv,
     _: JClass,
     op: *mut BlockingOperator,
-    file: JString,
+    path: JString,
 ) -> jstring {
-    intern_read(&mut env, &mut *op, file).unwrap_or_else(|e| {
+    intern_read(&mut env, &mut *op, path).unwrap_or_else(|e| {
         e.throw(&mut env);
         JObject::null().into_raw()
     })
 }
 
-fn intern_read(env: &mut JNIEnv, op: &mut BlockingOperator, file: JString) -> Result<jstring> {
-    let file = env.get_string(&file)?;
-    let content = String::from_utf8(op.read(file.to_str()?)?)?;
+fn intern_read(env: &mut JNIEnv, op: &mut BlockingOperator, path: JString) -> Result<jstring> {
+    let path = env.get_string(&path)?;
+    let content = String::from_utf8(op.read(path.to_str()?)?)?;
     Ok(env.new_string(content)?.into_raw())
 }
 
@@ -92,23 +92,23 @@ pub unsafe extern "system" fn Java_org_apache_opendal_BlockingOperator_write(
     mut env: JNIEnv,
     _: JClass,
     op: *mut BlockingOperator,
-    file: JString,
+    path: JString,
     content: JString,
 ) {
-    intern_write(&mut env, &mut *op, file, content).unwrap_or_else(|e| {
+    intern_write(&mut env, &mut *op, path, content).unwrap_or_else(|e| {
         e.throw(&mut env);
     })
 }
 
 fn intern_write(
     env: &mut JNIEnv,
     op: &mut BlockingOperator,
-    file: JString,
+    path: JString,
     content: JString,
 ) -> Result<()> {
-    let file = env.get_string(&file)?;
+    let path = env.get_string(&path)?;
     let content = env.get_string(&content)?;
-    Ok(op.write(file.to_str()?, content.to_str()?.to_string())?)
+    Ok(op.write(path.to_str()?, content.to_str()?.to_string())?)
 }
 
 /// # Safety
@@ -119,17 +119,17 @@ pub unsafe extern "system" fn Java_org_apache_opendal_BlockingOperator_stat(
     mut env: JNIEnv,
     _: JClass,
     op: *mut BlockingOperator,
-    file: JString,
+    path: JString,
 ) -> jlong {
-    intern_stat(&mut env, &mut *op, file).unwrap_or_else(|e| {
+    intern_stat(&mut env, &mut *op, path).unwrap_or_else(|e| {
         e.throw(&mut env);
         0
     })
 }
 
-fn intern_stat(env: &mut JNIEnv, op: &mut BlockingOperator, file: JString) -> Result<jlong> {
-    let file = env.get_string(&file)?;
-    let metadata = op.stat(file.to_str()?)?;
+fn intern_stat(env: &mut JNIEnv, op: &mut BlockingOperator, path: JString) -> Result<jlong> {
+    let path = env.get_string(&path)?;
+    let metadata = op.stat(path.to_str()?)?;
     Ok(Box::into_raw(Box::new(metadata)) as jlong)
 }
 
@@ -141,14 +141,14 @@ pub unsafe extern "system" fn Java_org_apache_opendal_BlockingOperator_delete(
     mut env: JNIEnv,
     _: JClass,
     op: *mut BlockingOperator,
-    file: JString,
+    path: JString,
 ) {
-    intern_delete(&mut env, &mut *op, file).unwrap_or_else(|e| {
+    intern_delete(&mut env, &mut *op, path).unwrap_or_else(|e| {
         e.throw(&mut env);
     })
 }
 
-fn intern_delete(env: &mut JNIEnv, op: &mut BlockingOperator, file: JString) -> Result<()> {
-    let file = env.get_string(&file)?;
-    Ok(op.delete(file.to_str()?)?)
+fn intern_delete(env: &mut JNIEnv, op: &mut BlockingOperator, path: JString) -> Result<()> {
+    let path = env.get_string(&path)?;
+    Ok(op.delete(path.to_str()?)?)
 }

bindings/java/src/main/java/org/apache/opendal/BlockingOperator.java

@@ -21,33 +21,51 @@
 
 import java.util.Map;
 
+/**
+ * A blocking operator represents an underneath OpenDAL operator that
+ * accesses data synchronously.
+ */
 public class BlockingOperator extends NativeObject {
+    /**
+     * Construct a blocking operator:
+     *
+     * <p>
+     * You can find all possible schemes <a href="https://docs.rs/opendal/latest/opendal/enum.Scheme.html">here</a>
+     * and see what config options each service supports.
+     *
+     * @param schema the name of the underneath service to access data from.
+     * @param map a map of properties to construct the underneath operator.
+     */
     public BlockingOperator(String schema, Map<String, String> map) {
         super(constructor(schema, map));
     }
 
-    public void write(String fileName, String content) {
-        write(nativeHandle, fileName, content);
+    public void write(String path, String content) {
+        write(nativeHandle, path, content);
     }
 
-    public String read(String s) {
-        return read(nativeHandle, s);
+    public String read(String path) {
+        return read(nativeHandle, path);
     }
 
-    public void delete(String s) {
-        delete(nativeHandle, s);
+    public void delete(String path) {
+        delete(nativeHandle, path);
     }
 
-    public Metadata stat(String fileName) {
-        return new Metadata(stat(nativeHandle, fileName));
+    public Metadata stat(String path) {
+        return new Metadata(stat(nativeHandle, path));
     }
 
     @Override
     protected native void disposeInternal(long handle);
 
     private static native long constructor(String schema, Map<String, String> map);
-    private static native void write(long nativeHandle, String fileName, String content);
-    private static native String read(long nativeHandle, String fileName);
-    private static native void delete(long nativeHandle, String fileName);
+
+    private static native void write(long nativeHandle, String path, String content);
+
+    private static native String read(long nativeHandle, String path);
+
+    private static native void delete(long nativeHandle, String path);
+
     private static native long stat(long nativeHandle, String file);
 }

bindings/java/src/main/java/org/apache/opendal/Environment.java

@@ -60,5 +60,4 @@ public static String getClassifier() {
     public static String getVersion() {
         return INSTANCE.projectVersion;
     }
-
 }

bindings/java/src/main/java/org/apache/opendal/Metadata.java

@@ -34,6 +34,8 @@ public long getContentLength() {
 
     @Override
     protected native void disposeInternal(long handle);
+
     private static native boolean isFile(long nativeHandle);
+
     private static native long getContentLength(long nativeHandle);
 }

bindings/java/src/main/java/org/apache/opendal/NativeObject.java

@@ -30,8 +30,7 @@ private enum LibraryState {
         LOADED
     }
 
-    private static final AtomicReference<LibraryState> libraryLoaded =
-        new AtomicReference<>(LibraryState.NOT_LOADED);
+    private static final AtomicReference<LibraryState> libraryLoaded = new AtomicReference<>(LibraryState.NOT_LOADED);
 
     static {
         NativeObject.loadLibrary();
@@ -43,11 +42,7 @@ public static void loadLibrary() {
         }
 
         if (libraryLoaded.compareAndSet(LibraryState.NOT_LOADED, LibraryState.LOADING)) {
-            JarJniLoader.loadLib(
-                NativeObject.class,
-                "/native",
-                "opendal_java",
-                Environment.getClassifier());
+            JarJniLoader.loadLib(NativeObject.class, "/native", "opendal_java", Environment.getClassifier());
             libraryLoaded.set(LibraryState.LOADED);
             return;
         }

bindings/java/src/main/java/org/apache/opendal/Operator.java

@@ -25,7 +25,7 @@
 import java.util.concurrent.ConcurrentHashMap;
 
 public class Operator extends NativeObject {
-    private static AsyncRegistry registry()  {
+    private static AsyncRegistry registry() {
         return AsyncRegistry.INSTANCE;
     }
 
@@ -64,27 +64,30 @@ public Operator(String schema, Map<String, String> map) {
         super(constructor(schema, map));
     }
 
-    public CompletableFuture<Void> write(String fileName, String content) {
-        final long requestId = write(nativeHandle, fileName, content);
+    public CompletableFuture<Void> write(String path, String content) {
+        final long requestId = write(nativeHandle, path, content);
         return registry().take(requestId);
     }
 
-    public CompletableFuture<Metadata> stat(String fileName) {
-        final long requestId = stat(nativeHandle, fileName);
+    public CompletableFuture<Metadata> stat(String path) {
+        final long requestId = stat(nativeHandle, path);
         final CompletableFuture<Long> f = registry().take(requestId);
         return f.thenApply(Metadata::new);
     }
 
-    public CompletableFuture<String> read(String fileName) {
-        final long requestId = read(nativeHandle, fileName);
+    public CompletableFuture<String> read(String path) {
+        final long requestId = read(nativeHandle, path);
         return registry().take(requestId);
     }
 
     @Override
     protected native void disposeInternal(long handle);
 
     private static native long constructor(String schema, Map<String, String> map);
-    private static native long read(long nativeHandle, String fileName);
-    private static native long write(long nativeHandle, String fileName, String content);
+
+    private static native long read(long nativeHandle, String path);
+
+    private static native long write(long nativeHandle, String path, String content);
+
     private static native long stat(long nativeHandle, String file);
 }