#59 Make BaseKernel#eval() throw runtime EvaluationException

Author: m-dzianishchyts

jjava/pom.xml

@@ -41,6 +41,16 @@
             <artifactId>testcontainers</artifactId>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-junit-jupiter</artifactId>
+            <scope>test</scope>
+        </dependency>
         <dependency>
             <groupId>org.slf4j</groupId>
             <artifactId>slf4j-simple</artifactId>
@@ -189,6 +199,15 @@
                     </filesets>
                 </configuration>
             </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <configuration>
+                    <argLine>
+                        --add-opens jdk.jshell/jdk.jshell=ALL-UNNAMED
+                    </argLine>
+                </configuration>
+            </plugin>
         </plugins>
     </build>
 

jjava/src/main/java/org/dflib/jjava/JJavaExtension.java

@@ -25,10 +25,6 @@ public class JJavaExtension implements Extension {
 
     @Override
     public void install(BaseKernel kernel) {
-        try {
-            kernel.eval(STARTUP_SCRIPT);
-        } catch (Exception e) {
-            throw new RuntimeException(e);
-        }
+        kernel.eval(STARTUP_SCRIPT);
     }
 }

jjava/src/main/java/org/dflib/jjava/JavaKernel.java

@@ -39,6 +39,7 @@
 import org.dflib.jjava.execution.MagicsSourceTransformer;
 import org.dflib.jjava.jupyter.Extension;
 import org.dflib.jjava.jupyter.kernel.BaseKernel;
+import org.dflib.jjava.jupyter.kernel.EvaluationException;
 import org.dflib.jjava.jupyter.kernel.LanguageInfo;
 import org.dflib.jjava.jupyter.kernel.ReplacementOptions;
 import org.dflib.jjava.jupyter.kernel.display.DisplayData;
@@ -210,7 +211,9 @@ public boolean autoLoadExtensions() {
     }
 
     @Override
-    public List<String> formatError(Exception e) {
+    public List<String> formatError(Throwable e) {
+        if (e instanceof EvaluationException)
+            return formatError(e.getCause());
         if (e instanceof CompilationException) {
             return formatCompilationException((CompilationException) e);
         } else if (e instanceof IncompleteSourceException) {
@@ -338,15 +341,20 @@ public Object evalRaw(String expr) throws Exception {
     }
 
     @Override
-    public DisplayData eval(String expr) throws Exception {
-        Object result = this.evalRaw(expr);
-
-        if (result != null)
-            return result instanceof DisplayData
-                    ? (DisplayData) result
-                    : this.getRenderer().render(result);
+    public DisplayData eval(String expr) {
+        Object result;
+        try {
+            result = this.evalRaw(expr);
+        } catch (Exception e) {
+            throw new EvaluationException(e);
+        }
 
-        return null;
+        if (result == null) {
+            return null;
+        }
+        return result instanceof DisplayData
+                ? (DisplayData) result
+                : this.getRenderer().render(result);
     }
 
     @Override

jjava/src/test/java/org/dflib/jjava/JavaKernelTest.java

@@ -0,0 +1,22 @@
+package org.dflib.jjava;
+
+import org.dflib.jjava.jupyter.kernel.EvaluationException;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+public class JavaKernelTest {
+
+    @Test
+    public void eval_throwsRuntimeException() throws Exception {
+        JavaKernel kernel = new JavaKernel("0");
+        String expr = "invalid expression";
+
+        JavaKernel mockKernel = mock(JavaKernel.class);
+        when(mockKernel.evalRaw(expr)).thenThrow(new Exception("Evaluation error"));
+
+        assertThrows(EvaluationException.class, () -> kernel.eval(expr));
+    }
+}

jupyter-jvm-basekernel/src/main/java/org/dflib/jjava/jupyter/kernel/BaseKernel.java

@@ -161,7 +161,30 @@ public HistoryManager getHistoryManager() {
         return null;
     }
 
-    public abstract DisplayData eval(String expr) throws Exception;
+    /**
+     * Evaluates a code expression in the kernel's language environment and returns the result
+     * as display data. This is the core evaluation method called when executing code cells
+     * in a Jupyter notebook.
+     *
+     * <p>The implementation should:
+     * <ul>
+     *   <li>Parse and evaluate the provided expression string</li>
+     *   <li>Convert the evaluation result into appropriate display data formats</li>
+     *   <li>Handle any language-specific evaluation context/scope</li>
+     * </ul>
+     *
+     * <p>The returned {@link DisplayData} can contain multiple representations of the result
+     * (e.g. text/plain, text/html, image/png) to allow rich display in the notebook.
+     * Return null if the expression produces no displayable result.
+     *
+     * @param expr The code expression to evaluate as received from the Jupyter frontend
+     *
+     * @return A {@link DisplayData} object containing the evaluation result in one or more
+     *         MIME formats, or null if there is no displayable result
+     *
+     * @throws EvaluationException If an error occurs during expression evaluation
+     */
+    public abstract DisplayData eval(String expr);
 
     /**
      * Inspect the code to get things such as documentation for a function. This is
@@ -283,7 +306,7 @@ public void interrupt() {
      *         not include strings with newlines but rather separate strings each to go on a
      *         new line.
      */
-    public List<String> formatError(Exception e) {
+    public List<String> formatError(Throwable e) {
         List<String> lines = new LinkedList<>();
         lines.add(this.errorStyler.secondary("---------------------------------------------------------------------------"));
 

jupyter-jvm-basekernel/src/main/java/org/dflib/jjava/jupyter/kernel/EvaluationException.java

@@ -0,0 +1,10 @@
+package org.dflib.jjava.jupyter.kernel;
+
+import java.util.Objects;
+
+public class EvaluationException extends RuntimeException {
+
+    public EvaluationException(Throwable cause) {
+        super(Objects.requireNonNull(cause));
+    }
+}

pom.xml

@@ -53,6 +53,7 @@
         <hamcrest.version>1.3</hamcrest.version>
         <jimfs.version>1.3.0</jimfs.version>
         <testcontainers.version>1.20.2</testcontainers.version>
+        <mockito.version>5.3.1</mockito.version>
         <slf4j.version>1.7.36</slf4j.version>
     </properties>
 
@@ -126,6 +127,13 @@
                 <artifactId>testcontainers</artifactId>
                 <version>${testcontainers.version}</version>
             </dependency>
+            <dependency>
+                <groupId>org.mockito</groupId>
+                <artifactId>mockito-bom</artifactId>
+                <version>${mockito.version}</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
             <dependency>
                 <groupId>org.slf4j</groupId>
                 <artifactId>slf4j-simple</artifactId>