chore(bindings/java): improve OpenDALException tests and docs (#2343)

Signed-off-by: tison <[email protected]>

bindings/java/pom.xml

@@ -55,7 +55,9 @@
         <!-- Use camelCase instead of separating by dots to workaround PowerShell parsing. -->
         <jniClassifier>${os.detected.classifier}</jniClassifier>
 
+        <assertj-version>3.23.1</assertj-version>
         <questdb.version>1.0.0</questdb.version>
+
         <maven-surefire-plugin.version>3.0.0</maven-surefire-plugin.version>
         <exec-maven-plugin.version>3.1.0</exec-maven-plugin.version>
     </properties>
@@ -76,6 +78,11 @@
                 <type>pom</type>
                 <scope>import</scope>
             </dependency>
+            <dependency>
+                <groupId>org.assertj</groupId>
+                <artifactId>assertj-core</artifactId>
+                <version>${assertj-version}</version>
+            </dependency>
         </dependencies>
     </dependencyManagement>
 
@@ -106,6 +113,11 @@
             <artifactId>junit-jupiter</artifactId>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <build>

bindings/java/src/error.rs

@@ -39,7 +39,7 @@ impl Error {
         &self,
         env: &mut JNIEnv<'local>,
     ) -> jni::errors::Result<JThrowable<'local>> {
-        let class = env.find_class("org/apache/opendal/exception/ODException")?;
+        let class = env.find_class("org/apache/opendal/exception/OpenDALException")?;
         let code = env.new_string(match self.inner.kind() {
             ErrorKind::Unexpected => "Unexpected",
             ErrorKind::Unsupported => "Unsupported",

bindings/java/src/main/java/org/apache/opendal/exception/ODException.java → bindings/java/src/main/java/org/apache/opendal/exception/OpenDALException.java

@@ -19,23 +19,46 @@
 
 package org.apache.opendal.exception;
 
-public class ODException extends RuntimeException {
+/**
+ * A OpenDALException encapsulates the error of an operation. This exception
+ * type is used to describe an internal error from the native opendal library.
+ */
+public class OpenDALException extends RuntimeException {
     private final Code code;
 
-    @SuppressWarnings("unused") // called by jni-rs
-    public ODException(String code, String message) {
+    /**
+     * Construct an OpenDALException. This is called from JNI bindings code.
+     *
+     * @param code string representation of the error code
+     * @param message error message
+     */
+    @SuppressWarnings("unused")
+    public OpenDALException(String code, String message) {
         this(Code.valueOf(code), message);
     }
 
-    public ODException(Code code, String message) {
+    public OpenDALException(Code code, String message) {
         super(message);
         this.code = code;
     }
 
+    /**
+     * Get the error code returned from OpenDAL.
+     *
+     * @return The error code reported by OpenDAL.
+     */
     public Code getCode() {
         return code;
     }
 
+    /**
+     * Enumerate all kinds of Error that OpenDAL may return.
+     *
+     * <p>
+     * Read the document of
+     * <a href="https://docs.rs/opendal/latest/opendal/enum.ErrorKind.html">opendal::ErrorKind</a>
+     * for the details of each code.
+     */
     public enum Code {
         Unexpected,
         Unsupported,

bindings/java/src/test/java/org/apache/opendal/ExceptionTest.java → bindings/java/src/test/java/org/apache/opendal/BlockingOperatorTest.java

@@ -19,17 +19,16 @@
 
 package org.apache.opendal;
 
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
 import java.util.HashMap;
 import java.util.Map;
-import org.apache.opendal.exception.ODException;
+import org.apache.opendal.exception.OpenDALException;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
-import static org.junit.jupiter.api.Assertions.assertEquals;
-import static org.junit.jupiter.api.Assertions.assertThrows;
-
-public class ExceptionTest {
+public class BlockingOperatorTest {
     private BlockingOperator op;
 
     @BeforeEach
@@ -46,7 +45,20 @@ public void clean() {
 
     @Test
     public void testStatNotExistFile() {
-        final ODException exception = assertThrows(ODException.class, () -> op.stat("not_exist_file"));
-        assertEquals(ODException.Code.NotFound, exception.getCode());
+        assertThatExceptionOfType(OpenDALException.class)
+            .isThrownBy(() -> op.stat("nonexistence"))
+            .extracting(OpenDALException::getCode)
+            .isEqualTo(OpenDALException.Code.NotFound);
+    }
+
+    @Test
+    public void testCreateAndDelete() {
+        op.write("testCreateAndDelete", "Odin");
+        assertThat(op.read("testCreateAndDelete")).isEqualTo("Odin");
+        op.delete("testCreateAndDelete");
+        assertThatExceptionOfType(OpenDALException.class)
+            .isThrownBy(() -> op.stat("testCreateAndDelete"))
+            .extracting(OpenDALException::getCode)
+            .isEqualTo(OpenDALException.Code.NotFound);
     }
 }

bindings/java/tools/build.py

@@ -59,15 +59,15 @@ def get_cargo_artifact_name(classifier: str) -> str:
     target = classifier_to_target(args.classifier)
     if target:
         command = ['rustup', 'target', 'add', target]
-        print(subprocess.list2cmdline(command))
+        print('$ ' + subprocess.list2cmdline(command))
         subprocess.run(command, cwd=basedir, check=True)
         cmd += ['--target', target]
 
     output = basedir / 'target' / 'bindings'
     Path(output).mkdir(exist_ok=True, parents=True)
     cmd += ['--target-dir', output]
 
-    print(subprocess.list2cmdline(cmd))
+    print('$ ' + subprocess.list2cmdline(cmd))
     subprocess.run(cmd, cwd=basedir, check=True)
 
     artifact = get_cargo_artifact_name(args.classifier)