feat: typed DataFusionException hierarchy across the JNI boundary (#81)

Author: LantaoJin

core/src/main/java/org/apache/datafusion/ConfigurationException.java

@@ -0,0 +1,37 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.datafusion;
+
+/**
+ * Invalid or unrecognised DataFusion configuration option. Surfaces upstream {@code
+ * DataFusionError::Configuration}.
+ */
+public class ConfigurationException extends DataFusionException {
+
+  private static final long serialVersionUID = 1L;
+
+  public ConfigurationException(String message) {
+    super(message);
+  }
+
+  public ConfigurationException(String message, Throwable cause) {
+    super(message, cause);
+  }
+}

core/src/main/java/org/apache/datafusion/DataFusionException.java

@@ -0,0 +1,45 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.datafusion;
+
+/**
+ * Base unchecked exception for every error surfaced from the native DataFusion side.
+ *
+ * <p>Concrete subclasses correspond to caller-relevant error categories (planning, execution, IO,
+ * resources, configuration, not-implemented). Variants of {@code DataFusionError} on the Rust side
+ * that don't fit a clean caller-facing category surface as the parent class itself.
+ *
+ * <p>All subclasses extend {@link RuntimeException} so existing callers that {@code catch
+ * (RuntimeException)} keep working unchanged. Callers that want to discriminate can {@code catch
+ * (PlanException)} / {@code catch (ResourcesExhaustedException)} etc., or {@code catch
+ * (DataFusionException)} for "anything from DataFusion".
+ */
+public class DataFusionException extends RuntimeException {
+
+  private static final long serialVersionUID = 1L;
+
+  public DataFusionException(String message) {
+    super(message);
+  }
+
+  public DataFusionException(String message, Throwable cause) {
+    super(message, cause);
+  }
+}

core/src/main/java/org/apache/datafusion/ExecutionException.java

@@ -0,0 +1,42 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.datafusion;
+
+/**
+ * Runtime execution failure: a UDF threw, a join task panicked, an external (non-DataFusion) error
+ * propagated up, or an FFI-level failure surfaced. Surfaces upstream {@code
+ * DataFusionError::Execution}, {@code ExecutionJoin}, {@code External}, and {@code Ffi}.
+ *
+ * <p>Note: this is {@code org.apache.datafusion.ExecutionException}, distinct from {@code
+ * java.util.concurrent.ExecutionException}. A file that needs both should fully-qualify one or
+ * import them with care.
+ */
+public class ExecutionException extends DataFusionException {
+
+  private static final long serialVersionUID = 1L;
+
+  public ExecutionException(String message) {
+    super(message);
+  }
+
+  public ExecutionException(String message, Throwable cause) {
+    super(message, cause);
+  }
+}

core/src/main/java/org/apache/datafusion/IoException.java

@@ -0,0 +1,44 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.datafusion;
+
+/**
+ * IO-shaped failure: a local filesystem read failed, an object store request failed, or a parquet /
+ * arrow / avro decoder reported a malformed file. Surfaces upstream {@code
+ * DataFusionError::IoError}, {@code ObjectStore}, {@code ArrowError}, {@code ParquetError}, and
+ * {@code AvroError}.
+ *
+ * <p>Note: this is {@code org.apache.datafusion.IoException} (lowercase {@code o}), distinct from
+ * {@code java.io.IOException}. The {@code IoException} spelling matches the orthography of the
+ * underlying {@code DataFusionError::IoError} variant; a file that needs both should fully-qualify
+ * one.
+ */
+public class IoException extends DataFusionException {
+
+  private static final long serialVersionUID = 1L;
+
+  public IoException(String message) {
+    super(message);
+  }
+
+  public IoException(String message, Throwable cause) {
+    super(message, cause);
+  }
+}

core/src/main/java/org/apache/datafusion/NotImplementedException.java

@@ -0,0 +1,37 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.datafusion;
+
+/**
+ * The requested feature is recognised by DataFusion but not implemented yet. Surfaces upstream
+ * {@code DataFusionError::NotImplemented}.
+ */
+public class NotImplementedException extends DataFusionException {
+
+  private static final long serialVersionUID = 1L;
+
+  public NotImplementedException(String message) {
+    super(message);
+  }
+
+  public NotImplementedException(String message, Throwable cause) {
+    super(message, cause);
+  }
+}

core/src/main/java/org/apache/datafusion/PlanException.java

@@ -0,0 +1,37 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.datafusion;
+
+/**
+ * SQL parsing, logical planning, or schema-resolution failure. Surfaces upstream {@code
+ * DataFusionError::Plan}, {@code DataFusionError::SQL}, and {@code DataFusionError::SchemaError}.
+ */
+public class PlanException extends DataFusionException {
+
+  private static final long serialVersionUID = 1L;
+
+  public PlanException(String message) {
+    super(message);
+  }
+
+  public PlanException(String message, Throwable cause) {
+    super(message, cause);
+  }
+}

core/src/main/java/org/apache/datafusion/ResourcesExhaustedException.java

@@ -0,0 +1,40 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.datafusion;
+
+/**
+ * The DataFusion runtime exhausted a configured resource budget — typically the memory pool, but
+ * applies to any guard upstream surfaces as {@code DataFusionError::ResourcesExhausted}.
+ *
+ * <p>Distinguishing this from {@link ExecutionException} lets callers retry transient
+ * resource-pressure failures without retrying genuine query bugs.
+ */
+public class ResourcesExhaustedException extends DataFusionException {
+
+  private static final long serialVersionUID = 1L;
+
+  public ResourcesExhaustedException(String message) {
+    super(message);
+  }
+
+  public ResourcesExhaustedException(String message, Throwable cause) {
+    super(message, cause);
+  }
+}

core/src/test/java/org/apache/datafusion/DataFusionExceptionTest.java

@@ -0,0 +1,84 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.datafusion;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertInstanceOf;
+import static org.junit.jupiter.api.Assertions.assertSame;
+
+import org.junit.jupiter.api.Test;
+
+class DataFusionExceptionTest {
+
+  @Test
+  void parentExtendsRuntimeException() {
+    DataFusionException e = new DataFusionException("x");
+    assertInstanceOf(RuntimeException.class, e);
+    assertEquals("x", e.getMessage());
+  }
+
+  @Test
+  void parentCauseConstructorPropagatesCause() {
+    Throwable cause = new IllegalStateException("inner");
+    DataFusionException e = new DataFusionException("outer", cause);
+    assertEquals("outer", e.getMessage());
+    assertSame(cause, e.getCause());
+  }
+
+  @Test
+  void allSubclassesExtendDataFusionException() {
+    // Each subclass must extend the parent so callers can `catch
+    // (DataFusionException)` for "anything from DataFusion" and `catch
+    // (RuntimeException)` keeps working unchanged.
+    assertInstanceOf(DataFusionException.class, new PlanException("x"));
+    assertInstanceOf(DataFusionException.class, new ExecutionException("x"));
+    assertInstanceOf(DataFusionException.class, new ResourcesExhaustedException("x"));
+    assertInstanceOf(DataFusionException.class, new IoException("x"));
+    assertInstanceOf(DataFusionException.class, new NotImplementedException("x"));
+    assertInstanceOf(DataFusionException.class, new ConfigurationException("x"));
+  }
+
+  @Test
+  void allSubclassesExtendRuntimeException() {
+    // Existing callers use `catch (RuntimeException)`. A typed-exception PR
+    // that breaks them is a regression even if the new types are correct.
+    assertInstanceOf(RuntimeException.class, new PlanException("x"));
+    assertInstanceOf(RuntimeException.class, new ExecutionException("x"));
+    assertInstanceOf(RuntimeException.class, new ResourcesExhaustedException("x"));
+    assertInstanceOf(RuntimeException.class, new IoException("x"));
+    assertInstanceOf(RuntimeException.class, new NotImplementedException("x"));
+    assertInstanceOf(RuntimeException.class, new ConfigurationException("x"));
+  }
+
+  @Test
+  void allSubclassesAcceptCauseConstructor() {
+    // The (String, Throwable) constructor is the seam upstream issue #55
+    // plugs into for Java-throwable propagation from JVM upcalls. v1 has no
+    // production caller for it, but it must exist on every subclass so #55
+    // doesn't have to add it later.
+    Throwable cause = new IllegalStateException("c");
+    assertSame(cause, new PlanException("m", cause).getCause());
+    assertSame(cause, new ExecutionException("m", cause).getCause());
+    assertSame(cause, new ResourcesExhaustedException("m", cause).getCause());
+    assertSame(cause, new IoException("m", cause).getCause());
+    assertSame(cause, new NotImplementedException("m", cause).getCause());
+    assertSame(cause, new ConfigurationException("m", cause).getCause());
+  }
+}