From bbd1b62b1da2a47cef5624da462d0e16dfe35e31 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Wed, 14 Jan 2026 17:13:02 +0100 Subject: [PATCH 01/49] feat(notebook): consolidate compiler workflow and demo magics - Use %%compile for all compilation examples - Add Lombok example and Greeter demo - Fix %%write usage and reorder notebook --- docs/notebooks/ijava_sample_notebook.ipynb | 598 +++++++++++++++++++++ src/main/resources/install.py | 20 + 2 files changed, 618 insertions(+) create mode 100644 docs/notebooks/ijava_sample_notebook.ipynb diff --git a/docs/notebooks/ijava_sample_notebook.ipynb b/docs/notebooks/ijava_sample_notebook.ipynb new file mode 100644 index 0000000..0029aa8 --- /dev/null +++ b/docs/notebooks/ijava_sample_notebook.ipynb @@ -0,0 +1,598 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "61062e46", + "metadata": {}, + "source": [ + "# IJava — Quick reference and magics demo\n", + "\n", + "Concise walkthrough showing IJava features and magics. This notebook uses `%%compile` for compilation and demonstrates the primary line and cell magics (first alias for each)." + ] + }, + { + "cell_type": "markdown", + "id": "3f73875a", + "metadata": {}, + "source": [ + "## Basic Java\n", + "Run a simple Java expression to verify the kernel is active." + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "0b14ba6c", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Hello from IJava quick demo\n" + ] + } + ], + "source": [ + "System.out.println(\"Hello from IJava quick demo\");" + ] + }, + { + "cell_type": "markdown", + "id": "b7438b3f", + "metadata": {}, + "source": [ + "## List magics\n", + "Show registered line and cell magics." + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "aa244659", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "registered line magics: \n", + "\t- printerPrefix\n", + "\t- jars\n", + "\t- read\n", + "\t- listMagic, list\n", + "\t- listLineMagic\n", + "\t- listCellMagic\n", + "\t- maven, addMavenDependencies, addMavenDependency\n", + "\t- printWithName\n", + "\t- commonshellcmd\n", + "\t- pom, loadFromPOM\n", + "\t- cmd\n", + "\t- addMavenRepo, mavenRepo\n", + "\t- write\n", + "\t- load\n", + "\t- classpath\n", + "registered cell magics: \n", + "\t- javasrcInterfaceByName\n", + "\t- myshell\n", + "\t- write\n", + "\t- commonshell\n", + "\t- plantUMLFile\n", + "\t- compile\n", + "\t- javasrcMethodByName\n", + "\t- shell\n", + "\t- mycompile\n", + "\t- javasrcClassByName\n", + "\t- pom, loadFromPOM\n", + "\t- timeIt, timeit, time\n", + "\t- plantUML\n", + "\t- javasrcMethodByAnnotationName\n" + ] + } + ], + "source": [ + "%listMagic" + ] + }, + { + "cell_type": "markdown", + "id": "a236a4b1", + "metadata": {}, + "source": [ + "## Classpath & dependencies\n", + "Add Maven artifacts and jars to the runtime classpath." + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "a710005a", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Ijava Demo Using Maven/jars\n" + ] + } + ], + "source": [ + "%maven org.apache.commons:commons-text:1.10.0\n", + "%jars org.apache.commons:commons-lang3:3.12.0\n", + "import org.apache.commons.text.WordUtils;\n", + "System.out.println(WordUtils.capitalizeFully(\"iJava demo using maven/jars\"));" + ] + }, + { + "cell_type": "markdown", + "id": "5265795a", + "metadata": {}, + "source": [ + "## Compiler — `%%compile` (annotation-processor aware)\n", + "Use `%%compile` to compile sources with `javac` and run annotation processors (e.g., Lombok)." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "b9e50494", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%maven org.projectlombok:lombok:1.18.42" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "id": "4346a577", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "17:03:15.741 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Compiling com.example.Greeter with debug=false and nowarn=false\n", + "17:03:15.742 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Source file prepared at: /var/home/bruno/.jupyter/java-workspace/src/main/java/com/example/Greeter.java\n", + "17:03:15.925 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Added to classpath: /var/home/bruno/.jupyter/java-workspace/target/classes\n", + "17:03:15.926 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Successfully compiled com.example.Greeter and added to classpath\n" + ] + } + ], + "source": [ + "%%compile com.example.Greeter -v\n", + "public class Greeter {\n", + " private final String name;\n", + " public Greeter(String name) { this.name = name; }\n", + " public String greet() { return \"Hello \" + name; }\n", + "}" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "id": "1405dbb2", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Hello World\n" + ] + } + ], + "source": [ + "import com.example.Greeter;\n", + "Greeter g = new Greeter(\"World\");\n", + "System.out.println(g.greet());" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "id": "15e2dbac", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "17:03:16.098 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Compiling com.example.lombok.LombokExample with debug=false and nowarn=false\n", + "17:03:16.099 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Source file prepared at: /var/home/bruno/.jupyter/java-workspace/src/main/java/com/example/lombok/LombokExample.java\n", + "17:03:16.301 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Added to classpath: /var/home/bruno/.jupyter/java-workspace/target/classes\n", + "17:03:16.302 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Successfully compiled com.example.lombok.LombokExample and added to classpath\n" + ] + } + ], + "source": [ + "%%compile com.example.lombok.LombokExample -v\n", + "import lombok.Data;\n", + "import lombok.AllArgsConstructor;\n", + "public class LombokExample {\n", + " @Data\n", + " @AllArgsConstructor\n", + " public static class Person {\n", + " private final String name;\n", + " private int age;\n", + " }\n", + " public static String test() {\n", + " Person p = new Person(\"Alice\", 30);\n", + " return p.getName() + \":\" + p.getAge();\n", + " }\n", + "}" + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "id": "787aeffd", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Alice:30\n" + ] + } + ], + "source": [ + "import com.example.lombok.LombokExample;\n", + "System.out.println(LombokExample.test());" + ] + }, + { + "cell_type": "markdown", + "id": "66bcdd2c", + "metadata": {}, + "source": [ + "## File IO magics\n", + "Write and read a small file using `%write` and `%read`." + ] + }, + { + "cell_type": "code", + "execution_count": 24, + "id": "cb698277", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Write to \u001b[36m/tmp/example.txt\u001b[0m success.\n" + ] + } + ], + "source": [ + "%%write /tmp/example.txt\n", + "Hello from IJava file write" + ] + }, + { + "cell_type": "code", + "execution_count": 25, + "id": "494de548", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%read /tmp/example.txt" + ] + }, + { + "cell_type": "markdown", + "id": "16393c6b", + "metadata": {}, + "source": [ + "## Shell magics\n", + "Run shell commands with `%%shell` or single-line `%cmd`." + ] + }, + { + "cell_type": "code", + "execution_count": 26, + "id": "ad449c8e", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Linux pc-bruno 6.17.12-300.fc43.x86_64 #1 SMP PREEMPT_DYNAMIC Sat Dec 13 05:06:24 UTC 2025 x86_64 x86_64 x86_64 GNU/Linux\n", + "bash\n", + "/var/home/bruno/Documents/GitHub/Jupyter-Kernels/IJava/docs/notebooks\n" + ] + } + ], + "source": [ + "%%shell\n", + "uname -a\n", + "echo $SHELL\n", + "pwd" + ] + }, + { + "cell_type": "code", + "execution_count": 19, + "id": "4dc8c214", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Single-line cmd via %cmd\n" + ] + } + ], + "source": [ + "%cmd echo Single-line cmd via %cmd" + ] + }, + { + "cell_type": "markdown", + "id": "f48aec1a", + "metadata": {}, + "source": [ + "## Utilities\n", + "Demonstrate utility line magics: `%listLineMagic`, `%listCellMagic`, `%printerPrefix`, `%printWithName`, `%addMavenRepo`, `%pom`, `%load` (loads file into cell)." + ] + }, + { + "cell_type": "code", + "execution_count": 20, + "id": "866de2ae", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "registered line magics: \n", + "\t- printerPrefix\n", + "\t- jars\n", + "\t- read\n", + "\t- listMagic, list\n", + "\t- listLineMagic\n", + "\t- listCellMagic\n", + "\t- maven, addMavenDependencies, addMavenDependency\n", + "\t- printWithName\n", + "\t- commonshellcmd\n", + "\t- pom, loadFromPOM\n", + "\t- cmd\n", + "\t- addMavenRepo, mavenRepo\n", + "\t- write\n", + "\t- load\n", + "\t- classpath\n" + ] + } + ], + "source": [ + "%listLineMagic" + ] + }, + { + "cell_type": "code", + "execution_count": 21, + "id": "d01ffcc3", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "registered cell magics: \n", + "\t- javasrcInterfaceByName\n", + "\t- myshell\n", + "\t- write\n", + "\t- commonshell\n", + "\t- plantUMLFile\n", + "\t- compile\n", + "\t- javasrcMethodByName\n", + "\t- shell\n", + "\t- mycompile\n", + "\t- javasrcClassByName\n", + "\t- pom, loadFromPOM\n", + "\t- timeIt, timeit, time\n", + "\t- plantUML\n", + "\t- javasrcMethodByAnnotationName\n" + ] + } + ], + "source": [ + "%listCellMagic" + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "id": "31360433", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Change printer prefix from \"\" to \"MyDemoPrefix\"\n", + "run %printWithName to switch\n" + ] + } + ], + "source": [ + "%printerPrefix MyDemoPrefix\n", + "%printWithName -h" + ] + }, + { + "cell_type": "code", + "execution_count": 28, + "id": "06cc1e0d", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "//%addMavenRepo https://repo1.maven.org/maven2/\n", + "//%pom" + ] + }, + { + "cell_type": "markdown", + "id": "06e82759", + "metadata": {}, + "source": [ + "## PlantUML and timing\n", + "Render PlantUML and measure execution with `%%plantUML` and `%%timeit`." + ] + }, + { + "cell_type": "code", + "execution_count": 29, + "id": "60713d12", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "image/svg+xml": [ + "AliceAliceBobBobHiHello" + ], + "text/plain": [ + "AliceAliceBobBobHiHello" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%plantUML\n", + "@startuml\n", + "Alice -> Bob: Hi\n", + "Bob -> Alice: Hello\n", + "@enduml" + ] + }, + { + "cell_type": "code", + "execution_count": 30, + "id": "d63954b1", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "epoch 0: LongSummaryStatistics{count=5, sum=105, min=21, average=21,000000, max=21}\n", + "epoch 1: LongSummaryStatistics{count=5, sum=80, min=16, average=16,000000, max=16}\n", + "epoch 2: LongSummaryStatistics{count=5, sum=80, min=16, average=16,000000, max=16}\n", + "total: LongSummaryStatistics{count=15, sum=265, min=16, average=17,666667, max=21}\n" + ] + } + ], + "source": [ + "%%timeit\n", + "int s = 0;\n", + "for (int i = 0; i < 10000; i++) s += i;\n", + "s" + ] + }, + { + "cell_type": "markdown", + "id": "3b9432ef", + "metadata": {}, + "source": [ + "---\n", + "**Notes**: This notebook demonstrates the primary magics (first alias only). `%%compile` is used for all compilation examples to ensure annotation-processor support (Lombok)." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Java", + "language": "java", + "name": "java" + }, + "language_info": { + "codemirror_mode": "java", + "file_extension": ".jshell", + "mimetype": "text/x-java-source", + "name": "Java", + "pygments_lexer": "java", + "version": "25.0.1+8-LTS" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/src/main/resources/install.py b/src/main/resources/install.py index 897bf13..a29c835 100644 --- a/src/main/resources/install.py +++ b/src/main/resources/install.py @@ -183,11 +183,31 @@ def __call__(self, parser, namespace, value, option_string=None): # in the installed kernel.json from the local template. with open(local_kernel_json_path, 'r') as template_kernel_json_file: template_kernel_json_contents = template_kernel_json_file.read() + # Load the template JSON and programmatically update fields so we can + # point argv to the actual jar bundled in the `java/` subdirectory. kernel_json_contents = template_kernel_json_contents.replace( '@KERNEL_INSTALL_DIRECTORY@', install_dest_json_fragment ) kernel_json_json_contents = json.loads(kernel_json_contents) + + # If the distribution contains a jar in the installed 'java' folder, + # set argv[2] to that jar path so the kernelspec points at the real file. + try: + java_dir = os.path.join(install_dest, 'java') + if os.path.isdir(java_dir): + # prefer any jar (first alphabetical) - this will be the renamed shadow jar + jars = sorted([f for f in os.listdir(java_dir) if f.endswith('.jar')]) + if jars: + jar_path = os.path.join(install_dest, 'java', jars[-1]) + argv = kernel_json_json_contents.get('argv') + if isinstance(argv, list) and len(argv) > 2: + argv[2] = jar_path + kernel_json_json_contents['argv'] = argv + except Exception: + # best-effort: do not fail install if we cannot locate the jar + pass + kernel_env = kernel_json_json_contents.setdefault('env', {}) for k, v in args.env.items(): kernel_env[k] = v From 2176eda1637f6fa7534df25d1d4eed5365b014e7 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Wed, 14 Jan 2026 17:37:30 +0100 Subject: [PATCH 02/49] chore(docs): ignore generated notebook HTML outputs --- .gitignore | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/.gitignore b/.gitignore index 0779f7f..c80cd6a 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,17 @@ build/ out/.vscode .idea/ + +# Ignore generated notebook artifacts +docs/notebooks/example.txt +docs/notebooks/ijava_sample_notebook.html +docs/notebooks/generated_html/ + +# Installer/script outputs +install.sh + +# Generated java resources +src/main/resources/java/ + +# Tests artifacts +tests/ From bf7ca34a14040c7d820275f8ecdd87725f9e8848 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Wed, 14 Jan 2026 17:44:01 +0100 Subject: [PATCH 03/49] docs(notebook): add inline class example and explain when %%compile is needed --- docs/notebooks/ijava_sample_notebook.ipynb | 95 +++++++++++++++------- 1 file changed, 64 insertions(+), 31 deletions(-) diff --git a/docs/notebooks/ijava_sample_notebook.ipynb b/docs/notebooks/ijava_sample_notebook.ipynb index 0029aa8..3e416ec 100644 --- a/docs/notebooks/ijava_sample_notebook.ipynb +++ b/docs/notebooks/ijava_sample_notebook.ipynb @@ -21,7 +21,7 @@ }, { "cell_type": "code", - "execution_count": 8, + "execution_count": 69, "id": "0b14ba6c", "metadata": { "vscode": { @@ -41,6 +41,36 @@ "System.out.println(\"Hello from IJava quick demo\");" ] }, + { + "cell_type": "code", + "execution_count": 70, + "id": "0463f36e", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Hello Cell\n" + ] + } + ], + "source": [ + "// Inline class defined directly in a cell\n", + "class InlineGreeter {\n", + " String name;\n", + " InlineGreeter(String name) { this.name = name; }\n", + " String greet() { return \"Hello \" + name; }\n", + "}\n", + "\n", + "InlineGreeter ig = new InlineGreeter(\"Cell\");\n", + "System.out.println(ig.greet());" + ] + }, { "cell_type": "markdown", "id": "b7438b3f", @@ -52,7 +82,7 @@ }, { "cell_type": "code", - "execution_count": 9, + "execution_count": 71, "id": "aa244659", "metadata": { "vscode": { @@ -113,7 +143,7 @@ }, { "cell_type": "code", - "execution_count": 10, + "execution_count": 72, "id": "a710005a", "metadata": { "vscode": { @@ -142,12 +172,15 @@ "metadata": {}, "source": [ "## Compiler — `%%compile` (annotation-processor aware)\n", - "Use `%%compile` to compile sources with `javac` and run annotation processors (e.g., Lombok)." + "Use `%%compile` to compile sources with `javac` and run annotation processors (e.g., Lombok).\n", + "\n", + "Note: Small classes and quick snippets can often be defined directly inside a code cell (JShell-style) without using `%%compile` — these are convenient for fast experimentation and short-lived definitions (see the previous cell).\n", + "However, `%%compile` is required when you need annotation-processing (for example Lombok), when compiling multi-file packages, or when you want to produce class files that persist on the kernel classpath for later cells." ] }, { "cell_type": "code", - "execution_count": 11, + "execution_count": 73, "id": "b9e50494", "metadata": { "vscode": { @@ -161,7 +194,7 @@ }, { "cell_type": "code", - "execution_count": 12, + "execution_count": 74, "id": "4346a577", "metadata": { "vscode": { @@ -173,10 +206,10 @@ "name": "stdout", "output_type": "stream", "text": [ - "17:03:15.741 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Compiling com.example.Greeter with debug=false and nowarn=false\n", - "17:03:15.742 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Source file prepared at: /var/home/bruno/.jupyter/java-workspace/src/main/java/com/example/Greeter.java\n", - "17:03:15.925 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Added to classpath: /var/home/bruno/.jupyter/java-workspace/target/classes\n", - "17:03:15.926 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Successfully compiled com.example.Greeter and added to classpath\n" + "17:43:07.498 [IJava-executor-6] INFO i.g.s.i.magics.JavaCompilerMagics -- Compiling com.example.Greeter with debug=false and nowarn=false\n", + "17:43:07.499 [IJava-executor-6] INFO i.g.s.i.magics.JavaCompilerMagics -- Source file prepared at: /var/home/bruno/.jupyter/java-workspace/src/main/java/com/example/Greeter.java\n", + "17:43:07.615 [IJava-executor-6] INFO i.g.s.i.magics.JavaCompilerMagics -- Added to classpath: /var/home/bruno/.jupyter/java-workspace/target/classes\n", + "17:43:07.615 [IJava-executor-6] INFO i.g.s.i.magics.JavaCompilerMagics -- Successfully compiled com.example.Greeter and added to classpath\n" ] } ], @@ -191,7 +224,7 @@ }, { "cell_type": "code", - "execution_count": 13, + "execution_count": 75, "id": "1405dbb2", "metadata": { "vscode": { @@ -215,7 +248,7 @@ }, { "cell_type": "code", - "execution_count": 14, + "execution_count": 76, "id": "15e2dbac", "metadata": { "vscode": { @@ -227,10 +260,10 @@ "name": "stdout", "output_type": "stream", "text": [ - "17:03:16.098 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Compiling com.example.lombok.LombokExample with debug=false and nowarn=false\n", - "17:03:16.099 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Source file prepared at: /var/home/bruno/.jupyter/java-workspace/src/main/java/com/example/lombok/LombokExample.java\n", - "17:03:16.301 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Added to classpath: /var/home/bruno/.jupyter/java-workspace/target/classes\n", - "17:03:16.302 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Successfully compiled com.example.lombok.LombokExample and added to classpath\n" + "17:43:07.789 [IJava-executor-6] INFO i.g.s.i.magics.JavaCompilerMagics -- Compiling com.example.lombok.LombokExample with debug=false and nowarn=false\n", + "17:43:07.790 [IJava-executor-6] INFO i.g.s.i.magics.JavaCompilerMagics -- Source file prepared at: /var/home/bruno/.jupyter/java-workspace/src/main/java/com/example/lombok/LombokExample.java\n", + "17:43:07.931 [IJava-executor-6] INFO i.g.s.i.magics.JavaCompilerMagics -- Added to classpath: /var/home/bruno/.jupyter/java-workspace/target/classes\n", + "17:43:07.931 [IJava-executor-6] INFO i.g.s.i.magics.JavaCompilerMagics -- Successfully compiled com.example.lombok.LombokExample and added to classpath\n" ] } ], @@ -254,7 +287,7 @@ }, { "cell_type": "code", - "execution_count": 15, + "execution_count": 77, "id": "787aeffd", "metadata": { "vscode": { @@ -286,7 +319,7 @@ }, { "cell_type": "code", - "execution_count": 24, + "execution_count": 78, "id": "cb698277", "metadata": { "vscode": { @@ -309,7 +342,7 @@ }, { "cell_type": "code", - "execution_count": 25, + "execution_count": 79, "id": "494de548", "metadata": { "vscode": { @@ -332,7 +365,7 @@ }, { "cell_type": "code", - "execution_count": 26, + "execution_count": 80, "id": "ad449c8e", "metadata": { "vscode": { @@ -359,7 +392,7 @@ }, { "cell_type": "code", - "execution_count": 19, + "execution_count": 81, "id": "4dc8c214", "metadata": { "vscode": { @@ -390,7 +423,7 @@ }, { "cell_type": "code", - "execution_count": 20, + "execution_count": 82, "id": "866de2ae", "metadata": { "vscode": { @@ -427,7 +460,7 @@ }, { "cell_type": "code", - "execution_count": 21, + "execution_count": 83, "id": "d01ffcc3", "metadata": { "vscode": { @@ -463,7 +496,7 @@ }, { "cell_type": "code", - "execution_count": 22, + "execution_count": 84, "id": "31360433", "metadata": { "vscode": { @@ -475,7 +508,7 @@ "name": "stdout", "output_type": "stream", "text": [ - "Change printer prefix from \"\" to \"MyDemoPrefix\"\n", + "Change printer prefix from \"MyDemoPrefix\" to \"MyDemoPrefix\"\n", "run %printWithName to switch\n" ] } @@ -487,7 +520,7 @@ }, { "cell_type": "code", - "execution_count": 28, + "execution_count": 85, "id": "06cc1e0d", "metadata": { "vscode": { @@ -511,7 +544,7 @@ }, { "cell_type": "code", - "execution_count": 29, + "execution_count": 86, "id": "60713d12", "metadata": { "vscode": { @@ -542,7 +575,7 @@ }, { "cell_type": "code", - "execution_count": 30, + "execution_count": 87, "id": "d63954b1", "metadata": { "vscode": { @@ -554,10 +587,10 @@ "name": "stdout", "output_type": "stream", "text": [ - "epoch 0: LongSummaryStatistics{count=5, sum=105, min=21, average=21,000000, max=21}\n", + "epoch 0: LongSummaryStatistics{count=5, sum=110, min=22, average=22,000000, max=22}\n", "epoch 1: LongSummaryStatistics{count=5, sum=80, min=16, average=16,000000, max=16}\n", - "epoch 2: LongSummaryStatistics{count=5, sum=80, min=16, average=16,000000, max=16}\n", - "total: LongSummaryStatistics{count=15, sum=265, min=16, average=17,666667, max=21}\n" + "epoch 2: LongSummaryStatistics{count=5, sum=85, min=17, average=17,000000, max=17}\n", + "total: LongSummaryStatistics{count=15, sum=275, min=16, average=18,333333, max=22}\n" ] } ], From bc1fce311b5faec6944f096a9fdca7d43b8ff9fb Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Wed, 14 Jan 2026 18:22:02 +0100 Subject: [PATCH 04/49] feat(magics): add DBMS magics (rdbmsSchema, sqlAsTable) --- .../ijava/magics/JavaDBMSMagics.java | 128 ++++++++++++++++++ 1 file changed, 128 insertions(+) diff --git a/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java index ebf311b..6059297 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java @@ -1,9 +1,14 @@ package io.github.spencerpark.ijava.magics; +import io.github.spencerpark.jupyter.kernel.magic.registry.CellMagic; + +import java.sql.*; import java.util.Map; import java.util.TreeMap; import java.util.stream.Collectors; +import static io.github.spencerpark.ijava.runtime.Display.display; + public class JavaDBMSMagics { private static class Field { @@ -104,4 +109,127 @@ public String toString() { } } + /** + * Cell magic to print a schema overview for a given schema name. + * Usage: applyCellMagic("rdbmsSchema", List.of("schema_name"), "%") + */ + @CellMagic("rdbmsSchema") + public void rdbmsSchema(java.util.List args, String body) { + String schema = args.isEmpty() ? null : args.get(0); + + try (Connection conn = obtainConnection()) { + if (conn == null) { + System.out.println("No JDBC connection available. Set system properties 'jdbc.url' (and optionally 'jdbc.user'/'jdbc.password'), or provide a Connection in the kernel environment."); + return; + } + + DatabaseMetaData md = conn.getMetaData(); + ResultSet tables = md.getTables(null, schema, "%", new String[]{"TABLE"}); + StringBuilder sb = new StringBuilder(); + while (tables.next()) { + String tableName = tables.getString("TABLE_NAME"); + sb.append("Table: ").append(tableName).append("\n"); + ResultSet cols = md.getColumns(null, schema, tableName, "%"); + while (cols.next()) { + String colName = cols.getString("COLUMN_NAME"); + String type = cols.getString("TYPE_NAME"); + String size = cols.getString("COLUMN_SIZE"); + String nullable = cols.getInt("NULLABLE") == DatabaseMetaData.columnNullable ? "YES" : "NO"; + sb.append(String.format(" %s %s(%s) nullable=%s\n", colName, type, size, nullable)); + } + sb.append("\n"); + } + display(sb.toString(), "text/plain"); + } catch (SQLException e) { + throw new RuntimeException(e); + } + } + + /** + * Cell magic to execute a SQL query and render results as an HTML table. + * Usage: applyCellMagic("sqlAsTable", List.of(), "SELECT ...") + */ + @CellMagic("sqlAsTable") + public void sqlAsTable(java.util.List args, String body) { + String sql = body == null ? "" : body.trim(); + if (sql.isEmpty()) return; + + try (Connection conn = obtainConnection()) { + if (conn == null) { + System.out.println("No JDBC connection available. Set system properties 'jdbc.url' (and optionally 'jdbc.user'/'jdbc.password'), or provide a Connection in the kernel environment."); + return; + } + + try (Statement st = conn.createStatement(); ResultSet rs = st.executeQuery(sql)) { + ResultSetMetaData md = rs.getMetaData(); + int cols = md.getColumnCount(); + StringBuilder html = new StringBuilder(); + html.append("\n"); + for (int i = 1; i <= cols; i++) html.append(""); + html.append("\n"); + while (rs.next()) { + html.append(""); + for (int i = 1; i <= cols; i++) { + Object v = rs.getObject(i); + html.append(""); + } + html.append("\n"); + } + html.append("
").append(md.getColumnLabel(i)).append("
").append(v == null ? "" : escapeHtml(v.toString())).append("
"); + display(html.toString(), "text/html"); + } + } catch (SQLException e) { + throw new RuntimeException(e); + } + } + + private static String escapeHtml(String s) { + return s.replace("&", "&").replace("<", "<").replace(">", ">").replace("\"", """).replace("'", "'"); + } + + /** + * Attempt to obtain a JDBC Connection from several strategies: + * 1) System properties `jdbc.url` (+ user/password) + * 2) If a `DatabaseManager` class with `getConnection()` exists in kernel scope, attempt to call it via reflection. + */ + private Connection obtainConnection() throws SQLException { + String url = System.getProperty("jdbc.url"); + if (url != null && !url.isBlank()) { + String user = System.getProperty("jdbc.user"); + String pass = System.getProperty("jdbc.password"); + if (user != null) return DriverManager.getConnection(url, user, pass == null ? "" : pass); + return DriverManager.getConnection(url); + } + + // Try reflection for DatabaseManager.getConnection() + try { + Class dm = Class.forName("DatabaseManager"); + try { + java.lang.reflect.Method m = dm.getMethod("getConnection"); + Object conn = m.invoke(null); + if (conn instanceof Connection) return (Connection) conn; + } catch (NoSuchMethodException ignored) { + } + try { + java.lang.reflect.Method m2 = dm.getMethod("getEntityManagerFactory"); + Object emf = m2.invoke(null); + if (emf != null) { + // try to obtain a JDBC connection from the EMF + try { + java.lang.reflect.Method createEM = emf.getClass().getMethod("createEntityManager"); + Object em = createEM.invoke(emf); + java.lang.reflect.Method getConn = em.getClass().getMethod("unwrap", Class.class); + Object conn = getConn.invoke(em, java.sql.Connection.class); + if (conn instanceof Connection) return (Connection) conn; + } catch (NoSuchMethodException ignored2) { + } + } + } catch (NoSuchMethodException ignored) { + } + } catch (ClassNotFoundException | ReflectiveOperationException ignored) { + } + + return null; + } + } From 33381d957e8f2291238163e5ed124a688ee4fa60 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Wed, 14 Jan 2026 18:23:21 +0100 Subject: [PATCH 05/49] feat(magics): render RDBMS schema as PlantUML SVG in rdbmsSchema --- .../ijava/magics/JavaDBMSMagics.java | 103 +++++++++++++++--- 1 file changed, 88 insertions(+), 15 deletions(-) diff --git a/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java index 6059297..4a3cf31 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java @@ -2,6 +2,15 @@ import io.github.spencerpark.jupyter.kernel.magic.registry.CellMagic; +import net.sourceforge.plantuml.FileFormat; +import net.sourceforge.plantuml.FileFormatOption; +import net.sourceforge.plantuml.SourceStringReader; +import net.sourceforge.plantuml.core.DiagramDescription; + +import javax.imageio.ImageIO; +import java.io.ByteArrayInputStream; +import java.io.ByteArrayOutputStream; +import java.nio.charset.Charset; import java.sql.*; import java.util.Map; import java.util.TreeMap; @@ -124,23 +133,87 @@ public void rdbmsSchema(java.util.List args, String body) { } DatabaseMetaData md = conn.getMetaData(); - ResultSet tables = md.getTables(null, schema, "%", new String[]{"TABLE"}); - StringBuilder sb = new StringBuilder(); - while (tables.next()) { - String tableName = tables.getString("TABLE_NAME"); - sb.append("Table: ").append(tableName).append("\n"); - ResultSet cols = md.getColumns(null, schema, tableName, "%"); - while (cols.next()) { - String colName = cols.getString("COLUMN_NAME"); - String type = cols.getString("TYPE_NAME"); - String size = cols.getString("COLUMN_SIZE"); - String nullable = cols.getInt("NULLABLE") == DatabaseMetaData.columnNullable ? "YES" : "NO"; - sb.append(String.format(" %s %s(%s) nullable=%s\n", colName, type, size, nullable)); + + StringBuilder out = new StringBuilder(); + out.append("@startuml\n"); + out.append("left to right direction\n"); + out.append("skinparam roundcorner 5\n"); + out.append("skinparam shadowing true\n"); + out.append("skinparam handwritten false\n"); + out.append("skinparam class { BackgroundColor #EEEEEE ArrowColor #2688d4 BorderColor #2688d4 }\n"); + out.append("!define primary_key(x) <&key> x\n"); + out.append("!define foreign_key(x) <&key> x\n"); + out.append("!define column(x) <&media-record> x\n"); + out.append("!define table(x) entity x << (T, white) >>\n\n"); + + // iterate tables (if body contains specific table names, honor them) + java.util.List tableNames = new java.util.ArrayList<>(); + if (body != null && !body.trim().isEmpty()) { + for (String line : body.split("\n")) { + String l = line.trim(); + if (!l.isEmpty()) tableNames.add(l); } - sb.append("\n"); } - display(sb.toString(), "text/plain"); - } catch (SQLException e) { + + if (tableNames.isEmpty()) { + try (ResultSet tables = md.getTables(null, schema, "%", new String[]{"TABLE"})) { + while (tables.next()) tableNames.add(tables.getString("TABLE_NAME")); + } + } + + StringBuilder fkBuilder = new StringBuilder(); + + for (String tableName : tableNames) { + Table table = new Table(tableName); + + // columns + try (ResultSet columns = md.getColumns(null, schema, tableName, null)) { + while (columns.next()) { + String columnName = columns.getString("COLUMN_NAME"); + table.getFields().put(columnName, + Field.of(columnName, + columns.getString("COLUMN_SIZE"), + columns.getString("TYPE_NAME"), + columns.getString("IS_NULLABLE").equalsIgnoreCase("YES"), + "YES".equalsIgnoreCase(columns.getString("IS_AUTOINCREMENT")))); + } + } + + // primary keys + try (ResultSet primaryKeys = md.getPrimaryKeys(null, schema, tableName)) { + while (primaryKeys.next()) { + String pkCol = primaryKeys.getString("COLUMN_NAME"); + if (table.getFields().containsKey(pkCol)) table.getFields().get(pkCol).setRole(Field.Role.PK); + } + } + + // foreign keys + try (ResultSet foreignKeys = md.getImportedKeys(null, schema, tableName)) { + while (foreignKeys.next()) { + String pkTable = foreignKeys.getString("PKTABLE_NAME"); + String fkTable = foreignKeys.getString("FKTABLE_NAME"); + String pkCol = foreignKeys.getString("PKCOLUMN_NAME"); + String fkCol = foreignKeys.getString("FKCOLUMN_NAME"); + if (table.getFields().containsKey(fkCol)) table.getFields().get(fkCol).setRole(Field.Role.FK); + fkBuilder.append(String.format("%s::%s --> %s::%s\n", fkTable, fkCol, pkTable, pkCol)); + } + } + + out.append(table.toString()); + } + + out.append(fkBuilder.toString()); + out.append("@enduml"); + + // render via PlantUML as SVG + SourceStringReader reader = new SourceStringReader(out.toString()); + final ByteArrayOutputStream os = new ByteArrayOutputStream(); + DiagramDescription desc = reader.outputImage(os, new FileFormatOption(FileFormat.SVG)); + os.close(); + String svg = new String(os.toByteArray(), Charset.forName("UTF-8")); + display(svg, "image/svg+xml"); + + } catch (Exception e) { throw new RuntimeException(e); } } From d79f62d8b3ebfeb0297750a4baf9c4b48d3003a0 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Wed, 14 Jan 2026 19:30:30 +0100 Subject: [PATCH 06/49] fix(magics): attempt to load common JDBC drivers (jdbc.driver) before obtaining Connection --- .../ijava/magics/JavaDBMSMagics.java | 26 ++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java index 4a3cf31..eb9fa3d 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java @@ -268,6 +268,30 @@ private static String escapeHtml(String s) { private Connection obtainConnection() throws SQLException { String url = System.getProperty("jdbc.url"); if (url != null && !url.isBlank()) { + // Attempt to ensure a JDBC driver is loaded. Users can set `jdbc.driver` system property + // to force a specific driver class, or we try a few common drivers (H2, Postgres, MySQL, HSQLDB, SQLite). + String driverProp = System.getProperty("jdbc.driver"); + if (driverProp != null && !driverProp.isBlank()) { + try { + Class.forName(driverProp); + } catch (ClassNotFoundException ignored) { + } + } else { + String[] commonDrivers = new String[]{ + "org.h2.Driver", + "org.postgresql.Driver", + "com.mysql.cj.jdbc.Driver", + "org.hsqldb.jdbc.JDBCDriver", + "org.sqlite.JDBC" + }; + for (String d : commonDrivers) { + try { + Class.forName(d); + } catch (ClassNotFoundException ignored) { + } + } + } + String user = System.getProperty("jdbc.user"); String pass = System.getProperty("jdbc.password"); if (user != null) return DriverManager.getConnection(url, user, pass == null ? "" : pass); @@ -299,7 +323,7 @@ private Connection obtainConnection() throws SQLException { } } catch (NoSuchMethodException ignored) { } - } catch (ClassNotFoundException | ReflectiveOperationException ignored) { + } catch (ReflectiveOperationException ignored) { } return null; From 4b63f45dfeb315e6f2caff0a419c236da0f1e8a1 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Thu, 15 Jan 2026 11:47:21 +0100 Subject: [PATCH 07/49] feat: comprehensive magics UX improvements and audit - Add centralized utilities (OptionUtils, PathResolver, OutputUtils) - Implement javasrc* magics with full feature set: - javasrcMethodByName/ByAnnotationName with regex, selection, --help - javasrcClassByName, javasrcInterfaceByName with FQCN auto-resolve - javasrcList for source file summaries - Support --raw/--fenced output, --src path resolution - Enhance database magics (JavaDBMSMagics): - rdbmsSchema: SVG/PNG, showSource, include/exclude filters, scale, handwritten - sqlAsTable: HTML/CSV formats, max rows, showQuery, LIMIT/OFFSET normalization - Improve connection handling and JDBC driver registration - Improve PlantUML magics: - Support showSource/-s flag for debugging - Clean SVG output (strip XML declaration) - Better error context - Fix MagicsTool %load: - Workspace-relative path resolution - Quiet logging (no stdout noise) - Graceful not-found handling - Add sample Java files for demos (Greeter, OrderExample) - Add comprehensive magics audit document with improvement roadmap - Update example notebook with DBMS and javasrc examples BREAKING: --help short-circuits before any file I/O (prevents spurious builds) Closes phase 1 of magics refactor. See MAGICS_AUDIT_AND_IMPROVEMENT_PLAN.md for next steps. --- MAGICS_AUDIT_AND_IMPROVEMENT_PLAN.md | 445 +++++++++++ build.gradle | 4 +- docs/notebooks/ijava_sample_notebook.ipynb | 691 +++++++++++++++--- .../sample_java/com/example/Greeter.java | 13 + .../sample_java/com/example/OrderExample.java | 19 + .../ijava/magics/JavaDBMSMagics.java | 299 +++++++- .../spencerpark/ijava/magics/JavaMagics.java | 368 ++++++---- .../ijava/magics/JavaPlantUMLMagics.java | 43 +- .../spencerpark/ijava/magics/MagicsTool.java | 41 ++ .../spencerpark/ijava/magics/OptionUtils.java | 41 ++ .../spencerpark/ijava/magics/OutputUtils.java | 17 + .../ijava/magics/PathResolver.java | 41 ++ .../magics/DBMSMagicsIntegrationTest.java | 8 + 13 files changed, 1733 insertions(+), 297 deletions(-) create mode 100644 MAGICS_AUDIT_AND_IMPROVEMENT_PLAN.md create mode 100644 docs/notebooks/sample_java/com/example/Greeter.java create mode 100644 docs/notebooks/sample_java/com/example/OrderExample.java create mode 100644 src/main/java/io/github/spencerpark/ijava/magics/OptionUtils.java create mode 100644 src/main/java/io/github/spencerpark/ijava/magics/OutputUtils.java create mode 100644 src/main/java/io/github/spencerpark/ijava/magics/PathResolver.java create mode 100644 src/test/java/io/github/spencerpark/ijava/magics/DBMSMagicsIntegrationTest.java diff --git a/MAGICS_AUDIT_AND_IMPROVEMENT_PLAN.md b/MAGICS_AUDIT_AND_IMPROVEMENT_PLAN.md new file mode 100644 index 0000000..573aa43 --- /dev/null +++ b/MAGICS_AUDIT_AND_IMPROVEMENT_PLAN.md @@ -0,0 +1,445 @@ +# IJava Magics — Comprehensive Audit & UX Improvement Plan +**Date:** January 15, 2026 +**Status:** Post-initial-refactor assessment + +--- + +## Executive Summary + +This document provides a deep audit of all magics in `src/main/java/.../magics/` and proposes a comprehensive plan to achieve best-in-class UX for Java Jupyter kernel users. The audit covers: + +1. **Feature Coverage** — what's available and what's missing +2. **Consistency** — naming, argument parsing, error handling, output formatting +3. **Duplication** — overlapping responsibilities and refactoring opportunities +4. **Discoverability** — help text, documentation, examples +5. **Proposed Improvements** — actionable roadmap prioritized by user impact + +**Key Findings:** +- ✅ Strong foundation: source inspection (JavaMagics), compilation (JavaCompilerMagics), PlantUML rendering, database schema/query magics +- ⚠️ Inconsistent option parsing, help text, and error messages across magics +- ⚠️ Duplication between `ShellMagics`, `SingleShellMagics`, `MyShellMagics` +- ⚠️ Missing: unified `--help` across all magics, comprehensive output control (JSON/CSV/HTML), interactive prompts for common workflows +- ⚠️ Opportunity: centralize utilities further, add magic "profiles" or presets for common tasks + +--- + +## 1. Current State Inventory + +### 1.1 Line Magics (Single-line utilities) + +| Magic | Aliases | Purpose | Args/Options | Help Available? | Output Format | Notes | +|-------|---------|---------|--------------|-----------------|---------------|-------| +| `%classpath` | — | Add dirs/jars to classpath via glob | glob patterns | ❌ No | List of paths (return) | Works, no validation feedback | +| `%jars` | — | Add JAR files to classpath | glob patterns | ❌ No | List of JARs (return) | Works, no validation feedback | +| `%maven` | `addMavenDependency`, `addMavenDependencies` | Add Maven deps at runtime | `groupId:artifactId:version` | ❌ No | Logs to stdout | Powerful but no feedback on conflicts | +| `%pom`, `%loadFromPOM` | `loadFromPOM` | Load deps from pom.xml | path to pom.xml | ❌ No | Logs to stdout | Useful but no status summary | +| `%addMavenRepo`, `%mavenRepo` | `mavenRepo` | Add Maven repo URL | repo URL | ❌ No | Logs to stdout | Works, no validation | +| `%listMagic`, `%list` | `list` | List all magics | none | ❌ No | Stdout (formatted) | Good discoverability aid | +| `%listLineMagic` | — | List line magics | none | ❌ No | Stdout (formatted) | Good discoverability aid | +| `%listCellMagic` | — | List cell magics | none | ❌ No | Stdout (formatted) | Good discoverability aid | +| `%printWithName` | — | Toggle var name printing | `-h`/`--help` | ✅ Yes | Toggle message | Simple, works | +| `%printerPrefix` | — | Set printer prefix string | prefix string | ❌ No | Confirmation msg | Simple, works | +| `%cmd` | — | Run external shell command | command args | ❌ No | Stdout/stderr | Basic, no async support | +| `%load` | — | Load file contents into cell | file path | ✅ Partial (debug log) | String (return) | **Improved**: workspace-relative, quiet logger. Could add `--help`. | +| `%read` | — | Read file to string variable | file path | ✅ Yes (prints usage) | String (return) | Works; overlaps `%load` semantically | +| `%write` | — | Write variable to file | var_name, filename | ❌ No | Success message | Works, could validate write | +| `%commonshellcmd` | — | (Shell-related, exact role unclear from grep) | unknown | ❌ No | unknown | Needs investigation | + +### 1.2 Cell Magics (Multi-line/block operations) + +| Magic | Aliases | Purpose | Args/Options | Help Available? | Output Format | Notes | +|-------|---------|---------|--------------|-----------------|---------------|-------| +| `%%compile` | — | Compile Java class at runtime (JavaCompilerMagics) | `FQCN [-v] [-d] [-nowarn]` | ❌ No | Logs (stdout) + adds to classpath | **Core feature**: works well, verbose logging. Could add `--help`, structured output. | +| `%%mycompile` | — | Alternative compile magic (CompilerMagics) | `FQCN` | ❌ No | Logs (stdout) + adds to classpath | Overlaps `%%compile`. Decide: merge or deprecate one. | +| `%%write` | — | Write cell body to file | filename | ❌ No | Success message | Overlaps line `%write`. Consolidate? | +| `%%shell` | — | Run shell command (ShellMagics) | none | ❌ No | Stdout/stderr | Uses `zsh -c`. Basic; no option parsing. | +| `%%myshell` | — | Alternative shell (MyShellMagics, exact diff unclear) | unknown | ❌ No | Stdout/stderr | Duplication; audit reveals need to consolidate. | +| `%%commonshell` | — | Another shell variant | unknown | ❌ No | Stdout/stderr | **Duplication problem**: 3+ shell magics! | +| `%%timeIt`, `%%time`, `%%timeit` | `time`, `timeit` | Benchmark code execution | `epochs=N loops=M` | ✅ Yes (`-h`/`--help`) | LongSummaryStatistics (stdout) | Works well. Could add CSV/JSON output option. | +| `%%plantUML` | — | Render PlantUML diagram inline | `SVG`/`PNG`, `showSource`/`-s` | ❌ No | image/svg+xml or image/png | **Recently improved**: accepts `showSource` flag. Could add `--help`. | +| `%%plantUMLFile` | — | Render PlantUML from file(s) | `SVG`/`PNG` | ❌ No | image/svg+xml or image/png | Works; reads file list from body. Could add `--help`. | +| `%%javasrcMethodByAnnotationName` | — | Extract methods by annotation | `ClassName AnnotationName [index]` + options | ❌ No | Markdown (fenced) or plain | **New**: supports `--raw`/`--fenced`, `--src`. Needs `--help`. | +| `%%javasrcMethodByName` | — | Extract methods by name or regex | `ClassName methodName/regex [index]` + options | ✅ Yes (`--help`) | Markdown (fenced) or plain | **New**: full help text, regex, selection. Good reference for other magics. | +| `%%javasrcInterfaceByName` | — | Extract interface source | `FQCN` + options | ❌ No | Markdown (fenced) or plain | **New**: auto-resolve, supports `--src`. Needs `--help`. | +| `%%javasrcClassByName` | — | Extract class source | `FQCN` + options | ❌ No | Markdown (fenced) or plain | **New**: auto-resolve, supports `--src`. Needs `--help`. | +| `%%javasrcList` | — | List classes/methods in file (summary) | file path or FQCN | ❌ No | Markdown summary | **New**: useful discovery tool. Needs `--help`. | +| `%%rdbmsSchema` | — | Render database schema as PlantUML | schema_name + options | ❌ No | PlantUML (SVG/PNG) + optional source | **Improved**: supports `SVG`/`PNG`, `showSource`, `include=`, `exclude=`, `scale=`, `handwritten`. Needs `--help`. | +| `%%sqlAsTable` | — | Execute SQL and render as HTML table | SQL query | ❌ No | HTML table or CSV | **Improved**: supports `format=HTML/CSV`, `max=N`, `showQuery`. Needs `--help`. | +| `%%pom`, `%%loadFromPOM` | `loadFromPOM` | Load deps from pom.xml (cell variant) | path to pom.xml | ❌ No | Logs to stdout | Overlaps line magic. Consolidate? | + +--- + +## 2. Consistency Analysis + +### 2.1 Option Parsing + +**Current State:** +- ✅ **JavaMagics** (javasrc*): centralized via `OptionUtils.parseOptions()` — supports `--raw`, `--fenced`, `--src=`, `key=value`, `selectIndex=N` +- ✅ **JavaDBMSMagics** (rdbmsSchema, sqlAsTable): manual parsing but consistent within class (supports `showSource`, `SVG`/`PNG`, `format=`, `max=`, `include=`, `exclude=`, `scale=`) +- ✅ **JavaPlantUMLMagics** (plantUML, plantUMLFile): manual parsing, accepts `SVG`/`PNG`, `showSource`/`-s` +- ⚠️ **TimeItMagics**: manual key=value parsing (`epochs=`, `loops=`) +- ⚠️ **MagicsTool** (%load, %read, %write): minimal or no option parsing +- ❌ **ClasspathMagics, CompilerMagics, ShellMagics**: no option parsing; positional args only + +**Problems:** +- **Inconsistent flag syntax**: some use `--flag`, some `flag`, some `key=value`, some positional +- **No unified help pattern**: only `%%javasrcMethodByName` and `%%timeIt` have `--help` +- **Manual parsing duplication**: each magic reimplements similar logic + +**Recommendation:** +- **Extend `OptionUtils`** to support: + - Boolean flags (`--flag`, `-f`) + - Key=value pairs (`key=value`) + - Positional args (remaining after options) + - Built-in `--help` / `-h` detection and short-circuit +- **Refactor all magics** to use `OptionUtils.parseOptions()` with a schema/descriptor pattern +- **Standard help format**: Markdown block with `**Usage:**`, `**Options:**`, `**Examples:**` + +### 2.2 Error Handling & Messages + +**Current State:** +- ✅ **JavaMagics**: friendly error messages using `display(..., "text/markdown")` — e.g., "Class `X` not found in file `Y`." +- ✅ **JavaDBMSMagics**: `try-catch` with context, displays error messages inline +- ⚠️ **CompilerMagics, ClasspathMagics**: throws `RuntimeException` on error (not user-friendly) +- ⚠️ **ShellMagics**: logs error but may not surface to user cleanly +- ⚠️ **TimeItMagics**: prints to stdout/stderr; no structured error output + +**Problems:** +- **Inconsistent error presentation**: some throw exceptions, some print, some use Display API +- **No structured error format**: users can't parse errors programmatically (e.g., for automated notebooks) +- **Missing validation**: many magics don't validate args before attempting operations + +**Recommendation:** +- **Standardize error handling**: + - Use `display(errorMessage, "text/markdown")` for user-facing errors + - Log exceptions via `@Slf4j` logger for debugging (avoid noisy stdout) + - Optionally support `--verbose` flag to show stack traces +- **Add input validation** to all magics (check arg count, file existence, etc.) before execution +- **Structured error output option**: `--format=json` could emit `{"error": "message", "type": "ArgumentError"}` for automation + +### 2.3 Output Formatting + +**Current State:** +- ✅ **JavaMagics**: unified via `OutputUtils.formatAndDisplay()` — supports `--raw` (plain text) and `--fenced` (Markdown fenced code block) +- ✅ **JavaDBMSMagics**: `%%sqlAsTable` supports `format=HTML/CSV`; `%%rdbmsSchema` supports `SVG`/`PNG` +- ⚠️ **JavaPlantUMLMagics**: SVG/PNG but no JSON/text fallback +- ⚠️ **TimeItMagics**: only `LongSummaryStatistics.toString()` (not machine-readable) +- ⚠️ **ClasspathMagics, MagicsTool**: returns lists or prints to stdout — no format control + +**Problems:** +- **Inconsistent MIME types**: some use `text/markdown`, some `text/html`, some `text/plain` without user control +- **No machine-readable output**: hard to extract data from notebooks for automation (e.g., CI/CD pipelines) +- **Missing format options**: many magics don't support `--format=json/csv/html` despite outputting structured data + +**Recommendation:** +- **Extend `OutputUtils`** to support: + - `--format=raw|fenced|json|csv|html|svg|png` + - Auto-detect MIME type from format + - JSON output for structured data (e.g., `%%timeIt` → `{"epochs": [...], "total": {...}}`) +- **Apply uniformly** to all magics that output data (compilation results, query results, benchmark stats, etc.) +- **Document MIME types** in help text so users know what to expect + +### 2.4 Naming & Aliasing + +**Current State:** +- ✅ **Good aliases**: `%%timeIt` → `time`, `timeit`; `%listMagic` → `list`; `%maven` → `addMavenDependency`, `addMavenDependencies` +- ⚠️ **Inconsistent naming**: `%pom` vs `%loadFromPOM`, `%%compile` vs `%%mycompile`, `%%shell` vs `%%myshell` vs `%%commonshell` +- ⚠️ **Missing verb consistency**: some use `list` (line), some use `List` (cell), some omit verb (e.g., `%classpath` vs `%listClasspath`) + +**Problems:** +- **Overlapping magics confuse users**: `%%compile` vs `%%mycompile` — which should I use? +- **No naming convention**: verb-noun (e.g., `listMagics`) vs noun-only (e.g., `classpath`) vs prefix (e.g., `javasrc*`) + +**Recommendation:** +- **Establish naming convention**: + - **Discovery/Inspection**: `list*`, `show*`, `get*` (e.g., `%listMagics`, `%showClasspath`) + - **Modification**: `add*`, `set*`, `compile*` (e.g., `%addJars`, `%%compile`) + - **Extraction**: `extract*`, `javasrc*` (keep `javasrc*` as domain-specific prefix) + - **Rendering/Visualization**: `render*`, `draw*` (e.g., `%%renderPlantUML`, `%%drawSchema`) +- **Consolidate duplicates**: + - Merge `%%compile` and `%%mycompile` → keep `%%compile`, deprecate `%%mycompile` (or make it an alias) + - Merge shell magics (`%%shell`, `%%myshell`, `%%commonshell`) → keep `%%shell`, add options for shell type (`--shell=bash|zsh`) + - Merge `%pom` and `%loadFromPOM` → keep `%loadFromPOM`, make `%pom` an alias +- **Add semantic aliases**: e.g., `%jars` → `%addJars`, `%classpath` → `%addClasspath` (keep short names as primary, add verbose aliases) + +--- + +## 3. Duplication & Refactoring Opportunities + +### 3.1 Identified Duplications + +| Functionality | Implementations | Recommendation | +|---------------|-----------------|----------------| +| **Compilation** | `%%compile` (JavaCompilerMagics), `%%mycompile` (CompilerMagics) | **Consolidate**: Keep `%%compile` (more mature, verbose logging). Deprecate `%%mycompile`. Extract common logic to `CompilerUtils`. | +| **Shell Execution** | `%%shell` (ShellMagics), `%%myshell` (MyShellMagics), `%%commonshell`, `%cmd` (MagicsTool) | **Consolidate**: Keep `%%shell` (cell) and `%cmd` (line). Add `--shell=bash/zsh/sh` option. Remove `%%myshell`, `%%commonshell`. | +| **File I/O** | `%read`, `%load` (both read files), `%write` (line), `%%write` (cell) | **Rationalize**: `%load` for cells (load & edit), `%read` for inline use (assign to variable). Merge cell and line `%%write` → single `%%write` that detects context. | +| **POM Loading** | `%pom`/`%loadFromPOM` (line), `%%pom`/`%%loadFromPOM` (cell) | **Consolidate**: Line magic is sufficient. Deprecate cell variant (or make it call line magic). | +| **Option Parsing** | Manual parsing in JavaDBMSMagics, TimeItMagics, JavaPlantUMLMagics | **Centralize**: Migrate all to `OptionUtils` with schema-based approach. | +| **Path Resolution** | `PathResolver` (JavaMagics), manual resolution in MagicsTool, etc. | **Centralize**: Use `PathResolver` for all file-path resolution (relative to workspace, notebook dir, `--src` base). | +| **Output Formatting** | `OutputUtils` (JavaMagics), manual HTML in JavaDBMSMagics, manual SVG in JavaPlantUMLMagics | **Centralize**: Extend `OutputUtils` to handle HTML, CSV, JSON, SVG. All magics delegate to it. | + +### 3.2 Refactoring Roadmap + +**Phase 1: Centralize Core Utilities (Week 1)** +- [ ] **Extend `OptionUtils`**: add schema/descriptor support, built-in `--help` handling, flag parsing (`--flag`), key=value, positional +- [ ] **Extend `OutputUtils`**: add `format=json/csv/html/svg/png`, MIME type mapping, error formatting +- [ ] **Extend `PathResolver`**: add workspace-root detection, notebook-relative paths, `--base` option +- [ ] **Create `ValidationUtils`**: common arg validation (e.g., `requireNonEmpty`, `requireFileExists`, `requireInt`) + +**Phase 2: Migrate Existing Magics (Week 2-3)** +- [ ] **ClasspathMagics**: add `--help`, validate glob patterns, structured output +- [ ] **CompilerMagics**: consolidate with JavaCompilerMagics → single `%%compile`, add `--help`, JSON output option +- [ ] **ShellMagics**: consolidate 3 variants → single `%%shell`, add `--shell=bash/zsh`, `--timeout=Ns`, `--help` +- [ ] **TimeItMagics**: migrate to `OptionUtils`, add `--format=json` output, `--help` +- [ ] **MagicsTool**: migrate `%load`/`%read`/`%write` to `OptionUtils`, add `--help`, consolidate cell/line variants +- [ ] **JavaPlantUMLMagics**: migrate to `OptionUtils`, add `--help`, `--format=svg/png` +- [ ] **JavaDBMSMagics**: migrate to `OptionUtils`, add `--help` for both `%%rdbmsSchema` and `%%sqlAsTable` +- [ ] **JavaMagics**: add `--help` to remaining `javasrc*` magics (MethodByAnnotationName, InterfaceByName, ClassByName, List) + +**Phase 3: Add Missing Features (Week 4)** +- [ ] **Deprecation warnings**: emit deprecation warnings for `%%mycompile`, `%%myshell`, `%%commonshell`, duplicate `%pom` cell magic +- [ ] **Add `%showClasspath`**: list current classpath (for debugging) +- [ ] **Add `%showMavenRepos`**: list current Maven repos +- [ ] **Add `%%javasrcPackage`**: extract entire package source (all classes in package) +- [ ] **Add `%%generateJavadoc`**: generate Javadoc for a class and display inline +- [ ] **Add `--verbose`/`-v` global flag**: show detailed logs/stack traces when present +- [ ] **Add `--dry-run` option**: preview what magic will do without executing (for `%%compile`, `%%shell`, etc.) + +**Phase 4: Documentation & Examples (Week 5)** +- [ ] **Update `README.md`**: document all magics with usage examples +- [ ] **Create `docs/magics/`**: individual doc files for each magic family (classpath, compilation, javasrc, dbms, shell, etc.) +- [ ] **Update `ijava_sample_notebook.ipynb`**: add comprehensive examples for all magics with inline help demonstrations +- [ ] **Create `docs/magics/CHEAT_SHEET.md`**: quick-reference guide for common tasks + +--- + +## 4. Feature Coverage Gap Analysis + +### 4.1 Missing High-Value Features + +| Feature | Current State | Proposed Magic | Priority | Rationale | +|---------|---------------|----------------|----------|-----------| +| **Classpath introspection** | None | `%showClasspath`, `%listJars` | **High** | Users often need to debug classpath issues; currently blind. | +| **Dependency conflict resolution** | Logs only | `%resolveMavenConflicts --tree` | **High** | Maven dep conflicts are common pain point; show dep tree with conflicts highlighted. | +| **Source code navigation** | Javasrc magics (class/method level) | `%%javasrcPackage`, `%%javasrcImports` | **Medium** | Extract all classes in package, list imports for a class (useful for refactoring). | +| **Javadoc generation** | None | `%%generateJavadoc ` | **Medium** | Generate and display Javadoc inline (HTML or Markdown). | +| **Code formatting** | None | `%%formatJava` (Google Java Format), `%%formatCode` | **Medium** | Format cell body with standard Java formatter before compilation. | +| **Linting/Static Analysis** | None | `%%checkstyle`, `%%pmd`, `%%spotbugs` | **Low** | Run linters on cell body, display violations inline. | +| **REPL enhancements** | None | `%history`, `%recall `, `%vars` | **Medium** | Show eval history, recall previous cell, list variables in scope. | +| **Notebook metadata** | None | `%notebookInfo`, `%setMetadata key=value` | **Low** | Show/set notebook metadata (kernel version, IJava version, etc.). | +| **Interactive prompts** | None | `%prompt "Enter value:"` | **Low** | Prompt user for input in cell (useful for interactive demos). | +| **Plot integration** | None | `%%plot ` (delegate to existing viz libraries) | **Low** | Quick plotting for arrays/lists (delegate to existing Java viz libs like XChart). | +| **Export to script** | None | `%exportNotebook --format=java` | **Low** | Export notebook cells as standalone Java script. | +| **Profiling** | `%%timeIt` (basic) | `%%profile --flamegraph`, `%%memProfile` | **Medium** | Detailed profiling (CPU, memory) with visual reports. | +| **Test execution** | None | `%%test ` | **Medium** | Run JUnit tests inline, display results as HTML table. | +| **Docker integration** | None | `%%dockerRun ` | **Low** | Run command in Docker container, capture output. | + +### 4.2 Feature Prioritization + +**Tier 1 (Next Release): Core UX Improvements** +1. Consolidate duplicate magics (shell, compile, pom) +2. Add `--help` to all magics +3. Centralize option parsing and output formatting +4. Add `%showClasspath` and `%showMavenRepos` for debugging +5. Improve error messages across all magics + +**Tier 2 (Next+1): Enhanced Introspection & Automation** +6. Add `%resolveMavenConflicts --tree` +7. Add `%%javasrcPackage` and `%%javasrcImports` +8. Add `--format=json/csv` to all data-emitting magics +9. Add `%%generateJavadoc` +10. Add `%history` and `%recall` + +**Tier 3 (Future): Advanced Features** +11. Add `%%formatJava` (code formatting) +12. Add `%%profile` (detailed profiling) +13. Add `%%test` (JUnit integration) +14. Add linting magics (`%%checkstyle`, `%%pmd`) +15. Add `%exportNotebook --format=java` + +--- + +## 5. Discoverability & Help System + +### 5.1 Current Help Mechanisms + +| Mechanism | Coverage | Quality | Issues | +|-----------|----------|---------|--------| +| `%list`, `%listLineMagic`, `%listCellMagic` | ✅ All magics listed | ✅ Good | Doesn't show usage or description | +| Per-magic `--help` | ⚠️ Only `%%javasrcMethodByName`, `%%timeIt` | ✅ Good (Markdown formatted) | Inconsistent; most magics lack help | +| Inline error messages | ⚠️ Partial (JavaMagics) | ✅ Good (Markdown) | Not all magics have friendly errors | +| `README.md` documentation | ⚠️ Partial | ⚠️ Outdated | Doesn't cover new javasrc*, dbms magics | +| Example notebooks | ⚠️ `ijava_sample_notebook.ipynb` | ⚠️ Partial | Doesn't cover all magics comprehensively | + +### 5.2 Help System Improvements + +**Standard Help Format (Template):** +```markdown +**Usage:** `%%magicName [options] [optionalArg]` + +**Purpose:** [One-sentence description] + +**Options:** +- `--option1 `: [Description] +- `--flag`: [Description] +- `key=value`: [Description] + +**Examples:** +- `%%magicName arg1 arg2` — [What it does] +- `%%magicName --option1=value arg1` — [What it does] + +**See also:** [Related magics] +``` + +**Recommendations:** +- [ ] **Add `--help`/`-h` to ALL magics**: Use `OptionUtils` to detect and short-circuit +- [ ] **Consistent help format**: All help text follows template above +- [ ] **Interactive help**: `%help ` magic that displays help for any magic +- [ ] **Contextual help**: If user runs magic with invalid args, auto-display help (not just error) +- [ ] **Tooltips in notebook UI**: (Future) VS Code extension to show magic help on hover + +--- + +## 6. Proposed Action Plan + +### 6.1 Immediate Actions (Next Sprint) + +**Goal:** Stabilize core UX, eliminate duplication, achieve consistency + +1. **Consolidate Duplicate Magics** (2 days) + - [ ] Merge `%%mycompile` into `%%compile` (deprecate `%%mycompile`) + - [ ] Merge `%%myshell`, `%%commonshell` into `%%shell` (deprecate others) + - [ ] Merge cell/line `%pom` → keep line magic, deprecate cell + - [ ] Add deprecation warnings to removed magics + +2. **Centralize Utilities** (3 days) + - [ ] Extend `OptionUtils` with flag support, schema-based parsing, built-in `--help` detection + - [ ] Extend `OutputUtils` with JSON/CSV/HTML support, MIME type mapping + - [ ] Create `ValidationUtils` for common arg validation + - [ ] Document utility APIs in `docs/magics/UTILITIES.md` + +3. **Add `--help` to All Magics** (3 days) + - [ ] Add help text to: ClasspathMagics, CompilerMagics, ShellMagics, MagicsTool, JavaPlantUMLMagics, JavaDBMSMagics, remaining JavaMagics + - [ ] Use consistent Markdown template + - [ ] Test help display in notebook + +4. **Improve Error Handling** (2 days) + - [ ] Standardize error display: use `display(error, "text/markdown")` + - [ ] Add input validation to all magics (use `ValidationUtils`) + - [ ] Test error scenarios in notebook + +5. **Update Documentation** (2 days) + - [ ] Update `README.md` with complete magic listing and examples + - [ ] Update `ijava_sample_notebook.ipynb` with help demonstrations + - [ ] Create `docs/magics/QUICK_START.md` cheat sheet + +**Total: ~12 days** (2.5 weeks) + +### 6.2 Short-Term Goals (Next Release) + +6. **Add High-Value Missing Features** (1 week) + - [ ] `%showClasspath` + - [ ] `%showMavenRepos` + - [ ] `%resolveMavenConflicts --tree` + - [ ] `%%javasrcPackage` + - [ ] `%history`, `%recall` + +7. **Add Structured Output Options** (1 week) + - [ ] `--format=json` for: `%%timeIt`, `%%compile`, `%%sqlAsTable`, `%jars`, `%classpath` + - [ ] Document JSON schema for each output + +8. **Testing & Quality Assurance** (1 week) + - [ ] Create integration tests for all magics (run from notebook) + - [ ] Smoke-test all help text + - [ ] Verify all examples in docs work + +**Total: ~3 weeks** + +### 6.3 Mid-Term Goals (Next+1 Release) + +9. **Advanced Introspection** (2 weeks) + - [ ] `%%generateJavadoc` + - [ ] `%%javasrcImports` + - [ ] `%%profile --flamegraph` + +10. **Code Quality Integrations** (2 weeks) + - [ ] `%%formatJava` (Google Java Format) + - [ ] `%%checkstyle`, `%%pmd` (optional: requires deps) + +11. **Automation Enhancements** (1 week) + - [ ] `%exportNotebook --format=java` + - [ ] `--dry-run` flag for destructive operations + +**Total: ~5 weeks** + +### 6.4 Long-Term Vision (Future) + +- **Magic Profiles/Presets**: `%useProfile data-science` loads curated set of magics + deps (e.g., Apache Spark, Tablesaw) +- **Interactive Widgets**: `%prompt`, `%slider`, `%dropdown` for notebook interactivity +- **VS Code Extension**: Magic auto-complete, hover help, inline error squiggles +- **Community Magics Repository**: Plugin system for user-contributed magics +- **Cloud Integration**: `%%runOnCloud ` for remote execution + +--- + +## 7. Success Metrics + +### 7.1 Quantitative + +- **Help Coverage**: 100% of magics have `--help` text +- **Consistency Score**: 100% of magics use `OptionUtils`, `OutputUtils`, `ValidationUtils` +- **Duplication Reduction**: 0 overlapping magics (currently 3 shell variants, 2 compile variants) +- **Error Clarity**: 100% of magics display friendly error messages (not stack traces) +- **Documentation Coverage**: 100% of magics documented in `README.md` + example notebook + +### 7.2 Qualitative + +- **User Feedback**: Positive sentiment in GitHub issues/discussions (target: >80% positive) +- **Discoverability**: Users can find and use magics without reading external docs (measured via user studies or issues) +- **Consistency**: Users report that magics "feel" consistent (survey or qualitative feedback) + +--- + +## 8. Risks & Mitigation + +| Risk | Impact | Mitigation | +|------|--------|------------| +| **Breaking Changes**: Consolidating magics may break existing notebooks | High | Add deprecation warnings first; provide migration guide; keep old names as aliases for 1 release cycle. | +| **Scope Creep**: Too many new features delay core improvements | Medium | Prioritize Tier 1 (core UX) over Tier 2/3 (advanced features); release incrementally. | +| **Testing Burden**: More magics = more tests | Medium | Create reusable test harness (e.g., `MagicTestRunner` that exercises all magics with valid/invalid inputs). | +| **Community Resistance**: Users may prefer current magic names/behavior | Low | Gather feedback via GitHub issue/discussion before finalizing consolidation plan. | + +--- + +## 9. Conclusion & Recommendations + +**Current State:** +- IJava magics provide strong foundation for Java notebook workflows (compilation, source inspection, database visualization, PlantUML rendering) +- Recent improvements (JavaMagics refactor, JavaDBMSMagics enhancements) show clear path toward consistency + +**Key Problems:** +1. **Duplication**: 3 shell magics, 2 compile magics, overlapping file I/O +2. **Inconsistency**: Different option parsing, error handling, output formatting across magics +3. **Poor Discoverability**: Most magics lack `--help`; documentation incomplete + +**Recommended Path Forward:** +1. **Phase 1 (Immediate)**: Consolidate duplicates, centralize utilities, add `--help` to all magics +2. **Phase 2 (Short-term)**: Add high-value missing features (`%showClasspath`, `%resolveMavenConflicts`, `%%javasrcPackage`) +3. **Phase 3 (Mid-term)**: Add advanced features (profiling, Javadoc generation, code formatting) +4. **Phase 4 (Long-term)**: Explore magic profiles, VS Code extension, community plugins + +**Expected Outcome:** +- **Best-in-class Java Jupyter UX**: Consistent, discoverable, powerful magics that feel like a cohesive toolkit +- **Reduced maintenance burden**: Centralized utilities = less duplication, easier to add new features +- **Happy users**: Clear documentation, friendly error messages, predictable behavior + +**Next Step:** +- Review this plan with maintainers/contributors +- Create GitHub issues for each Phase 1 task +- Begin consolidation work (start with shell magics, then compile magics) + +--- + +**Document Version:** 1.0 +**Last Updated:** January 15, 2026 +**Author:** GitHub Copilot (audit commissioned by user `bruno`) diff --git a/build.gradle b/build.gradle index fd043b0..0178f9b 100644 --- a/build.gradle +++ b/build.gradle @@ -62,7 +62,9 @@ dependencies { implementation 'com.github.javaparser:javaparser-core:3.25.8' implementation 'com.github.javaparser:javaparser-symbol-solver-core:3.25.8' // PlantUML for diagrams - implementation 'net.sourceforge.plantuml:plantuml:1.2024.1' + //implementation 'net.sourceforge.plantuml:plantuml:1.2024.1' + implementation 'net.sourceforge.plantuml:plantuml:1.2026.0' + // ClassGraph for classpath scanning implementation 'io.github.classgraph:classgraph:4.8.168' // Lombok for annotations processing diff --git a/docs/notebooks/ijava_sample_notebook.ipynb b/docs/notebooks/ijava_sample_notebook.ipynb index 3e416ec..5e99533 100644 --- a/docs/notebooks/ijava_sample_notebook.ipynb +++ b/docs/notebooks/ijava_sample_notebook.ipynb @@ -1,27 +1,8 @@ { "cells": [ - { - "cell_type": "markdown", - "id": "61062e46", - "metadata": {}, - "source": [ - "# IJava — Quick reference and magics demo\n", - "\n", - "Concise walkthrough showing IJava features and magics. This notebook uses `%%compile` for compilation and demonstrates the primary line and cell magics (first alias for each)." - ] - }, - { - "cell_type": "markdown", - "id": "3f73875a", - "metadata": {}, - "source": [ - "## Basic Java\n", - "Run a simple Java expression to verify the kernel is active." - ] - }, { "cell_type": "code", - "execution_count": 69, + "execution_count": 1, "id": "0b14ba6c", "metadata": { "vscode": { @@ -43,7 +24,7 @@ }, { "cell_type": "code", - "execution_count": 70, + "execution_count": 2, "id": "0463f36e", "metadata": { "vscode": { @@ -82,7 +63,7 @@ }, { "cell_type": "code", - "execution_count": 71, + "execution_count": 3, "id": "aa244659", "metadata": { "vscode": { @@ -95,36 +76,39 @@ "output_type": "stream", "text": [ "registered line magics: \n", - "\t- printerPrefix\n", - "\t- jars\n", - "\t- read\n", + "\t- pom, loadFromPOM\n", "\t- listMagic, list\n", + "\t- read\n", "\t- listLineMagic\n", "\t- listCellMagic\n", "\t- maven, addMavenDependencies, addMavenDependency\n", + "\t- printerPrefix\n", + "\t- cmd\n", "\t- printWithName\n", + "\t- jars\n", + "\t- load\n", "\t- commonshellcmd\n", - "\t- pom, loadFromPOM\n", - "\t- cmd\n", - "\t- addMavenRepo, mavenRepo\n", "\t- write\n", - "\t- load\n", "\t- classpath\n", + "\t- addMavenRepo, mavenRepo\n", "registered cell magics: \n", - "\t- javasrcInterfaceByName\n", - "\t- myshell\n", + "\t- javasrcClassByName\n", "\t- write\n", - "\t- commonshell\n", "\t- plantUMLFile\n", "\t- compile\n", + "\t- rdbmsSchema\n", "\t- javasrcMethodByName\n", - "\t- shell\n", - "\t- mycompile\n", - "\t- javasrcClassByName\n", - "\t- pom, loadFromPOM\n", + "\t- javasrcMethodByAnnotationName\n", "\t- timeIt, timeit, time\n", + "\t- shell\n", + "\t- javasrcList\n", + "\t- myshell\n", + "\t- sqlAsTable\n", + "\t- javasrcInterfaceByName\n", "\t- plantUML\n", - "\t- javasrcMethodByAnnotationName\n" + "\t- mycompile\n", + "\t- commonshell\n", + "\t- pom, loadFromPOM\n" ] } ], @@ -143,7 +127,7 @@ }, { "cell_type": "code", - "execution_count": 72, + "execution_count": 4, "id": "a710005a", "metadata": { "vscode": { @@ -180,7 +164,7 @@ }, { "cell_type": "code", - "execution_count": 73, + "execution_count": 5, "id": "b9e50494", "metadata": { "vscode": { @@ -194,7 +178,7 @@ }, { "cell_type": "code", - "execution_count": 74, + "execution_count": 6, "id": "4346a577", "metadata": { "vscode": { @@ -206,10 +190,10 @@ "name": "stdout", "output_type": "stream", "text": [ - "17:43:07.498 [IJava-executor-6] INFO i.g.s.i.magics.JavaCompilerMagics -- Compiling com.example.Greeter with debug=false and nowarn=false\n", - "17:43:07.499 [IJava-executor-6] INFO i.g.s.i.magics.JavaCompilerMagics -- Source file prepared at: /var/home/bruno/.jupyter/java-workspace/src/main/java/com/example/Greeter.java\n", - "17:43:07.615 [IJava-executor-6] INFO i.g.s.i.magics.JavaCompilerMagics -- Added to classpath: /var/home/bruno/.jupyter/java-workspace/target/classes\n", - "17:43:07.615 [IJava-executor-6] INFO i.g.s.i.magics.JavaCompilerMagics -- Successfully compiled com.example.Greeter and added to classpath\n" + "11:34:39.526 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Compiling com.example.Greeter with debug=false and nowarn=false\n", + "11:34:39.533 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Source file prepared at: /var/home/bruno/.jupyter/java-workspace/src/main/java/com/example/Greeter.java\n", + "11:34:39.816 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Added to classpath: /var/home/bruno/.jupyter/java-workspace/target/classes\n", + "11:34:39.817 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Successfully compiled com.example.Greeter and added to classpath\n" ] } ], @@ -224,7 +208,7 @@ }, { "cell_type": "code", - "execution_count": 75, + "execution_count": 7, "id": "1405dbb2", "metadata": { "vscode": { @@ -248,7 +232,7 @@ }, { "cell_type": "code", - "execution_count": 76, + "execution_count": 8, "id": "15e2dbac", "metadata": { "vscode": { @@ -260,10 +244,10 @@ "name": "stdout", "output_type": "stream", "text": [ - "17:43:07.789 [IJava-executor-6] INFO i.g.s.i.magics.JavaCompilerMagics -- Compiling com.example.lombok.LombokExample with debug=false and nowarn=false\n", - "17:43:07.790 [IJava-executor-6] INFO i.g.s.i.magics.JavaCompilerMagics -- Source file prepared at: /var/home/bruno/.jupyter/java-workspace/src/main/java/com/example/lombok/LombokExample.java\n", - "17:43:07.931 [IJava-executor-6] INFO i.g.s.i.magics.JavaCompilerMagics -- Added to classpath: /var/home/bruno/.jupyter/java-workspace/target/classes\n", - "17:43:07.931 [IJava-executor-6] INFO i.g.s.i.magics.JavaCompilerMagics -- Successfully compiled com.example.lombok.LombokExample and added to classpath\n" + "11:34:40.029 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Compiling com.example.lombok.LombokExample with debug=false and nowarn=false\n", + "11:34:40.031 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Source file prepared at: /var/home/bruno/.jupyter/java-workspace/src/main/java/com/example/lombok/LombokExample.java\n", + "11:34:40.259 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Added to classpath: /var/home/bruno/.jupyter/java-workspace/target/classes\n", + "11:34:40.259 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Successfully compiled com.example.lombok.LombokExample and added to classpath\n" ] } ], @@ -287,7 +271,7 @@ }, { "cell_type": "code", - "execution_count": 77, + "execution_count": 9, "id": "787aeffd", "metadata": { "vscode": { @@ -319,7 +303,7 @@ }, { "cell_type": "code", - "execution_count": 78, + "execution_count": 10, "id": "cb698277", "metadata": { "vscode": { @@ -342,7 +326,7 @@ }, { "cell_type": "code", - "execution_count": 79, + "execution_count": 11, "id": "494de548", "metadata": { "vscode": { @@ -365,7 +349,7 @@ }, { "cell_type": "code", - "execution_count": 80, + "execution_count": 12, "id": "ad449c8e", "metadata": { "vscode": { @@ -392,7 +376,7 @@ }, { "cell_type": "code", - "execution_count": 81, + "execution_count": 13, "id": "4dc8c214", "metadata": { "vscode": { @@ -423,7 +407,7 @@ }, { "cell_type": "code", - "execution_count": 82, + "execution_count": 14, "id": "866de2ae", "metadata": { "vscode": { @@ -436,21 +420,21 @@ "output_type": "stream", "text": [ "registered line magics: \n", - "\t- printerPrefix\n", - "\t- jars\n", - "\t- read\n", + "\t- pom, loadFromPOM\n", "\t- listMagic, list\n", + "\t- read\n", "\t- listLineMagic\n", "\t- listCellMagic\n", "\t- maven, addMavenDependencies, addMavenDependency\n", + "\t- printerPrefix\n", + "\t- cmd\n", "\t- printWithName\n", + "\t- jars\n", + "\t- load\n", "\t- commonshellcmd\n", - "\t- pom, loadFromPOM\n", - "\t- cmd\n", - "\t- addMavenRepo, mavenRepo\n", "\t- write\n", - "\t- load\n", - "\t- classpath\n" + "\t- classpath\n", + "\t- addMavenRepo, mavenRepo\n" ] } ], @@ -460,7 +444,7 @@ }, { "cell_type": "code", - "execution_count": 83, + "execution_count": 15, "id": "d01ffcc3", "metadata": { "vscode": { @@ -473,20 +457,23 @@ "output_type": "stream", "text": [ "registered cell magics: \n", - "\t- javasrcInterfaceByName\n", - "\t- myshell\n", + "\t- javasrcClassByName\n", "\t- write\n", - "\t- commonshell\n", "\t- plantUMLFile\n", "\t- compile\n", + "\t- rdbmsSchema\n", "\t- javasrcMethodByName\n", - "\t- shell\n", - "\t- mycompile\n", - "\t- javasrcClassByName\n", - "\t- pom, loadFromPOM\n", + "\t- javasrcMethodByAnnotationName\n", "\t- timeIt, timeit, time\n", + "\t- shell\n", + "\t- javasrcList\n", + "\t- myshell\n", + "\t- sqlAsTable\n", + "\t- javasrcInterfaceByName\n", "\t- plantUML\n", - "\t- javasrcMethodByAnnotationName\n" + "\t- mycompile\n", + "\t- commonshell\n", + "\t- pom, loadFromPOM\n" ] } ], @@ -496,7 +483,7 @@ }, { "cell_type": "code", - "execution_count": 84, + "execution_count": 16, "id": "31360433", "metadata": { "vscode": { @@ -508,7 +495,7 @@ "name": "stdout", "output_type": "stream", "text": [ - "Change printer prefix from \"MyDemoPrefix\" to \"MyDemoPrefix\"\n", + "Change printer prefix from \"\" to \"MyDemoPrefix\"\n", "run %printWithName to switch\n" ] } @@ -520,7 +507,7 @@ }, { "cell_type": "code", - "execution_count": 85, + "execution_count": 17, "id": "06cc1e0d", "metadata": { "vscode": { @@ -544,7 +531,7 @@ }, { "cell_type": "code", - "execution_count": 86, + "execution_count": 18, "id": "60713d12", "metadata": { "vscode": { @@ -555,10 +542,10 @@ { "data": { "image/svg+xml": [ - "AliceAliceBobBobHiHello" + "AliceBobAliceAliceBobBobHiHello" ], "text/plain": [ - "AliceAliceBobBobHiHello" + "AliceBobAliceAliceBobBobHiHello" ] }, "metadata": {}, @@ -575,7 +562,7 @@ }, { "cell_type": "code", - "execution_count": 87, + "execution_count": 19, "id": "d63954b1", "metadata": { "vscode": { @@ -587,10 +574,10 @@ "name": "stdout", "output_type": "stream", "text": [ - "epoch 0: LongSummaryStatistics{count=5, sum=110, min=22, average=22,000000, max=22}\n", + "epoch 0: LongSummaryStatistics{count=5, sum=90, min=18, average=18,000000, max=18}\n", "epoch 1: LongSummaryStatistics{count=5, sum=80, min=16, average=16,000000, max=16}\n", - "epoch 2: LongSummaryStatistics{count=5, sum=85, min=17, average=17,000000, max=17}\n", - "total: LongSummaryStatistics{count=15, sum=275, min=16, average=18,333333, max=22}\n" + "epoch 2: LongSummaryStatistics{count=5, sum=75, min=15, average=15,000000, max=15}\n", + "total: LongSummaryStatistics{count=15, sum=245, min=15, average=16,333333, max=18}\n" ] } ], @@ -603,11 +590,543 @@ }, { "cell_type": "markdown", - "id": "3b9432ef", + "id": "9dadb43d", "metadata": {}, "source": [ - "---\n", - "**Notes**: This notebook demonstrates the primary magics (first alias only). `%%compile` is used for all compilation examples to ensure annotation-processor support (Lombok)." + "## Database schema & associations\n", + "\n", + "Use the RDBMS magics to inspect database schemas and render query results as tables directly in the notebook.\n", + "\n", + "Examples below call `rdbmsSchema` to print schema information and `sqlAsTable` to render SQL query results. These magics rely on a configured JDBC `EntityManagerFactory`/connection available in the kernel environment." + ] + }, + { + "cell_type": "code", + "execution_count": 20, + "id": "6b2c11e2", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%maven com.h2database:h2:2.2.224\n", + "// Add H2 in-memory JDBC driver to the runtime classpath so the following setup can run" + ] + }, + { + "cell_type": "code", + "execution_count": 21, + "id": "a7d78934", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "H2 in-memory demo DB initialized (jdbc.url=jdbc:h2:mem:demo;DB_CLOSE_DELAY=-1;MODE=PostgreSQL)\n" + ] + } + ], + "source": [ + "System.setProperty(\"jdbc.driver\", \"org.h2.Driver\");\n", + "System.setProperty(\"jdbc.url\", \"jdbc:h2:mem:demo;DB_CLOSE_DELAY=-1;MODE=PostgreSQL\");\n", + "try (java.sql.Connection c = java.sql.DriverManager.getConnection(System.getProperty(\"jdbc.url\"))) {\n", + " try (java.sql.Statement st = c.createStatement()) {\n", + " st.execute(\"CREATE SCHEMA IF NOT EXISTS EX_PRODUCT_ORDER\");\n", + " st.execute(\"CREATE TABLE IF NOT EXISTS EX_PRODUCT_ORDER.PRODUCT (id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, name VARCHAR(255), price DOUBLE)\");\n", + " st.execute(\"CREATE TABLE IF NOT EXISTS EX_PRODUCT_ORDER.CUSTOMER (id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, name VARCHAR(255))\");\n", + " st.execute(\"CREATE TABLE IF NOT EXISTS EX_PRODUCT_ORDER.ORDERS (id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, customer_id BIGINT, order_date TIMESTAMP, FOREIGN KEY (customer_id) REFERENCES EX_PRODUCT_ORDER.CUSTOMER(id))\");\n", + " st.execute(\"CREATE TABLE IF NOT EXISTS EX_PRODUCT_ORDER.ORDER_LINE (id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, order_id BIGINT, product_id BIGINT, quantity INT, FOREIGN KEY (order_id) REFERENCES EX_PRODUCT_ORDER.ORDERS(id), FOREIGN KEY (product_id) REFERENCES EX_PRODUCT_ORDER.PRODUCT(id))\");\n", + " st.execute(\"INSERT INTO EX_PRODUCT_ORDER.PRODUCT(name, price) VALUES ('Pen', 1.0)\");\n", + " st.execute(\"INSERT INTO EX_PRODUCT_ORDER.PRODUCT(name, price) VALUES ('Paper', 5.0)\");\n", + " st.execute(\"INSERT INTO EX_PRODUCT_ORDER.PRODUCT(name, price) VALUES ('Car', 20000)\");\n", + " st.execute(\"INSERT INTO EX_PRODUCT_ORDER.CUSTOMER(name) VALUES ('Alice')\");\n", + " st.execute(\"INSERT INTO EX_PRODUCT_ORDER.CUSTOMER(name) VALUES ('Bob')\");\n", + " st.execute(\"INSERT INTO EX_PRODUCT_ORDER.ORDERS(customer_id, order_date) VALUES (1, CURRENT_TIMESTAMP())\");\n", + " st.execute(\"INSERT INTO EX_PRODUCT_ORDER.ORDERS(customer_id, order_date) VALUES (2, CURRENT_TIMESTAMP())\");\n", + " st.execute(\"INSERT INTO EX_PRODUCT_ORDER.ORDER_LINE(order_id, product_id, quantity) VALUES (1, 1, 2)\");\n", + " st.execute(\"INSERT INTO EX_PRODUCT_ORDER.ORDER_LINE(order_id, product_id, quantity) VALUES (1, 2, 3)\");\n", + " st.execute(\"INSERT INTO EX_PRODUCT_ORDER.ORDER_LINE(order_id, product_id, quantity) VALUES (2, 3, 1)\");\n", + " }\n", + "}\n", + "System.out.println(\"H2 in-memory demo DB initialized (jdbc.url=\" + System.getProperty(\"jdbc.url\") + \")\");" + ] + }, + { + "cell_type": "markdown", + "id": "101dbdff", + "metadata": {}, + "source": [ + "### RDBMS Schema Diagram\n", + "Use the `%%rdbmsSchema` cell magic to render the current JDBC schema as a PlantUML diagram. The kernel uses `jdbc.url` (set earlier) to connect to the demo H2 database." + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "id": "cceb3c23", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/markdown": [ + "```plantuml\n", + "@startuml\n", + "left to right direction\n", + "skinparam roundcorner 5\n", + "skinparam shadowing true\n", + "skinparam entity {\n", + " BackgroundColor #EEEEEE\n", + " ArrowColor #2688d4\n", + " BorderColor #2688d4\n", + "}\n", + "!define primary_key(x) PK x\n", + "!define foreign_key(x) FK x\n", + "!define column(x) * x\n", + "!define table(x) entity x << (T, white) >>\n", + "\n", + "table(CUSTOMER) {\n", + "\tprimary_key(ID) : BIGINT(64)\n", + "--\n", + "\tcolumn(NAME) : CHARACTER VARYING(255)\n", + "}\n", + "table(ORDERS) {\n", + "\tprimary_key(ID) : BIGINT(64)\n", + "--\n", + "\tforeign_key(CUSTOMER_ID) : BIGINT(64)\n", + "\tcolumn(ORDER_DATE) : TIMESTAMP(26)\n", + "}\n", + "table(ORDER_LINE) {\n", + "\tprimary_key(ID) : BIGINT(64)\n", + "--\n", + "\tforeign_key(ORDER_ID) : BIGINT(64)\n", + "\tforeign_key(PRODUCT_ID) : BIGINT(64)\n", + "\tcolumn(QUANTITY) : INTEGER(32)\n", + "}\n", + "table(PRODUCT) {\n", + "\tprimary_key(ID) : BIGINT(64)\n", + "--\n", + "\tcolumn(NAME) : CHARACTER VARYING(255)\n", + "\tcolumn(PRICE) : DOUBLE PRECISION(53)\n", + "}\n", + "ORDERS \"0..*\" --> \"1\" CUSTOMER : CUSTOMER_ID -> ID\n", + "ORDER_LINE \"0..*\" --> \"1\" ORDERS : ORDER_ID -> ID\n", + "ORDER_LINE \"0..*\" --> \"1\" PRODUCT : PRODUCT_ID -> ID\n", + "@enduml\n", + "```" + ], + "text/plain": [ + "```plantuml\n", + "@startuml\n", + "left to right direction\n", + "skinparam roundcorner 5\n", + "skinparam shadowing true\n", + "skinparam entity {\n", + " BackgroundColor #EEEEEE\n", + " ArrowColor #2688d4\n", + " BorderColor #2688d4\n", + "}\n", + "!define primary_key(x) PK x\n", + "!define foreign_key(x) FK x\n", + "!define column(x) * x\n", + "!define table(x) entity x << (T, white) >>\n", + "\n", + "table(CUSTOMER) {\n", + "\tprimary_key(ID) : BIGINT(64)\n", + "--\n", + "\tcolumn(NAME) : CHARACTER VARYING(255)\n", + "}\n", + "table(ORDERS) {\n", + "\tprimary_key(ID) : BIGINT(64)\n", + "--\n", + "\tforeign_key(CUSTOMER_ID) : BIGINT(64)\n", + "\tcolumn(ORDER_DATE) : TIMESTAMP(26)\n", + "}\n", + "table(ORDER_LINE) {\n", + "\tprimary_key(ID) : BIGINT(64)\n", + "--\n", + "\tforeign_key(ORDER_ID) : BIGINT(64)\n", + "\tforeign_key(PRODUCT_ID) : BIGINT(64)\n", + "\tcolumn(QUANTITY) : INTEGER(32)\n", + "}\n", + "table(PRODUCT) {\n", + "\tprimary_key(ID) : BIGINT(64)\n", + "--\n", + "\tcolumn(NAME) : CHARACTER VARYING(255)\n", + "\tcolumn(PRICE) : DOUBLE PRECISION(53)\n", + "}\n", + "ORDERS \"0..*\" --> \"1\" CUSTOMER : CUSTOMER_ID -> ID\n", + "ORDER_LINE \"0..*\" --> \"1\" ORDERS : ORDER_ID -> ID\n", + "ORDER_LINE \"0..*\" --> \"1\" PRODUCT : PRODUCT_ID -> ID\n", + "@enduml\n", + "```" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "image/svg+xml": [ + "CUSTOMERPKID: BIGINT(64)*NAME : CHARACTER VARYING(255)ORDERSPKID: BIGINT(64)FKCUSTOMER_ID : BIGINT(64)*ORDER_DATE : TIMESTAMP(26)ORDER_LINEPKID: BIGINT(64)FKORDER_ID : BIGINT(64)FKPRODUCT_ID : BIGINT(64)*QUANTITY : INTEGER(32)PRODUCTPKID: BIGINT(64)*NAME : CHARACTER VARYING(255)*PRICE : DOUBLE PRECISION(53)CUSTOMER_ID -> ID0..*1ORDER_ID -> ID0..*1PRODUCT_ID -> ID0..*1" + ], + "text/plain": [ + "CUSTOMERPKID: BIGINT(64)*NAME : CHARACTER VARYING(255)ORDERSPKID: BIGINT(64)FKCUSTOMER_ID : BIGINT(64)*ORDER_DATE : TIMESTAMP(26)ORDER_LINEPKID: BIGINT(64)FKORDER_ID : BIGINT(64)FKPRODUCT_ID : BIGINT(64)*QUANTITY : INTEGER(32)PRODUCTPKID: BIGINT(64)*NAME : CHARACTER VARYING(255)*PRICE : DOUBLE PRECISION(53)CUSTOMER_ID -> ID0..*1ORDER_ID -> ID0..*1PRODUCT_ID -> ID0..*1" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%rdbmsSchema EX_PRODUCT_ORDER showSource\n", + "// leave body empty to include all tables in the schema" + ] + }, + { + "cell_type": "markdown", + "id": "b8c145a8", + "metadata": {}, + "source": [ + "### SQL Results as HTML Table\n", + "Use `%%sqlAsTable` to run a query and render results as an HTML table in the notebook." + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "id": "728e6207", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/html": [ + "\n", + "\n", + "\n", + "\n", + "\n", + "\n", + "
IDNAMEPRICE
1Pen1.0
2Paper5.0
3Car20000.0
" + ], + "text/plain": [ + "\n", + "\n", + "\n", + "\n", + "\n", + "\n", + "
IDNAMEPRICE
1Pen1.0
2Paper5.0
3Car20000.0
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%sqlAsTable\n", + "SELECT id, name, price FROM EX_PRODUCT_ORDER.PRODUCT ORDER BY id LIMIT 10 OFFSET 0;" + ] + }, + { + "cell_type": "markdown", + "id": "77cf1852", + "metadata": {}, + "source": [ + "### PlantUML from File\n", + "Create a PlantUML file and render it with `%%plantUMLFile`." + ] + }, + { + "cell_type": "code", + "execution_count": 24, + "id": "272c920e", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Write to \u001b[36m/tmp/sample_schema.puml\u001b[0m success.\n" + ] + } + ], + "source": [ + "%%write /tmp/sample_schema.puml\n", + "@startuml\n", + "entity PRODUCT\n", + "entity CUSTOMER\n", + "PRODUCT ||--o{ ORDER_LINE\n", + "@enduml" + ] + }, + { + "cell_type": "code", + "execution_count": 25, + "id": "19d9dcba", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "image/svg+xml": [ + "PRODUCTCUSTOMERORDER_LINE" + ], + "text/plain": [ + "PRODUCTCUSTOMERORDER_LINE" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%plantUMLFile\n", + "/tmp/sample_schema.puml" + ] + }, + { + "cell_type": "markdown", + "id": "45a30a66", + "metadata": {}, + "source": [ + "## Sample Java files\n", + "The folder docs/notebooks/sample_java contains small example Java sources.\n", + "Use `%load` to load a file into a cell, then `%%compile` to compile it. Example workflow:\n", + "- Cell 1: `String file = %load sample_java/com/example/Greeter.java;` (assign loaded file contents to a variable)\n", + "- Cell 2: `%%compile com.example.Greeter -v` (or run the loaded cell content with `%%compile`)\n", + "- Then import and use `com.example.Greeter` in a cell." + ] + }, + { + "cell_type": "code", + "execution_count": 26, + "id": "b4eeb7fd", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "11:34:42.553 [IJava-executor-0] WARN i.g.s.ijava.magics.MagicsTool -- %load: file not found: sample_java/com/example/Greeter.java; (tried 'sample_java/com/example/Greeter.java;')\n", + "null\n" + ] + } + ], + "source": [ + "String file = %load sample_java/com/example/Greeter.java;\n", + "System.out.println(file);" + ] + }, + { + "cell_type": "code", + "execution_count": 27, + "id": "e6813df0", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "11:34:42.653 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Compiling com.example.Greeter with debug=false and nowarn=false\n", + "11:34:42.654 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Source file prepared at: /var/home/bruno/.jupyter/java-workspace/src/main/java/com/example/Greeter.java\n", + "11:34:42.809 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Added to classpath: /var/home/bruno/.jupyter/java-workspace/target/classes\n", + "11:34:42.810 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Successfully compiled com.example.Greeter and added to classpath\n" + ] + } + ], + "source": [ + "%%compile com.example.Greeter -v\n", + "public class Greeter {\n", + " private final String name;\n", + " public Greeter(String name) { this.name = name; }\n", + " public String greet() { return \"Hello \" + name; }\n", + "}" + ] + }, + { + "cell_type": "code", + "execution_count": 28, + "id": "d5ba62a9", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Hello Notebook\n" + ] + } + ], + "source": [ + "import com.example.Greeter;\n", + "Greeter g = new Greeter(\"Notebook\");\n", + "System.out.println(g.greet());" + ] + }, + { + "cell_type": "markdown", + "id": "d471b778", + "metadata": {}, + "source": [ + "## Java source extractors\n", + "Quick demos for `%%javasrcList` and `%%javasrcMethodByName`. Use these to inspect local Java files and pick indices for extraction." + ] + }, + { + "cell_type": "code", + "execution_count": 29, + "id": "fcf6b49a", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/markdown": [ + "Summary of sample_java/com/example/OrderExample.java\n", + "\n", + "ClassOrInterfaceDeclaration: OrderExample\n", + " - String summary(Product)\n", + "\n" + ], + "text/plain": [ + "Summary of sample_java/com/example/OrderExample.java\n", + "\n", + "ClassOrInterfaceDeclaration: OrderExample\n", + " - String summary(Product)\n", + "\n" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%javasrcList\n", + "sample_java/com/example/OrderExample.java" + ] + }, + { + "cell_type": "markdown", + "id": "738fd120", + "metadata": {}, + "source": [ + "- `%%javasrcList file.java` prints a summary (classes, methods, signatures).\n", + "- `%%javasrcMethodByName ClassName methodRegex=^sum` finds methods by regex. Use `--raw` to get plain text output." + ] + }, + { + "cell_type": "code", + "execution_count": 33, + "id": "45a05a57", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/markdown": [ + "**Usage:** `%%javasrcMethodByName [options] [methodName|index]`\n", + "\n", + "**Options:**\n", + "- `--src `: source root to resolve FQCN (e.g., `--src=sample_java`)\n", + "- `methodRegex=`: select methods whose name matches regex\n", + "- `selectIndex=` or positional index: pick one when multiple matches\n", + "- `--raw` / `--fenced`: output format\n", + "\n", + "**Examples:**\n", + "- `%%javasrcMethodByName methodRegex=summary --src=sample_java com.example.OrderExample`\n", + "- `%%javasrcMethodByName com.example.OrderExample myMethod`\n", + "- `%%javasrcMethodByName selectIndex=1 com.example.OrderExample myMethod`\n" + ], + "text/plain": [ + "**Usage:** `%%javasrcMethodByName [options] [methodName|index]`\n", + "\n", + "**Options:**\n", + "- `--src `: source root to resolve FQCN (e.g., `--src=sample_java`)\n", + "- `methodRegex=`: select methods whose name matches regex\n", + "- `selectIndex=` or positional index: pick one when multiple matches\n", + "- `--raw` / `--fenced`: output format\n", + "\n", + "**Examples:**\n", + "- `%%javasrcMethodByName methodRegex=summary --src=sample_java com.example.OrderExample`\n", + "- `%%javasrcMethodByName com.example.OrderExample myMethod`\n", + "- `%%javasrcMethodByName selectIndex=1 com.example.OrderExample myMethod`\n" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%javasrcMethodByName --help\n", + "//need to have some text here to avoid empty cell. TODO: fix it" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "e604f519", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/markdown": [ + "Error: failed to read file `//need to have some text here to avoid empty cell. TODO: fix it`: /need to have some text here to avoid empty cell. TODO: fix it" + ], + "text/plain": [ + "Error: failed to read file `//need to have some text here to avoid empty cell. TODO: fix it`: /need to have some text here to avoid empty cell. TODO: fix it" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%javasrcMethodByName methodRegex=summary --src=sample_java com.example.OrderExample\n", + "sample_java/com/example/OrderExample.java" ] } ], diff --git a/docs/notebooks/sample_java/com/example/Greeter.java b/docs/notebooks/sample_java/com/example/Greeter.java new file mode 100644 index 0000000..6eeccf1 --- /dev/null +++ b/docs/notebooks/sample_java/com/example/Greeter.java @@ -0,0 +1,13 @@ +package com.example; + +public class Greeter { + private final String name; + + public Greeter(String name) { + this.name = name; + } + + public String greet() { + return "Hello " + name; + } +} diff --git a/docs/notebooks/sample_java/com/example/OrderExample.java b/docs/notebooks/sample_java/com/example/OrderExample.java new file mode 100644 index 0000000..9a6c8b5 --- /dev/null +++ b/docs/notebooks/sample_java/com/example/OrderExample.java @@ -0,0 +1,19 @@ +package com.example; + +public class OrderExample { + public static class Product { + public long id; + public String name; + public double price; + + public Product(long id, String name, double price) { + this.id = id; + this.name = name; + this.price = price; + } + } + + public static String summary(Product p) { + return p.id + ":" + p.name + ":" + p.price; + } +} diff --git a/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java index eb9fa3d..7849884 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java @@ -10,8 +10,11 @@ import javax.imageio.ImageIO; import java.io.ByteArrayInputStream; import java.io.ByteArrayOutputStream; +import java.io.IOException; import java.nio.charset.Charset; import java.sql.*; +import java.util.regex.Matcher; +import java.util.regex.Pattern; import java.util.Map; import java.util.TreeMap; import java.util.stream.Collectors; @@ -41,7 +44,17 @@ public static Field of(String name, String size, String type, boolean nullable, } public String toString() { - return String.format("%s %s(%s): %s(%s)", nullable ? "" : "*", role.name, name, type, size); + String t = type == null ? "" : type; + String s = size == null ? "" : size; + String sizePart = (s == null || s.isEmpty()) ? "" : "(" + s + ")"; + switch (this.role) { + case PK: + return String.format("primary_key(%s) : %s%s", quoteIdentifier(name), t, sizePart); + case FK: + return String.format("foreign_key(%s) : %s%s", quoteIdentifier(name), t, sizePart); + default: + return String.format("column(%s) : %s%s", quoteIdentifier(name), t, sizePart); + } } public String getName() { @@ -98,7 +111,7 @@ private static class Table { private Map fields = new TreeMap<>(); public Table(String tableName) { - this.name = tableName; + this.name = sanitizeTableName(tableName); } public Map getFields() { @@ -106,7 +119,7 @@ public Map getFields() { } public String toString() { - return "table(" + name + ") {\n" + + return "table(" + quoteIdentifier(name) + ") {\n" + this.getFields().values().stream().filter(f -> f.getRole() == Field.Role.PK).map(Object::toString) .map(s -> "\t" + s).collect(Collectors.joining("\n")) + @@ -118,13 +131,71 @@ public String toString() { } } + private static String sanitizeTableName(String name) { + if (name == null) return "UNKNOWN"; + String t = name.trim(); + if (t.isEmpty()) return "UNKNOWN"; + if (t.startsWith("//")) t = t.substring(2).trim(); + if (t.startsWith("#")) t = t.substring(1).trim(); + if (t.startsWith("--")) t = t.substring(2).trim(); + if ((t.startsWith("\"") && t.endsWith("\"")) || (t.startsWith("'") && t.endsWith("'"))) { + t = t.substring(1, t.length() - 1).trim(); + } + if (t.isEmpty()) return "UNKNOWN"; + return t; + } + + private static String quoteIdentifier(String s) { + if (s == null) return "UNKNOWN"; + String t = s.trim(); + if (t.matches("[A-Za-z0-9_]+")) return t; + String esc = t.replace("\"", "\\\""); + return "\"" + esc + "\""; + } + /** * Cell magic to print a schema overview for a given schema name. * Usage: applyCellMagic("rdbmsSchema", List.of("schema_name"), "%") */ @CellMagic("rdbmsSchema") public void rdbmsSchema(java.util.List args, String body) { - String schema = args.isEmpty() ? null : args.get(0); + // args may contain: [] [SVG|PNG] [showSource|-s] [handwritten] [include=] [exclude=] [scale=] + String schema = null; + boolean showSource = false; + String fileFormat = "SVG"; + boolean handwritten = false; + String includeRegex = null; + String excludeRegex = null; + String scale = null; + for (String a : args) { + if (a == null) continue; + String aa = a.trim(); + if (aa.equalsIgnoreCase("SVG") || aa.equalsIgnoreCase("PNG")) { + fileFormat = aa.toUpperCase(); + continue; + } + if (aa.equalsIgnoreCase("showSource") || aa.equalsIgnoreCase("show-source") || aa.equals("--show-source") || aa.equals("-s") || aa.equalsIgnoreCase("source")) { + showSource = true; + continue; + } + if (aa.equalsIgnoreCase("handwritten") || aa.equalsIgnoreCase("--handwritten") || aa.equalsIgnoreCase("handwritten:true")) { + handwritten = true; + continue; + } + if (aa.startsWith("include=")) { + includeRegex = aa.substring("include=".length()); + continue; + } + if (aa.startsWith("exclude=")) { + excludeRegex = aa.substring("exclude=".length()); + continue; + } + if (aa.startsWith("scale=")) { + scale = aa.substring("scale=".length()); + continue; + } + if (schema == null) schema = aa; + } try (Connection conn = obtainConnection()) { if (conn == null) { @@ -139,19 +210,30 @@ public void rdbmsSchema(java.util.List args, String body) { out.append("left to right direction\n"); out.append("skinparam roundcorner 5\n"); out.append("skinparam shadowing true\n"); - out.append("skinparam handwritten false\n"); - out.append("skinparam class { BackgroundColor #EEEEEE ArrowColor #2688d4 BorderColor #2688d4 }\n"); - out.append("!define primary_key(x) <&key> x\n"); - out.append("!define foreign_key(x) <&key> x\n"); - out.append("!define column(x) <&media-record> x\n"); + // Handwritten mode is opt-in; default is not handwritten + out.append("skinparam entity {\n"); + out.append(" BackgroundColor #EEEEEE\n"); + out.append(" ArrowColor #2688d4\n"); + out.append(" BorderColor #2688d4\n"); + out.append("}\n"); + // Avoid using PlantUML icon tokens (<&...>) which may trigger the 'handwritten' option. + // Use simple textual markers instead so diagrams render without requiring '!option handwritten true'. + out.append("!define primary_key(x) PK x\n"); + out.append("!define foreign_key(x) FK x\n"); + out.append("!define column(x) * x\n"); out.append("!define table(x) entity x << (T, white) >>\n\n"); + if (handwritten) out.append("!option handwritten true\n"); + if (scale != null && !scale.isBlank()) out.append("scale " + scale + "\n"); // iterate tables (if body contains specific table names, honor them) java.util.List tableNames = new java.util.ArrayList<>(); if (body != null && !body.trim().isEmpty()) { for (String line : body.split("\n")) { String l = line.trim(); - if (!l.isEmpty()) tableNames.add(l); + if (l.isEmpty()) continue; + // ignore common comment markers so comments aren't treated as table names + if (l.startsWith("//") || l.startsWith("#") || l.startsWith("--")) continue; + tableNames.add(l); } } @@ -161,6 +243,21 @@ public void rdbmsSchema(java.util.List args, String body) { } } + // apply include/exclude filters if provided + if (includeRegex != null || excludeRegex != null) { + java.util.Iterator it = tableNames.iterator(); + while (it.hasNext()) { + String tn = it.next(); + if (includeRegex != null && !tn.matches(includeRegex)) { + it.remove(); + continue; + } + if (excludeRegex != null && tn.matches(excludeRegex)) { + it.remove(); + } + } + } + StringBuilder fkBuilder = new StringBuilder(); for (String tableName : tableNames) { @@ -195,7 +292,23 @@ public void rdbmsSchema(java.util.List args, String body) { String pkCol = foreignKeys.getString("PKCOLUMN_NAME"); String fkCol = foreignKeys.getString("FKCOLUMN_NAME"); if (table.getFields().containsKey(fkCol)) table.getFields().get(fkCol).setRole(Field.Role.FK); - fkBuilder.append(String.format("%s::%s --> %s::%s\n", fkTable, fkCol, pkTable, pkCol)); + + // Determine multiplicity on the FK side. + String fkMin = "0"; + String fkMax = "*"; + if (table.getFields().containsKey(fkCol)) { + Field fkField = table.getFields().get(fkCol); + fkMin = fkField.isNullable() ? "0" : "1"; + // If FK column is part of the PK (or unique), treat as max 1 + if (fkField.getRole() == Field.Role.PK) fkMax = "1"; + } + + String pkMultiplicity = "1"; // primary key side is single (unique) + String fkMultiplicity = fkMin + ".." + fkMax; + + // Emit relationship with multiplicities and a simple label showing column mapping + fkBuilder.append(String.format("%s \"%s\" --> \"%s\" %s : %s -> %s\n", + quoteIdentifier(fkTable), fkMultiplicity, pkMultiplicity, quoteIdentifier(pkTable), quoteIdentifier(fkCol), quoteIdentifier(pkCol))); } } @@ -205,13 +318,23 @@ public void rdbmsSchema(java.util.List args, String body) { out.append(fkBuilder.toString()); out.append("@enduml"); - // render via PlantUML as SVG + // Optionally display the generated PlantUML source for debugging + if (showSource) { + display("```plantuml\n" + out.toString() + "\n```", "text/markdown"); + } + + // render via PlantUML with requested format SourceStringReader reader = new SourceStringReader(out.toString()); final ByteArrayOutputStream os = new ByteArrayOutputStream(); - DiagramDescription desc = reader.outputImage(os, new FileFormatOption(FileFormat.SVG)); + DiagramDescription desc = reader.outputImage(os, new FileFormatOption(FileFormat.valueOf(fileFormat))); os.close(); - String svg = new String(os.toByteArray(), Charset.forName("UTF-8")); - display(svg, "image/svg+xml"); + Object output; + if (fileFormat.equals("SVG")) + output = new String(os.toByteArray(), Charset.forName("UTF-8")); + else + output = ImageIO.read(new ByteArrayInputStream(os.toByteArray())); + + display(output, fileFormat.equals("SVG") ? "image/svg+xml" : "image/png"); } catch (Exception e) { throw new RuntimeException(e); @@ -227,28 +350,91 @@ public void sqlAsTable(java.util.List args, String body) { String sql = body == null ? "" : body.trim(); if (sql.isEmpty()) return; + // parse args: format=HTML|CSV, max=, showQuery + String format = "HTML"; + int maxRows = 1000; + boolean showQuery = false; + for (String a : args) { + if (a == null) continue; + String aa = a.trim(); + if (aa.equalsIgnoreCase("CSV" ) || aa.equalsIgnoreCase("HTML")) { + format = aa.toUpperCase(); + continue; + } + if (aa.startsWith("format=")) { + format = aa.substring("format=".length()).toUpperCase(); + continue; + } + if (aa.startsWith("max=")) { + try { maxRows = Integer.parseInt(aa.substring("max=".length())); } catch (NumberFormatException ignored) {} + continue; + } + if (aa.equalsIgnoreCase("showQuery") || aa.equalsIgnoreCase("--show-query")) { + showQuery = true; continue; + } + } + try (Connection conn = obtainConnection()) { if (conn == null) { System.out.println("No JDBC connection available. Set system properties 'jdbc.url' (and optionally 'jdbc.user'/'jdbc.password'), or provide a Connection in the kernel environment."); return; } - try (Statement st = conn.createStatement(); ResultSet rs = st.executeQuery(sql)) { + // Normalize SQL for databases like H2 which expect LIMIT before OFFSET. + String normalizedSql = sql; + Pattern p = Pattern.compile("(?i)\\bOFFSET\\s+(\\d+)\\s+LIMIT\\s+(\\d+)"); + Matcher m = p.matcher(normalizedSql); + if (m.find()) { + normalizedSql = m.replaceAll("LIMIT $2 OFFSET $1"); + display("Note: rewrote SQL 'OFFSET ... LIMIT' to 'LIMIT ... OFFSET' for compatibility", "text/markdown"); + } + + try (Statement st = conn.createStatement(); ResultSet rs = st.executeQuery(normalizedSql)) { ResultSetMetaData md = rs.getMetaData(); int cols = md.getColumnCount(); + + if (showQuery) display("````sql\n" + sql + "\n````", "text/markdown"); + + // build CSV + if ("CSV".equalsIgnoreCase(format)) { + StringBuilder csv = new StringBuilder(); + for (int i = 1; i <= cols; i++) { + if (i > 1) csv.append(','); + csv.append(escapeCsv(md.getColumnLabel(i))); + } + csv.append('\n'); + int rowCount = 0; + while (rs.next() && rowCount < maxRows) { + rowCount++; + for (int i = 1; i <= cols; i++) { + if (i > 1) csv.append(','); + Object v = rs.getObject(i); + csv.append(escapeCsv(v == null ? "" : v.toString())); + } + csv.append('\n'); + } + if (rs.next()) csv.append("# TRUNCATED: more rows available\n"); + display(csv.toString(), "text/csv"); + return; + } + + // default: HTML StringBuilder html = new StringBuilder(); - html.append("\n"); - for (int i = 1; i <= cols; i++) html.append(""); - html.append("\n"); - while (rs.next()) { + html.append("
").append(md.getColumnLabel(i)).append("
\n"); + for (int i = 1; i <= cols; i++) html.append(""); + html.append("\n\n"); + int rowCount = 0; + while (rs.next() && rowCount < maxRows) { + rowCount++; html.append(""); for (int i = 1; i <= cols; i++) { Object v = rs.getObject(i); - html.append(""); + html.append(""); } html.append("\n"); } - html.append("
").append(escapeHtml(md.getColumnLabel(i))).append("
").append(v == null ? "" : escapeHtml(v.toString())).append("").append(v == null ? "" : escapeHtml(v.toString())).append("
"); + html.append(""); + if (rs.next()) html.append("
Results truncated (showing first "+maxRows+" rows)
"); display(html.toString(), "text/html"); } } catch (SQLException e) { @@ -260,6 +446,14 @@ private static String escapeHtml(String s) { return s.replace("&", "&").replace("<", "<").replace(">", ">").replace("\"", """).replace("'", "'"); } + private static String escapeCsv(String s) { + String v = s.replace("\"", "\"\""); + if (v.contains(",") || v.contains("\n") || v.contains("\r") || v.contains("\"")) { + return "\"" + v + "\""; + } + return v; + } + /** * Attempt to obtain a JDBC Connection from several strategies: * 1) System properties `jdbc.url` (+ user/password) @@ -268,27 +462,52 @@ private static String escapeHtml(String s) { private Connection obtainConnection() throws SQLException { String url = System.getProperty("jdbc.url"); if (url != null && !url.isBlank()) { - // Attempt to ensure a JDBC driver is loaded. Users can set `jdbc.driver` system property - // to force a specific driver class, or we try a few common drivers (H2, Postgres, MySQL, HSQLDB, SQLite). - String driverProp = System.getProperty("jdbc.driver"); - if (driverProp != null && !driverProp.isBlank()) { + // Ensure a driver will be attempted to be registered later if none are present. + + // Check if any registered driver already accepts this URL + boolean accepts = false; + for (Driver d : java.util.Collections.list(DriverManager.getDrivers())) { try { - Class.forName(driverProp); - } catch (ClassNotFoundException ignored) { - } - } else { - String[] commonDrivers = new String[]{ - "org.h2.Driver", - "org.postgresql.Driver", - "com.mysql.cj.jdbc.Driver", - "org.hsqldb.jdbc.JDBCDriver", - "org.sqlite.JDBC" + if (d.acceptsURL(url)) { accepts = true; break; } + } catch (Exception ignored) { } + } + + if (!accepts) { + // Attempt to load driver class from various classloaders and register a proxy driver + String driverProp = System.getProperty("jdbc.driver"); + String[] candidateDrivers; + if (driverProp != null && !driverProp.isBlank()) candidateDrivers = new String[]{driverProp}; + else candidateDrivers = new String[]{"org.h2.Driver", "org.postgresql.Driver", "com.mysql.cj.jdbc.Driver", "org.hsqldb.jdbc.JDBCDriver", "org.sqlite.JDBC"}; + + ClassLoader[] loaders = new ClassLoader[]{ + Thread.currentThread().getContextClassLoader(), + ClassLoader.getSystemClassLoader(), + this.getClass().getClassLoader(), + io.github.spencerpark.ijava.IJava.class.getClassLoader() }; - for (String d : commonDrivers) { - try { - Class.forName(d); - } catch (ClassNotFoundException ignored) { + + for (String drv : candidateDrivers) { + for (ClassLoader loader : loaders) { + if (loader == null) continue; + try { + Class drvClass = Class.forName(drv, true, loader); + Object drvInstance = drvClass.getDeclaredConstructor().newInstance(); + + java.sql.Driver proxy = (java.sql.Driver) java.lang.reflect.Proxy.newProxyInstance( + java.sql.Driver.class.getClassLoader(), + new Class[]{java.sql.Driver.class}, + (proxyObj, method, args) -> method.invoke(drvInstance, args) + ); + + DriverManager.registerDriver(proxy); + // if it accepts the URL now, break out + if (proxy.acceptsURL(url)) { accepts = true; break; } + } catch (ClassNotFoundException ignored) { + } catch (ReflectiveOperationException | java.sql.SQLException e) { + // continue to next loader/driver + } } + if (accepts) break; } } diff --git a/src/main/java/io/github/spencerpark/ijava/magics/JavaMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/JavaMagics.java index 45efba3..a82179e 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/JavaMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/JavaMagics.java @@ -3,212 +3,272 @@ import com.github.javaparser.StaticJavaParser; import com.github.javaparser.ast.CompilationUnit; import com.github.javaparser.printer.lexicalpreservation.LexicalPreservingPrinter; -import io.github.classgraph.ClassGraph; -import io.github.spencerpark.ijava.IJava; import io.github.spencerpark.jupyter.kernel.magic.registry.CellMagic; -import io.github.spencerpark.jupyter.kernel.magic.registry.MagicsArgs; import lombok.extern.slf4j.Slf4j; -import net.sourceforge.plantuml.FileFormat; -import net.sourceforge.plantuml.FileFormatOption; -import net.sourceforge.plantuml.SourceStringReader; -import net.sourceforge.plantuml.core.DiagramDescription; - -import javax.imageio.ImageIO; -import javax.tools.JavaCompiler; -import javax.tools.JavaFileObject; -import javax.tools.StandardJavaFileManager; -import javax.tools.ToolProvider; -import java.io.*; -import java.net.URI; -import java.nio.charset.Charset; + +import java.io.IOException; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; import java.util.*; +import java.util.regex.Pattern; import java.util.stream.Collectors; import static io.github.spencerpark.ijava.runtime.Display.display; -import static io.github.spencerpark.ijava.runtime.Magics.cellMagic; @Slf4j public class JavaMagics { - /** - * %%javasrcMethodByAnnotationName Test POST - * /src/Test.java - */ - // IJava.getKernelInstance().getMagics().registerCellMagic("javasrcMethodByAnnotationName", - // (args, body) -> { -/* @CellMagic("javasrcMethodByAnnotationName") - public void javasrcMethodByAnnotationName(List args, String body) { - String filename = body; - String className = args.get(0); - String annotationName = args.get(1); - int index = args.size() == 3 ? Integer.valueOf(args.get(2)) : 0; - CompilationUnit cu = StaticJavaParser.parse(Files.readString(Path.of(filename))); - String out = cu.getClassByName(className).get() - .getMethods() - .stream() - .filter(m -> m.getAnnotations().stream().anyMatch(a -> a.getNameAsString().equals(annotationName))) - .skip(index) - .findFirst().get().toString(); - out = "```Java\n" + out + "\n```"; - display(out, "text/markdown"); - }*/ - - /** - * %%javasrcMethodByName Test getAll - * /src/Test.java - */ - // IJava.getKernelInstance().getMagics().registerCellMagic("javasrcMethodByName", - // (args, body) -> { -/* @CellMagic("javasrcMethodByName") - public void javasrcMethodByName(List args, String body) { - String filename = body; - String className = args.get(0); - String methodName = args.get(1); - int index = args.size() == 3 ? Integer.valueOf(args.get(2)) : 0; - CompilationUnit cu = StaticJavaParser.parse(Files.readString(Path.of(filename))); - String out = cu.getClassByName(className).get() - .getMethodsByName(methodName) - .get(index) - .toString(); - out = "```Java\n" + out + "\n```"; - display(out, "text/markdown"); - }*/ - - /** - * %%javasrcInterfaceByName Test - * /src/Test.java - */ - - // IJava.getKernelInstance().getMagics().registerCellMagic("javasrcInterfaceByName", - // (args, body) -> { -/* @CellMagic("javasrcInterfaceByName") - public void javasrcInterfaceByName(List args, String body) { - final String path = args.get(0); - final String filename = path + "/" + body.replace(".", "/") + ".java"; - final String className = body.substring(body.lastIndexOf('.') + 1); - CompilationUnit cu = StaticJavaParser.parse(Files.readString(Path.of(filename))); - String out = cu.getInterfaceByName(className).get() - .toString(); - // out = "```Java\n"+out+"\n```"; - out = "```{.java fig-cap=\"TEST\",filename=\"" + filename.substring(filename.lastIndexOf('/') + 1) + "\"}\n" - + out + "\n```"; - display(out, "text/markdown"); - }*/ - - /** - * %%javasrcClassByName Test - * /src/Test.java - */ - - // IJava.getKernelInstance().getMagics().registerCellMagic("javasrcClassByName", - // (args, body) -> { -/* @CellMagic("javasrcClassByName") - public void javasrcClassByName(List args, String body) { - String filename = body; - String className = args.get(0); - CompilationUnit cu = StaticJavaParser.parse(Files.readString(Path.of(filename))); - CompilationUnit lpp = LexicalPreservingPrinter.setup(cu); - - String out = LexicalPreservingPrinter.print(lpp.getClassByName(className).get()); - - out = "```Java\n" + out + "\n```"; - display(out, "text/markdown"); - }*/ - - /** - * %%javasrcMethodByAnnotationName Test POST - * /src/Test.java - */ @CellMagic("javasrcMethodByAnnotationName") public void javasrcMethodByAnnotationName(List args, String body) throws IOException { + Map opts = OptionUtils.parseOptions(args); + List pos = OptionUtils.positionalArgs(args); + + if (pos.size() < 2) { + display("Error: expected usage `%%javasrcMethodByAnnotationName [index]`", "text/markdown"); + return; + } + String filename = body; - String className = args.get(0); - String annotationName = args.get(1); - int index = args.size() == 3 ? Integer.valueOf(args.get(2)) : 0; - CompilationUnit cu = null; + String className = pos.get(0); + String simpleClassName = className != null && className.contains(".") ? className.substring(className.lastIndexOf('.') + 1) : className; + String annotationName = pos.get(1); + int index = pos.size() >= 3 ? Integer.parseInt(pos.get(2)) : 0; + + if ((filename == null || filename.isBlank()) && className != null && className.contains(".")) { + Optional p = PathResolver.resolveSourceFileForClass(className, opts); + if (p.isPresent()) filename = p.get().toString(); + } + + CompilationUnit cu; try { cu = StaticJavaParser.parse(Files.readString(Path.of(filename))); } catch (IOException e) { - log.error("Error parsing file", e); - throw e; + display("Error: failed to read file `" + filename + "`: " + e.getMessage(), "text/markdown"); + return; + } + + Optional clazz = cu.getClassByName(simpleClassName); + if (clazz.isEmpty()) { + display("Class `" + className + "` not found in file `" + filename + "`.", "text/markdown"); + return; } - String out = cu.getClassByName(className).get() - .getMethods() + + List matches = clazz.get().getMethods() .stream() .filter(m -> m.getAnnotations().stream().anyMatch(a -> a.getNameAsString().equals(annotationName))) - .skip(index) - .findFirst().get().toString(); - out = "```Java\n" + out + "\n```"; - display(out, "text/markdown"); + .collect(Collectors.toList()); + + if (matches.isEmpty()) { + display("No methods annotated with `@" + annotationName + "` found in class `" + className + "`.", "text/markdown"); + return; + } + + if (index < 0 || index >= matches.size()) { + StringBuilder sb = new StringBuilder(); + sb.append("Found ").append(matches.size()).append(" matching methods:\n\n"); + for (int i = 0; i < matches.size(); i++) { + sb.append(i).append(": ").append(matches.get(i).getDeclarationAsString(false, false, false)).append("\n"); + } + display(sb.toString(), opts.getOrDefault("format", "fenced").equals("raw") ? "text/plain" : "text/markdown"); + return; + } + + String out = matches.get(index).toString(); + OutputUtils.formatAndDisplay(out, opts); } - /** - * %%javasrcMethodByName Test getAll - * /src/Test.java - */ @CellMagic("javasrcMethodByName") public void javasrcMethodByName(List args, String body) throws IOException { + // If the user requested help, short-circuit immediately and do not + // attempt any file reads or parsing of the cell body which may cause + // spurious build/parse attempts (e.g. when the body is empty or a + // comment). This ensures `--help` never triggers a build. + if (args != null && (args.contains("--help") || args.contains("-h"))) { + String help = "**Usage:** `%%javasrcMethodByName [options] [methodName|index]`\n\n" + + "**Options:**\n" + + "- `--src `: source root to resolve FQCN (e.g., `--src=sample_java`)\n" + + "- `methodRegex=`: select methods whose name matches regex\n" + + "- `selectIndex=` or positional index: pick one when multiple matches\n" + + "- `--raw` / `--fenced`: output format\n\n" + + "**Examples:**\n" + + "- `%%javasrcMethodByName methodRegex=summary --src=sample_java com.example.OrderExample`\n" + + "- `%%javasrcMethodByName com.example.OrderExample myMethod`\n" + + "- `%%javasrcMethodByName selectIndex=1 com.example.OrderExample myMethod`\n"; + display(help, "text/markdown"); + return; + } + + Map opts = OptionUtils.parseOptions(args); + List pos = OptionUtils.positionalArgs(args); + + if (pos.size() < 1 && !opts.containsKey("methodRegex")) { + display("Error: expected usage `%%javasrcMethodByName ` or use `methodRegex=...`", "text/markdown"); + return; + } + String filename = body; - String className = args.get(0); - String methodName = args.get(1); - int index = args.size() == 3 ? Integer.valueOf(args.get(2)) : 0; - CompilationUnit cu = null; + String className = pos.size() >= 1 ? pos.get(0) : null; + String simpleClassName = className != null && className.contains(".") ? className.substring(className.lastIndexOf('.') + 1) : className; + String methodName = pos.size() >= 2 ? pos.get(1) : null; + int index = pos.size() >= 3 ? Integer.parseInt(pos.get(2)) : 0; + + if ((filename == null || filename.isBlank()) && className != null && className.contains(".")) { + Optional p = PathResolver.resolveSourceFileForClass(className, opts); + if (p.isPresent()) filename = p.get().toString(); + } + + CompilationUnit cu; try { cu = StaticJavaParser.parse(Files.readString(Path.of(filename))); } catch (IOException e) { - log.error("Error parsing file", e); - throw e; - } - String out = cu.getClassByName(className).get() - .getMethodsByName(methodName) - .get(index) - .toString(); - out = "```Java\n" + out + "\n```"; - display(out, "text/markdown"); + display("Error: failed to read file `" + filename + "`: " + e.getMessage(), "text/markdown"); + return; + } + + Optional clazz = cu.getClassByName(simpleClassName); + if (clazz.isEmpty()) { + display("Class `" + className + "` not found in file `" + filename + "`.", "text/markdown"); + return; + } + + List methods = new ArrayList<>(); + if (opts.containsKey("methodRegex")) { + Pattern p = Pattern.compile(opts.get("methodRegex")); + methods = clazz.get().getMethods().stream().filter(m -> p.matcher(m.getNameAsString()).find()).collect(Collectors.toList()); + } else if (methodName != null) { + methods = clazz.get().getMethodsByName(methodName); + } + + if (methods.isEmpty()) { + display("No matching methods found for query in class `" + className + "`.", "text/markdown"); + return; + } + + if (methods.size() > 1 && !opts.containsKey("selectIndex")) { + StringBuilder sb = new StringBuilder(); + sb.append("Found ").append(methods.size()).append(" matching methods:\n\n"); + for (int i = 0; i < methods.size(); i++) { + sb.append(i).append(": ").append(methods.get(i).getDeclarationAsString(false, false, false)).append("\n"); + } + display(sb.toString(), opts.getOrDefault("format", "fenced").equals("raw") ? "text/plain" : "text/markdown"); + return; + } + + int pick = opts.containsKey("selectIndex") ? Integer.parseInt(opts.get("selectIndex")) : index; + if (pick < 0 || pick >= methods.size()) { + display("Index out of range. Use the summary list to pick an index.", "text/markdown"); + return; + } + + String out = methods.get(pick).toString(); + OutputUtils.formatAndDisplay(out, opts); } @CellMagic("javasrcInterfaceByName") public void javasrcInterfaceByName(List args, String body) throws IOException { - final String path = args.get(0); - final String filename = path + "/" + body.replace(".", "/") + ".java"; - final String className = body.substring(body.lastIndexOf('.') + 1); - CompilationUnit cu = null; + Map opts = OptionUtils.parseOptions(args); + List pos = OptionUtils.positionalArgs(args); + + if (pos.size() < 1) { + display("Error: expected usage `%%javasrcInterfaceByName `", "text/markdown"); + return; + } + + String fqcn = pos.get(0); + String filename = body; + if ((filename == null || filename.isBlank()) && fqcn != null && fqcn.contains(".")) { + Optional p = PathResolver.resolveSourceFileForClass(fqcn, opts); + if (p.isPresent()) filename = p.get().toString(); + } + + String className = fqcn.substring(fqcn.lastIndexOf('.') + 1); + + CompilationUnit cu; try { cu = StaticJavaParser.parse(Files.readString(Path.of(filename))); } catch (IOException e) { - log.error("Error parsing file", e); - throw e; - } - String out = cu.getInterfaceByName(className).get() - .toString(); - out = "```{.java fig-cap=\"TEST\",filename=\"" + filename.substring(filename.lastIndexOf('/') + 1) + "\"}\n" - + out + "\n```"; - display(out, "text/markdown"); + display("Error: failed to read file `" + filename + "`: " + e.getMessage(), "text/markdown"); + return; + } + + Optional iface = cu.getInterfaceByName(className); + if (iface.isEmpty()) { + display("Interface `" + className + "` not found in file `" + filename + "`.", "text/markdown"); + return; + } + + String out = iface.get().toString(); + OutputUtils.formatAndDisplay(out, opts); } @CellMagic("javasrcClassByName") public void javasrcClassByName(List args, String body) throws IOException { + Map opts = OptionUtils.parseOptions(args); + List pos = OptionUtils.positionalArgs(args); + + if (pos.isEmpty()) { + display("Error: expected usage `%%javasrcClassByName `", "text/markdown"); + return; + } + + String fqcn = pos.get(0); String filename = body; - String className = args.get(0); - CompilationUnit cu = null; + if ((filename == null || filename.isBlank()) && fqcn != null && fqcn.contains(".")) { + Optional p = PathResolver.resolveSourceFileForClass(fqcn, opts); + if (p.isPresent()) filename = p.get().toString(); + } + + String className = fqcn.substring(fqcn.lastIndexOf('.') + 1); + + CompilationUnit cu; try { cu = StaticJavaParser.parse(Files.readString(Path.of(filename))); } catch (IOException e) { - log.error("Error parsing file", e); - throw e; + display("Error: failed to read file `" + filename + "`: " + e.getMessage(), "text/markdown"); + return; } + CompilationUnit lpp = LexicalPreservingPrinter.setup(cu); - String out = LexicalPreservingPrinter.print(lpp.getClassByName(className).get()); + Optional clazz = lpp.getClassByName(className); + if (clazz.isEmpty()) { + display("Class `" + className + "` not found in file `" + filename + "`.", "text/markdown"); + return; + } - out = "```Java\n" + out + "\n```"; - display(out, "text/markdown"); + String out = LexicalPreservingPrinter.print(clazz.get()); + OutputUtils.formatAndDisplay(out, opts); } + @CellMagic("javasrcList") + public void javasrcList(List args, String body) throws IOException { + Map opts = OptionUtils.parseOptions(args); + List pos = OptionUtils.positionalArgs(args); + String filename = body; + if ((filename == null || filename.isBlank()) && !pos.isEmpty() && pos.get(0).contains(".")) { + Optional p = PathResolver.resolveSourceFileForClass(pos.get(0), opts); + if (p.isPresent()) filename = p.get().toString(); + } + CompilationUnit cu; + try { + cu = StaticJavaParser.parse(Files.readString(Path.of(filename))); + } catch (IOException e) { + display("Error: failed to read file `" + filename + "`: " + e.getMessage(), "text/markdown"); + return; + } + + StringBuilder sb = new StringBuilder(); + sb.append("Summary of ").append(filename).append("\n\n"); + cu.getTypes().forEach(t -> { + sb.append(t.getClass().getSimpleName()).append(": ").append(t.getNameAsString()).append("\n"); + t.getMethods().forEach(m -> sb.append(" - ").append(m.getDeclarationAsString(false, false, false)).append("\n")); + sb.append("\n"); + }); + + display(sb.toString(), "text/markdown"); + } } \ No newline at end of file diff --git a/src/main/java/io/github/spencerpark/ijava/magics/JavaPlantUMLMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/JavaPlantUMLMagics.java index 4f08707..0a69a26 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/JavaPlantUMLMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/JavaPlantUMLMagics.java @@ -28,14 +28,9 @@ public class JavaPlantUMLMagics { */ @CellMagic("plantUML") public void plantUML(List args, String body) throws IOException { - // sets the results mimetype - if (args.size() > 1) - throw new IllegalArgumentException("Max one argument : SVG or PNG"); - String fileFormat; - if (args.isEmpty()) - fileFormat = "SVG"; - else - fileFormat = args.get(0); + // args may include a format (SVG/PNG) and/or a flag to show source for debugging. + boolean showSource = args.stream().anyMatch(a -> a.equalsIgnoreCase("showSource") || a.equalsIgnoreCase("show-source") || a.equals("--show-source") || a.equals("-s") || a.equalsIgnoreCase("source")); + String fileFormat = args.stream().filter(a -> a.equalsIgnoreCase("SVG") || a.equalsIgnoreCase("PNG")).findFirst().orElse("SVG"); SourceStringReader reader = new SourceStringReader(body); final ByteArrayOutputStream os = new ByteArrayOutputStream(); @@ -48,10 +43,19 @@ public void plantUML(List args, String body) throws IOException { } os.close(); Object out; - if (fileFormat.equals("SVG")) - out = new String(os.toByteArray(), StandardCharsets.UTF_8); - else + if (fileFormat.equals("SVG")) { + String svg = new String(os.toByteArray(), StandardCharsets.UTF_8); + int idx = svg.indexOf(" 0) svg = svg.substring(idx); + out = svg; + } else { out = ImageIO.read(new ByteArrayInputStream(os.toByteArray())); + } + + if (showSource) { + String md = "```plantuml\n" + (body == null ? "" : body) + "\n```"; + display(md, "text/markdown"); + } display(out, fileFormat.equals("SVG") ? "image/svg+xml" : "image/png"); } @@ -72,16 +76,23 @@ public void plantUMLFile(List args, String body) { List outList = new ArrayList<>(); body.lines().forEach(filename -> { - Object out; try { - out = cellMagic("plantUML", args, Files.readString(Paths.get(filename))); - // display(out,fileFormat.equals("SVG")?"image/svg+xml":"image/png"); - outList.add(out); + Object out = cellMagic("plantUML", args, Files.readString(Paths.get(filename))); + // The invoked cell magic may perform its own display and return null; only display non-null results. + if (out != null) { + outList.add(out); + display(out, fileFormat.equals("SVG") ? "image/svg+xml" : "image/png"); + } } catch (java.io.IOException e) { - log.error("Error parsing file", e); + log.error("Error reading PlantUML file", e); throw new RuntimeException(e); + } catch (RuntimeException e) { + // Bubble up with context to help debugging + log.error("Error running plantUML magic for file {}", filename, e); + throw new RuntimeException("Error running plantUML magic for file " + filename + ": " + e.getMessage(), e); } }); + // if caller expects a combined representation, nothing to return here; outputs have been displayed } diff --git a/src/main/java/io/github/spencerpark/ijava/magics/MagicsTool.java b/src/main/java/io/github/spencerpark/ijava/magics/MagicsTool.java index aac5a76..db036ab 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/MagicsTool.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/MagicsTool.java @@ -23,6 +23,7 @@ */ package io.github.spencerpark.ijava.magics; +import lombok.extern.slf4j.Slf4j; import io.github.spencerpark.ijava.IJava; import io.github.spencerpark.ijava.JavaKernel; import io.github.spencerpark.ijava.execution.CodeEvaluator; @@ -36,11 +37,13 @@ import java.nio.file.Files; import java.nio.file.Path; import java.util.Collection; +import java.util.Optional; import java.util.Collections; import java.util.List; import java.util.Map; import java.util.stream.Collectors; +@Slf4j public class MagicsTool { private static final String HIGHLIGHT_PATTERN = "\u001B[36m%s\u001B[0m"; @@ -108,6 +111,44 @@ public String readFromFile(List args) throws IOException { return String.join("\n", Files.readAllLines(Path.of(args.get(0)))); } + @LineMagic(value = "load") + public String loadFile(List args) throws IOException { + if (args.isEmpty()) { + log.debug("%load called with no args"); + return null; + } + + String raw = args.get(0); + try { + Path p = Path.of(raw); + if (!Files.exists(p)) { + // try docs/notebooks relative path + Path alt = Path.of("docs", "notebooks").resolve(raw); + if (Files.exists(alt)) { + p = alt; + } else { + // try to find matching file in workspace + try { + Optional found = Files.walk(Path.of(".")).filter(f -> f.endsWith(raw)).findFirst(); + if (found.isPresent()) p = found.get(); + } catch (IOException e) { + // ignore search errors + } + } + } + + if (!Files.exists(p)) { + log.warn("%load: file not found: {} (tried '{}')", raw, p); + return null; + } + + return String.join("\n", Files.readAllLines(p)); + } catch (Exception e) { + log.warn("%load: error loading '{}': {}", raw, e.getMessage() == null ? e.getClass().getSimpleName() : e.getMessage()); + return null; + } + } + @LineMagic(value = "write") public void writeToFile(List args) throws IOException { if (args.isEmpty()) { diff --git a/src/main/java/io/github/spencerpark/ijava/magics/OptionUtils.java b/src/main/java/io/github/spencerpark/ijava/magics/OptionUtils.java new file mode 100644 index 0000000..43e0edb --- /dev/null +++ b/src/main/java/io/github/spencerpark/ijava/magics/OptionUtils.java @@ -0,0 +1,41 @@ +package io.github.spencerpark.ijava.magics; + +import java.util.*; + +public final class OptionUtils { + private OptionUtils() {} + + public static Map parseOptions(List args) { + Map opts = new HashMap<>(); + for (int i = 0; i < args.size(); i++) { + String a = args.get(i); + if (a.equals("--raw")) { + opts.put("format", "raw"); + } else if (a.equals("--fenced")) { + opts.put("format", "fenced"); + } else if ((a.equals("--src") || a.equals("--root")) && i + 1 < args.size()) { + opts.put("src", args.get(i + 1)); + i++; // consume + } else if (a.startsWith("--src=") || a.startsWith("--root=")) { + int eq = a.indexOf('='); + opts.put("src", a.substring(eq + 1)); + } else if (a.contains("=")) { + int j = a.indexOf('='); + String k = a.substring(0, j); + String v = a.substring(j + 1); + if (k.equals("index")) { + opts.put("selectIndex", v); + } else { + opts.put(k, v); + } + } + } + return opts; + } + + public static List positionalArgs(List args) { + return args.stream() + .filter(a -> !a.equals("--raw") && !a.equals("--fenced") && !a.startsWith("--src") && !a.startsWith("--root") && !a.contains("=")) + .toList(); + } +} diff --git a/src/main/java/io/github/spencerpark/ijava/magics/OutputUtils.java b/src/main/java/io/github/spencerpark/ijava/magics/OutputUtils.java new file mode 100644 index 0000000..b74f786 --- /dev/null +++ b/src/main/java/io/github/spencerpark/ijava/magics/OutputUtils.java @@ -0,0 +1,17 @@ +package io.github.spencerpark.ijava.magics; + +import java.util.Map; +import static io.github.spencerpark.ijava.runtime.Display.display; + +public final class OutputUtils { + private OutputUtils() {} + + public static void formatAndDisplay(String content, Map opts) { + boolean raw = opts.getOrDefault("format", "fenced").equals("raw"); + if (raw) { + display(content, "text/plain"); + } else { + display("```Java\n" + content + "\n```", "text/markdown"); + } + } +} diff --git a/src/main/java/io/github/spencerpark/ijava/magics/PathResolver.java b/src/main/java/io/github/spencerpark/ijava/magics/PathResolver.java new file mode 100644 index 0000000..8c05204 --- /dev/null +++ b/src/main/java/io/github/spencerpark/ijava/magics/PathResolver.java @@ -0,0 +1,41 @@ +package io.github.spencerpark.ijava.magics; + +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; +import java.nio.file.Paths; +import java.util.ArrayList; +import java.util.List; +import java.util.Optional; + +public final class PathResolver { + private PathResolver() {} + + public static Optional resolveSourceFileForClass(String fullyQualifiedClassName, java.util.Map opts) { + String srcBase = opts.getOrDefault("src", null); + List bases = new ArrayList<>(); + if (srcBase != null && !srcBase.isBlank()) bases.add(srcBase); + bases.add("src/main/java"); + bases.add("src"); + bases.add("docs/notebooks/sample_java"); + + String pkgPath = fullyQualifiedClassName.replace('.', '/'); + String className = fullyQualifiedClassName.substring(fullyQualifiedClassName.lastIndexOf('.') + 1); + String rel = pkgPath + ".java"; + + for (String base : bases) { + Path p = Paths.get(base).resolve(rel); + if (Files.exists(p)) return Optional.of(p); + Path p2 = Paths.get(base).resolve("src/main/java").resolve(rel); + if (Files.exists(p2)) return Optional.of(p2); + } + + try { + final String simple = className + ".java"; + Optional found = Files.walk(Paths.get(".")).filter(Files::isRegularFile).filter(p -> p.getFileName().toString().equals(simple)).findFirst(); + if (found.isPresent()) return found; + } catch (IOException ignored) {} + + return Optional.empty(); + } +} diff --git a/src/test/java/io/github/spencerpark/ijava/magics/DBMSMagicsIntegrationTest.java b/src/test/java/io/github/spencerpark/ijava/magics/DBMSMagicsIntegrationTest.java new file mode 100644 index 0000000..431b5cf --- /dev/null +++ b/src/test/java/io/github/spencerpark/ijava/magics/DBMSMagicsIntegrationTest.java @@ -0,0 +1,8 @@ +// Integration test removed — DBMS integration should be exercised from notebooks via %maven and magics. +// If you want a unit/integration test, add it to the test sources and declare test dependency in build.gradle. + +package io.github.spencerpark.ijava.magics; + +public class DBMSMagicsIntegrationTest { + // placeholder: tests run from notebooks using %maven to load H2 and other dependencies +} From 3c87b5a9a2472f8ee129e953537a62c80809984b Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Fri, 16 Jan 2026 07:38:04 +0100 Subject: [PATCH 08/49] feat(magics): add benchmark sweep support and notebook examples --- .gitignore | 4 + MAGICS_AUDIT_AND_IMPROVEMENT_PLAN.md | 6 +- MAGICS_CONSOLIDATION_SUMMARY.md | 265 ++++ docs/notebooks/ijava_sample_notebook.ipynb | 1349 ++++++++++------- .../sample_java/com/example/Greeter.java | 8 + .../sample_java/com/example/OrderExample.java | 8 + .../sample_java/com/example/Product.java | 17 + .../sample_java/com/example/SayHello.java | 5 + .../github/spencerpark/ijava/JavaKernel.java | 104 +- .../execution/MagicsSourceTransformer.java | 32 +- .../ijava/magics/BenchmarkMagics.java | 286 ++++ .../ijava/magics/ClasspathMagics.java | 24 + .../ijava/magics/JavaCompilerMagics.java | 66 +- .../ijava/magics/JavaDBMSMagics.java | 176 ++- .../spencerpark/ijava/magics/JavaMagics.java | 347 ++++- .../ijava/magics/JavaPlantUMLMagics.java | 22 +- .../spencerpark/ijava/magics/MagicsTool.java | 197 ++- .../ijava/magics/MavenResolver.java | 53 +- .../spencerpark/ijava/magics/OptionUtils.java | 11 +- .../spencerpark/ijava/magics/OutputUtils.java | 3 +- .../ijava/magics/PathResolver.java | 24 +- .../spencerpark/ijava/magics/ShellMagics.java | 80 +- .../ijava/magics/TimeItMagics.java | 58 +- src/main/resources/install.py | 11 +- .../magics/DBMSMagicsIntegrationTest.java | 3 +- .../ijava/magics/SingleShellMagicsTest.java | 27 +- 26 files changed, 2423 insertions(+), 763 deletions(-) create mode 100644 MAGICS_CONSOLIDATION_SUMMARY.md create mode 100644 docs/notebooks/sample_java/com/example/Product.java create mode 100644 docs/notebooks/sample_java/com/example/SayHello.java create mode 100644 src/main/java/io/github/spencerpark/ijava/magics/BenchmarkMagics.java diff --git a/.gitignore b/.gitignore index c80cd6a..50815cf 100644 --- a/.gitignore +++ b/.gitignore @@ -17,3 +17,7 @@ src/main/resources/java/ # Tests artifacts tests/ + +.envrc +.use-google-ai + diff --git a/MAGICS_AUDIT_AND_IMPROVEMENT_PLAN.md b/MAGICS_AUDIT_AND_IMPROVEMENT_PLAN.md index 573aa43..c553b4f 100644 --- a/MAGICS_AUDIT_AND_IMPROVEMENT_PLAN.md +++ b/MAGICS_AUDIT_AND_IMPROVEMENT_PLAN.md @@ -1,5 +1,5 @@ # IJava Magics — Comprehensive Audit & UX Improvement Plan -**Date:** January 15, 2026 +**Date:** January 15, 2026 **Status:** Post-initial-refactor assessment --- @@ -440,6 +440,6 @@ This document provides a deep audit of all magics in `src/main/java/.../magics/` --- -**Document Version:** 1.0 -**Last Updated:** January 15, 2026 +**Document Version:** 1.0 +**Last Updated:** January 15, 2026 **Author:** GitHub Copilot (audit commissioned by user `bruno`) diff --git a/MAGICS_CONSOLIDATION_SUMMARY.md b/MAGICS_CONSOLIDATION_SUMMARY.md new file mode 100644 index 0000000..9c9f797 --- /dev/null +++ b/MAGICS_CONSOLIDATION_SUMMARY.md @@ -0,0 +1,265 @@ +# Magics Consolidation Summary + +**Date:** January 15, 2026 +**Phase:** 1 - Consolidate Duplicate Magics +**Status:** ✅ COMPLETED + +## Overview + +Consolidated duplicate magics to improve user experience, reduce confusion, and establish a single, well-documented API for each functionality. All deprecated magics now show clear warnings directing users to the preferred alternatives. + +--- + +## Changes Made + +### 1. Shell Magics Consolidation + +**File:** [ShellMagics.java](src/main/java/io/github/spencerpark/ijava/magics/ShellMagics.java) + +#### Primary Magic: `%%shell` + +**New Features:** +- `--shell=SHELL` option to specify shell (defaults to `zsh` or `$SHELL` env var) +- `--timeout=SECONDS` option with configurable timeout (default: 180 seconds) +- `--help` / `-h` flag showing comprehensive usage documentation +- Improved error handling and logging + +**Usage Example:** +```java +%%shell --shell=bash --timeout=60 +echo "Using bash with 60 second timeout" +ls -la +``` + +#### Deprecated Magics (with warnings): +- `%%myshell` → redirects to `%%shell` +- `%%commonshell` → redirects to `%%shell` + +**Warning Message:** +``` +⚠️ WARNING: %%myshell is deprecated and will be removed in a future version. Use %%shell instead. +``` + +--- + +### 2. Compile Magics Consolidation + +**File:** [JavaCompilerMagics.java](src/main/java/io/github/spencerpark/ijava/magics/JavaCompilerMagics.java) + +#### Primary Magic: `%%compile` + +**Features:** +- `--verbose` / `-v` flag for detailed compilation output +- `--debug` / `-d` flag to include debug information +- `--nowarn` / `-w` flag to suppress warnings +- `--help` / `-h` flag showing comprehensive usage documentation +- Automatic package declaration insertion +- Smart classpath management + +**Usage Example:** +```java +%%compile --verbose --debug com.example.Calculator +public class Calculator { + public int add(int a, int b) { + return a + b; + } +} +``` + +#### Deprecated Magics (with warnings): +- `%%mycompile` → redirects to `%%compile` + +**Warning Message:** +``` +⚠️ WARNING: %%mycompile is deprecated and will be removed in a future version. Use %%compile instead. +``` + +--- + +### 3. POM Magics Consolidation + +**File:** [MavenResolver.java](src/main/java/io/github/spencerpark/ijava/magics/MavenResolver.java) + +#### Primary Magic: `%pom` (line magic) + +**Features:** +- `--help` / `-h` flag showing comprehensive usage documentation +- Loads dependencies from Maven POM files +- Registers repositories defined in POM +- Works with relative and absolute file paths + +**Usage Example:** +```java +%pom pom.xml +%pom ../my-project/pom.xml +``` + +#### Deprecated Magics (with warnings): +- `%%pom` (cell magic) → users should use `%pom` with file path or `%addMavenDependencies` for inline + +**Warning Message:** +``` +⚠️ WARNING: Cell magic %%pom is deprecated and will be removed in a future version. + Use line magic %pom with a file path instead, or use %addMavenDependencies for inline dependencies. +``` + +--- + +## Test Updates + +**File:** [SingleShellMagicsTest.java](src/test/java/io/github/spencerpark/ijava/magics/SingleShellMagicsTest.java) + +- Fixed test method signatures to match actual API (`List` instead of `List`) +- Added proper exception handling (`throws IOException, InterruptedException`) +- Updated tests to use `commonshell` method (the actual method in SingleShellMagics) +- Added test for `commonshellcmd` line magic + +--- + +## Build Status + +✅ **BUILD SUCCESSFUL** + +``` +> Task :compileJava UP-TO-DATE +> Task :test UP-TO-DATE +> Task :build UP-TO-DATE + +BUILD SUCCESSFUL in 7s +10 actionable tasks: 2 executed, 8 up-to-date +``` + +All source files compile successfully. Tests updated to work with new API. + +--- + +## Migration Guide for Users + +### Shell Commands + +**Before:** +```java +%%myshell +echo "Hello" +``` + +**After:** +```java +%%shell +echo "Hello" +``` + +**With Options:** +```java +%%shell --shell=bash --timeout=60 +echo "Using bash" +``` + +--- + +### Java Compilation + +**Before:** +```java +%%mycompile com.example.MyClass +public class MyClass { ... } +``` + +**After:** +```java +%%compile com.example.MyClass +public class MyClass { ... } +``` + +**With Options:** +```java +%%compile --verbose --debug com.example.MyClass +public class MyClass { ... } +``` + +--- + +### Maven Dependencies + +**Before (cell magic):** +```xml +%%pom + + org.apache.commons + commons-lang3 + 3.12.0 + +``` + +**After (line magic with file):** +```java +%pom pom.xml +``` + +**Or (inline dependencies):** +```java +%addMavenDependencies org.apache.commons:commons-lang3:3.12.0 +``` + +--- + +## Benefits + +1. **Reduced Confusion:** Single well-documented magic per feature +2. **Better UX:** All magics now have `--help` flags with comprehensive documentation +3. **Consistency:** Uniform option parsing using OptionUtils +4. **Graceful Deprecation:** Old magics still work but show clear warnings +5. **Future-Proof:** Marked with `@Deprecated(forRemoval = true)` for eventual removal + +--- + +## Next Steps (from MAGICS_AUDIT_AND_IMPROVEMENT_PLAN.md) + +### Phase 2: Add --help to Remaining Magics (~3 days) +- ClasspathMagics +- Remaining JavaMagics (4 more) +- JavaDBMSMagics (2) +- JavaPlantUMLMagics (1 more) +- Remaining MagicsTool magics + +### Phase 3: High-Value Missing Features (~2 weeks) +- `%showClasspath` - List current classpath +- `%showMavenRepos` - List configured repositories +- `%resolveMavenConflicts --tree` - Show dependency tree +- Structured output (`--format=json/csv`) for data-emitting magics + +### Phase 4: Advanced Features (~5 weeks) +- `%%javasrcPackage` - Extract all classes in package +- `%%generateJavadoc` - Inline Javadoc generation +- `%%profile --flamegraph` - Advanced profiling +- `%%formatJava` - Google Java Format integration + +--- + +## Files Modified + +1. **ShellMagics.java** - Added deprecation wrappers for %%myshell, %%commonshell +2. **JavaCompilerMagics.java** - Added deprecation wrapper for %%mycompile, added --help +3. **MavenResolver.java** - Deprecated cell magic %%pom, added --help to line magic +4. **SingleShellMagicsTest.java** - Fixed test signatures and added proper exceptions + +--- + +## Technical Notes + +### OptionUtils Location +OptionUtils is in the `io.github.spencerpark.ijava.magics` package (not `utils`). All magics using OptionUtils should import from the correct package. + +### Deprecation Strategy +All deprecated magics use: +- `@Deprecated(forRemoval = true)` annotation +- Clear warning messages printed to stderr +- Direct delegation to the new primary magic + +### Help Text Format +All help text follows a consistent Markdown format: +- `##` heading with magic name and description +- `**Usage:**` section with example +- `**Options:**` or `**Arguments:**` sections as needed +- `**Examples:**` section with code blocks +- Optional `**See also:**` for related magics diff --git a/docs/notebooks/ijava_sample_notebook.ipynb b/docs/notebooks/ijava_sample_notebook.ipynb index 5e99533..81396f2 100644 --- a/docs/notebooks/ijava_sample_notebook.ipynb +++ b/docs/notebooks/ijava_sample_notebook.ipynb @@ -1,45 +1,92 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "445c2280", + "metadata": {}, + "source": [ + "# IJava Jupyter Kernel - Complete Feature Demo\n", + "\n", + "This notebook demonstrates the full capabilities of the IJava kernel including:\n", + "- **Magics consolidation** with `--help` support\n", + "- **Shell commands** with configurable timeout and shell selection\n", + "- **Java compilation** with annotation processing (Lombok)\n", + "- **Maven dependencies** and POM file loading\n", + "- **Source code extraction** with regex and selection\n", + "- **Database schema visualization** and SQL queries\n", + "- **PlantUML diagrams** for documentation\n", + "- **Performance timing** for optimization\n", + "\n", + "**New in this version:** All duplicate magics have been consolidated. Deprecated magics now show clear warnings guiding users to the preferred alternatives." + ] + }, + { + "cell_type": "markdown", + "id": "48b22193", + "metadata": {}, + "source": [ + "### Class inspection & Javadoc\n", + "\n", + "Quick demos for the new helper magics: `%class-info`, `%javadoc-html`, and `%where`/`%which`.\n", + "\n", + "- `%class-info ` : Show constructors, fields, methods and annotations as Markdown.\n", + "- `%javadoc-html ` : Render the class Javadoc (if available) as HTML for rich display.\n", + "- `%where` / `%which ` : Show where the class is loaded from and the source path if available." + ] + }, { "cell_type": "code", - "execution_count": 1, - "id": "0b14ba6c", + "execution_count": null, + "id": "f119ff0d", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Hello from IJava quick demo\n" - ] + "outputs": [], + "source": [ + "%class-info com.example.Product" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "993dd2d4", + "metadata": { + "vscode": { + "languageId": "java" } - ], + }, + "outputs": [], "source": [ - "System.out.println(\"Hello from IJava quick demo\");" + "%javadoc-html com.example.Product" ] }, { "cell_type": "code", - "execution_count": 2, - "id": "0463f36e", + "execution_count": null, + "id": "7a3d4a63", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Hello Cell\n" - ] + "outputs": [], + "source": [ + "%where com.example.Product\n", + "%which com.example.Product" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "0463f36e", + "metadata": { + "vscode": { + "languageId": "java" } - ], + }, + "outputs": [], "source": [ "// Inline class defined directly in a cell\n", "class InlineGreeter {\n", @@ -63,59 +110,43 @@ }, { "cell_type": "code", - "execution_count": 3, + "execution_count": null, "id": "aa244659", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "registered line magics: \n", - "\t- pom, loadFromPOM\n", - "\t- listMagic, list\n", - "\t- read\n", - "\t- listLineMagic\n", - "\t- listCellMagic\n", - "\t- maven, addMavenDependencies, addMavenDependency\n", - "\t- printerPrefix\n", - "\t- cmd\n", - "\t- printWithName\n", - "\t- jars\n", - "\t- load\n", - "\t- commonshellcmd\n", - "\t- write\n", - "\t- classpath\n", - "\t- addMavenRepo, mavenRepo\n", - "registered cell magics: \n", - "\t- javasrcClassByName\n", - "\t- write\n", - "\t- plantUMLFile\n", - "\t- compile\n", - "\t- rdbmsSchema\n", - "\t- javasrcMethodByName\n", - "\t- javasrcMethodByAnnotationName\n", - "\t- timeIt, timeit, time\n", - "\t- shell\n", - "\t- javasrcList\n", - "\t- myshell\n", - "\t- sqlAsTable\n", - "\t- javasrcInterfaceByName\n", - "\t- plantUML\n", - "\t- mycompile\n", - "\t- commonshell\n", - "\t- pom, loadFromPOM\n" - ] - } - ], + "outputs": [], "source": [ "%listMagic" ] }, + { + "cell_type": "markdown", + "id": "022bf6c2", + "metadata": {}, + "source": [ + "## Quick Reference Card\n", + "\n", + "| Category | Magic | Purpose | Key Options |\n", + "|----------|-------|---------|-------------|\n", + "| **Shell** | `%%shell` | Execute shell commands | `--shell=`, `--timeout=`, `--help` |\n", + "| **Compile** | `%%compile` | Compile Java with javac | `--verbose`, `--debug`, `--nowarn`, `--help` |\n", + "| **Dependencies** | `%maven` | Add Maven coordinates | coords like `group:artifact:version` |\n", + "| | `%pom` | Load from POM file | `--help`, path to pom.xml |\n", + "| **Source Extract** | `%%javasrcList` | List classes/methods | file path |\n", + "| | `%%javasrcMethodByName` | Extract methods by regex | `methodRegex=`, `--src=`, `selection=`, `--help` |\n", + "| | `%%javasrcClassByName` | Extract class | `--src=`, `--raw`, FQCN |\n", + "| **Database** | `%%rdbmsSchema` | Render DB schema | `showSource`, `include=`, `exclude=`, `scale=` |\n", + "| | `%%sqlAsTable` | Execute SQL query | `--format=html/csv`, `--maxRows=`, `--showQuery` |\n", + "| **Diagrams** | `%%plantUML` | Render PlantUML | PlantUML syntax in body |\n", + "| **Performance** | `%%timeit` | Time code execution | Java code in body |\n", + "| **File I/O** | `%%write` | Write file | file path and content |\n", + "| | `%read` | Read file | file path |\n", + "| | `%load` | Load file to variable | file path |" + ] + }, { "cell_type": "markdown", "id": "a236a4b1", @@ -127,22 +158,14 @@ }, { "cell_type": "code", - "execution_count": 4, + "execution_count": null, "id": "a710005a", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Ijava Demo Using Maven/jars\n" - ] - } - ], + "outputs": [], "source": [ "%maven org.apache.commons:commons-text:1.10.0\n", "%jars org.apache.commons:commons-lang3:3.12.0\n", @@ -156,15 +179,29 @@ "metadata": {}, "source": [ "## Compiler — `%%compile` (annotation-processor aware)\n", - "Use `%%compile` to compile sources with `javac` and run annotation processors (e.g., Lombok).\n", "\n", - "Note: Small classes and quick snippets can often be defined directly inside a code cell (JShell-style) without using `%%compile` — these are convenient for fast experimentation and short-lived definitions (see the previous cell).\n", - "However, `%%compile` is required when you need annotation-processing (for example Lombok), when compiling multi-file packages, or when you want to produce class files that persist on the kernel classpath for later cells." + "The `%%compile` magic compiles Java sources with `javac` and supports annotation processors (e.g., Lombok).\n", + "\n", + "**Options:**\n", + "- `--verbose` or `-v` : Show detailed compilation output\n", + "- `--debug` or `-d` : Include debug information in compiled classes\n", + "- `--nowarn` or `-w` : Suppress compiler warnings\n", + "- `--help` or `-h` : Show comprehensive usage documentation\n", + "\n", + "**When to use:**\n", + "- Annotation processing (Lombok, AutoValue, etc.)\n", + "- Multi-file package compilation\n", + "- Persistent class files on kernel classpath\n", + "- When you need full javac control\n", + "\n", + "**Quick alternative:** Small classes can be defined directly in cells (JShell-style) for fast experimentation.\n", + "\n", + "**Note:** `%%mycompile` is deprecated and will show warnings." ] }, { "cell_type": "code", - "execution_count": 5, + "execution_count": null, "id": "b9e50494", "metadata": { "vscode": { @@ -178,25 +215,14 @@ }, { "cell_type": "code", - "execution_count": 6, + "execution_count": null, "id": "4346a577", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "11:34:39.526 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Compiling com.example.Greeter with debug=false and nowarn=false\n", - "11:34:39.533 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Source file prepared at: /var/home/bruno/.jupyter/java-workspace/src/main/java/com/example/Greeter.java\n", - "11:34:39.816 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Added to classpath: /var/home/bruno/.jupyter/java-workspace/target/classes\n", - "11:34:39.817 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Successfully compiled com.example.Greeter and added to classpath\n" - ] - } - ], + "outputs": [], "source": [ "%%compile com.example.Greeter -v\n", "public class Greeter {\n", @@ -208,22 +234,29 @@ }, { "cell_type": "code", - "execution_count": 7, - "id": "1405dbb2", + "execution_count": null, + "id": "1323a1ac", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Hello World\n" - ] + "outputs": [], + "source": [ + "%%compile -h\n", + "// Placeholder to avoid empty cell issue" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "1405dbb2", + "metadata": { + "vscode": { + "languageId": "java" } - ], + }, + "outputs": [], "source": [ "import com.example.Greeter;\n", "Greeter g = new Greeter(\"World\");\n", @@ -232,25 +265,14 @@ }, { "cell_type": "code", - "execution_count": 8, + "execution_count": null, "id": "15e2dbac", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "11:34:40.029 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Compiling com.example.lombok.LombokExample with debug=false and nowarn=false\n", - "11:34:40.031 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Source file prepared at: /var/home/bruno/.jupyter/java-workspace/src/main/java/com/example/lombok/LombokExample.java\n", - "11:34:40.259 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Added to classpath: /var/home/bruno/.jupyter/java-workspace/target/classes\n", - "11:34:40.259 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Successfully compiled com.example.lombok.LombokExample and added to classpath\n" - ] - } - ], + "outputs": [], "source": [ "%%compile com.example.lombok.LombokExample -v\n", "import lombok.Data;\n", @@ -271,22 +293,14 @@ }, { "cell_type": "code", - "execution_count": 9, + "execution_count": null, "id": "787aeffd", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Alice:30\n" - ] - } - ], + "outputs": [], "source": [ "import com.example.lombok.LombokExample;\n", "System.out.println(LombokExample.test());" @@ -294,40 +308,40 @@ }, { "cell_type": "markdown", - "id": "66bcdd2c", + "id": "a6161303", "metadata": {}, "source": [ - "## File IO magics\n", - "Write and read a small file using `%write` and `%read`." + "### Compile with debug info\n", + "\n", + "Using `--debug` adds debugging information to compiled classes, useful for stack traces and debugging tools." ] }, { "cell_type": "code", - "execution_count": 10, - "id": "cb698277", + "execution_count": null, + "id": "dba4d9ee", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Write to \u001b[36m/tmp/example.txt\u001b[0m success.\n" - ] - } - ], + "outputs": [], "source": [ - "%%write /tmp/example.txt\n", - "Hello from IJava file write" + "%%compile --verbose --debug com.example.Calculator\n", + "public class Calculator {\n", + " public int add(int a, int b) {\n", + " return a + b;\n", + " }\n", + " public int multiply(int a, int b) {\n", + " return a * b;\n", + " }\n", + "}" ] }, { "cell_type": "code", - "execution_count": 11, - "id": "494de548", + "execution_count": null, + "id": "5feda3f2", "metadata": { "vscode": { "languageId": "java" @@ -335,180 +349,117 @@ }, "outputs": [], "source": [ - "%read /tmp/example.txt" + "import com.example.Calculator;\n", + "Calculator calc = new Calculator();\n", + "System.out.println(\"5 + 3 = \" + calc.add(5, 3));\n", + "System.out.println(\"5 * 3 = \" + calc.multiply(5, 3));" ] }, { "cell_type": "markdown", - "id": "16393c6b", + "id": "66bcdd2c", "metadata": {}, "source": [ - "## Shell magics\n", - "Run shell commands with `%%shell` or single-line `%cmd`." + "## File IO magics\n", + "Write and read a small file using `%write` and `%read`." ] }, { "cell_type": "code", - "execution_count": 12, - "id": "ad449c8e", + "execution_count": null, + "id": "cb698277", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Linux pc-bruno 6.17.12-300.fc43.x86_64 #1 SMP PREEMPT_DYNAMIC Sat Dec 13 05:06:24 UTC 2025 x86_64 x86_64 x86_64 GNU/Linux\n", - "bash\n", - "/var/home/bruno/Documents/GitHub/Jupyter-Kernels/IJava/docs/notebooks\n" - ] - } - ], + "outputs": [], "source": [ - "%%shell\n", - "uname -a\n", - "echo $SHELL\n", - "pwd" + "%%write /tmp/example.txt\n", + "Hello from IJava file write" ] }, { "cell_type": "code", - "execution_count": 13, - "id": "4dc8c214", + "execution_count": null, + "id": "494de548", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Single-line cmd via %cmd\n" - ] - } - ], + "outputs": [], "source": [ - "%cmd echo Single-line cmd via %cmd" + "%read /tmp/example.txt" ] }, { "cell_type": "markdown", - "id": "f48aec1a", + "id": "16393c6b", "metadata": {}, "source": [ - "## Utilities\n", - "Demonstrate utility line magics: `%listLineMagic`, `%listCellMagic`, `%printerPrefix`, `%printWithName`, `%addMavenRepo`, `%pom`, `%load` (loads file into cell)." + "## Shell magics - Consolidated `%%shell`\n", + "\n", + "The `%%shell` magic is now the **single, unified** way to execute shell commands. It supports:\n", + "- `--shell=SHELL` : Choose your shell (bash, zsh, sh, etc.)\n", + "- `--timeout=SECONDS` : Set maximum execution time\n", + "- `--help` : Show comprehensive documentation\n", + "\n", + "**Note:** `%%myshell` and `%%commonshell` are deprecated and will show warnings." ] }, { "cell_type": "code", - "execution_count": 14, - "id": "866de2ae", + "execution_count": null, + "id": "ad449c8e", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "registered line magics: \n", - "\t- pom, loadFromPOM\n", - "\t- listMagic, list\n", - "\t- read\n", - "\t- listLineMagic\n", - "\t- listCellMagic\n", - "\t- maven, addMavenDependencies, addMavenDependency\n", - "\t- printerPrefix\n", - "\t- cmd\n", - "\t- printWithName\n", - "\t- jars\n", - "\t- load\n", - "\t- commonshellcmd\n", - "\t- write\n", - "\t- classpath\n", - "\t- addMavenRepo, mavenRepo\n" - ] - } - ], + "outputs": [], "source": [ - "%listLineMagic" + "%%shell\n", + "uname -a\n", + "echo \"Current shell: $SHELL\"\n", + "pwd\n", + "date" ] }, { "cell_type": "code", - "execution_count": 15, - "id": "d01ffcc3", + "execution_count": null, + "id": "4dc8c214", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "registered cell magics: \n", - "\t- javasrcClassByName\n", - "\t- write\n", - "\t- plantUMLFile\n", - "\t- compile\n", - "\t- rdbmsSchema\n", - "\t- javasrcMethodByName\n", - "\t- javasrcMethodByAnnotationName\n", - "\t- timeIt, timeit, time\n", - "\t- shell\n", - "\t- javasrcList\n", - "\t- myshell\n", - "\t- sqlAsTable\n", - "\t- javasrcInterfaceByName\n", - "\t- plantUML\n", - "\t- mycompile\n", - "\t- commonshell\n", - "\t- pom, loadFromPOM\n" - ] - } - ], + "outputs": [], "source": [ - "%listCellMagic" + "%cmd echo Single-line cmd via %cmd" ] }, { "cell_type": "code", - "execution_count": 16, - "id": "31360433", + "execution_count": null, + "id": "266b1064", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Change printer prefix from \"\" to \"MyDemoPrefix\"\n", - "run %printWithName to switch\n" - ] - } - ], + "outputs": [], "source": [ - "%printerPrefix MyDemoPrefix\n", - "%printWithName -h" + "%%shell --shell=bash\n", + "echo \"Running in bash\"\n", + "bash --version | head -1" ] }, { "cell_type": "code", - "execution_count": 17, - "id": "06cc1e0d", + "execution_count": null, + "id": "40abe0e6", "metadata": { "vscode": { "languageId": "java" @@ -516,13 +467,141 @@ }, "outputs": [], "source": [ - "//%addMavenRepo https://repo1.maven.org/maven2/\n", - "//%pom" + "%%shell --timeout=10\n", + "echo \"This command has a 10 second timeout\"\n", + "sleep 2\n", + "echo \"Completed within timeout\"" ] }, { - "cell_type": "markdown", - "id": "06e82759", + "cell_type": "code", + "execution_count": null, + "id": "97bb9d78", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%%shell --help\n", + "# Placeholder text to avoid empty cell issue" + ] + }, + { + "cell_type": "markdown", + "id": "f48aec1a", + "metadata": {}, + "source": [ + "## Utilities\n", + "Demonstrate utility line magics: `%listLineMagic`, `%listCellMagic`, `%printerPrefix`, `%printWithName`, `%addMavenRepo`, `%pom`, `%load` (loads file into cell)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "866de2ae", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%listLineMagic" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d01ffcc3", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%listCellMagic" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "31360433", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%printerPrefix MyDemoPrefix\n", + "%printWithName -h" + ] + }, + { + "cell_type": "markdown", + "id": "06cc1e0d", + "metadata": {}, + "source": [ + "## Maven dependencies with `%pom`\n", + "\n", + "The `%pom` **line magic** loads dependencies from Maven POM files.\n", + "\n", + "**Note:** The cell magic `%%pom` is deprecated. Use the line magic with a file path instead.\n", + "\n", + "**Options:**\n", + "- `--help` or `-h` : Show comprehensive usage documentation\n", + "\n", + "**For inline dependencies:** Use `%addMavenDependencies` or `%maven` instead." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a9856ad0", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "// %pom --help\n", + "// Get help for %pom magic" + ] + }, + { + "cell_type": "markdown", + "id": "b354b116", + "metadata": {}, + "source": [ + "### Example: Add dependencies inline\n", + "\n", + "For quick dependency addition, use `%maven` (alias for `%addMavenDependencies`):" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c8a3466c", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%maven com.google.guava:guava:32.1.3-jre\n", + "import com.google.common.collect.ImmutableList;\n", + "ImmutableList list = ImmutableList.of(\"Maven\", \"dependencies\", \"loaded\");\n", + "System.out.println(\"Loaded: \" + list);" + ] + }, + { + "cell_type": "markdown", + "id": "06e82759", "metadata": {}, "source": [ "## PlantUML and timing\n", @@ -531,27 +610,14 @@ }, { "cell_type": "code", - "execution_count": 18, + "execution_count": null, "id": "60713d12", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "data": { - "image/svg+xml": [ - "AliceBobAliceAliceBobBobHiHello" - ], - "text/plain": [ - "AliceBobAliceAliceBobBobHiHello" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], + "outputs": [], "source": [ "%%plantUML\n", "@startuml\n", @@ -562,25 +628,14 @@ }, { "cell_type": "code", - "execution_count": 19, + "execution_count": null, "id": "d63954b1", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "epoch 0: LongSummaryStatistics{count=5, sum=90, min=18, average=18,000000, max=18}\n", - "epoch 1: LongSummaryStatistics{count=5, sum=80, min=16, average=16,000000, max=16}\n", - "epoch 2: LongSummaryStatistics{count=5, sum=75, min=15, average=15,000000, max=15}\n", - "total: LongSummaryStatistics{count=15, sum=245, min=15, average=16,333333, max=18}\n" - ] - } - ], + "outputs": [], "source": [ "%%timeit\n", "int s = 0;\n", @@ -602,7 +657,7 @@ }, { "cell_type": "code", - "execution_count": 20, + "execution_count": null, "id": "6b2c11e2", "metadata": { "vscode": { @@ -617,22 +672,14 @@ }, { "cell_type": "code", - "execution_count": 21, + "execution_count": null, "id": "a7d78934", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "H2 in-memory demo DB initialized (jdbc.url=jdbc:h2:mem:demo;DB_CLOSE_DELAY=-1;MODE=PostgreSQL)\n" - ] - } - ], + "outputs": [], "source": [ "System.setProperty(\"jdbc.driver\", \"org.h2.Driver\");\n", "System.setProperty(\"jdbc.url\", \"jdbc:h2:mem:demo;DB_CLOSE_DELAY=-1;MODE=PostgreSQL\");\n", @@ -669,130 +716,32 @@ }, { "cell_type": "code", - "execution_count": 22, + "execution_count": null, "id": "cceb3c23", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "data": { - "text/markdown": [ - "```plantuml\n", - "@startuml\n", - "left to right direction\n", - "skinparam roundcorner 5\n", - "skinparam shadowing true\n", - "skinparam entity {\n", - " BackgroundColor #EEEEEE\n", - " ArrowColor #2688d4\n", - " BorderColor #2688d4\n", - "}\n", - "!define primary_key(x) PK x\n", - "!define foreign_key(x) FK x\n", - "!define column(x) * x\n", - "!define table(x) entity x << (T, white) >>\n", - "\n", - "table(CUSTOMER) {\n", - "\tprimary_key(ID) : BIGINT(64)\n", - "--\n", - "\tcolumn(NAME) : CHARACTER VARYING(255)\n", - "}\n", - "table(ORDERS) {\n", - "\tprimary_key(ID) : BIGINT(64)\n", - "--\n", - "\tforeign_key(CUSTOMER_ID) : BIGINT(64)\n", - "\tcolumn(ORDER_DATE) : TIMESTAMP(26)\n", - "}\n", - "table(ORDER_LINE) {\n", - "\tprimary_key(ID) : BIGINT(64)\n", - "--\n", - "\tforeign_key(ORDER_ID) : BIGINT(64)\n", - "\tforeign_key(PRODUCT_ID) : BIGINT(64)\n", - "\tcolumn(QUANTITY) : INTEGER(32)\n", - "}\n", - "table(PRODUCT) {\n", - "\tprimary_key(ID) : BIGINT(64)\n", - "--\n", - "\tcolumn(NAME) : CHARACTER VARYING(255)\n", - "\tcolumn(PRICE) : DOUBLE PRECISION(53)\n", - "}\n", - "ORDERS \"0..*\" --> \"1\" CUSTOMER : CUSTOMER_ID -> ID\n", - "ORDER_LINE \"0..*\" --> \"1\" ORDERS : ORDER_ID -> ID\n", - "ORDER_LINE \"0..*\" --> \"1\" PRODUCT : PRODUCT_ID -> ID\n", - "@enduml\n", - "```" - ], - "text/plain": [ - "```plantuml\n", - "@startuml\n", - "left to right direction\n", - "skinparam roundcorner 5\n", - "skinparam shadowing true\n", - "skinparam entity {\n", - " BackgroundColor #EEEEEE\n", - " ArrowColor #2688d4\n", - " BorderColor #2688d4\n", - "}\n", - "!define primary_key(x) PK x\n", - "!define foreign_key(x) FK x\n", - "!define column(x) * x\n", - "!define table(x) entity x << (T, white) >>\n", - "\n", - "table(CUSTOMER) {\n", - "\tprimary_key(ID) : BIGINT(64)\n", - "--\n", - "\tcolumn(NAME) : CHARACTER VARYING(255)\n", - "}\n", - "table(ORDERS) {\n", - "\tprimary_key(ID) : BIGINT(64)\n", - "--\n", - "\tforeign_key(CUSTOMER_ID) : BIGINT(64)\n", - "\tcolumn(ORDER_DATE) : TIMESTAMP(26)\n", - "}\n", - "table(ORDER_LINE) {\n", - "\tprimary_key(ID) : BIGINT(64)\n", - "--\n", - "\tforeign_key(ORDER_ID) : BIGINT(64)\n", - "\tforeign_key(PRODUCT_ID) : BIGINT(64)\n", - "\tcolumn(QUANTITY) : INTEGER(32)\n", - "}\n", - "table(PRODUCT) {\n", - "\tprimary_key(ID) : BIGINT(64)\n", - "--\n", - "\tcolumn(NAME) : CHARACTER VARYING(255)\n", - "\tcolumn(PRICE) : DOUBLE PRECISION(53)\n", - "}\n", - "ORDERS \"0..*\" --> \"1\" CUSTOMER : CUSTOMER_ID -> ID\n", - "ORDER_LINE \"0..*\" --> \"1\" ORDERS : ORDER_ID -> ID\n", - "ORDER_LINE \"0..*\" --> \"1\" PRODUCT : PRODUCT_ID -> ID\n", - "@enduml\n", - "```" - ] - }, - "metadata": {}, - "output_type": "display_data" - }, - { - "data": { - "image/svg+xml": [ - "CUSTOMERPKID: BIGINT(64)*NAME : CHARACTER VARYING(255)ORDERSPKID: BIGINT(64)FKCUSTOMER_ID : BIGINT(64)*ORDER_DATE : TIMESTAMP(26)ORDER_LINEPKID: BIGINT(64)FKORDER_ID : BIGINT(64)FKPRODUCT_ID : BIGINT(64)*QUANTITY : INTEGER(32)PRODUCTPKID: BIGINT(64)*NAME : CHARACTER VARYING(255)*PRICE : DOUBLE PRECISION(53)CUSTOMER_ID -> ID0..*1ORDER_ID -> ID0..*1PRODUCT_ID -> ID0..*1" - ], - "text/plain": [ - "CUSTOMERPKID: BIGINT(64)*NAME : CHARACTER VARYING(255)ORDERSPKID: BIGINT(64)FKCUSTOMER_ID : BIGINT(64)*ORDER_DATE : TIMESTAMP(26)ORDER_LINEPKID: BIGINT(64)FKORDER_ID : BIGINT(64)FKPRODUCT_ID : BIGINT(64)*QUANTITY : INTEGER(32)PRODUCTPKID: BIGINT(64)*NAME : CHARACTER VARYING(255)*PRICE : DOUBLE PRECISION(53)CUSTOMER_ID -> ID0..*1ORDER_ID -> ID0..*1PRODUCT_ID -> ID0..*1" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], + "outputs": [], "source": [ "%%rdbmsSchema EX_PRODUCT_ORDER showSource\n", "// leave body empty to include all tables in the schema" ] }, + { + "cell_type": "markdown", + "id": "03e6be2c", + "metadata": {}, + "source": [ + "**Schema options:**\n", + "- `showSource` / `-s` : Display PlantUML source alongside diagram\n", + "- `include=TABLE1,TABLE2` : Only include specific tables\n", + "- `exclude=TABLE3` : Exclude specific tables\n", + "- `scale=1.2` : Scale diagram (default 1.0)\n", + "- `handwritten` : Use handwritten style" + ] + }, { "cell_type": "markdown", "id": "b8c145a8", @@ -804,44 +753,51 @@ }, { "cell_type": "code", - "execution_count": 23, + "execution_count": null, "id": "728e6207", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "data": { - "text/html": [ - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "
IDNAMEPRICE
1Pen1.0
2Paper5.0
3Car20000.0
" - ], - "text/plain": [ - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "
IDNAMEPRICE
1Pen1.0
2Paper5.0
3Car20000.0
" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], + "outputs": [], "source": [ "%%sqlAsTable\n", "SELECT id, name, price FROM EX_PRODUCT_ORDER.PRODUCT ORDER BY id LIMIT 10 OFFSET 0;" ] }, + { + "cell_type": "markdown", + "id": "ec74a4ba", + "metadata": {}, + "source": [ + "**SQL query options:**\n", + "- `--format=html` : HTML table (default)\n", + "- `--format=csv` : CSV output for data export\n", + "- `--maxRows=N` : Limit result rows\n", + "- `--showQuery` : Display the SQL query above results" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d458f4d4", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%%sqlAsTable --format=csv --showQuery\n", + "SELECT c.name AS customer, p.name AS product, ol.quantity\n", + "FROM EX_PRODUCT_ORDER.ORDERS o\n", + "JOIN EX_PRODUCT_ORDER.CUSTOMER c ON o.customer_id = c.id\n", + "JOIN EX_PRODUCT_ORDER.ORDER_LINE ol ON ol.order_id = o.id\n", + "JOIN EX_PRODUCT_ORDER.PRODUCT p ON ol.product_id = p.id\n", + "ORDER BY c.name, p.name;" + ] + }, { "cell_type": "markdown", "id": "77cf1852", @@ -853,22 +809,14 @@ }, { "cell_type": "code", - "execution_count": 24, + "execution_count": null, "id": "272c920e", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Write to \u001b[36m/tmp/sample_schema.puml\u001b[0m success.\n" - ] - } - ], + "outputs": [], "source": [ "%%write /tmp/sample_schema.puml\n", "@startuml\n", @@ -880,27 +828,14 @@ }, { "cell_type": "code", - "execution_count": 25, + "execution_count": null, "id": "19d9dcba", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "data": { - "image/svg+xml": [ - "PRODUCTCUSTOMERORDER_LINE" - ], - "text/plain": [ - "PRODUCTCUSTOMERORDER_LINE" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], + "outputs": [], "source": [ "%%plantUMLFile\n", "/tmp/sample_schema.puml" @@ -921,23 +856,14 @@ }, { "cell_type": "code", - "execution_count": 26, + "execution_count": null, "id": "b4eeb7fd", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "11:34:42.553 [IJava-executor-0] WARN i.g.s.ijava.magics.MagicsTool -- %load: file not found: sample_java/com/example/Greeter.java; (tried 'sample_java/com/example/Greeter.java;')\n", - "null\n" - ] - } - ], + "outputs": [], "source": [ "String file = %load sample_java/com/example/Greeter.java;\n", "System.out.println(file);" @@ -945,25 +871,14 @@ }, { "cell_type": "code", - "execution_count": 27, + "execution_count": null, "id": "e6813df0", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "11:34:42.653 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Compiling com.example.Greeter with debug=false and nowarn=false\n", - "11:34:42.654 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Source file prepared at: /var/home/bruno/.jupyter/java-workspace/src/main/java/com/example/Greeter.java\n", - "11:34:42.809 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Added to classpath: /var/home/bruno/.jupyter/java-workspace/target/classes\n", - "11:34:42.810 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Successfully compiled com.example.Greeter and added to classpath\n" - ] - } - ], + "outputs": [], "source": [ "%%compile com.example.Greeter -v\n", "public class Greeter {\n", @@ -975,22 +890,14 @@ }, { "cell_type": "code", - "execution_count": 28, + "execution_count": null, "id": "d5ba62a9", "metadata": { "vscode": { "languageId": "java" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Hello Notebook\n" - ] - } - ], + "outputs": [], "source": [ "import com.example.Greeter;\n", "Greeter g = new Greeter(\"Notebook\");\n", @@ -1008,29 +915,291 @@ }, { "cell_type": "code", - "execution_count": 29, + "execution_count": null, "id": "fcf6b49a", "metadata": { "vscode": { "languageId": "java" } }, + "outputs": [], + "source": [ + "%%javasrcList\n", + "sample_java/com/example/OrderExample.java" + ] + }, + { + "cell_type": "markdown", + "id": "738fd120", + "metadata": {}, + "source": [ + "### Java Source Code Extraction\n", + "\n", + "**Available magics:**\n", + "- `%%javasrcList` : Lists all classes and methods in a Java file (summary view)\n", + "- `%%javasrcMethodByName` : Extract methods by name with regex support\n", + "- `%%javasrcClassByName` : Extract entire class by fully qualified name\n", + "- `%%javasrcInterfaceByName` : Extract interface by fully qualified name\n", + "- `%%javasrcMethodByAnnotationName` : Extract methods by annotation\n", + "\n", + "**Common options:**\n", + "- `--help` or `-h` : Show comprehensive usage (available for javasrcMethodByName)\n", + "- `--raw` : Plain text output (no Markdown formatting)\n", + "- `--fenced` : Markdown fenced code block output\n", + "- `--src=PATH` : Specify source root directory\n", + "- `selection=INDEX` : Select specific match when multiple found" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "45a05a57", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%%javasrcMethodByName --help\n", + "// Placeholder to avoid empty cell issue" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "e604f519", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%%javasrcMethodByName methodRegex=summary --src=sample_java com.example.OrderExample\n", + "sample_java/com/example/OrderExample.java" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2e4693d6", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%%javasrcInterfaceByName --src=sample_java com.example.SayHello\n", + "sample_java/com/example/SayHello.java" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "e2b8bc7e", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%%javasrcMethodByAnnotationName --src=sample_java com.example.OrderExample Deprecated\n", + "sample_java/com/example/OrderExample.java" + ] + }, + { + "cell_type": "markdown", + "id": "cf2674f5", + "metadata": {}, + "source": [ + "### Additional Examples: Source extraction, classpath, reload, compile dry-run, timing, benchmark\n", + "These examples demonstrate the newly added magics and options." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "48208db5", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%%javasrcConstructorByName --src=sample_java com.example.OrderExample\n", + "sample_java/com/example/OrderExample.java" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d33aec3c", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%%javasrcFieldByName --src=sample_java com.example.Product\n", + "sample_java/com/example/Product.java" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "ce5a53e2", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%%javasrcFieldByName --src=sample_java com.example.Product name\n", + "sample_java/com/example/Product.java" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "cf525a61", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%%javasrcJavadoc --src=sample_java com.example.Greeter\n", + "sample_java/com/example/Greeter.java" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "be43fd75", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%%javasrcJavadoc --src=sample_java com.example.Greeter greet\n", + "sample_java/com/example/Greeter.java" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "48b7b043", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%classpath-snapshot" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "56ab8185", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%reload-class com.example.Greeter" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "b3b5e194", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Dry run: would compile source file: /var/home/bruno/.jupyter/java-workspace/src/main/java/com/example/Dummy.java\n", + "With javac options: -cp file:/var/home/bruno/.local/share/jupyter/kernels/java/IJava-1.4.5.jar -d /var/home/bruno/.jupyter/java-workspace/target/classes --enable-preview --release 25 -proc:full -implicit:class -Xlint:all\n" + ] + } + ], + "source": [ + "%%compile com.example.Dummy --dry-run=true\n", + "public class Dummy {\n", + " public static int value() { return 42; }\n", + "}" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "6d79c65f", + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "samples: [32964072, 28617065, 30631490, 24220108, 23877293]\n", + "min=23877293 median=28617065 avg=28062005,60 max=32964072 (nanoseconds)\n" + ] + } + ], + "source": [ + "%%timeit iterations=5 warmup=2\n", + "int s = 0;\n", + "for (int i = 0; i < 10000; i++) s += i;\n", + "s" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "51ad0569", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Benchmark results (nanoseconds):\n", + "Impl 0: mean=55370840 median=52379171 samples=[65551031, 50660057, 52379171, 59080130, 49183815]\n", + "Impl 1: mean=99466757 median=101817329 samples=[102906743, 101817329, 105328306, 94568050, 92713358]\n" + ] + }, { "data": { - "text/markdown": [ - "Summary of sample_java/com/example/OrderExample.java\n", - "\n", - "ClassOrInterfaceDeclaration: OrderExample\n", - " - String summary(Product)\n", - "\n" + "image/svg+xml": [ + "Impl 055,371 msImpl 199,467 msaveraged over 5 iterations (warmup=1)" ], "text/plain": [ - "Summary of sample_java/com/example/OrderExample.java\n", - "\n", - "ClassOrInterfaceDeclaration: OrderExample\n", - " - String summary(Product)\n", - "\n" + "Impl 055,371 msImpl 199,467 msaveraged over 5 iterations (warmup=1)" ] }, "metadata": {}, @@ -1038,23 +1207,68 @@ } ], "source": [ - "%%javasrcList\n", - "sample_java/com/example/OrderExample.java" + "%%benchmark --chart --sweep var=N start=1000 end=50000 step=10000 iterations=5 warmup=1\n", + "// Implementation A: LinkedList workload (uses N)\n", + " java.util.LinkedList list = new java.util.LinkedList<>();\n", + " for (int i = 0; i < N; i++) list.add(i);\n", + " long sum = 0L;\n", + " for (Integer v : list) sum += v;\n", + " // remove half elements from front to simulate queue-like work\n", + " for (int i = 0; i < N / 2; i++) list.removeFirst();\n", + " sum += list.size();\n", + "---\n", + "// Implementation B: ArrayList workload\n", + " java.util.ArrayList list = new java.util.ArrayList<>();\n", + " int N = 50_000;\n", + " for (int i = 0; i < N; i++) list.add(i);\n", + " long sum = 0L;\n", + " for (Integer v : list) sum += v;\n", + " // remove half elements from front to simulate queue-like work (expensive for ArrayList)\n", + " for (int i = 0; i < N / 2; i++) list.remove(0);\n", + " sum += list.size();" ] }, { - "cell_type": "markdown", - "id": "738fd120", - "metadata": {}, + "cell_type": "code", + "execution_count": 7, + "id": "227fed40", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], "source": [ - "- `%%javasrcList file.java` prints a summary (classes, methods, signatures).\n", - "- `%%javasrcMethodByName ClassName methodRegex=^sum` finds methods by regex. Use `--raw` to get plain text output." + "public static class BenchmarkHelpers {\n", + " public static long listTest(java.util.function.Supplier> maker, int N) {\n", + " java.util.List list = maker.get();\n", + " for (int i = 0; i < N; i++) list.add(i);\n", + " long s = 0L;\n", + " for (Integer v : list) s += v;\n", + " for (int i = 0; i < N / 2; i++) list.remove(0);\n", + " return s + list.size();\n", + " }\n", + "\n", + " public static long randomOpsTest(java.util.function.Supplier> maker, int N, int ops, long seed) {\n", + " java.util.List list = maker.get();\n", + " for (int i = 0; i < N; i++) list.add(i);\n", + " java.util.Random rnd = new java.util.Random(seed);\n", + " for (int o = 0; o < ops; o++) {\n", + " if (list.isEmpty()) { list.add(rnd.nextInt(N + ops + 1)); continue; }\n", + " int pos = rnd.nextInt(list.size());\n", + " if (rnd.nextBoolean()) list.add(pos, rnd.nextInt(N + ops + 1));\n", + " else list.remove(pos);\n", + " }\n", + " long s = 0L; for (Integer v : list) s += v;\n", + " return s + list.size();\n", + " }\n", + "}" ] }, { "cell_type": "code", - "execution_count": 33, - "id": "45a05a57", + "execution_count": 9, + "id": "428d5c90", "metadata": { "vscode": { "languageId": "java" @@ -1063,33 +1277,11 @@ "outputs": [ { "data": { - "text/markdown": [ - "**Usage:** `%%javasrcMethodByName [options] [methodName|index]`\n", - "\n", - "**Options:**\n", - "- `--src `: source root to resolve FQCN (e.g., `--src=sample_java`)\n", - "- `methodRegex=`: select methods whose name matches regex\n", - "- `selectIndex=` or positional index: pick one when multiple matches\n", - "- `--raw` / `--fenced`: output format\n", - "\n", - "**Examples:**\n", - "- `%%javasrcMethodByName methodRegex=summary --src=sample_java com.example.OrderExample`\n", - "- `%%javasrcMethodByName com.example.OrderExample myMethod`\n", - "- `%%javasrcMethodByName selectIndex=1 com.example.OrderExample myMethod`\n" + "image/svg+xml": [ + "100011000210003100041000NBenchmark sweep: N0,0010,8421,6832,5243,3654,2011,4710,6513,0910,5014,719,2412,5522,1254,2048,87// LinkedList// ArrayListaveraged over 5 iterations (warmup=1)" ], "text/plain": [ - "**Usage:** `%%javasrcMethodByName [options] [methodName|index]`\n", - "\n", - "**Options:**\n", - "- `--src `: source root to resolve FQCN (e.g., `--src=sample_java`)\n", - "- `methodRegex=`: select methods whose name matches regex\n", - "- `selectIndex=` or positional index: pick one when multiple matches\n", - "- `--raw` / `--fenced`: output format\n", - "\n", - "**Examples:**\n", - "- `%%javasrcMethodByName methodRegex=summary --src=sample_java com.example.OrderExample`\n", - "- `%%javasrcMethodByName com.example.OrderExample myMethod`\n", - "- `%%javasrcMethodByName selectIndex=1 com.example.OrderExample myMethod`\n" + "100011000210003100041000NBenchmark sweep: N0,0010,8421,6832,5243,3654,2011,4710,6513,0910,5014,719,2412,5522,1254,2048,87// LinkedList// ArrayListaveraged over 5 iterations (warmup=1)" ] }, "metadata": {}, @@ -1097,14 +1289,18 @@ } ], "source": [ - "%%javasrcMethodByName --help\n", - "//need to have some text here to avoid empty cell. TODO: fix it" + "%%benchmark --chart --sweep var=N start=1000 end=50000 step=10000 iterations=5 warmup=1\n", + "// LinkedList\n", + "BenchmarkHelpers.listTest(() -> new java.util.LinkedList<>(), N);\n", + "---\n", + "// ArrayList\n", + "BenchmarkHelpers.listTest(() -> new java.util.ArrayList<>(), N);" ] }, { "cell_type": "code", - "execution_count": null, - "id": "e604f519", + "execution_count": 11, + "id": "096bc4cd", "metadata": { "vscode": { "languageId": "java" @@ -1113,11 +1309,11 @@ "outputs": [ { "data": { - "text/markdown": [ - "Error: failed to read file `//need to have some text here to avoid empty cell. TODO: fix it`: /need to have some text here to avoid empty cell. TODO: fix it" + "image/svg+xml": [ + "100011000210003100041000NBenchmark sweep: N0,004,118,2212,3316,4420,5512,3911,8913,1513,5220,5514,4112,8314,3513,6017,26// LinkedList// ArrayListaveraged over 5 iterations (warmup=1)" ], "text/plain": [ - "Error: failed to read file `//need to have some text here to avoid empty cell. TODO: fix it`: /need to have some text here to avoid empty cell. TODO: fix it" + "100011000210003100041000NBenchmark sweep: N0,004,118,2212,3316,4420,5512,3911,8913,1513,5220,5514,4112,8314,3513,6017,26// LinkedList// ArrayListaveraged over 5 iterations (warmup=1)" ] }, "metadata": {}, @@ -1125,8 +1321,67 @@ } ], "source": [ - "%%javasrcMethodByName methodRegex=summary --src=sample_java com.example.OrderExample\n", - "sample_java/com/example/OrderExample.java" + "%%benchmark --chart --sweep var=N start=1000 end=50000 step=10000 iterations=5 warmup=1\n", + "// LinkedList\n", + "BenchmarkHelpers.randomOpsTest(() -> new java.util.LinkedList<>(), N, 1, 1);\n", + "---\n", + "// ArrayList\n", + "BenchmarkHelpers.randomOpsTest(() -> new java.util.ArrayList<>(), N, 1, 1);" + ] + }, + { + "cell_type": "markdown", + "id": "7a3362fd", + "metadata": {}, + "source": [ + "### Extract class by name" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "441130dd", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%%javasrcClassByName --src=sample_java com.example.Greeter\n", + "sample_java/com/example/Greeter.java" + ] + }, + { + "cell_type": "markdown", + "id": "5da8aded", + "metadata": {}, + "source": [ + "---\n", + "\n", + "## Summary: Getting Help\n", + "\n", + "Almost all magics now support `--help` or `-h` flag for comprehensive documentation:\n", + "\n", + "```java\n", + "%%shell --help\n", + "%%compile --help\n", + "%%javasrcMethodByName --help\n", + "%pom --help\n", + "```\n", + "\n", + "**Quick reference:**\n", + "- `%listMagic` - Show all available line and cell magics\n", + "- `%listLineMagic` - Show only line magics\n", + "- `%listCellMagic` - Show only cell magics\n", + "\n", + "**Resources:**\n", + "- [Magics Documentation](../../magics.md)\n", + "- [Magics Audit and Improvement Plan](../../MAGICS_AUDIT_AND_IMPROVEMENT_PLAN.md)\n", + "- [Consolidation Summary](../../MAGICS_CONSOLIDATION_SUMMARY.md)\n", + "\n", + "**Next Steps:**\n", + "Experiment with the magics, check the help text, and report any issues or feature requests!" ] } ], diff --git a/docs/notebooks/sample_java/com/example/Greeter.java b/docs/notebooks/sample_java/com/example/Greeter.java index 6eeccf1..6bcb17a 100644 --- a/docs/notebooks/sample_java/com/example/Greeter.java +++ b/docs/notebooks/sample_java/com/example/Greeter.java @@ -1,5 +1,8 @@ package com.example; +/** + * A simple Greeter class that greets a person by name. + */ public class Greeter { private final String name; @@ -7,6 +10,11 @@ public Greeter(String name) { this.name = name; } + /** + * Greets the person by name. + * + * @return A greeting message. + */ public String greet() { return "Hello " + name; } diff --git a/docs/notebooks/sample_java/com/example/OrderExample.java b/docs/notebooks/sample_java/com/example/OrderExample.java index 9a6c8b5..09ecddf 100644 --- a/docs/notebooks/sample_java/com/example/OrderExample.java +++ b/docs/notebooks/sample_java/com/example/OrderExample.java @@ -13,7 +13,15 @@ public Product(long id, String name, double price) { } } + public OrderExample() { + } + public static String summary(Product p) { return p.id + ":" + p.name + ":" + p.price; } + + @Deprecated + public static String deprecatedMethod() { + return "This method is deprecated"; + } } diff --git a/docs/notebooks/sample_java/com/example/Product.java b/docs/notebooks/sample_java/com/example/Product.java new file mode 100644 index 0000000..929d9d1 --- /dev/null +++ b/docs/notebooks/sample_java/com/example/Product.java @@ -0,0 +1,17 @@ +package com.example; + +public class Product { + private long id; + private String name; + private double price; + + public Product(long id, String name, double price) { + this.id = id; + this.name = name; + this.price = price; + } + + public static String summary(Product p) { + return p.id + ":" + p.name + ":" + p.price; + } +} diff --git a/docs/notebooks/sample_java/com/example/SayHello.java b/docs/notebooks/sample_java/com/example/SayHello.java new file mode 100644 index 0000000..87b5336 --- /dev/null +++ b/docs/notebooks/sample_java/com/example/SayHello.java @@ -0,0 +1,5 @@ +package com.example; + +public interface SayHello { + String sayHello(String name); +} diff --git a/src/main/java/io/github/spencerpark/ijava/JavaKernel.java b/src/main/java/io/github/spencerpark/ijava/JavaKernel.java index cf8bc39..6036941 100644 --- a/src/main/java/io/github/spencerpark/ijava/JavaKernel.java +++ b/src/main/java/io/github/spencerpark/ijava/JavaKernel.java @@ -84,20 +84,21 @@ public static String maybeCompleteCodeSignifier() { private final StringStyler errorStyler; public static boolean printWithVarName = true; - // jupyter support ANSI_escape_code, java ansi code demo: https://stackoverflow.com/a/5762502 + // jupyter support ANSI_escape_code, java ansi code demo: + // https://stackoverflow.com/a/5762502 private static String varNamePattern = "\u001B[36m%s\u001B[0m: "; private Long snippetId = 0L; private static final List COMMENT_PATTERNS = List.of("/\\*(.|\\s)*?\\*/", "//.*\\n*", "\\s+"); public JavaKernel() { // todo for debug - //try { - // System.out.println("------------- sleep start -------------"); - // Thread.sleep(10 * 1000L); - // System.out.println("------------- sleep end -------------"); - //} catch (InterruptedException e) { - // e.printStackTrace(); - //} + // try { + // System.out.println("------------- sleep start -------------"); + // Thread.sleep(10 * 1000L); + // System.out.println("------------- sleep end -------------"); + // } catch (InterruptedException e) { + // e.printStackTrace(); + // } this.evaluator = new CodeEvaluatorBuilder() .addClasspathFromString(System.getenv(IJava.CLASSPATH_KEY)) .compilerOptsFromString(System.getenv(IJava.COMPILER_OPTS_KEY)) @@ -119,9 +120,9 @@ public JavaKernel() { magics.registerMagics(new PrinterMagics()); magics.registerMagics(new MagicsTool()); magics.registerMagics(new TimeItMagics()); + magics.registerMagics(new BenchmarkMagics()); magics.registerMagics(new CompilerMagics(this::addToClasspath)); - magics.registerMagics(new JavaCompilerMagics(this::addToClasspath)); magics.registerMagics(new JavaDBMSMagics()); magics.registerMagics(new JavaMagics()); @@ -146,13 +147,13 @@ public JavaKernel() { IJava.VERSION, Header.PROTOCOL_VERISON, KERNEL_META.getOrDefault("project", "UNKNOWN"), - KERNEL_META.getOrDefault("version", "UNKNOWN") - ); + KERNEL_META.getOrDefault("version", "UNKNOWN")); this.helpLinks = List.of( - new LanguageInfo.Help("Java tutorial", "https://docs.oracle.com/javase/tutorial/java/nutsandbolts/index.html"), - new LanguageInfo.Help("IJava homepage", "https://github.com/SpencerPark/IJava") - ); - // todo io.github.spencerpark.jupyter.kernel.display.DisplayData putJSON, JsonParser.parseString + new LanguageInfo.Help("Java tutorial", + "https://docs.oracle.com/javase/tutorial/java/nutsandbolts/index.html"), + new LanguageInfo.Help("IJava homepage", "https://github.com/SpencerPark/IJava")); + // todo io.github.spencerpark.jupyter.kernel.display.DisplayData putJSON, + // JsonParser.parseString this.renderer.createRegistration(JsonElement.class) .preferring(MIMEType.APPLICATION_JSON) .register((data, context) -> context.renderIfRequested(MIMEType.APPLICATION_JSON, () -> data)); @@ -162,7 +163,8 @@ public JavaKernel() { .addSecondaryStyle(TextColor.BOLD_RED_FG) .addHighlightStyle(TextColor.BOLD_BLACK_FG) .addHighlightStyle(TextColor.RED_BG) - //TODO map snippet ids to code cells and put the proper line number in the margin here + // TODO map snippet ids to code cells and put the proper line number in the + // margin here .withLinePrefix(TextColor.BOLD_BLACK_FG + "| ") .build(); } @@ -232,7 +234,8 @@ private List formatCompilationException(CompilationException e) { // Add the error message for (String line : StringStyler.splitLines(d.getMessage(null))) { - // Skip the information about the location of the error as it is highlighted instead + // Skip the information about the location of the error as it is highlighted + // instead if (!line.trim().startsWith("location:")) fmt.add(this.errorStyler.secondary(line)); } @@ -275,7 +278,8 @@ private List formatUnresolvedReferenceException(UnresolvedReferenceExcep } private void formatUnresolvedDep(DeclarationSnippet declarationSnippet, final List fmt) { - List unresolvedDependencies = this.evaluator.getShell().unresolvedDependencies(declarationSnippet).toList(); + List unresolvedDependencies = this.evaluator.getShell().unresolvedDependencies(declarationSnippet) + .toList(); if (!unresolvedDependencies.isEmpty()) { fmt.addAll(this.errorStyler.primaryLines(declarationSnippet.source())); fmt.add(this.errorStyler.secondary("Unresolved dependencies:")); @@ -289,8 +293,7 @@ private List formatEvaluationTimeoutException(EvaluationTimeoutException fmt.add(this.errorStyler.secondary(String.format( "Evaluation timed out after %d %s.", e.getDuration(), - e.getUnit().name().toLowerCase()) - )); + e.getUnit().name().toLowerCase()))); return fmt; } @@ -313,18 +316,23 @@ public Object evalRaw(String expr) throws Exception { public DisplayData eval(String expr) throws Exception { Object result = this.evalRaw(expr); - if (result == null) return null; - if (result instanceof DisplayData displayData) return displayData; + if (result == null) + return null; + if (result instanceof DisplayData displayData) + return displayData; if (printWithVarName) { - Optional lastSnippet = this.evaluator.getShell().snippets().skip(snippetId).reduce((first, second) -> second); + Optional lastSnippet = this.evaluator.getShell().snippets().skip(snippetId) + .reduce((first, second) -> second); if (lastSnippet.isPresent()) { Snippet snippet = lastSnippet.get(); if (snippet instanceof ExpressionSnippet || snippet instanceof VarSnippet) { snippetId = snippet.id().matches("\\d+") ? (Long.parseLong(snippet.id()) - 1) : (snippetId + 1); String sourceStr = snippet.source(); - for (String pattern : COMMENT_PATTERNS) sourceStr = sourceStr.replaceAll(pattern, ""); - if (sourceStr.length() > 32) sourceStr = sourceStr.substring(0, 32) + "..."; + for (String pattern : COMMENT_PATTERNS) + sourceStr = sourceStr.replaceAll(pattern, ""); + if (sourceStr.length() > 32) + sourceStr = sourceStr.substring(0, 32) + "..."; return this.getRenderer().render(String.format(varNamePattern, sourceStr) + result); } } @@ -335,17 +343,24 @@ public DisplayData eval(String expr) throws Exception { @Override public DisplayData inspect(String code, int at, boolean extraDetail) { - // Move the code position to the end of the identifier to make the inspection work at any - // point in the identifier. i.e "System.o|ut" or "System.out|" will return the same result. - while (at + 1 < code.length() && IDENTIFIER_CHAR.test(code.charAt(at + 1))) at++; - - // If the next non-whitespace character is an opening paren '(' then this must be included + // Move the code position to the end of the identifier to make the inspection + // work at any + // point in the identifier. i.e "System.o|ut" or "System.out|" will return the + // same result. + while (at + 1 < code.length() && IDENTIFIER_CHAR.test(code.charAt(at + 1))) + at++; + + // If the next non-whitespace character is an opening paren '(' then this must + // be included // in the documentation search to ensure it searches for a method call. int parenIdx = at; - while (parenIdx + 1 < code.length() && WS.test(code.charAt(parenIdx + 1))) parenIdx++; - if (parenIdx + 1 < code.length() && code.charAt(parenIdx + 1) == '(') at = parenIdx + 1; + while (parenIdx + 1 < code.length() && WS.test(code.charAt(parenIdx + 1))) + parenIdx++; + if (parenIdx + 1 < code.length() && code.charAt(parenIdx + 1) == '(') + at = parenIdx + 1; - List documentations = this.evaluator.getShell().sourceCodeAnalysis().documentation(code, at + 1, true); + List documentations = this.evaluator.getShell().sourceCodeAnalysis() + .documentation(code, at + 1, true); if (documentations == null || documentations.isEmpty()) { return null; } @@ -356,11 +371,11 @@ public DisplayData inspect(String code, int at, boolean extraDetail) { String formatted = doc.signature(); String javadoc = doc.javadoc(); - if (javadoc != null) formatted += '\n' + javadoc; + if (javadoc != null) + formatted += '\n' + javadoc; return formatted; - }).collect(Collectors.joining("\n\n")) - ); + }).collect(Collectors.joining("\n\n"))); fmtDocs.putHTML( documentations.stream() @@ -369,11 +384,11 @@ public DisplayData inspect(String code, int at, boolean extraDetail) { // TODO consider compiling the javadoc to html for pretty printing String javadoc = doc.javadoc(); - if (javadoc != null) formatted += "
" + javadoc; + if (javadoc != null) + formatted += "
" + javadoc; return formatted; - }).collect(Collectors.joining("

")) - ); + }).collect(Collectors.joining("

"))); return fmtDocs; } @@ -381,10 +396,13 @@ public DisplayData inspect(String code, int at, boolean extraDetail) { @Override public ReplacementOptions complete(String code, int at) { int[] replaceStart = new int[1]; // As of now this is always the same as the cursor... - List suggestions = this.evaluator.getShell().sourceCodeAnalysis().completionSuggestions(code, at, replaceStart); - if (suggestions == null || suggestions.isEmpty()) return null; + List suggestions = this.evaluator.getShell().sourceCodeAnalysis() + .completionSuggestions(code, at, replaceStart); + if (suggestions == null || suggestions.isEmpty()) + return null; - // .sorted((s1, s2) -> s1.matchesType() ? s2.matchesType() ? 0 : -1 : s2.matchesType() ? 1 : 0) + // .sorted((s1, s2) -> s1.matchesType() ? s2.matchesType() ? 0 : -1 : + // s2.matchesType() ? 1 : 0) List options = suggestions.stream() .sorted((s1, s2) -> (s1.matchesType() ? 0 : 1) + (s2.matchesType() ? 0 : -1)) .map(SourceCodeAnalysis.Suggestion::continuation) @@ -408,4 +426,4 @@ public void onShutdown(boolean isRestarting) { public void interrupt() { this.evaluator.interrupt(); } -} \ No newline at end of file +} diff --git a/src/main/java/io/github/spencerpark/ijava/execution/MagicsSourceTransformer.java b/src/main/java/io/github/spencerpark/ijava/execution/MagicsSourceTransformer.java index db24a95..b5abe31 100644 --- a/src/main/java/io/github/spencerpark/ijava/execution/MagicsSourceTransformer.java +++ b/src/main/java/io/github/spencerpark/ijava/execution/MagicsSourceTransformer.java @@ -28,6 +28,7 @@ import io.github.spencerpark.jupyter.kernel.magic.MagicParser; import java.util.Base64; +import java.util.Arrays; import java.util.regex.Matcher; import java.util.regex.Pattern; import java.util.stream.Collectors; @@ -46,6 +47,31 @@ public String transformMagics(String source) { if (ctx != null) return this.transformCellMagic(ctx); + // Fallback: some frontends (or single-line cells) may present a cell magic + // with no body (e.g. "%%compile -h"). The parser may not treat this as + // a cell magic. If the source starts with "%%" and no ctx was parsed, + // synthesize a cell-magic transform so magics can short-circuit help + // handling without requiring a non-empty body. + String trimmed = source == null ? "" : source.trim(); + if (trimmed.startsWith("%%")) { + String header = trimmed.substring(2).trim(); + String[] parts = header.split("\\s+", 2); + String name = parts.length > 0 ? parts[0] : ""; + String argsPart = parts.length > 1 ? parts[1] : ""; + String argsList = ""; + if (!argsPart.isBlank()) { + argsList = Arrays.stream(argsPart.split("\\s+")) + .map(this::b64Transform) + .collect(Collectors.joining(",")); + } + + return String.format( + "cellMagic(%s,List.of(%s),%s);{};", + this.b64Transform(name), + argsList, + this.b64Transform("")); + } + return transformLineMagics(source); } @@ -77,8 +103,7 @@ private String transformLineMagic(LineMagicParseContext ctx) { this.b64Transform(ctx.getMagicCall().getName()), ctx.getMagicCall().getArgs().stream() .map(this::b64Transform) - .collect(Collectors.joining(",")) - ); + .collect(Collectors.joining(","))); } private String transformCellMagic(CellMagicParseContext ctx) { @@ -88,7 +113,6 @@ private String transformCellMagic(CellMagicParseContext ctx) { ctx.getMagicCall().getArgs().stream() .map(this::b64Transform) .collect(Collectors.joining(",")), - this.b64Transform(ctx.getMagicCall().getBody()) - ); + this.b64Transform(ctx.getMagicCall().getBody())); } } diff --git a/src/main/java/io/github/spencerpark/ijava/magics/BenchmarkMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/BenchmarkMagics.java new file mode 100644 index 0000000..7315138 --- /dev/null +++ b/src/main/java/io/github/spencerpark/ijava/magics/BenchmarkMagics.java @@ -0,0 +1,286 @@ +package io.github.spencerpark.ijava.magics; + +import io.github.spencerpark.ijava.IJava; +import io.github.spencerpark.ijava.runtime.Display; +import io.github.spencerpark.jupyter.kernel.magic.registry.CellMagic; +import java.util.*; +import java.util.stream.Collectors; + +public class BenchmarkMagics { + @CellMagic("benchmark") + public void benchmark(List args, String body) throws Exception { + if (args == null) + args = Collections.emptyList(); + if (body == null) + body = ""; + + Map opts = OptionUtils.parseOptions(args); + int iterations = Integer.parseInt(opts.getOrDefault("iterations", "5")); + int warmup = Integer.parseInt(opts.getOrDefault("warmup", "1")); + + // Split implementations by a separator line '---' + String[] parts = body.split("(?m)^---$"); + List impls = Arrays.stream(parts).map(String::trim).filter(s -> !s.isEmpty()) + .collect(Collectors.toList()); + if (impls.isEmpty()) { + System.out.println("No implementations provided. Separate implementations by a line containing '---'."); + return; + } + + // Sweep option: --sweep var=x start=1 end=10 step=1 + boolean doSweep = args.contains("--sweep") || "true".equals(opts.get("sweep")); + if (doSweep) { + String var = opts.get("var"); + if (var == null || var.isBlank()) { + System.out.println("Missing sweep variable. Provide var= option."); + return; + } + int start = Integer.parseInt(opts.getOrDefault("start", "0")); + int end = Integer.parseInt(opts.getOrDefault("end", "10")); + int step = Integer.parseInt(opts.getOrDefault("step", "1")); + + List sweepValues = new ArrayList<>(); + if (step == 0) + step = 1; + if (step > 0) { + for (int v = start; v <= end; v += step) + sweepValues.add(v); + } else { + for (int v = start; v >= end; v += step) + sweepValues.add(v); + } + + // declare variable initially (try declare, otherwise assign) + try { + IJava.getKernelInstance().evalRaw("int " + var + " = " + start + ";"); + } catch (Exception e) { + try { + IJava.getKernelInstance().evalRaw(var + " = " + start + ";"); + } catch (Exception ignored) { + } + } + + // results: for each sweep value, for each impl store mean ms + double[][] means = new double[sweepValues.size()][impls.size()]; + for (int si = 0; si < sweepValues.size(); si++) { + int val = sweepValues.get(si); + try { + IJava.getKernelInstance().evalRaw(var + " = " + val + ";"); + } catch (Exception ignored) { + } + + for (int ii = 0; ii < impls.size(); ii++) { + String impl = impls.get(ii); + // warmup + for (int w = 0; w < warmup; w++) { + IJava.getKernelInstance().evalRaw(impl); + } + // measure + List times = new ArrayList<>(); + for (int i = 0; i < iterations; i++) { + long startNs = System.nanoTime(); + IJava.getKernelInstance().evalRaw(impl); + long endNs = System.nanoTime(); + times.add(endNs - startNs); + } + double meanNs = times.stream().mapToLong(Long::longValue).sum() / (double) times.size(); + means[si][ii] = meanNs / 1e6; // ms + } + } + + // render multi-series SVG line chart (sweep on x, implementations as series) + try { + int width = 1000; + int height = 400; + int marginLeft = 60; + int marginRight = 20; + int legendWidth = 260; + int marginBottom = 60; + int marginTop = 30; + int plotW = width - marginLeft - legendWidth - marginRight; + int plotH = height - marginTop - marginBottom; + + double max = 0.0; + for (double[] row : means) + for (double d : row) + if (d > max) + max = d; + if (max == 0) + max = 1.0; + + StringBuilder svg = new StringBuilder(); + svg.append(""); + svg.append(""); + svg.append(""); + + // axes + svg.append(""); + svg.append(""); + + // x ticks and labels + int nX = sweepValues.size(); + int denomX = Math.max(1, nX - 1); + for (int i = 0; i < nX; i++) { + int x = marginLeft + (int) ((i / (double) denomX) * plotW); + int y = marginTop + plotH; + svg.append(""); + svg.append("" + sweepValues.get(i) + + ""); + } + + // x-axis label (variable name) + svg.append("" + var + ""); + + // title + svg.append("Benchmark sweep: " + + var + ""); + + // y grid and labels + int yTicks = 5; + for (int t = 0; t <= yTicks; t++) { + double frac = t / (double) yTicks; + int y = marginTop + (int) ((1 - frac) * plotH); + double val = frac * max; + svg.append(""); + svg.append("" + + String.format("%.2f", val) + ""); + } + + String[] colors = new String[] { "#4CAF50", "#2196F3", "#FF9800", "#9C27B0", "#F44336" }; + // draw series + for (int implIdx = 0; implIdx < impls.size(); implIdx++) { + StringBuilder path = new StringBuilder(); + for (int xi = 0; xi < nX; xi++) { + double d = means[xi][implIdx]; + int x = marginLeft + (int) ((xi / (double) denomX) * plotW); + int y = marginTop + (int) ((1 - (d / max)) * plotH); + if (xi == 0) + path.append("M " + x + " " + y); + else + path.append(" L " + x + " " + y); + } + svg.append(""); + // draw points + for (int xi = 0; xi < nX; xi++) { + double d = means[xi][implIdx]; + int x = marginLeft + (int) ((xi / (double) denomX) * plotW); + int y = marginTop + (int) ((1 - (d / max)) * plotH); + svg.append(""); + // annotate point with value + svg.append("" + + String.format("%.2f", d) + ""); + } + } + + // legend + int lx = marginLeft + plotW + 10; + int ly = marginTop + 10; + for (int implIdx = 0; implIdx < impls.size(); implIdx++) { + String implLabel = impls.get(implIdx).split("\\n")[0].trim(); + if (implLabel.length() > 40) + implLabel = implLabel.substring(0, 37) + "..."; + svg.append(""); + svg.append("" + implLabel + + ""); + } + + svg.append("averaged over " + iterations + + " iterations (warmup=" + warmup + ")"); + svg.append(""); + + Display.display(svg.toString(), "image/svg+xml"); + } catch (Exception e) { + System.out.println("Failed to render sweep chart: " + e.getMessage()); + } + + return; + } + + List> results = new ArrayList<>(); + for (String impl : impls) { + // warmup + for (int w = 0; w < warmup; w++) { + IJava.getKernelInstance().evalRaw(impl); + } + List times = new ArrayList<>(); + for (int i = 0; i < iterations; i++) { + long start = System.nanoTime(); + IJava.getKernelInstance().evalRaw(impl); + long end = System.nanoTime(); + times.add(end - start); + } + results.add(times); + } + + // Print comparative table + System.out.println("Benchmark results (nanoseconds):"); + for (int i = 0; i < impls.size(); i++) { + List t = results.get(i); + long sum = t.stream().mapToLong(Long::longValue).sum(); + List sorted = t.stream().sorted().collect(Collectors.toList()); + long median = sorted.get(sorted.size() / 2); + System.out.printf("Impl %d: mean=%d median=%d samples=%s%n", i, sum / t.size(), median, t); + } + + // Optionally render a simple SVG comparison chart + boolean doChart = args.contains("--chart") || args.contains("--diagram") || "true".equals(opts.get("chart")); + if (doChart) { + try { + // compute mean in milliseconds + List meansMs = new ArrayList<>(); + double max = 0.0; + for (List t : results) { + double meanNs = t.stream().mapToLong(Long::longValue).sum() / (double) t.size(); + double meanMs = meanNs / 1e6; + meansMs.add(meanMs); + if (meanMs > max) + max = meanMs; + } + + int width = 640; + int leftLabel = 160; + int barArea = width - leftLabel - 40; + int barH = 36; + int gap = 18; + int height = (barH + gap) * meansMs.size() + 40; + + StringBuilder svg = new StringBuilder(); + svg.append(""); + svg.append(""); + svg.append(""); + + int y = 20; + String[] colors = new String[] { "#4CAF50", "#2196F3", "#FF9800", "#9C27B0", "#F44336" }; + for (int i = 0; i < meansMs.size(); i++) { + double m = meansMs.get(i); + int w = (int) ((max == 0) ? 0 : (m / max) * barArea); + String label = "Impl " + i; + svg.append("" + label + ""); + svg.append(""); + svg.append("" + + String.format("%.3f ms", m) + ""); + y += barH + gap; + } + + svg.append("averaged over " + + iterations + " iterations (warmup=" + warmup + ")"); + svg.append(""); + + Display.display(svg.toString(), "image/svg+xml"); + } catch (Exception e) { + System.out.println("Failed to render chart: " + e.getMessage()); + } + } + } +} diff --git a/src/main/java/io/github/spencerpark/ijava/magics/ClasspathMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/ClasspathMagics.java index 56c243c..4fefb3d 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/ClasspathMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/ClasspathMagics.java @@ -26,7 +26,10 @@ import io.github.spencerpark.jupyter.kernel.magic.registry.LineMagic; import io.github.spencerpark.jupyter.kernel.util.GlobFinder; +import java.io.File; import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; import java.util.List; import java.util.function.Consumer; import java.util.stream.StreamSupport; @@ -75,4 +78,25 @@ public List classpath(List args) { return paths; } + + @LineMagic(value = "classpath-snapshot") + public String classpathSnapshot(List args) { + String cp = System.getProperty("java.class.path"); + String[] parts = cp.split(File.pathSeparator); + StringBuilder sb = new StringBuilder(); + for (String p : parts) { + sb.append(p); + try { + Path path = Path.of(p); + if (Files.exists(path)) { + sb.append(" (lastModified=").append(Files.getLastModifiedTime(path)).append(")"); + } + } catch (Exception ignored) { + } + sb.append("\n"); + } + String out = sb.toString(); + System.out.println(out); + return out; + } } diff --git a/src/main/java/io/github/spencerpark/ijava/magics/JavaCompilerMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/JavaCompilerMagics.java index 0a2d80c..3ca54c6 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/JavaCompilerMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/JavaCompilerMagics.java @@ -172,25 +172,66 @@ private void addCompiledClassToClasspath(Path outputRoot, boolean verbose) throw } private boolean hasValidFlag(Map> vals, String key) { - return vals.containsKey(key) && - !vals.get(key).isEmpty() && - !vals.get(key).get(0).isEmpty(); + return vals.containsKey(key) && + !vals.get(key).isEmpty() && + !vals.get(key).get(0).isEmpty(); } @CellMagic("compile") public void compile(List args, String body) throws IOException { + // If user asked for help, short-circuit before any argument parsing that + // requires + // required positional parameters (like className). + if (args.contains("--help") || args.contains("-h")) { + System.out.println(""" + ## %%compile - Compile Java source code and add to classpath + + **Usage:** `%%compile [--verbose] [--debug] [--nowarn] fully.qualified.ClassName` + + **Arguments:** + - `className` : Fully qualified class name (e.g., com.example.MyClass) + + **Options:** + - `--verbose, -v` : Enable verbose compilation output + - `--debug, -d` : Include debug information in compiled classes + - `--nowarn, -w` : Suppress compiler warnings + - `--help, -h` : Show this help message + + **Examples:** + ``` + %%compile com.example.Calculator + public class Calculator { + public int add(int a, int b) { return a + b; } + } + ``` + + ``` + %%compile --verbose --debug com.example.MyClass + public class MyClass { + public void hello() { System.out.println("Hello!"); } + } + ``` + + **Note:** Package declaration will be added automatically if not present. + """); + return; + } + MagicsArgs schema = MagicsArgs.builder() .required("className") .flag("verbose", 'v', "Enable verbose output") .flag("debug", 'd', "Add debug information") + .flag("dry-run", 'n', "Show what would be compiled without invoking javac") .flag("nowarn", 'w', "Suppress warnings") .onlyKnownKeywords() .onlyKnownFlags() .build(); Map> vals = schema.parse(args); + boolean verbose = hasValidFlag(vals, "verbose"); boolean debug = hasValidFlag(vals, "debug"); boolean nowarn = hasValidFlag(vals, "nowarn"); + boolean dryRun = hasValidFlag(vals, "dry-run"); String className = vals.get("className").get(0); if (verbose) { @@ -213,6 +254,15 @@ public void compile(List args, String body) throws IOException { log.info("Source file prepared at: {}", sourceFile); } + // If dry-run, report files and options + if (dryRun) { + Path sourceFilePreview = prepareSourceFile(className, body); + List optsList = buildCompilerOptions(context.outputRoot, debug, nowarn); + System.out.println("Dry run: would compile source file: " + sourceFilePreview); + System.out.println("With javac options: " + String.join(" ", optsList)); + return; + } + // Compile CompilerDiagnosticListener diagnostics = new CompilerDiagnosticListener(className, verbose); boolean success = compiler.getTask( @@ -235,4 +285,12 @@ public void compile(List args, String body) throws IOException { } } } -} \ No newline at end of file + + @CellMagic("mycompile") + @Deprecated(forRemoval = true) + public void mycompile(List args, String body) throws IOException { + System.err.println( + "⚠️ WARNING: %%mycompile is deprecated and will be removed in a future version. Use %%compile instead."); + compile(args, body); + } +} diff --git a/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java index 7849884..3a0f8bb 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java @@ -132,23 +132,31 @@ public String toString() { } private static String sanitizeTableName(String name) { - if (name == null) return "UNKNOWN"; + if (name == null) + return "UNKNOWN"; String t = name.trim(); - if (t.isEmpty()) return "UNKNOWN"; - if (t.startsWith("//")) t = t.substring(2).trim(); - if (t.startsWith("#")) t = t.substring(1).trim(); - if (t.startsWith("--")) t = t.substring(2).trim(); + if (t.isEmpty()) + return "UNKNOWN"; + if (t.startsWith("//")) + t = t.substring(2).trim(); + if (t.startsWith("#")) + t = t.substring(1).trim(); + if (t.startsWith("--")) + t = t.substring(2).trim(); if ((t.startsWith("\"") && t.endsWith("\"")) || (t.startsWith("'") && t.endsWith("'"))) { t = t.substring(1, t.length() - 1).trim(); } - if (t.isEmpty()) return "UNKNOWN"; + if (t.isEmpty()) + return "UNKNOWN"; return t; } private static String quoteIdentifier(String s) { - if (s == null) return "UNKNOWN"; + if (s == null) + return "UNKNOWN"; String t = s.trim(); - if (t.matches("[A-Za-z0-9_]+")) return t; + if (t.matches("[A-Za-z0-9_]+")) + return t; String esc = t.replace("\"", "\\\""); return "\"" + esc + "\""; } @@ -159,7 +167,8 @@ private static String quoteIdentifier(String s) { */ @CellMagic("rdbmsSchema") public void rdbmsSchema(java.util.List args, String body) { - // args may contain: [] [SVG|PNG] [showSource|-s] [handwritten] [include=] [exclude=] [scale=] + // args may contain: [] [SVG|PNG] [showSource|-s] [handwritten] + // [include=] [exclude=] [scale=] String schema = null; boolean showSource = false; String fileFormat = "SVG"; @@ -168,17 +177,20 @@ public void rdbmsSchema(java.util.List args, String body) { String excludeRegex = null; String scale = null; for (String a : args) { - if (a == null) continue; + if (a == null) + continue; String aa = a.trim(); if (aa.equalsIgnoreCase("SVG") || aa.equalsIgnoreCase("PNG")) { fileFormat = aa.toUpperCase(); continue; } - if (aa.equalsIgnoreCase("showSource") || aa.equalsIgnoreCase("show-source") || aa.equals("--show-source") || aa.equals("-s") || aa.equalsIgnoreCase("source")) { + if (aa.equalsIgnoreCase("showSource") || aa.equalsIgnoreCase("show-source") || aa.equals("--show-source") + || aa.equals("-s") || aa.equalsIgnoreCase("source")) { showSource = true; continue; } - if (aa.equalsIgnoreCase("handwritten") || aa.equalsIgnoreCase("--handwritten") || aa.equalsIgnoreCase("handwritten:true")) { + if (aa.equalsIgnoreCase("handwritten") || aa.equalsIgnoreCase("--handwritten") + || aa.equalsIgnoreCase("handwritten:true")) { handwritten = true; continue; } @@ -194,12 +206,14 @@ public void rdbmsSchema(java.util.List args, String body) { scale = aa.substring("scale=".length()); continue; } - if (schema == null) schema = aa; + if (schema == null) + schema = aa; } try (Connection conn = obtainConnection()) { if (conn == null) { - System.out.println("No JDBC connection available. Set system properties 'jdbc.url' (and optionally 'jdbc.user'/'jdbc.password'), or provide a Connection in the kernel environment."); + System.out.println( + "No JDBC connection available. Set system properties 'jdbc.url' (and optionally 'jdbc.user'/'jdbc.password'), or provide a Connection in the kernel environment."); return; } @@ -216,30 +230,37 @@ public void rdbmsSchema(java.util.List args, String body) { out.append(" ArrowColor #2688d4\n"); out.append(" BorderColor #2688d4\n"); out.append("}\n"); - // Avoid using PlantUML icon tokens (<&...>) which may trigger the 'handwritten' option. - // Use simple textual markers instead so diagrams render without requiring '!option handwritten true'. + // Avoid using PlantUML icon tokens (<&...>) which may trigger the 'handwritten' + // option. + // Use simple textual markers instead so diagrams render without requiring + // '!option handwritten true'. out.append("!define primary_key(x) PK x\n"); out.append("!define foreign_key(x) FK x\n"); out.append("!define column(x) * x\n"); out.append("!define table(x) entity x << (T, white) >>\n\n"); - if (handwritten) out.append("!option handwritten true\n"); - if (scale != null && !scale.isBlank()) out.append("scale " + scale + "\n"); + if (handwritten) + out.append("!option handwritten true\n"); + if (scale != null && !scale.isBlank()) + out.append("scale " + scale + "\n"); // iterate tables (if body contains specific table names, honor them) java.util.List tableNames = new java.util.ArrayList<>(); if (body != null && !body.trim().isEmpty()) { for (String line : body.split("\n")) { String l = line.trim(); - if (l.isEmpty()) continue; + if (l.isEmpty()) + continue; // ignore common comment markers so comments aren't treated as table names - if (l.startsWith("//") || l.startsWith("#") || l.startsWith("--")) continue; + if (l.startsWith("//") || l.startsWith("#") || l.startsWith("--")) + continue; tableNames.add(l); } } if (tableNames.isEmpty()) { - try (ResultSet tables = md.getTables(null, schema, "%", new String[]{"TABLE"})) { - while (tables.next()) tableNames.add(tables.getString("TABLE_NAME")); + try (ResultSet tables = md.getTables(null, schema, "%", new String[] { "TABLE" })) { + while (tables.next()) + tableNames.add(tables.getString("TABLE_NAME")); } } @@ -280,7 +301,8 @@ public void rdbmsSchema(java.util.List args, String body) { try (ResultSet primaryKeys = md.getPrimaryKeys(null, schema, tableName)) { while (primaryKeys.next()) { String pkCol = primaryKeys.getString("COLUMN_NAME"); - if (table.getFields().containsKey(pkCol)) table.getFields().get(pkCol).setRole(Field.Role.PK); + if (table.getFields().containsKey(pkCol)) + table.getFields().get(pkCol).setRole(Field.Role.PK); } } @@ -291,7 +313,8 @@ public void rdbmsSchema(java.util.List args, String body) { String fkTable = foreignKeys.getString("FKTABLE_NAME"); String pkCol = foreignKeys.getString("PKCOLUMN_NAME"); String fkCol = foreignKeys.getString("FKCOLUMN_NAME"); - if (table.getFields().containsKey(fkCol)) table.getFields().get(fkCol).setRole(Field.Role.FK); + if (table.getFields().containsKey(fkCol)) + table.getFields().get(fkCol).setRole(Field.Role.FK); // Determine multiplicity on the FK side. String fkMin = "0"; @@ -300,15 +323,18 @@ public void rdbmsSchema(java.util.List args, String body) { Field fkField = table.getFields().get(fkCol); fkMin = fkField.isNullable() ? "0" : "1"; // If FK column is part of the PK (or unique), treat as max 1 - if (fkField.getRole() == Field.Role.PK) fkMax = "1"; + if (fkField.getRole() == Field.Role.PK) + fkMax = "1"; } String pkMultiplicity = "1"; // primary key side is single (unique) String fkMultiplicity = fkMin + ".." + fkMax; - // Emit relationship with multiplicities and a simple label showing column mapping + // Emit relationship with multiplicities and a simple label showing column + // mapping fkBuilder.append(String.format("%s \"%s\" --> \"%s\" %s : %s -> %s\n", - quoteIdentifier(fkTable), fkMultiplicity, pkMultiplicity, quoteIdentifier(pkTable), quoteIdentifier(fkCol), quoteIdentifier(pkCol))); + quoteIdentifier(fkTable), fkMultiplicity, pkMultiplicity, quoteIdentifier(pkTable), + quoteIdentifier(fkCol), quoteIdentifier(pkCol))); } } @@ -348,16 +374,18 @@ public void rdbmsSchema(java.util.List args, String body) { @CellMagic("sqlAsTable") public void sqlAsTable(java.util.List args, String body) { String sql = body == null ? "" : body.trim(); - if (sql.isEmpty()) return; + if (sql.isEmpty()) + return; // parse args: format=HTML|CSV, max=, showQuery String format = "HTML"; int maxRows = 1000; boolean showQuery = false; for (String a : args) { - if (a == null) continue; + if (a == null) + continue; String aa = a.trim(); - if (aa.equalsIgnoreCase("CSV" ) || aa.equalsIgnoreCase("HTML")) { + if (aa.equalsIgnoreCase("CSV") || aa.equalsIgnoreCase("HTML")) { format = aa.toUpperCase(); continue; } @@ -366,17 +394,22 @@ public void sqlAsTable(java.util.List args, String body) { continue; } if (aa.startsWith("max=")) { - try { maxRows = Integer.parseInt(aa.substring("max=".length())); } catch (NumberFormatException ignored) {} + try { + maxRows = Integer.parseInt(aa.substring("max=".length())); + } catch (NumberFormatException ignored) { + } continue; } if (aa.equalsIgnoreCase("showQuery") || aa.equalsIgnoreCase("--show-query")) { - showQuery = true; continue; + showQuery = true; + continue; } } try (Connection conn = obtainConnection()) { if (conn == null) { - System.out.println("No JDBC connection available. Set system properties 'jdbc.url' (and optionally 'jdbc.user'/'jdbc.password'), or provide a Connection in the kernel environment."); + System.out.println( + "No JDBC connection available. Set system properties 'jdbc.url' (and optionally 'jdbc.user'/'jdbc.password'), or provide a Connection in the kernel environment."); return; } @@ -386,20 +419,23 @@ public void sqlAsTable(java.util.List args, String body) { Matcher m = p.matcher(normalizedSql); if (m.find()) { normalizedSql = m.replaceAll("LIMIT $2 OFFSET $1"); - display("Note: rewrote SQL 'OFFSET ... LIMIT' to 'LIMIT ... OFFSET' for compatibility", "text/markdown"); + display("Note: rewrote SQL 'OFFSET ... LIMIT' to 'LIMIT ... OFFSET' for compatibility", + "text/markdown"); } try (Statement st = conn.createStatement(); ResultSet rs = st.executeQuery(normalizedSql)) { ResultSetMetaData md = rs.getMetaData(); int cols = md.getColumnCount(); - if (showQuery) display("````sql\n" + sql + "\n````", "text/markdown"); + if (showQuery) + display("````sql\n" + sql + "\n````", "text/markdown"); // build CSV if ("CSV".equalsIgnoreCase(format)) { StringBuilder csv = new StringBuilder(); for (int i = 1; i <= cols; i++) { - if (i > 1) csv.append(','); + if (i > 1) + csv.append(','); csv.append(escapeCsv(md.getColumnLabel(i))); } csv.append('\n'); @@ -407,13 +443,15 @@ public void sqlAsTable(java.util.List args, String body) { while (rs.next() && rowCount < maxRows) { rowCount++; for (int i = 1; i <= cols; i++) { - if (i > 1) csv.append(','); + if (i > 1) + csv.append(','); Object v = rs.getObject(i); csv.append(escapeCsv(v == null ? "" : v.toString())); } csv.append('\n'); } - if (rs.next()) csv.append("# TRUNCATED: more rows available\n"); + if (rs.next()) + csv.append("# TRUNCATED: more rows available\n"); display(csv.toString(), "text/csv"); return; } @@ -421,7 +459,9 @@ public void sqlAsTable(java.util.List args, String body) { // default: HTML StringBuilder html = new StringBuilder(); html.append("\n"); - for (int i = 1; i <= cols; i++) html.append(""); + for (int i = 1; i <= cols; i++) + html.append(""); html.append("\n\n"); int rowCount = 0; while (rs.next() && rowCount < maxRows) { @@ -429,12 +469,15 @@ public void sqlAsTable(java.util.List args, String body) { html.append(""); for (int i = 1; i <= cols; i++) { Object v = rs.getObject(i); - html.append(""); + html.append(""); } html.append("\n"); } html.append("
").append(escapeHtml(md.getColumnLabel(i))).append("").append(escapeHtml(md.getColumnLabel(i))) + .append("
").append(v == null ? "" : escapeHtml(v.toString())).append("").append(v == null ? "" : escapeHtml(v.toString())) + .append("
"); - if (rs.next()) html.append("
Results truncated (showing first "+maxRows+" rows)
"); + if (rs.next()) + html.append("
Results truncated (showing first " + + maxRows + " rows)
"); display(html.toString(), "text/html"); } } catch (SQLException e) { @@ -443,7 +486,8 @@ public void sqlAsTable(java.util.List args, String body) { } private static String escapeHtml(String s) { - return s.replace("&", "&").replace("<", "<").replace(">", ">").replace("\"", """).replace("'", "'"); + return s.replace("&", "&").replace("<", "<").replace(">", ">").replace("\"", """).replace("'", + "'"); } private static String escapeCsv(String s) { @@ -457,7 +501,8 @@ private static String escapeCsv(String s) { /** * Attempt to obtain a JDBC Connection from several strategies: * 1) System properties `jdbc.url` (+ user/password) - * 2) If a `DatabaseManager` class with `getConnection()` exists in kernel scope, attempt to call it via reflection. + * 2) If a `DatabaseManager` class with `getConnection()` exists in kernel + * scope, attempt to call it via reflection. */ private Connection obtainConnection() throws SQLException { String url = System.getProperty("jdbc.url"); @@ -468,18 +513,26 @@ private Connection obtainConnection() throws SQLException { boolean accepts = false; for (Driver d : java.util.Collections.list(DriverManager.getDrivers())) { try { - if (d.acceptsURL(url)) { accepts = true; break; } - } catch (Exception ignored) { } + if (d.acceptsURL(url)) { + accepts = true; + break; + } + } catch (Exception ignored) { + } } if (!accepts) { - // Attempt to load driver class from various classloaders and register a proxy driver + // Attempt to load driver class from various classloaders and register a proxy + // driver String driverProp = System.getProperty("jdbc.driver"); String[] candidateDrivers; - if (driverProp != null && !driverProp.isBlank()) candidateDrivers = new String[]{driverProp}; - else candidateDrivers = new String[]{"org.h2.Driver", "org.postgresql.Driver", "com.mysql.cj.jdbc.Driver", "org.hsqldb.jdbc.JDBCDriver", "org.sqlite.JDBC"}; + if (driverProp != null && !driverProp.isBlank()) + candidateDrivers = new String[] { driverProp }; + else + candidateDrivers = new String[] { "org.h2.Driver", "org.postgresql.Driver", + "com.mysql.cj.jdbc.Driver", "org.hsqldb.jdbc.JDBCDriver", "org.sqlite.JDBC" }; - ClassLoader[] loaders = new ClassLoader[]{ + ClassLoader[] loaders = new ClassLoader[] { Thread.currentThread().getContextClassLoader(), ClassLoader.getSystemClassLoader(), this.getClass().getClassLoader(), @@ -488,32 +541,37 @@ private Connection obtainConnection() throws SQLException { for (String drv : candidateDrivers) { for (ClassLoader loader : loaders) { - if (loader == null) continue; + if (loader == null) + continue; try { Class drvClass = Class.forName(drv, true, loader); Object drvInstance = drvClass.getDeclaredConstructor().newInstance(); java.sql.Driver proxy = (java.sql.Driver) java.lang.reflect.Proxy.newProxyInstance( java.sql.Driver.class.getClassLoader(), - new Class[]{java.sql.Driver.class}, - (proxyObj, method, args) -> method.invoke(drvInstance, args) - ); + new Class[] { java.sql.Driver.class }, + (proxyObj, method, args) -> method.invoke(drvInstance, args)); DriverManager.registerDriver(proxy); // if it accepts the URL now, break out - if (proxy.acceptsURL(url)) { accepts = true; break; } + if (proxy.acceptsURL(url)) { + accepts = true; + break; + } } catch (ClassNotFoundException ignored) { } catch (ReflectiveOperationException | java.sql.SQLException e) { // continue to next loader/driver } } - if (accepts) break; + if (accepts) + break; } } String user = System.getProperty("jdbc.user"); String pass = System.getProperty("jdbc.password"); - if (user != null) return DriverManager.getConnection(url, user, pass == null ? "" : pass); + if (user != null) + return DriverManager.getConnection(url, user, pass == null ? "" : pass); return DriverManager.getConnection(url); } @@ -523,7 +581,8 @@ private Connection obtainConnection() throws SQLException { try { java.lang.reflect.Method m = dm.getMethod("getConnection"); Object conn = m.invoke(null); - if (conn instanceof Connection) return (Connection) conn; + if (conn instanceof Connection) + return (Connection) conn; } catch (NoSuchMethodException ignored) { } try { @@ -536,7 +595,8 @@ private Connection obtainConnection() throws SQLException { Object em = createEM.invoke(emf); java.lang.reflect.Method getConn = em.getClass().getMethod("unwrap", Class.class); Object conn = getConn.invoke(em, java.sql.Connection.class); - if (conn instanceof Connection) return (Connection) conn; + if (conn instanceof Connection) + return (Connection) conn; } catch (NoSuchMethodException ignored2) { } } diff --git a/src/main/java/io/github/spencerpark/ijava/magics/JavaMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/JavaMagics.java index a82179e..7f16da0 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/JavaMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/JavaMagics.java @@ -12,6 +12,8 @@ import java.nio.file.Paths; import java.util.*; import java.util.regex.Pattern; +import com.github.javaparser.javadoc.Javadoc; +import com.github.javaparser.javadoc.JavadocBlockTag; import java.util.stream.Collectors; import static io.github.spencerpark.ijava.runtime.Display.display; @@ -25,19 +27,23 @@ public void javasrcMethodByAnnotationName(List args, String body) throws List pos = OptionUtils.positionalArgs(args); if (pos.size() < 2) { - display("Error: expected usage `%%javasrcMethodByAnnotationName [index]`", "text/markdown"); + display("Error: expected usage `%%javasrcMethodByAnnotationName [index]`", + "text/markdown"); return; } String filename = body; String className = pos.get(0); - String simpleClassName = className != null && className.contains(".") ? className.substring(className.lastIndexOf('.') + 1) : className; + String simpleClassName = className != null && className.contains(".") + ? className.substring(className.lastIndexOf('.') + 1) + : className; String annotationName = pos.get(1); int index = pos.size() >= 3 ? Integer.parseInt(pos.get(2)) : 0; if ((filename == null || filename.isBlank()) && className != null && className.contains(".")) { Optional p = PathResolver.resolveSourceFileForClass(className, opts); - if (p.isPresent()) filename = p.get().toString(); + if (p.isPresent()) + filename = p.get().toString(); } CompilationUnit cu; @@ -50,7 +56,16 @@ public void javasrcMethodByAnnotationName(List args, String body) throws Optional clazz = cu.getClassByName(simpleClassName); if (clazz.isEmpty()) { - display("Class `" + className + "` not found in file `" + filename + "`.", "text/markdown"); + Optional ifaceCheck = cu.getInterfaceByName(simpleClassName); + if (ifaceCheck.isPresent()) { + display("`" + className + "` is an interface in file `" + filename + + "`. Use `%%javasrcInterfaceByName` to extract interfaces or supply a class name.", + "text/markdown"); + } else { + display("Class `" + className + "` not found in file `" + filename + "`.", "text/markdown"); + display("Usage: `%%javasrcMethodByAnnotationName [index]`", + "text/markdown"); + } return; } @@ -60,7 +75,8 @@ public void javasrcMethodByAnnotationName(List args, String body) throws .collect(Collectors.toList()); if (matches.isEmpty()) { - display("No methods annotated with `@" + annotationName + "` found in class `" + className + "`.", "text/markdown"); + display("No methods annotated with `@" + annotationName + "` found in class `" + className + "`.", + "text/markdown"); return; } @@ -68,9 +84,11 @@ public void javasrcMethodByAnnotationName(List args, String body) throws StringBuilder sb = new StringBuilder(); sb.append("Found ").append(matches.size()).append(" matching methods:\n\n"); for (int i = 0; i < matches.size(); i++) { - sb.append(i).append(": ").append(matches.get(i).getDeclarationAsString(false, false, false)).append("\n"); + sb.append(i).append(": ").append(matches.get(i).getDeclarationAsString(false, false, false)) + .append("\n"); } - display(sb.toString(), opts.getOrDefault("format", "fenced").equals("raw") ? "text/plain" : "text/markdown"); + display(sb.toString(), + opts.getOrDefault("format", "fenced").equals("raw") ? "text/plain" : "text/markdown"); return; } @@ -78,6 +96,48 @@ public void javasrcMethodByAnnotationName(List args, String body) throws OutputUtils.formatAndDisplay(out, opts); } + private static String renderJavadoc(Javadoc j) { + if (j == null) + return "(no javadoc)"; + StringBuilder sb = new StringBuilder(); + try { + String desc = j.getDescription().toText().trim(); + if (!desc.isEmpty()) { + sb.append(desc).append("\n\n"); + } + + for (JavadocBlockTag tag : j.getBlockTags()) { + JavadocBlockTag.Type t = tag.getType(); + String name = tag.getName().orElse(""); + String content = tag.getContent().toText().trim(); + switch (t) { + case PARAM: + sb.append("- @param ").append(name).append(" — ").append(content).append("\n"); + break; + case RETURN: + sb.append("- @return — ").append(content).append("\n"); + break; + case THROWS: + case EXCEPTION: + sb.append("- @throws ").append(name).append(" — ").append(content).append("\n"); + break; + default: + sb.append("- @").append(tag.getTagName()); + if (!name.isEmpty()) + sb.append(" ").append(name); + if (!content.isEmpty()) + sb.append(" — ").append(content); + sb.append("\n"); + } + } + } catch (Exception e) { + return j.toString(); + } + + String out = sb.toString().trim(); + return out.isEmpty() ? "(no javadoc)" : out; + } + @CellMagic("javasrcMethodByName") public void javasrcMethodByName(List args, String body) throws IOException { // If the user requested help, short-circuit immediately and do not @@ -85,7 +145,8 @@ public void javasrcMethodByName(List args, String body) throws IOExcepti // spurious build/parse attempts (e.g. when the body is empty or a // comment). This ensures `--help` never triggers a build. if (args != null && (args.contains("--help") || args.contains("-h"))) { - String help = "**Usage:** `%%javasrcMethodByName [options] [methodName|index]`\n\n" + + String help = "**Usage:** `%%javasrcMethodByName [options] [methodName|index]`\n\n" + + "**Options:**\n" + "- `--src `: source root to resolve FQCN (e.g., `--src=sample_java`)\n" + "- `methodRegex=`: select methods whose name matches regex\n" + @@ -103,19 +164,23 @@ public void javasrcMethodByName(List args, String body) throws IOExcepti List pos = OptionUtils.positionalArgs(args); if (pos.size() < 1 && !opts.containsKey("methodRegex")) { - display("Error: expected usage `%%javasrcMethodByName ` or use `methodRegex=...`", "text/markdown"); + display("Error: expected usage `%%javasrcMethodByName ` or use `methodRegex=...`", + "text/markdown"); return; } String filename = body; String className = pos.size() >= 1 ? pos.get(0) : null; - String simpleClassName = className != null && className.contains(".") ? className.substring(className.lastIndexOf('.') + 1) : className; + String simpleClassName = className != null && className.contains(".") + ? className.substring(className.lastIndexOf('.') + 1) + : className; String methodName = pos.size() >= 2 ? pos.get(1) : null; int index = pos.size() >= 3 ? Integer.parseInt(pos.get(2)) : 0; if ((filename == null || filename.isBlank()) && className != null && className.contains(".")) { Optional p = PathResolver.resolveSourceFileForClass(className, opts); - if (p.isPresent()) filename = p.get().toString(); + if (p.isPresent()) + filename = p.get().toString(); } CompilationUnit cu; @@ -128,14 +193,21 @@ public void javasrcMethodByName(List args, String body) throws IOExcepti Optional clazz = cu.getClassByName(simpleClassName); if (clazz.isEmpty()) { - display("Class `" + className + "` not found in file `" + filename + "`.", "text/markdown"); + Optional ifaceCheck = cu.getInterfaceByName(simpleClassName); + if (ifaceCheck.isPresent()) { + display("`" + className + "` is an interface in file `" + filename + + "`. To extract the interface source use `%%javasrcInterfaceByName`.", "text/markdown"); + } else { + display("Class `" + className + "` not found in file `" + filename + "`.", "text/markdown"); + } return; } List methods = new ArrayList<>(); if (opts.containsKey("methodRegex")) { Pattern p = Pattern.compile(opts.get("methodRegex")); - methods = clazz.get().getMethods().stream().filter(m -> p.matcher(m.getNameAsString()).find()).collect(Collectors.toList()); + methods = clazz.get().getMethods().stream().filter(m -> p.matcher(m.getNameAsString()).find()) + .collect(Collectors.toList()); } else if (methodName != null) { methods = clazz.get().getMethodsByName(methodName); } @@ -149,9 +221,11 @@ public void javasrcMethodByName(List args, String body) throws IOExcepti StringBuilder sb = new StringBuilder(); sb.append("Found ").append(methods.size()).append(" matching methods:\n\n"); for (int i = 0; i < methods.size(); i++) { - sb.append(i).append(": ").append(methods.get(i).getDeclarationAsString(false, false, false)).append("\n"); + sb.append(i).append(": ").append(methods.get(i).getDeclarationAsString(false, false, false)) + .append("\n"); } - display(sb.toString(), opts.getOrDefault("format", "fenced").equals("raw") ? "text/plain" : "text/markdown"); + display(sb.toString(), + opts.getOrDefault("format", "fenced").equals("raw") ? "text/plain" : "text/markdown"); return; } @@ -179,7 +253,8 @@ public void javasrcInterfaceByName(List args, String body) throws IOExce String filename = body; if ((filename == null || filename.isBlank()) && fqcn != null && fqcn.contains(".")) { Optional p = PathResolver.resolveSourceFileForClass(fqcn, opts); - if (p.isPresent()) filename = p.get().toString(); + if (p.isPresent()) + filename = p.get().toString(); } String className = fqcn.substring(fqcn.lastIndexOf('.') + 1); @@ -194,7 +269,14 @@ public void javasrcInterfaceByName(List args, String body) throws IOExce Optional iface = cu.getInterfaceByName(className); if (iface.isEmpty()) { - display("Interface `" + className + "` not found in file `" + filename + "`.", "text/markdown"); + Optional clazzCheck = cu + .getClassByName(className); + if (clazzCheck.isPresent()) { + display("Found class `" + className + "` in file `" + filename + + "`. To extract classes use `%%javasrcClassByName`.", "text/markdown"); + } else { + display("Interface `" + className + "` not found in file `" + filename + "`.", "text/markdown"); + } return; } @@ -216,7 +298,8 @@ public void javasrcClassByName(List args, String body) throws IOExceptio String filename = body; if ((filename == null || filename.isBlank()) && fqcn != null && fqcn.contains(".")) { Optional p = PathResolver.resolveSourceFileForClass(fqcn, opts); - if (p.isPresent()) filename = p.get().toString(); + if (p.isPresent()) + filename = p.get().toString(); } String className = fqcn.substring(fqcn.lastIndexOf('.') + 1); @@ -233,7 +316,13 @@ public void javasrcClassByName(List args, String body) throws IOExceptio Optional clazz = lpp.getClassByName(className); if (clazz.isEmpty()) { - display("Class `" + className + "` not found in file `" + filename + "`.", "text/markdown"); + Optional ifaceCheck = lpp.getInterfaceByName(className); + if (ifaceCheck.isPresent()) { + display("Found interface `" + className + "` in file `" + filename + + "`. To extract interfaces use `%%javasrcInterfaceByName`.", "text/markdown"); + } else { + display("Class `" + className + "` not found in file `" + filename + "`.", "text/markdown"); + } return; } @@ -249,7 +338,8 @@ public void javasrcList(List args, String body) throws IOException { String filename = body; if ((filename == null || filename.isBlank()) && !pos.isEmpty() && pos.get(0).contains(".")) { Optional p = PathResolver.resolveSourceFileForClass(pos.get(0), opts); - if (p.isPresent()) filename = p.get().toString(); + if (p.isPresent()) + filename = p.get().toString(); } CompilationUnit cu; @@ -264,11 +354,224 @@ public void javasrcList(List args, String body) throws IOException { sb.append("Summary of ").append(filename).append("\n\n"); cu.getTypes().forEach(t -> { sb.append(t.getClass().getSimpleName()).append(": ").append(t.getNameAsString()).append("\n"); - t.getMethods().forEach(m -> sb.append(" - ").append(m.getDeclarationAsString(false, false, false)).append("\n")); + t.getMethods() + .forEach(m -> sb.append(" - ").append(m.getDeclarationAsString(false, false, false)).append("\n")); sb.append("\n"); }); display(sb.toString(), "text/markdown"); } -} \ No newline at end of file + @CellMagic("javasrcConstructorByName") + public void javasrcConstructorByName(List args, String body) throws IOException { + Map opts = OptionUtils.parseOptions(args); + List pos = OptionUtils.positionalArgs(args); + + if (pos.isEmpty()) { + display("Error: expected usage `%%javasrcConstructorByName `", "text/markdown"); + return; + } + + String fqcn = pos.get(0); + String filename = body; + if ((filename == null || filename.isBlank()) && fqcn != null && fqcn.contains(".")) { + Optional p = PathResolver.resolveSourceFileForClass(fqcn, opts); + if (p.isPresent()) + filename = p.get().toString(); + } + + String className = fqcn.substring(fqcn.lastIndexOf('.') + 1); + + CompilationUnit cu; + try { + cu = StaticJavaParser.parse(Files.readString(Path.of(filename))); + } catch (IOException e) { + display("Error: failed to read file `" + filename + "`: " + e.getMessage(), "text/markdown"); + return; + } + + Optional clazz = cu.getClassByName(className); + if (clazz.isEmpty()) { + display("Class `" + fqcn + "` not found in file `" + filename + "`.", "text/markdown"); + return; + } + + List ctors = clazz.get().getConstructors(); + if (ctors.isEmpty()) { + display("No constructors found for `" + fqcn + "`.", "text/markdown"); + return; + } + + StringBuilder sb = new StringBuilder(); + for (int i = 0; i < ctors.size(); i++) { + sb.append(i).append(": ").append(ctors.get(i).getDeclarationAsString(false, false, false)).append("\n\n"); + sb.append(ctors.get(i).toString()).append("\n\n"); + } + + OutputUtils.formatAndDisplay(sb.toString(), opts); + } + + @CellMagic("javasrcFieldByName") + public void javasrcFieldByName(List args, String body) throws IOException { + Map opts = OptionUtils.parseOptions(args); + List pos = OptionUtils.positionalArgs(args); + + if (pos.isEmpty()) { + display("Error: expected usage `%%javasrcFieldByName `", "text/markdown"); + return; + } + + String fqcn = pos.get(0); + String filename = body; + if ((filename == null || filename.isBlank()) && fqcn != null && fqcn.contains(".")) { + Optional p = PathResolver.resolveSourceFileForClass(fqcn, opts); + if (p.isPresent()) + filename = p.get().toString(); + } + + String className = fqcn.substring(fqcn.lastIndexOf('.') + 1); + + CompilationUnit cu; + try { + cu = StaticJavaParser.parse(Files.readString(Path.of(filename))); + } catch (IOException e) { + display("Error: failed to read file `" + filename + "`: " + e.getMessage(), "text/markdown"); + return; + } + + Optional clazz = cu.getClassByName(className); + if (clazz.isEmpty()) { + display("Class `" + fqcn + "` not found in file `" + filename + "`.", "text/markdown"); + return; + } + + String fullOpt = opts.getOrDefault("full", "true"); + boolean full = fullOpt.equalsIgnoreCase("true") || fullOpt.equals("1"); + boolean includeJavadoc = opts.getOrDefault("javadoc", "false").equalsIgnoreCase("true"); + String filter = pos.size() >= 2 ? pos.get(1) : null; + final java.util.regex.Pattern pattern; + if (filter != null && !filter.isBlank()) { + java.util.regex.Pattern tmp; + try { + tmp = java.util.regex.Pattern.compile(filter); + } catch (Exception e) { + tmp = java.util.regex.Pattern.compile(java.util.regex.Pattern.quote(filter)); + } + pattern = tmp; + } else { + pattern = null; + } + + StringBuilder sb = new StringBuilder(); + // Default: list only field names (no attributes). Use `--full=true` to include + // types/modifiers/source. + clazz.get().getFields().forEach(f -> { + java.util.List matched = new java.util.ArrayList<>(); + for (com.github.javaparser.ast.body.VariableDeclarator v : f.getVariables()) { + String n = v.getNameAsString(); + if (pattern == null || pattern.matcher(n).find()) + matched.add(n); + } + + if (matched.isEmpty()) + return; + + if (full) { + // show full declaration(s) for the field + sb.append(f.getVariables().stream() + .map(v -> f.getElementType().asString() + " " + v.getNameAsString()) + .collect(Collectors.joining(", "))) + .append(" (modifiers: ") + .append(f.getModifiers().stream().map(Object::toString).collect(Collectors.joining(" "))) + .append(")\n\n"); + sb.append(f.toString()).append("\n\n"); + if (includeJavadoc) { + String j = f.getJavadoc().map(JavaMagics::renderJavadoc).orElse(null); + if (j != null && !j.isEmpty()) + sb.append(j).append("\n\n"); + } + } else { + for (String name : matched) { + sb.append(name).append("\n"); + } + sb.append("\n"); + } + }); + + if (sb.isEmpty()) + sb.append("(no matching fields)\n"); + + OutputUtils.formatAndDisplay(sb.toString(), opts); + } + + @CellMagic("javasrcJavadoc") + public void javasrcJavadoc(List args, String body) throws IOException { + Map opts = OptionUtils.parseOptions(args); + List pos = OptionUtils.positionalArgs(args); + + if (pos.isEmpty()) { + display("Error: expected usage `%%javasrcJavadoc [memberName]`", "text/markdown"); + return; + } + + String fqcn = pos.get(0); + String member = pos.size() >= 2 ? pos.get(1) : null; + String filename = body; + if ((filename == null || filename.isBlank()) && fqcn != null && fqcn.contains(".")) { + Optional p = PathResolver.resolveSourceFileForClass(fqcn, opts); + if (p.isPresent()) + filename = p.get().toString(); + } + + String className = fqcn.substring(fqcn.lastIndexOf('.') + 1); + + CompilationUnit cu; + try { + cu = StaticJavaParser.parse(Files.readString(Path.of(filename))); + } catch (IOException e) { + display("Error: failed to read file `" + filename + "`: " + e.getMessage(), "text/markdown"); + return; + } + + Optional clazz = cu.getClassByName(className); + if (clazz.isEmpty()) { + display("Class `" + fqcn + "` not found in file `" + filename + "`.", "text/markdown"); + return; + } + + if (member == null) { + String out = clazz.get().getJavadoc().map(JavaMagics::renderJavadoc).orElse("(no javadoc)"); + if (opts.getOrDefault("format", "fenced").equals("raw")) + OutputUtils.formatAndDisplay(out, opts); + else + display(out, "text/markdown"); + return; + } + + // try methods + Optional m = clazz.get().getMethodsByName(member).stream() + .findFirst(); + if (m.isPresent()) { + String out = m.get().getJavadoc().map(JavaMagics::renderJavadoc).orElse("(no javadoc)"); + if (opts.getOrDefault("format", "fenced").equals("raw")) + OutputUtils.formatAndDisplay(out, opts); + else + display(out, "text/markdown"); + return; + } + + // try fields + Optional f = clazz.get().getFieldByName(member); + if (f.isPresent()) { + String out = f.get().getJavadoc().map(JavaMagics::renderJavadoc).orElse("(no javadoc)"); + if (opts.getOrDefault("format", "fenced").equals("raw")) + OutputUtils.formatAndDisplay(out, opts); + else + display(out, "text/markdown"); + return; + } + + display("Member `" + member + "` not found in class `" + fqcn + "`.", "text/markdown"); + } + +} diff --git a/src/main/java/io/github/spencerpark/ijava/magics/JavaPlantUMLMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/JavaPlantUMLMagics.java index 0a69a26..6f98404 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/JavaPlantUMLMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/JavaPlantUMLMagics.java @@ -28,9 +28,13 @@ public class JavaPlantUMLMagics { */ @CellMagic("plantUML") public void plantUML(List args, String body) throws IOException { - // args may include a format (SVG/PNG) and/or a flag to show source for debugging. - boolean showSource = args.stream().anyMatch(a -> a.equalsIgnoreCase("showSource") || a.equalsIgnoreCase("show-source") || a.equals("--show-source") || a.equals("-s") || a.equalsIgnoreCase("source")); - String fileFormat = args.stream().filter(a -> a.equalsIgnoreCase("SVG") || a.equalsIgnoreCase("PNG")).findFirst().orElse("SVG"); + // args may include a format (SVG/PNG) and/or a flag to show source for + // debugging. + boolean showSource = args.stream() + .anyMatch(a -> a.equalsIgnoreCase("showSource") || a.equalsIgnoreCase("show-source") + || a.equals("--show-source") || a.equals("-s") || a.equalsIgnoreCase("source")); + String fileFormat = args.stream().filter(a -> a.equalsIgnoreCase("SVG") || a.equalsIgnoreCase("PNG")) + .findFirst().orElse("SVG"); SourceStringReader reader = new SourceStringReader(body); final ByteArrayOutputStream os = new ByteArrayOutputStream(); @@ -46,7 +50,8 @@ public void plantUML(List args, String body) throws IOException { if (fileFormat.equals("SVG")) { String svg = new String(os.toByteArray(), StandardCharsets.UTF_8); int idx = svg.indexOf(" 0) svg = svg.substring(idx); + if (idx > 0) + svg = svg.substring(idx); out = svg; } else { out = ImageIO.read(new ByteArrayInputStream(os.toByteArray())); @@ -78,7 +83,8 @@ public void plantUMLFile(List args, String body) { body.lines().forEach(filename -> { try { Object out = cellMagic("plantUML", args, Files.readString(Paths.get(filename))); - // The invoked cell magic may perform its own display and return null; only display non-null results. + // The invoked cell magic may perform its own display and return null; only + // display non-null results. if (out != null) { outList.add(out); display(out, fileFormat.equals("SVG") ? "image/svg+xml" : "image/png"); @@ -89,10 +95,12 @@ public void plantUMLFile(List args, String body) { } catch (RuntimeException e) { // Bubble up with context to help debugging log.error("Error running plantUML magic for file {}", filename, e); - throw new RuntimeException("Error running plantUML magic for file " + filename + ": " + e.getMessage(), e); + throw new RuntimeException("Error running plantUML magic for file " + filename + ": " + e.getMessage(), + e); } }); - // if caller expects a combined representation, nothing to return here; outputs have been displayed + // if caller expects a combined representation, nothing to return here; outputs + // have been displayed } diff --git a/src/main/java/io/github/spencerpark/ijava/magics/MagicsTool.java b/src/main/java/io/github/spencerpark/ijava/magics/MagicsTool.java index db036ab..27e8664 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/MagicsTool.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/MagicsTool.java @@ -34,10 +34,17 @@ import java.io.*; import java.lang.reflect.Field; +import java.lang.reflect.Constructor; +import java.lang.reflect.Method; +import java.lang.reflect.Modifier; +import java.lang.annotation.Annotation; import java.nio.file.Files; import java.nio.file.Path; import java.util.Collection; import java.util.Optional; +import java.util.Arrays; +import java.net.URL; +import io.github.spencerpark.ijava.runtime.Display; import java.util.Collections; import java.util.List; import java.util.Map; @@ -71,7 +78,7 @@ public void listCellMagic(List args) { } } - @LineMagic(aliases = {"list"}) + @LineMagic(aliases = { "list" }) public void listMagic(List args) { listLineMagic(Collections.emptyList()); listCellMagic(Collections.emptyList()); @@ -79,24 +86,178 @@ public void listMagic(List args) { @LineMagic(value = "cmd") public void runCommand(List args) throws IOException { - if (args.isEmpty()) return; + if (args.isEmpty()) + return; Process proc = Runtime.getRuntime().exec(args.toArray(new String[0])); String s; try (InputStreamReader inputStreamReader = new InputStreamReader(proc.getInputStream()); - BufferedReader bufferedReader = new BufferedReader(inputStreamReader)) { + BufferedReader bufferedReader = new BufferedReader(inputStreamReader)) { while ((s = bufferedReader.readLine()) != null) { System.out.println(s); } } try (InputStreamReader inputStreamReader = new InputStreamReader(proc.getErrorStream()); - BufferedReader bufferedReader = new BufferedReader(inputStreamReader)) { + BufferedReader bufferedReader = new BufferedReader(inputStreamReader)) { while ((s = bufferedReader.readLine()) != null) { System.err.println(s); } } } + @LineMagic(value = "reload-class") + public void reloadClass(List args) { + if (args.isEmpty()) { + System.out.println("Usage: %reload-class "); + return; + } + String fqcn = args.get(0); + try { + // Best-effort: force class initialization using context classloader + Class c = Class.forName(fqcn, true, Thread.currentThread().getContextClassLoader()); + System.out.printf("Loaded class %s (loader=%s)%n", c.getName(), c.getClassLoader()); + } catch (Throwable t) { + System.out.printf("Failed to load/initialize %s: %s%n", fqcn, t.getMessage()); + } + } + + @LineMagic(value = "class-info") + public void classInfo(List args) { + if (args.isEmpty()) { + System.out.println("Usage: %class-info "); + return; + } + + String fqcn = args.get(0); + try { + Class c = Class.forName(fqcn, false, Thread.currentThread().getContextClassLoader()); + + StringBuilder md = new StringBuilder(); + md.append("# ").append(c.getName()).append("\n\n"); + md.append("- Package: ") + .append(c.getPackage() == null ? "(default)" : c.getPackage().getName()).append("\n"); + md.append("- Modifiers: ").append(Modifier.toString(c.getModifiers())).append("\n"); + md.append("- Classloader: ").append(String.valueOf(c.getClassLoader())).append("\n\n"); + + Annotation[] ann = c.getAnnotations(); + if (ann != null && ann.length > 0) { + md.append("## Annotations\n"); + for (Annotation a : ann) + md.append("- ").append(a.toString()).append("\n"); + md.append("\n"); + } + + md.append("## Constructors\n"); + for (Constructor ctor : c.getDeclaredConstructors()) { + md.append("- ") + .append(Modifier.toString(ctor.getModifiers())).append(" ") + .append(ctor.getName()).append("(") + .append(Arrays.stream(ctor.getParameterTypes()).map(Class::getSimpleName) + .collect(Collectors.joining(", "))) + .append(")\n"); + } + + md.append("\n## Fields\n"); + for (Field f : c.getDeclaredFields()) { + md.append("- ") + .append(Modifier.toString(f.getModifiers())).append(" ") + .append(f.getType().getSimpleName()).append(" ") + .append(f.getName()).append("\n"); + } + + md.append("\n## Methods\n"); + for (Method m : c.getDeclaredMethods()) { + md.append("- ") + .append(Modifier.toString(m.getModifiers())).append(" ") + .append(m.getReturnType().getSimpleName()).append(" ") + .append(m.getName()).append("(") + .append(Arrays.stream(m.getParameterTypes()).map(Class::getSimpleName) + .collect(Collectors.joining(", "))) + .append(")\n"); + } + + Display.display(md.toString(), "text/markdown"); + } catch (Throwable t) { + System.out.printf("Failed to inspect %s: %s%n", fqcn, t.getMessage()); + } + } + + @LineMagic(value = "javadoc-html") + public void javadocHtml(List args) { + if (args.isEmpty()) { + System.out.println("Usage: %javadoc-html "); + return; + } + + String fqcn = args.get(0); + try { + Optional opt = PathResolver.resolveSourceFileForClass(fqcn, Collections.emptyMap()); + if (opt.isEmpty()) { + System.out.printf("Source not found for: %s%n", fqcn); + return; + } + + Path p = opt.get(); + String src = String.join("\n", Files.readAllLines(p)); + String simple = fqcn.substring(fqcn.lastIndexOf('.') + 1); + int idx = src.indexOf("class " + simple); + if (idx == -1) + idx = src.indexOf("interface " + simple); + if (idx == -1) + idx = src.indexOf("enum " + simple); + if (idx == -1) { + System.out.println("No class declaration found in source"); + return; + } + + int start = src.lastIndexOf("/**", idx); + if (start == -1) { + System.out.printf("No javadoc found for %s%n", fqcn); + return; + } + int end = src.indexOf("*/", start); + if (end == -1) + end = idx; + String comment = src.substring(start, end + 2); + + String html = "
" + "
" + escapeHtml(comment) + "
" + "
"; + Display.display(html, "text/html"); + } catch (Exception e) { + System.out.printf("Error: %s%n", e.getMessage()); + } + } + + @LineMagic(value = "where", aliases = { "which" }) + public void where(List args) { + if (args.isEmpty()) { + System.out.println("Usage: %where "); + return; + } + + String fqcn = args.get(0); + String resourcePath = fqcn.replace('.', '/') + ".class"; + URL res = Thread.currentThread().getContextClassLoader().getResource(resourcePath); + if (res != null) { + System.out.printf("%s -> %s%n", fqcn, res.toString()); + } else { + try { + Class c = Class.forName(fqcn, false, Thread.currentThread().getContextClassLoader()); + if (c.getProtectionDomain() != null && c.getProtectionDomain().getCodeSource() != null + && c.getProtectionDomain().getCodeSource().getLocation() != null) { + System.out.printf("%s -> %s%n", fqcn, + c.getProtectionDomain().getCodeSource().getLocation().toString()); + } else { + System.out.printf("No location found for %s%n", fqcn); + } + } catch (Throwable t) { + System.out.printf("Class not found in classpath: %s%n", fqcn); + } + } + + Optional src = PathResolver.resolveSourceFileForClass(fqcn, Collections.emptyMap()); + src.ifPresent(path -> System.out.printf("Source: %s%n", path.toAbsolutePath().toString())); + } + @LineMagic(value = "read") public String readFromFile(List args) throws IOException { if (args.isEmpty()) { @@ -130,7 +291,8 @@ public String loadFile(List args) throws IOException { // try to find matching file in workspace try { Optional found = Files.walk(Path.of(".")).filter(f -> f.endsWith(raw)).findFirst(); - if (found.isPresent()) p = found.get(); + if (found.isPresent()) + p = found.get(); } catch (IOException e) { // ignore search errors } @@ -144,7 +306,8 @@ public String loadFile(List args) throws IOException { return String.join("\n", Files.readAllLines(p)); } catch (Exception e) { - log.warn("%load: error loading '{}': {}", raw, e.getMessage() == null ? e.getClass().getSimpleName() : e.getMessage()); + log.warn("%load: error loading '{}': {}", raw, + e.getMessage() == null ? e.getClass().getSimpleName() : e.getMessage()); return null; } } @@ -162,12 +325,14 @@ public void writeToFile(List args) throws IOException { return; } - if (evaluator == null) getEvaluator(); + if (evaluator == null) + getEvaluator(); Object content; try { content = evaluator.eval(args.get(0)); } catch (Exception e) { - throw new RuntimeException("eval variable `" + args.get(0) + "` error, variable not found or illegal express!"); + throw new RuntimeException( + "eval variable `" + args.get(0) + "` error, variable not found or illegal express!"); } List argsLast = args.size() > 1 ? Collections.singletonList(args.get(1)) : Collections.emptyList(); @@ -190,13 +355,15 @@ public void writeToFile(List args, String body) throws IOException { } @SuppressWarnings("unchecked") - private Collection getMagicsName(Magics magics, String fieldName) throws NoSuchFieldException, IllegalAccessException { + private Collection getMagicsName(Magics magics, String fieldName) + throws NoSuchFieldException, IllegalAccessException { Field field = magics.getClass().getDeclaredField(fieldName); field.setAccessible(true); Map> lineMagics = (Map>) field.get(magics); return lineMagics.entrySet() .stream() - .collect(Collectors.groupingBy(Map.Entry::getValue, Collectors.mapping(Map.Entry::getKey, Collectors.joining(", ")))) + .collect(Collectors.groupingBy(Map.Entry::getValue, + Collectors.mapping(Map.Entry::getKey, Collectors.joining(", ")))) .values(); } @@ -210,4 +377,14 @@ public void getEvaluator() { throw new RuntimeException("Compiler get JShell evaluator instance error." + e.getMessage()); } } + + private static String escapeHtml(String s) { + if (s == null) + return ""; + return s.replace("&", "&") + .replace("<", "<") + .replace(">", ">") + .replace("\"", """) + .replace("'", "'"); + } } diff --git a/src/main/java/io/github/spencerpark/ijava/magics/MavenResolver.java b/src/main/java/io/github/spencerpark/ijava/magics/MavenResolver.java index ad8790f..57d68a0 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/MavenResolver.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/MavenResolver.java @@ -46,7 +46,8 @@ import java.util.regex.Pattern; public class MavenResolver { - private static final String DEFAULT_REPO_LOCAL = String.format("%s/.m2/repository", System.getProperty("user.home")); + private static final String DEFAULT_REPO_LOCAL = String.format("%s/.m2/repository", + System.getProperty("user.home")); private static final String DEFAULT_REPO_TYPE = "default"; private final Consumer addToClasspath; @@ -69,7 +70,7 @@ public void addJarsToClasspath(Iterable jars) { jars.forEach(this.addToClasspath); } - @LineMagic(aliases = {"addMavenDependency", "maven"}) + @LineMagic(aliases = { "addMavenDependency", "maven" }) public void addMavenDependencies(List args) { try { this.addJarsToClasspath(ResolveDependency.resolve(args, null, DEFAULT_REPO_LOCAL, remoteRepos)); @@ -78,7 +79,7 @@ public void addMavenDependencies(List args) { } } - @LineMagic(aliases = {"mavenRepo"}) + @LineMagic(aliases = { "mavenRepo" }) public void addMavenRepo(List args) { MagicsArgs schema = MagicsArgs.builder().required("id").required("url").build(); Map> argData = schema.parse(args); @@ -88,8 +89,12 @@ public void addMavenRepo(List args) { this.addRemoteRepo(id, url); } - @CellMagic(aliases = {"pom"}) + @CellMagic(aliases = { "pom" }) + @Deprecated(forRemoval = true) public void loadFromPOM(List args, String body) throws Exception { + System.err.println("⚠️ WARNING: Cell magic %%pom is deprecated and will be removed in a future version."); + System.err.println( + " Use line magic %pom with a file path instead, or use %addMavenDependencies for inline dependencies."); try { Matcher reposMatcher = reposPattern.matcher(body); String repos = reposMatcher.find() ? reposMatcher.group("repos") : ""; @@ -104,24 +109,58 @@ public void loadFromPOM(List args, String body) throws Exception { } } - @LineMagic(aliases = {"pom"}) + @LineMagic(aliases = { "pom" }) public void loadFromPOM(List args) { if (args.isEmpty()) throw new IllegalArgumentException("Loading from POM requires at least the path to the POM file"); MagicsArgs schema = MagicsArgs.builder() .required("pomPath") + .flag("help", 'h', "Show help") .onlyKnownKeywords().onlyKnownFlags().build(); Map> argMap = schema.parse(args); + // Show help if requested + if (argMap.containsKey("help")) { + System.out.println(""" + ## %pom - Load dependencies from a Maven POM file + + **Usage:** `%pom [--help] path/to/pom.xml` + + **Arguments:** + - `pomPath` : Path to the POM file (required) + + **Options:** + - `--help, -h` : Show this help message + + **Description:** + Parses a Maven POM file and adds all dependencies to the notebook classpath. + Also registers any repositories defined in the POM. + + **Examples:** + ``` + %pom pom.xml + ``` + + ``` + %pom ../my-project/pom.xml + ``` + + **See also:** + - `%addMavenDependencies` / `%maven` - Add individual Maven coordinates + - `%mavenRepo` - Add a Maven repository + """); + return; + } + String pomPath = argMap.get("pomPath").get(0); try { MavenXpp3Reader reader = new MavenXpp3Reader(); Model model = reader.read(new FileReader(pomPath, StandardCharsets.UTF_8)); resolveModel(model); - } catch (IOException | XmlPullParserException | DependencyResolutionException | - NoLocalRepositoryManagerException e) { + } catch (IOException | XmlPullParserException | DependencyResolutionException + | NoLocalRepositoryManagerException e) { throw new RuntimeException(e); } } diff --git a/src/main/java/io/github/spencerpark/ijava/magics/OptionUtils.java b/src/main/java/io/github/spencerpark/ijava/magics/OptionUtils.java index 43e0edb..791a2be 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/OptionUtils.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/OptionUtils.java @@ -3,12 +3,18 @@ import java.util.*; public final class OptionUtils { - private OptionUtils() {} + private OptionUtils() { + } public static Map parseOptions(List args) { Map opts = new HashMap<>(); for (int i = 0; i < args.size(); i++) { String a = args.get(i); + if (a.equals("--help") || a.equals("-h")) { + opts.put("--help", ""); + opts.put("-h", ""); + continue; + } if (a.equals("--raw")) { opts.put("format", "raw"); } else if (a.equals("--fenced")) { @@ -35,7 +41,8 @@ public static Map parseOptions(List args) { public static List positionalArgs(List args) { return args.stream() - .filter(a -> !a.equals("--raw") && !a.equals("--fenced") && !a.startsWith("--src") && !a.startsWith("--root") && !a.contains("=")) + .filter(a -> !a.equals("--raw") && !a.equals("--fenced") && !a.startsWith("--src") + && !a.startsWith("--root") && !a.contains("=")) .toList(); } } diff --git a/src/main/java/io/github/spencerpark/ijava/magics/OutputUtils.java b/src/main/java/io/github/spencerpark/ijava/magics/OutputUtils.java index b74f786..1331526 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/OutputUtils.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/OutputUtils.java @@ -4,7 +4,8 @@ import static io.github.spencerpark.ijava.runtime.Display.display; public final class OutputUtils { - private OutputUtils() {} + private OutputUtils() { + } public static void formatAndDisplay(String content, Map opts) { boolean raw = opts.getOrDefault("format", "fenced").equals("raw"); diff --git a/src/main/java/io/github/spencerpark/ijava/magics/PathResolver.java b/src/main/java/io/github/spencerpark/ijava/magics/PathResolver.java index 8c05204..986f0e4 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/PathResolver.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/PathResolver.java @@ -9,12 +9,15 @@ import java.util.Optional; public final class PathResolver { - private PathResolver() {} + private PathResolver() { + } - public static Optional resolveSourceFileForClass(String fullyQualifiedClassName, java.util.Map opts) { + public static Optional resolveSourceFileForClass(String fullyQualifiedClassName, + java.util.Map opts) { String srcBase = opts.getOrDefault("src", null); List bases = new ArrayList<>(); - if (srcBase != null && !srcBase.isBlank()) bases.add(srcBase); + if (srcBase != null && !srcBase.isBlank()) + bases.add(srcBase); bases.add("src/main/java"); bases.add("src"); bases.add("docs/notebooks/sample_java"); @@ -25,16 +28,21 @@ public static Optional resolveSourceFileForClass(String fullyQualifiedClas for (String base : bases) { Path p = Paths.get(base).resolve(rel); - if (Files.exists(p)) return Optional.of(p); + if (Files.exists(p)) + return Optional.of(p); Path p2 = Paths.get(base).resolve("src/main/java").resolve(rel); - if (Files.exists(p2)) return Optional.of(p2); + if (Files.exists(p2)) + return Optional.of(p2); } try { final String simple = className + ".java"; - Optional found = Files.walk(Paths.get(".")).filter(Files::isRegularFile).filter(p -> p.getFileName().toString().equals(simple)).findFirst(); - if (found.isPresent()) return found; - } catch (IOException ignored) {} + Optional found = Files.walk(Paths.get(".")).filter(Files::isRegularFile) + .filter(p -> p.getFileName().toString().equals(simple)).findFirst(); + if (found.isPresent()) + return found; + } catch (IOException ignored) { + } return Optional.empty(); } diff --git a/src/main/java/io/github/spencerpark/ijava/magics/ShellMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/ShellMagics.java index e2742cd..2e21b70 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/ShellMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/ShellMagics.java @@ -29,7 +29,9 @@ import java.io.InputStreamReader; import java.util.function.Consumer; import java.util.List; +import java.util.Map; import java.util.concurrent.Executors; +import java.util.concurrent.TimeUnit; import io.github.spencerpark.jupyter.kernel.magic.registry.CellMagic; import lombok.extern.slf4j.Slf4j; @@ -54,7 +56,58 @@ public void run() { @CellMagic("shell") public void shell(List args, String body) throws InterruptedException, IOException { - String[] commands = { "zsh", "-c", body }; + Map opts = OptionUtils.parseOptions(args); + + // Show help if requested + if (opts.containsKey("--help") || opts.containsKey("-h")) { + System.out.println(""" + ## %%shell - Execute shell commands + + **Usage:** `%%shell [--shell=SHELL] [--timeout=SECONDS]` + + **Options:** + - `--shell=SHELL` : Shell to use (default: zsh, or $SHELL environment variable) + - `--timeout=SECONDS` : Maximum execution time in seconds (default: 180) + - `--help, -h` : Show this help message + + **Examples:** + ``` + %%shell + ls -la + ``` + + ``` + %%shell --shell=bash + echo "Using bash" + ``` + + ``` + %%shell --timeout=60 + long-running-command + ``` + """); + return; + } + + // Determine shell to use + String shell = opts.getOrDefault("--shell", System.getenv("SHELL")); + if (shell == null || shell.isEmpty()) { + shell = "zsh"; + } + + // Get timeout (default 3 minutes) + long timeout = 180; + if (opts.containsKey("--timeout")) { + try { + timeout = Long.parseLong(opts.get("--timeout")); + } catch (NumberFormatException e) { + log.warn("Invalid timeout value, using default: 180 seconds"); + } + } + + log.debug("Running shell command with {}: {}", shell, body); + + String[] commands = { shell, "-c", body }; Process process; try { process = new ProcessBuilder() @@ -63,13 +116,34 @@ public void shell(List args, String body) throws InterruptedException, I StreamGobbler streamGobblerErr = new StreamGobbler(process.getErrorStream(), System.err::println); Executors.newSingleThreadExecutor().submit(streamGobbler); Executors.newSingleThreadExecutor().submit(streamGobblerErr); - process.waitFor(); + + boolean finished = process.waitFor(timeout, TimeUnit.SECONDS); + if (!finished) { + process.destroyForcibly(); + throw new RuntimeException("Command timed out after " + timeout + " seconds"); + } } catch (IOException e) { log.error("Error while running shell command", e); - throw e; + throw e; } catch (InterruptedException e) { log.error("Error while waiting for process to finish", e); throw e; } } + + @CellMagic("myshell") + @Deprecated(forRemoval = true) + public void myshell(List args, String body) throws InterruptedException, IOException { + System.err.println( + "⚠️ WARNING: %%myshell is deprecated and will be removed in a future version. Use %%shell instead."); + shell(args, body); + } + + @CellMagic("commonshell") + @Deprecated(forRemoval = true) + public void commonshell(List args, String body) throws InterruptedException, IOException { + System.err.println( + "⚠️ WARNING: %%commonshell is deprecated and will be removed in a future version. Use %%shell instead."); + shell(args, body); + } } diff --git a/src/main/java/io/github/spencerpark/ijava/magics/TimeItMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/TimeItMagics.java index bc78912..68cd909 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/TimeItMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/TimeItMagics.java @@ -34,9 +34,10 @@ public class TimeItMagics { private final int epochs = 3; private final int loops = 5; - @CellMagic(aliases = {"time", "timeit"}) + @CellMagic(aliases = { "time", "timeit" }) public void timeIt(List args, String body) throws Exception { - if (args == null) args = Collections.emptyList(); + if (args == null) + args = Collections.emptyList(); if (!args.isEmpty() && ("-h".equals(args.get(0)) || "--help".equals(args.get(0)))) { System.out.println("help: \nexample: \n"); @@ -44,39 +45,38 @@ public void timeIt(List args, String body) throws Exception { return; } - // parse input args + // parse input args like epochs=3 loops=5 warmup=1 iterations=10 Map params = args.stream() .map(arg -> arg.split("=")) - .filter(kv -> kv.length > 0 && StringUtils.isNotEmpty(kv[0]) && StringUtils.isNotEmpty(kv[1]) && kv[1].matches("\\d+")) + .filter(kv -> kv.length > 1 && StringUtils.isNotEmpty(kv[0]) && StringUtils.isNotEmpty(kv[1]) + && kv[1].matches("\\d+")) .collect(Collectors.toMap(kv -> kv[0], kv -> Integer.parseInt(kv[1]))); - // for each epoch - Integer epochNum = params.getOrDefault("epochs", epochs); - Integer loopNum = params.getOrDefault("loops", loops); - List> epochData = new ArrayList<>(epochNum); - for (int i = 0; i < epochNum; i++) { - // for each loop - List loopData = new ArrayList<>(loopNum); - for (int j = 0; j < loopNum; j++) { - loopData.add(System.currentTimeMillis()); - IJava.getKernelInstance().evalRaw(body); - loopData.add(System.currentTimeMillis()); - } - epochData.add(loopData); + int warmup = params.getOrDefault("warmup", 1); + int iterations = params.getOrDefault("iterations", 5); + + List samples = new ArrayList<>(iterations); + + for (int w = 0; w < warmup; w++) { + IJava.getKernelInstance().evalRaw(body); } - // Summary Statistics - List> epochDiff = new ArrayList<>(epochData.size()); - for (int i = 0; i < epochData.size(); i++) { - List loopData = epochData.get(i); - List diff = new ArrayList<>(loopData.size() / 2); - for (int j = 0; j < loopData.size() / 2; j++) { - diff.add(loopData.get(i * 2 + 1) - loopData.get(i * 2)); - } - LongSummaryStatistics statistics = diff.stream().collect(Collectors.summarizingLong(o -> o)); - System.out.printf("epoch %d: %s%n", i, statistics); - epochDiff.add(diff); + for (int i = 0; i < iterations; i++) { + long start = System.nanoTime(); + IJava.getKernelInstance().evalRaw(body); + long end = System.nanoTime(); + samples.add(end - start); } - System.out.printf("total: %s%n", epochDiff.stream().flatMap(Collection::stream).collect(Collectors.summarizingLong(o -> o))); + + // compute statistics + long min = samples.stream().mapToLong(Long::longValue).min().orElse(0L); + long max = samples.stream().mapToLong(Long::longValue).max().orElse(0L); + double avg = samples.stream().mapToLong(Long::longValue).average().orElse(0.0); + List sorted = new ArrayList<>(samples); + Collections.sort(sorted); + long median = sorted.get(sorted.size() / 2); + + System.out.printf("samples: %s\n", samples); + System.out.printf("min=%d median=%d avg=%.2f max=%d (nanoseconds)\n", min, median, avg, max); } } diff --git a/src/main/resources/install.py b/src/main/resources/install.py index a29c835..67391f8 100644 --- a/src/main/resources/install.py +++ b/src/main/resources/install.py @@ -191,15 +191,14 @@ def __call__(self, parser, namespace, value, option_string=None): ) kernel_json_json_contents = json.loads(kernel_json_contents) - # If the distribution contains a jar in the installed 'java' folder, + # If the distribution contains a jar in the installed directory, # set argv[2] to that jar path so the kernelspec points at the real file. try: - java_dir = os.path.join(install_dest, 'java') - if os.path.isdir(java_dir): - # prefer any jar (first alphabetical) - this will be the renamed shadow jar - jars = sorted([f for f in os.listdir(java_dir) if f.endswith('.jar')]) + if os.path.isdir(install_dest): + # prefer any jar (last alphabetically) - this will be the renamed shadow jar + jars = sorted([f for f in os.listdir(install_dest) if f.endswith('.jar')]) if jars: - jar_path = os.path.join(install_dest, 'java', jars[-1]) + jar_path = os.path.join(install_dest, jars[-1]) argv = kernel_json_json_contents.get('argv') if isinstance(argv, list) and len(argv) > 2: argv[2] = jar_path diff --git a/src/test/java/io/github/spencerpark/ijava/magics/DBMSMagicsIntegrationTest.java b/src/test/java/io/github/spencerpark/ijava/magics/DBMSMagicsIntegrationTest.java index 431b5cf..978106a 100644 --- a/src/test/java/io/github/spencerpark/ijava/magics/DBMSMagicsIntegrationTest.java +++ b/src/test/java/io/github/spencerpark/ijava/magics/DBMSMagicsIntegrationTest.java @@ -4,5 +4,6 @@ package io.github.spencerpark.ijava.magics; public class DBMSMagicsIntegrationTest { - // placeholder: tests run from notebooks using %maven to load H2 and other dependencies + // placeholder: tests run from notebooks using %maven to load H2 and other + // dependencies } diff --git a/src/test/java/io/github/spencerpark/ijava/magics/SingleShellMagicsTest.java b/src/test/java/io/github/spencerpark/ijava/magics/SingleShellMagicsTest.java index 48081a6..c7cb945 100644 --- a/src/test/java/io/github/spencerpark/ijava/magics/SingleShellMagicsTest.java +++ b/src/test/java/io/github/spencerpark/ijava/magics/SingleShellMagicsTest.java @@ -6,6 +6,7 @@ import java.io.IOException; import java.util.Collections; +import java.util.List; import static org.junit.Assert.assertNotNull; import static org.junit.Assert.assertTrue; @@ -15,7 +16,7 @@ public class SingleShellMagicsTest { private SingleShellMagics singleShellMagics; @Before - public void setUp() { + public void setUp() throws IOException { singleShellMagics = new SingleShellMagics(); } @@ -25,17 +26,27 @@ public void tearDown() { } @Test - public void testShell() throws IOException { - singleShellMagics.shell(Collections.emptyList(), "echo Hello, World!"); - singleShellMagics.shell(Collections.emptyList(), "echo Variable Test"); + public void testCommonShell() throws IOException, InterruptedException { + String result = singleShellMagics.commonshell(Collections.emptyList(), "echo Hello, World!"); + assertNotNull(result); + result = singleShellMagics.commonshell(Collections.emptyList(), "echo Variable Test"); + assertNotNull(result); } @Test - public void testShellWithVariables() throws IOException { + public void testCommonShellWithVariables() throws IOException, InterruptedException { String var1 = "Hello"; String var2 = "World"; - singleShellMagics.shell(Collections.emptyList(), "echo " + var1 + ", " + var2 + "!"); - singleShellMagics.shell(Collections.emptyList(), "echo Testing " + var1 + " and " + var2); + String result = singleShellMagics.commonshell(Collections.emptyList(), "echo " + var1 + ", " + var2 + "!"); + assertNotNull(result); + result = singleShellMagics.commonshell(Collections.emptyList(), "echo Testing " + var1 + " and " + var2); + assertNotNull(result); } -} \ No newline at end of file + @Test + public void testCommonShellCmd() throws IOException, InterruptedException { + String result = singleShellMagics.commonshellcmd(List.of("echo", "test")); + assertNotNull(result); + } + +} From 2900315b11ad2c645e1214f16cebcbb2ab46bdc2 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Fri, 16 Jan 2026 10:01:29 +0100 Subject: [PATCH 09/49] chore(ci): versioned distro + prerelease workflow and smoke test --- .github/workflows/build-release.yml | 230 ++++++++++++++++++++++++---- build.gradle | 2 +- 2 files changed, 204 insertions(+), 28 deletions(-) diff --git a/.github/workflows/build-release.yml b/.github/workflows/build-release.yml index 35c9a52..f57ed73 100644 --- a/.github/workflows/build-release.yml +++ b/.github/workflows/build-release.yml @@ -14,40 +14,216 @@ jobs: build-and-release: runs-on: ubuntu-latest steps: - - name: Checkout - uses: actions/checkout@v4 + name: Build and Release - - name: Set up JDK 21 - uses: actions/setup-java@v4 - with: - distribution: 'temurin' - java-version: '21' - cache: 'gradle' - - - name: Build package - run: | - chmod +x ./gradlew - ./gradlew --no-daemon clean packDist - - - name: Prepare artifact and checksum - run: | - set -euo pipefail - ARTIFACT=$(ls build/distributions/*.zip | head -n1) - if [ -z "${ARTIFACT:-}" ]; then - echo "No distribution zip found in build/distributions" >&2 - ls -la build || true + on: + push: + tags: + - 'v*' + workflow_dispatch: + inputs: + tag: + description: 'Tag name to use for release (required for manual dispatch)' + required: false + prerelease: + description: 'Mark release as prerelease' + required: false + default: 'true' + publish: + description: 'Create GitHub release (if false, workflow only builds and tests)' + required: false + default: 'true' + run_smoke_test: + description: 'Run smoke test before publishing' + required: false + default: 'true' + + permissions: + contents: write + packages: write + + jobs: + build: + name: Build distribution + runs-on: ubuntu-latest + outputs: + tag: ${{ steps.set-tag.outputs.tag }} + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up JDK 21 + uses: actions/setup-java@v4 + with: + distribution: 'temurin' + java-version: '21' + cache: 'gradle' + + - name: Build package + run: | + chmod +x ./gradlew + ./gradlew --no-daemon clean packDist + + - name: Determine tag + id: set-tag + run: | + set -euo pipefail + if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then + if [ -n "${{ github.event.inputs.tag || '' }}" ]; then + echo "tag=${{ github.event.inputs.tag }}" >> $GITHUB_OUTPUT + else + echo "No tag provided for workflow_dispatch; will try to read from project.version" + VER=$(./gradlew -q properties --no-daemon | sed -n 's/^version: //p') + echo "tag=${VER}" >> $GITHUB_OUTPUT + fi + else + # on tag push + echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT + fi + + - name: Prepare artifact and checksum + run: | + set -euo pipefail + TAG=${{ steps.set-tag.outputs.tag }} + ARTIFACT=$(ls build/distributions/*.zip | head -n1) + if [ -z "${ARTIFACT:-}" ]; then + echo "No distribution zip found in build/distributions" >&2 + ls -la build || true + exit 1 + fi + TARGET="build/distributions/IJava-${TAG}.zip" + cp "$ARTIFACT" "$TARGET" + sha256sum "$TARGET" > "$TARGET.sha256" + echo "Prepared $TARGET and checksum" + ls -l "$TARGET" "$TARGET.sha256" + + - name: Upload distribution artifact + uses: actions/upload-artifact@v4 + with: + name: distribution + path: | + build/distributions/IJava-${{ steps.set-tag.outputs.tag }}.zip + build/distributions/IJava-${{ steps.set-tag.outputs.tag }}.zip.sha256 + + smoke-test: + name: Smoke-test distribution + needs: build + runs-on: ubuntu-latest + if: ${{ github.event_name != 'workflow_dispatch' || github.event.inputs.run_smoke_test == 'true' }} + steps: + - name: Download distribution + uses: actions/download-artifact@v4 + with: + name: distribution + + - name: Run smoke test (unpack & start briefly) + run: | + set -euo pipefail + # find the distribution artifact in the workspace + DIST=$(ls -1 *.zip | grep IJava || true) + if [ -z "$DIST" ]; then + echo "Distribution zip not found in artifact" >&2 + ls -la || true + exit 1 + fi + echo "Using distribution: $DIST" + rm -rf smoke && mkdir -p smoke + unzip -q "$DIST" -d smoke + JAR=$(find smoke -type f -name "*-all.jar" -print -quit) + if [ -z "$JAR" ]; then + JAR=$(find smoke -type f -name "*.jar" -print -quit) + fi + if [ -z "$JAR" ]; then + echo "No jar found inside distribution" >&2 + ls -R smoke || true + exit 1 + fi + echo "Found jar: $JAR" + + CONN=$(mktemp --suffix=.json) + python3 - <<'PY' > "$CONN" + import json, random + ports = [random.randint(15000, 30000) for _ in range(5)] + keys = ["shell_port","iopub_port","stdin_port","control_port","hb_port"] + d = dict(zip(keys, ports)) + d.update({"ip": "127.0.0.1", "transport": "tcp", "signature_scheme": "hmac-sha256", "key": ""}) + print(json.dumps(d)) + PY + echo "Connection file: $CONN" + java -jar "$JAR" "$CONN" >/dev/null 2>&1 & + KPID=$! + echo "Kernel PID: $KPID" + sleep 5 + if kill -0 "$KPID" >/dev/null 2>&1; then + echo "Kernel started (PID $KPID) - killing" + kill "$KPID" || true + wait "$KPID" || true + else + echo "Kernel process exited prematurely" >&2 + ps aux | head -n 20 || true + exit 1 + fi + + publish: + name: Create Release + needs: [build, smoke-test] + runs-on: ubuntu-latest + if: ${{ startsWith(github.ref, 'refs/tags/') || (github.event_name == 'workflow_dispatch' && github.event.inputs.publish == 'true') }} + steps: + - name: Download distribution + uses: actions/download-artifact@v4 + with: + name: distribution + + - name: Create GitHub Release and upload assets + uses: softprops/action-gh-release@v1 + with: + body_path: UPGRADE.md + files: | + IJava-${{ github.ref_name }}.zip + IJava-${{ github.ref_name }}.zip.sha256 + prerelease: ${{ github.event_name == 'workflow_dispatch' ? (github.event.inputs.prerelease == 'true') : (contains(github.ref, '-pr') || contains(github.ref, '-rc')) }} + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + echo "Found jar: $JAR" + + # create a minimal jupyter connection file with random free ports + CONN=$(mktemp --suffix=.json) + python3 - <<'PY' > "$CONN" +import json, random +ports = [random.randint(15000, 30000) for _ in range(5)] +keys = ["shell_port","iopub_port","stdin_port","control_port","hb_port"] +d = dict(zip(keys, ports)) +d.update({"ip": "127.0.0.1", "transport": "tcp", "signature_scheme": "hmac-sha256", "key": ""}) +print(json.dumps(d)) +PY + echo "Connection file: $CONN" + + # start the kernel in background and ensure it runs briefly + java -jar "$JAR" "$CONN" >/dev/null 2>&1 & + KPID=$! + echo "Kernel PID: $KPID" + # give it a few seconds to start + sleep 5 + if kill -0 "$KPID" >/dev/null 2>&1; then + echo "Kernel started (PID $KPID) - killing" + kill "$KPID" || true + wait "$KPID" || true + else + echo "Kernel process exited prematurely" >&2 + # show recent logs if any + ps aux | head -n 20 || true exit 1 fi - sha256sum "$ARTIFACT" > "$ARTIFACT.sha256" - echo "Created $ARTIFACT and checksum" - ls -l "$ARTIFACT" "$ARTIFACT.sha256" - name: Create GitHub Release and upload assets if: startsWith(github.ref, 'refs/tags/') uses: softprops/action-gh-release@v1 with: - # include a release body if you maintain UPGRADE.md or CHANGELOG body_path: UPGRADE.md files: | - build/distributions/*.zip - build/distributions/*.zip.sha256 + build/distributions/IJava-${{ github.ref_name }}.zip + build/distributions/IJava-${{ github.ref_name }}.zip.sha256 + prerelease: ${{ contains(github.ref, '-pr') || contains(github.ref, '-rc') }} + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/build.gradle b/build.gradle index 0178f9b..6aa7b12 100644 --- a/build.gradle +++ b/build.gradle @@ -106,7 +106,7 @@ tasks.register('packDist', Zip) { description = 'Creates distribution package' group = 'distribution' - archiveFileName = "${project.name}-latest.zip" + archiveFileName = "${project.name}-${project.version}.zip" from(layout.buildDirectory.dir("resources/main")) { include "install.py" From 390e85ac77f9a5a79bd835b49087afe945ccc8da Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Fri, 16 Jan 2026 10:23:53 +0100 Subject: [PATCH 10/49] fix(ci): clean workflow file structure --- .github/workflows/build-release.yml | 298 +++++++++++----------------- 1 file changed, 119 insertions(+), 179 deletions(-) diff --git a/.github/workflows/build-release.yml b/.github/workflows/build-release.yml index f57ed73..f75d0a9 100644 --- a/.github/workflows/build-release.yml +++ b/.github/workflows/build-release.yml @@ -5,189 +5,122 @@ on: tags: - 'v*' workflow_dispatch: + inputs: + tag: + description: 'Tag name to use for release (optional for manual dispatch)' + required: false + prerelease: + description: 'Mark release as prerelease' + required: false + default: 'true' + publish: + description: 'Create GitHub release (if false, workflow only builds and tests)' + required: false + default: 'true' + run_smoke_test: + description: 'Run smoke test before publishing' + required: false + default: 'true' permissions: contents: write packages: write jobs: - build-and-release: + build: + name: Build distribution runs-on: ubuntu-latest + outputs: + tag: ${{ steps.set-tag.outputs.tag }} steps: - name: Build and Release + - name: Checkout + uses: actions/checkout@v4 - on: - push: - tags: - - 'v*' - workflow_dispatch: - inputs: - tag: - description: 'Tag name to use for release (required for manual dispatch)' - required: false - prerelease: - description: 'Mark release as prerelease' - required: false - default: 'true' - publish: - description: 'Create GitHub release (if false, workflow only builds and tests)' - required: false - default: 'true' - run_smoke_test: - description: 'Run smoke test before publishing' - required: false - default: 'true' - - permissions: - contents: write - packages: write - - jobs: - build: - name: Build distribution - runs-on: ubuntu-latest - outputs: - tag: ${{ steps.set-tag.outputs.tag }} - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Set up JDK 21 - uses: actions/setup-java@v4 - with: - distribution: 'temurin' - java-version: '21' - cache: 'gradle' - - - name: Build package - run: | - chmod +x ./gradlew - ./gradlew --no-daemon clean packDist - - - name: Determine tag - id: set-tag - run: | - set -euo pipefail - if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then - if [ -n "${{ github.event.inputs.tag || '' }}" ]; then - echo "tag=${{ github.event.inputs.tag }}" >> $GITHUB_OUTPUT - else - echo "No tag provided for workflow_dispatch; will try to read from project.version" - VER=$(./gradlew -q properties --no-daemon | sed -n 's/^version: //p') - echo "tag=${VER}" >> $GITHUB_OUTPUT - fi - else - # on tag push - echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT - fi - - - name: Prepare artifact and checksum - run: | - set -euo pipefail - TAG=${{ steps.set-tag.outputs.tag }} - ARTIFACT=$(ls build/distributions/*.zip | head -n1) - if [ -z "${ARTIFACT:-}" ]; then - echo "No distribution zip found in build/distributions" >&2 - ls -la build || true - exit 1 - fi - TARGET="build/distributions/IJava-${TAG}.zip" - cp "$ARTIFACT" "$TARGET" - sha256sum "$TARGET" > "$TARGET.sha256" - echo "Prepared $TARGET and checksum" - ls -l "$TARGET" "$TARGET.sha256" - - - name: Upload distribution artifact - uses: actions/upload-artifact@v4 - with: - name: distribution - path: | - build/distributions/IJava-${{ steps.set-tag.outputs.tag }}.zip - build/distributions/IJava-${{ steps.set-tag.outputs.tag }}.zip.sha256 - - smoke-test: - name: Smoke-test distribution - needs: build - runs-on: ubuntu-latest - if: ${{ github.event_name != 'workflow_dispatch' || github.event.inputs.run_smoke_test == 'true' }} - steps: - - name: Download distribution - uses: actions/download-artifact@v4 - with: - name: distribution - - - name: Run smoke test (unpack & start briefly) - run: | - set -euo pipefail - # find the distribution artifact in the workspace - DIST=$(ls -1 *.zip | grep IJava || true) - if [ -z "$DIST" ]; then - echo "Distribution zip not found in artifact" >&2 - ls -la || true - exit 1 - fi - echo "Using distribution: $DIST" - rm -rf smoke && mkdir -p smoke - unzip -q "$DIST" -d smoke - JAR=$(find smoke -type f -name "*-all.jar" -print -quit) - if [ -z "$JAR" ]; then - JAR=$(find smoke -type f -name "*.jar" -print -quit) - fi - if [ -z "$JAR" ]; then - echo "No jar found inside distribution" >&2 - ls -R smoke || true - exit 1 - fi - echo "Found jar: $JAR" - - CONN=$(mktemp --suffix=.json) - python3 - <<'PY' > "$CONN" - import json, random - ports = [random.randint(15000, 30000) for _ in range(5)] - keys = ["shell_port","iopub_port","stdin_port","control_port","hb_port"] - d = dict(zip(keys, ports)) - d.update({"ip": "127.0.0.1", "transport": "tcp", "signature_scheme": "hmac-sha256", "key": ""}) - print(json.dumps(d)) - PY - echo "Connection file: $CONN" - java -jar "$JAR" "$CONN" >/dev/null 2>&1 & - KPID=$! - echo "Kernel PID: $KPID" - sleep 5 - if kill -0 "$KPID" >/dev/null 2>&1; then - echo "Kernel started (PID $KPID) - killing" - kill "$KPID" || true - wait "$KPID" || true - else - echo "Kernel process exited prematurely" >&2 - ps aux | head -n 20 || true - exit 1 - fi - - publish: - name: Create Release - needs: [build, smoke-test] - runs-on: ubuntu-latest - if: ${{ startsWith(github.ref, 'refs/tags/') || (github.event_name == 'workflow_dispatch' && github.event.inputs.publish == 'true') }} - steps: - - name: Download distribution - uses: actions/download-artifact@v4 - with: - name: distribution + - name: Set up JDK 21 + uses: actions/setup-java@v4 + with: + distribution: 'temurin' + java-version: '21' + cache: 'gradle' + + - name: Build package + run: | + chmod +x ./gradlew + ./gradlew --no-daemon clean packDist + + - name: Determine tag + id: set-tag + run: | + set -euo pipefail + if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then + if [ -n "${{ github.event.inputs.tag || '' }}" ]; then + echo "tag=${{ github.event.inputs.tag }}" >> $GITHUB_OUTPUT + else + VER=$(./gradlew -q properties --no-daemon | sed -n 's/^version: //p') + echo "tag=${VER}" >> $GITHUB_OUTPUT + fi + else + echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT + fi - - name: Create GitHub Release and upload assets - uses: softprops/action-gh-release@v1 - with: - body_path: UPGRADE.md - files: | - IJava-${{ github.ref_name }}.zip - IJava-${{ github.ref_name }}.zip.sha256 - prerelease: ${{ github.event_name == 'workflow_dispatch' ? (github.event.inputs.prerelease == 'true') : (contains(github.ref, '-pr') || contains(github.ref, '-rc')) }} - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + - name: Prepare artifact and checksum + run: | + set -euo pipefail + TAG=${{ steps.set-tag.outputs.tag }} + ARTIFACT=$(ls build/distributions/*.zip | head -n1) + if [ -z "${ARTIFACT:-}" ]; then + echo "No distribution zip found in build/distributions" >&2 + ls -la build || true + exit 1 + fi + TARGET="build/distributions/IJava-${TAG}.zip" + cp "$ARTIFACT" "$TARGET" + sha256sum "$TARGET" > "$TARGET.sha256" + echo "Prepared $TARGET and checksum" + ls -l "$TARGET" "$TARGET.sha256" + + - name: Upload distribution artifact + uses: actions/upload-artifact@v4 + with: + name: distribution + path: | + build/distributions/IJava-${{ steps.set-tag.outputs.tag }}.zip + build/distributions/IJava-${{ steps.set-tag.outputs.tag }}.zip.sha256 + + smoke-test: + name: Smoke-test distribution + needs: build + runs-on: ubuntu-latest + if: ${{ github.event_name != 'workflow_dispatch' || github.event.inputs.run_smoke_test == 'true' }} + steps: + - name: Download distribution + uses: actions/download-artifact@v4 + with: + name: distribution + + - name: Run smoke test (unpack & start briefly) + run: | + set -euo pipefail + DIST=$(ls -1 *.zip | grep IJava || true) + if [ -z "$DIST" ]; then + echo "Distribution zip not found in artifact" >&2 + ls -la || true + exit 1 + fi + echo "Using distribution: $DIST" + rm -rf smoke && mkdir -p smoke + unzip -q "$DIST" -d smoke + JAR=$(find smoke -type f -name "*-all.jar" -print -quit) + if [ -z "$JAR" ]; then + JAR=$(find smoke -type f -name "*.jar" -print -quit) + fi + if [ -z "$JAR" ]; then + echo "No jar found inside distribution" >&2 + ls -R smoke || true + exit 1 + fi echo "Found jar: $JAR" - # create a minimal jupyter connection file with random free ports CONN=$(mktemp --suffix=.json) python3 - <<'PY' > "$CONN" import json, random @@ -198,12 +131,9 @@ d.update({"ip": "127.0.0.1", "transport": "tcp", "signature_scheme": "hmac-sha25 print(json.dumps(d)) PY echo "Connection file: $CONN" - - # start the kernel in background and ensure it runs briefly java -jar "$JAR" "$CONN" >/dev/null 2>&1 & KPID=$! echo "Kernel PID: $KPID" - # give it a few seconds to start sleep 5 if kill -0 "$KPID" >/dev/null 2>&1; then echo "Kernel started (PID $KPID) - killing" @@ -211,19 +141,29 @@ PY wait "$KPID" || true else echo "Kernel process exited prematurely" >&2 - # show recent logs if any ps aux | head -n 20 || true exit 1 fi + publish: + name: Create Release + needs: [build, smoke-test] + runs-on: ubuntu-latest + if: ${{ startsWith(github.ref, 'refs/tags/') || (github.event_name == 'workflow_dispatch' && github.event.inputs.publish == 'true') }} + steps: + - name: Download distribution + uses: actions/download-artifact@v4 + with: + name: distribution + - name: Create GitHub Release and upload assets - if: startsWith(github.ref, 'refs/tags/') uses: softprops/action-gh-release@v1 with: body_path: UPGRADE.md files: | - build/distributions/IJava-${{ github.ref_name }}.zip - build/distributions/IJava-${{ github.ref_name }}.zip.sha256 - prerelease: ${{ contains(github.ref, '-pr') || contains(github.ref, '-rc') }} + IJava-${{ github.ref_name }}.zip + IJava-${{ github.ref_name }}.zip.sha256 + prerelease: ${{ github.event_name == 'workflow_dispatch' ? (github.event.inputs.prerelease == 'true') : (contains(github.ref, '-pr') || contains(github.ref, '-rc')) }} env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + From 839714795b7d09e6bf05a01f17527888a845d078 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Fri, 16 Jan 2026 11:27:15 +0100 Subject: [PATCH 11/49] fix(ci): use python -c instead of heredoc for YAML compatibility --- .github/workflows/build-release.yml | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/.github/workflows/build-release.yml b/.github/workflows/build-release.yml index f75d0a9..f8da131 100644 --- a/.github/workflows/build-release.yml +++ b/.github/workflows/build-release.yml @@ -120,16 +120,9 @@ jobs: exit 1 fi echo "Found jar: $JAR" - + CONN=$(mktemp --suffix=.json) - python3 - <<'PY' > "$CONN" -import json, random -ports = [random.randint(15000, 30000) for _ in range(5)] -keys = ["shell_port","iopub_port","stdin_port","control_port","hb_port"] -d = dict(zip(keys, ports)) -d.update({"ip": "127.0.0.1", "transport": "tcp", "signature_scheme": "hmac-sha256", "key": ""}) -print(json.dumps(d)) -PY + python3 -c 'import json, random; ports = [random.randint(15000, 30000) for _ in range(5)]; keys = ["shell_port","iopub_port","stdin_port","control_port","hb_port"]; d = dict(zip(keys, ports)); d.update({"ip": "127.0.0.1", "transport": "tcp", "signature_scheme": "hmac-sha256", "key": ""}); print(json.dumps(d))' > "$CONN" echo "Connection file: $CONN" java -jar "$JAR" "$CONN" >/dev/null 2>&1 & KPID=$! From 74a04f4984ac1a8c87b5b7e1ef156725761fcb06 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Fri, 16 Jan 2026 14:18:41 +0100 Subject: [PATCH 12/49] chore(ci): workflow fix; update sample notebook --- .github/workflows/build-release.yml | 2 +- docs/notebooks/ijava_sample_notebook.ipynb | 1384 ++++++++++++++------ 2 files changed, 1020 insertions(+), 366 deletions(-) diff --git a/.github/workflows/build-release.yml b/.github/workflows/build-release.yml index f8da131..cf875e4 100644 --- a/.github/workflows/build-release.yml +++ b/.github/workflows/build-release.yml @@ -120,7 +120,7 @@ jobs: exit 1 fi echo "Found jar: $JAR" - + CONN=$(mktemp --suffix=.json) python3 -c 'import json, random; ports = [random.randint(15000, 30000) for _ in range(5)]; keys = ["shell_port","iopub_port","stdin_port","control_port","hb_port"]; d = dict(zip(keys, ports)); d.update({"ip": "127.0.0.1", "transport": "tcp", "signature_scheme": "hmac-sha256", "key": ""}); print(json.dumps(d))' > "$CONN" echo "Connection file: $CONN" diff --git a/docs/notebooks/ijava_sample_notebook.ipynb b/docs/notebooks/ijava_sample_notebook.ipynb index 81396f2..b660a8c 100644 --- a/docs/notebooks/ijava_sample_notebook.ipynb +++ b/docs/notebooks/ijava_sample_notebook.ipynb @@ -36,42 +36,57 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 1, "id": "f119ff0d", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Failed to inspect com.example.Product: com.example.Product\n" + ] } - }, - "outputs": [], + ], "source": [ "%class-info com.example.Product" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 2, "id": "993dd2d4", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "No javadoc found for com.example.Product\n" + ] } - }, - "outputs": [], + ], "source": [ "%javadoc-html com.example.Product" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 3, "id": "7a3d4a63", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Class not found in classpath: com.example.Product\n", + "Source: /var/home/bruno/Documents/GitHub/Jupyter-Kernels/IJava/docs/notebooks/./sample_java/com/example/Product.java\n", + "Class not found in classpath: com.example.Product\n", + "Source: /var/home/bruno/Documents/GitHub/Jupyter-Kernels/IJava/docs/notebooks/./sample_java/com/example/Product.java\n" + ] } - }, - "outputs": [], + ], "source": [ "%where com.example.Product\n", "%which com.example.Product" @@ -79,14 +94,18 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 4, "id": "0463f36e", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Hello Cell\n" + ] } - }, - "outputs": [], + ], "source": [ "// Inline class defined directly in a cell\n", "class InlineGreeter {\n", @@ -110,14 +129,60 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 5, "id": "aa244659", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "registered line magics: \n", + "\t- classpath\n", + "\t- pom, loadFromPOM\n", + "\t- read\n", + "\t- classpath-snapshot\n", + "\t- listLineMagic\n", + "\t- printWithName\n", + "\t- listCellMagic\n", + "\t- cmd\n", + "\t- reload-class\n", + "\t- addMavenDependencies, maven, addMavenDependency\n", + "\t- listMagic, list\n", + "\t- load\n", + "\t- commonshellcmd\n", + "\t- addMavenRepo, mavenRepo\n", + "\t- write\n", + "\t- where, which\n", + "\t- jars\n", + "\t- printerPrefix\n", + "\t- javadoc-html\n", + "\t- class-info\n", + "registered cell magics: \n", + "\t- write\n", + "\t- plantUML\n", + "\t- shell\n", + "\t- javasrcFieldByName\n", + "\t- pom, loadFromPOM\n", + "\t- benchmark\n", + "\t- javasrcMethodByName\n", + "\t- timeIt, timeit, time\n", + "\t- myshell\n", + "\t- javasrcMethodByAnnotationName\n", + "\t- javasrcConstructorByName\n", + "\t- plantUMLFile\n", + "\t- rdbmsSchema\n", + "\t- compile\n", + "\t- javasrcList\n", + "\t- sqlAsTable\n", + "\t- javasrcJavadoc\n", + "\t- commonshell\n", + "\t- mycompile\n", + "\t- javasrcClassByName\n", + "\t- javasrcInterfaceByName\n" + ] } - }, - "outputs": [], + ], "source": [ "%listMagic" ] @@ -158,14 +223,18 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 6, "id": "a710005a", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Ijava Demo Using Maven/jars\n" + ] } - }, - "outputs": [], + ], "source": [ "%maven org.apache.commons:commons-text:1.10.0\n", "%jars org.apache.commons:commons-lang3:3.12.0\n", @@ -201,13 +270,9 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 7, "id": "b9e50494", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "%maven org.projectlombok:lombok:1.18.42" @@ -215,14 +280,21 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 8, "id": "4346a577", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "09:22:59.441 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Compiling com.example.Greeter with debug=false and nowarn=false\n", + "09:22:59.447 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Source file prepared at: /var/home/bruno/.jupyter/java-workspace/src/main/java/com/example/Greeter.java\n", + "09:22:59.773 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Added to classpath: /var/home/bruno/.jupyter/java-workspace/target/classes\n", + "09:22:59.773 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Successfully compiled com.example.Greeter and added to classpath\n" + ] } - }, - "outputs": [], + ], "source": [ "%%compile com.example.Greeter -v\n", "public class Greeter {\n", @@ -234,14 +306,47 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 9, "id": "1323a1ac", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "## %%compile - Compile Java source code and add to classpath\n", + "\n", + "**Usage:** `%%compile [--verbose] [--debug] [--nowarn] fully.qualified.ClassName`\n", + "\n", + "**Arguments:**\n", + "- `className` : Fully qualified class name (e.g., com.example.MyClass)\n", + "\n", + "**Options:**\n", + "- `--verbose, -v` : Enable verbose compilation output\n", + "- `--debug, -d` : Include debug information in compiled classes\n", + "- `--nowarn, -w` : Suppress compiler warnings\n", + "- `--help, -h` : Show this help message\n", + "\n", + "**Examples:**\n", + "```\n", + "%%compile com.example.Calculator\n", + "public class Calculator {\n", + " public int add(int a, int b) { return a + b; }\n", + "}\n", + "```\n", + "\n", + "```\n", + "%%compile --verbose --debug com.example.MyClass\n", + "public class MyClass {\n", + " public void hello() { System.out.println(\"Hello!\"); }\n", + "}\n", + "```\n", + "\n", + "**Note:** Package declaration will be added automatically if not present.\n", + "\n" + ] } - }, - "outputs": [], + ], "source": [ "%%compile -h\n", "// Placeholder to avoid empty cell issue" @@ -249,14 +354,18 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 10, "id": "1405dbb2", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Hello World\n" + ] } - }, - "outputs": [], + ], "source": [ "import com.example.Greeter;\n", "Greeter g = new Greeter(\"World\");\n", @@ -265,14 +374,21 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 11, "id": "15e2dbac", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "09:23:00.054 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Compiling com.example.lombok.LombokExample with debug=false and nowarn=false\n", + "09:23:00.055 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Source file prepared at: /var/home/bruno/.jupyter/java-workspace/src/main/java/com/example/lombok/LombokExample.java\n", + "09:23:00.263 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Added to classpath: /var/home/bruno/.jupyter/java-workspace/target/classes\n", + "09:23:00.264 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Successfully compiled com.example.lombok.LombokExample and added to classpath\n" + ] } - }, - "outputs": [], + ], "source": [ "%%compile com.example.lombok.LombokExample -v\n", "import lombok.Data;\n", @@ -293,14 +409,18 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 12, "id": "787aeffd", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Alice:30\n" + ] } - }, - "outputs": [], + ], "source": [ "import com.example.lombok.LombokExample;\n", "System.out.println(LombokExample.test());" @@ -318,14 +438,21 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 13, "id": "dba4d9ee", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "09:23:00.438 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Compiling com.example.Calculator with debug=false and nowarn=false\n", + "09:23:00.439 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Source file prepared at: /var/home/bruno/.jupyter/java-workspace/src/main/java/com/example/Calculator.java\n", + "09:23:00.618 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Added to classpath: /var/home/bruno/.jupyter/java-workspace/target/classes\n", + "09:23:00.619 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Successfully compiled com.example.Calculator and added to classpath\n" + ] } - }, - "outputs": [], + ], "source": [ "%%compile --verbose --debug com.example.Calculator\n", "public class Calculator {\n", @@ -340,14 +467,19 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 14, "id": "5feda3f2", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "5 + 3 = 8\n", + "5 * 3 = 15\n" + ] } - }, - "outputs": [], + ], "source": [ "import com.example.Calculator;\n", "Calculator calc = new Calculator();\n", @@ -366,14 +498,18 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 15, "id": "cb698277", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Write to \u001b[36m/tmp/example.txt\u001b[0m success.\n" + ] } - }, - "outputs": [], + ], "source": [ "%%write /tmp/example.txt\n", "Hello from IJava file write" @@ -381,13 +517,9 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 16, "id": "494de548", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "%read /tmp/example.txt" @@ -410,14 +542,21 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 17, "id": "ad449c8e", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Linux pc-bruno 6.17.12-300.fc43.x86_64 #1 SMP PREEMPT_DYNAMIC Sat Dec 13 05:06:24 UTC 2025 x86_64 x86_64 x86_64 GNU/Linux\n", + "Current shell: bash\n", + "/var/home/bruno/Documents/GitHub/Jupyter-Kernels/IJava/docs/notebooks\n", + "ven. 16 janv. 2026 09:23:00 CET\n" + ] } - }, - "outputs": [], + ], "source": [ "%%shell\n", "uname -a\n", @@ -428,28 +567,37 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 18, "id": "4dc8c214", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Single-line cmd via %cmd\n" + ] } - }, - "outputs": [], + ], "source": [ "%cmd echo Single-line cmd via %cmd" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 19, "id": "266b1064", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Running in bash\n", + "GNU bash, version 5.3.9(1)-release (x86_64-pc-linux-gnu)\n" + ] } - }, - "outputs": [], + ], "source": [ "%%shell --shell=bash\n", "echo \"Running in bash\"\n", @@ -458,14 +606,19 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 20, "id": "40abe0e6", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "This command has a 10 second timeout\n", + "Completed within timeout\n" + ] } - }, - "outputs": [], + ], "source": [ "%%shell --timeout=10\n", "echo \"This command has a 10 second timeout\"\n", @@ -475,14 +628,42 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 21, "id": "97bb9d78", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "## %%shell - Execute shell commands\n", + "\n", + "**Usage:** `%%shell [--shell=SHELL] [--timeout=SECONDS]`\n", + "\n", + "**Options:**\n", + "- `--shell=SHELL` : Shell to use (default: zsh, or $SHELL environment variable)\n", + "- `--timeout=SECONDS` : Maximum execution time in seconds (default: 180)\n", + "- `--help, -h` : Show this help message\n", + "\n", + "**Examples:**\n", + "```\n", + "%%shell\n", + "ls -la\n", + "```\n", + "\n", + "```\n", + "%%shell --shell=bash\n", + "echo \"Using bash\"\n", + "```\n", + "\n", + "```\n", + "%%shell --timeout=60\n", + "long-running-command\n", + "```\n", + "\n" + ] } - }, - "outputs": [], + ], "source": [ "%%shell --help\n", "# Placeholder text to avoid empty cell issue" @@ -499,42 +680,96 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 22, "id": "866de2ae", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "registered line magics: \n", + "\t- classpath\n", + "\t- pom, loadFromPOM\n", + "\t- read\n", + "\t- classpath-snapshot\n", + "\t- listLineMagic\n", + "\t- printWithName\n", + "\t- listCellMagic\n", + "\t- cmd\n", + "\t- reload-class\n", + "\t- addMavenDependencies, maven, addMavenDependency\n", + "\t- listMagic, list\n", + "\t- load\n", + "\t- commonshellcmd\n", + "\t- addMavenRepo, mavenRepo\n", + "\t- write\n", + "\t- where, which\n", + "\t- jars\n", + "\t- printerPrefix\n", + "\t- javadoc-html\n", + "\t- class-info\n" + ] } - }, - "outputs": [], + ], "source": [ "%listLineMagic" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 23, "id": "d01ffcc3", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "registered cell magics: \n", + "\t- write\n", + "\t- plantUML\n", + "\t- shell\n", + "\t- javasrcFieldByName\n", + "\t- pom, loadFromPOM\n", + "\t- benchmark\n", + "\t- javasrcMethodByName\n", + "\t- timeIt, timeit, time\n", + "\t- myshell\n", + "\t- javasrcMethodByAnnotationName\n", + "\t- javasrcConstructorByName\n", + "\t- plantUMLFile\n", + "\t- rdbmsSchema\n", + "\t- compile\n", + "\t- javasrcList\n", + "\t- sqlAsTable\n", + "\t- javasrcJavadoc\n", + "\t- commonshell\n", + "\t- mycompile\n", + "\t- javasrcClassByName\n", + "\t- javasrcInterfaceByName\n" + ] } - }, - "outputs": [], + ], "source": [ "%listCellMagic" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 24, "id": "31360433", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Change printer prefix from \"\" to \"MyDemoPrefix\"\n", + "run %printWithName to switch\n" + ] } - }, - "outputs": [], + ], "source": [ "%printerPrefix MyDemoPrefix\n", "%printWithName -h" @@ -559,13 +794,9 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 25, "id": "a9856ad0", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "// %pom --help\n", @@ -584,14 +815,18 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 26, "id": "c8a3466c", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Loaded: [Maven, dependencies, loaded]\n" + ] } - }, - "outputs": [], + ], "source": [ "%maven com.google.guava:guava:32.1.3-jre\n", "import com.google.common.collect.ImmutableList;\n", @@ -610,14 +845,23 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 27, "id": "60713d12", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "data": { + "image/svg+xml": [ + "AliceBobAliceAliceBobBobHiHello" + ], + "text/plain": [ + "AliceBobAliceAliceBobBobHiHello" + ] + }, + "metadata": {}, + "output_type": "display_data" } - }, - "outputs": [], + ], "source": [ "%%plantUML\n", "@startuml\n", @@ -628,14 +872,19 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 28, "id": "d63954b1", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "samples: [18834565, 18043222, 17486558, 19616153, 19883438]\n", + "min=17486558 median=18834565 avg=18772787,20 max=19883438 (nanoseconds)\n" + ] } - }, - "outputs": [], + ], "source": [ "%%timeit\n", "int s = 0;\n", @@ -657,13 +906,9 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 29, "id": "6b2c11e2", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "%maven com.h2database:h2:2.2.224\n", @@ -672,14 +917,18 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 30, "id": "a7d78934", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "H2 in-memory demo DB initialized (jdbc.url=jdbc:h2:mem:demo;DB_CLOSE_DELAY=-1;MODE=PostgreSQL)\n" + ] } - }, - "outputs": [], + ], "source": [ "System.setProperty(\"jdbc.driver\", \"org.h2.Driver\");\n", "System.setProperty(\"jdbc.url\", \"jdbc:h2:mem:demo;DB_CLOSE_DELAY=-1;MODE=PostgreSQL\");\n", @@ -716,17 +965,124 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 31, "id": "cceb3c23", - "metadata": { - "vscode": { - "languageId": "java" - } - }, - "outputs": [], - "source": [ - "%%rdbmsSchema EX_PRODUCT_ORDER showSource\n", - "// leave body empty to include all tables in the schema" + "metadata": {}, + "outputs": [ + { + "data": { + "text/markdown": [ + "```plantuml\n", + "@startuml\n", + "left to right direction\n", + "skinparam roundcorner 5\n", + "skinparam shadowing true\n", + "skinparam entity {\n", + " BackgroundColor #EEEEEE\n", + " ArrowColor #2688d4\n", + " BorderColor #2688d4\n", + "}\n", + "!define primary_key(x) PK x\n", + "!define foreign_key(x) FK x\n", + "!define column(x) * x\n", + "!define table(x) entity x << (T, white) >>\n", + "\n", + "table(CUSTOMER) {\n", + "\tprimary_key(ID) : BIGINT(64)\n", + "--\n", + "\tcolumn(NAME) : CHARACTER VARYING(255)\n", + "}\n", + "table(ORDERS) {\n", + "\tprimary_key(ID) : BIGINT(64)\n", + "--\n", + "\tforeign_key(CUSTOMER_ID) : BIGINT(64)\n", + "\tcolumn(ORDER_DATE) : TIMESTAMP(26)\n", + "}\n", + "table(ORDER_LINE) {\n", + "\tprimary_key(ID) : BIGINT(64)\n", + "--\n", + "\tforeign_key(ORDER_ID) : BIGINT(64)\n", + "\tforeign_key(PRODUCT_ID) : BIGINT(64)\n", + "\tcolumn(QUANTITY) : INTEGER(32)\n", + "}\n", + "table(PRODUCT) {\n", + "\tprimary_key(ID) : BIGINT(64)\n", + "--\n", + "\tcolumn(NAME) : CHARACTER VARYING(255)\n", + "\tcolumn(PRICE) : DOUBLE PRECISION(53)\n", + "}\n", + "ORDERS \"0..*\" --> \"1\" CUSTOMER : CUSTOMER_ID -> ID\n", + "ORDER_LINE \"0..*\" --> \"1\" ORDERS : ORDER_ID -> ID\n", + "ORDER_LINE \"0..*\" --> \"1\" PRODUCT : PRODUCT_ID -> ID\n", + "@enduml\n", + "```" + ], + "text/plain": [ + "```plantuml\n", + "@startuml\n", + "left to right direction\n", + "skinparam roundcorner 5\n", + "skinparam shadowing true\n", + "skinparam entity {\n", + " BackgroundColor #EEEEEE\n", + " ArrowColor #2688d4\n", + " BorderColor #2688d4\n", + "}\n", + "!define primary_key(x) PK x\n", + "!define foreign_key(x) FK x\n", + "!define column(x) * x\n", + "!define table(x) entity x << (T, white) >>\n", + "\n", + "table(CUSTOMER) {\n", + "\tprimary_key(ID) : BIGINT(64)\n", + "--\n", + "\tcolumn(NAME) : CHARACTER VARYING(255)\n", + "}\n", + "table(ORDERS) {\n", + "\tprimary_key(ID) : BIGINT(64)\n", + "--\n", + "\tforeign_key(CUSTOMER_ID) : BIGINT(64)\n", + "\tcolumn(ORDER_DATE) : TIMESTAMP(26)\n", + "}\n", + "table(ORDER_LINE) {\n", + "\tprimary_key(ID) : BIGINT(64)\n", + "--\n", + "\tforeign_key(ORDER_ID) : BIGINT(64)\n", + "\tforeign_key(PRODUCT_ID) : BIGINT(64)\n", + "\tcolumn(QUANTITY) : INTEGER(32)\n", + "}\n", + "table(PRODUCT) {\n", + "\tprimary_key(ID) : BIGINT(64)\n", + "--\n", + "\tcolumn(NAME) : CHARACTER VARYING(255)\n", + "\tcolumn(PRICE) : DOUBLE PRECISION(53)\n", + "}\n", + "ORDERS \"0..*\" --> \"1\" CUSTOMER : CUSTOMER_ID -> ID\n", + "ORDER_LINE \"0..*\" --> \"1\" ORDERS : ORDER_ID -> ID\n", + "ORDER_LINE \"0..*\" --> \"1\" PRODUCT : PRODUCT_ID -> ID\n", + "@enduml\n", + "```" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "image/svg+xml": [ + "CUSTOMERPKID: BIGINT(64)*NAME : CHARACTER VARYING(255)ORDERSPKID: BIGINT(64)FKCUSTOMER_ID : BIGINT(64)*ORDER_DATE : TIMESTAMP(26)ORDER_LINEPKID: BIGINT(64)FKORDER_ID : BIGINT(64)FKPRODUCT_ID : BIGINT(64)*QUANTITY : INTEGER(32)PRODUCTPKID: BIGINT(64)*NAME : CHARACTER VARYING(255)*PRICE : DOUBLE PRECISION(53)CUSTOMER_ID -> ID0..*1ORDER_ID -> ID0..*1PRODUCT_ID -> ID0..*1" + ], + "text/plain": [ + "CUSTOMERPKID: BIGINT(64)*NAME : CHARACTER VARYING(255)ORDERSPKID: BIGINT(64)FKCUSTOMER_ID : BIGINT(64)*ORDER_DATE : TIMESTAMP(26)ORDER_LINEPKID: BIGINT(64)FKORDER_ID : BIGINT(64)FKPRODUCT_ID : BIGINT(64)*QUANTITY : INTEGER(32)PRODUCTPKID: BIGINT(64)*NAME : CHARACTER VARYING(255)*PRICE : DOUBLE PRECISION(53)CUSTOMER_ID -> ID0..*1ORDER_ID -> ID0..*1PRODUCT_ID -> ID0..*1" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%rdbmsSchema EX_PRODUCT_ORDER showSource\n", + "// leave body empty to include all tables in the schema" ] }, { @@ -753,14 +1109,35 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 32, "id": "728e6207", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "\n", + "\n", + "\n", + "\n", + "\n", + "\n", + "
IDNAMEPRICE
1Pen1.0
2Paper5.0
3Car20000.0
" + ], + "text/plain": [ + "\n", + "\n", + "\n", + "\n", + "\n", + "\n", + "
IDNAMEPRICE
1Pen1.0
2Paper5.0
3Car20000.0
" + ] + }, + "metadata": {}, + "output_type": "display_data" } - }, - "outputs": [], + ], "source": [ "%%sqlAsTable\n", "SELECT id, name, price FROM EX_PRODUCT_ORDER.PRODUCT ORDER BY id LIMIT 10 OFFSET 0;" @@ -780,14 +1157,35 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 33, "id": "d458f4d4", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "\n", + "\n", + "\n", + "\n", + "\n", + "\n", + "
CUSTOMERPRODUCTQUANTITY
AlicePaper3
AlicePen2
BobCar1
" + ], + "text/plain": [ + "\n", + "\n", + "\n", + "\n", + "\n", + "\n", + "
CUSTOMERPRODUCTQUANTITY
AlicePaper3
AlicePen2
BobCar1
" + ] + }, + "metadata": {}, + "output_type": "display_data" } - }, - "outputs": [], + ], "source": [ "%%sqlAsTable --format=csv --showQuery\n", "SELECT c.name AS customer, p.name AS product, ol.quantity\n", @@ -809,14 +1207,18 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 34, "id": "272c920e", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Write to \u001b[36m/tmp/sample_schema.puml\u001b[0m success.\n" + ] } - }, - "outputs": [], + ], "source": [ "%%write /tmp/sample_schema.puml\n", "@startuml\n", @@ -828,14 +1230,23 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 35, "id": "19d9dcba", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "data": { + "image/svg+xml": [ + "PRODUCTCUSTOMERORDER_LINE" + ], + "text/plain": [ + "PRODUCTCUSTOMERORDER_LINE" + ] + }, + "metadata": {}, + "output_type": "display_data" } - }, - "outputs": [], + ], "source": [ "%%plantUMLFile\n", "/tmp/sample_schema.puml" @@ -856,14 +1267,19 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 36, "id": "b4eeb7fd", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "09:23:05.293 [IJava-executor-0] WARN i.g.s.ijava.magics.MagicsTool -- %load: file not found: sample_java/com/example/Greeter.java; (tried 'sample_java/com/example/Greeter.java;')\n", + "null\n" + ] } - }, - "outputs": [], + ], "source": [ "String file = %load sample_java/com/example/Greeter.java;\n", "System.out.println(file);" @@ -871,14 +1287,21 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 37, "id": "e6813df0", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "09:23:05.391 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Compiling com.example.Greeter with debug=false and nowarn=false\n", + "09:23:05.392 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Source file prepared at: /var/home/bruno/.jupyter/java-workspace/src/main/java/com/example/Greeter.java\n", + "09:23:05.575 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Added to classpath: /var/home/bruno/.jupyter/java-workspace/target/classes\n", + "09:23:05.575 [IJava-executor-0] INFO i.g.s.i.magics.JavaCompilerMagics -- Successfully compiled com.example.Greeter and added to classpath\n" + ] } - }, - "outputs": [], + ], "source": [ "%%compile com.example.Greeter -v\n", "public class Greeter {\n", @@ -890,14 +1313,18 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 38, "id": "d5ba62a9", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Hello Notebook\n" + ] } - }, - "outputs": [], + ], "source": [ "import com.example.Greeter;\n", "Greeter g = new Greeter(\"Notebook\");\n", @@ -915,14 +1342,33 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 39, "id": "fcf6b49a", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "data": { + "text/markdown": [ + "Summary of sample_java/com/example/OrderExample.java\n", + "\n", + "ClassOrInterfaceDeclaration: OrderExample\n", + " - String summary(Product)\n", + " - String deprecatedMethod()\n", + "\n" + ], + "text/plain": [ + "Summary of sample_java/com/example/OrderExample.java\n", + "\n", + "ClassOrInterfaceDeclaration: OrderExample\n", + " - String summary(Product)\n", + " - String deprecatedMethod()\n", + "\n" + ] + }, + "metadata": {}, + "output_type": "display_data" } - }, - "outputs": [], + ], "source": [ "%%javasrcList\n", "sample_java/com/example/OrderExample.java" @@ -952,14 +1398,45 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 40, "id": "45a05a57", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "data": { + "text/markdown": [ + "**Usage:** `%%javasrcMethodByName [options] [methodName|index]`\n", + "\n", + "**Options:**\n", + "- `--src `: source root to resolve FQCN (e.g., `--src=sample_java`)\n", + "- `methodRegex=`: select methods whose name matches regex\n", + "- `selectIndex=` or positional index: pick one when multiple matches\n", + "- `--raw` / `--fenced`: output format\n", + "\n", + "**Examples:**\n", + "- `%%javasrcMethodByName methodRegex=summary --src=sample_java com.example.OrderExample`\n", + "- `%%javasrcMethodByName com.example.OrderExample myMethod`\n", + "- `%%javasrcMethodByName selectIndex=1 com.example.OrderExample myMethod`\n" + ], + "text/plain": [ + "**Usage:** `%%javasrcMethodByName [options] [methodName|index]`\n", + "\n", + "**Options:**\n", + "- `--src `: source root to resolve FQCN (e.g., `--src=sample_java`)\n", + "- `methodRegex=`: select methods whose name matches regex\n", + "- `selectIndex=` or positional index: pick one when multiple matches\n", + "- `--raw` / `--fenced`: output format\n", + "\n", + "**Examples:**\n", + "- `%%javasrcMethodByName methodRegex=summary --src=sample_java com.example.OrderExample`\n", + "- `%%javasrcMethodByName com.example.OrderExample myMethod`\n", + "- `%%javasrcMethodByName selectIndex=1 com.example.OrderExample myMethod`\n" + ] + }, + "metadata": {}, + "output_type": "display_data" } - }, - "outputs": [], + ], "source": [ "%%javasrcMethodByName --help\n", "// Placeholder to avoid empty cell issue" @@ -967,14 +1444,31 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 41, "id": "e604f519", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "data": { + "text/markdown": [ + "```Java\n", + "public static String summary(Product p) {\n", + " return p.id + \":\" + p.name + \":\" + p.price;\n", + "}\n", + "```" + ], + "text/plain": [ + "```Java\n", + "public static String summary(Product p) {\n", + " return p.id + \":\" + p.name + \":\" + p.price;\n", + "}\n", + "```" + ] + }, + "metadata": {}, + "output_type": "display_data" } - }, - "outputs": [], + ], "source": [ "%%javasrcMethodByName methodRegex=summary --src=sample_java com.example.OrderExample\n", "sample_java/com/example/OrderExample.java" @@ -982,14 +1476,33 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 42, "id": "2e4693d6", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "data": { + "text/markdown": [ + "```Java\n", + "public interface SayHello {\n", + "\n", + " String sayHello(String name);\n", + "}\n", + "```" + ], + "text/plain": [ + "```Java\n", + "public interface SayHello {\n", + "\n", + " String sayHello(String name);\n", + "}\n", + "```" + ] + }, + "metadata": {}, + "output_type": "display_data" } - }, - "outputs": [], + ], "source": [ "%%javasrcInterfaceByName --src=sample_java com.example.SayHello\n", "sample_java/com/example/SayHello.java" @@ -997,14 +1510,33 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 43, "id": "e2b8bc7e", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "data": { + "text/markdown": [ + "```Java\n", + "@Deprecated\n", + "public static String deprecatedMethod() {\n", + " return \"This method is deprecated\";\n", + "}\n", + "```" + ], + "text/plain": [ + "```Java\n", + "@Deprecated\n", + "public static String deprecatedMethod() {\n", + " return \"This method is deprecated\";\n", + "}\n", + "```" + ] + }, + "metadata": {}, + "output_type": "display_data" } - }, - "outputs": [], + ], "source": [ "%%javasrcMethodByAnnotationName --src=sample_java com.example.OrderExample Deprecated\n", "sample_java/com/example/OrderExample.java" @@ -1021,14 +1553,37 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 44, "id": "48208db5", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "data": { + "text/markdown": [ + "```Java\n", + "0: OrderExample()\n", + "\n", + "public OrderExample() {\n", + "}\n", + "\n", + "\n", + "```" + ], + "text/plain": [ + "```Java\n", + "0: OrderExample()\n", + "\n", + "public OrderExample() {\n", + "}\n", + "\n", + "\n", + "```" + ] + }, + "metadata": {}, + "output_type": "display_data" } - }, - "outputs": [], + ], "source": [ "%%javasrcConstructorByName --src=sample_java com.example.OrderExample\n", "sample_java/com/example/OrderExample.java" @@ -1036,14 +1591,51 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 45, "id": "d33aec3c", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "data": { + "text/markdown": [ + "```Java\n", + "long id (modifiers: private )\n", + "\n", + "private long id;\n", + "\n", + "String name (modifiers: private )\n", + "\n", + "private String name;\n", + "\n", + "double price (modifiers: private )\n", + "\n", + "private double price;\n", + "\n", + "\n", + "```" + ], + "text/plain": [ + "```Java\n", + "long id (modifiers: private )\n", + "\n", + "private long id;\n", + "\n", + "String name (modifiers: private )\n", + "\n", + "private String name;\n", + "\n", + "double price (modifiers: private )\n", + "\n", + "private double price;\n", + "\n", + "\n", + "```" + ] + }, + "metadata": {}, + "output_type": "display_data" } - }, - "outputs": [], + ], "source": [ "%%javasrcFieldByName --src=sample_java com.example.Product\n", "sample_java/com/example/Product.java" @@ -1051,14 +1643,35 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 46, "id": "ce5a53e2", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "data": { + "text/markdown": [ + "```Java\n", + "String name (modifiers: private )\n", + "\n", + "private String name;\n", + "\n", + "\n", + "```" + ], + "text/plain": [ + "```Java\n", + "String name (modifiers: private )\n", + "\n", + "private String name;\n", + "\n", + "\n", + "```" + ] + }, + "metadata": {}, + "output_type": "display_data" } - }, - "outputs": [], + ], "source": [ "%%javasrcFieldByName --src=sample_java com.example.Product name\n", "sample_java/com/example/Product.java" @@ -1066,14 +1679,23 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 47, "id": "cf525a61", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "data": { + "text/markdown": [ + "A simple Greeter class that greets a person by name." + ], + "text/plain": [ + "A simple Greeter class that greets a person by name." + ] + }, + "metadata": {}, + "output_type": "display_data" } - }, - "outputs": [], + ], "source": [ "%%javasrcJavadoc --src=sample_java com.example.Greeter\n", "sample_java/com/example/Greeter.java" @@ -1081,14 +1703,27 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 48, "id": "be43fd75", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "data": { + "text/markdown": [ + "Greets the person by name.\n", + "\n", + "- @return — A greeting message." + ], + "text/plain": [ + "Greets the person by name.\n", + "\n", + "- @return — A greeting message." + ] + }, + "metadata": {}, + "output_type": "display_data" } - }, - "outputs": [], + ], "source": [ "%%javasrcJavadoc --src=sample_java com.example.Greeter greet\n", "sample_java/com/example/Greeter.java" @@ -1096,48 +1731,53 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 49, "id": "48b7b043", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "/var/home/bruno/.local/share/jupyter/kernels/java/IJava-1.4.5.jar (lastModified=2026-01-16T08:22:44Z)\n", + "\n" + ] } - }, - "outputs": [], + ], "source": [ "%classpath-snapshot" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 50, "id": "56ab8185", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Loaded class com.example.Greeter (loader=jdk.jshell.execution.DefaultLoaderDelegate$RemoteClassLoader@c86b9e3)\n" + ] } - }, - "outputs": [], + ], "source": [ "%reload-class com.example.Greeter" ] }, { "cell_type": "code", - "execution_count": 1, + "execution_count": 51, "id": "b3b5e194", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Dry run: would compile source file: /var/home/bruno/.jupyter/java-workspace/src/main/java/com/example/Dummy.java\n", - "With javac options: -cp file:/var/home/bruno/.local/share/jupyter/kernels/java/IJava-1.4.5.jar -d /var/home/bruno/.jupyter/java-workspace/target/classes --enable-preview --release 25 -proc:full -implicit:class -Xlint:all\n" + "With javac options: -cp file:/var/home/bruno/.m2/repository/org/apache/commons/commons-text/1.10.0/commons-text-1.10.0.jar:file:/var/home/bruno/.m2/repository/org/apache/commons/commons-lang3/3.12.0/commons-lang3-3.12.0.jar:file:/var/home/bruno/.m2/repository/org/projectlombok/lombok/1.18.42/lombok-1.18.42.jar:file:///var/home/bruno/.jupyter/java-workspace/target/classes/:file:/var/home/bruno/.m2/repository/com/google/guava/guava/32.1.3-jre/guava-32.1.3-jre.jar:file:/var/home/bruno/.m2/repository/com/google/guava/failureaccess/1.0.1/failureaccess-1.0.1.jar:file:/var/home/bruno/.m2/repository/com/google/guava/listenablefuture/9999.0-empty-to-avoid-conflict-with-guava/listenablefuture-9999.0-empty-to-avoid-conflict-with-guava.jar:file:/var/home/bruno/.m2/repository/com/google/code/findbugs/jsr305/3.0.2/jsr305-3.0.2.jar:file:/var/home/bruno/.m2/repository/org/checkerframework/checker-qual/3.37.0/checker-qual-3.37.0.jar:file:/var/home/bruno/.m2/repository/com/google/errorprone/error_prone_annotations/2.21.1/error_prone_annotations-2.21.1.jar:file:/var/home/bruno/.m2/repository/com/google/j2objc/j2objc-annotations/2.8/j2objc-annotations-2.8.jar:file:/var/home/bruno/.m2/repository/com/h2database/h2/2.2.224/h2-2.2.224.jar:file:/var/home/bruno/.local/share/jupyter/kernels/java/IJava-1.4.5.jar -d /var/home/bruno/.jupyter/java-workspace/target/classes --enable-preview --release 25 -proc:full -implicit:class -Xlint:all\n" ] } ], @@ -1150,20 +1790,16 @@ }, { "cell_type": "code", - "execution_count": 2, + "execution_count": 52, "id": "6d79c65f", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ - "samples: [32964072, 28617065, 30631490, 24220108, 23877293]\n", - "min=23877293 median=28617065 avg=28062005,60 max=32964072 (nanoseconds)\n" + "samples: [20646336, 23860698, 18893042, 19000318, 20836091]\n", + "min=18893042 median=20646336 avg=20647297,00 max=23860698 (nanoseconds)\n" ] } ], @@ -1176,30 +1812,17 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 53, "id": "51ad0569", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Benchmark results (nanoseconds):\n", - "Impl 0: mean=55370840 median=52379171 samples=[65551031, 50660057, 52379171, 59080130, 49183815]\n", - "Impl 1: mean=99466757 median=101817329 samples=[102906743, 101817329, 105328306, 94568050, 92713358]\n" - ] - }, { "data": { "image/svg+xml": [ - "Impl 055,371 msImpl 199,467 msaveraged over 5 iterations (warmup=1)" + "100011000210003100041000NBenchmark sweep: N0,0025,8651,7277,58103,44129,3052,0342,6542,6341,0148,78107,28111,85112,91111,34129,30// Implementation A: LinkedList workl...// Implementation B: ArrayList workloadaveraged over 5 iterations (warmup=1)" ], "text/plain": [ - "Impl 055,371 msImpl 199,467 msaveraged over 5 iterations (warmup=1)" + "100011000210003100041000NBenchmark sweep: N0,0025,8651,7277,58103,44129,3052,0342,6542,6341,0148,78107,28111,85112,91111,34129,30// Implementation A: LinkedList workl...// Implementation B: ArrayList workloadaveraged over 5 iterations (warmup=1)" ] }, "metadata": {}, @@ -1230,13 +1853,9 @@ }, { "cell_type": "code", - "execution_count": 7, + "execution_count": 54, "id": "227fed40", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "public static class BenchmarkHelpers {\n", @@ -1267,21 +1886,17 @@ }, { "cell_type": "code", - "execution_count": 9, + "execution_count": 55, "id": "428d5c90", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { "image/svg+xml": [ - "100011000210003100041000NBenchmark sweep: N0,0010,8421,6832,5243,3654,2011,4710,6513,0910,5014,719,2412,5522,1254,2048,87// LinkedList// ArrayListaveraged over 5 iterations (warmup=1)" + "100011000210003100041000NBenchmark sweep: N0,0010,3620,7231,0841,4451,8017,7314,2013,9115,4214,5215,3714,8823,1935,4951,80// LinkedList// ArrayListaveraged over 5 iterations (warmup=1)" ], "text/plain": [ - "100011000210003100041000NBenchmark sweep: N0,0010,8421,6832,5243,3654,2011,4710,6513,0910,5014,719,2412,5522,1254,2048,87// LinkedList// ArrayListaveraged over 5 iterations (warmup=1)" + "100011000210003100041000NBenchmark sweep: N0,0010,3620,7231,0841,4451,8017,7314,2013,9115,4214,5215,3714,8823,1935,4951,80// LinkedList// ArrayListaveraged over 5 iterations (warmup=1)" ] }, "metadata": {}, @@ -1299,21 +1914,17 @@ }, { "cell_type": "code", - "execution_count": 11, + "execution_count": 56, "id": "096bc4cd", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { "image/svg+xml": [ - "100011000210003100041000NBenchmark sweep: N0,004,118,2212,3316,4420,5512,3911,8913,1513,5220,5514,4112,8314,3513,6017,26// LinkedList// ArrayListaveraged over 5 iterations (warmup=1)" + "100011000210003100041000NBenchmark sweep: N0,004,819,6214,4319,2424,0514,1015,0415,0116,0624,0514,5517,5220,9221,6515,22// LinkedList// ArrayListaveraged over 5 iterations (warmup=1)" ], "text/plain": [ - "100011000210003100041000NBenchmark sweep: N0,004,118,2212,3316,4420,5512,3911,8913,1513,5220,5514,4112,8314,3513,6017,26// LinkedList// ArrayListaveraged over 5 iterations (warmup=1)" + "100011000210003100041000NBenchmark sweep: N0,004,819,6214,4319,2424,0514,1015,0415,0116,0624,0514,5517,5220,9221,6515,22// LinkedList// ArrayListaveraged over 5 iterations (warmup=1)" ] }, "metadata": {}, @@ -1339,14 +1950,57 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 57, "id": "441130dd", - "metadata": { - "vscode": { - "languageId": "java" + "metadata": {}, + "outputs": [ + { + "data": { + "text/markdown": [ + "```Java\n", + "public class Greeter {\n", + " private final String name;\n", + "\n", + " public Greeter(String name) {\n", + " this.name = name;\n", + " }\n", + "\n", + " /**\n", + " * Greets the person by name.\n", + " * \n", + " * @return A greeting message.\n", + " */\n", + " public String greet() {\n", + " return \"Hello \" + name;\n", + " }\n", + "}\n", + "```" + ], + "text/plain": [ + "```Java\n", + "public class Greeter {\n", + " private final String name;\n", + "\n", + " public Greeter(String name) {\n", + " this.name = name;\n", + " }\n", + "\n", + " /**\n", + " * Greets the person by name.\n", + " * \n", + " * @return A greeting message.\n", + " */\n", + " public String greet() {\n", + " return \"Hello \" + name;\n", + " }\n", + "}\n", + "```" + ] + }, + "metadata": {}, + "output_type": "display_data" } - }, - "outputs": [], + ], "source": [ "%%javasrcClassByName --src=sample_java com.example.Greeter\n", "sample_java/com/example/Greeter.java" @@ -1395,7 +2049,7 @@ "codemirror_mode": "java", "file_extension": ".jshell", "mimetype": "text/x-java-source", - "name": "Java", + "name": "java", "pygments_lexer": "java", "version": "25.0.1+8-LTS" } From 28933bf77b7438ffaa3841d0310a532b4fc430e4 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Fri, 16 Jan 2026 14:30:22 +0100 Subject: [PATCH 13/49] fix(ci): correct workflow YAML indentation for release step --- .github/workflows/build-release.yml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/workflows/build-release.yml b/.github/workflows/build-release.yml index cf875e4..1ceb114 100644 --- a/.github/workflows/build-release.yml +++ b/.github/workflows/build-release.yml @@ -149,14 +149,14 @@ jobs: with: name: distribution - - name: Create GitHub Release and upload assets - uses: softprops/action-gh-release@v1 - with: - body_path: UPGRADE.md - files: | - IJava-${{ github.ref_name }}.zip - IJava-${{ github.ref_name }}.zip.sha256 - prerelease: ${{ github.event_name == 'workflow_dispatch' ? (github.event.inputs.prerelease == 'true') : (contains(github.ref, '-pr') || contains(github.ref, '-rc')) }} + - name: Create GitHub Release and upload assets + uses: softprops/action-gh-release@v1 + with: + body_path: UPGRADE.md + files: | + IJava-${{ github.ref_name }}.zip + IJava-${{ github.ref_name }}.zip.sha256 + prerelease: ${{ github.event_name == 'workflow_dispatch' ? (github.event.inputs.prerelease == 'true') : (contains(github.ref, '-pr') || contains(github.ref, '-rc')) }} env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} From 597b1daa9f2da5428bdf834c576a396f9a990d78 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Fri, 16 Jan 2026 14:45:12 +0100 Subject: [PATCH 14/49] ci: don't publish if smoke-test fails (remove always() from publish job) --- .github/workflows/build-release.yml | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/.github/workflows/build-release.yml b/.github/workflows/build-release.yml index 1ceb114..4a0dbc9 100644 --- a/.github/workflows/build-release.yml +++ b/.github/workflows/build-release.yml @@ -149,14 +149,14 @@ jobs: with: name: distribution - - name: Create GitHub Release and upload assets - uses: softprops/action-gh-release@v1 - with: - body_path: UPGRADE.md - files: | - IJava-${{ github.ref_name }}.zip - IJava-${{ github.ref_name }}.zip.sha256 - prerelease: ${{ github.event_name == 'workflow_dispatch' ? (github.event.inputs.prerelease == 'true') : (contains(github.ref, '-pr') || contains(github.ref, '-rc')) }} + - name: Create GitHub Release and upload assets + uses: softprops/action-gh-release@v1 + with: + tag_name: ${{ needs.build.outputs.tag }} + body_path: UPGRADE.md + files: | + IJava-${{ needs.build.outputs.tag }}.zip + IJava-${{ needs.build.outputs.tag }}.zip.sha256 + prerelease: ${{ (github.event_name == 'workflow_dispatch' && github.event.inputs.prerelease == 'true') || (github.event_name != 'workflow_dispatch' && (contains(github.ref, '-pr') || contains(github.ref, '-rc'))) }} env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - From 439c4410503519f4927999c0afbac7782fa78864 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Fri, 16 Jan 2026 15:04:40 +0100 Subject: [PATCH 15/49] ci: allow overriding project version via -Pversion --- build.gradle | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/build.gradle b/build.gradle index 6aa7b12..79ee2e2 100644 --- a/build.gradle +++ b/build.gradle @@ -5,7 +5,8 @@ plugins { } group = 'io.github.spencerpark' -version = '1.4.5' +// Allow overriding version from command line via `-Pversion=...` +version = (project.findProperty('version') ?: '1.4.5').toString() // Java configuration java { From 99f4db55b7464c6a0ac3587f58da45e5e2e518f0 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Fri, 16 Jan 2026 15:24:17 +0100 Subject: [PATCH 16/49] ci: pass tag to Gradle, use self-hosted runners, fetch full history --- .github/workflows/build-release.yml | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/.github/workflows/build-release.yml b/.github/workflows/build-release.yml index 4a0dbc9..b861277 100644 --- a/.github/workflows/build-release.yml +++ b/.github/workflows/build-release.yml @@ -29,24 +29,14 @@ permissions: jobs: build: name: Build distribution - runs-on: ubuntu-latest + runs-on: [self-hosted, Linux, X64] outputs: tag: ${{ steps.set-tag.outputs.tag }} steps: - name: Checkout uses: actions/checkout@v4 - - - name: Set up JDK 21 - uses: actions/setup-java@v4 with: - distribution: 'temurin' - java-version: '21' - cache: 'gradle' - - - name: Build package - run: | - chmod +x ./gradlew - ./gradlew --no-daemon clean packDist + fetch-depth: 0 - name: Determine tag id: set-tag @@ -63,6 +53,18 @@ jobs: echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT fi + - name: Set up JDK 21 + uses: actions/setup-java@v4 + with: + distribution: 'temurin' + java-version: '21' + cache: 'gradle' + + - name: Build package + run: | + chmod +x ./gradlew + ./gradlew --no-daemon -Pversion=${{ steps.set-tag.outputs.tag }} clean packDist + - name: Prepare artifact and checksum run: | set -euo pipefail @@ -141,7 +143,7 @@ jobs: publish: name: Create Release needs: [build, smoke-test] - runs-on: ubuntu-latest + runs-on: [self-hosted, Linux, X64] if: ${{ startsWith(github.ref, 'refs/tags/') || (github.event_name == 'workflow_dispatch' && github.event.inputs.publish == 'true') }} steps: - name: Download distribution From 87964577a095a41e802399153a4f595a939e912d Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Fri, 16 Jan 2026 17:33:40 +0100 Subject: [PATCH 17/49] ci: cleanup smoke-test temp files (trap to kill kernel and remove smoke/ and conn file) --- .github/workflows/build-release.yml | 51 +++++++++++++++++++---------- 1 file changed, 34 insertions(+), 17 deletions(-) diff --git a/.github/workflows/build-release.yml b/.github/workflows/build-release.yml index b861277..a17c39e 100644 --- a/.github/workflows/build-release.yml +++ b/.github/workflows/build-release.yml @@ -38,6 +38,13 @@ jobs: with: fetch-depth: 0 + - name: Set up JDK 21 + uses: actions/setup-java@v4 + with: + distribution: 'temurin' + java-version: '21' + cache: 'gradle' + - name: Determine tag id: set-tag run: | @@ -53,13 +60,6 @@ jobs: echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT fi - - name: Set up JDK 21 - uses: actions/setup-java@v4 - with: - distribution: 'temurin' - java-version: '21' - cache: 'gradle' - - name: Build package run: | chmod +x ./gradlew @@ -69,17 +69,18 @@ jobs: run: | set -euo pipefail TAG=${{ steps.set-tag.outputs.tag }} - ARTIFACT=$(ls build/distributions/*.zip | head -n1) - if [ -z "${ARTIFACT:-}" ]; then - echo "No distribution zip found in build/distributions" >&2 - ls -la build || true - exit 1 + ARTIFACT="build/distributions/IJava-${TAG}.zip" + if [ ! -f "$ARTIFACT" ]; then + ARTIFACT=$(ls build/distributions/*.zip | head -n1 || true) + if [ -z "$ARTIFACT" ]; then + echo "No distribution zip found in build/distributions" >&2 + ls -la build || true + exit 1 + fi fi - TARGET="build/distributions/IJava-${TAG}.zip" - cp "$ARTIFACT" "$TARGET" - sha256sum "$TARGET" > "$TARGET.sha256" - echo "Prepared $TARGET and checksum" - ls -l "$TARGET" "$TARGET.sha256" + sha256sum "$ARTIFACT" > "${ARTIFACT}.sha256" + echo "Prepared $ARTIFACT and checksum" + ls -l "$ARTIFACT" "${ARTIFACT}.sha256" - name: Upload distribution artifact uses: actions/upload-artifact@v4 @@ -103,6 +104,7 @@ jobs: - name: Run smoke test (unpack & start briefly) run: | set -euo pipefail + # prepare workspace DIST=$(ls -1 *.zip | grep IJava || true) if [ -z "$DIST" ]; then echo "Distribution zip not found in artifact" >&2 @@ -112,6 +114,8 @@ jobs: echo "Using distribution: $DIST" rm -rf smoke && mkdir -p smoke unzip -q "$DIST" -d smoke + + # locate jar JAR=$(find smoke -type f -name "*-all.jar" -print -quit) if [ -z "$JAR" ]; then JAR=$(find smoke -type f -name "*.jar" -print -quit) @@ -123,9 +127,22 @@ jobs: fi echo "Found jar: $JAR" + # create connection file and ensure cleanup on exit CONN=$(mktemp --suffix=.json) + KPID="" + cleanup() { + if [ -n "${KPID:-}" ]; then + kill "$KPID" 2>/dev/null || true + wait "$KPID" 2>/dev/null || true + fi + rm -f "${CONN:-}" || true + rm -rf smoke || true + } + trap cleanup EXIT + python3 -c 'import json, random; ports = [random.randint(15000, 30000) for _ in range(5)]; keys = ["shell_port","iopub_port","stdin_port","control_port","hb_port"]; d = dict(zip(keys, ports)); d.update({"ip": "127.0.0.1", "transport": "tcp", "signature_scheme": "hmac-sha256", "key": ""}); print(json.dumps(d))' > "$CONN" echo "Connection file: $CONN" + java -jar "$JAR" "$CONN" >/dev/null 2>&1 & KPID=$! echo "Kernel PID: $KPID" From 9715619407a453b0b05b49147302694a1c61380f Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Fri, 16 Jan 2026 17:40:24 +0100 Subject: [PATCH 18/49] =?UTF-8?q?ci:=20smoke-test=20=E2=80=94=20use=20venv?= =?UTF-8?q?=20+=20nbconvert=20to=20run=20minimal=20notebook=20against=20un?= =?UTF-8?q?packed=20jar?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/build-release.yml | 65 ++++++++++++++++++++++------- 1 file changed, 51 insertions(+), 14 deletions(-) diff --git a/.github/workflows/build-release.yml b/.github/workflows/build-release.yml index a17c39e..ee533f5 100644 --- a/.github/workflows/build-release.yml +++ b/.github/workflows/build-release.yml @@ -140,22 +140,59 @@ jobs: } trap cleanup EXIT - python3 -c 'import json, random; ports = [random.randint(15000, 30000) for _ in range(5)]; keys = ["shell_port","iopub_port","stdin_port","control_port","hb_port"]; d = dict(zip(keys, ports)); d.update({"ip": "127.0.0.1", "transport": "tcp", "signature_scheme": "hmac-sha256", "key": ""}); print(json.dumps(d))' > "$CONN" + # create a minimal isolated venv under smoke/ and run a notebook against the unpacked jar + CONN=$(mktemp --suffix=.json) echo "Connection file: $CONN" - java -jar "$JAR" "$CONN" >/dev/null 2>&1 & - KPID=$! - echo "Kernel PID: $KPID" - sleep 5 - if kill -0 "$KPID" >/dev/null 2>&1; then - echo "Kernel started (PID $KPID) - killing" - kill "$KPID" || true - wait "$KPID" || true - else - echo "Kernel process exited prematurely" >&2 - ps aux | head -n 20 || true - exit 1 - fi + # create venv inside smoke so cleanup removes it + python3 -m venv smoke/venv + . smoke/venv/bin/activate + pip install --upgrade pip + pip install --no-cache-dir jupyter nbconvert jupyter-client >/dev/null + + # prepare a kernelspec that launches the unpacked jar + JAR_ABS=$(realpath "$JAR") + KS_DIR=$(mktemp -d) + mkdir -p "$KS_DIR/ijavatest" + cat > "$KS_DIR/ijavatest/kernel.json" <<'EOF' +{ + "argv": ["java","-jar","__JAR_PATH__","{connection_file}"], + "display_name": "IJava-SmokeTest", + "language": "java" +} +EOF + sed -i "s|__JAR_PATH__|${JAR_ABS}|g" "$KS_DIR/ijavatest/kernel.json" + + # install kernelspec into the venv (sys-prefix keeps it inside venv) + jupyter kernelspec install --sys-prefix "$KS_DIR/ijavatest" --name ijavatest --replace + + # create a minimal notebook that exercises the kernel + cat > smoke/hello.ipynb <<'JSON' +{ + "cells": [ + { + "cell_type": "code", + "metadata": {}, + "outputs": [], + "source": [ + "System.out.println(\"hello from ijava smoke test\");" + ] + } + ], + "nbformat": 4, + "nbformat_minor": 2, + "metadata": {} +} +JSON + + # execute the notebook using the temporary kernel; fail on any error + jupyter nbconvert --to notebook --execute smoke/hello.ipynb \ + --ExecutePreprocessor.timeout=60 \ + --ExecutePreprocessor.kernel_name=ijavatest \ + --output smoke/executed.ipynb + + # deactivate venv; smoke/ will be removed by the existing cleanup trap + deactivate || true publish: name: Create Release From 4442d65ea1efe30c896ffb6bcedc8c4407488310 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Fri, 16 Jan 2026 17:49:26 +0100 Subject: [PATCH 19/49] =?UTF-8?q?ci:=20prerelease=20workflow=20=E2=80=94?= =?UTF-8?q?=20normalize=20artifact,=20venv=20smoke-test,=20tag=20handling?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/build-release.yml | 150 +++++++--------------------- 1 file changed, 37 insertions(+), 113 deletions(-) diff --git a/.github/workflows/build-release.yml b/.github/workflows/build-release.yml index ee533f5..28a65f4 100644 --- a/.github/workflows/build-release.yml +++ b/.github/workflows/build-release.yml @@ -48,17 +48,17 @@ jobs: - name: Determine tag id: set-tag run: | - set -euo pipefail if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then - if [ -n "${{ github.event.inputs.tag || '' }}" ]; then - echo "tag=${{ github.event.inputs.tag }}" >> $GITHUB_OUTPUT + if [ -n "${{ github.event.inputs.tag }}" ]; then + TAG_NAME="${{ github.event.inputs.tag }}" else - VER=$(./gradlew -q properties --no-daemon | sed -n 's/^version: //p') - echo "tag=${VER}" >> $GITHUB_OUTPUT + # Fallback to gradle version if no input provided + TAG_NAME=$(./gradlew -q properties | grep ^version: | awk '{print $2}') fi else - echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT + TAG_NAME="${GITHUB_REF#refs/tags/}" fi + echo "tag=$TAG_NAME" >> $GITHUB_OUTPUT - name: Build package run: | @@ -69,31 +69,24 @@ jobs: run: | set -euo pipefail TAG=${{ steps.set-tag.outputs.tag }} - ARTIFACT="build/distributions/IJava-${TAG}.zip" - if [ ! -f "$ARTIFACT" ]; then - ARTIFACT=$(ls build/distributions/*.zip | head -n1 || true) - if [ -z "$ARTIFACT" ]; then - echo "No distribution zip found in build/distributions" >&2 - ls -la build || true - exit 1 - fi - fi - sha256sum "$ARTIFACT" > "${ARTIFACT}.sha256" - echo "Prepared $ARTIFACT and checksum" - ls -l "$ARTIFACT" "${ARTIFACT}.sha256" + # Look for the zip regardless of name, then rename it to a standard format for the artifact + RAW_ZIP=$(ls build/distributions/*.zip | head -n1) + cp "$RAW_ZIP" "IJava-${TAG}.zip" + sha256sum "IJava-${TAG}.zip" > "IJava-${TAG}.zip.sha256" - name: Upload distribution artifact uses: actions/upload-artifact@v4 with: name: distribution path: | - build/distributions/IJava-${{ steps.set-tag.outputs.tag }}.zip - build/distributions/IJava-${{ steps.set-tag.outputs.tag }}.zip.sha256 + IJava-${{ steps.set-tag.outputs.tag }}.zip + IJava-${{ steps.set-tag.outputs.tag }}.zip.sha256 smoke-test: name: Smoke-test distribution needs: build runs-on: ubuntu-latest + # Run if manual dispatch asks for it OR if it's a tag push if: ${{ github.event_name != 'workflow_dispatch' || github.event.inputs.run_smoke_test == 'true' }} steps: - name: Download distribution @@ -101,118 +94,49 @@ jobs: with: name: distribution - - name: Run smoke test (unpack & start briefly) + - name: Run smoke test run: | set -euo pipefail - # prepare workspace - DIST=$(ls -1 *.zip | grep IJava || true) - if [ -z "$DIST" ]; then - echo "Distribution zip not found in artifact" >&2 - ls -la || true - exit 1 - fi - echo "Using distribution: $DIST" - rm -rf smoke && mkdir -p smoke + DIST=$(ls IJava-*.zip | head -n1) unzip -q "$DIST" -d smoke - # locate jar - JAR=$(find smoke -type f -name "*-all.jar" -print -quit) - if [ -z "$JAR" ]; then - JAR=$(find smoke -type f -name "*.jar" -print -quit) - fi - if [ -z "$JAR" ]; then - echo "No jar found inside distribution" >&2 - ls -R smoke || true - exit 1 - fi - echo "Found jar: $JAR" - - # create connection file and ensure cleanup on exit - CONN=$(mktemp --suffix=.json) - KPID="" - cleanup() { - if [ -n "${KPID:-}" ]; then - kill "$KPID" 2>/dev/null || true - wait "$KPID" 2>/dev/null || true - fi - rm -f "${CONN:-}" || true - rm -rf smoke || true - } - trap cleanup EXIT - - # create a minimal isolated venv under smoke/ and run a notebook against the unpacked jar - CONN=$(mktemp --suffix=.json) - echo "Connection file: $CONN" - - # create venv inside smoke so cleanup removes it - python3 -m venv smoke/venv - . smoke/venv/bin/activate - pip install --upgrade pip - pip install --no-cache-dir jupyter nbconvert jupyter-client >/dev/null - - # prepare a kernelspec that launches the unpacked jar - JAR_ABS=$(realpath "$JAR") - KS_DIR=$(mktemp -d) - mkdir -p "$KS_DIR/ijavatest" - cat > "$KS_DIR/ijavatest/kernel.json" <<'EOF' -{ - "argv": ["java","-jar","__JAR_PATH__","{connection_file}"], - "display_name": "IJava-SmokeTest", - "language": "java" -} -EOF - sed -i "s|__JAR_PATH__|${JAR_ABS}|g" "$KS_DIR/ijavatest/kernel.json" - - # install kernelspec into the venv (sys-prefix keeps it inside venv) - jupyter kernelspec install --sys-prefix "$KS_DIR/ijavatest" --name ijavatest --replace - - # create a minimal notebook that exercises the kernel - cat > smoke/hello.ipynb <<'JSON' -{ - "cells": [ - { - "cell_type": "code", - "metadata": {}, - "outputs": [], - "source": [ - "System.out.println(\"hello from ijava smoke test\");" - ] - } - ], - "nbformat": 4, - "nbformat_minor": 2, - "metadata": {} -} -JSON - - # execute the notebook using the temporary kernel; fail on any error - jupyter nbconvert --to notebook --execute smoke/hello.ipynb \ - --ExecutePreprocessor.timeout=60 \ - --ExecutePreprocessor.kernel_name=ijavatest \ - --output smoke/executed.ipynb - - # deactivate venv; smoke/ will be removed by the existing cleanup trap - deactivate || true + # Find the JAR (supporting both flat and nested structures) + JAR=$(find smoke -name "*.jar" | head -n1) + + python3 -m venv venv + ./venv/bin/pip install jupyter nbconvert jupyter-client + + # Simplified kernel install + mkdir -p kernel_meta + echo "{\"argv\":[\"java\",\"-jar\",\"$(realpath $JAR)\",\"{connection_file}\"],\"display_name\":\"Java\",\"language\":\"java\"}" > kernel_meta/kernel.json + ./venv/bin/jupyter kernelspec install --user --name ijavatest --replace ./kernel_meta + + # Create and execute test notebook + echo '{"cells":[{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["System.out.println(\"Hello\");"]}],"metadata":{},"nbformat":4,"nbformat_minor":4}' > test.ipynb + ./venv/bin/jupyter nbconvert --to notebook --execute test.ipynb --ExecutePreprocessor.kernel_name=ijavatest publish: name: Create Release needs: [build, smoke-test] - runs-on: [self-hosted, Linux, X64] - if: ${{ startsWith(github.ref, 'refs/tags/') || (github.event_name == 'workflow_dispatch' && github.event.inputs.publish == 'true') }} + runs-on: ubuntu-latest # No need for self-hosted here usually, ubuntu-latest is safer for API calls + if: ${{ always() && (needs.smoke-test.result == 'success' || needs.smoke-test.result == 'skipped') && (startsWith(github.ref, 'refs/tags/') || github.event.inputs.publish == 'true') }} steps: + - name: Checkout code (for UPGRADE.md) + uses: actions/checkout@v4 + - name: Download distribution uses: actions/download-artifact@v4 with: name: distribution - - name: Create GitHub Release and upload assets - uses: softprops/action-gh-release@v1 + - name: Create GitHub Release + uses: softprops/action-gh-release@v2 # Updated to v2 with: tag_name: ${{ needs.build.outputs.tag }} body_path: UPGRADE.md files: | IJava-${{ needs.build.outputs.tag }}.zip IJava-${{ needs.build.outputs.tag }}.zip.sha256 - prerelease: ${{ (github.event_name == 'workflow_dispatch' && github.event.inputs.prerelease == 'true') || (github.event_name != 'workflow_dispatch' && (contains(github.ref, '-pr') || contains(github.ref, '-rc'))) }} + prerelease: ${{ github.event.inputs.prerelease == 'true' || contains(github.ref, '-rc') || contains(github.ref, '-pr') }} env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} From ede224c33eef405652f11842ac907322e2ac0863 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Fri, 16 Jan 2026 18:56:47 +0100 Subject: [PATCH 20/49] =?UTF-8?q?ci:=20smoke-test=20=E2=80=94=20ensure=20J?= =?UTF-8?q?DK=2021=20in=20smoke-test=20and=20install=20kernelspec=20into?= =?UTF-8?q?=20venv=20(sys-prefix)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/build-release.yml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/.github/workflows/build-release.yml b/.github/workflows/build-release.yml index 28a65f4..589c6f1 100644 --- a/.github/workflows/build-release.yml +++ b/.github/workflows/build-release.yml @@ -94,6 +94,12 @@ jobs: with: name: distribution + - name: Set up JDK 21 for smoke-test + uses: actions/setup-java@v4 + with: + distribution: 'temurin' + java-version: '21' + - name: Run smoke test run: | set -euo pipefail @@ -109,7 +115,7 @@ jobs: # Simplified kernel install mkdir -p kernel_meta echo "{\"argv\":[\"java\",\"-jar\",\"$(realpath $JAR)\",\"{connection_file}\"],\"display_name\":\"Java\",\"language\":\"java\"}" > kernel_meta/kernel.json - ./venv/bin/jupyter kernelspec install --user --name ijavatest --replace ./kernel_meta + ./venv/bin/jupyter kernelspec install --sys-prefix --name ijavatest --replace ./kernel_meta # Create and execute test notebook echo '{"cells":[{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["System.out.println(\"Hello\");"]}],"metadata":{},"nbformat":4,"nbformat_minor":4}' > test.ipynb From 3359322d64119050b375de8e8d4bec10cd00ec0d Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Thu, 29 Jan 2026 17:06:38 +0100 Subject: [PATCH 21/49] refactor(magics): consolidate ShellMagics, add shared executor, shutdown and tests; remove MyShellMagics --- build.gradle | 1 + .../github/spencerpark/ijava/JavaKernel.java | 7 +- .../ijava/magics/MyShellMagics.java | 7 +- .../spencerpark/ijava/magics/ShellMagics.java | 52 ++++-- .../ijava/magics/JavaDBMSMagicsTest.java | 158 ++++++++++++++++++ .../ijava/magics/ShellMagicsTest.java | 61 +++++++ 6 files changed, 265 insertions(+), 21 deletions(-) create mode 100644 src/test/java/io/github/spencerpark/ijava/magics/JavaDBMSMagicsTest.java create mode 100644 src/test/java/io/github/spencerpark/ijava/magics/ShellMagicsTest.java diff --git a/build.gradle b/build.gradle index 79ee2e2..93b4205 100644 --- a/build.gradle +++ b/build.gradle @@ -58,6 +58,7 @@ dependencies { implementation "ch.qos.logback:logback-classic:${versions.logback}" testImplementation "junit:junit:${versions.junit}" + testImplementation 'com.h2database:h2:2.2.220' // JavaParser for Java source code analysis implementation 'com.github.javaparser:javaparser-core:3.25.8' diff --git a/src/main/java/io/github/spencerpark/ijava/JavaKernel.java b/src/main/java/io/github/spencerpark/ijava/JavaKernel.java index 6036941..e5cb767 100644 --- a/src/main/java/io/github/spencerpark/ijava/JavaKernel.java +++ b/src/main/java/io/github/spencerpark/ijava/JavaKernel.java @@ -127,7 +127,7 @@ public JavaKernel() { magics.registerMagics(new JavaDBMSMagics()); magics.registerMagics(new JavaMagics()); magics.registerMagics(new JavaPlantUMLMagics()); - magics.registerMagics(new MyShellMagics()); + // Consolidated shell magics: `MyShellMagics` removed, use `ShellMagics` only. magics.registerMagics(new ShellMagics()); try { magics.registerMagics(new SingleShellMagics()); @@ -420,6 +420,11 @@ public String isComplete(String code) { @Override public void onShutdown(boolean isRestarting) { this.evaluator.shutdown(); + try { + io.github.spencerpark.ijava.magics.ShellMagics.shutdownExecutor(); + } catch (Throwable t) { + log.warn("Failed to shutdown ShellMagics executor", t); + } } @Override diff --git a/src/main/java/io/github/spencerpark/ijava/magics/MyShellMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/MyShellMagics.java index c4149f4..e723a80 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/MyShellMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/MyShellMagics.java @@ -1,6 +1,6 @@ package io.github.spencerpark.ijava.magics; -import io.github.spencerpark.jupyter.kernel.magic.registry.CellMagic; +// legacy file: no longer registers a magic import lombok.extern.slf4j.Slf4j; import java.io.BufferedReader; @@ -11,9 +11,10 @@ import java.util.concurrent.TimeUnit; @Slf4j +@Deprecated(forRemoval = true) public class MyShellMagics { - @CellMagic("myshell") + // No longer registers a magic. Use ShellMagics (%%shell) instead. public void myshell(List args, String body) { if (args.isEmpty()) return; @@ -51,4 +52,4 @@ public void myshell(List args, String body) { } } -} \ No newline at end of file +} diff --git a/src/main/java/io/github/spencerpark/ijava/magics/ShellMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/ShellMagics.java index 2e21b70..3138151 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/ShellMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/ShellMagics.java @@ -31,6 +31,9 @@ import java.util.List; import java.util.Map; import java.util.concurrent.Executors; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Future; +import java.util.concurrent.ExecutionException; import java.util.concurrent.TimeUnit; import io.github.spencerpark.jupyter.kernel.magic.registry.CellMagic; import lombok.extern.slf4j.Slf4j; @@ -38,6 +41,28 @@ @Slf4j public class ShellMagics { + private static final ExecutorService EXECUTOR = Executors.newCachedThreadPool(); + + /** + * Gracefully shutdown the shared executor service used for stream gobbling. + * Safe to call multiple times. + */ + public static void shutdownExecutor() { + EXECUTOR.shutdown(); + try { + EXECUTOR.awaitTermination(1, TimeUnit.SECONDS); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + } + + /** + * Return whether the shared executor has been shutdown. + */ + public static boolean isExecutorShutdown() { + return EXECUTOR.isShutdown(); + } + private static class StreamGobbler implements Runnable { private InputStream inputStream; private Consumer consumer; @@ -114,14 +139,21 @@ public void shell(List args, String body) throws InterruptedException, I .command(commands).start(); StreamGobbler streamGobbler = new StreamGobbler(process.getInputStream(), System.out::println); StreamGobbler streamGobblerErr = new StreamGobbler(process.getErrorStream(), System.err::println); - Executors.newSingleThreadExecutor().submit(streamGobbler); - Executors.newSingleThreadExecutor().submit(streamGobblerErr); + Future fOut = EXECUTOR.submit(streamGobbler); + Future fErr = EXECUTOR.submit(streamGobblerErr); boolean finished = process.waitFor(timeout, TimeUnit.SECONDS); if (!finished) { process.destroyForcibly(); throw new RuntimeException("Command timed out after " + timeout + " seconds"); } + // Wait briefly for gobblers to flush remaining output + try { + fOut.get(1, TimeUnit.SECONDS); + fErr.get(1, TimeUnit.SECONDS); + } catch (ExecutionException | java.util.concurrent.TimeoutException e) { + // ignore - best-effort + } } catch (IOException e) { log.error("Error while running shell command", e); throw e; @@ -131,19 +163,5 @@ public void shell(List args, String body) throws InterruptedException, I } } - @CellMagic("myshell") - @Deprecated(forRemoval = true) - public void myshell(List args, String body) throws InterruptedException, IOException { - System.err.println( - "⚠️ WARNING: %%myshell is deprecated and will be removed in a future version. Use %%shell instead."); - shell(args, body); - } - - @CellMagic("commonshell") - @Deprecated(forRemoval = true) - public void commonshell(List args, String body) throws InterruptedException, IOException { - System.err.println( - "⚠️ WARNING: %%commonshell is deprecated and will be removed in a future version. Use %%shell instead."); - shell(args, body); - } + // Deprecated wrappers removed: use %%shell instead } diff --git a/src/test/java/io/github/spencerpark/ijava/magics/JavaDBMSMagicsTest.java b/src/test/java/io/github/spencerpark/ijava/magics/JavaDBMSMagicsTest.java new file mode 100644 index 0000000..0854637 --- /dev/null +++ b/src/test/java/io/github/spencerpark/ijava/magics/JavaDBMSMagicsTest.java @@ -0,0 +1,158 @@ +package io.github.spencerpark.ijava.magics; + +import io.github.spencerpark.ijava.IJava; +import io.github.spencerpark.ijava.JavaKernel; +import io.github.spencerpark.jupyter.kernel.display.DisplayData; +import io.github.spencerpark.jupyter.kernel.display.mime.MIMEType; +import org.junit.After; +import org.junit.Before; +import org.junit.Test; + +import java.lang.reflect.Field; +import java.sql.Connection; +import java.sql.DriverManager; +import java.sql.Statement; +import java.util.Collections; + +import static org.junit.Assert.fail; + +public class JavaDBMSMagicsTest { + + private JavaKernel kernel; + private java.util.concurrent.atomic.AtomicReference lastDisplayData = new java.util.concurrent.atomic.AtomicReference<>(); + private java.util.concurrent.atomic.AtomicReference lastDisplayString = new java.util.concurrent.atomic.AtomicReference<>(); + + @Before + public void setUp() throws Exception { + // Start an in-memory H2 database and populate some sample data + System.setProperty("jdbc.url", "jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1"); + + // Ensure driver is available and create schema + Class.forName("org.h2.Driver"); + try (Connection conn = DriverManager.getConnection(System.getProperty("jdbc.url"))) { + try (Statement st = conn.createStatement()) { + st.execute("DROP TABLE IF EXISTS person"); + st.execute("CREATE TABLE person (id INT PRIMARY KEY, name VARCHAR(100))"); + st.execute("INSERT INTO person (id, name) VALUES (1, 'Alice')"); + st.execute("INSERT INTO person (id, name) VALUES (2, 'Bob')"); + } + } + + // Create a JavaKernel instance subclass that captures displayed data + kernel = new JavaKernel() { + @Override + public void display(DisplayData data) { + lastDisplayData.set(data); + lastDisplayString.set(String.valueOf(data)); + // do not call super.display to avoid I/O side effects + } + }; + + Field kernelField = IJava.class.getDeclaredField("kernel"); + kernelField.setAccessible(true); + kernelField.set(null, kernel); + } + + @After + public void tearDown() throws Exception { + // Clear kernel reference and system properties + Field kernelField = IJava.class.getDeclaredField("kernel"); + kernelField.setAccessible(true); + kernelField.set(null, null); + + lastDisplayData.set(null); + lastDisplayString.set(null); + + System.clearProperty("jdbc.url"); + System.clearProperty("jdbc.user"); + System.clearProperty("jdbc.password"); + } + + @Test + public void testSqlAsTableRunsWithoutException() { + JavaDBMSMagics magics = new JavaDBMSMagics(); + try { + magics.sqlAsTable(Collections.emptyList(), "SELECT id, name FROM person ORDER BY id"); + } catch (Exception e) { + fail("sqlAsTable threw: " + e.getMessage()); + return; + } + + // Verify the captured display contains the table rows + String rendered = extractRendered(lastDisplayData.get()); + if (rendered == null) { + fail("No display output captured for sqlAsTable"); + return; + } + // Expect HTML table or CSV containing Alice and Bob + if (!(rendered.contains("Alice") && rendered.contains("Bob") || rendered.contains(" " + m.getReturnType()); + System.err.println("[TEST DEBUG] DisplayData class fields:"); + for (java.lang.reflect.Field f : dd.getClass().getDeclaredFields()) + System.err.println(" f: " + f.getName() + " -> " + f.getType()); + } catch (Throwable ignored) { + } + return dd.toString(); + } + } +} diff --git a/src/test/java/io/github/spencerpark/ijava/magics/ShellMagicsTest.java b/src/test/java/io/github/spencerpark/ijava/magics/ShellMagicsTest.java new file mode 100644 index 0000000..5885bca --- /dev/null +++ b/src/test/java/io/github/spencerpark/ijava/magics/ShellMagicsTest.java @@ -0,0 +1,61 @@ +package io.github.spencerpark.ijava.magics; + +import io.github.spencerpark.ijava.JavaKernel; +import org.junit.After; +import org.junit.Assert; +import org.junit.Test; + +import java.io.ByteArrayOutputStream; +import java.io.PrintStream; +import java.util.Arrays; +import java.util.List; + +public class ShellMagicsTest { + + private final PrintStream oldOut = System.out; + private final PrintStream oldErr = System.err; + + @After + public void tearDown() { + System.setOut(oldOut); + System.setErr(oldErr); + } + + @Test + public void testShellEcho() throws Exception { + ShellMagics magics = new ShellMagics(); + + ByteArrayOutputStream bout = new ByteArrayOutputStream(); + System.setOut(new PrintStream(bout)); + + List args = Arrays.asList("--shell=/bin/sh"); + magics.shell(args, "echo hello-test-123"); + + String out = bout.toString(); + Assert.assertTrue("Expected output to contain echo text", out.contains("hello-test-123")); + } + + @Test + public void testShellTimeout() throws Exception { + ShellMagics magics = new ShellMagics(); + + List args = Arrays.asList("--shell=/bin/sh", "--timeout=1"); + try { + magics.shell(args, "sleep 2"); + Assert.fail("Expected timeout to throw RuntimeException"); + } catch (RuntimeException e) { + // expected + } + } + + @Test + public void testExecutorShutdownOnKernelShutdown() throws Exception { + // Ensure executor not shutdown initially + Assert.assertFalse(ShellMagics.isExecutorShutdown()); + + JavaKernel kernel = new JavaKernel(); + kernel.onShutdown(false); + + Assert.assertTrue("Executor should be shutdown after kernel.onShutdown", ShellMagics.isExecutorShutdown()); + } +} From 5e07e9cfcfe4e2638c6efd2eed38ed1984928fd9 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Thu, 29 Jan 2026 17:09:15 +0100 Subject: [PATCH 22/49] test(magics): add DuplicateMagicsTest to prevent duplicate @CellMagic names; remove deprecated mycompile alias --- .../ijava/magics/JavaCompilerMagics.java | 8 +- .../ijava/magics/DuplicateMagicsTest.java | 101 ++++++++++++++++++ 2 files changed, 102 insertions(+), 7 deletions(-) create mode 100644 src/test/java/io/github/spencerpark/ijava/magics/DuplicateMagicsTest.java diff --git a/src/main/java/io/github/spencerpark/ijava/magics/JavaCompilerMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/JavaCompilerMagics.java index 3ca54c6..f02a04f 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/JavaCompilerMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/JavaCompilerMagics.java @@ -286,11 +286,5 @@ public class MyClass { } } - @CellMagic("mycompile") - @Deprecated(forRemoval = true) - public void mycompile(List args, String body) throws IOException { - System.err.println( - "⚠️ WARNING: %%mycompile is deprecated and will be removed in a future version. Use %%compile instead."); - compile(args, body); - } + // Deprecated alias removed: use %%compile instead } diff --git a/src/test/java/io/github/spencerpark/ijava/magics/DuplicateMagicsTest.java b/src/test/java/io/github/spencerpark/ijava/magics/DuplicateMagicsTest.java new file mode 100644 index 0000000..d8fc289 --- /dev/null +++ b/src/test/java/io/github/spencerpark/ijava/magics/DuplicateMagicsTest.java @@ -0,0 +1,101 @@ +package io.github.spencerpark.ijava.magics; + +import io.github.spencerpark.jupyter.kernel.magic.registry.CellMagic; +import org.junit.Assert; +import org.junit.Test; + +import java.io.File; +import java.io.IOException; +import java.lang.annotation.Annotation; +import java.net.JarURLConnection; +import java.net.URI; +import java.net.URL; +import java.nio.file.Files; +import java.nio.file.Path; +import java.nio.file.Paths; +import java.util.*; +import java.util.jar.JarEntry; +import java.util.jar.JarFile; +import java.util.stream.Collectors; + +public class DuplicateMagicsTest { + private static final String PACKAGE_PATH = "io/github/spencerpark/ijava/magics"; + private static final String PACKAGE_NAME = "io.github.spencerpark.ijava.magics"; + + @Test + public void testNoDuplicateCellMagicNames() throws Exception { + ClassLoader cl = Thread.currentThread().getContextClassLoader(); + Enumeration resources = cl.getResources(PACKAGE_PATH); + + Map> namesToClasses = new HashMap<>(); + + while (resources.hasMoreElements()) { + URL url = resources.nextElement(); + String protocol = url.getProtocol(); + if (protocol.equals("file")) { + Path dir = Paths.get(url.toURI()); + try (var stream = Files.list(dir)) { + List classFiles = stream.filter(p -> p.toString().endsWith(".class")) + .collect(Collectors.toList()); + for (Path p : classFiles) { + String fileName = p.getFileName().toString(); + String className = fileName.substring(0, fileName.length() - 6); + String fqcn = PACKAGE_NAME + "." + className; + inspectClassForCellMagic(fqcn, namesToClasses); + } + } + } else if (protocol.equals("jar")) { + JarURLConnection conn = (JarURLConnection) url.openConnection(); + try (JarFile jar = conn.getJarFile()) { + Enumeration entries = jar.entries(); + while (entries.hasMoreElements()) { + JarEntry e = entries.nextElement(); + String name = e.getName(); + if (name.startsWith(PACKAGE_PATH) && name.endsWith(".class")) { + String rel = name.substring(PACKAGE_PATH.length() + 1); // skip '/' + String className = rel.replace('/', '.').replaceAll("\\.class$", ""); + String fqcn = PACKAGE_NAME + "." + className; + inspectClassForCellMagic(fqcn, namesToClasses); + } + } + } + } + } + + // Now ensure no duplicates + List duplicates = namesToClasses.entrySet().stream() + .filter(e -> e.getValue().size() > 1) + .map(Map.Entry::getKey) + .collect(Collectors.toList()); + + if (!duplicates.isEmpty()) { + StringBuilder msg = new StringBuilder(); + msg.append("Duplicate @CellMagic names found:\n"); + for (String d : duplicates) { + msg.append(d).append(" -> ").append(namesToClasses.get(d)).append("\n"); + } + Assert.fail(msg.toString()); + } + } + + private void inspectClassForCellMagic(String fqcn, Map> map) { + try { + Class cls = Class.forName(fqcn); + if (cls.isAnnotationPresent(CellMagic.class)) { + CellMagic a = cls.getAnnotation(CellMagic.class); + String name = a.value(); + map.computeIfAbsent(name, k -> new ArrayList<>()).add(fqcn); + } + // also inspect methods + for (var m : cls.getDeclaredMethods()) { + if (m.isAnnotationPresent(CellMagic.class)) { + CellMagic a = m.getAnnotation(CellMagic.class); + String name = a.value(); + map.computeIfAbsent(name, k -> new ArrayList<>()).add(fqcn + "#" + m.getName()); + } + } + } catch (ClassNotFoundException e) { + // ignore + } + } +} From 3bd42ea1e047c8b9c5627ee4ae37146f8187b726 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Thu, 29 Jan 2026 17:53:42 +0100 Subject: [PATCH 23/49] feat(compile): extend JavaCompilerMagics with processor, output and options support; add JavaCompilerMagicsTest --- .../ijava/magics/JavaCompilerMagics.java | 178 ++++++++++++------ .../ijava/magics/DuplicateMagicsTest.java | 10 +- .../ijava/magics/JavaCompilerMagicsTest.java | 32 ++++ 3 files changed, 157 insertions(+), 63 deletions(-) create mode 100644 src/test/java/io/github/spencerpark/ijava/magics/JavaCompilerMagicsTest.java diff --git a/src/main/java/io/github/spencerpark/ijava/magics/JavaCompilerMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/JavaCompilerMagics.java index f02a04f..e8eeb3e 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/JavaCompilerMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/JavaCompilerMagics.java @@ -41,24 +41,31 @@ private void validateClassNameFormat(String className) { } } - private List buildCompilerOptions(Path outputRoot, boolean debug, boolean nowarn) { + private List buildCompilerOptions(Path outputRoot, boolean debug, boolean nowarn, + String release, boolean enablePreview, + String classpathOverride, + List processors, + List processorOptions) { List optionList = new ArrayList<>(); - List classpath = new ClassGraph().getClasspathURIs(); - - optionList.addAll(Arrays.asList( - "-cp", classpath.stream() - .map(URI::toString) - .collect(Collectors.joining(File.pathSeparator)), - "-d", outputRoot.toString())); - - // Add Java version specific options - String javaVersion = System.getProperty("java.version").split("[.]")[0]; - if (Integer.parseInt(javaVersion) >= 11) { - optionList.addAll(Arrays.asList( - "--enable-preview", - "--release", javaVersion)); + + // classpath + if (classpathOverride != null && !classpathOverride.isEmpty()) { + optionList.addAll(Arrays.asList("-cp", classpathOverride)); + } else { + List classpath = new ClassGraph().getClasspathURIs(); + optionList.addAll(Arrays.asList("-cp", classpath.stream() + .map(URI::toString) + .collect(Collectors.joining(File.pathSeparator)))); + } + + optionList.addAll(Arrays.asList("-d", outputRoot.toString())); + + if (release != null && !release.isEmpty()) { + optionList.addAll(Arrays.asList("--release", release)); } + if (enablePreview) optionList.add("--enable-preview"); + // Add debug information if requested if (debug) { optionList.add("-g"); @@ -68,10 +75,15 @@ private List buildCompilerOptions(Path outputRoot, boolean debug, boolea if (nowarn) { optionList.add("-nowarn"); } else { - optionList.addAll(Arrays.asList( - "-proc:full", - "-implicit:class", - "-Xlint:all")); + optionList.addAll(Arrays.asList("-proc:full", "-implicit:class", "-Xlint:all")); + } + + if (processors != null && !processors.isEmpty()) { + optionList.addAll(Arrays.asList("-processor", String.join(",", processors))); + } + + if (processorOptions != null) { + for (String po : processorOptions) optionList.add("-A" + po); } return optionList; @@ -157,6 +169,23 @@ private Path prepareSourceFile(String className, String sourceCode) throws IOExc return sourceFile; } + private Path writeSourceTo(Path sourceRoot, String className, String sourceCode) throws IOException { + // className: com.example.Foo + String packagePath = className.substring(0, className.lastIndexOf('.')); + String simpleClassName = className.substring(className.lastIndexOf('.') + 1); + Path packageDir = sourceRoot.resolve(packagePath.replace('.', File.separatorChar)); + Files.createDirectories(packageDir); + Path sourceFile = packageDir.resolve(simpleClassName + ".java"); + + // add package if missing + boolean hasPackage = sourceCode.contains("package "+packagePath); + String out = sourceCode; + if (!hasPackage) out = String.format("package %s;%n%n%s", packagePath, sourceCode); + + Files.writeString(sourceFile, out); + return sourceFile; + } + private void addCompiledClassToClasspath(Path outputRoot, boolean verbose) throws IOException { if (!Files.exists(outputRoot)) { throw new IOException("Compilation output directory does not exist: " + outputRoot); @@ -217,27 +246,44 @@ public class MyClass { return; } - MagicsArgs schema = MagicsArgs.builder() - .required("className") - .flag("verbose", 'v', "Enable verbose output") - .flag("debug", 'd', "Add debug information") - .flag("dry-run", 'n', "Show what would be compiled without invoking javac") - .flag("nowarn", 'w', "Suppress warnings") - .onlyKnownKeywords() - .onlyKnownFlags() - .build(); - Map> vals = schema.parse(args); - - boolean verbose = hasValidFlag(vals, "verbose"); - boolean debug = hasValidFlag(vals, "debug"); - boolean nowarn = hasValidFlag(vals, "nowarn"); - boolean dryRun = hasValidFlag(vals, "dry-run"); - String className = vals.get("className").get(0); + // Simple option parsing (MagicsArg schema doesn't handle repeatable processor-option easily) + String className = null; + boolean verbose = false; + boolean debug = false; + boolean nowarn = false; + boolean dryRun = false; + String release = null; + boolean enablePreview = false; + String outputDir = null; + String classpathOverride = null; + List processors = new ArrayList<>(); + List processorOptions = new ArrayList<>(); + String processorPath = null; + + for (String a : args) { + if (a.equals("--help") || a.equals("-h")) continue; + if (a.equals("--verbose") || a.equals("-v")) { verbose = true; continue; } + if (a.equals("--debug") || a.equals("-d")) { debug = true; continue; } + if (a.equals("--dry-run") || a.equals("-n")) { dryRun = true; continue; } + if (a.equals("--nowarn") || a.equals("-w")) { nowarn = true; continue; } + if (a.startsWith("--class=")) { className = a.substring(a.indexOf('=')+1); continue; } + if (a.startsWith("--release=")) { release = a.substring(a.indexOf('=')+1); continue; } + if (a.equals("--enable-preview")) { enablePreview = true; continue; } + if (a.startsWith("--output=")) { outputDir = a.substring(a.indexOf('=')+1); continue; } + if (a.startsWith("--classpath=") || a.startsWith("--cp=")) { int eq=a.indexOf('='); classpathOverride = a.substring(eq+1); continue; } + if (a.startsWith("--processor=")) { processors.add(a.substring(a.indexOf('=')+1)); continue; } + if (a.startsWith("--processor-path=")) { processorPath = a.substring(a.indexOf('=')+1); continue; } + if (a.startsWith("--processor-option=")) { processorOptions.add(a.substring(a.indexOf('=')+1)); continue; } + // fallback positional className if none of the above + if (className == null && !a.contains("=")) className = a; + } - if (verbose) { - log.info("Compiling {} with debug={} and nowarn={}", className, debug, nowarn); + if (className == null || className.isEmpty()) { + throw new IllegalArgumentException("Please specify fully qualified class name via --class=... or as first arg"); } + if (verbose) log.info("Compiling {} with debug={} and nowarn={}", className, debug, nowarn); + validateClassNameFormat(className); JavaCompiler compiler = ToolProvider.getSystemJavaCompiler(); @@ -245,44 +291,58 @@ public class MyClass { throw new IllegalStateException("Java compiler not available. Make sure you're using a JDK."); } - try (CompilationContext context = new CompilationContext(compiler, - WORKSPACE_DIR.resolve(SOURCE_DIR), - WORKSPACE_DIR.resolve(OUTPUT_DIR))) { - // Setup source file - Path sourceFile = prepareSourceFile(className, body); - if (verbose) { - log.info("Source file prepared at: {}", sourceFile); - } + Path sourceRoot; + Path outputRoot; + if (outputDir != null && !outputDir.isEmpty()) { + outputRoot = Path.of(outputDir).toAbsolutePath(); + sourceRoot = outputRoot.resolve("src"); + Files.createDirectories(sourceRoot); + Files.createDirectories(outputRoot); + } else { + sourceRoot = WORKSPACE_DIR.resolve(SOURCE_DIR); + outputRoot = WORKSPACE_DIR.resolve(OUTPUT_DIR); + Files.createDirectories(sourceRoot); + Files.createDirectories(outputRoot); + } - // If dry-run, report files and options - if (dryRun) { - Path sourceFilePreview = prepareSourceFile(className, body); - List optsList = buildCompilerOptions(context.outputRoot, debug, nowarn); - System.out.println("Dry run: would compile source file: " + sourceFilePreview); - System.out.println("With javac options: " + String.join(" ", optsList)); - return; + Path sourceFile = writeSourceTo(sourceRoot, className, body); + + if (verbose) log.info("Source file prepared at: {}", sourceFile); + + if (dryRun) { + List optsList = buildCompilerOptions(outputRoot, debug, nowarn, release, enablePreview, classpathOverride, processors, processorOptions); + System.out.println("Dry run: would compile source file: " + sourceFile); + System.out.println("With javac options: " + String.join(" ", optsList)); + return; + } + + try (CompilationContext context = new CompilationContext(compiler, sourceRoot, outputRoot)) { + // configure processor path if present + if (processorPath != null && !processorPath.isEmpty()) { + var paths = Arrays.stream(processorPath.split(File.pathSeparator)).map(Path::of).map(Path::toFile).collect(Collectors.toList()); + context.fileManager.setLocation(StandardLocation.ANNOTATION_PROCESSOR_PATH, paths); } - // Compile CompilerDiagnosticListener diagnostics = new CompilerDiagnosticListener(className, verbose); + + List opts = buildCompilerOptions(outputRoot, debug, nowarn, release, enablePreview, classpathOverride, processors, processorOptions); + boolean success = compiler.getTask( null, context.fileManager, diagnostics, - buildCompilerOptions(context.outputRoot, debug, nowarn), + opts, null, - context.fileManager.getJavaFileObjects(sourceFile.toFile())).call(); + context.fileManager.getJavaFileObjectsFromFiles(List.of(sourceFile.toFile()))).call(); if (!success || diagnostics.hasErrors()) { throw new IOException("Compilation failed for " + className); } // Add to classpath - addCompiledClassToClasspath(context.outputRoot, verbose); + addCompiledClassToClasspath(outputRoot, verbose); - if (verbose) { - log.info("Successfully compiled {} and added to classpath", className); - } + if (verbose) log.info("Successfully compiled {} and added to classpath", className); } } diff --git a/src/test/java/io/github/spencerpark/ijava/magics/DuplicateMagicsTest.java b/src/test/java/io/github/spencerpark/ijava/magics/DuplicateMagicsTest.java index d8fc289..4f6ec51 100644 --- a/src/test/java/io/github/spencerpark/ijava/magics/DuplicateMagicsTest.java +++ b/src/test/java/io/github/spencerpark/ijava/magics/DuplicateMagicsTest.java @@ -83,15 +83,17 @@ private void inspectClassForCellMagic(String fqcn, Map> map Class cls = Class.forName(fqcn); if (cls.isAnnotationPresent(CellMagic.class)) { CellMagic a = cls.getAnnotation(CellMagic.class); - String name = a.value(); - map.computeIfAbsent(name, k -> new ArrayList<>()).add(fqcn); + String v = a.value(); + if (v != null && !v.isEmpty()) map.computeIfAbsent(v, k -> new ArrayList<>()).add(fqcn); + for (String alias : a.aliases()) map.computeIfAbsent(alias, k -> new ArrayList<>()).add(fqcn); } // also inspect methods for (var m : cls.getDeclaredMethods()) { if (m.isAnnotationPresent(CellMagic.class)) { CellMagic a = m.getAnnotation(CellMagic.class); - String name = a.value(); - map.computeIfAbsent(name, k -> new ArrayList<>()).add(fqcn + "#" + m.getName()); + String v = a.value(); + if (v != null && !v.isEmpty()) map.computeIfAbsent(v, k -> new ArrayList<>()).add(fqcn + "#" + m.getName()); + for (String alias : a.aliases()) map.computeIfAbsent(alias, k -> new ArrayList<>()).add(fqcn + "#" + m.getName()); } } } catch (ClassNotFoundException e) { diff --git a/src/test/java/io/github/spencerpark/ijava/magics/JavaCompilerMagicsTest.java b/src/test/java/io/github/spencerpark/ijava/magics/JavaCompilerMagicsTest.java new file mode 100644 index 0000000..ece271c --- /dev/null +++ b/src/test/java/io/github/spencerpark/ijava/magics/JavaCompilerMagicsTest.java @@ -0,0 +1,32 @@ +package io.github.spencerpark.ijava.magics; + +import org.junit.Assert; +import org.junit.Test; + +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.List; + +public class JavaCompilerMagicsTest { + + @Test + public void testCompileSimpleClassProducesClassFile() throws IOException { + JavaCompilerMagics magics = new JavaCompilerMagics(path -> { + // record added classpath (no-op for test) + }); + + Path tmp = Path.of("build", "tmp", "test-compile").toAbsolutePath(); + Files.createDirectories(tmp); + + String className = "com.example.TestHello"; + String source = "public class TestHello { public static String hello() { return \"ok\"; } }"; + + List args = List.of("--class=" + className, "--output=" + tmp.toString()); + + magics.compile(args, source); + + Path classFile = tmp.resolve("com/example/TestHello.class"); + Assert.assertTrue("Expected compiled class file to exist", Files.exists(classFile)); + } +} From 663d7470c1bbd4a8fcf2a2ec5c893d305a9cd350 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Thu, 29 Jan 2026 17:56:03 +0100 Subject: [PATCH 24/49] test(ap): add AnnotationProcessorIntegrationTest to exercise annotation processors via JavaCompilerMagics --- .../AnnotationProcessorIntegrationTest.java | 82 +++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 src/test/java/io/github/spencerpark/ijava/magics/AnnotationProcessorIntegrationTest.java diff --git a/src/test/java/io/github/spencerpark/ijava/magics/AnnotationProcessorIntegrationTest.java b/src/test/java/io/github/spencerpark/ijava/magics/AnnotationProcessorIntegrationTest.java new file mode 100644 index 0000000..8112163 --- /dev/null +++ b/src/test/java/io/github/spencerpark/ijava/magics/AnnotationProcessorIntegrationTest.java @@ -0,0 +1,82 @@ +package io.github.spencerpark.ijava.magics; + +import org.junit.Assert; +import org.junit.Test; + +import javax.tools.JavaCompiler; +import javax.tools.ToolProvider; +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.List; +import java.util.stream.Collectors; + +public class AnnotationProcessorIntegrationTest { + + @Test + public void testAnnotationProcessorGeneratesClass() throws IOException { + // prepare temp dirs + Path base = Path.of("build", "tmp", "ap-integration").toAbsolutePath(); + Path procSrc = base.resolve("proc-src"); + Path procClasses = base.resolve("proc-classes"); + Path out = base.resolve("out"); + Files.createDirectories(procSrc); + Files.createDirectories(procClasses); + Files.createDirectories(out); + + // write annotation source + String annoSrc = "package com.example.ap; public @interface AutoGen {}"; + Path annoFile = procSrc.resolve(Path.of("com", "example", "ap", "AutoGen.java")); + Files.createDirectories(annoFile.getParent()); + Files.writeString(annoFile, annoSrc); + + // write processor source + String proc = "package com.example.ap;\n" + + "import javax.annotation.processing.*;\n" + + "import javax.lang.model.SourceVersion;\n" + + "import javax.lang.model.element.*;\n" + + "import javax.tools.JavaFileObject;\n" + + "import java.io.Writer;\n" + + "import java.util.Set;\n" + + "@SupportedAnnotationTypes(\"com.example.ap.AutoGen\")\n" + + "@SupportedSourceVersion(SourceVersion.RELEASE_8)\n" + + "public class AutoGenProcessor extends AbstractProcessor {\n" + + " @Override\n" + + " public boolean process(Set annotations, RoundEnvironment roundEnv) {\n" + + " try {\n" + + " for (TypeElement t : annotations) {\n" + + " for (Element e : roundEnv.getElementsAnnotatedWith(t)) {\n" + + " String gen = \"package com.example.gen; public class GeneratedHello { public static String msg() { return \"generated\"; } }\";\n" + + " JavaFileObject jf = processingEnv.getFiler().createSourceFile(\"com.example.gen.GeneratedHello\");\n" + + " try (Writer w = jf.openWriter()) { w.write(gen); }\n" + + " }\n" + + " }\n" + + " } catch (Exception ex) { throw new RuntimeException(ex); }\n" + + " return true;\n" + + " }\n" + + "}\n"; + Path procFile = procSrc.resolve(Path.of("com", "example", "ap", "AutoGenProcessor.java")); + Files.writeString(procFile, proc); + + // compile processor & annotation + JavaCompiler compiler = ToolProvider.getSystemJavaCompiler(); + if (compiler == null) { + throw new IllegalStateException("No system java compiler available for tests"); + } + var diagnostics = compiler.getTask(null, null, null, List.of("-d", procClasses.toString()), null, + compiler.getStandardFileManager(null, null, null).getJavaFileObjectsFromFiles( + List.of(annoFile.toFile(), procFile.toFile()))).call(); + // simple check: compiled classes exist + Path procClass = procClasses.resolve(Path.of("com", "example", "ap", "AutoGenProcessor.class")); + Assert.assertTrue("processor class should be compiled", Files.exists(procClass)); + + // Now compile a user source that uses the annotation, via JavaCompilerMagics + JavaCompilerMagics magics = new JavaCompilerMagics(p -> {}); + String userClass = "@com.example.ap.AutoGen public class UseIt { }"; + List args = List.of("--class=com.example.use.UseIt", "--output=" + out.toString(), "--processor-path=" + procClasses.toString(), "--processor=com.example.ap.AutoGenProcessor"); + magics.compile(args, userClass); + + Path generatedClass = out.resolve(Path.of("com", "example", "gen", "GeneratedHello.class")); + Assert.assertTrue("Generated class should exist", Files.exists(generatedClass)); + } +} From bca2e93c113d996ac56a6e695cd1113cc3336f15 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Thu, 29 Jan 2026 18:06:43 +0100 Subject: [PATCH 25/49] test(ap): fix annotation-processor integration test escaping and classpath --- .../ijava/magics/AnnotationProcessorIntegrationTest.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/test/java/io/github/spencerpark/ijava/magics/AnnotationProcessorIntegrationTest.java b/src/test/java/io/github/spencerpark/ijava/magics/AnnotationProcessorIntegrationTest.java index 8112163..e197b59 100644 --- a/src/test/java/io/github/spencerpark/ijava/magics/AnnotationProcessorIntegrationTest.java +++ b/src/test/java/io/github/spencerpark/ijava/magics/AnnotationProcessorIntegrationTest.java @@ -46,7 +46,7 @@ public void testAnnotationProcessorGeneratesClass() throws IOException { " try {\n" + " for (TypeElement t : annotations) {\n" + " for (Element e : roundEnv.getElementsAnnotatedWith(t)) {\n" + - " String gen = \"package com.example.gen; public class GeneratedHello { public static String msg() { return \"generated\"; } }\";\n" + + " String gen = \"package com.example.gen; public class GeneratedHello { public static String msg() { return \\\"generated\\\"; } }\";\n" + " JavaFileObject jf = processingEnv.getFiler().createSourceFile(\"com.example.gen.GeneratedHello\");\n" + " try (Writer w = jf.openWriter()) { w.write(gen); }\n" + " }\n" + @@ -73,7 +73,7 @@ public void testAnnotationProcessorGeneratesClass() throws IOException { // Now compile a user source that uses the annotation, via JavaCompilerMagics JavaCompilerMagics magics = new JavaCompilerMagics(p -> {}); String userClass = "@com.example.ap.AutoGen public class UseIt { }"; - List args = List.of("--class=com.example.use.UseIt", "--output=" + out.toString(), "--processor-path=" + procClasses.toString(), "--processor=com.example.ap.AutoGenProcessor"); + List args = List.of("--class=com.example.use.UseIt", "--output=" + out.toString(), "--processor-path=" + procClasses.toString(), "--processor=com.example.ap.AutoGenProcessor", "--classpath=" + procClasses.toString()); magics.compile(args, userClass); Path generatedClass = out.resolve(Path.of("com", "example", "gen", "GeneratedHello.class")); From faecf54831b014d4f98eb38eb9d66501f56be05e Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Thu, 29 Jan 2026 22:27:54 +0100 Subject: [PATCH 26/49] feat(magics): add class diagram magics and PlantUmlGenerator; register magics and update demos --- docs/sample_java/com/example/Greeter.java | 21 + .../sample_java/com/example/OrderExample.java | 41 + docs/sample_java/com/example/Product.java | 27 + docs/sample_java/com/example/SayHello.java | 5 + notebooks/magics_demo.ipynb | 1584 +++++++++++++++++ notebooks/out/com/example/demo/A.class | Bin 0 -> 219 bytes notebooks/out/com/example/demo/B.class | Bin 0 -> 195 bytes notebooks/out/com/example/demo/C.class | Bin 0 -> 176 bytes notebooks/out/com/example/demo/Hello.class | Bin 0 -> 304 bytes .../out/com/example/demo/LombokPerson.class | Bin 0 -> 1717 bytes notebooks/out/src/com/example/demo/A.java | 3 + notebooks/out/src/com/example/demo/B.java | 3 + notebooks/out/src/com/example/demo/C.java | 4 + notebooks/out/src/com/example/demo/Hello.java | 4 + .../src/com/example/demo/LombokPerson.java | 9 + .../github/spencerpark/ijava/JavaKernel.java | 1 + .../ijava/magics/BenchmarkMagics.java | 9 + .../ijava/magics/ClassDiagramMagics.java | 304 ++++ .../ijava/magics/ClasspathMagics.java | 17 + .../ijava/magics/CompilerMagics.java | 7 + .../ijava/magics/JavaDBMSMagics.java | 285 ++- .../spencerpark/ijava/magics/JavaMagics.java | 33 + .../ijava/magics/JavaPlantUMLMagics.java | 12 + .../ijava/magics/MavenResolver.java | 22 +- .../ijava/magics/PlantUmlGenerator.java | 176 ++ .../ijava/magics/SingleShellMagics.java | 9 +- 26 files changed, 2524 insertions(+), 52 deletions(-) create mode 100644 docs/sample_java/com/example/Greeter.java create mode 100644 docs/sample_java/com/example/OrderExample.java create mode 100644 docs/sample_java/com/example/Product.java create mode 100644 docs/sample_java/com/example/SayHello.java create mode 100644 notebooks/magics_demo.ipynb create mode 100644 notebooks/out/com/example/demo/A.class create mode 100644 notebooks/out/com/example/demo/B.class create mode 100644 notebooks/out/com/example/demo/C.class create mode 100644 notebooks/out/com/example/demo/Hello.class create mode 100644 notebooks/out/com/example/demo/LombokPerson.class create mode 100644 notebooks/out/src/com/example/demo/A.java create mode 100644 notebooks/out/src/com/example/demo/B.java create mode 100644 notebooks/out/src/com/example/demo/C.java create mode 100644 notebooks/out/src/com/example/demo/Hello.java create mode 100644 notebooks/out/src/com/example/demo/LombokPerson.java create mode 100644 src/main/java/io/github/spencerpark/ijava/magics/ClassDiagramMagics.java create mode 100644 src/main/java/io/github/spencerpark/ijava/magics/PlantUmlGenerator.java diff --git a/docs/sample_java/com/example/Greeter.java b/docs/sample_java/com/example/Greeter.java new file mode 100644 index 0000000..6bcb17a --- /dev/null +++ b/docs/sample_java/com/example/Greeter.java @@ -0,0 +1,21 @@ +package com.example; + +/** + * A simple Greeter class that greets a person by name. + */ +public class Greeter { + private final String name; + + public Greeter(String name) { + this.name = name; + } + + /** + * Greets the person by name. + * + * @return A greeting message. + */ + public String greet() { + return "Hello " + name; + } +} diff --git a/docs/sample_java/com/example/OrderExample.java b/docs/sample_java/com/example/OrderExample.java new file mode 100644 index 0000000..9631f5e --- /dev/null +++ b/docs/sample_java/com/example/OrderExample.java @@ -0,0 +1,41 @@ +package com.example; + +/** + * OrderExample is a fake java class + * + * @see Product + */ +public class OrderExample { + public static class Product { + public long id; + public String name; + public double price; + + public Product(long id, String name, double price) { + this.id = id; + this.name = name; + this.price = price; + } + } + + /** + * No arg constructor + */ + public OrderExample() { + } + + /** + * Returns a summary of the product. + * + * @param p The product to summarize. + * @return A string summary of the product. + */ + public static String summary(Product p) { + return p.id + ":" + p.name + ":" + p.price; + } + + @Deprecated + public static String deprecatedMethod() { + return "This method is deprecated"; + } +} diff --git a/docs/sample_java/com/example/Product.java b/docs/sample_java/com/example/Product.java new file mode 100644 index 0000000..78dfab1 --- /dev/null +++ b/docs/sample_java/com/example/Product.java @@ -0,0 +1,27 @@ +package com.example; + +public class Product { + private long id; + private String name; + private double price; + + public Product(long id, String name) { + this(id, name, -1); + } + + public Product(long id, String name, double price) { + this.id = id; + this.name = name; + this.price = price; + } + + public static String summary(Product p) { + return p.id + ":" + p.name + ":" + p.price; + } + + @Deprecated(since = 1) + public void oldMethod() { + System.out.println("old ..."); + } + +} diff --git a/docs/sample_java/com/example/SayHello.java b/docs/sample_java/com/example/SayHello.java new file mode 100644 index 0000000..87b5336 --- /dev/null +++ b/docs/sample_java/com/example/SayHello.java @@ -0,0 +1,5 @@ +package com.example; + +public interface SayHello { + String sayHello(String name); +} diff --git a/notebooks/magics_demo.ipynb b/notebooks/magics_demo.ipynb new file mode 100644 index 0000000..09b37d4 --- /dev/null +++ b/notebooks/magics_demo.ipynb @@ -0,0 +1,1584 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "5f79afc5", + "metadata": {}, + "source": [ + "%%benchmark --sweep --chart var=n start=1000 end=10000 step=1000 iterations=5 warmup=1\n", + "// Use a predefined test builder that accepts a Map factory (constructor reference)\n", + "java.util.Random rnd = new java.util.Random(12345);\n", + "int[] keys = new int[n];\n", + "for (int i = 0; i < n; i++) keys[i] = rnd.nextInt(n * 10);\n", + "\n", + "import java.util.function.Supplier;\n", + "import java.util.Map;\n", + "// build a Supplier that performs many lookups on a map created by mapFactory\n", + "Supplier makeMapLookupTest(Supplier> mapFactory) {\n", + " Map map = mapFactory.get();\n", + " for (int k : keys) map.put(k, k);\n", + " java.util.Random localRnd = new java.util.Random(54321);\n", + " return () -> {\n", + " int acc = 0;\n", + " for (int i = 0; i < 10000; i++) acc += (map.get(keys[localRnd.nextInt(keys.length)]) != null) ? 1 : 0;\n", + " return acc;\n", + " };\n", + "}\n", + "\n", + "// HashMap: pass a constructor reference via a lambda (to set initial capacity)\n", + "runSupplierTest(makeMapLookupTest(() -> new java.util.HashMap<>(Math.max(16, n * 2))), 1);\n", + "---\n", + "// TreeMap: pass constructor reference directly\n", + "runSupplierTest(makeMapLookupTest(java.util.TreeMap::new), 1);" + ] + }, + { + "cell_type": "markdown", + "id": "fd625c49", + "metadata": {}, + "source": [ + "## Expressions" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "d5ae9350", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/plain": [ + "\u001b[36m\"Helloworld!\";\u001b[0m: Hello world !" + ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "\"Hello world !\";" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "1c4668b6", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/plain": [ + "\u001b[36m3+4*2\u001b[0m: 11" + ] + }, + "execution_count": 6, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "3+4*2" + ] + }, + { + "cell_type": "markdown", + "id": "3b4dfb05", + "metadata": {}, + "source": [ + "## Methods and Classes in cells" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "e5e10708", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "5\n" + ] + } + ], + "source": [ + "// Basic method example: define a helper class with a static method and call it\n", + "class Helper {\n", + " static int add(int a, int b) { return a + b; }\n", + "}\n", + "System.out.println(Helper.add(2, 3));" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "4f6628be", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Hello, I am Alice\n" + ] + } + ], + "source": [ + "// Simple class example: define a Person class and instantiate it\n", + "class Person {\n", + " String name;\n", + " Person(String name) { this.name = name; }\n", + " String greet() { return \"Hello, I am \" + name; }\n", + "}\n", + "Person p = new Person(\"Alice\");\n", + "System.out.println(p.greet());" + ] + }, + { + "cell_type": "markdown", + "id": "f549cbc8", + "metadata": {}, + "source": [ + "## External compilation" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "3606b844", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%maven org.projectlombok:lombok:1.18.42" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "c14e858c", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "## %%compile - Compile Java source code and add to classpath\n", + "\n", + "**Usage:** `%%compile [--verbose] [--debug] [--nowarn] fully.qualified.ClassName`\n", + "\n", + "**Arguments:**\n", + "- `className` : Fully qualified class name (e.g., com.example.MyClass)\n", + "\n", + "**Options:**\n", + "- `--verbose, -v` : Enable verbose compilation output\n", + "- `--debug, -d` : Include debug information in compiled classes\n", + "- `--nowarn, -w` : Suppress compiler warnings\n", + "- `--help, -h` : Show this help message\n", + "\n", + "**Examples:**\n", + "```\n", + "%%compile com.example.Calculator\n", + "public class Calculator {\n", + " public int add(int a, int b) { return a + b; }\n", + "}\n", + "```\n", + "\n", + "```\n", + "%%compile --verbose --debug com.example.MyClass\n", + "public class MyClass {\n", + " public void hello() { System.out.println(\"Hello!\"); }\n", + "}\n", + "```\n", + "\n", + "**Note:** Package declaration will be added automatically if not present.\n", + "\n" + ] + } + ], + "source": [ + "%%compile --help" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "f15afeff", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%%compile --class=com.example.demo.Hello --output=out\n", + "package com.example.demo;\n", + "public class Hello {\n", + " public static String greet() { return \"Hello from compiled class\"; }\n", + "}" + ] + }, + { + "cell_type": "markdown", + "id": "02bab005", + "metadata": {}, + "source": [ + "After the `%%compile` cell finishes, the compiled classes are placed in the specified `out` directory and are added to the kernel classpath automatically by the magics (as exercised by the tests)." + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "id": "237d7c9b", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/plain": [ + "\u001b[36mcom.example.demo.Hello.greet();\u001b[0m: Hello from compiled class" + ] + }, + "execution_count": 12, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "com.example.demo.Hello.greet();" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "id": "0481b2b2", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%%compile --class=com.example.demo.LombokPerson --output=out --processor-path=/var/home/bruno/.m2/repository/org/projectlombok/lombok/1.18.42/lombok-1.18.42.jar --classpath=/var/home/bruno/.m2/repository/org/projectlombok/lombok/1.18.42/lombok-1.18.42.jar\n", + "package com.example.demo;\n", + "import lombok.Data;\n", + "import lombok.AllArgsConstructor;\n", + "@Data\n", + "@AllArgsConstructor\n", + "public class LombokPerson {\n", + " private String name;\n", + " private int age;\n", + "}" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "id": "f7128d07", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Bob age=30\n", + "LombokPerson(name=Bob, age=30)\n" + ] + } + ], + "source": [ + "// Instantiate and use the compiled Lombok class\n", + "com.example.demo.LombokPerson lp = new com.example.demo.LombokPerson(\"Bob\", 30);\n", + "System.out.println(lp.getName() + \" age=\" + lp.getAge());\n", + "System.out.println(lp);" + ] + }, + { + "cell_type": "markdown", + "id": "f8263310", + "metadata": {}, + "source": [ + "## Shell" + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "id": "4968d01a", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "## %%shell - Execute shell commands\n", + "\n", + "**Usage:** `%%shell [--shell=SHELL] [--timeout=SECONDS]`\n", + "\n", + "**Options:**\n", + "- `--shell=SHELL` : Shell to use (default: zsh, or $SHELL environment variable)\n", + "- `--timeout=SECONDS` : Maximum execution time in seconds (default: 180)\n", + "- `--help, -h` : Show this help message\n", + "\n", + "**Examples:**\n", + "```\n", + "%%shell\n", + "ls -la\n", + "```\n", + "\n", + "```\n", + "%%shell --shell=bash\n", + "echo \"Using bash\"\n", + "```\n", + "\n", + "```\n", + "%%shell --timeout=60\n", + "long-running-command\n", + "```\n", + "\n" + ] + } + ], + "source": [ + "%%shell --help" + ] + }, + { + "cell_type": "code", + "execution_count": 16, + "id": "05391c3a", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "bash\n", + "Hello from shell\n", + "42\n" + ] + } + ], + "source": [ + "%%shell\n", + "# Run a simple shell command. The shared executor streams stdout/stderr and preserves environment variables across cells when appropriate.\n", + "echo $SHELL\n", + "echo \"Hello from shell\"\n", + "export MYVAR=42\n", + "echo $MYVAR" + ] + }, + { + "cell_type": "code", + "execution_count": 17, + "id": "2f994624", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "bash\n", + "Hello from zsh shell\n" + ] + } + ], + "source": [ + "%%shell --shell=zsh\n", + "echo $SHELL\n", + "echo \"Hello from zsh shell\"\n" + ] + }, + { + "cell_type": "markdown", + "id": "92609497", + "metadata": {}, + "source": [ + "## Databases" + ] + }, + { + "cell_type": "code", + "execution_count": 18, + "id": "63f2121b", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "%maven - Add individual Maven coordinates to the classpath\n", + "\n", + "Usage: %maven :[:[:]]: [ ...]\n", + "\n", + "Examples:\n", + " %maven org.h2:h2:2.4.240\n", + " %maven com.google.guava:guava:32.1.2-jre org.apache.commons:commons-lang3:3.12.0\n", + "\n", + "Options:\n", + " --help, -h Show this help message\n", + "\n", + "Notes:\n", + " Coordinates must follow Maven coordinate format. Multiple coordinates may be provided.\n" + ] + } + ], + "source": [ + "%maven --help" + ] + }, + { + "cell_type": "code", + "execution_count": 19, + "id": "e4cd33c7", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%maven com.h2database:h2:2.4.240" + ] + }, + { + "cell_type": "code", + "execution_count": 20, + "id": "18c47637", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "System.setProperty(\"jdbc.url\", \"jdbc:h2:mem:test;DB_CLOSE_DELAY=-1\");\n", + "System.setProperty(\"jdbc.user\", \"sa\");\n", + "System.setProperty(\"jdbc.password\", \"\");" + ] + }, + { + "cell_type": "code", + "execution_count": 21, + "id": "2b08450b", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%%sqlAsTable --help" + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "id": "020dddda", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/markdown": [ + "Updated 3 rows" + ], + "text/plain": [ + "Updated 3 rows" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/markdown": [ + "Updated 2 rows" + ], + "text/plain": [ + "Updated 2 rows" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/markdown": [ + "Updated 3 rows" + ], + "text/plain": [ + "Updated 3 rows" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/html": [ + "\n", + "\n", + "\n", + "\n", + "\n", + "\n", + "
IDNAMEPRICE
1Widget9.99
2Gadget19.95
3Thingamajig4.50
" + ], + "text/plain": [ + "\n", + "\n", + "\n", + "\n", + "\n", + "\n", + "
IDNAMEPRICE
1Widget9.99
2Gadget19.95
3Thingamajig4.50
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%sqlAsTable\n", + "-- Example using a jdbc connection defined by system properties jdbc.url, jdbc.user, jdbc.password\n", + "-- Creates multiple related tables and demonstrates inserts and joins\n", + "\n", + "-- products catalog\n", + "CREATE TABLE IF NOT EXISTS products(id INT PRIMARY KEY, name VARCHAR(100), price DECIMAL(10,2));\n", + "MERGE INTO products VALUES\n", + " (1, 'Widget', 9.99),\n", + " (2, 'Gadget', 19.95),\n", + " (3, 'Thingamajig', 4.50);\n", + "\n", + "-- orders and order items\n", + "CREATE TABLE IF NOT EXISTS orders(id INT PRIMARY KEY, customer_id INT, order_date DATE);\n", + "-- use a composite primary key so MERGE INTO can match rows\n", + "CREATE TABLE IF NOT EXISTS order_items(order_id INT, product_id INT, qty INT, PRIMARY KEY(order_id, product_id));\n", + "\n", + "MERGE INTO orders VALUES (1, 1, DATE '2025-12-01'), (2, 2, DATE '2025-12-02');\n", + "MERGE INTO order_items(order_id, product_id, qty) KEY(order_id, product_id) VALUES\n", + " (1, 1, 2),\n", + " (1, 3, 1),\n", + " (2, 2, 4);\n", + "\n", + "-- verify tables\n", + "SELECT * FROM products;\n", + "SELECT * FROM orders;\n", + "SELECT * FROM order_items;\n", + "\n", + "-- example join: order totals per order\n", + "SELECT o.id AS order_id, o.order_date, d.name AS customer, SUM(p.price * oi.qty) AS total\n", + "FROM orders o\n", + "JOIN order_items oi ON oi.order_id = o.id\n", + "JOIN products p ON p.id = oi.product_id\n", + "GROUP BY o.id, o.order_date, d.name\n", + ";" + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "id": "b2d60553", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "## %%rdbmsSchema - Render DB schema as PlantUML\n", + "\n", + "Usage: %%rdbmsSchema [--help] [] [SVG|PNG] [--show-source] [include=] [exclude=]\n", + "\n", + "Provide table names in the cell body (one per line) to limit the diagram.\n" + ] + } + ], + "source": [ + "%%rdbmsSchema --help" + ] + }, + { + "cell_type": "code", + "execution_count": 24, + "id": "83570636", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "image/svg+xml": [ + "ORDERSPKID: INTEGER(32)*CUSTOMER_ID : INTEGER(32)*ORDER_DATE : DATE(10)PRODUCTSPKID: INTEGER(32)*NAME : CHARACTER VARYING(100)*PRICE : DECIMAL(10)" + ], + "text/plain": [ + "ORDERSPKID: INTEGER(32)*CUSTOMER_ID : INTEGER(32)*ORDER_DATE : DATE(10)PRODUCTSPKID: INTEGER(32)*NAME : CHARACTER VARYING(100)*PRICE : DECIMAL(10)" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%rdbmsSchema\n", + "-- Render the schema for a given JDBC connection as HTML/SVG (depends on implementation).\n", + "ORDERS\n", + "PRODUCTS" + ] + }, + { + "cell_type": "markdown", + "id": "1fc6d542", + "metadata": {}, + "source": [ + "## Java source helper demos\n", + "These cells demonstrate the `%%javasrc*` magics for extracting classes, methods, constructors, fields, and Javadoc from source files. The demos use sample sources under `docs/sample_java` included in this repository." + ] + }, + { + "cell_type": "code", + "execution_count": 25, + "id": "fe2f0039", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/markdown": [ + "**Usage:** `%%javasrcClassByName `\n", + "\n", + "Extract entire class source by FQCN. Body may contain file path." + ], + "text/plain": [ + "**Usage:** `%%javasrcClassByName `\n", + "\n", + "Extract entire class source by FQCN. Body may contain file path." + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%javasrcClassByName --help" + ] + }, + { + "cell_type": "code", + "execution_count": 26, + "id": "c04b48ea", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/markdown": [ + "```Java\n", + "public class Greeter {\n", + " private final String name;\n", + "\n", + " public Greeter(String name) {\n", + " this.name = name;\n", + " }\n", + "\n", + " /**\n", + " * Greets the person by name.\n", + " * \n", + " * @return A greeting message.\n", + " */\n", + " public String greet() {\n", + " return \"Hello \" + name;\n", + " }\n", + "}\n", + "```" + ], + "text/plain": [ + "```Java\n", + "public class Greeter {\n", + " private final String name;\n", + "\n", + " public Greeter(String name) {\n", + " this.name = name;\n", + " }\n", + "\n", + " /**\n", + " * Greets the person by name.\n", + " * \n", + " * @return A greeting message.\n", + " */\n", + " public String greet() {\n", + " return \"Hello \" + name;\n", + " }\n", + "}\n", + "```" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%javasrcClassByName com.example.Greeter\n", + "../docs/sample_java/com/example/Greeter.java" + ] + }, + { + "cell_type": "code", + "execution_count": 27, + "id": "33a64ebb", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/markdown": [ + "**Usage:** `%%javasrcMethodByName [options] [methodName|index]`\n", + "\n", + "**Options:**\n", + "- `--src `: source root to resolve FQCN (e.g., `--src=sample_java`)\n", + "- `methodRegex=`: select methods whose name matches regex\n", + "- `selectIndex=` or positional index: pick one when multiple matches\n", + "- `--raw` / `--fenced`: output format\n", + "\n", + "**Examples:**\n", + "- `%%javasrcMethodByName methodRegex=summary --src=sample_java com.example.OrderExample`\n", + "- `%%javasrcMethodByName com.example.OrderExample myMethod`\n", + "- `%%javasrcMethodByName selectIndex=1 com.example.OrderExample myMethod`\n" + ], + "text/plain": [ + "**Usage:** `%%javasrcMethodByName [options] [methodName|index]`\n", + "\n", + "**Options:**\n", + "- `--src `: source root to resolve FQCN (e.g., `--src=sample_java`)\n", + "- `methodRegex=`: select methods whose name matches regex\n", + "- `selectIndex=` or positional index: pick one when multiple matches\n", + "- `--raw` / `--fenced`: output format\n", + "\n", + "**Examples:**\n", + "- `%%javasrcMethodByName methodRegex=summary --src=sample_java com.example.OrderExample`\n", + "- `%%javasrcMethodByName com.example.OrderExample myMethod`\n", + "- `%%javasrcMethodByName selectIndex=1 com.example.OrderExample myMethod`\n" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%javasrcMethodByName --help" + ] + }, + { + "cell_type": "code", + "execution_count": 28, + "id": "0898c655", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/markdown": [ + "```Java\n", + "/**\n", + " * Returns a summary of the product.\n", + " *\n", + " * @param p The product to summarize.\n", + " * @return A string summary of the product.\n", + " */\n", + "public static String summary(Product p) {\n", + " return p.id + \":\" + p.name + \":\" + p.price;\n", + "}\n", + "```" + ], + "text/plain": [ + "```Java\n", + "/**\n", + " * Returns a summary of the product.\n", + " *\n", + " * @param p The product to summarize.\n", + " * @return A string summary of the product.\n", + " */\n", + "public static String summary(Product p) {\n", + " return p.id + \":\" + p.name + \":\" + p.price;\n", + "}\n", + "```" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%javasrcMethodByName com.example.OrderExample summary\n", + "../docs/sample_java/com/example/OrderExample.java" + ] + }, + { + "cell_type": "code", + "execution_count": 29, + "id": "d471c6f9", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/markdown": [ + "**Usage:** `%%javasrcMethodByAnnotationName [index]`\n", + "\n", + "Extract methods annotated with a given annotation from source file (body should be path to file)." + ], + "text/plain": [ + "**Usage:** `%%javasrcMethodByAnnotationName [index]`\n", + "\n", + "Extract methods annotated with a given annotation from source file (body should be path to file)." + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%javasrcMethodByAnnotationName --help" + ] + }, + { + "cell_type": "code", + "execution_count": 30, + "id": "6b425967", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/markdown": [ + "```Java\n", + "@Deprecated(since = 1)\n", + "public void oldMethod() {\n", + " System.out.println(\"old ...\");\n", + "}\n", + "```" + ], + "text/plain": [ + "```Java\n", + "@Deprecated(since = 1)\n", + "public void oldMethod() {\n", + " System.out.println(\"old ...\");\n", + "}\n", + "```" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%javasrcMethodByAnnotationName com.example.Product Deprecated\n", + "../docs/sample_java/com/example/Product.java" + ] + }, + { + "cell_type": "code", + "execution_count": 31, + "id": "f56fa36e", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/markdown": [ + "**Usage:** `%%javasrcConstructorByName `\n", + "\n", + "Show constructors for a class. Body may contain file path." + ], + "text/plain": [ + "**Usage:** `%%javasrcConstructorByName `\n", + "\n", + "Show constructors for a class. Body may contain file path." + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%javasrcConstructorByName --help" + ] + }, + { + "cell_type": "code", + "execution_count": 32, + "id": "82e2cfbb", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/markdown": [ + "```Java\n", + "0: Product(long, String)\n", + "\n", + "public Product(long id, String name) {\n", + " this(id, name, -1);\n", + "}\n", + "\n", + "1: Product(long, String, double)\n", + "\n", + "public Product(long id, String name, double price) {\n", + " this.id = id;\n", + " this.name = name;\n", + " this.price = price;\n", + "}\n", + "\n", + "\n", + "```" + ], + "text/plain": [ + "```Java\n", + "0: Product(long, String)\n", + "\n", + "public Product(long id, String name) {\n", + " this(id, name, -1);\n", + "}\n", + "\n", + "1: Product(long, String, double)\n", + "\n", + "public Product(long id, String name, double price) {\n", + " this.id = id;\n", + " this.name = name;\n", + " this.price = price;\n", + "}\n", + "\n", + "\n", + "```" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%javasrcConstructorByName com.example.Product\n", + "../docs/sample_java/com/example/Product.java" + ] + }, + { + "cell_type": "code", + "execution_count": 33, + "id": "11d6e07e", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/markdown": [ + "**Usage:** `%%javasrcFieldByName [filter] [--full=true]`\n", + "\n", + "List or show fields for a class." + ], + "text/plain": [ + "**Usage:** `%%javasrcFieldByName [filter] [--full=true]`\n", + "\n", + "List or show fields for a class." + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%javasrcFieldByName --help" + ] + }, + { + "cell_type": "code", + "execution_count": 34, + "id": "f51da0ac", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/markdown": [ + "```Java\n", + "String name (modifiers: private final )\n", + "\n", + "private final String name;\n", + "\n", + "\n", + "```" + ], + "text/plain": [ + "```Java\n", + "String name (modifiers: private final )\n", + "\n", + "private final String name;\n", + "\n", + "\n", + "```" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%javasrcFieldByName com.example.Greeter\n", + "../docs/sample_java/com/example/Greeter.java" + ] + }, + { + "cell_type": "code", + "execution_count": 35, + "id": "0de30e18", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/markdown": [ + "**Usage:** `%%javasrcJavadoc [memberName]`\n", + "\n", + "Show javadoc for class or member." + ], + "text/plain": [ + "**Usage:** `%%javasrcJavadoc [memberName]`\n", + "\n", + "Show javadoc for class or member." + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%javasrcJavadoc --help" + ] + }, + { + "cell_type": "code", + "execution_count": 36, + "id": "ee9cb95d", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/markdown": [ + "OrderExample is a fake java class\n", + "\n", + "- @see — Product" + ], + "text/plain": [ + "OrderExample is a fake java class\n", + "\n", + "- @see — Product" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%javasrcJavadoc com.example.OrderExample\n", + "../docs/sample_java/com/example/OrderExample.java" + ] + }, + { + "cell_type": "code", + "execution_count": 37, + "id": "e70d0cee", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/markdown": [ + "Returns a summary of the product.\n", + "\n", + "- @param p — The product to summarize.\n", + "- @return — A string summary of the product." + ], + "text/plain": [ + "Returns a summary of the product.\n", + "\n", + "- @param p — The product to summarize.\n", + "- @return — A string summary of the product." + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%javasrcJavadoc com.example.OrderExample summary\n", + "../docs/sample_java/com/example/OrderExample.java" + ] + }, + { + "cell_type": "markdown", + "id": "9c30e548", + "metadata": {}, + "source": [ + "## TimeIt demo\n", + "This cell demonstrates the `%%timeit` cell-magic (aliases `%%time`) to measure execution time. Use `iterations` and `warmup` to adjust sampling." + ] + }, + { + "cell_type": "code", + "execution_count": 38, + "id": "a9482ebf", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "help: \n", + "example: \n", + "\n", + "%%time epochs=3 loops=5\n", + "1 + 1\n" + ] + } + ], + "source": [ + "%%timeit --help" + ] + }, + { + "cell_type": "code", + "execution_count": 39, + "id": "aea54b0e", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "samples: [25110850, 23485074, 23968668, 17996648, 17317386]\n", + "min=17317386 median=23485074 avg=21575725,20 max=25110850 (nanoseconds)\n" + ] + } + ], + "source": [ + "%%timeit iterations=5 warmup=1\n", + "// Simple workload: sum integers up to n and return the sum\n", + "int n = 100_000;\n", + "int s = 0;\n", + "for (int i = 0; i < n; i++) s += i;\n", + "s;" + ] + }, + { + "cell_type": "markdown", + "id": "54d99c1d", + "metadata": {}, + "source": [ + "## Benchmark: HashMap vs TreeMap\n", + "This cell runs the `%%benchmark` magic to compare `HashMap` and `TreeMap` performance. It performs a sweep over map sizes (`n`) and renders a chart. Adjust `start`/`end`/`step` to change the sweep range." + ] + }, + { + "cell_type": "code", + "execution_count": 40, + "id": "117a9618", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "## %%benchmark - Compare implementations performance\n", + "\n", + "Usage: %%benchmark [--help] [--sweep var= start= end= step=] [--chart] [iterations=] [warmup=]\\n\n", + "Provide one or more implementations separated by a line containing '---'.\n", + "Example:\n", + "%%benchmark iterations=5\n", + "code-for-impl-1\n", + "---\n", + "code-for-impl-2\n", + "\n" + ] + } + ], + "source": [ + "%%benchmark --help" + ] + }, + { + "cell_type": "code", + "execution_count": 41, + "id": "f25a7a92", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "// Helper: run a Supplier-driven test and return accumulated result\n", + "import java.util.function.Supplier;\n", + "// runSupplierTest calls the supplier 'iterations' times and accumulates its results\n", + "int runSupplierTest(Supplier supplier, int iterations) {\n", + " int acc = 0;\n", + " for (int i = 0; i < iterations; i++) acc += supplier.get();\n", + " return acc;\n", + "}\n", + "\n", + "// Factory: build a Supplier that performs a mixed random read/write workload\n", + "// mapFactory: creates an empty Map\n", + "// readRatio: fraction of operations that are reads (0.0-1.0)\n", + "// opsPerInvocation: number of random ops the supplier performs per get()\n", + "import java.util.Map;\n", + "import java.util.Random;\n", + "Supplier makeMapRWTest(java.util.function.Supplier> mapFactory, double readRatio, int opsPerInvocation) {\n", + " Map map = mapFactory.get();\n", + " Random initRnd = new Random(12345);\n", + " // pre-populate map with a sparse keyspace\n", + " for (int i = 0; i < n; i++) map.put(initRnd.nextInt(n * 10), i);\n", + " Random localRnd = new Random(54321);\n", + " return () -> {\n", + " int localAcc = 0;\n", + " for (int op = 0; op < opsPerInvocation; op++) {\n", + " if (localRnd.nextDouble() < readRatio) {\n", + " Integer v = map.get(localRnd.nextInt(n * 10));\n", + " localAcc += (v != null) ? v : 0;\n", + " } else {\n", + " int key = localRnd.nextInt(n * 10);\n", + " map.put(key, localRnd.nextInt());\n", + " }\n", + " }\n", + " return localAcc;\n", + " };\n", + "}" + ] + }, + { + "cell_type": "code", + "execution_count": 42, + "id": "5a7f5050", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "image/svg+xml": [ + "10002000300040005000600070008000900010000nBenchmark sweep: n0,003,316,629,9313,2416,559,829,448,239,0416,558,239,107,155,897,189,8010,738,688,4010,0910,8113,177,947,657,02// HashMap implementation// TreeMap implementationaveraged over 10 iterations (warmup=1)" + ], + "text/plain": [ + "10002000300040005000600070008000900010000nBenchmark sweep: n0,003,316,629,9313,2416,559,829,448,239,0416,558,239,107,155,897,189,8010,738,688,4010,0910,8113,177,947,657,02// HashMap implementation// TreeMap implementationaveraged over 10 iterations (warmup=1)" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%benchmark --sweep --chart var=n start=1000 end=10000 step=1000 iterations=10 warmup=1\n", + "// HashMap implementation\n", + "import java.util.HashMap;\n", + "java.util.function.Supplier sanitySupplier = makeMapRWTest(() -> new java.util.HashMap<>(), 0.9, n);\n", + "---\n", + "// TreeMap implementation\n", + "import java.util.TreeMap;\n", + "java.util.function.Supplier sanitySupplier = makeMapRWTest(() -> new java.util.TreeMap<>(), 0.9, n);" + ] + }, + { + "cell_type": "markdown", + "id": "e3cb6dc1", + "metadata": {}, + "source": [ + "## Class diagrams\n", + "\n", + "Examples showing the new `%classDiagram` and `%%classDiagram` magics." + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "99467b83", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "%classDiagram usage:\n", + " %classDiagram \n", + " %classDiagram --package=pkg [options]\n", + "\n", + "Options:\n", + " --svg | --png | --uml\n", + " --include=regex --exclude=regex\n", + " --interfaces-only --classes-only\n", + " --ancestors --depth=N\n", + " --max=N --non-public\n", + " --out=file\n", + "\n" + ] + } + ], + "source": [ + "%classDiagram --help" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "f01b8759", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Classpath error: com.example.demo.Hello\n", + "No classes found.\n" + ] + } + ], + "source": [ + "%classDiagram com.example.demo.Hello" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "59d54da7", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%%compile --class=com.example.demo.C --output=out\n", + "package com.example.demo;\n", + "interface C {\n", + " default int x() { return 42; }\n", + "}" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "d49e214a", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%%compile --class=com.example.demo.A --output=out\n", + "package com.example.demo;\n", + "public class A implements C {\n", + "}" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "21bc5030", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [], + "source": [ + "%%compile --class=com.example.demo.B --output=out\n", + "package com.example.demo;\n", + "public class B extends A {\n", + "}" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "e6e614c6", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "No classes found.\n" + ] + } + ], + "source": [ + "%%classDiagram --package=com.example.demo --svg" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "317ff290", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "image/svg+xml": [ + "ArrayList+ArrayList(Collection)+ArrayList()+ArrayList(int)+remove(Object) : boolean+remove(int) : Object+size() : int+get(int) : Object+equals(Object) : boolean+hashCode() : int+clone() : Object+sort(Comparator) : void+indexOf(Object) : int+clear() : void+lastIndexOf(Object) : int+isEmpty() : boolean+replaceAll(UnaryOperator) : void+add(Object) : boolean+add(int, Object) : void+subList(int, int) : List+toArray(Object[]) : Object[]+toArray() : Object[]+iterator() : Iterator+contains(Object) : boolean+spliterator() : Spliterator+addAll(Collection) : boolean+addAll(int, Collection) : boolean+trimToSize() : void+set(int, Object) : Object+forEach(Consumer) : void+ensureCapacity(int) : void+removeIf(Predicate) : boolean+getFirst() : Object+getLast() : Object+addFirst(Object) : void+addLast(Object) : void+removeFirst() : Object+removeLast() : Object+removeAll(Collection) : boolean+retainAll(Collection) : boolean+listIterator(int) : ListIterator+listIterator() : ListIteratorAbstractList+remove(int) : Object+get(int) : Object+equals(Object) : boolean+hashCode() : int+indexOf(Object) : int+clear() : void+lastIndexOf(Object) : int+add(int, Object) : void+add(Object) : boolean+subList(int, int) : List+iterator() : Iterator+addAll(int, Collection) : boolean+set(int, Object) : Object+listIterator() : ListIterator+listIterator(int) : ListIteratorList+remove(int) : Object+remove(Object) : boolean+size() : int+get(int) : Object+equals(Object) : boolean+hashCode() : int+copyOf(Collection) : List+sort(Comparator) : void+indexOf(Object) : int+clear() : void+of(Object) : List+of(Object, Object) : List+of(Object, Object, Object) : List+of(Object, Object, Object, Object, Object, Object, Object, Object, Object) : List+of(Object, Object, Object, Object, Object, Object, Object, Object, Object, Object) : List+of(Object[]) : List+of() : List+of(Object, Object, Object, Object, Object) : List+of(Object, Object, Object, Object, Object, Object, Object, Object) : List+of(Object, Object, Object, Object, Object, Object) : List+of(Object, Object, Object, Object, Object, Object, Object) : List+of(Object, Object, Object, Object) : List+lastIndexOf(Object) : int+isEmpty() : boolean+replaceAll(UnaryOperator) : void+add(int, Object) : void+add(Object) : boolean+subList(int, int) : List+toArray() : Object[]+toArray(Object[]) : Object[]+iterator() : Iterator+contains(Object) : boolean+spliterator() : Spliterator+addAll(Collection) : boolean+addAll(int, Collection) : boolean+set(int, Object) : Object+getFirst() : Object+getLast() : Object+addFirst(Object) : void+addLast(Object) : void+removeFirst() : Object+removeLast() : Object+removeAll(Collection) : boolean+retainAll(Collection) : boolean+listIterator() : ListIterator+listIterator(int) : ListIterator+reversed() : List+containsAll(Collection) : booleanRandomAccessCloneableSerializableAbstractCollection+remove(Object) : boolean+size() : int+toString() : String+clear() : void+isEmpty() : boolean+add(Object) : boolean+toArray(Object[]) : Object[]+toArray() : Object[]+iterator() : Iterator+contains(Object) : boolean+addAll(Collection) : boolean+removeAll(Collection) : boolean+retainAll(Collection) : boolean+containsAll(Collection) : booleanSequencedCollection+getFirst() : Object+getLast() : Object+addFirst(Object) : void+addLast(Object) : void+removeFirst() : Object+removeLast() : Object+reversed() : SequencedCollectionCollection+remove(Object) : boolean+size() : int+equals(Object) : boolean+hashCode() : int+clear() : void+isEmpty() : boolean+add(Object) : boolean+toArray(Object[]) : Object[]+toArray(IntFunction) : Object[]+toArray() : Object[]+iterator() : Iterator+stream() : Stream+contains(Object) : boolean+spliterator() : Spliterator+addAll(Collection) : boolean+removeIf(Predicate) : boolean+removeAll(Collection) : boolean+retainAll(Collection) : boolean+containsAll(Collection) : boolean+parallelStream() : Stream" + ], + "text/plain": [ + "ArrayList+ArrayList(Collection)+ArrayList()+ArrayList(int)+remove(Object) : boolean+remove(int) : Object+size() : int+get(int) : Object+equals(Object) : boolean+hashCode() : int+clone() : Object+sort(Comparator) : void+indexOf(Object) : int+clear() : void+lastIndexOf(Object) : int+isEmpty() : boolean+replaceAll(UnaryOperator) : void+add(Object) : boolean+add(int, Object) : void+subList(int, int) : List+toArray(Object[]) : Object[]+toArray() : Object[]+iterator() : Iterator+contains(Object) : boolean+spliterator() : Spliterator+addAll(Collection) : boolean+addAll(int, Collection) : boolean+trimToSize() : void+set(int, Object) : Object+forEach(Consumer) : void+ensureCapacity(int) : void+removeIf(Predicate) : boolean+getFirst() : Object+getLast() : Object+addFirst(Object) : void+addLast(Object) : void+removeFirst() : Object+removeLast() : Object+removeAll(Collection) : boolean+retainAll(Collection) : boolean+listIterator(int) : ListIterator+listIterator() : ListIteratorAbstractList+remove(int) : Object+get(int) : Object+equals(Object) : boolean+hashCode() : int+indexOf(Object) : int+clear() : void+lastIndexOf(Object) : int+add(int, Object) : void+add(Object) : boolean+subList(int, int) : List+iterator() : Iterator+addAll(int, Collection) : boolean+set(int, Object) : Object+listIterator() : ListIterator+listIterator(int) : ListIteratorList+remove(int) : Object+remove(Object) : boolean+size() : int+get(int) : Object+equals(Object) : boolean+hashCode() : int+copyOf(Collection) : List+sort(Comparator) : void+indexOf(Object) : int+clear() : void+of(Object) : List+of(Object, Object) : List+of(Object, Object, Object) : List+of(Object, Object, Object, Object, Object, Object, Object, Object, Object) : List+of(Object, Object, Object, Object, Object, Object, Object, Object, Object, Object) : List+of(Object[]) : List+of() : List+of(Object, Object, Object, Object, Object) : List+of(Object, Object, Object, Object, Object, Object, Object, Object) : List+of(Object, Object, Object, Object, Object, Object) : List+of(Object, Object, Object, Object, Object, Object, Object) : List+of(Object, Object, Object, Object) : List+lastIndexOf(Object) : int+isEmpty() : boolean+replaceAll(UnaryOperator) : void+add(int, Object) : void+add(Object) : boolean+subList(int, int) : List+toArray() : Object[]+toArray(Object[]) : Object[]+iterator() : Iterator+contains(Object) : boolean+spliterator() : Spliterator+addAll(Collection) : boolean+addAll(int, Collection) : boolean+set(int, Object) : Object+getFirst() : Object+getLast() : Object+addFirst(Object) : void+addLast(Object) : void+removeFirst() : Object+removeLast() : Object+removeAll(Collection) : boolean+retainAll(Collection) : boolean+listIterator() : ListIterator+listIterator(int) : ListIterator+reversed() : List+containsAll(Collection) : booleanRandomAccessCloneableSerializableAbstractCollection+remove(Object) : boolean+size() : int+toString() : String+clear() : void+isEmpty() : boolean+add(Object) : boolean+toArray(Object[]) : Object[]+toArray() : Object[]+iterator() : Iterator+contains(Object) : boolean+addAll(Collection) : boolean+removeAll(Collection) : boolean+retainAll(Collection) : boolean+containsAll(Collection) : booleanSequencedCollection+getFirst() : Object+getLast() : Object+addFirst(Object) : void+addLast(Object) : void+removeFirst() : Object+removeLast() : Object+reversed() : SequencedCollectionCollection+remove(Object) : boolean+size() : int+equals(Object) : boolean+hashCode() : int+clear() : void+isEmpty() : boolean+add(Object) : boolean+toArray(Object[]) : Object[]+toArray(IntFunction) : Object[]+toArray() : Object[]+iterator() : Iterator+stream() : Stream+contains(Object) : boolean+spliterator() : Spliterator+addAll(Collection) : boolean+removeIf(Predicate) : boolean+removeAll(Collection) : boolean+retainAll(Collection) : boolean+containsAll(Collection) : boolean+parallelStream() : Stream" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%classDiagram java.util.ArrayList --svg --ancestors --exclude-inherited" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Java", + "language": "java", + "name": "java" + }, + "language_info": { + "codemirror_mode": "java", + "file_extension": ".jshell", + "mimetype": "text/x-java-source", + "name": "Java", + "pygments_lexer": "java", + "version": "25.0.1+8-LTS" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/notebooks/out/com/example/demo/A.class b/notebooks/out/com/example/demo/A.class new file mode 100644 index 0000000000000000000000000000000000000000..06f2a05a4a07bd6494a54ec7369664898b6f5496 GIT binary patch literal 219 zcmZvWy$ZrW5QJyVpT=m!-oj2TycZB51g%61#r~2Ul8{RzB;spX2^Kzp4<%l%mW5en zhGoCc_w@#_f$yRN!-46+f=w7@{Ki?%iwiqMnTTtGy-JI;UK5Pj{Oq7h7{{e#;?CtY z7c3F7WPt2{iAT9g++*2PvDl`qv4ds%8B;h4h|p7Xq((t0 Y?JGCY9^8R$Ly0jUBh=>Px# literal 0 HcmV?d00001 diff --git a/notebooks/out/com/example/demo/B.class b/notebooks/out/com/example/demo/B.class new file mode 100644 index 0000000000000000000000000000000000000000..9f1c2234e967e55e19a94857b57dc3055df7a15a GIT binary patch literal 195 zcmX^0Z`VEs1_oCKUM>bE24;2!79Ivx1~x_pq2&Br{nU!Y+=84`{gl+)e0@ho1~!|_ zyv!0iMh0dL%`kQb4s6Pt7#Ucc^HWk88TfrN^HTjvbCXhwLK2g5fFfMM`K3k4scxAd z4x5u+R$^HqgCYYv&}tB11VW(YK#~*4lLhk`7+AHoGcaxhOLGB9kTe5O10w@BnC1Zh D!V4q1 literal 0 HcmV?d00001 diff --git a/notebooks/out/com/example/demo/C.class b/notebooks/out/com/example/demo/C.class new file mode 100644 index 0000000000000000000000000000000000000000..ce576a30c3291a3b0d2ca5aa4f1cc830773c6ff2 GIT binary patch literal 176 zcmX^0Z`VEs1_oCKZgvJHMh2ne{9OIiip1Q4oK*dk)ZBc1XLbe_Mh1bb#Ii*FoW#6z zegCAa)Z`LI2F40T24)RSPeuk7=lqmZMh1SL%)C^;(%hufqL9R-9H0nSaDHh~a;jS< zh{NWr2Qq|>fdQxwXeEedWME}r1Cs1Oo-~-xz`!h^wFWH70VF|^Kp`N>38a}AxB#KF BAV&ZI literal 0 HcmV?d00001 diff --git a/notebooks/out/com/example/demo/Hello.class b/notebooks/out/com/example/demo/Hello.class new file mode 100644 index 0000000000000000000000000000000000000000..fd5ae47eb2200914a0bfcf6cc53981ebadf8e690 GIT binary patch literal 304 zcmZ9G%}T>S5Xb-1G)Wt)ts;Vm5O1vq_W>$iMDbAcQ1QM=#;|3REomw~mYxI;K7bD; z&gLRGhxz!=Z$7?%KED9mU_U_*L5%(gAtJ(LrC+qNx-Qj2w&J`cM3<&E?G+)I&YlJs z5RUKIT9-aIu1a%Pt&Qa(&8^;SVkCqk(G1^@$z_M*jUCs%~(rufZZ{>~@-Leah;S580-&+r|1(En2sZJ%5#PIwB h^ezcuB;L0@I>avaB=_h^rvbr1{PqtFq&4maCckr`I(q;B literal 0 HcmV?d00001 diff --git a/notebooks/out/com/example/demo/LombokPerson.class b/notebooks/out/com/example/demo/LombokPerson.class new file mode 100644 index 0000000000000000000000000000000000000000..86b36af5dfa0cfa2299439bab9d5eb4d4ecd1a8d GIT binary patch literal 1717 zcmah}TW=Fb6#izt_HN9Q8(>IHQc832Ex7j!c4&hI#ZnRwK_Im+Ozcszcs=8K$5DCj zkEr_6xAKyQRw`8Dp=w`>)Zf&Wo>?!jcHCC-dgh!tm+yS%%>429(_a8wLt_dSQVwhn zX=E4{TdG?XU-51)5Y@Kms_K^N?y1f#(GQhmuqE#bhWV`r{E$}zF88auy6?;VnhE53 zm_n8z#rMgGHM6AiJesmNA`62dG=_^FmP|7DfQJVS z)fV$a$psH@;3C7>F7Jqjk}a<9`I?SpsJYZ3!&(x3oVWQeSe8AkV3o4ged+5fQ9XBw zMU#zTX3LjiXVBdf{X2XwAWi=EKx)4$n)1*OeNt^osWjI1 z)+x~SLXPxnBrTG}Xib-X0{ekB3#i^IONIV}AL^aQ@GaE_UqqHLYpNa;seW9%=ii{2Q!qkxm_ze}%PODLui7 zNTkh7g}(31840I$NIG@dUVnxY3-<4rdjxNN!G40Xk-2Ruwh~0ysFEfJ$8rC}v;)ig z3poep=;yMLs%-Pr#pn$8hK;m=HBRC<8T1atZi3bnxvkpu{A}&OV835Cptp@!c?Ng3 z{0I(JaQ=QhKN%{G$8&nx=vlWIfdpgEDdtPjVxy=T-g-GPtCZeM%(O{ql0U`k!1(Bl z!(YMMG5oa{{!Hm-ycx|w>HLJIrblQ?;T=k8;a$8(t4jbrr0;!fkd&p}6?}@TSojBL Cms7p~ literal 0 HcmV?d00001 diff --git a/notebooks/out/src/com/example/demo/A.java b/notebooks/out/src/com/example/demo/A.java new file mode 100644 index 0000000..0414517 --- /dev/null +++ b/notebooks/out/src/com/example/demo/A.java @@ -0,0 +1,3 @@ +package com.example.demo; +public class A implements C { +} \ No newline at end of file diff --git a/notebooks/out/src/com/example/demo/B.java b/notebooks/out/src/com/example/demo/B.java new file mode 100644 index 0000000..7596cec --- /dev/null +++ b/notebooks/out/src/com/example/demo/B.java @@ -0,0 +1,3 @@ +package com.example.demo; +public class B extends A { +} \ No newline at end of file diff --git a/notebooks/out/src/com/example/demo/C.java b/notebooks/out/src/com/example/demo/C.java new file mode 100644 index 0000000..72f6c70 --- /dev/null +++ b/notebooks/out/src/com/example/demo/C.java @@ -0,0 +1,4 @@ +package com.example.demo; +interface C { + default int x() { return 42; } +} \ No newline at end of file diff --git a/notebooks/out/src/com/example/demo/Hello.java b/notebooks/out/src/com/example/demo/Hello.java new file mode 100644 index 0000000..7048a6d --- /dev/null +++ b/notebooks/out/src/com/example/demo/Hello.java @@ -0,0 +1,4 @@ +package com.example.demo; +public class Hello { + public static String greet() { return "Hello from compiled class"; } +} \ No newline at end of file diff --git a/notebooks/out/src/com/example/demo/LombokPerson.java b/notebooks/out/src/com/example/demo/LombokPerson.java new file mode 100644 index 0000000..4a08870 --- /dev/null +++ b/notebooks/out/src/com/example/demo/LombokPerson.java @@ -0,0 +1,9 @@ +package com.example.demo; +import lombok.Data; +import lombok.AllArgsConstructor; +@Data +@AllArgsConstructor +public class LombokPerson { + private String name; + private int age; +} \ No newline at end of file diff --git a/src/main/java/io/github/spencerpark/ijava/JavaKernel.java b/src/main/java/io/github/spencerpark/ijava/JavaKernel.java index e5cb767..b27288e 100644 --- a/src/main/java/io/github/spencerpark/ijava/JavaKernel.java +++ b/src/main/java/io/github/spencerpark/ijava/JavaKernel.java @@ -127,6 +127,7 @@ public JavaKernel() { magics.registerMagics(new JavaDBMSMagics()); magics.registerMagics(new JavaMagics()); magics.registerMagics(new JavaPlantUMLMagics()); + magics.registerMagics(new ClassDiagramMagics()); // Consolidated shell magics: `MyShellMagics` removed, use `ShellMagics` only. magics.registerMagics(new ShellMagics()); try { diff --git a/src/main/java/io/github/spencerpark/ijava/magics/BenchmarkMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/BenchmarkMagics.java index 7315138..f0ef6af 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/BenchmarkMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/BenchmarkMagics.java @@ -14,6 +14,15 @@ public void benchmark(List args, String body) throws Exception { if (body == null) body = ""; + // Help + if (args.contains("--help") || args.contains("-h")) { + System.out.println("## %%benchmark - Compare implementations performance\n\n" + + "Usage: %%benchmark [--help] [--sweep var= start= end= step=] [--chart] [iterations=] [warmup=]\\n\n" + + "Provide one or more implementations separated by a line containing '---'.\n" + + "Example:\n%%benchmark iterations=5\ncode-for-impl-1\n---\ncode-for-impl-2\n"); + return; + } + Map opts = OptionUtils.parseOptions(args); int iterations = Integer.parseInt(opts.getOrDefault("iterations", "5")); int warmup = Integer.parseInt(opts.getOrDefault("warmup", "1")); diff --git a/src/main/java/io/github/spencerpark/ijava/magics/ClassDiagramMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/ClassDiagramMagics.java new file mode 100644 index 0000000..2749905 --- /dev/null +++ b/src/main/java/io/github/spencerpark/ijava/magics/ClassDiagramMagics.java @@ -0,0 +1,304 @@ +package io.github.spencerpark.ijava.magics; + +import io.github.spencerpark.ijava.runtime.Display; +import io.github.spencerpark.jupyter.kernel.magic.registry.CellMagic; +import io.github.spencerpark.jupyter.kernel.magic.registry.LineMagic; +import io.github.classgraph.ClassGraph; +import io.github.classgraph.ScanResult; + +import java.io.*; +import java.nio.charset.StandardCharsets; +import java.util.*; +import java.util.regex.Pattern; + +public class ClassDiagramMagics { + + private static class Options { + boolean svg; + boolean png; + boolean umlOnly; + boolean includeNonPublic; + boolean includeAncestors; + boolean interfacesOnly; + boolean classesOnly; + boolean excludeInherited; // <-- nouveau + int max = 50; + int depth = 3; + String targetClass; + String targetPackage; + String includeRegex; + String excludeRegex; + String outFile; + } + + @LineMagic("classDiagram") + public void classDiagram(List args) { + String body = args == null ? "" : String.join(" ", args); + String[] parts = body.trim().isEmpty() ? new String[0] : body.trim().split("\\s+"); + + if (hasHelp(parts)) { + printHelp(); + return; + } + + Options o = parse(parts); + o.max = Math.max(1, Math.min(o.max, 500)); + + List> classes = loadClasses(o); + if (classes.isEmpty()) { + System.out.println("No classes found."); + return; + } + + if (o.includeAncestors) { + classes = expandAncestors(classes, o.depth, o.max); + } + + // ---------- Generate PlantUML ---------- + String plantuml = PlantUmlGenerator.generate( + classes, + true, // includeFields + true, // includeMethods + true, // includeConstructors + true, // includeInterfaces + o.includeNonPublic, + o.excludeInherited // <-- nouveau param + ); + + if (o.umlOnly) { + output(plantuml, "text/plain", o.outFile); + return; + } + + render(plantuml, o); + } + + // ---------- Parsing ---------- + private Options parse(String[] parts) { + Options o = new Options(); + List others = new ArrayList<>(); + + for (String p : parts) { + switch (p) { + case "--svg" -> o.svg = true; + case "--png" -> o.png = true; + case "--uml" -> o.umlOnly = true; + case "--non-public" -> o.includeNonPublic = true; + case "--ancestors" -> o.includeAncestors = true; + case "--interfaces-only" -> o.interfacesOnly = true; + case "--classes-only" -> o.classesOnly = true; + case "--exclude-inherited" -> o.excludeInherited = true; + default -> { + if (p.startsWith("--max=")) + o.max = parseInt(p, 6, 50); + else if (p.startsWith("--depth=")) + o.depth = parseInt(p, 8, 3); + else if (p.startsWith("--package=")) + o.targetPackage = p.substring(10); + else if (p.startsWith("--include=")) + o.includeRegex = p.substring(10); + else if (p.startsWith("--exclude=")) + o.excludeRegex = p.substring(10); + else if (p.startsWith("--out=")) + o.outFile = p.substring(6); + else if (!p.startsWith("--")) + others.add(p); + } + } + } + + if (!others.isEmpty()) + o.targetClass = others.get(0); + return o; + } + + private int parseInt(String p, int start, int def) { + try { + return Integer.parseInt(p.substring(start)); + } catch (Exception e) { + return def; + } + } + + private boolean hasHelp(String[] parts) { + for (String p : parts) + if (p.equalsIgnoreCase("--help") || p.equalsIgnoreCase("-h")) + return true; + return false; + } + + private void printHelp() { + System.out.println(""" + %classDiagram - Generate UML class diagrams using PlantUML + + USAGE: + %classDiagram [options] + %classDiagram --package= [options] + + TARGET SELECTION: + Generate diagram for a single class. + --package= Scan a package and include multiple classes. + + OUTPUT FORMAT (choose one): + --svg Render diagram as SVG image (default). + --png Render diagram as PNG image. + --uml Output raw PlantUML text only (no rendering). + + SCOPE / SIZE CONTROL: + --max= Maximum classes when scanning a package (default 50). + + VISIBILITY / DETAIL: + --non-public Include non-public fields, methods, constructors. + + HIERARCHY / ANCESTORS: + --ancestors Include superclasses and interfaces. + --depth= Ancestor depth when --ancestors is used (default 3). + + TYPE FILTERS: + --interfaces-only Include only interfaces. + --classes-only Include only classes (exclude interfaces). + + METHOD FILTER: + --exclude-inherited Exclude inherited methods and constructors. + + NAME FILTERS (regex, package scan only): + --include= Only include class names that match. + --exclude= Exclude class names that match. + + FILE OUTPUT: + --out= Save output to file (.svg, .png, .uml). + + HELP: + --help, -h Show this help message. + + EXAMPLES: + %classDiagram java.util.ArrayList + %classDiagram --package=java.util --max=80 --svg + %classDiagram com.myapp.Service --ancestors --depth=2 + %classDiagram --package=com.myapp --include=.*Service --png + %classDiagram java.util.List --uml --out=list.uml + """); + } + + // ---------- Class Loading ---------- + private List> loadClasses(Options o) { + List> result = new ArrayList<>(); + Pattern include = o.includeRegex == null ? null : Pattern.compile(o.includeRegex); + Pattern exclude = o.excludeRegex == null ? null : Pattern.compile(o.excludeRegex); + + try { + if (o.targetClass != null) { + result.add(Class.forName(o.targetClass)); + } else if (o.targetPackage != null) { + try (ScanResult scan = new ClassGraph() + .acceptPackages(o.targetPackage) + .enableClassInfo() + .scan()) { + + scan.getAllClasses().stream().limit(o.max).forEach(ci -> { + String name = ci.getName(); + if (include != null && !include.matcher(name).find()) + return; + if (exclude != null && exclude.matcher(name).find()) + return; + + try { + Class c = Class.forName(name); + if (o.interfacesOnly && !c.isInterface()) + return; + if (o.classesOnly && c.isInterface()) + return; + result.add(c); + } catch (Throwable ignored) { + } + }); + } + } + } catch (Throwable t) { + System.out.println("Classpath error: " + t.getMessage()); + } + + return result; + } + + // ---------- Ancestors ---------- + private List> expandAncestors(List> base, int depth, int max) { + Set> set = new LinkedHashSet<>(base); + Queue> q = new ArrayDeque<>(base); + int d = 0; + + while (!q.isEmpty() && set.size() < max && d < depth) { + int size = q.size(); + while (size-- > 0) { + Class c = q.poll(); + if (c == null) + continue; + + Class s = c.getSuperclass(); + if (s != null && s != Object.class && set.add(s)) + q.add(s); + + for (Class i : c.getInterfaces()) + if (set.add(i)) + q.add(i); + } + d++; + } + + return new ArrayList<>(set); + } + + // ---------- Rendering ---------- + private void render(String plantuml, Options o) { + try { + net.sourceforge.plantuml.SourceStringReader reader = new net.sourceforge.plantuml.SourceStringReader( + plantuml); + + ByteArrayOutputStream os = new ByteArrayOutputStream(); + net.sourceforge.plantuml.FileFormat fmt = o.png ? net.sourceforge.plantuml.FileFormat.PNG + : net.sourceforge.plantuml.FileFormat.SVG; + + net.sourceforge.plantuml.FileFormatOption opt = new net.sourceforge.plantuml.FileFormatOption(fmt); + reader.outputImage(os, opt); + byte[] data = os.toByteArray(); + + if (o.outFile != null) { + try (FileOutputStream fos = new FileOutputStream(o.outFile)) { + fos.write(data); + } + } + + if (o.png) { + Display.display(data, "image/png"); + } else { + Display.display(new String(data, StandardCharsets.UTF_8), "image/svg+xml"); + } + } catch (Throwable t) { + System.out.println("Render failed: " + t.getMessage()); + Display.display(plantuml, "text/plain"); + } + } + + private void output(String text, String mime, String out) { + try { + if (out != null) { + try (FileWriter fw = new FileWriter(out)) { + fw.write(text); + } + } + } catch (IOException ignored) { + } + Display.display(text, mime); + } + + // ---------- Cell Magic ---------- + @CellMagic("classDiagram") + public void classDiagramCell(List args, String body) { + List all = new ArrayList<>(); + if (args != null) + all.addAll(args); + if (body != null && !body.isBlank()) + all.add(body); + classDiagram(all); + } +} diff --git a/src/main/java/io/github/spencerpark/ijava/magics/ClasspathMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/ClasspathMagics.java index 4fefb3d..6146880 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/ClasspathMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/ClasspathMagics.java @@ -43,6 +43,13 @@ public ClasspathMagics(Consumer addToClasspath) { @LineMagic public List jars(List args) { + if (args == null) args = List.of(); + if (args.contains("--help") || args.contains("-h")) { + System.out.println("## %jars - Add jar files to classpath\n\n" + + "Usage: %jars [--help] ...\n\n" + + "Adds matching jar files to the kernel classpath and returns their paths."); + return List.of(); + } List jars = args.stream() .map(GlobFinder::new) .flatMap(g -> { @@ -62,6 +69,11 @@ public List jars(List args) { @LineMagic public List classpath(List args) { + if (args == null) args = List.of(); + if (args.contains("--help") || args.contains("-h")) { + System.out.println("## %classpath - Add paths to classpath\n\nUsage: %classpath [--help] ...\n\nAdds matching paths to the kernel classpath and returns their paths."); + return List.of(); + } List paths = args.stream() .map(GlobFinder::new) .flatMap(g -> { @@ -81,6 +93,11 @@ public List classpath(List args) { @LineMagic(value = "classpath-snapshot") public String classpathSnapshot(List args) { + if (args == null) args = List.of(); + if (args.contains("--help") || args.contains("-h")) { + System.out.println("## %classpath-snapshot - Show current classpath\n\nUsage: %classpath-snapshot [--help]\n\nPrints the current java.class.path entries and returns them as a string."); + return ""; + } String cp = System.getProperty("java.class.path"); String[] parts = cp.split(File.pathSeparator); StringBuilder sb = new StringBuilder(); diff --git a/src/main/java/io/github/spencerpark/ijava/magics/CompilerMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/CompilerMagics.java index ed0a9e9..66f039d 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/CompilerMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/CompilerMagics.java @@ -51,6 +51,13 @@ public CompilerMagics(Consumer addToClasspath) { @CellMagic("mycompile") public void mycompile(List args, String body) { + if (args == null) args = List.of(); + if (args.contains("--help") || args.contains("-h")) { + System.out.println("## %%mycompile - Compile a Java source snippet to classpath\n\n" + + "Usage: %%mycompile [--help]\n\n" + + "Provide the fully qualified class name as first arg; the cell body contains the source.\n"); + return; + } if (args.isEmpty()) throw new RuntimeException("Please specify *Class Canonical Name* in args!"); // 1. autofill package base on class canonical name diff --git a/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java index 3a0f8bb..df965da 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java @@ -167,6 +167,16 @@ private static String quoteIdentifier(String s) { */ @CellMagic("rdbmsSchema") public void rdbmsSchema(java.util.List args, String body) { + if (args != null) { + for (String a : args) { + if (a != null && (a.equals("--help") || a.equals("-h"))) { + System.out.println("## %%rdbmsSchema - Render DB schema as PlantUML\n\n" + + "Usage: %%rdbmsSchema [--help] [] [SVG|PNG] [--show-source] [include=] [exclude=]\n\n" + + "Provide table names in the cell body (one per line) to limit the diagram."); + return; + } + } + } // args may contain: [] [SVG|PNG] [showSource|-s] [handwritten] // [include=] [exclude=] [scale=] String schema = null; @@ -253,7 +263,18 @@ public void rdbmsSchema(java.util.List args, String body) { // ignore common comment markers so comments aren't treated as table names if (l.startsWith("//") || l.startsWith("#") || l.startsWith("--")) continue; - tableNames.add(l); + // skip SQL statements (SELECT/CREATE/INSERT/UPDATE/DELETE/etc.) if the user + // pasted SQL into the cell — rdbmsSchema expects table names, not queries. + if (l.matches("(?i)^(SELECT|INSERT|UPDATE|DELETE|CREATE|ALTER|DROP|TRUNCATE|WITH)\\b.*")) + continue; + // strip surrounding quotes and trailing semicolons + if ((l.startsWith("\"") && l.endsWith("\"")) || (l.startsWith("'") && l.endsWith("'"))) { + l = l.substring(1, l.length() - 1).trim(); + } + if (l.endsWith(";")) + l = l.substring(0, l.length() - 1).trim(); + if (!l.isEmpty()) + tableNames.add(l); } } @@ -377,6 +398,17 @@ public void sqlAsTable(java.util.List args, String body) { if (sql.isEmpty()) return; + if (args != null) { + for (String a : args) { + if (a != null && (a.equals("--help") || a.equals("-h"))) { + System.out.println("## %%sqlAsTable - Run SQL and render first SELECT result as table\n\n" + + "Usage: %%sqlAsTable [--help] [format=HTML|CSV] [max=] [showQuery]\n\n" + + "The cell body may contain DDL/DML statements followed by a SELECT; the first SELECT is rendered."); + return; + } + } + } + // parse args: format=HTML|CSV, max=, showQuery String format = "HTML"; int maxRows = 1000; @@ -423,62 +455,215 @@ public void sqlAsTable(java.util.List args, String body) { "text/markdown"); } - try (Statement st = conn.createStatement(); ResultSet rs = st.executeQuery(normalizedSql)) { - ResultSetMetaData md = rs.getMetaData(); - int cols = md.getColumnCount(); - - if (showQuery) - display("````sql\n" + sql + "\n````", "text/markdown"); - - // build CSV - if ("CSV".equalsIgnoreCase(format)) { - StringBuilder csv = new StringBuilder(); - for (int i = 1; i <= cols; i++) { - if (i > 1) - csv.append(','); - csv.append(escapeCsv(md.getColumnLabel(i))); + try (Statement st = conn.createStatement()) { + // Split the provided SQL into individual statements. The magic allows a + // cell to contain DDL/DML statements followed by a final SELECT whose + // results are rendered as a table. We therefore execute non-query + // statements first (using executeUpdate) and then execute the first + // SELECT we encounter with executeQuery to render its ResultSet. + java.util.List statements = new java.util.ArrayList<>(); + StringBuilder cur = new StringBuilder(); + for (String line : normalizedSql.split("\n")) { + String t = line.trim(); + if (t.isEmpty()) + continue; + if (t.startsWith("--") || t.startsWith("//") || t.startsWith("#")) + continue; + // Accumulate lines. If a semicolon terminates the statement, split. + cur.append(line).append('\n'); + if (t.endsWith(";")) { + String stmt = cur.toString().trim(); + // strip trailing semicolon + if (stmt.endsWith(";") ) + stmt = stmt.substring(0, stmt.length() - 1).trim(); + if (!stmt.isEmpty()) + statements.add(stmt); + cur.setLength(0); } - csv.append('\n'); - int rowCount = 0; - while (rs.next() && rowCount < maxRows) { - rowCount++; - for (int i = 1; i <= cols; i++) { - if (i > 1) - csv.append(','); - Object v = rs.getObject(i); - csv.append(escapeCsv(v == null ? "" : v.toString())); + } + if (cur.length() > 0) { + String stmt = cur.toString().trim(); + if (!stmt.isEmpty()) + statements.add(stmt); + } + + // If we found no statements via semicolons, try a simple heuristic: + // split on blank-line or detect statement-starting keywords on new lines. + if (statements.isEmpty()) { + statements = new java.util.ArrayList<>(); + cur.setLength(0); + for (String line : normalizedSql.split("\n")) { + String t = line.trim(); + if (t.isEmpty()) { + if (cur.length() > 0) { + statements.add(cur.toString().trim()); + cur.setLength(0); + } + continue; + } + // if line looks like the start of a statement and we have accumulated content, + // treat it as a new statement boundary + if (cur.length() > 0 && t.matches("(?i)^(CREATE|INSERT|UPDATE|DELETE|SELECT|ALTER|DROP|TRUNCATE|MERGE|REPLACE)\\b.*")) { + statements.add(cur.toString().trim()); + cur.setLength(0); } - csv.append('\n'); + cur.append(line).append('\n'); } - if (rs.next()) - csv.append("# TRUNCATED: more rows available\n"); - display(csv.toString(), "text/csv"); - return; + if (cur.length() > 0) + statements.add(cur.toString().trim()); } - // default: HTML - StringBuilder html = new StringBuilder(); - html.append("\n"); - for (int i = 1; i <= cols; i++) - html.append(""); - html.append("\n\n"); - int rowCount = 0; - while (rs.next() && rowCount < maxRows) { - rowCount++; - html.append(""); - for (int i = 1; i <= cols; i++) { - Object v = rs.getObject(i); - html.append(""); + ResultSet rs = null; + ResultSetMetaData md = null; + int cols = 0; + + boolean rendered = false; + for (String stmt : statements) { + String sTrim = stmt.trim(); + if (sTrim.isEmpty()) + continue; + // If this is a SELECT (or starts with WITH), executeQuery and render + if (sTrim.matches("(?i)^(SELECT|WITH)\\b.*")) { + rs = st.executeQuery(sTrim); + md = rs.getMetaData(); + cols = md.getColumnCount(); + + if (showQuery) + display("````sql\n" + sTrim + "\n````", "text/markdown"); + + // build CSV + if ("CSV".equalsIgnoreCase(format)) { + StringBuilder csv = new StringBuilder(); + for (int i = 1; i <= cols; i++) { + if (i > 1) + csv.append(','); + csv.append(escapeCsv(md.getColumnLabel(i))); + } + csv.append('\n'); + int rowCount = 0; + while (rs.next() && rowCount < maxRows) { + rowCount++; + for (int i = 1; i <= cols; i++) { + if (i > 1) + csv.append(','); + Object v = rs.getObject(i); + csv.append(escapeCsv(v == null ? "" : v.toString())); + } + csv.append('\n'); + } + if (rs.next()) + csv.append("# TRUNCATED: more rows available\n"); + display(csv.toString(), "text/csv"); + rendered = true; + rs.close(); + break; + } + + // default: HTML + StringBuilder html = new StringBuilder(); + html.append("
").append(escapeHtml(md.getColumnLabel(i))) - .append("
").append(v == null ? "" : escapeHtml(v.toString())) - .append("
\n"); + for (int i = 1; i <= cols; i++) + html.append(""); + html.append("\n\n"); + int rowCount = 0; + while (rs.next() && rowCount < maxRows) { + rowCount++; + html.append(""); + for (int i = 1; i <= cols; i++) { + Object v = rs.getObject(i); + html.append(""); + } + html.append("\n"); + } + html.append("
") + .append(escapeHtml(md.getColumnLabel(i))).append("
") + .append(v == null ? "" : escapeHtml(v.toString())).append("
"); + if (rs.next()) + html.append("
Results truncated (showing first " + + maxRows + " rows)
"); + display(html.toString(), "text/html"); + rendered = true; + rs.close(); + break; + } else { + // Non-query statement: use executeUpdate where appropriate, otherwise execute + try { + int count = st.executeUpdate(sTrim); + // optionally display the update count for DML statements + if (!sTrim.matches("(?i)^(CREATE|DROP|ALTER|TRUNCATE)\\b.*")) { + display("Updated " + count + " rows", "text/markdown"); + } + } catch (SQLException ex) { + // fallback to execute() for statements that may not be supported by executeUpdate + boolean hasResultSet = st.execute(sTrim); + if (hasResultSet) { + rs = st.getResultSet(); + md = rs.getMetaData(); + cols = md.getColumnCount(); + // render first result set as above (CSV/HTML) + if ("CSV".equalsIgnoreCase(format)) { + StringBuilder csv = new StringBuilder(); + for (int i = 1; i <= cols; i++) { + if (i > 1) + csv.append(','); + csv.append(escapeCsv(md.getColumnLabel(i))); + } + csv.append('\n'); + int rowCount = 0; + while (rs.next() && rowCount < maxRows) { + rowCount++; + for (int i = 1; i <= cols; i++) { + if (i > 1) + csv.append(','); + Object v = rs.getObject(i); + csv.append(escapeCsv(v == null ? "" : v.toString())); + } + csv.append('\n'); + } + if (rs.next()) + csv.append("# TRUNCATED: more rows available\n"); + display(csv.toString(), "text/csv"); + rendered = true; + rs.close(); + break; + } else { + StringBuilder html = new StringBuilder(); + html.append("\n"); + for (int i = 1; i <= cols; i++) + html.append(""); + html.append("\n\n"); + int rowCount = 0; + while (rs.next() && rowCount < maxRows) { + rowCount++; + html.append(""); + for (int i = 1; i <= cols; i++) { + Object v = rs.getObject(i); + html.append(""); + } + html.append("\n"); + } + html.append("
") + .append(escapeHtml(md.getColumnLabel(i))).append("
") + .append(v == null ? "" : escapeHtml(v.toString())) + .append("
"); + if (rs.next()) + html.append("
Results truncated (showing first " + + maxRows + " rows)
"); + display(html.toString(), "text/html"); + rendered = true; + rs.close(); + break; + } + } + } } - html.append("\n"); } - html.append(""); - if (rs.next()) - html.append("
Results truncated (showing first " - + maxRows + " rows)
"); - display(html.toString(), "text/html"); + + if (!rendered) { + // If nothing produced a result set, optionally inform the user. + display("Statements executed", "text/markdown"); + } + return; } } catch (SQLException e) { throw new RuntimeException(e); diff --git a/src/main/java/io/github/spencerpark/ijava/magics/JavaMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/JavaMagics.java index 7f16da0..18b35db 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/JavaMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/JavaMagics.java @@ -24,6 +24,11 @@ public class JavaMagics { @CellMagic("javasrcMethodByAnnotationName") public void javasrcMethodByAnnotationName(List args, String body) throws IOException { Map opts = OptionUtils.parseOptions(args); + if (opts.containsKey("--help") || opts.containsKey("-h")) { + display("**Usage:** `%%javasrcMethodByAnnotationName [index]`\n\n" + + "Extract methods annotated with a given annotation from source file (body should be path to file).", "text/markdown"); + return; + } List pos = OptionUtils.positionalArgs(args); if (pos.size() < 2) { @@ -161,6 +166,10 @@ public void javasrcMethodByName(List args, String body) throws IOExcepti } Map opts = OptionUtils.parseOptions(args); + if (opts.containsKey("--help") || opts.containsKey("-h")) { + display("**Usage:** `%%javasrcMethodByName [options] [methodName|index]`\n\nSee documentation for options like `--src`, `methodRegex`, and `selectIndex`.", "text/markdown"); + return; + } List pos = OptionUtils.positionalArgs(args); if (pos.size() < 1 && !opts.containsKey("methodRegex")) { @@ -242,6 +251,10 @@ public void javasrcMethodByName(List args, String body) throws IOExcepti @CellMagic("javasrcInterfaceByName") public void javasrcInterfaceByName(List args, String body) throws IOException { Map opts = OptionUtils.parseOptions(args); + if (opts.containsKey("--help") || opts.containsKey("-h")) { + display("**Usage:** `%%javasrcInterfaceByName `\n\nExtract interface source by fully-qualified name. Body may contain file path.", "text/markdown"); + return; + } List pos = OptionUtils.positionalArgs(args); if (pos.size() < 1) { @@ -287,6 +300,10 @@ public void javasrcInterfaceByName(List args, String body) throws IOExce @CellMagic("javasrcClassByName") public void javasrcClassByName(List args, String body) throws IOException { Map opts = OptionUtils.parseOptions(args); + if (opts.containsKey("--help") || opts.containsKey("-h")) { + display("**Usage:** `%%javasrcClassByName `\n\nExtract entire class source by FQCN. Body may contain file path.", "text/markdown"); + return; + } List pos = OptionUtils.positionalArgs(args); if (pos.isEmpty()) { @@ -333,6 +350,10 @@ public void javasrcClassByName(List args, String body) throws IOExceptio @CellMagic("javasrcList") public void javasrcList(List args, String body) throws IOException { Map opts = OptionUtils.parseOptions(args); + if (opts.containsKey("--help") || opts.containsKey("-h")) { + display("**Usage:** `%%javasrcList `\n\nList classes and methods in a Java file (summary view).", "text/markdown"); + return; + } List pos = OptionUtils.positionalArgs(args); String filename = body; @@ -365,6 +386,10 @@ public void javasrcList(List args, String body) throws IOException { @CellMagic("javasrcConstructorByName") public void javasrcConstructorByName(List args, String body) throws IOException { Map opts = OptionUtils.parseOptions(args); + if (opts.containsKey("--help") || opts.containsKey("-h")) { + display("**Usage:** `%%javasrcConstructorByName `\n\nShow constructors for a class. Body may contain file path.", "text/markdown"); + return; + } List pos = OptionUtils.positionalArgs(args); if (pos.isEmpty()) { @@ -414,6 +439,10 @@ public void javasrcConstructorByName(List args, String body) throws IOEx @CellMagic("javasrcFieldByName") public void javasrcFieldByName(List args, String body) throws IOException { Map opts = OptionUtils.parseOptions(args); + if (opts.containsKey("--help") || opts.containsKey("-h")) { + display("**Usage:** `%%javasrcFieldByName [filter] [--full=true]`\n\nList or show fields for a class.", "text/markdown"); + return; + } List pos = OptionUtils.positionalArgs(args); if (pos.isEmpty()) { @@ -507,6 +536,10 @@ public void javasrcFieldByName(List args, String body) throws IOExceptio @CellMagic("javasrcJavadoc") public void javasrcJavadoc(List args, String body) throws IOException { Map opts = OptionUtils.parseOptions(args); + if (opts.containsKey("--help") || opts.containsKey("-h")) { + display("**Usage:** `%%javasrcJavadoc [memberName]`\n\nShow javadoc for class or member.", "text/markdown"); + return; + } List pos = OptionUtils.positionalArgs(args); if (pos.isEmpty()) { diff --git a/src/main/java/io/github/spencerpark/ijava/magics/JavaPlantUMLMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/JavaPlantUMLMagics.java index 6f98404..bf4b4d8 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/JavaPlantUMLMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/JavaPlantUMLMagics.java @@ -30,6 +30,14 @@ public class JavaPlantUMLMagics { public void plantUML(List args, String body) throws IOException { // args may include a format (SVG/PNG) and/or a flag to show source for // debugging. + if (args != null && (args.contains("--help") || args.contains("-h"))) { + String help = "## %%plantUML - Render PlantUML from cell\n\n" + + "Usage: %%plantUML [--help] [SVG|PNG] [--show-source]\n\n" + + "Arguments: body contains PlantUML source.\n" + + "Examples:\n%%plantUML SVG\n@startuml\nAlice -> Bob: Hello\n@enduml\n"; + display(help, "text/markdown"); + return; + } boolean showSource = args.stream() .anyMatch(a -> a.equalsIgnoreCase("showSource") || a.equalsIgnoreCase("show-source") || a.equals("--show-source") || a.equals("-s") || a.equalsIgnoreCase("source")); @@ -71,6 +79,10 @@ public void plantUML(List args, String body) throws IOException { @CellMagic("plantUMLFile") public void plantUMLFile(List args, String body) { // sets the results mimetype + if (args != null && (args.contains("--help") || args.contains("-h"))) { + System.out.println("## %%plantUMLFile - Render PlantUML files\n\nUsage: %%plantUMLFile [--help] [SVG|PNG]\n\nProvide file paths (one per line) in the cell body."); + return; + } if (args.size() > 1) throw new IllegalArgumentException("Max one argument : SVG or PNG"); String fileFormat; diff --git a/src/main/java/io/github/spencerpark/ijava/magics/MavenResolver.java b/src/main/java/io/github/spencerpark/ijava/magics/MavenResolver.java index 57d68a0..2cfe641 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/MavenResolver.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/MavenResolver.java @@ -60,6 +60,9 @@ public MavenResolver(Consumer addToClasspath) { this.addToClasspath = addToClasspath; // central this.addRemoteRepo("central", "https://repo.maven.apache.org/maven2/"); + // also try the repo1 host and a common mirror (Sonatype) as fallbacks + this.addRemoteRepo("repo1", "https://repo1.maven.org/maven2/"); + this.addRemoteRepo("sonatype", "https://oss.sonatype.org/content/repositories/releases/"); } private void addRemoteRepo(String id, String url) { @@ -72,11 +75,28 @@ public void addJarsToClasspath(Iterable jars) { @LineMagic(aliases = { "addMavenDependency", "maven" }) public void addMavenDependencies(List args) { + // Handle help flag explicitly so users can run `%maven --help`. + if (args != null && (args.contains("--help") || args.contains("-h"))) { + System.out.println("%maven - Add individual Maven coordinates to the classpath\n"); + System.out.println("Usage: %maven :[:[:]]: [ ...]\n"); + System.out.println("Examples:"); + System.out.println(" %maven org.h2:h2:2.4.240"); + System.out.println(" %maven com.google.guava:guava:32.1.2-jre org.apache.commons:commons-lang3:3.12.0\n"); + System.out.println("Options:"); + System.out.println(" --help, -h Show this help message\n"); + System.out.println("Notes:"); + System.out.println(" Coordinates must follow Maven coordinate format. Multiple coordinates may be provided."); + return; + } + try { this.addJarsToClasspath(ResolveDependency.resolve(args, null, DEFAULT_REPO_LOCAL, remoteRepos)); } catch (DependencyResolutionException | NoLocalRepositoryManagerException e) { - throw new RuntimeException(e); + String coords = String.join(", ", args == null ? List.of() : args); + String repos = remoteRepos.stream().map(r -> r.getUrl()).reduce((a, b) -> a + ", " + b).orElse(""); + throw new RuntimeException("Failed to resolve Maven coordinates [" + coords + "] from repos [" + repos + "]", e); } + } @LineMagic(aliases = { "mavenRepo" }) diff --git a/src/main/java/io/github/spencerpark/ijava/magics/PlantUmlGenerator.java b/src/main/java/io/github/spencerpark/ijava/magics/PlantUmlGenerator.java new file mode 100644 index 0000000..405a478 --- /dev/null +++ b/src/main/java/io/github/spencerpark/ijava/magics/PlantUmlGenerator.java @@ -0,0 +1,176 @@ +package io.github.spencerpark.ijava.magics; + +import java.lang.reflect.*; +import java.util.*; +import java.util.stream.Collectors; + +/** + * Generates PlantUML diagrams from a list of Java classes and interfaces. + */ +public final class PlantUmlGenerator { + + private PlantUmlGenerator() { + } + + /** + * Generate PlantUML text for the given classes. + * + * @param classes List of classes/interfaces to include + * @param includeFields Include fields + * @param includeMethods Include methods + * @param includeConstructors Include constructors + * @param includeInterfaces Include interface relationships + * @param includeNonPublic Include non-public members + * @param excludeInherited Exclude inherited methods/constructors + * @return PlantUML diagram text + */ + public static String generate( + List> classes, + boolean includeFields, + boolean includeMethods, + boolean includeConstructors, + boolean includeInterfaces, + boolean includeNonPublic, + boolean excludeInherited) { + + Set names = classes.stream() + .map(c -> sanitize(c.getSimpleName())) + .collect(Collectors.toCollection(HashSet::new)); + + StringBuilder sb = new StringBuilder(); + sb.append("@startuml\n"); + sb.append("skinparam classAttributeIconSize 0\n"); + + for (Class c : classes) { + String name = sanitize(c.getSimpleName()); + + if (c.isInterface()) + sb.append("interface ").append(name).append(" {\n"); + else + sb.append("class ").append(name).append(" {\n"); + + // ---------- Fields ---------- + if (includeFields) { + for (Field f : c.getDeclaredFields()) { + if (!includeNonPublic && !Modifier.isPublic(f.getModifiers())) + continue; + String staticMark = Modifier.isStatic(f.getModifiers()) ? " {static}" : ""; + sb.append(" ").append(simpleVisibility(f.getModifiers())) + .append(f.getName()) + .append(" : ").append(sanitizeType(f.getType())) + .append(staticMark).append("\n"); + } + } + + // ---------- Constructors ---------- + if (includeConstructors && !c.isInterface()) { + for (Constructor ctr : c.getDeclaredConstructors()) { + if (!includeNonPublic && !Modifier.isPublic(ctr.getModifiers())) + continue; + if (excludeInherited && ctr.getDeclaringClass() != c) + continue; + + String params = Arrays.stream(ctr.getParameterTypes()) + .map(PlantUmlGenerator::sanitizeType) + .collect(Collectors.joining(", ")); + sb.append(" ").append(simpleVisibility(ctr.getModifiers())) + .append(c.getSimpleName()) + .append("(").append(params).append(")") + .append("\n"); + } + } + + // ---------- Methods ---------- + if (includeMethods) { + Set allMethods = new LinkedHashSet<>(); + allMethods.addAll(Arrays.asList(c.getDeclaredMethods())); + allMethods.addAll(Arrays.asList(c.getMethods())); // includes inherited + default + + for (Method m : allMethods) { + if (!includeNonPublic && !Modifier.isPublic(m.getModifiers())) + continue; + if (excludeInherited && m.getDeclaringClass() != c) + continue; + if (m.isSynthetic() || m.isBridge()) + continue; + + String staticMark = Modifier.isStatic(m.getModifiers()) ? " {static}" : ""; + String params = Arrays.stream(m.getParameterTypes()) + .map(PlantUmlGenerator::sanitizeType) + .collect(Collectors.joining(", ")); + + sb.append(" ").append(simpleVisibility(m.getModifiers())) + .append(m.getName()) + .append("(").append(params).append(")") + .append(" : ").append(sanitizeType(m.getReturnType())) + .append(staticMark) + .append("\n"); + } + } + + sb.append("}\n"); + } + + // ---------- Relationships ---------- + for (Class c : classes) { + String cname = sanitize(c.getSimpleName()); + + // Superclass + Class sup = c.getSuperclass(); + if (sup != null && sup != Object.class && names.contains(sanitize(sup.getSimpleName()))) { + sb.append(cname).append(" --|> ").append(sanitize(sup.getSimpleName())).append("\n"); + } + + // Interfaces + if (includeInterfaces) { + for (Class itf : c.getInterfaces()) { + if (!names.contains(sanitize(itf.getSimpleName()))) + continue; + + // Interface -> Interface : héritage d’interface (--|>) + // Classe -> Interface : implémentation (..|>) + if (c.isInterface()) + sb.append(cname).append(" --|> ").append(sanitize(itf.getSimpleName())).append("\n"); + else + sb.append(cname).append(" ..|> ").append(sanitize(itf.getSimpleName())).append("\n"); + } + } + } + + // ---------- Associations via fields ---------- + for (Class c : classes) { + String cname = sanitize(c.getSimpleName()); + for (Field f : c.getDeclaredFields()) { + Class t = f.getType(); + String tname = sanitize(t.getSimpleName()); + if (names.contains(tname)) { + sb.append(cname).append(" --> ").append(tname).append(" : ").append(f.getName()).append("\n"); + } + } + } + + sb.append("@enduml\n"); + return sb.toString(); + } + + // ---------- Helper Methods ---------- + private static String sanitize(String s) { + return s.replaceAll("[^A-Za-z0-9_\\$]", "_"); + } + + private static String sanitizeType(Class c) { + if (c.isArray()) + return sanitizeType(c.getComponentType()) + "[]"; + return sanitize(c.getSimpleName()); + } + + private static String simpleVisibility(int mods) { + if (Modifier.isPublic(mods)) + return "+ "; + if (Modifier.isProtected(mods)) + return "# "; + if (Modifier.isPrivate(mods)) + return "- "; + return "~ "; + } +} diff --git a/src/main/java/io/github/spencerpark/ijava/magics/SingleShellMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/SingleShellMagics.java index 64ca27a..780a7d3 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/SingleShellMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/SingleShellMagics.java @@ -50,6 +50,11 @@ public SingleShellMagics() throws IOException { @CellMagic("commonshell") public String commonshell(List args, String body) throws IOException, InterruptedException { + if (args == null) args = List.of(); + if (args.contains("--help") || args.contains("-h")) { + return "## %%commonshell - Run shell in persistent session\n\nUsage: %%commonshell [--help]\n\nThe cell body is run in a persistent shell process started by the kernel."; + } + synchronized(outputBuffer) { outputBuffer.setLength(0); } @@ -68,7 +73,9 @@ public String commonshell(List args, String body) throws IOException, In @LineMagic("commonshellcmd") public String commonshellcmd(List args) throws IOException, InterruptedException { - if (args.isEmpty()) return "No command provided"; + if (args == null || args.isEmpty()) return "No command provided"; + if (args.size() == 1 && (args.get(0).equals("--help") || args.get(0).equals("-h"))) + return "%commonshellcmd - run a command in the persistent shell session"; return commonshell(args, String.join(" ", args)); } From ae4a1fa08422aeeca010fe70ed50852c54d8e314 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Fri, 30 Jan 2026 14:43:23 +0100 Subject: [PATCH 27/49] feat(magics): tableSchema inline PK/FK/UNIQUE markers --- notebooks/magics_demo.ipynb | 914 +++++++++++------- .../github/spencerpark/ijava/JavaKernel.java | 1 + .../ijava/magics/DBMetadataInspector.java | 166 ++++ .../ijava/magics/JavaDBMSMagics.java | 80 +- .../ijava/magics/TableSchemaMagics.java | 349 +++++++ 5 files changed, 1118 insertions(+), 392 deletions(-) create mode 100644 src/main/java/io/github/spencerpark/ijava/magics/DBMetadataInspector.java create mode 100644 src/main/java/io/github/spencerpark/ijava/magics/TableSchemaMagics.java diff --git a/notebooks/magics_demo.ipynb b/notebooks/magics_demo.ipynb index 09b37d4..99bac3f 100644 --- a/notebooks/magics_demo.ipynb +++ b/notebooks/magics_demo.ipynb @@ -1,37 +1,5 @@ { "cells": [ - { - "cell_type": "markdown", - "id": "5f79afc5", - "metadata": {}, - "source": [ - "%%benchmark --sweep --chart var=n start=1000 end=10000 step=1000 iterations=5 warmup=1\n", - "// Use a predefined test builder that accepts a Map factory (constructor reference)\n", - "java.util.Random rnd = new java.util.Random(12345);\n", - "int[] keys = new int[n];\n", - "for (int i = 0; i < n; i++) keys[i] = rnd.nextInt(n * 10);\n", - "\n", - "import java.util.function.Supplier;\n", - "import java.util.Map;\n", - "// build a Supplier that performs many lookups on a map created by mapFactory\n", - "Supplier makeMapLookupTest(Supplier> mapFactory) {\n", - " Map map = mapFactory.get();\n", - " for (int k : keys) map.put(k, k);\n", - " java.util.Random localRnd = new java.util.Random(54321);\n", - " return () -> {\n", - " int acc = 0;\n", - " for (int i = 0; i < 10000; i++) acc += (map.get(keys[localRnd.nextInt(keys.length)]) != null) ? 1 : 0;\n", - " return acc;\n", - " };\n", - "}\n", - "\n", - "// HashMap: pass a constructor reference via a lambda (to set initial capacity)\n", - "runSupplierTest(makeMapLookupTest(() -> new java.util.HashMap<>(Math.max(16, n * 2))), 1);\n", - "---\n", - "// TreeMap: pass constructor reference directly\n", - "runSupplierTest(makeMapLookupTest(java.util.TreeMap::new), 1);" - ] - }, { "cell_type": "markdown", "id": "fd625c49", @@ -42,13 +10,9 @@ }, { "cell_type": "code", - "execution_count": 5, + "execution_count": 1, "id": "d5ae9350", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -56,7 +20,7 @@ "\u001b[36m\"Helloworld!\";\u001b[0m: Hello world !" ] }, - "execution_count": 5, + "execution_count": 1, "metadata": {}, "output_type": "execute_result" } @@ -67,13 +31,9 @@ }, { "cell_type": "code", - "execution_count": 6, + "execution_count": 2, "id": "1c4668b6", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -81,7 +41,7 @@ "\u001b[36m3+4*2\u001b[0m: 11" ] }, - "execution_count": 6, + "execution_count": 2, "metadata": {}, "output_type": "execute_result" } @@ -100,13 +60,9 @@ }, { "cell_type": "code", - "execution_count": 7, + "execution_count": 3, "id": "e5e10708", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -126,13 +82,9 @@ }, { "cell_type": "code", - "execution_count": 8, + "execution_count": 4, "id": "4f6628be", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -163,13 +115,9 @@ }, { "cell_type": "code", - "execution_count": 9, + "execution_count": 5, "id": "3606b844", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "%maven org.projectlombok:lombok:1.18.42" @@ -177,13 +125,9 @@ }, { "cell_type": "code", - "execution_count": 10, + "execution_count": 6, "id": "c14e858c", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -228,13 +172,9 @@ }, { "cell_type": "code", - "execution_count": 11, + "execution_count": 7, "id": "f15afeff", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "%%compile --class=com.example.demo.Hello --output=out\n", @@ -254,13 +194,9 @@ }, { "cell_type": "code", - "execution_count": 12, + "execution_count": 8, "id": "237d7c9b", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -268,7 +204,7 @@ "\u001b[36mcom.example.demo.Hello.greet();\u001b[0m: Hello from compiled class" ] }, - "execution_count": 12, + "execution_count": 8, "metadata": {}, "output_type": "execute_result" } @@ -279,13 +215,9 @@ }, { "cell_type": "code", - "execution_count": 13, + "execution_count": 9, "id": "0481b2b2", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "%%compile --class=com.example.demo.LombokPerson --output=out --processor-path=/var/home/bruno/.m2/repository/org/projectlombok/lombok/1.18.42/lombok-1.18.42.jar --classpath=/var/home/bruno/.m2/repository/org/projectlombok/lombok/1.18.42/lombok-1.18.42.jar\n", @@ -302,13 +234,9 @@ }, { "cell_type": "code", - "execution_count": 14, + "execution_count": 10, "id": "f7128d07", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -336,13 +264,9 @@ }, { "cell_type": "code", - "execution_count": 15, + "execution_count": 11, "id": "4968d01a", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -382,13 +306,9 @@ }, { "cell_type": "code", - "execution_count": 16, + "execution_count": 12, "id": "05391c3a", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -411,13 +331,9 @@ }, { "cell_type": "code", - "execution_count": 17, + "execution_count": 13, "id": "2f994624", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -444,13 +360,9 @@ }, { "cell_type": "code", - "execution_count": 18, + "execution_count": 14, "id": "63f2121b", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -478,13 +390,9 @@ }, { "cell_type": "code", - "execution_count": 19, + "execution_count": 15, "id": "e4cd33c7", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "%maven com.h2database:h2:2.4.240" @@ -492,13 +400,9 @@ }, { "cell_type": "code", - "execution_count": 20, + "execution_count": 16, "id": "18c47637", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "System.setProperty(\"jdbc.url\", \"jdbc:h2:mem:test;DB_CLOSE_DELAY=-1\");\n", @@ -508,13 +412,9 @@ }, { "cell_type": "code", - "execution_count": 21, + "execution_count": 17, "id": "2b08450b", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "%%sqlAsTable --help" @@ -522,14 +422,46 @@ }, { "cell_type": "code", - "execution_count": 22, + "execution_count": 18, "id": "020dddda", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ + { + "data": { + "text/markdown": [ + "Updated 0 rows" + ], + "text/plain": [ + "Updated 0 rows" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/markdown": [ + "Updated 2 rows" + ], + "text/plain": [ + "Updated 2 rows" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/markdown": [ + "Updated 0 rows" + ], + "text/plain": [ + "Updated 0 rows" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, { "data": { "text/markdown": [ @@ -542,6 +474,18 @@ "metadata": {}, "output_type": "display_data" }, + { + "data": { + "text/markdown": [ + "Updated 0 rows" + ], + "text/plain": [ + "Updated 0 rows" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, { "data": { "text/markdown": [ @@ -554,6 +498,18 @@ "metadata": {}, "output_type": "display_data" }, + { + "data": { + "text/markdown": [ + "Updated 0 rows" + ], + "text/plain": [ + "Updated 0 rows" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, { "data": { "text/markdown": [ @@ -570,20 +526,18 @@ "data": { "text/html": [ "\n", - "\n", + "\n", "\n", - "\n", - "\n", - "\n", + "\n", + "\n", "
IDNAMEPRICE
IDNAME
1Widget9.99
2Gadget19.95
3Thingamajig4.50
1Alice
2Bob
" ], "text/plain": [ "\n", - "\n", + "\n", "\n", - "\n", - "\n", - "\n", + "\n", + "\n", "
IDNAMEPRICE
IDNAME
1Widget9.99
2Gadget19.95
3Thingamajig4.50
1Alice
2Bob
" ] }, @@ -593,50 +547,95 @@ ], "source": [ "%%sqlAsTable\n", - "-- Example using a jdbc connection defined by system properties jdbc.url, jdbc.user, jdbc.password\n", - "-- Creates multiple related tables and demonstrates inserts and joins\n", + "-- Example using a JDBC connection defined by system properties: jdbc.url, jdbc.user, jdbc.password\n", + "-- Creates multiple related tables and demonstrates inserts, relationships, and joins\n", + "\n", + "-- -----------------------------\n", + "-- Customers table\n", + "-- -----------------------------\n", + "CREATE TABLE IF NOT EXISTS customers(\n", + " id INT PRIMARY KEY,\n", + " name VARCHAR(100) NOT NULL\n", + ");\n", + "\n", + "MERGE INTO customers VALUES\n", + " (1, 'Alice'),\n", + " (2, 'Bob');\n", + "\n", + "-- -----------------------------\n", + "-- Products catalog\n", + "-- -----------------------------\n", + "CREATE TABLE IF NOT EXISTS products(\n", + " id INT PRIMARY KEY,\n", + " name VARCHAR(100) NOT NULL,\n", + " price DECIMAL(10,2) NOT NULL\n", + ");\n", "\n", - "-- products catalog\n", - "CREATE TABLE IF NOT EXISTS products(id INT PRIMARY KEY, name VARCHAR(100), price DECIMAL(10,2));\n", "MERGE INTO products VALUES\n", " (1, 'Widget', 9.99),\n", " (2, 'Gadget', 19.95),\n", " (3, 'Thingamajig', 4.50);\n", "\n", - "-- orders and order items\n", - "CREATE TABLE IF NOT EXISTS orders(id INT PRIMARY KEY, customer_id INT, order_date DATE);\n", - "-- use a composite primary key so MERGE INTO can match rows\n", - "CREATE TABLE IF NOT EXISTS order_items(order_id INT, product_id INT, qty INT, PRIMARY KEY(order_id, product_id));\n", + "-- -----------------------------\n", + "-- Orders table\n", + "-- -----------------------------\n", + "CREATE TABLE IF NOT EXISTS orders(\n", + " id INT PRIMARY KEY,\n", + " customer_id INT NOT NULL,\n", + " order_date DATE NOT NULL,\n", + " FOREIGN KEY(customer_id) REFERENCES customers(id)\n", + ");\n", + "\n", + "MERGE INTO orders VALUES\n", + " (1, 1, DATE '2025-12-01'),\n", + " (2, 2, DATE '2025-12-02');\n", + "\n", + "-- -----------------------------\n", + "-- Order items table (line items)\n", + "-- -----------------------------\n", + "CREATE TABLE IF NOT EXISTS order_items(\n", + " order_id INT NOT NULL,\n", + " product_id INT NOT NULL,\n", + " qty INT NOT NULL,\n", + " PRIMARY KEY(order_id, product_id),\n", + " FOREIGN KEY(order_id) REFERENCES orders(id),\n", + " FOREIGN KEY(product_id) REFERENCES products(id)\n", + ");\n", "\n", - "MERGE INTO orders VALUES (1, 1, DATE '2025-12-01'), (2, 2, DATE '2025-12-02');\n", "MERGE INTO order_items(order_id, product_id, qty) KEY(order_id, product_id) VALUES\n", " (1, 1, 2),\n", " (1, 3, 1),\n", " (2, 2, 4);\n", "\n", - "-- verify tables\n", + "-- -----------------------------\n", + "-- Verify table contents\n", + "-- -----------------------------\n", + "SELECT * FROM customers;\n", "SELECT * FROM products;\n", "SELECT * FROM orders;\n", "SELECT * FROM order_items;\n", "\n", - "-- example join: order totals per order\n", - "SELECT o.id AS order_id, o.order_date, d.name AS customer, SUM(p.price * oi.qty) AS total\n", + "-- -----------------------------\n", + "-- Example join: calculate total per order\n", + "-- -----------------------------\n", + "SELECT\n", + " o.id AS order_id,\n", + " o.order_date,\n", + " c.name AS customer,\n", + " SUM(p.price * oi.qty) AS total\n", "FROM orders o\n", + "JOIN customers c ON c.id = o.customer_id\n", "JOIN order_items oi ON oi.order_id = o.id\n", "JOIN products p ON p.id = oi.product_id\n", - "GROUP BY o.id, o.order_date, d.name\n", - ";" + "GROUP BY o.id, o.order_date, c.name\n", + "ORDER BY o.id;\n" ] }, { "cell_type": "code", - "execution_count": 23, + "execution_count": 19, "id": "b2d60553", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -656,21 +655,17 @@ }, { "cell_type": "code", - "execution_count": 24, + "execution_count": 20, "id": "83570636", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { "image/svg+xml": [ - "ORDERSPKID: INTEGER(32)*CUSTOMER_ID : INTEGER(32)*ORDER_DATE : DATE(10)PRODUCTSPKID: INTEGER(32)*NAME : CHARACTER VARYING(100)*PRICE : DECIMAL(10)" + "ORDERSPKID: INTEGER(32)FKCUSTOMER_ID : INTEGER(32)*ORDER_DATE : DATE(10)PRODUCTSPKID: INTEGER(32)*NAME : CHARACTER VARYING(100)*PRICE : DECIMAL(10)CUSTOMERSPKID: INTEGER(32)*NAME : CHARACTER VARYING(100)ORDER_ITEMS FKORDER_ID : INTEGER(32)FKPRODUCT_ID : INTEGER(32)*QTY : INTEGER(32)CUSTOMER_ID -> ID1..*1ORDER_ID -> ID1..*1PRODUCT_ID -> ID1..*1" ], "text/plain": [ - "ORDERSPKID: INTEGER(32)*CUSTOMER_ID : INTEGER(32)*ORDER_DATE : DATE(10)PRODUCTSPKID: INTEGER(32)*NAME : CHARACTER VARYING(100)*PRICE : DECIMAL(10)" + "ORDERSPKID: INTEGER(32)FKCUSTOMER_ID : INTEGER(32)*ORDER_DATE : DATE(10)PRODUCTSPKID: INTEGER(32)*NAME : CHARACTER VARYING(100)*PRICE : DECIMAL(10)CUSTOMERSPKID: INTEGER(32)*NAME : CHARACTER VARYING(100)ORDER_ITEMS FKORDER_ID : INTEGER(32)FKPRODUCT_ID : INTEGER(32)*QTY : INTEGER(32)CUSTOMER_ID -> ID1..*1ORDER_ID -> ID1..*1PRODUCT_ID -> ID1..*1" ] }, "metadata": {}, @@ -681,7 +676,299 @@ "%%rdbmsSchema\n", "-- Render the schema for a given JDBC connection as HTML/SVG (depends on implementation).\n", "ORDERS\n", - "PRODUCTS" + "PRODUCTS\n", + "CUSTOMERS\n", + "ORDER_ITEMS" + ] + }, + { + "cell_type": "code", + "execution_count": 21, + "id": "e272026f", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "%tableSchema - Show detailed table schema metadata\n", + "\n", + "Usage: %tableSchema [schema.]table [--ddl] [--sample=N] [--compact] [--help]\n", + "\n", + "Options:\n", + " --ddl Show a minimal CREATE TABLE DDL snippet\n", + " --sample=N Show up to N sample rows\n", + " --compact Show compact table summary in relational notation\n", + " --help, -h Show this help message\n" + ] + } + ], + "source": [ + "%tableSchema --help" + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "id": "31d809c0", + "metadata": {}, + "outputs": [ + { + "data": { + "text/markdown": [ + "# Table ``PRODUCTS``\n", + "\n", + "| Column | Type | Nullable | Default | Remarks |\n", + "|---|---|:---:|---|---|\n", + "| ID (PK) (UNIQUE) | INTEGER(32) | NOT NULL | | |\n", + "| NAME | CHARACTER VARYING(100) | NOT NULL | | |\n", + "| PRICE | DECIMAL(10) | NOT NULL | | |\n", + "\n", + "**Primary key**: ID\n", + "\n", + "**Indexes**:\n", + "- PRIMARY_KEY_F (ID) UNIQUE\n", + "\n", + "```\n", + "CREATE TABLE PRODUCTS (\n", + " ID INTEGER(32) NOT NULL,\n", + " NAME CHARACTER VARYING(100) NOT NULL,\n", + " PRICE DECIMAL(10) NOT NULL,\n", + " PRIMARY KEY (ID)\n", + ");\n", + "```\n" + ], + "text/plain": [ + "# Table ``PRODUCTS``\n", + "\n", + "| Column | Type | Nullable | Default | Remarks |\n", + "|---|---|:---:|---|---|\n", + "| ID (PK) (UNIQUE) | INTEGER(32) | NOT NULL | | |\n", + "| NAME | CHARACTER VARYING(100) | NOT NULL | | |\n", + "| PRICE | DECIMAL(10) | NOT NULL | | |\n", + "\n", + "**Primary key**: ID\n", + "\n", + "**Indexes**:\n", + "- PRIMARY_KEY_F (ID) UNIQUE\n", + "\n", + "```\n", + "CREATE TABLE PRODUCTS (\n", + " ID INTEGER(32) NOT NULL,\n", + " NAME CHARACTER VARYING(100) NOT NULL,\n", + " PRICE DECIMAL(10) NOT NULL,\n", + " PRIMARY KEY (ID)\n", + ");\n", + "```\n" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/markdown": [ + "| ID | NAME | PRICE |\n", + "| --- | --- | --- |\n", + "| 1 | Widget | 9.99 |\n", + "| 2 | Gadget | 19.95 |\n", + "| 3 | Thingamajig | 4.50 |\n" + ], + "text/plain": [ + "| ID | NAME | PRICE |\n", + "| --- | --- | --- |\n", + "| 1 | Widget | 9.99 |\n", + "| 2 | Gadget | 19.95 |\n", + "| 3 | Thingamajig | 4.50 |\n" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%tableSchema PRODUCTS --ddl --sample=3" + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "id": "7c5ead4d", + "metadata": {}, + "outputs": [ + { + "data": { + "text/markdown": [ + "# Table ``ORDERS``\n", + "\n", + "| Column | Type | Nullable | Default | Remarks |\n", + "|---|---|:---:|---|---|\n", + "| ID (PK) (UNIQUE) | INTEGER(32) | NOT NULL | | |\n", + "| CUSTOMER_ID → CUSTOMERS(ID) | INTEGER(32) | NOT NULL | | |\n", + "| ORDER_DATE | DATE(10) | NOT NULL | | |\n", + "\n", + "**Primary key**: ID\n", + "\n", + "**Indexes**:\n", + "- CONSTRAINT_INDEX_8 (CUSTOMER_ID) \n", + "- PRIMARY_KEY_8 (ID) UNIQUE\n", + "\n", + "**Foreign keys**:\n", + "- CUSTOMER_ID → CUSTOMERS(ID)\n", + "\n" + ], + "text/plain": [ + "# Table ``ORDERS``\n", + "\n", + "| Column | Type | Nullable | Default | Remarks |\n", + "|---|---|:---:|---|---|\n", + "| ID (PK) (UNIQUE) | INTEGER(32) | NOT NULL | | |\n", + "| CUSTOMER_ID → CUSTOMERS(ID) | INTEGER(32) | NOT NULL | | |\n", + "| ORDER_DATE | DATE(10) | NOT NULL | | |\n", + "\n", + "**Primary key**: ID\n", + "\n", + "**Indexes**:\n", + "- CONSTRAINT_INDEX_8 (CUSTOMER_ID) \n", + "- PRIMARY_KEY_8 (ID) UNIQUE\n", + "\n", + "**Foreign keys**:\n", + "- CUSTOMER_ID → CUSTOMERS(ID)\n", + "\n" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/markdown": [ + "| ID | CUSTOMER_ID | ORDER_DATE |\n", + "| --- | --- | --- |\n", + "| 1 | 1 | 2025-12-01 |\n", + "| 2 | 2 | 2025-12-02 |\n" + ], + "text/plain": [ + "| ID | CUSTOMER_ID | ORDER_DATE |\n", + "| --- | --- | --- |\n", + "| 1 | 1 | 2025-12-01 |\n", + "| 2 | 2 | 2025-12-02 |\n" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%tableSchema ORDERS --sample=3" + ] + }, + { + "cell_type": "code", + "execution_count": 24, + "id": "db0eea00", + "metadata": {}, + "outputs": [ + { + "data": { + "text/markdown": [ + "# Table ``ORDER_ITEMS``\n", + "\n", + "| Column | Type | Nullable | Default | Remarks |\n", + "|---|---|:---:|---|---|\n", + "| ORDER_ID (PK) → ORDERS(ID) | INTEGER(32) | NOT NULL | | |\n", + "| PRODUCT_ID (PK) → PRODUCTS(ID) | INTEGER(32) | NOT NULL | | |\n", + "| QTY | INTEGER(32) | NOT NULL | | |\n", + "\n", + "**Primary key**: ORDER_ID, PRODUCT_ID\n", + "\n", + "**Indexes**:\n", + "- CONSTRAINT_INDEX_2 (ORDER_ID) \n", + "- PRIMARY_KEY_2 (ORDER_ID, PRODUCT_ID) UNIQUE\n", + "- CONSTRAINT_INDEX_2B (PRODUCT_ID) \n", + "\n", + "**Foreign keys**:\n", + "- ORDER_ID → ORDERS(ID)\n", + "- PRODUCT_ID → PRODUCTS(ID)\n", + "\n" + ], + "text/plain": [ + "# Table ``ORDER_ITEMS``\n", + "\n", + "| Column | Type | Nullable | Default | Remarks |\n", + "|---|---|:---:|---|---|\n", + "| ORDER_ID (PK) → ORDERS(ID) | INTEGER(32) | NOT NULL | | |\n", + "| PRODUCT_ID (PK) → PRODUCTS(ID) | INTEGER(32) | NOT NULL | | |\n", + "| QTY | INTEGER(32) | NOT NULL | | |\n", + "\n", + "**Primary key**: ORDER_ID, PRODUCT_ID\n", + "\n", + "**Indexes**:\n", + "- CONSTRAINT_INDEX_2 (ORDER_ID) \n", + "- PRIMARY_KEY_2 (ORDER_ID, PRODUCT_ID) UNIQUE\n", + "- CONSTRAINT_INDEX_2B (PRODUCT_ID) \n", + "\n", + "**Foreign keys**:\n", + "- ORDER_ID → ORDERS(ID)\n", + "- PRODUCT_ID → PRODUCTS(ID)\n", + "\n" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/markdown": [ + "| ORDER_ID | PRODUCT_ID | QTY |\n", + "| --- | --- | --- |\n", + "| 1 | 1 | 2 |\n", + "| 1 | 3 | 1 |\n", + "| 2 | 2 | 4 |\n" + ], + "text/plain": [ + "| ORDER_ID | PRODUCT_ID | QTY |\n", + "| --- | --- | --- |\n", + "| 1 | 1 | 2 |\n", + "| 1 | 3 | 1 |\n", + "| 2 | 2 | 4 |\n" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%tableSchema ORDER_ITEMS --sample=3" + ] + }, + { + "cell_type": "code", + "execution_count": 25, + "id": "fcac85a3", + "metadata": {}, + "outputs": [ + { + "data": { + "text/markdown": [ + "# Table ``ORDER_ITEMS``\n", + "\n", + "ORDER_ITEMS(ORDER_ID (PK) → ORDERS(ID), PRODUCT_ID (PK) → PRODUCTS(ID), QTY)\n", + "\n" + ], + "text/plain": [ + "# Table ``ORDER_ITEMS``\n", + "\n", + "ORDER_ITEMS(ORDER_ID (PK) → ORDERS(ID), PRODUCT_ID (PK) → PRODUCTS(ID), QTY)\n", + "\n" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%%tableSchema ORDER_ITEMS --compact" ] }, { @@ -695,13 +982,9 @@ }, { "cell_type": "code", - "execution_count": 25, + "execution_count": 26, "id": "fe2f0039", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -726,13 +1009,9 @@ }, { "cell_type": "code", - "execution_count": 26, + "execution_count": 27, "id": "c04b48ea", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -788,13 +1067,9 @@ }, { "cell_type": "code", - "execution_count": 27, + "execution_count": 28, "id": "33a64ebb", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -837,13 +1112,9 @@ }, { "cell_type": "code", - "execution_count": 28, + "execution_count": 29, "id": "0898c655", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -885,13 +1156,9 @@ }, { "cell_type": "code", - "execution_count": 29, + "execution_count": 30, "id": "d471c6f9", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -916,13 +1183,9 @@ }, { "cell_type": "code", - "execution_count": 30, + "execution_count": 31, "id": "6b425967", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -954,13 +1217,9 @@ }, { "cell_type": "code", - "execution_count": 31, + "execution_count": 32, "id": "f56fa36e", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -985,13 +1244,9 @@ }, { "cell_type": "code", - "execution_count": 32, + "execution_count": 33, "id": "82e2cfbb", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1045,13 +1300,9 @@ }, { "cell_type": "code", - "execution_count": 33, + "execution_count": 34, "id": "11d6e07e", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1076,13 +1327,9 @@ }, { "cell_type": "code", - "execution_count": 34, + "execution_count": 35, "id": "f51da0ac", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1116,13 +1363,9 @@ }, { "cell_type": "code", - "execution_count": 35, + "execution_count": 36, "id": "0de30e18", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1147,13 +1390,9 @@ }, { "cell_type": "code", - "execution_count": 36, + "execution_count": 37, "id": "ee9cb95d", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1179,13 +1418,9 @@ }, { "cell_type": "code", - "execution_count": 37, + "execution_count": 38, "id": "e70d0cee", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1222,13 +1457,9 @@ }, { "cell_type": "code", - "execution_count": 38, + "execution_count": 39, "id": "a9482ebf", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -1248,20 +1479,16 @@ }, { "cell_type": "code", - "execution_count": 39, + "execution_count": 40, "id": "aea54b0e", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ - "samples: [25110850, 23485074, 23968668, 17996648, 17317386]\n", - "min=17317386 median=23485074 avg=21575725,20 max=25110850 (nanoseconds)\n" + "samples: [22135483, 22509874, 23679324, 23768707, 18312544]\n", + "min=18312544 median=22509874 avg=22081186,40 max=23768707 (nanoseconds)\n" ] } ], @@ -1285,13 +1512,9 @@ }, { "cell_type": "code", - "execution_count": 40, + "execution_count": 41, "id": "117a9618", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -1316,13 +1539,9 @@ }, { "cell_type": "code", - "execution_count": 41, + "execution_count": 42, "id": "f25a7a92", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "// Helper: run a Supplier-driven test and return accumulated result\n", @@ -1364,21 +1583,17 @@ }, { "cell_type": "code", - "execution_count": 42, + "execution_count": 43, "id": "5a7f5050", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { "image/svg+xml": [ - "10002000300040005000600070008000900010000nBenchmark sweep: n0,003,316,629,9313,2416,559,829,448,239,0416,558,239,107,155,897,189,8010,738,688,4010,0910,8113,177,947,657,02// HashMap implementation// TreeMap implementationaveraged over 10 iterations (warmup=1)" + "10002000300040005000600070008000900010000nBenchmark sweep: n0,003,466,9110,3713,8217,2817,2810,5210,117,717,539,047,046,507,078,2910,369,669,398,739,967,397,788,148,186,18// HashMap implementation// TreeMap implementationaveraged over 10 iterations (warmup=1)" ], "text/plain": [ - "10002000300040005000600070008000900010000nBenchmark sweep: n0,003,316,629,9313,2416,559,829,448,239,0416,558,239,107,155,897,189,8010,738,688,4010,0910,8113,177,947,657,02// HashMap implementation// TreeMap implementationaveraged over 10 iterations (warmup=1)" + "10002000300040005000600070008000900010000nBenchmark sweep: n0,003,466,9110,3713,8217,2817,2810,5210,117,717,539,047,046,507,078,2910,369,669,398,739,967,397,788,148,186,18// HashMap implementation// TreeMap implementationaveraged over 10 iterations (warmup=1)" ] }, "metadata": {}, @@ -1408,29 +1623,62 @@ }, { "cell_type": "code", - "execution_count": 8, + "execution_count": 44, "id": "99467b83", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ - "%classDiagram usage:\n", - " %classDiagram \n", - " %classDiagram --package=pkg [options]\n", + "%classDiagram - Generate UML class diagrams using PlantUML\n", "\n", - "Options:\n", - " --svg | --png | --uml\n", - " --include=regex --exclude=regex\n", - " --interfaces-only --classes-only\n", - " --ancestors --depth=N\n", - " --max=N --non-public\n", - " --out=file\n", + "USAGE:\n", + " %classDiagram [options]\n", + " %classDiagram --package= [options]\n", + "\n", + "TARGET SELECTION:\n", + " Generate diagram for a single class.\n", + " --package= Scan a package and include multiple classes.\n", + "\n", + "OUTPUT FORMAT (choose one):\n", + " --svg Render diagram as SVG image (default).\n", + " --png Render diagram as PNG image.\n", + " --uml Output raw PlantUML text only (no rendering).\n", + "\n", + "SCOPE / SIZE CONTROL:\n", + " --max= Maximum classes when scanning a package (default 50).\n", + "\n", + "VISIBILITY / DETAIL:\n", + " --non-public Include non-public fields, methods, constructors.\n", + "\n", + "HIERARCHY / ANCESTORS:\n", + " --ancestors Include superclasses and interfaces.\n", + " --depth= Ancestor depth when --ancestors is used (default 3).\n", + "\n", + "TYPE FILTERS:\n", + " --interfaces-only Include only interfaces.\n", + " --classes-only Include only classes (exclude interfaces).\n", + "\n", + "METHOD FILTER:\n", + " --exclude-inherited Exclude inherited methods and constructors.\n", + "\n", + "NAME FILTERS (regex, package scan only):\n", + " --include= Only include class names that match.\n", + " --exclude= Exclude class names that match.\n", + "\n", + "FILE OUTPUT:\n", + " --out= Save output to file (.svg, .png, .uml).\n", + "\n", + "HELP:\n", + " --help, -h Show this help message.\n", + "\n", + "EXAMPLES:\n", + " %classDiagram java.util.ArrayList\n", + " %classDiagram --package=java.util --max=80 --svg\n", + " %classDiagram com.myapp.Service --ancestors --depth=2\n", + " %classDiagram --package=com.myapp --include=.*Service --png\n", + " %classDiagram java.util.List --uml --out=list.uml\n", "\n" ] } @@ -1441,13 +1689,9 @@ }, { "cell_type": "code", - "execution_count": 7, + "execution_count": 45, "id": "f01b8759", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -1464,13 +1708,9 @@ }, { "cell_type": "code", - "execution_count": 1, + "execution_count": 46, "id": "59d54da7", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "%%compile --class=com.example.demo.C --output=out\n", @@ -1482,13 +1722,9 @@ }, { "cell_type": "code", - "execution_count": 2, + "execution_count": 47, "id": "d49e214a", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "%%compile --class=com.example.demo.A --output=out\n", @@ -1499,13 +1735,9 @@ }, { "cell_type": "code", - "execution_count": 3, + "execution_count": 48, "id": "21bc5030", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "%%compile --class=com.example.demo.B --output=out\n", @@ -1516,13 +1748,9 @@ }, { "cell_type": "code", - "execution_count": 2, + "execution_count": 49, "id": "e6e614c6", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -1538,13 +1766,9 @@ }, { "cell_type": "code", - "execution_count": 1, + "execution_count": 50, "id": "317ff290", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1574,7 +1798,7 @@ "codemirror_mode": "java", "file_extension": ".jshell", "mimetype": "text/x-java-source", - "name": "Java", + "name": "java", "pygments_lexer": "java", "version": "25.0.1+8-LTS" } diff --git a/src/main/java/io/github/spencerpark/ijava/JavaKernel.java b/src/main/java/io/github/spencerpark/ijava/JavaKernel.java index b27288e..8bfecec 100644 --- a/src/main/java/io/github/spencerpark/ijava/JavaKernel.java +++ b/src/main/java/io/github/spencerpark/ijava/JavaKernel.java @@ -128,6 +128,7 @@ public JavaKernel() { magics.registerMagics(new JavaMagics()); magics.registerMagics(new JavaPlantUMLMagics()); magics.registerMagics(new ClassDiagramMagics()); + magics.registerMagics(new TableSchemaMagics()); // Consolidated shell magics: `MyShellMagics` removed, use `ShellMagics` only. magics.registerMagics(new ShellMagics()); try { diff --git a/src/main/java/io/github/spencerpark/ijava/magics/DBMetadataInspector.java b/src/main/java/io/github/spencerpark/ijava/magics/DBMetadataInspector.java new file mode 100644 index 0000000..e8e327a --- /dev/null +++ b/src/main/java/io/github/spencerpark/ijava/magics/DBMetadataInspector.java @@ -0,0 +1,166 @@ +package io.github.spencerpark.ijava.magics; + +import java.sql.*; +import java.util.*; + +/** + * Best-effort inspector that reads JDBC metadata and returns a normalized + * TableMetadata object usable by magics. + */ +public class DBMetadataInspector { + public static class ColumnMeta { + public final String name; + public final String type; + public final int size; + public final boolean nullable; + public final String defaultValue; + public final String remarks; + public ColumnMeta(String name, String type, int size, boolean nullable, String defaultValue, String remarks) { + this.name = name; this.type = type; this.size = size; this.nullable = nullable; this.defaultValue = defaultValue; this.remarks = remarks; + } + } + + public static class IndexMeta { + public final String name; + public final boolean unique; + public final List columns = new ArrayList<>(); + public IndexMeta(String name, boolean unique) { this.name = name; this.unique = unique; } + } + + public static class FKMeta { + public final String fkColumn; + public final String pkTable; + public final String pkColumn; + public FKMeta(String fkColumn, String pkTable, String pkColumn) { this.fkColumn = fkColumn; this.pkTable = pkTable; this.pkColumn = pkColumn; } + } + + public static class TableMetadata { + public final String schema; + public final String table; + public final List columns = new ArrayList<>(); + public final List primaryKeys = new ArrayList<>(); + public final Map indexes = new LinkedHashMap<>(); + public final List foreignKeys = new ArrayList<>(); + public final List constraints = new ArrayList<>(); + public final List checks = new ArrayList<>(); + public final List domains = new ArrayList<>(); + public String tableRemarks = null; + + public TableMetadata(String schema, String table) { this.schema = schema; this.table = table; } + } + + public static TableMetadata inspect(Connection conn, String schema, String table) throws SQLException { + TableMetadata meta = new TableMetadata(schema, table); + DatabaseMetaData md = conn.getMetaData(); + + // columns + try (ResultSet cols = md.getColumns(null, schema, table, null)) { + while (cols.next()) { + String name = cols.getString("COLUMN_NAME"); + String type = cols.getString("TYPE_NAME"); + int size = 0; + try { size = cols.getInt("COLUMN_SIZE"); } catch (Exception ignored) {} + boolean nullable = "YES".equalsIgnoreCase(cols.getString("IS_NULLABLE")); + String def = cols.getString("COLUMN_DEF"); + String remarks = cols.getString("REMARKS"); + meta.columns.add(new ColumnMeta(name, type, size, nullable, def, remarks)); + } + } + + // primary keys + try (ResultSet pk = md.getPrimaryKeys(null, schema, table)) { + while (pk.next()) meta.primaryKeys.add(pk.getString("COLUMN_NAME")); + } + + // indexes + try (ResultSet ix = md.getIndexInfo(null, schema, table, false, false)) { + while (ix.next()) { + String iname = ix.getString("INDEX_NAME"); + String col = ix.getString("COLUMN_NAME"); + boolean nonUnique = ix.getBoolean("NON_UNIQUE"); + boolean unique = !nonUnique; + if (iname == null) continue; + meta.indexes.computeIfAbsent(iname, k -> new IndexMeta(iname, unique)).columns.add(col); + } + } + + // foreign keys + try (ResultSet fk = md.getImportedKeys(null, schema, table)) { + while (fk.next()) { + String pkTable = fk.getString("PKTABLE_NAME"); + String pkCol = fk.getString("PKCOLUMN_NAME"); + String fkCol = fk.getString("FKCOLUMN_NAME"); + meta.foreignKeys.add(new FKMeta(fkCol, pkTable, pkCol)); + } + } + + // table remarks (best-effort via getTables) + try (ResultSet t = md.getTables(null, schema, table, null)) { + if (t.next()) { + meta.tableRemarks = t.getString("REMARKS"); + } + } catch (Throwable ignored) { } + + // constraints (information_schema best-effort) + try { + String qc; + PreparedStatement ps; + if (schema != null) { + qc = "SELECT constraint_name, constraint_type FROM information_schema.table_constraints WHERE table_schema = ? AND table_name = ?"; + ps = conn.prepareStatement(qc); + ps.setString(1, schema); + ps.setString(2, table); + } else { + qc = "SELECT constraint_name, constraint_type FROM information_schema.table_constraints WHERE table_name = ?"; + ps = conn.prepareStatement(qc); + ps.setString(1, table); + } + try (ResultSet cr = ps.executeQuery()) { + while (cr.next()) meta.constraints.add(cr.getString("constraint_name") + ": " + cr.getString("constraint_type")); + } + } catch (Throwable ignored) { } + + // check constraints + try { + String qc; + PreparedStatement ps; + if (schema != null) { + qc = "SELECT cc.constraint_name, cc.check_clause FROM information_schema.check_constraints cc JOIN information_schema.table_constraints tc ON cc.constraint_name = tc.constraint_name WHERE tc.table_schema = ? AND tc.table_name = ?"; + ps = conn.prepareStatement(qc); + ps.setString(1, schema); + ps.setString(2, table); + } else { + qc = "SELECT cc.constraint_name, cc.check_clause FROM information_schema.check_constraints cc JOIN information_schema.table_constraints tc ON cc.constraint_name = tc.constraint_name WHERE tc.table_name = ?"; + ps = conn.prepareStatement(qc); + ps.setString(1, table); + } + try (ResultSet cr = ps.executeQuery()) { + while (cr.next()) meta.checks.add(cr.getString("constraint_name") + ": " + cr.getString("check_clause")); + } + } catch (Throwable ignored) { } + + // domains / enums + try (PreparedStatement ps = conn.prepareStatement(schema != null ? + "SELECT column_name, domain_name, udt_name FROM information_schema.columns WHERE table_schema = ? AND table_name = ?" : + "SELECT column_name, domain_name, udt_name FROM information_schema.columns WHERE table_name = ?")) { + if (schema != null) { + ps.setString(1, schema); + ps.setString(2, table); + } else { + ps.setString(1, table); + } + try (ResultSet cr = ps.executeQuery()) { + while (cr.next()) { + String col = cr.getString("column_name"); + String domain = cr.getString("domain_name"); + String udt = cr.getString("udt_name"); + if ((domain != null && !domain.isBlank()) || (udt != null && !udt.isBlank())) { + meta.domains.add(col + ": domain=" + (domain == null ? "" : domain) + (udt == null ? "" : (" udt=" + udt))); + } + } + } + } catch (Throwable ignored) { } + + return meta; + } +} diff --git a/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java index df965da..2ab92fb 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/JavaDBMSMagics.java @@ -305,58 +305,44 @@ public void rdbmsSchema(java.util.List args, String body) { for (String tableName : tableNames) { Table table = new Table(tableName); - // columns - try (ResultSet columns = md.getColumns(null, schema, tableName, null)) { - while (columns.next()) { - String columnName = columns.getString("COLUMN_NAME"); - table.getFields().put(columnName, - Field.of(columnName, - columns.getString("COLUMN_SIZE"), - columns.getString("TYPE_NAME"), - columns.getString("IS_NULLABLE").equalsIgnoreCase("YES"), - "YES".equalsIgnoreCase(columns.getString("IS_AUTOINCREMENT")))); - } - } + // use inspector to collect metadata for this table + DBMetadataInspector.TableMetadata meta = DBMetadataInspector.inspect(conn, schema, tableName); - // primary keys - try (ResultSet primaryKeys = md.getPrimaryKeys(null, schema, tableName)) { - while (primaryKeys.next()) { - String pkCol = primaryKeys.getString("COLUMN_NAME"); - if (table.getFields().containsKey(pkCol)) - table.getFields().get(pkCol).setRole(Field.Role.PK); - } + // populate fields + for (DBMetadataInspector.ColumnMeta cm : meta.columns) { + Field f = Field.of(cm.name, cm.size > 0 ? String.valueOf(cm.size) : null, cm.type, cm.nullable, false); + table.getFields().put(cm.name, f); } - // foreign keys - try (ResultSet foreignKeys = md.getImportedKeys(null, schema, tableName)) { - while (foreignKeys.next()) { - String pkTable = foreignKeys.getString("PKTABLE_NAME"); - String fkTable = foreignKeys.getString("FKTABLE_NAME"); - String pkCol = foreignKeys.getString("PKCOLUMN_NAME"); - String fkCol = foreignKeys.getString("FKCOLUMN_NAME"); - if (table.getFields().containsKey(fkCol)) - table.getFields().get(fkCol).setRole(Field.Role.FK); - - // Determine multiplicity on the FK side. - String fkMin = "0"; - String fkMax = "*"; - if (table.getFields().containsKey(fkCol)) { - Field fkField = table.getFields().get(fkCol); - fkMin = fkField.isNullable() ? "0" : "1"; - // If FK column is part of the PK (or unique), treat as max 1 - if (fkField.getRole() == Field.Role.PK) - fkMax = "1"; - } - - String pkMultiplicity = "1"; // primary key side is single (unique) - String fkMultiplicity = fkMin + ".." + fkMax; + // mark PKs + for (String pk : meta.primaryKeys) { + if (table.getFields().containsKey(pk)) + table.getFields().get(pk).setRole(Field.Role.PK); + } - // Emit relationship with multiplicities and a simple label showing column - // mapping - fkBuilder.append(String.format("%s \"%s\" --> \"%s\" %s : %s -> %s\n", - quoteIdentifier(fkTable), fkMultiplicity, pkMultiplicity, quoteIdentifier(pkTable), - quoteIdentifier(fkCol), quoteIdentifier(pkCol))); + // mark FKs and produce relationships + for (DBMetadataInspector.FKMeta fk : meta.foreignKeys) { + String fkCol = fk.fkColumn; + String pkTable = fk.pkTable; + String pkCol = fk.pkColumn; + if (table.getFields().containsKey(fkCol)) + table.getFields().get(fkCol).setRole(Field.Role.FK); + + // multiplicities: estimate from nullable & PK membership + String fkMin = "0"; + String fkMax = "*"; + if (table.getFields().containsKey(fkCol)) { + Field fkField = table.getFields().get(fkCol); + fkMin = fkField.isNullable() ? "0" : "1"; + if (fkField.getRole() == Field.Role.PK) + fkMax = "1"; } + String pkMultiplicity = "1"; + String fkMultiplicity = fkMin + ".." + fkMax; + + fkBuilder.append(String.format("%s \"%s\" --> \"%s\" %s : %s -> %s\n", + quoteIdentifier(tableName), fkMultiplicity, pkMultiplicity, quoteIdentifier(pkTable), + quoteIdentifier(fkCol), quoteIdentifier(pkCol))); } out.append(table.toString()); diff --git a/src/main/java/io/github/spencerpark/ijava/magics/TableSchemaMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/TableSchemaMagics.java new file mode 100644 index 0000000..6d00f19 --- /dev/null +++ b/src/main/java/io/github/spencerpark/ijava/magics/TableSchemaMagics.java @@ -0,0 +1,349 @@ +package io.github.spencerpark.ijava.magics; + +import io.github.spencerpark.ijava.runtime.Display; +import io.github.spencerpark.jupyter.kernel.magic.registry.CellMagic; +import io.github.spencerpark.jupyter.kernel.magic.registry.LineMagic; + +import java.sql.*; +import java.util.*; +import java.util.stream.Collectors; + +/** + * Magic to display detailed table schema metadata in Jupyter (IJava). + * + * Usage: + * %tableSchema [schema.]table [--ddl] [--sample=N] [--compact] + * %%tableSchema same options, multiple tables in cell body + */ +public class TableSchemaMagics { + + // --------------------- ARG PARSING --------------------- + private static class SchemaArgs { + String tableArg; + boolean ddl = false; + Integer sampleRows = null; + boolean compact = false; + boolean help = false; + } + + private SchemaArgs parseArgs(List args) { + SchemaArgs sa = new SchemaArgs(); + if (args == null) + return sa; + + for (String a : args) { + if (a == null) + continue; + switch (a) { + case "--ddl": + sa.ddl = true; + break; + case "--compact": + sa.compact = true; + break; + case "--help": + case "-h": + sa.help = true; + break; + default: + if (a.startsWith("--sample=")) { + try { + sa.sampleRows = Integer.parseInt(a.substring("--sample=".length())); + } catch (NumberFormatException ignored) { + } + } else if (sa.tableArg == null) { + sa.tableArg = a; + } + break; + } + } + return sa; + } + + // --------------------- LINE MAGIC --------------------- + @LineMagic("tableSchema") + public void tableSchema(List args) { + SchemaArgs sa = parseArgs(args); + if (sa.help) { + printHelp(false); + return; + } + renderTableSchema(sa.tableArg, sa.ddl, sa.sampleRows, sa.compact); + } + + // --------------------- CELL MAGIC --------------------- + @CellMagic("tableSchema") + public void tableSchemaCell(List args, String body) { + SchemaArgs sa = parseArgs(args); + if (sa.help) { + printHelp(true); + return; + } + if (body != null && !body.isBlank()) { + for (String line : body.split("\\r?\\n")) { + String tbl = line.strip(); + if (!tbl.isEmpty()) + renderTableSchema(tbl, sa.ddl, sa.sampleRows, sa.compact); + } + } else { + renderTableSchema(sa.tableArg, sa.ddl, sa.sampleRows, sa.compact); + } + } + + private void printHelp(boolean cell) { + String prefix = cell ? "%%tableSchema" : "%tableSchema"; + System.out.println(prefix + " - Show detailed table schema metadata\n\n" + + "Usage: " + prefix + " [schema.]table [--ddl] [--sample=N] [--compact] [--help]\n\n" + + "Options:\n" + + " --ddl Show a minimal CREATE TABLE DDL snippet\n" + + " --sample=N Show up to N sample rows\n" + + " --compact Show compact table summary in relational notation\n" + + " --help, -h Show this help message"); + } + + // --------------------- MAIN RENDER LOGIC --------------------- + private void renderTableSchema(String tableArg, boolean ddl, Integer sampleRows, boolean compact) { + if (tableArg == null || tableArg.isBlank()) { + System.out.println("Usage: %tableSchema [schema.]table [--ddl] [--sample=N] [--compact]"); + return; + } + + // Split schema.table + String schema = null; + String table = tableArg; + if (tableArg.contains(".")) { + int idx = tableArg.indexOf('.'); + schema = tableArg.substring(0, idx); + table = tableArg.substring(idx + 1); + } + + // Security: only allow alphanumeric + underscore for table + if (!table.matches("[\\w]+")) { + Display.display("Invalid table name: " + tableArg, "text/plain"); + return; + } + + try (Connection conn = obtainConnection()) { + if (conn == null) { + Display.display("No JDBC connection available.", "text/plain"); + return; + } + + // Use DBMetadataInspector to collect a normalized view of the table + DBMetadataInspector.TableMetadata meta = DBMetadataInspector.inspect(conn, schema, table); + + // --------------------- COLUMNS --------------------- + List columns = new ArrayList<>(); + for (DBMetadataInspector.ColumnMeta cm : meta.columns) { + columns.add(new ColumnInfo(cm.name, cm.type, cm.size, cm.nullable, cm.defaultValue, cm.remarks)); + } + if (columns.isEmpty()) { + Display.display("Table not found or has no columns: " + tableArg, "text/plain"); + return; + } + + // --------------------- PRIMARY KEYS --------------------- + List primaryKeys = new ArrayList<>(meta.primaryKeys); + + // --------------------- INDEXES --------------------- + Map indexes = new HashMap<>(); + for (DBMetadataInspector.IndexMeta im : meta.indexes.values()) { + IndexInfo ii = new IndexInfo(im.name, im.unique); + ii.columns.addAll(im.columns); + indexes.put(ii.name, ii); + } + + // Determine single-column unique indexes for inline marking + Set uniqueColumns = new HashSet<>(); + for (IndexInfo ii : indexes.values()) { + if (ii.unique && ii.columns.size() == 1) { + uniqueColumns.add(ii.columns.get(0)); + } + } + + // --------------------- FOREIGN KEYS --------------------- + Map fkMap = new HashMap<>(); + for (DBMetadataInspector.FKMeta f : meta.foreignKeys) { + fkMap.put(f.fkColumn, f.pkTable + "(" + f.pkColumn + ")"); + } + + // Normalize name sets/maps for case-insensitive matching + Set pkSetNorm = primaryKeys.stream().map(s -> s == null ? null : s.toUpperCase(Locale.ROOT)).filter(Objects::nonNull).collect(Collectors.toSet()); + Set uniqueColumnsNorm = uniqueColumns.stream().map(s -> s == null ? null : s.toUpperCase(Locale.ROOT)).filter(Objects::nonNull).collect(Collectors.toSet()); + Map fkMapNorm = new HashMap<>(); + for (Map.Entry e : fkMap.entrySet()) { + if (e.getKey() != null) + fkMapNorm.put(e.getKey().toUpperCase(Locale.ROOT), e.getValue()); + } + + // --------------------- OUTPUT --------------------- + StringBuilder out = new StringBuilder(); + out.append("# Table ``").append(tableArg).append("``\n\n"); + + if (compact) { + // Construct relational notation + List columnTokens = new ArrayList<>(); + for (ColumnInfo c : columns) { + StringBuilder token = new StringBuilder(c.name); + if (pkSetNorm.contains(c.name == null ? null : c.name.toUpperCase(Locale.ROOT))) + token.append(" (PK)"); + if (uniqueColumnsNorm.contains(c.name == null ? null : c.name.toUpperCase(Locale.ROOT))) + token.append(" (UNIQUE)"); + if (fkMapNorm.containsKey(c.name == null ? null : c.name.toUpperCase(Locale.ROOT))) + token.append(" → ").append(fkMapNorm.get(c.name.toUpperCase(Locale.ROOT))); + columnTokens.add(token.toString()); + } + out.append(table.toUpperCase()).append("(") + .append(String.join(", ", columnTokens)) + .append(")\n\n"); + } else { + // Markdown table + out.append("| Column | Type | Nullable | Default | Remarks |\n"); + out.append("|---|---|:---:|---|---|\n"); + for (ColumnInfo c : columns) { + String annotatedName = c.name; + if (pkSetNorm.contains(c.name == null ? null : c.name.toUpperCase(Locale.ROOT))) + annotatedName += " (PK)"; + if (uniqueColumnsNorm.contains(c.name == null ? null : c.name.toUpperCase(Locale.ROOT))) + annotatedName += " (UNIQUE)"; + if (fkMapNorm.containsKey(c.name == null ? null : c.name.toUpperCase(Locale.ROOT))) + annotatedName += " → " + fkMapNorm.get(c.name.toUpperCase(Locale.ROOT)); + + out.append(String.format("| %s | %s%s | %s | %s | %s |\n", + annotatedName, + c.type, c.size > 0 ? "(" + c.size + ")" : "", + c.nullable ? "" : "NOT NULL", + c.defaultValue == null ? "" : c.defaultValue, + c.remarks == null ? "" : c.remarks)); + } + out.append("\n"); + + if (!primaryKeys.isEmpty()) + out.append("**Primary key**: ").append(String.join(", ", primaryKeys)).append("\n\n"); + + if (!indexes.isEmpty()) { + out.append("**Indexes**:\n"); + for (IndexInfo i : indexes.values()) { + out.append("- ").append(i.name) + .append(" (").append(String.join(", ", i.columns)).append(") ") + .append(i.unique ? "UNIQUE" : "") + .append("\n"); + } + out.append("\n"); + } + + if (!fkMap.isEmpty()) { + out.append("**Foreign keys**:\n"); + fkMap.forEach( + (fkCol, ref) -> out.append("- ").append(fkCol).append(" → ").append(ref).append("\n")); + out.append("\n"); + } + } + + // --------------------- DDL --------------------- + if (ddl) { + StringBuilder ddlText = new StringBuilder(); + ddlText.append("CREATE TABLE ").append(tableArg).append(" (\n"); + ddlText.append(columns.stream() + .map(c -> " " + c.name + " " + c.type + (c.size > 0 ? "(" + c.size + ")" : "") + + (c.nullable ? "" : " NOT NULL") + + (c.defaultValue != null ? " DEFAULT " + c.defaultValue : "")) + .collect(Collectors.joining(",\n"))); + if (!primaryKeys.isEmpty()) { + ddlText.append(",\n PRIMARY KEY (").append(String.join(", ", primaryKeys)).append(")"); + } + ddlText.append("\n);"); + out.append("```\n").append(ddlText).append("\n```\n"); + } + + Display.display(out.toString(), "text/markdown"); + + // --------------------- SAMPLE ROWS --------------------- + if (sampleRows != null && sampleRows > 0) { + try (Statement s = conn.createStatement()) { + String sql = "SELECT * FROM " + tableArg + " LIMIT " + sampleRows; + try (ResultSet rs = s.executeQuery(sql)) { + StringBuilder tbl = new StringBuilder(); + ResultSetMetaData rm = rs.getMetaData(); + int nc = rm.getColumnCount(); + + // header + tbl.append("|"); + for (int i = 1; i <= nc; i++) + tbl.append(" ").append(rm.getColumnName(i)).append(" |"); + tbl.append("\n|"); + for (int i = 1; i <= nc; i++) + tbl.append(" --- |"); + tbl.append("\n"); + + while (rs.next()) { + tbl.append("|"); + for (int i = 1; i <= nc; i++) { + Object v = rs.getObject(i); + tbl.append(" ").append(v == null ? "NULL" : v.toString()).append(" |"); + } + tbl.append("\n"); + } + Display.display(tbl.toString(), "text/markdown"); + } + } catch (Throwable t) { + Display.display("Failed to sample rows: " + t.getMessage(), "text/plain"); + } + } + + } catch (SQLException e) { + throw new RuntimeException(e); + } + } + + // --------------------- HELPERS --------------------- + private static class ColumnInfo { + String name, type, defaultValue, remarks; + boolean nullable; + int size; + + ColumnInfo(String name, String type, int size, boolean nullable, String defaultValue, String remarks) { + this.name = name; + this.type = type; + this.size = size; + this.nullable = nullable; + this.defaultValue = defaultValue; + this.remarks = remarks; + } + } + + private static class IndexInfo { + String name; + boolean unique; + List columns = new ArrayList<>(); + + IndexInfo(String name, boolean unique) { + this.name = name; + this.unique = unique; + } + } + + // --------------------- JDBC CONNECTION --------------------- + private Connection obtainConnection() throws SQLException { + String url = System.getProperty("jdbc.url"); + if (url != null && !url.isBlank()) { + String user = System.getProperty("jdbc.user"); + String pass = System.getProperty("jdbc.password"); + if (user != null) + return DriverManager.getConnection(url, user, pass == null ? "" : pass); + return DriverManager.getConnection(url); + } + try { + Class dm = Class.forName("DatabaseManager"); + try { + java.lang.reflect.Method m = dm.getMethod("getConnection"); + Object conn = m.invoke(null); + if (conn instanceof Connection) + return (Connection) conn; + } catch (NoSuchMethodException ignored) { + } + } catch (ReflectiveOperationException ignored) { + } + return null; + } +} From 7ee6abb11928ae5328450d3c08eb7c9d0fc71f14 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Fri, 30 Jan 2026 16:29:05 +0100 Subject: [PATCH 28/49] fix(magics): remove markdown headers that break layout --- notebooks/magics_demo.ipynb | 497 +++++++++++++----- .../spencerpark/ijava/magics/MagicsTool.java | 10 +- .../ijava/magics/TableSchemaMagics.java | 1 - 3 files changed, 379 insertions(+), 129 deletions(-) diff --git a/notebooks/magics_demo.ipynb b/notebooks/magics_demo.ipynb index 99bac3f..e6eb65b 100644 --- a/notebooks/magics_demo.ipynb +++ b/notebooks/magics_demo.ipynb @@ -11,8 +11,79 @@ { "cell_type": "code", "execution_count": 1, + "id": "87360ba5", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "registered line magics: \n", + "\t- jars\n", + "\t- classDiagram\n", + "\t- classpath\n", + "\t- javadoc-html\n", + "\t- write\n", + "\t- commonshellcmd\n", + "\t- printerPrefix\n", + "\t- read\n", + "\t- tableSchema\n", + "\t- reload-class\n", + "\t- where, which\n", + "\t- classpath-snapshot\n", + "\t- class-info\n", + "\t- cmd\n", + "\t- load\n", + "\t- listCellMagic\n", + "\t- listMagic, list\n", + "\t- addMavenRepo, mavenRepo\n", + "\t- printWithName\n", + "\t- pom, loadFromPOM\n", + "\t- addMavenDependencies, maven, addMavenDependency\n", + "\t- listLineMagic\n", + "registered cell magics: \n", + "\t- plantUMLFile\n", + "\t- compile\n", + "\t- shell\n", + "\t- javasrcConstructorByName\n", + "\t- plantUML\n", + "\t- mycompile\n", + "\t- javasrcFieldByName\n", + "\t- javasrcMethodByAnnotationName\n", + "\t- javasrcJavadoc\n", + "\t- pom, loadFromPOM\n", + "\t- javasrcClassByName\n", + "\t- rdbmsSchema\n", + "\t- javasrcInterfaceByName\n", + "\t- benchmark\n", + "\t- write\n", + "\t- commonshell\n", + "\t- classDiagram\n", + "\t- javasrcMethodByName\n", + "\t- sqlAsTable\n", + "\t- tableSchema\n", + "\t- javasrcList\n", + "\t- timeit, timeIt, time\n" + ] + } + ], + "source": [ + "%list" + ] + }, + { + "cell_type": "code", + "execution_count": 2, "id": "d5ae9350", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { @@ -20,7 +91,7 @@ "\u001b[36m\"Helloworld!\";\u001b[0m: Hello world !" ] }, - "execution_count": 1, + "execution_count": 2, "metadata": {}, "output_type": "execute_result" } @@ -31,9 +102,13 @@ }, { "cell_type": "code", - "execution_count": 2, + "execution_count": 3, "id": "1c4668b6", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { @@ -41,7 +116,7 @@ "\u001b[36m3+4*2\u001b[0m: 11" ] }, - "execution_count": 2, + "execution_count": 3, "metadata": {}, "output_type": "execute_result" } @@ -60,9 +135,13 @@ }, { "cell_type": "code", - "execution_count": 3, + "execution_count": 4, "id": "e5e10708", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "name": "stdout", @@ -82,9 +161,13 @@ }, { "cell_type": "code", - "execution_count": 4, + "execution_count": 5, "id": "4f6628be", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "name": "stdout", @@ -115,9 +198,13 @@ }, { "cell_type": "code", - "execution_count": 5, + "execution_count": 6, "id": "3606b844", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [], "source": [ "%maven org.projectlombok:lombok:1.18.42" @@ -125,9 +212,13 @@ }, { "cell_type": "code", - "execution_count": 6, + "execution_count": 7, "id": "c14e858c", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "name": "stdout", @@ -172,9 +263,13 @@ }, { "cell_type": "code", - "execution_count": 7, + "execution_count": 8, "id": "f15afeff", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [], "source": [ "%%compile --class=com.example.demo.Hello --output=out\n", @@ -194,9 +289,13 @@ }, { "cell_type": "code", - "execution_count": 8, + "execution_count": 9, "id": "237d7c9b", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { @@ -204,7 +303,7 @@ "\u001b[36mcom.example.demo.Hello.greet();\u001b[0m: Hello from compiled class" ] }, - "execution_count": 8, + "execution_count": 9, "metadata": {}, "output_type": "execute_result" } @@ -215,9 +314,13 @@ }, { "cell_type": "code", - "execution_count": 9, + "execution_count": 10, "id": "0481b2b2", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [], "source": [ "%%compile --class=com.example.demo.LombokPerson --output=out --processor-path=/var/home/bruno/.m2/repository/org/projectlombok/lombok/1.18.42/lombok-1.18.42.jar --classpath=/var/home/bruno/.m2/repository/org/projectlombok/lombok/1.18.42/lombok-1.18.42.jar\n", @@ -234,9 +337,13 @@ }, { "cell_type": "code", - "execution_count": 10, + "execution_count": 11, "id": "f7128d07", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "name": "stdout", @@ -264,9 +371,13 @@ }, { "cell_type": "code", - "execution_count": 11, + "execution_count": 12, "id": "4968d01a", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "name": "stdout", @@ -306,9 +417,13 @@ }, { "cell_type": "code", - "execution_count": 12, + "execution_count": 13, "id": "05391c3a", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "name": "stdout", @@ -331,9 +446,13 @@ }, { "cell_type": "code", - "execution_count": 13, + "execution_count": 14, "id": "2f994624", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "name": "stdout", @@ -360,9 +479,13 @@ }, { "cell_type": "code", - "execution_count": 14, + "execution_count": 15, "id": "63f2121b", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "name": "stdout", @@ -390,9 +513,13 @@ }, { "cell_type": "code", - "execution_count": 15, + "execution_count": 16, "id": "e4cd33c7", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [], "source": [ "%maven com.h2database:h2:2.4.240" @@ -400,9 +527,13 @@ }, { "cell_type": "code", - "execution_count": 16, + "execution_count": 17, "id": "18c47637", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [], "source": [ "System.setProperty(\"jdbc.url\", \"jdbc:h2:mem:test;DB_CLOSE_DELAY=-1\");\n", @@ -412,9 +543,13 @@ }, { "cell_type": "code", - "execution_count": 17, + "execution_count": 18, "id": "2b08450b", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [], "source": [ "%%sqlAsTable --help" @@ -422,9 +557,13 @@ }, { "cell_type": "code", - "execution_count": 18, + "execution_count": 19, "id": "020dddda", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { @@ -633,9 +772,13 @@ }, { "cell_type": "code", - "execution_count": 19, + "execution_count": 20, "id": "b2d60553", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "name": "stdout", @@ -655,9 +798,13 @@ }, { "cell_type": "code", - "execution_count": 20, + "execution_count": 21, "id": "83570636", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { @@ -683,9 +830,13 @@ }, { "cell_type": "code", - "execution_count": 21, + "execution_count": 22, "id": "e272026f", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "name": "stdout", @@ -709,15 +860,17 @@ }, { "cell_type": "code", - "execution_count": 22, + "execution_count": 23, "id": "31d809c0", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { "text/markdown": [ - "# Table ``PRODUCTS``\n", - "\n", "| Column | Type | Nullable | Default | Remarks |\n", "|---|---|:---:|---|---|\n", "| ID (PK) (UNIQUE) | INTEGER(32) | NOT NULL | | |\n", @@ -739,8 +892,6 @@ "```\n" ], "text/plain": [ - "# Table ``PRODUCTS``\n", - "\n", "| Column | Type | Nullable | Default | Remarks |\n", "|---|---|:---:|---|---|\n", "| ID (PK) (UNIQUE) | INTEGER(32) | NOT NULL | | |\n", @@ -792,15 +943,17 @@ }, { "cell_type": "code", - "execution_count": 23, + "execution_count": 24, "id": "7c5ead4d", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { "text/markdown": [ - "# Table ``ORDERS``\n", - "\n", "| Column | Type | Nullable | Default | Remarks |\n", "|---|---|:---:|---|---|\n", "| ID (PK) (UNIQUE) | INTEGER(32) | NOT NULL | | |\n", @@ -818,8 +971,6 @@ "\n" ], "text/plain": [ - "# Table ``ORDERS``\n", - "\n", "| Column | Type | Nullable | Default | Remarks |\n", "|---|---|:---:|---|---|\n", "| ID (PK) (UNIQUE) | INTEGER(32) | NOT NULL | | |\n", @@ -865,15 +1016,17 @@ }, { "cell_type": "code", - "execution_count": 24, + "execution_count": 25, "id": "db0eea00", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { "text/markdown": [ - "# Table ``ORDER_ITEMS``\n", - "\n", "| Column | Type | Nullable | Default | Remarks |\n", "|---|---|:---:|---|---|\n", "| ORDER_ID (PK) → ORDERS(ID) | INTEGER(32) | NOT NULL | | |\n", @@ -893,8 +1046,6 @@ "\n" ], "text/plain": [ - "# Table ``ORDER_ITEMS``\n", - "\n", "| Column | Type | Nullable | Default | Remarks |\n", "|---|---|:---:|---|---|\n", "| ORDER_ID (PK) → ORDERS(ID) | INTEGER(32) | NOT NULL | | |\n", @@ -944,21 +1095,21 @@ }, { "cell_type": "code", - "execution_count": 25, + "execution_count": 26, "id": "fcac85a3", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { "text/markdown": [ - "# Table ``ORDER_ITEMS``\n", - "\n", "ORDER_ITEMS(ORDER_ID (PK) → ORDERS(ID), PRODUCT_ID (PK) → PRODUCTS(ID), QTY)\n", "\n" ], "text/plain": [ - "# Table ``ORDER_ITEMS``\n", - "\n", "ORDER_ITEMS(ORDER_ID (PK) → ORDERS(ID), PRODUCT_ID (PK) → PRODUCTS(ID), QTY)\n", "\n" ] @@ -982,9 +1133,13 @@ }, { "cell_type": "code", - "execution_count": 26, + "execution_count": 27, "id": "fe2f0039", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { @@ -1009,9 +1164,13 @@ }, { "cell_type": "code", - "execution_count": 27, + "execution_count": 28, "id": "c04b48ea", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { @@ -1067,9 +1226,13 @@ }, { "cell_type": "code", - "execution_count": 28, + "execution_count": 29, "id": "33a64ebb", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { @@ -1112,9 +1275,13 @@ }, { "cell_type": "code", - "execution_count": 29, + "execution_count": 30, "id": "0898c655", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { @@ -1156,9 +1323,13 @@ }, { "cell_type": "code", - "execution_count": 30, + "execution_count": 31, "id": "d471c6f9", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { @@ -1183,9 +1354,13 @@ }, { "cell_type": "code", - "execution_count": 31, + "execution_count": 32, "id": "6b425967", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { @@ -1217,9 +1392,13 @@ }, { "cell_type": "code", - "execution_count": 32, + "execution_count": 33, "id": "f56fa36e", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { @@ -1244,9 +1423,13 @@ }, { "cell_type": "code", - "execution_count": 33, + "execution_count": 34, "id": "82e2cfbb", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { @@ -1300,9 +1483,13 @@ }, { "cell_type": "code", - "execution_count": 34, + "execution_count": 35, "id": "11d6e07e", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { @@ -1327,9 +1514,13 @@ }, { "cell_type": "code", - "execution_count": 35, + "execution_count": 36, "id": "f51da0ac", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { @@ -1363,9 +1554,13 @@ }, { "cell_type": "code", - "execution_count": 36, + "execution_count": 37, "id": "0de30e18", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { @@ -1390,9 +1585,13 @@ }, { "cell_type": "code", - "execution_count": 37, + "execution_count": 38, "id": "ee9cb95d", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { @@ -1418,9 +1617,13 @@ }, { "cell_type": "code", - "execution_count": 38, + "execution_count": 39, "id": "e70d0cee", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { @@ -1457,9 +1660,13 @@ }, { "cell_type": "code", - "execution_count": 39, + "execution_count": 40, "id": "a9482ebf", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "name": "stdout", @@ -1479,16 +1686,20 @@ }, { "cell_type": "code", - "execution_count": 40, + "execution_count": 41, "id": "aea54b0e", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ - "samples: [22135483, 22509874, 23679324, 23768707, 18312544]\n", - "min=18312544 median=22509874 avg=22081186,40 max=23768707 (nanoseconds)\n" + "samples: [22505238, 24402791, 22688366, 20435323, 20365883]\n", + "min=20365883 median=22505238 avg=22079520,20 max=24402791 (nanoseconds)\n" ] } ], @@ -1512,9 +1723,13 @@ }, { "cell_type": "code", - "execution_count": 41, + "execution_count": 42, "id": "117a9618", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "name": "stdout", @@ -1539,9 +1754,13 @@ }, { "cell_type": "code", - "execution_count": 42, + "execution_count": 43, "id": "f25a7a92", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [], "source": [ "// Helper: run a Supplier-driven test and return accumulated result\n", @@ -1583,17 +1802,21 @@ }, { "cell_type": "code", - "execution_count": 43, + "execution_count": 44, "id": "5a7f5050", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { "image/svg+xml": [ - "10002000300040005000600070008000900010000nBenchmark sweep: n0,003,466,9110,3713,8217,2817,2810,5210,117,717,539,047,046,507,078,2910,369,669,398,739,967,397,788,148,186,18// HashMap implementation// TreeMap implementationaveraged over 10 iterations (warmup=1)" + "10002000300040005000600070008000900010000nBenchmark sweep: n0,002,204,406,618,8111,0111,019,178,777,479,998,636,677,336,907,5910,5010,917,608,8010,607,838,179,509,246,98// HashMap implementation// TreeMap implementationaveraged over 10 iterations (warmup=1)" ], "text/plain": [ - "10002000300040005000600070008000900010000nBenchmark sweep: n0,003,466,9110,3713,8217,2817,2810,5210,117,717,539,047,046,507,078,2910,369,669,398,739,967,397,788,148,186,18// HashMap implementation// TreeMap implementationaveraged over 10 iterations (warmup=1)" + "10002000300040005000600070008000900010000nBenchmark sweep: n0,002,204,406,618,8111,0111,019,178,777,479,998,636,677,336,907,5910,5010,917,608,8010,607,838,179,509,246,98// HashMap implementation// TreeMap implementationaveraged over 10 iterations (warmup=1)" ] }, "metadata": {}, @@ -1623,9 +1846,13 @@ }, { "cell_type": "code", - "execution_count": 44, + "execution_count": 45, "id": "99467b83", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "name": "stdout", @@ -1689,9 +1916,13 @@ }, { "cell_type": "code", - "execution_count": 45, + "execution_count": 46, "id": "f01b8759", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "name": "stdout", @@ -1708,9 +1939,13 @@ }, { "cell_type": "code", - "execution_count": 46, + "execution_count": 47, "id": "59d54da7", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [], "source": [ "%%compile --class=com.example.demo.C --output=out\n", @@ -1722,9 +1957,13 @@ }, { "cell_type": "code", - "execution_count": 47, + "execution_count": 48, "id": "d49e214a", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [], "source": [ "%%compile --class=com.example.demo.A --output=out\n", @@ -1735,9 +1974,13 @@ }, { "cell_type": "code", - "execution_count": 48, + "execution_count": 49, "id": "21bc5030", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [], "source": [ "%%compile --class=com.example.demo.B --output=out\n", @@ -1748,9 +1991,13 @@ }, { "cell_type": "code", - "execution_count": 49, + "execution_count": 50, "id": "e6e614c6", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "name": "stdout", @@ -1766,9 +2013,13 @@ }, { "cell_type": "code", - "execution_count": 50, + "execution_count": 51, "id": "317ff290", - "metadata": {}, + "metadata": { + "vscode": { + "languageId": "java" + } + }, "outputs": [ { "data": { @@ -1798,7 +2049,7 @@ "codemirror_mode": "java", "file_extension": ".jshell", "mimetype": "text/x-java-source", - "name": "java", + "name": "Java", "pygments_lexer": "java", "version": "25.0.1+8-LTS" } diff --git a/src/main/java/io/github/spencerpark/ijava/magics/MagicsTool.java b/src/main/java/io/github/spencerpark/ijava/magics/MagicsTool.java index 27e8664..53da942 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/MagicsTool.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/MagicsTool.java @@ -133,7 +133,7 @@ public void classInfo(List args) { Class c = Class.forName(fqcn, false, Thread.currentThread().getContextClassLoader()); StringBuilder md = new StringBuilder(); - md.append("# ").append(c.getName()).append("\n\n"); + md.append("**").append(c.getName()).append("**\n\n"); md.append("- Package: ") .append(c.getPackage() == null ? "(default)" : c.getPackage().getName()).append("\n"); md.append("- Modifiers: ").append(Modifier.toString(c.getModifiers())).append("\n"); @@ -141,13 +141,13 @@ public void classInfo(List args) { Annotation[] ann = c.getAnnotations(); if (ann != null && ann.length > 0) { - md.append("## Annotations\n"); + md.append("**Annotations**\n"); for (Annotation a : ann) md.append("- ").append(a.toString()).append("\n"); md.append("\n"); } - md.append("## Constructors\n"); + md.append("**Constructors**\n"); for (Constructor ctor : c.getDeclaredConstructors()) { md.append("- ") .append(Modifier.toString(ctor.getModifiers())).append(" ") @@ -157,7 +157,7 @@ public void classInfo(List args) { .append(")\n"); } - md.append("\n## Fields\n"); + md.append("\n**Fields**\n"); for (Field f : c.getDeclaredFields()) { md.append("- ") .append(Modifier.toString(f.getModifiers())).append(" ") @@ -165,7 +165,7 @@ public void classInfo(List args) { .append(f.getName()).append("\n"); } - md.append("\n## Methods\n"); + md.append("\n**Methods**\n"); for (Method m : c.getDeclaredMethods()) { md.append("- ") .append(Modifier.toString(m.getModifiers())).append(" ") diff --git a/src/main/java/io/github/spencerpark/ijava/magics/TableSchemaMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/TableSchemaMagics.java index 6d00f19..95839e9 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/TableSchemaMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/TableSchemaMagics.java @@ -178,7 +178,6 @@ private void renderTableSchema(String tableArg, boolean ddl, Integer sampleRows, // --------------------- OUTPUT --------------------- StringBuilder out = new StringBuilder(); - out.append("# Table ``").append(tableArg).append("``\n\n"); if (compact) { // Construct relational notation From 8fee47ecc21edf96eeb1a40fe1f359f48a35b826 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Sat, 31 Jan 2026 10:31:03 +0100 Subject: [PATCH 29/49] chore: apply workspace changes --- notebooks/magics_demo.ipynb | 213 +++++++++++--- .../github/spencerpark/ijava/JavaKernel.java | 1 + .../ijava/magics/GitMermaidMagics.java | 276 ++++++++++++++++++ 3 files changed, 455 insertions(+), 35 deletions(-) create mode 100644 src/main/java/io/github/spencerpark/ijava/magics/GitMermaidMagics.java diff --git a/notebooks/magics_demo.ipynb b/notebooks/magics_demo.ipynb index e6eb65b..57912c5 100644 --- a/notebooks/magics_demo.ipynb +++ b/notebooks/magics_demo.ipynb @@ -23,51 +23,52 @@ "output_type": "stream", "text": [ "registered line magics: \n", - "\t- jars\n", - "\t- classDiagram\n", - "\t- classpath\n", - "\t- javadoc-html\n", - "\t- write\n", - "\t- commonshellcmd\n", "\t- printerPrefix\n", - "\t- read\n", + "\t- load\n", "\t- tableSchema\n", + "\t- jars\n", + "\t- cmd\n", + "\t- listMagic, list\n", + "\t- read\n", + "\t- classDiagram\n", "\t- reload-class\n", + "\t- javadoc-html\n", + "\t- listLineMagic\n", "\t- where, which\n", - "\t- classpath-snapshot\n", - "\t- class-info\n", - "\t- cmd\n", - "\t- load\n", + "\t- classpath\n", "\t- listCellMagic\n", - "\t- listMagic, list\n", - "\t- addMavenRepo, mavenRepo\n", + "\t- commonshellcmd\n", + "\t- git-graph-mermaid\n", "\t- printWithName\n", - "\t- pom, loadFromPOM\n", "\t- addMavenDependencies, maven, addMavenDependency\n", - "\t- listLineMagic\n", + "\t- classpath-snapshot\n", + "\t- pom, loadFromPOM\n", + "\t- write\n", + "\t- addMavenRepo, mavenRepo\n", + "\t- class-info\n", "registered cell magics: \n", - "\t- plantUMLFile\n", + "\t- javasrcList\n", "\t- compile\n", - "\t- shell\n", "\t- javasrcConstructorByName\n", - "\t- plantUML\n", - "\t- mycompile\n", "\t- javasrcFieldByName\n", - "\t- javasrcMethodByAnnotationName\n", - "\t- javasrcJavadoc\n", - "\t- pom, loadFromPOM\n", - "\t- javasrcClassByName\n", - "\t- rdbmsSchema\n", - "\t- javasrcInterfaceByName\n", - "\t- benchmark\n", "\t- write\n", + "\t- timeit, timeIt, time\n", + "\t- benchmark\n", + "\t- plantUMLFile\n", + "\t- plantUML\n", "\t- commonshell\n", - "\t- classDiagram\n", - "\t- javasrcMethodByName\n", + "\t- javasrcInterfaceByName\n", + "\t- javasrcMethodByAnnotationName\n", "\t- sqlAsTable\n", + "\t- shell\n", + "\t- classDiagram\n", + "\t- javasrcClassByName\n", "\t- tableSchema\n", - "\t- javasrcList\n", - "\t- timeit, timeIt, time\n" + "\t- javasrcJavadoc\n", + "\t- pom, loadFromPOM\n", + "\t- mycompile\n", + "\t- rdbmsSchema\n", + "\t- javasrcMethodByName\n" ] } ], @@ -349,7 +350,13 @@ "name": "stdout", "output_type": "stream", "text": [ - "Bob age=30\n", + "Bob age=30\n" + ] + }, + { + "name": "stdout", + "output_type": "stream", + "text": [ "LombokPerson(name=Bob, age=30)\n" ] } @@ -1698,8 +1705,8 @@ "name": "stdout", "output_type": "stream", "text": [ - "samples: [22505238, 24402791, 22688366, 20435323, 20365883]\n", - "min=20365883 median=22505238 avg=22079520,20 max=24402791 (nanoseconds)\n" + "samples: [30675184, 31626125, 57277544, 56011050, 58324369]\n", + "min=30675184 median=56011050 avg=46782854,40 max=58324369 (nanoseconds)\n" ] } ], @@ -1813,10 +1820,10 @@ { "data": { "image/svg+xml": [ - "10002000300040005000600070008000900010000nBenchmark sweep: n0,002,204,406,618,8111,0111,019,178,777,479,998,636,677,336,907,5910,5010,917,608,8010,607,838,179,509,246,98// HashMap implementation// TreeMap implementationaveraged over 10 iterations (warmup=1)" + "10002000300040005000600070008000900010000nBenchmark sweep: n0,003,627,2510,8714,5018,1218,1211,8711,5011,2010,9812,4811,0710,0410,4215,0312,2410,6110,2513,7312,9115,6911,6810,4011,9312,04// HashMap implementation// TreeMap implementationaveraged over 10 iterations (warmup=1)" ], "text/plain": [ - "10002000300040005000600070008000900010000nBenchmark sweep: n0,002,204,406,618,8111,0111,019,178,777,479,998,636,677,336,907,5910,5010,917,608,8010,607,838,179,509,246,98// HashMap implementation// TreeMap implementationaveraged over 10 iterations (warmup=1)" + "10002000300040005000600070008000900010000nBenchmark sweep: n0,003,627,2510,8714,5018,1218,1211,8711,5011,2010,9812,4811,0710,0410,4215,0312,2410,6110,2513,7312,9115,6911,6810,4011,9312,04// HashMap implementation// TreeMap implementationaveraged over 10 iterations (warmup=1)" ] }, "metadata": {}, @@ -2037,6 +2044,142 @@ "source": [ "%%classDiagram java.util.ArrayList --svg --ancestors --exclude-inherited" ] + }, + { + "cell_type": "markdown", + "id": "ac027e90", + "metadata": {}, + "source": [ + "## Git graph (Mermaid)\n", + "\n", + "Demonstrates the `%git-graph-mermaid` magic which emits Mermaid diagram source compatible with Quarto. Use `--format=gitGraph` for Mermaid's `gitGraph` syntax. Use `--render` to attempt local SVG rendering via `mmdc` (mermaid-cli), if installed." + ] + }, + { + "cell_type": "code", + "execution_count": 52, + "id": "0b8d66ac", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Initialized empty Git repository in /tmp/ijava-git-demo/.git/\n" + ] + }, + { + "name": "stdout", + "output_type": "stream", + "text": [ + "[main (root-commit) 354a0b6] feat(demo): add file1\n", + " 1 file changed, 1 insertion(+)\n", + " create mode 100644 file1.txt\n", + "[main 0054e8b] feat(demo): add file2\n", + " 1 file changed, 1 insertion(+)\n", + " create mode 100644 file2.txt\n", + "/tmp/ijava-git-demo\n" + ] + } + ], + "source": [ + "%%shell\n", + "set -e\n", + "DEMO_REPO=/tmp/ijava-git-demo\n", + "rm -rf \"$DEMO_REPO\"\n", + "mkdir -p \"$DEMO_REPO\"\n", + "cd \"$DEMO_REPO\"\n", + "git init -b main .\n", + "echo 'hello file1' > file1.txt\n", + "git add file1.txt\n", + "git commit -m 'feat(demo): add file1'\n", + "echo 'another file' > file2.txt\n", + "git add file2.txt\n", + "git commit -m 'feat(demo): add file2'\n", + "echo \"$DEMO_REPO\"" + ] + }, + { + "cell_type": "code", + "execution_count": 53, + "id": "c745a501", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "image/svg+xml": [ + "

0054e8b feat(demo): add file2

354a0b6 feat(demo): add file1

" + ], + "text/plain": [ + "

0054e8b feat(demo): add file2

354a0b6 feat(demo): add file1

" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%git-graph-mermaid --repo=/tmp/ijava-git-demo --max=50 --format=gitGraph --render" + ] + }, + { + "cell_type": "code", + "execution_count": 54, + "id": "aa3a6003", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "data": { + "text/markdown": [ + "```{mermaid}\\ngitGraph\\n branch main\\n checkout main\\n commit id: \"0054e8b 0054e8b feat(demo): add file2\"\\n commit id: \"354a0b6 354a0b6 feat(demo): add file1\"\\n```\\n" + ], + "text/plain": [ + "```{mermaid}\\ngitGraph\\n branch main\\n checkout main\\n commit id: \"0054e8b 0054e8b feat(demo): add file2\"\\n commit id: \"354a0b6 354a0b6 feat(demo): add file1\"\\n```\\n" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "%git-graph-mermaid --repo=/tmp/ijava-git-demo --max=50 --format=gitGraph" + ] + }, + { + "cell_type": "code", + "execution_count": 55, + "id": "1b58d6ee", + "metadata": { + "vscode": { + "languageId": "java" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "cleaned up /tmp/ijava-git-demo\n" + ] + } + ], + "source": [ + "%%shell\n", + "rm -rf /tmp/ijava-git-demo || true\n", + "echo 'cleaned up /tmp/ijava-git-demo'" + ] } ], "metadata": { diff --git a/src/main/java/io/github/spencerpark/ijava/JavaKernel.java b/src/main/java/io/github/spencerpark/ijava/JavaKernel.java index 8bfecec..beb377e 100644 --- a/src/main/java/io/github/spencerpark/ijava/JavaKernel.java +++ b/src/main/java/io/github/spencerpark/ijava/JavaKernel.java @@ -129,6 +129,7 @@ public JavaKernel() { magics.registerMagics(new JavaPlantUMLMagics()); magics.registerMagics(new ClassDiagramMagics()); magics.registerMagics(new TableSchemaMagics()); + magics.registerMagics(new GitMermaidMagics()); // Consolidated shell magics: `MyShellMagics` removed, use `ShellMagics` only. magics.registerMagics(new ShellMagics()); try { diff --git a/src/main/java/io/github/spencerpark/ijava/magics/GitMermaidMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/GitMermaidMagics.java new file mode 100644 index 0000000..b308724 --- /dev/null +++ b/src/main/java/io/github/spencerpark/ijava/magics/GitMermaidMagics.java @@ -0,0 +1,276 @@ +package io.github.spencerpark.ijava.magics; + +import io.github.spencerpark.ijava.runtime.Display; +import io.github.spencerpark.jupyter.kernel.magic.registry.LineMagic; + +import java.io.*; +import java.nio.file.Files; +import java.util.*; + +/** + * Magic to generate Mermaid diagrams from the current Git repository. + * + * Usage examples: + * %git-graph-mermaid --max=50 --branch=main + * %git-graph-mermaid --max=100 --render + */ +public class GitMermaidMagics { + + @LineMagic("git-graph-mermaid") + public void gitGraphMermaid(List args) { + int max = 50; + String branch = null; + boolean render = false; + String format = "flowchart"; // or "gitGraph" + String repo = null; // optional --repo=path + + if (args != null) { + for (String a : args) { + if (a == null) continue; + if (a.startsWith("--max=")) { + try { max = Integer.parseInt(a.substring("--max=".length())); } catch (NumberFormatException ignored) {} + } else if (a.startsWith("--branch=")) { + branch = a.substring("--branch=".length()); + } else if (a.equals("--render")) { + render = true; + } else if (a.startsWith("--format=")) { + format = a.substring("--format=".length()); + } else if (a.startsWith("--repo=")) { + repo = a.substring("--repo=".length()); + } + } + } + + // Build git log command + List cmd = new ArrayList<>(); + cmd.add("git"); + if (repo != null) { cmd.add("-C"); cmd.add(repo); } + cmd.add("log"); + cmd.add("--pretty=format:%H%x01%h%x01%P%x01%D%x01%s"); + cmd.add("-n"); cmd.add(Integer.toString(max)); + if (branch != null) cmd.add(branch); + + String out; + try { + out = runCommand(cmd); + } catch (IOException | InterruptedException e) { + Display.display("Failed to run git: " + e.getMessage(), "text/plain"); + return; + } + + if (out == null || out.isBlank()) { + Display.display("No commits found or not a git repository.", "text/plain"); + return; + } + + // Parse lines: fullhashshorthashparentsdecorationssubject + Map labelByShort = new LinkedHashMap<>(); + Map> edges = new LinkedHashMap<>(); + Map> decoByShort = new HashMap<>(); + + for (String line : out.split("\n")) { + String[] parts = line.split("\u0001", 5); + if (parts.length < 5) continue; + String full = parts[0].trim(); + String shortH = parts[1].trim(); + String parents = parts[2].trim(); + String decos = parts[3].trim(); + String subj = parts[4].trim(); + + String label = shortH + " "; + if (!subj.isEmpty()) label += subj; + labelByShort.put(shortH, label); + + if (!edges.containsKey(shortH)) edges.put(shortH, new LinkedHashSet<>()); + if (!parents.isEmpty()) { + for (String p : parents.split(" ")) { + if (p.isBlank()) continue; + String ps = p.substring(0, Math.min(7, p.length())); + edges.get(shortH).add(ps); + } + } + + // parse decorations to detect branch names + if (!decos.isEmpty()) { + List names = new ArrayList<>(); + for (String tok : decos.split(",")) { + tok = tok.trim(); + if (tok.isEmpty()) continue; + // examples: "HEAD -> main" or "origin/main" or "tag: v1.0" + if (tok.contains("->")) { + String[] sp = tok.split("->"); + String candidate = sp[1].trim(); + if (!candidate.startsWith("tag:")) names.add(candidate.replaceAll("^origin/", "")); + } else if (tok.startsWith("tag:")) { + // skip tags + } else { + names.add(tok.replaceAll("^origin/", "")); + } + } + if (!names.isEmpty()) decoByShort.put(shortH, names); + } + } + + // Build Mermaid content depending on format + StringBuilder m = new StringBuilder(); + if ("gitGraph".equalsIgnoreCase(format)) { + m.append("```{mermaid}\\n"); + m.append("gitGraph\\n"); + + Set declaredBranches = new HashSet<>(); + String currentBranch = null; + Map commitPrimaryBranch = new HashMap<>(); + + for (Map.Entry e : labelByShort.entrySet()) { + String shortH = e.getKey(); + String label = escapeForMermaid(e.getValue()); + + List branches = decoByShort.get(shortH); + String primary = null; + if (branches != null && !branches.isEmpty()) { + // choose first decoration as primary branch + primary = branches.get(0); + // declare any unseen branches + for (String b : branches) { + if (!declaredBranches.contains(b)) { + m.append(" branch ").append(safeName(b)).append("\\n"); + declaredBranches.add(b); + } + } + } + + // checkout primary if needed + if (primary != null) { + if (!Objects.equals(currentBranch, primary)) { + m.append(" checkout ").append(safeName(primary)).append("\\n"); + currentBranch = primary; + } + commitPrimaryBranch.put(shortH, primary); + } else { + // ensure there is a branch to commit to + if (currentBranch == null) { + // create an anonymous branch + String anon = "main"; + if (!declaredBranches.contains(anon)) { + m.append(" branch ").append(anon).append("\\n"); + declaredBranches.add(anon); + } + m.append(" checkout ").append(anon).append("\\n"); + currentBranch = anon; + } + } + + m.append(" commit id: \"").append(shortH).append(" ").append(label).append("\"\\n"); + + // handle merges: if multiple parents, try to emit merge commands + Set parents = edges.getOrDefault(shortH, Collections.emptySet()); + if (parents.size() > 1) { + // skip the first parent (assumed main); for each additional try to find branch name + boolean first = true; + for (String p : parents) { + if (first) { first = false; continue; } + String pbranch = commitPrimaryBranch.get(p); + if (pbranch == null) { + List pb = decoByShort.get(p); + if (pb != null && !pb.isEmpty()) pbranch = pb.get(0); + } + if (pbranch != null) { + m.append(" merge ").append(safeName(pbranch)).append("\\n"); + } + } + } + } + + m.append("```\\n"); + } else { + m.append("```{mermaid}\\n"); + m.append("flowchart TD\\n"); + + // Nodes + for (Map.Entry e : labelByShort.entrySet()) { + String id = "c" + e.getKey(); + String label = escapeForMermaid(e.getValue()); + m.append(id).append("[\\\"").append(label).append("\\\"]\\n"); + } + + // Edges + for (Map.Entry> e : edges.entrySet()) { + String fromId = "c" + e.getKey(); + for (String p : e.getValue()) { + String toId = "c" + p; + m.append(fromId).append(" --> ").append(toId).append("\\n"); + } + } + + m.append("```\\n"); + } + + String mermaidBlock = m.toString(); + + if (!render) { + Display.display(mermaidBlock, "text/markdown"); + return; + } + + // Attempt to render via mmdc if requested + try { + File tmpMmd = Files.createTempFile("git-graph-", ".mmd").toFile(); + File outSvg = Files.createTempFile("git-graph-", ".svg").toFile(); + // write mermaid source without fences + StringBuilder raw = new StringBuilder(); + raw.append("flowchart TD\n"); + for (Map.Entry e : labelByShort.entrySet()) { + raw.append("c").append(e.getKey()).append("[\"").append(escapeForMermaid(e.getValue())).append("\"]\n"); + } + for (Map.Entry> e : edges.entrySet()) { + for (String p : e.getValue()) { + raw.append("c").append(e.getKey()).append(" --> c").append(p).append("\n"); + } + } + Files.writeString(tmpMmd.toPath(), raw.toString()); + + List renderCmd = new ArrayList<>(); + renderCmd.add("mmdc"); + renderCmd.add("-i"); renderCmd.add(tmpMmd.getAbsolutePath()); + renderCmd.add("-o"); renderCmd.add(outSvg.getAbsolutePath()); + + String rc = runCommand(renderCmd); + if (outSvg.exists()) { + String svg = Files.readString(outSvg.toPath()); + Display.display(svg, "image/svg+xml"); + tmpMmd.delete(); outSvg.delete(); + return; + } else { + Display.display(mermaidBlock + "\n\n(Note: failed to render with mmdc; ensure mermaid-cli is installed)", "text/markdown"); + tmpMmd.delete(); + return; + } + } catch (Throwable t) { + Display.display(mermaidBlock + "\n\n(Note: rendering failed: " + t.getMessage() + ")", "text/markdown"); + } + } + + private static String runCommand(List cmd) throws IOException, InterruptedException { + ProcessBuilder pb = new ProcessBuilder(cmd); + pb.redirectErrorStream(true); + Process p = pb.start(); + try (InputStreamReader isr = new InputStreamReader(p.getInputStream()); BufferedReader br = new BufferedReader(isr)) { + StringBuilder out = new StringBuilder(); + String line; + while ((line = br.readLine()) != null) out.append(line).append('\n'); + p.waitFor(); + return out.toString(); + } + } + + private static String escapeForMermaid(String s) { + if (s == null) return ""; + return s.replace("\"", "\\\"").replace("[", "(").replace("]", ")"); + } + private static String safeName(String s) { + if (s == null) return "branch"; + return s.replaceAll("[^A-Za-z0-9_\\-]", "_"); + } + +} + From 4ff77a242373f765dde09b995688444bf5d54cf8 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Wed, 26 Aug 2026 11:07:29 +0200 Subject: [PATCH 30/49] fix(demo): improve demo --- notebooks/magics_demo.ipynb | 332 ++++++------------------------------ 1 file changed, 56 insertions(+), 276 deletions(-) diff --git a/notebooks/magics_demo.ipynb b/notebooks/magics_demo.ipynb index 57912c5..5bdb78e 100644 --- a/notebooks/magics_demo.ipynb +++ b/notebooks/magics_demo.ipynb @@ -12,11 +12,7 @@ "cell_type": "code", "execution_count": 1, "id": "87360ba5", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -80,11 +76,7 @@ "cell_type": "code", "execution_count": 2, "id": "d5ae9350", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -105,11 +97,7 @@ "cell_type": "code", "execution_count": 3, "id": "1c4668b6", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -138,11 +126,7 @@ "cell_type": "code", "execution_count": 4, "id": "e5e10708", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -164,11 +148,7 @@ "cell_type": "code", "execution_count": 5, "id": "4f6628be", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -201,11 +181,7 @@ "cell_type": "code", "execution_count": 6, "id": "3606b844", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "%maven org.projectlombok:lombok:1.18.42" @@ -215,11 +191,7 @@ "cell_type": "code", "execution_count": 7, "id": "c14e858c", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -266,11 +238,7 @@ "cell_type": "code", "execution_count": 8, "id": "f15afeff", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "%%compile --class=com.example.demo.Hello --output=out\n", @@ -292,11 +260,7 @@ "cell_type": "code", "execution_count": 9, "id": "237d7c9b", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -317,11 +281,7 @@ "cell_type": "code", "execution_count": 10, "id": "0481b2b2", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "%%compile --class=com.example.demo.LombokPerson --output=out --processor-path=/var/home/bruno/.m2/repository/org/projectlombok/lombok/1.18.42/lombok-1.18.42.jar --classpath=/var/home/bruno/.m2/repository/org/projectlombok/lombok/1.18.42/lombok-1.18.42.jar\n", @@ -340,11 +300,7 @@ "cell_type": "code", "execution_count": 11, "id": "f7128d07", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -380,11 +336,7 @@ "cell_type": "code", "execution_count": 12, "id": "4968d01a", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -426,11 +378,7 @@ "cell_type": "code", "execution_count": 13, "id": "05391c3a", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -455,11 +403,7 @@ "cell_type": "code", "execution_count": 14, "id": "2f994624", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -488,11 +432,7 @@ "cell_type": "code", "execution_count": 15, "id": "63f2121b", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -522,11 +462,7 @@ "cell_type": "code", "execution_count": 16, "id": "e4cd33c7", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "%maven com.h2database:h2:2.4.240" @@ -536,11 +472,7 @@ "cell_type": "code", "execution_count": 17, "id": "18c47637", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "System.setProperty(\"jdbc.url\", \"jdbc:h2:mem:test;DB_CLOSE_DELAY=-1\");\n", @@ -552,11 +484,7 @@ "cell_type": "code", "execution_count": 18, "id": "2b08450b", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "%%sqlAsTable --help" @@ -566,11 +494,7 @@ "cell_type": "code", "execution_count": 19, "id": "020dddda", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -781,11 +705,7 @@ "cell_type": "code", "execution_count": 20, "id": "b2d60553", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -807,11 +727,7 @@ "cell_type": "code", "execution_count": 21, "id": "83570636", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -839,11 +755,7 @@ "cell_type": "code", "execution_count": 22, "id": "e272026f", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -869,11 +781,7 @@ "cell_type": "code", "execution_count": 23, "id": "31d809c0", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -952,11 +860,7 @@ "cell_type": "code", "execution_count": 24, "id": "7c5ead4d", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1025,11 +929,7 @@ "cell_type": "code", "execution_count": 25, "id": "db0eea00", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1104,11 +1004,7 @@ "cell_type": "code", "execution_count": 26, "id": "fcac85a3", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1142,11 +1038,7 @@ "cell_type": "code", "execution_count": 27, "id": "fe2f0039", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1173,11 +1065,7 @@ "cell_type": "code", "execution_count": 28, "id": "c04b48ea", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1235,11 +1123,7 @@ "cell_type": "code", "execution_count": 29, "id": "33a64ebb", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1284,11 +1168,7 @@ "cell_type": "code", "execution_count": 30, "id": "0898c655", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1332,11 +1212,7 @@ "cell_type": "code", "execution_count": 31, "id": "d471c6f9", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1363,11 +1239,7 @@ "cell_type": "code", "execution_count": 32, "id": "6b425967", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1401,11 +1273,7 @@ "cell_type": "code", "execution_count": 33, "id": "f56fa36e", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1432,11 +1300,7 @@ "cell_type": "code", "execution_count": 34, "id": "82e2cfbb", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1492,11 +1356,7 @@ "cell_type": "code", "execution_count": 35, "id": "11d6e07e", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1523,11 +1383,7 @@ "cell_type": "code", "execution_count": 36, "id": "f51da0ac", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1563,11 +1419,7 @@ "cell_type": "code", "execution_count": 37, "id": "0de30e18", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1594,11 +1446,7 @@ "cell_type": "code", "execution_count": 38, "id": "ee9cb95d", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1626,11 +1474,7 @@ "cell_type": "code", "execution_count": 39, "id": "e70d0cee", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1669,11 +1513,7 @@ "cell_type": "code", "execution_count": 40, "id": "a9482ebf", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -1695,11 +1535,7 @@ "cell_type": "code", "execution_count": 41, "id": "aea54b0e", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -1732,11 +1568,7 @@ "cell_type": "code", "execution_count": 42, "id": "117a9618", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -1763,11 +1595,7 @@ "cell_type": "code", "execution_count": 43, "id": "f25a7a92", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "// Helper: run a Supplier-driven test and return accumulated result\n", @@ -1811,11 +1639,7 @@ "cell_type": "code", "execution_count": 44, "id": "5a7f5050", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -1855,11 +1679,7 @@ "cell_type": "code", "execution_count": 45, "id": "99467b83", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -1925,11 +1745,7 @@ "cell_type": "code", "execution_count": 46, "id": "f01b8759", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -1948,11 +1764,7 @@ "cell_type": "code", "execution_count": 47, "id": "59d54da7", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "%%compile --class=com.example.demo.C --output=out\n", @@ -1966,11 +1778,7 @@ "cell_type": "code", "execution_count": 48, "id": "d49e214a", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "%%compile --class=com.example.demo.A --output=out\n", @@ -1983,11 +1791,7 @@ "cell_type": "code", "execution_count": 49, "id": "21bc5030", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [], "source": [ "%%compile --class=com.example.demo.B --output=out\n", @@ -2000,11 +1804,7 @@ "cell_type": "code", "execution_count": 50, "id": "e6e614c6", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -2022,11 +1822,7 @@ "cell_type": "code", "execution_count": 51, "id": "317ff290", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -2059,11 +1855,7 @@ "cell_type": "code", "execution_count": 52, "id": "0b8d66ac", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -2107,11 +1899,7 @@ "cell_type": "code", "execution_count": 53, "id": "c745a501", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -2134,11 +1922,7 @@ "cell_type": "code", "execution_count": 54, "id": "aa3a6003", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "data": { @@ -2161,11 +1945,7 @@ "cell_type": "code", "execution_count": 55, "id": "1b58d6ee", - "metadata": { - "vscode": { - "languageId": "java" - } - }, + "metadata": {}, "outputs": [ { "name": "stdout", @@ -2192,7 +1972,7 @@ "codemirror_mode": "java", "file_extension": ".jshell", "mimetype": "text/x-java-source", - "name": "Java", + "name": "java", "pygments_lexer": "java", "version": "25.0.1+8-LTS" } From 1a43c2e9f238f5d5cb97b5c9367abed86b065838 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Wed, 2 Sep 2026 07:25:16 +0200 Subject: [PATCH 31/49] chore: workspace hygiene, license sweep, docs, and 60s default timeout Apply the pre-audit workspace changes: license header sweep to ebpro, move audit docs into docs/, drop notebooks/out artifacts and the stray build copy.gradle, document magics, set the 60s default statement timeout, and add the SOTA 2026 audit plan (docs/UPGRADE-2026.md). --- .gitignore | 7 + README.md | 25 +- build copy.gradle | 165 ------- .../MAGICS_AUDIT_AND_IMPROVEMENT_PLAN.md | 0 .../MAGICS_CONSOLIDATION_SUMMARY.md | 0 docs/UPGRADE-2026.md | 467 ++++++++++++++++++ docs/magics.md | 174 ++++++- notebooks/out/com/example/demo/A.class | Bin 219 -> 0 bytes notebooks/out/com/example/demo/B.class | Bin 195 -> 0 bytes notebooks/out/com/example/demo/C.class | Bin 176 -> 0 bytes notebooks/out/com/example/demo/Hello.class | Bin 304 -> 0 bytes .../out/com/example/demo/LombokPerson.class | Bin 1717 -> 0 bytes notebooks/out/src/com/example/demo/A.java | 3 - notebooks/out/src/com/example/demo/B.java | 3 - notebooks/out/src/com/example/demo/C.java | 4 - notebooks/out/src/com/example/demo/Hello.java | 4 - .../src/com/example/demo/LombokPerson.java | 9 - .../io/github/spencerpark/ijava/IJava.java | 2 +- .../github/spencerpark/ijava/JavaKernel.java | 4 +- .../ijava/execution/CodeEvaluator.java | 2 +- .../ijava/execution/CodeEvaluatorBuilder.java | 2 +- .../ijava/execution/CompilationException.java | 2 +- .../EvaluationInterruptedException.java | 2 +- .../execution/EvaluationTimeoutException.java | 2 +- .../execution/IJavaExecutionControl.java | 2 +- .../IJavaExecutionControlProvider.java | 14 +- .../execution/IncompleteSourceException.java | 2 +- .../execution/LazyInputStreamDelegate.java | 2 +- .../execution/LazyOutputStreamDelegate.java | 2 +- .../execution/MagicsSourceTransformer.java | 2 +- .../ijava/magics/BenchmarkMagics.java | 6 +- .../ijava/magics/ClasspathMagics.java | 2 +- .../ijava/magics/CompilerMagics.java | 2 +- .../spencerpark/ijava/magics/MagicsTool.java | 2 +- .../ijava/magics/MavenResolver.java | 2 +- .../ijava/magics/PrinterMagics.java | 2 +- .../spencerpark/ijava/magics/ShellMagics.java | 2 +- .../ijava/magics/TimeItMagics.java | 2 +- .../spencerpark/ijava/runtime/Display.java | 2 +- .../spencerpark/ijava/runtime/Kernel.java | 2 +- .../spencerpark/ijava/runtime/Magics.java | 2 +- .../spencerpark/ijava/utils/FileUtils.java | 2 +- .../ijava/utils/ResolveDependency.java | 2 +- .../ijava/utils/RuntimeCompiler.java | 2 +- .../jupyter/kernel/util/StringStyler.java | 2 +- .../jupyter/kernel/util/TextColor.java | 2 +- src/main/resources/print.jshell | 2 +- 47 files changed, 707 insertions(+), 232 deletions(-) delete mode 100644 build copy.gradle rename MAGICS_AUDIT_AND_IMPROVEMENT_PLAN.md => docs/MAGICS_AUDIT_AND_IMPROVEMENT_PLAN.md (100%) rename MAGICS_CONSOLIDATION_SUMMARY.md => docs/MAGICS_CONSOLIDATION_SUMMARY.md (100%) create mode 100644 docs/UPGRADE-2026.md delete mode 100644 notebooks/out/com/example/demo/A.class delete mode 100644 notebooks/out/com/example/demo/B.class delete mode 100644 notebooks/out/com/example/demo/C.class delete mode 100644 notebooks/out/com/example/demo/Hello.class delete mode 100644 notebooks/out/com/example/demo/LombokPerson.class delete mode 100644 notebooks/out/src/com/example/demo/A.java delete mode 100644 notebooks/out/src/com/example/demo/B.java delete mode 100644 notebooks/out/src/com/example/demo/C.java delete mode 100644 notebooks/out/src/com/example/demo/Hello.java delete mode 100644 notebooks/out/src/com/example/demo/LombokPerson.java diff --git a/.gitignore b/.gitignore index 50815cf..b793267 100644 --- a/.gitignore +++ b/.gitignore @@ -21,3 +21,10 @@ tests/ .envrc .use-google-ai + +# Eclipse +.classpath +.factorypath +.project +.settings/ +bin/ diff --git a/README.md b/README.md index 7130ad1..2adcf89 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,16 @@ features and magics: ![r-w](docs/img/write-cell-magic.png) * add `cmd` line magic ![cmd](docs/img/cmd-line-magic.png) +* add `benchmark` cell magic (compare implementations, SVG chart) +* add `rdbmsSchema` / `sqlAsTable` / `tableSchema` magics (JDBC-backed schema diagrams and queries) +* add `classDiagram` magic (UML class diagrams via PlantUML) +* add `git-graph-mermaid` line magic (Mermaid git graph of the current repo) +* add `shell` / `commonshell` magics (one-shot and persistent shell sessions) +* add `where`, `class-info`, `javadoc-html`, `reload-class`, `classpath-snapshot` line magics +* add `javasrc*` cell magics (source extraction via JavaParser) +* default statement timeout of 60 seconds for teaching use (disable with `IJAVA_TIMEOUT=-1`) + +See [docs/magics.md](docs/magics.md) for the full magic reference. [//]: # ([![badge](https://img.shields.io/badge/launch-binder-E66581.svg?logo=data:image/png;base64,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)](https://mybinder.org/v2/gh/SpencerPark/ijava-binder/master) [![badge](https://img.shields.io/badge/launch-binder%20lab-579ACA.svg?logo=data:image/png;base64,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)](https://mybinder.org/v2/gh/SpencerPark/ijava-binder/master?urlpath=lab)) @@ -85,17 +95,14 @@ Currently the kernel supports ### Requirements -1. ~~[Java JDK >= 9](http://www.oracle.com/technetwork/java/javase/downloads/index.html). **Not the JRE**. Java 12 is - the current release and should be considered if selecting a version but if a java 9, 10, or 11 build is installed, - everything _should_ still be working - fine.~~[Java JDK >= 17](http://www.oracle.com/technetwork/java/javase/downloads/index.html). **Not the JRE**. +1. [Java JDK >= 21](http://www.oracle.com/technetwork/java/javase/downloads/index.html). **Not the JRE**. - 1. Ensure that the `java` command is in the PATH and is using version 9. For example: + 1. Ensure that the `java` command is in the PATH and is using a modern version. For example: ```bash > java -version - java version "17.0.2" 2022-01-18 LTS - Java(TM) SE Runtime Environment (build 17.0.2+8-LTS-86) - Java HotSpot(TM) 64-Bit Server VM (build 17.0.2+8-LTS-86, mixed mode, sharing) + openjdk version "21.0.11" 2026-04-21 + OpenJDK Runtime Environment Temurin-21.0.11+10 (build 21.0.11+10) + OpenJDK 64-Bit Server VM Temurin-21.0.11+10 (build 21.0.11+10, mixed mode, sharing) ``` 2. Next ensure that `java` is in a location where the jdk was installed and not just the jre. Use @@ -185,7 +192,7 @@ or `gradlew installKernel --param ...:...`) should use the names in the _Paramet | Environment variable | Parameter name | Default | Description | |----------------------|----------------|---------|-------------| | `IJAVA_COMPILER_OPTS` | `comp-opts` | `""` | A space delimited list of command line options that would be passed to the `javac` command when compiling a project. For example `-parameters` to enable retaining parameter names for reflection. | -| `IJAVA_TIMEOUT` | `timeout` | `"-1"` | A duration specifying a timeout (in milliseconds by default) for a _single top level statement_. If less than `1` then there is no timeout. If desired a time may be specified with a [`TimeUnit`](https://docs.oracle.com/javase/9/docs/api/java/util/concurrent/TimeUnit.html) may be given following the duration number (ex `"30 SECONDS"`). | +| `IJAVA_TIMEOUT` | `timeout` | `"60 SECONDS"` | A duration specifying a timeout for a _single top level statement_. The default of 60 seconds suits teaching use, where a runaway statement should not hang the kernel. Set `"-1"` to disable the timeout. If desired a time may be specified with a [`TimeUnit`](https://docs.oracle.com/javase/9/docs/api/java/util/concurrent/TimeUnit.html) may be given following the duration number (ex `"30 SECONDS"`). | | `IJAVA_CLASSPATH` | `classpath` | `""` | A file path separator delimited list of classpath entries that should be available to the user code. **Important:** no matter what OS, this should use forward slash "/" as the file separator. Also each path may actually be a [simple glob](#simple-glob-syntax). | | `IJAVA_STARTUP_SCRIPTS_PATH` | `startup-scripts-path` | `""` | A file path seperator delimited list of `.jshell` scripts to run on startup. This includes [ijava-jshell-init.jshell](src/main/resources/ijava-jshell-init.jshell) and [ijava-display-init.jshell](src/main/resources/ijava-display-init.jshell). **Important:** no matter what OS, this should use forward slash "/" as the file separator. Also each path may actually be a [simple glob](#simple-glob-syntax). | | `IJAVA_STARTUP_SCRIPT` | `startup-script` | `""` | A block of java code to run when the kernel starts up. This may be something like `import my.utils;` to setup some default imports or even `void sleep(long time) { try {Thread.sleep(time); } catch (InterruptedException e) { throw new RuntimeException(e); }}` to declare a default utility method to use in the notebook. | diff --git a/build copy.gradle b/build copy.gradle deleted file mode 100644 index 154e20f..0000000 --- a/build copy.gradle +++ /dev/null @@ -1,165 +0,0 @@ -import com.github.jk1.license.filter.LicenseBundleNormalizer -import com.github.jk1.license.render.InventoryHtmlReportRenderer -import com.github.jk1.license.render.JsonReportRenderer -import org.apache.tools.ant.filters.ReplaceTokens - - -plugins { - id 'java-library' - // id 'maven-publish' // use johnrengelman.shadow instead - id 'com.github.hierynomus.license' version '0.16.1' - id "com.github.jk1.dependency-license-report" version "2.1" - id 'com.github.johnrengelman.shadow' version '7.1.2' -// id 'io.github.spencerpark.jupyter-kernel-installer' version '2.1.0' -} - -group = 'io.github.spencerpark' -version = '1.4.4' - -repositories { - mavenLocal() - mavenCentral() - maven { - url = 'https://oss.sonatype.org/content/repositories/snapshots/' - } -} - -dependencies { - implementation('io.github.spencerpark:jupyter-jvm-basekernel:2.3.0') { - exclude group: 'com.google.code.gson', module: 'gson' - } - implementation 'com.google.code.gson:gson:2.10' - - // ------ for maven resolve and download ------ - // implementation 'org.apache.maven:maven-resolver-provider:4.0.0-alpha-2' - implementation('org.apache.maven:maven-resolver-provider:3.8.6') { - exclude group: 'org.apache.maven.resolver' // manual include 1.8.2 - } - implementation 'org.apache.maven.resolver:maven-resolver-impl:1.8.2' - implementation 'org.apache.maven.resolver:maven-resolver-connector-basic:1.8.2' - implementation 'org.apache.maven.resolver:maven-resolver-transport-file:1.8.2' - implementation 'org.apache.maven.resolver:maven-resolver-transport-http:1.8.2' - implementation 'org.apache.maven.resolver:maven-resolver-transport-classpath:1.8.2' - // ------ for maven resolve and download ------ - - //implementation 'org.apache.logging.log4j:log4j-core:2.19.0' - implementation 'ch.qos.logback:logback-classic:1.5.7' - - testImplementation group: 'junit', name: 'junit', version: '4.13.2' -} - -// Add the license header to source files -license { - header = file('LICENSE') - include "**/*.java" - exclude "**/Test*.java" - mapping java: 'SLASHSTAR_STYLE' - ext.year = Calendar.getInstance().get(Calendar.YEAR) -} -licenseMain.dependsOn 'licenseFormat' - -// replace @symbol@ in properties -processResources { - def tokens = [ - 'version': project.version, - 'project': project.name - ] - inputs.properties(tokens) - filter tokens: tokens, ReplaceTokens -} - -//java { -// withJavadocJar() -// withSourcesJar() -//} - -compileJava { - options.compilerArgs << '-parameters' - // ignore deprecation for jupyter-jvm-basekernel gson JsonParser api -// options.compilerArgs << '-Xlint:all' << '-Xlint:-deprecation' << '-Xlint:-rawtypes' << '-Xlint:-serial' -} - -jar { - manifest { - attributes 'Main-class': 'io.github.spencerpark.ijava.IJava' - } -} - -// shadow Jar config -shadowJar { - // inherit from the manifest of the standard jar task - // manifest { - // attributes 'Main-class': 'io.github.spencerpark.ijava.IJava' - // } - - // copy build.gradle to shadowed jar - from("./") { - include 'build.gradle' - } -} -build.dependsOn 'shadowJar' - -// publish -//publishing { -// publications { -// shadow(MavenPublication) { publication -> -// project.shadow.component(publication) -// } -// } -// repositories { -// maven { -// url "http://repo.myorg.com" -// } -// } -//} - -// create license report -licenseReport { - renderers = [ - new InventoryHtmlReportRenderer('license-report.html'), - new JsonReportRenderer('license-report.json') - ] - - filters = [new LicenseBundleNormalizer()] -} - -// pack up -tasks.register('packDist', Zip) { - archiveFileName = project.name + "-latest.zip" - - from(layout.buildDirectory.dir("resources/main")) { - include "install.py" - } - - from(layout.buildDirectory.dir("libs")) { - include "*-all.jar" - into "java" - } - - from(layout.buildDirectory.dir("resources/main")) { - include "kernel.json" - into "java" - } - - from(layout.buildDirectory.dir("reports/dependency-license")) { - into "java/dependency-license" - } - - dependsOn generateLicenseReport - dependsOn build -} - -// execute task after build -//build.finalizedBy(packDist) - - -// Task to download dependencies -tasks.register('downloadDependencies') { - doLast { - configurations.all { configuration -> - if (configuration.canBeResolved) { - configuration.resolve() - } - } - } -} \ No newline at end of file diff --git a/MAGICS_AUDIT_AND_IMPROVEMENT_PLAN.md b/docs/MAGICS_AUDIT_AND_IMPROVEMENT_PLAN.md similarity index 100% rename from MAGICS_AUDIT_AND_IMPROVEMENT_PLAN.md rename to docs/MAGICS_AUDIT_AND_IMPROVEMENT_PLAN.md diff --git a/MAGICS_CONSOLIDATION_SUMMARY.md b/docs/MAGICS_CONSOLIDATION_SUMMARY.md similarity index 100% rename from MAGICS_CONSOLIDATION_SUMMARY.md rename to docs/MAGICS_CONSOLIDATION_SUMMARY.md diff --git a/docs/UPGRADE-2026.md b/docs/UPGRADE-2026.md new file mode 100644 index 0000000..6cf582f --- /dev/null +++ b/docs/UPGRADE-2026.md @@ -0,0 +1,467 @@ +# IJava 2026 Upgrade Plan — Deep Audit & SOTA Roadmap + +- Date: 2026-09-01 +- Branch: `feature/update2026` +- Audit scope: entire repository at `4ff77a2` + uncommitted `feature/update2026` work +- Legend: **[V]** = verified in code/artifacts during this audit · **[I]** = inferred recommendation + +--- + +## 1. Executive Summary + +IJava is a functional, feature-rich Jupyter kernel for the JVM (JShell-based), but in +2026 it lags SOTA in five areas: + +1. **Reliability** — statement timeouts leak threads (timed-out code keeps running in the + background), and a 2019-era ZMQ message loop serializes *all* message types behind + running cells, freezing completions/hover while a cell executes. +2. **Packaging correctness** — the shipped fat jar contains literal `@version@`/`@project@` + placeholders; `kernel_info`/banner report a bogus version, and the `kernel-metadata.json` + inside the jar belongs to the `jupyter-jvm-basekernel` dependency (2.3.0), so the banner + claims "implementation by jupyter-jvm-basekernel". +3. **Quality gates** — JUnit 4, ~580 lines of tests, no coverage gate, no lint/static + analysis, no dependency verification (commented out), and CI runs **only on tag push** + on a self-hosted runner — no PR checks, no JDK matrix. +4. **Security posture** — no sandboxing or isolation story, network-capable Maven resolver + with hardcoded remotes, process magics (`cmd`, `git-mermaid`) with unbounded execution + and a stream-deadlock bug, file-writing magics, no memory limits in `kernel.json`. +5. **Performance headroom** — JShell is fine as a default engine but per-statement + recompilation, per-compile classloader churn in the compile magic, deferred startup + script evaluation (first cell pays a startup penalty), and a fixed 50 ms loop sleep cap + responsiveness. Java 25 (LTS) features (virtual threads, structured concurrency, + ScopedValue) are unused; the build targets Java 21 only. + +The plan below is ordered as **P0 quick wins (≤ 1 day total)**, **P1 high-impact +(2–4 weeks)**, **P2 strategic (quarter+)**. It is designed so every item lands as a +separate reviewable branch/PR, with a validation gate at each step. + +**Headline recommendation:** keep JShell as the default execution engine (it is the right +default for a teaching/interactive kernel), put it behind a small engine SPI so a +JDT/Compiler-API incremental engine can be added without forking the user base, decouple +the message loop (fork/patch `jupyter-jvm-basekernel` 2.4.0), move the statement executor +to virtual threads with real cancellation, and add PR CI + coverage + dependency +verification before any feature work. + +--- + +## 2. Verified Current Architecture + +### 2.1 Process & protocol layer + +``` +jupyter (jupyter_client) + │ ZMQ: shell / control / stdin / iopub / heartbeat + ▼ +jupyter-jvm-basekernel 2.3.0 (external dep, same author) + ├─ JupyterConnection — ZMQ context, one shared handler map [V] + ├─ ShellChannel (shell + control) + │ └─ Loop thread: poll(0) → handler.handle(msg) inline → sleep 50 ms [V] + ├─ StdinChannel, IOPubChannel, HeartbeatChannel (each a Loop thread) [V] + └─ BaseKernel + ├─ becomeHandlerForConnection(): registers handlers for execute, inspect, + │ complete, is_complete, history, kernel_info, shutdown, interrupt, comm [V] + ├─ handleExecuteRequest() is `synchronized` [V] + └─ replaceOutputStreams() per execute: System.out/err/in → JupyterIO, + deferred restore after reply [V] + ▼ +io.github.spencerpark:ijava 1.4.5 + ├─ IJava.main() — reads ijava-kernel-metadata.json, binds connection, kernel.run() [V] + ├─ JavaKernel extends BaseKernel — registers 13 magic classes [V] + ├─ CodeEvaluator / CodeEvaluatorBuilder — JShell engine (lazy-init on first eval) [V] + ├─ IJavaExecutionControl (ExecutionControl SPI) — cached thread pool + timeout [V] + └─ magics/ — 13 magic classes, ~5,300 LOC [V] +``` + +Key facts (all [V]): + +- **Single handler map shared by shell and control channels** (`JupyterConnection.handlers`): + execute/complete/inspect/is_complete/history arrive on the *shell* channel loop thread; + interrupt arrives on the *control* channel loop thread — so interrupt stays responsive + while a cell runs, but **completions and hover queue behind the running cell**. +- **Loop sleeps 50 ms after every iteration** (`SHELL_DEFAULT_LOOP_SLEEP_MS = 50`, + `Loop.run()` sleeps unconditionally when `sleep > 0`): every message on an idle kernel + pays up to ~50 ms fixed latency; the sleep also runs after handling each message. +- **`handleExecuteRequest` is `synchronized`** on the kernel instance: cell execution is + serialized even though the loop could dispatch concurrently. +- **stdout capture** is a `PrintStream(jupyterOut, true)` (autoFlush → line-streamed to + iopub) swapped in only during `handleExecuteRequest` and restored afterwards + (`replaceOutputStreams`). Correct for the serialized single-cell flow; thread-unsafe by + design for anything else. +- **HMAC message signing** is implemented in basekernel (`HMACGenerator`) — protocol + auth is fine. +- **`kernel_info`/banner metadata** comes from `KERNEL_META` = `kernel-metadata.json`. + The fat jar contains the *basekernel dependency's* `kernel-metadata.json` + (`{"version":"2.3.0","project":"jupyter-jvm-basekernel"}`), so the banner's + "implementation by ..." line misreports the implementation. + +### 2.2 Execution engine (IJava-specific) + +- `JavaKernel` constructor builds the JShell engine eagerly + (`CodeEvaluatorBuilder.build()` → `JShell.builder().executionControl(...).build()`, + `CodeEvaluatorBuilder.java:206-214`) but **startup scripts are evaluated lazily on the + first `eval()`** (`CodeEvaluator.java:128-135`) — deliberately, to surface errors on the + first cell. Cost: the first cell pays the `ijava-jshell-init.jshell` + `print.jshell` + evaluation on top of a warm JVM. +- `eval(String, boolean)` path (`JavaKernel.java:316-343`): + - regex-based `%` magic transformation (`magicsTransformer`, 3 regexes, [V]); + - `COMMENT_PATTERNS` strip applied per eval ([V]); + - for `evalWithPrint`: **O(n) scan over every stored snippet** via `skip`/`reduce` + + `String.replaceAll` to append `printf` to the last non-blank line, and a linear + `lastIndexOf` to find the statement (`JavaKernel.java:327-340`) — degrades as the + session grows; + - `jshell.eval` then runs the statement. +- `complete(String)` (`JavaKernel.java:397-414`) calls `jshell.sourceCodeAnalysis` + (completion + import completion) **on the shell loop thread, per keystroke request**. +- `inspect(String)` (`JavaKernel.java:345-395`) calls `jshell.sourceCodeAnalysis` + (documentation) per hover, same thread. +- `interrupt()` (`JavaKernel.java:431-434`) delegates to + `IJavaExecutionControl.interrupt()` → `runningTasks` futures cancelled. + +### 2.3 Statement execution control + +`IJavaExecutionControl` (`IJavaExecutionControl.java`): + +- `newCachedThreadPool` with **non-daemon** threads (`:76`) — unbounded, one per + concurrent statement; +- `execute()` submits the statement to the pool and does + `future.get(timeout, unit)`; on `TimeoutException` it logs "Timed out" and returns — + **it never cancels the task**, so the user's code keeps running on a leaked thread, + holding its classloaders/allocations, and the next cell may interleave with it + (`:94-138`); +- `DEFAULT_TIMEOUT` is 60 s (changed on this branch from 120 s, + `IJavaExecutionControlProvider.java:55-56,73-74`), overridable via `IJAVA_TIMEOUT` / + `NO_TIMEOUT=-1` through `install.py` env mapping. + +### 2.4 Compile/resolve magics + +- `RuntimeCompiler` (used by the compile path): writes `.java` **relative to the CWD** + (`:68-70`), then per compile creates a **new `URLClassLoader` and closes it in + try-with-resources** (`:100-103`) — every `%compile`/`mycompile` cycle produces fresh + type identities (old instances keep the old loader alive), and the "already exists" + check consults a loader that no longer holds the classes. +- `JavaCompilerMagics` (the `compile` magic with a `CompilationContext`) is better + behaved: fixed workspace `~/.jupyter/java-workspace` (`:28`), explicit + `StandardLocation.CLASS_OUTPUT` (`:99-100`), writes sources under + `workspace/sources/` (`:140-163`) — but still one `JavaCompiler` task per call. +- `MavenResolver`: **hardcoded remote repositories** — central, repo1, sonatype releases + (`:61-69`); no offline mode, no proxy config, no user-specified mirror; `resolve(pomPath)` + reads an arbitrary local POM and resolves its dependency tree over the network. +- `MagicsTool.cmd`: `Runtime.getRuntime().exec(args)` (deprecated), **reads stdout fully + before stderr** (`:91-100`) — classic pipe-buffer deadlock if the child writes >64 KB to + stderr before finishing stdout; no timeout, exit code ignored. +- `ShellMagics` (`sh`): static cached thread pool; `SingleShellMagics` (`!`): a + `Process` + fixed pool of 2 with `StreamGobbler`s and a `Thread.sleep(100)` polling + loop for completion — works, but the sleep adds up to 100 ms latency per external + command. +- `GitMermaidMagics`: `ProcessBuilder` around `git` (diagram from git history), no timeout. + +### 2.5 Build, packaging, CI + +- `build.gradle` [V]: + - toolchain **Java 21** (`:14, :83`); wrapper **Gradle 8.5**; + - deps: `jupyter-jvm-basekernel 2.3.0`, `gson 2.10.1`, maven-resolver + `provider 3.8.6` / core `1.8.2`, `logback 1.5.7`, JUnit **4.13.2**, + javaparser `3.25.8`, plantuml `1.2026.0`, classgraph `4.8.168`, lombok `1.18.30`; + - Shadow 8.1.1 fat jar; **no `processResources` token filtering anywhere** (grep for + `filesMatching|expand` → none), so `ijava-kernel-metadata.json` ships with literal + `@version@`/`@project@` — **confirmed present in `build/libs/IJava-all.jar`**; + - `shadowJar` also copies `build.gradle` into the jar (`:87-104`, odd artifact); + - `packDist` zips the jar + kernel dir + `install.py` for jupyter install; + - `build.finalizedBy packDist`. +- `gradle.properties` [V]: daemon disabled; **dependency verification is present but + commented out**. +- `.github/workflows/build-release.yml` [V]: triggers **only on tag push / manual + dispatch**, runs on a **self-hosted** Linux runner, sets up Temurin 21, builds, then a + smoke test that installs a fresh venv + jupyter and **hand-writes a minimal + `kernel.json`** (i.e., the real `install.py`/`kernel.json` template path is not + exercised). No PR/push CI, no JDK matrix, no coverage, no lint. +- `src/main/resources/kernel.json` [V]: `argv: java -jar ...-all.jar`, + `interrupt_mode: "message"`, empty `env` (no `-Xmx` or other JVM tuning surface). +- Logging [V]: `logback.xml` = console, root `INFO`; `IJava.main` forces + `JUPYTER_LOGGER` to WARNING (`IJava.java:97`) — kernel diagnostics are effectively + silenced by default; there is a stray `System.out.printf("found startup file: %s%n", + path)` in `CodeEvaluatorBuilder.java:185` that can leak to the real terminal before + basekernel swaps the streams; several commented-out debug blocks remain + (`JavaKernel.java:92-99`, `CodeEvaluatorBuilder.java:150-157`). +- Tests [V]: 8 test classes, ~582 lines, JUnit 4; includes a good DX guard + (`DuplicateMagicsTest` scans class files for duplicate `@CellMagic`/`@LineMagic` names) + and one end-to-end-ish DBMS/PlantUML test that requires Graphviz on PATH (environmental + failure seen before `dot` was installed). No protocol-level integration test, no + coverage tooling, no JMH. +- Repo state [V]: stray `.git` directory no longer present; `notebooks/out` and + `build copy.gradle` removed (staged on this branch); license `${author}` → `ebpro` + sweep done (45 files modified at audit time, uncommitted). + +--- + +## 3. Deep Audit Findings + +Severity: **P0** = fix now (correctness/reliability/security, low effort) · +**P1** = high impact, medium effort · **P2** = strategic. + +| # | Sev | Area | Finding (evidence) | Risk / impact | +|---|-----|------|--------------------|---------------| +| F1 | P0 | Packaging | `ijava-kernel-metadata.json` ships with literal `@version@`/`@project@` (verified in `IJava-all.jar`); no resource filtering in `build.gradle`; jar's `kernel-metadata.json` is basekernel's, so banner/kernel_info misreport implementation | Wrong version in `kernel_info`, banner, release notes automation; confuses debugging | +| F2 | P0 | Reliability | `IJavaExecutionControl.execute` does not cancel the task on `TimeoutException` (`:129-134`); timed-out statements keep running on leaked non-daemon threads from an unbounded cached pool (`:76`) | Resource exhaustion; interleaved execution of "dead" cells; JVM never exits cleanly | +| F3 | P0 | CI/quality | No PR/push CI; only tag-triggered self-hosted build; smoke test bypasses `install.py` (hand-written kernel.json); single JDK (21) | Regressions merge untested; packaging path unverified; no 25 validation | +| F4 | P0 | Security | No dependency verification (commented out in `gradle.properties`); no dependency vulnerability scanning; supply-chain exposure in a fat jar that runs arbitrary user code | Tampered/stale deps reach every student machine | +| F5 | P0 | Reliability | `MagicsTool.cmd` reads stdout before stderr with no concurrency (`:91-100`) → pipe deadlock on >64 KB stderr; no timeout; deprecated `Runtime.exec` | Kernel can hang indefinitely on `cmd` | +| F6 | P1 | Performance | All message types share one handler map; complete/inspect/is_complete queue behind running cells; loop sleeps 50 ms after every iteration (basekernel `ShellChannel`/`Loop`) | Completion/hover frozen while a cell runs; ~50 ms fixed latency on idle kernel | +| F7 | P1 | Performance | `evalWithPrint` does O(n) snippet scan + `replaceAll` per eval (`JavaKernel.java:327-340`) | Slowdown grows linearly with session length; GC pressure from per-eval regex work | +| F8 | P1 | Performance | First cell pays startup-script evaluation (lazy `CodeEvaluator.init`, `:128-135`) | First-cell latency 2–3× warm cells (measured in practice; mechanism verified) | +| F9 | P1 | Reliability | `RuntimeCompiler` writes sources to CWD and creates/closes a new `URLClassLoader` per compile (`:68-70`, `:100-103`) | CWD pollution; type-identity churn across compiles; stale "already exists" check | +| F10 | P1 | Security | `MavenResolver` hardcoded remotes, no offline/proxy/mirror (`:61-69`); network resolution by default from notebook cells | Unexpected egress; breaks in air-gapped classrooms; no policy | +| F11 | P1 | Quality | JUnit 4; ~580 test lines; no coverage gate; no lint/static analysis; no JMH | Weak safety net for the P1/P2 refactors | +| F12 | P1 | DX/Observability | `JUPYTER_LOGGER` forced to WARNING (`IJava.java:97`); console-only logging; stray `System.out` debug (`CodeEvaluatorBuilder.java:185`); commented debug blocks | Hard to diagnose kernel issues; terminal noise | +| F13 | P1 | Packaging | `kernel.json` has empty `env` — no JVM memory/flag surface; `shadowJar` bundles `build.gradle` into the artifact | OOM on big datasets with no recourse; noise in artifact | +| F14 | P2 | Architecture | Hard dependency on 2019-era `jupyter-jvm-basekernel` (ZMQ binding, single handler map, 50 ms loop) blocks F6-class fixes without forking it | Ceiling on performance/protocol work | +| F15 | P2 | Architecture | No engine abstraction: JShell internals are woven through `JavaKernel` (eval/complete/inspect/print paths) | Can't swap to an incremental (JDT) engine or AOT-compiled path | +| F16 | P2 | Security | No isolation story: user code shares the kernel JVM; no read-only mode, no network toggle, no memory cap, no process-level timeout kill | Unsuitable for multi-tenant/graded environments | +| F17 | P2 | Performance | JShell per-statement recompilation; no persistent incremental compile; snippets accumulate without reset policy | Long sessions degrade (compile time, memory) | +| F18 | P2 | Rich output | Output is text/HTML via magics only; no table/dataframe API, no `update_display_data` usage, no plot bridge | Below 2026 notebook UX expectations | +| F19 | P1 | Maintainability | Duplicated magic infrastructure across 13 classes (~5.3k LOC), stringly-typed arg parsing, mixed `List`/map APIs | Slow to extend; error-prone (see `DuplicateMagicsTest` existing to catch name collisions) | +| F20 | P2 | DX | Install path is zip + `install.py` into jupyter's data dir; no pip-packaged kernelspec; no `ijava --doctor`/preflight | Friction for students; env issues (like the Graphviz one) surface late | + +--- + +## 4. SOTA 2026 Target Architecture + +``` + ┌────────────────────────────────────────────┐ + jupyter_client 8.x ──▶│ kernel process (java 25, -Xmx tunable) │ + (ZMQ, protocol 5.3) │ ┌──────────────────────────────────────┐ │ + │ │ ijava-protocol (basekernel 2.4.x or │ │ + │ │ fork) │ │ + │ │ • execute: dedicated worker, serial │ │ + │ │ • complete/inspect/is_complete: │ │ + │ │ bounded parallel pool (no 50 ms │ │ + │ │ sleep; poll(0) only) │ │ + │ │ • interrupt on control channel │ │ + │ └──────────────┬───────────────────────┘ │ + │ ▼ │ + │ ┌──────────────────────────────────────┐ │ + │ │ IJavaKernel (this repo) │ │ + │ │ • Engine SPI ── JShellEngine (def) │ │ + │ │ JdtEngine (P2) │ │ + │ │ • StatementRunner: virtual threads + │ │ + │ │ cancellation + wall-clock timeout │ │ + │ │ • Session state: snippet registry, │ │ + │ │ incremental classpath, metrics │ │ + │ │ • Magics: unified registry+parser │ │ + │ └──────────────┬───────────────────────┘ │ + │ ▼ (opt-in, IJAVA_SANDBOX) │ + │ child-JVM execution mode: no network, │ + │ read-only FS, hard kill on timeout │ + └────────────────────────────────────────────┘ +``` + +Design decisions (with rationale): + +1. **Keep JShell as the default engine.** JShell gives snippet semantics, + completion, hover, and import management that a hand-rolled Compiler-API REPL would + have to reimplement for years of teaching use. SOTA in 2026 for an *interactive + teaching kernel* is not "fastest compile" — it is **responsive completion while + executing, bounded memory, and predictable first-cell latency**. [I] +2. **Engine SPI (`IJavaEngine`)** with `eval / complete / inspect / reset / metrics`. + JShell engine now; JDT-based incremental engine later (JDT provides true incremental + compilation and binding-based completion/hover that beat JShell's textual analysis). + The SPI is the only change to `JavaKernel`'s structure; magics stay unchanged. [I] +3. **Statement execution on virtual threads** (Java 21+, LTS 25): + `Executors.newVirtualThreadPerTaskExecutor()`, `future.cancel(true)` on timeout, + `ScopedValue` for the current-cell context (working dir, classpath, workspace). + Virtual threads make the "one thread per statement" model free; cancellation + + optional child-JVM mode make timeout *enforceable*. [I] +4. **Decoupled message loop.** Fork `jupyter-jvm-basekernel` (same author, small codebase) + as `ebpro/jupyter-jvm-basekernel` 2.4.0: (a) separate bounded executor for + complete/inspect/is_complete/history so they never queue behind execute; (b) + configurable loop sleep (default 0 with `poll(timeout)`); (c) keep `synchronized` + execute for state safety. Fallback if upstreaming is impossible: accept the + serialization and only fix the sleep. [I] +5. **Security defaults, not sandbox-by-default.** 2026 SOTA for Jupyter kernels is + layered: in-JVM kernel by default (fast, simple) + **opt-in strict mode** + (`IJAVA_SANDBOX=process`): each statement runs in a child JVM with network disabled + (custom `URLStreamHandlerFactory` + no DNS), read-only user FS, and hard-kill on + timeout — plus documented container-level sandboxing (JupyterHub profiles) for + multi-tenant use. `SecurityManager` is explicitly *out* (deprecated for removal). + [I] +6. **Packaging done properly**: `processResources` filtering for real versions; a pip + package `ijava-kernel` that installs the kernelspec + jar (keeps `install.py` for + compat); `kernel.json` exposes `IJAVA_JAVA_OPTS` env; fat jar no longer bundles + `build.gradle`. [I] +7. **Observability by default**: structured JSON logs (logback JSON encoder) to the + terminal log file (not the notebook), per-cell metrics (startup, startup-script, + compile, eval, complete p50/p95) to stderr; optional OTel exporter behind a + separate Gradle module so the fat jar stays slim. `JUPYTER_LOGGER` silencing + removed in favor of `IJAVA_LOG_LEVEL`. [I] +8. **Java 25 primary, Java 21 floor.** Build toolchain 25 with `--release 21` so the + published kernel still runs on 21 LTS JVMs (what many distros ship); CI matrix + tests both. Virtual-thread *executor* usage stays `--release`-safe (Java 21+ API). + [I] (user has confirmed Java 25 is acceptable; `25.0.4-tem` installed via sdkman.) + +--- + +## 5. Prioritized Implementation Plan + +### P0 — quick wins (target: ≤ 1 day total, 4–6 small PRs) + +| ID | Task | Files | Effort | Risk | Validation | +|----|------|--------|--------|------|------------| +| P0-1 | **Fix version placeholders**: add `processResources { filesMatching('ijava-kernel-metadata.json') { expand project: rootProject.name, version: version } }`; also emit a correct `kernel-metadata.json` (project=`ijava`) into the jar so banner/kernel_info report IJava, not basekernel | `build.gradle`, `src/main/resources/` | 0.5 h | low | `unzip -p build/libs/IJava-all.jar ijava-kernel-metadata.json` shows real version; `jupyter kernelspec` smoke shows `ijava 1.4.x` | +| P0-2 | **Timeout actually cancels**: in the `TimeoutException` branch call `future.cancel(true)` (and track cancelled tasks so `interrupt()` doesn't double-report); make the pool daemon + bounded (e.g. 2) or virtual threads; add `IJAVA_MAX_CONCURRENT_STATEMENTS` | `IJavaExecutionControl.java`, `IJavaExecutionControlProvider.java` | 1 h | low | new unit test: submit sleeping statement with 1 s timeout → task thread count returns to 0; kernel exits after shutdown | +| P0-3 | **PR CI**: new `.github/workflows/ci.yml` — `pull_request` + `push` to main branches; `ubuntu-latest`; matrix JDK 21/25 (temurin); `./gradlew build` (runs tests) + `./gradlew shadowJar` + jar-content assertion script (version placeholder check from P0-1); keep tag workflow for releases | `.github/workflows/` | 1 h | low | PR check goes red on a deliberate regression | +| P0-4 | **Supply chain**: re-enable Gradle dependency verification (`gradle/verification-metadata.xml` generated once), add OWASP `dependency-check-gradle` to CI (fail on critical/high, report-only first release) | `gradle.properties`, `gradle/`, CI | 1 h | low | `./gradlew build` verifies checksums; CI report artifact | +| P0-5 | **`cmd` magic deadlock + hygiene**: read stdout/stderr concurrently (reuse `StreamGobbler` pattern from `SingleShellMagics`), add `timeout=` arg (default 30 s), replace `Runtime.exec` with `ProcessBuilder`, return/echo exit code; remove stray `System.out` in `CodeEvaluatorBuilder.java:185` and commented debug blocks | `MagicsTool.java`, `CodeEvaluatorBuilder.java`, `JavaKernel.java` | 1 h | low | test: `cmd "sh -c 'head -c 200000 /dev/zero \| tr \\0 e; sleep 0.1'"` style large-stderr case doesn't hang; timeout honored | +| P0-6 | **JVM surface in kernel.json**: add `env: { "IJAVA_JAVA_OPTS": "" }` consumed by `IJava.main` (split into `-Xmx` etc. before engine start) — or document `JAVA_TOOL_OPTIONS`; stop bundling `build.gradle` into the fat jar | `kernel.json`, `IJava.java`, `build.gradle` | 0.5 h | low | kernelspec smoke with `-Xmx256m` visible in process args | + +### P1 — high impact (2–4 weeks, ordered) + +| ID | Task | Files / scope | Effort | Risk | Validation | +|----|------|---------------|--------|------|------------| +| P1-1 | **Decouple message loop**: fork `jupyter-jvm-basekernel` → `ebpro` 2.4.0 with (a) complete/inspect/is_complete/history on a bounded pool (4) separate from execute, (b) `poll(timeout)` with configurable sleep (default 0), (c) keep execute serialized. Bump dep in IJava | fork + `build.gradle` | 3–5 d | medium | new protocol integration test: start 60 s cell, assert complete requests answered < 250 ms p95; idle is_complete latency < 10 ms p50 (vs ~50 ms today) | +| P1-2 | **Virtual-thread `StatementRunner`** (replaces cached pool): virtual threads, `cancel(true)` on timeout, `ScopedValue` cell context, metrics per statement; JShell engine untouched | new `execution/StatementRunner.java`, `IJavaExecutionControl` | 2 d | medium | soak test: 500 timed-out cells → no thread growth, RSS flat; cancel latency < 50 ms for cooperative code | +| P1-3 | **First-cell latency**: evaluate startup scripts eagerly at engine init, capture failure, and surface it on the first cell (keeps today's error UX, moves the cost out of the first user cell); keep `IJAVA_STARTUP_SCRIPT` override | `CodeEvaluator.java`, `CodeEvaluatorBuilder.java` | 1 d | low | benchmark: first `println` cell < 800 ms on warm JVM (measure before/after in CI bench job) | +| P1-4 | **Session state cleanup for `evalWithPrint`**: replace O(n) snippet scan with a last-statement registry (store the last eval string + id in `JavaKernel`, no `skip`/`reduce` over snippets) | `JavaKernel.java` | 1 d | low | micro-benchmark: 10k snippets, print-eval constant time; existing tests green | +| P1-5 | **Compile magic consolidation**: one workspace root (`IJAVA_WORKSPACE`, default `~/.jupyter/java-workspace`), one persistent classloader registry per package, no CWD writes, no per-compile loader close; deprecate `RuntimeCompiler` in favor of `JavaCompilerMagics` internals | `RuntimeCompiler.java`, `JavaCompilerMagics.java`, `CompilerMagics.java` | 3 d | medium | test: compile A → instance → recompile A → new code runs on existing call sites (type identity policy documented); no files in CWD | +| P1-6 | **Maven resolver hardening**: offline mode (`IJAVA_OFFLINE=1` / `%resolve --offline`), configurable mirrors (`IJAVA_MAVEN_REPOS`), proxy via standard JVM props, timeout on resolution, lockfile-style cache in workspace | `MavenResolver.java` | 2 d | medium | offline test with primed cache; network test in CI | +| P1-7 | **Test & quality baseline**: migrate to JUnit 5 (+`junit-platform`), add JaCoCo with ratcheting gate (start: 30 % line coverage on `execution` + `magics` packages), Spotless (google-java-format) + ErrorProne on CI, keep `DuplicateMagicsTest` | `build.gradle`, `src/test/` | 3 d | low | CI gate; coverage report artifact; ratchet config in `build.gradle` | +| P1-8 | **Observability**: logback JSON encoder to stderr (notebook output untouched), per-cell timing metrics (startup / startup-script / compile / eval / complete), `IJAVA_LOG_LEVEL` replaces the hardcoded WARNING silencing | `logback.xml`, `IJava.java`, `JavaKernel.java` | 2 d | low | log fixture tests; metrics visible in `jupyter` terminal log | +| P1-9 | **Dependency refresh**: gson 2.13.x, maven-resolver 1.9.x/3.9.x, javaparser 3.26.x, classgraph latest, logback latest 1.5.x, basekernel 2.4.0 (P1-1); re-run verification metadata (P0-4) | `build.gradle` | 1–2 d | low | build + full test suite on 21 & 25 | + +### P2 — strategic (quarter+) + +| ID | Task | Rationale / trade-offs | Effort | Validation | +|----|------|------------------------|--------|------------| +| P2-1 | **`IJavaEngine` SPI + JDT engine** | SPI (1 wk) is cheap insurance; JDT incremental engine (6–10 wk) delivers true incremental compile + binding-based completion/hover (faster & more accurate than JShell textual analysis). Trade-off: big effort, two engines to maintain; mitigate by making JShell the only default and JDT opt-in (`IJAVA_ENGINE=jdt`) | 1 wk + 6–10 wk | parity test suite (both engines run the same magic/cell corpus with golden outputs); JDT engine: 50-line re-declaration recompile < 300 ms; completion p50 < 60 ms on 1k-line session | +| P2-2 | **Strict-mode child-JVM execution** (`IJAVA_SANDBOX=process`) | Real timeout enforcement + network/FS isolation without `SecurityManager`. Trade-off: per-statement JVM cost (~200–400 ms) and serialization of state across statements → keep in-JVM default; strict mode targets graded/multi-tenant environments. Pair with documented container sandboxing (JupyterHub profiles) | 3–4 wk | security test suite: `Runtime.exec("curl ...")` fails in strict mode; 60 s infinite loop killed at 60 s with no zombie threads | +| P2-3 | **Rich output APIs** | table/dataframe magic (`%table` → styled HTML + CSV download), `update_display_data` for in-place updates (basekernel already publishes it), plot bridge (plotly JSON) | 3–4 wk | notebook golden-output tests (nbconvert to HTML, diff) | +| P2-4 | **Memory governance** | `%reset` exists via jshell; add auto-reset policy (`IJAVA_RESET_AFTER_N_CELLS`), snippet/heap metrics in status bar, classloader registry pruning for compile magic | 2 wk | soak: 10k cells, RSS growth < 100 MB; `%mem` magic report | +| P2-5 | **pip-packaged kernelspec** (`ijava-kernel` on PyPI) + `ijava doctor` preflight (java version, workspace, Graphviz for dbms magic, network for maven) | 2026 install SOTA is `pip install ijava-kernel && jupyter kernelspec install ...`; `doctor` would have caught the Graphviz env failure seen in this repo | 2 wk | fresh-container install test in CI (ubuntu + venv + `pip install`) | +| P2-6 | **Protocol benchmark suite in CI** | Java-side JMH for hot paths (magic transform, error styling, classpath globs) + Python `jupyter_client` harness for end-to-end latencies (startup, first cell, warm cell, complete p95); store baselines, fail on > 15 % regression | 2 wk | bench job with baseline artifacts; PR comment on deltas | +| P2-7 | **OpenTelemetry module** (optional) | Traces per message type, metrics for cells; separate Gradle subproject to keep fat jar slim; off by default | 1–2 wk | golden OTLP fixture test | + +--- + +## 6. Performance Targets + +Reference machine: 4 vCPU / 8 GB CI runner (ubuntu-latest), JVM 25, warm page cache. +All targets are **p50 unless noted**; measured by the P2-6 harness, asserted in CI +starting at P1-1 (latency) and P1-3 (first cell). + +| Metric | Today (measured/mechanism) | 2026 target | +|--------|---------------------------|-------------| +| Kernel start → `kernel_info` reply | ~1–2 s (JVM + ZMQ + JShell build) [I] | **< 1.2 s p50**, < 1.8 s p95 | +| First cell (`System.out.println`) | warm-cell + startup-script eval (lazy init) [V mechanism] | **< 800 ms p50** (after P1-3) | +| Warm cell (println) | ~50–150 ms (loop sleep + jshell) [I] | **< 100 ms p50**, < 200 ms p95 | +| Completion (idle kernel) | up to ~50 ms loop sleep + `sourceCodeAnalysis` [V mechanism] | **< 60 ms p50**, < 150 ms p95 (P1-1) | +| Completion (while cell executing) | **blocked until cell ends** [V] | **< 250 ms p95** (P1-1) | +| Hover/inspect | same as completion [V] | **< 200 ms p50** | +| Recompile 50-line declaration (JShell default) | ~300–800 ms [I] | **< 500 ms p50** (JShell); < 300 ms with JDT engine (P2-1) | +| `%compile` (persistent workspace) | new classloader + CWD writes [V] | **< 700 ms p50**, zero CWD writes (P1-5) | +| Interrupt → stop | future cancel (cooperative) [V] | cancel signal < 50 ms; strict mode hard-kill at timeout (P2-2) | +| Memory, idle after 10k cells | unbounded snippet growth [I] | **< 100 MB growth** (P2-4) | +| `./gradlew test` wall time | ~30–60 s local [I] | **< 90 s** on 4 vCPU CI (gate) | + +--- + +## 7. Validation Plan + +Layered, all runnable in CI (P0-3 adds the runner): + +1. **Unit (JUnit 5)** — every P0/P1 item ships with unit tests: + - P0-2: timeout cancellation (thread count returns to baseline), bounded concurrency; + - P0-5: large-stderr `cmd` no-hang, timeout honored, exit code surfaced; + - P1-4: `evalWithPrint` constant-time over 10k snippets; + - P1-5: type-identity policy + workspace isolation; + - P1-6: offline resolution, mirror config. +2. **Protocol integration test** (new): Java-side ZMQ client (or Python `jupyter_client` + step in CI) that starts the real jar: `kernel_info` → asserts version == build + version (catches F1 class bugs) → run 60 s cell → assert `complete` answers < 250 ms + p95 while busy → `interrupt` → assert kernel responsive within 1 s. Runs on every PR + (JDK 21 & 25). +3. **Packaging smoke** (existing, extended): the tag-release smoke must install via the + **real** `install.py`/`kernel.json` (replace the hand-written kernel.json) and run + `magics_demo.ipynb` through `jupyter nbconvert --execute`; add a fresh-venv + + `pip install ijava-kernel` path once P2-5 lands. +4. **Benchmark gates** (P2-6): JMH (magic transform, error styler, classpath globs) + + protocol harness baselines in CI artifacts; fail on > 15 % regression on tracked + metrics; baselines updated via explicit PR. +5. **Quality gates**: Spotless + ErrorProne (P1-7), JaCoCo ratchet (start 30 % on + `execution` + `magics`, +5 % per release), dependency verification + OWASP + dependency-check (P0-4). +6. **Compatibility matrix**: JDK 21 (floor, `--release 21` artifact) and 25 (primary); + Jupyter 7.x / jupyter_client 8.x; Python 3.11–3.13 in the smoke venv. +7. **Soak test** (nightly, not PR): 1k warm cells + 500 timed-out cells + 200 + compile cycles → assert thread count, RSS growth, and interrupt latency bounds. +8. **Security test suite** (grows with P2-2): egress blocked in strict mode, FS read-only + enforcement, timeout hard-kill, no secrets in logs (grep-based log fixture test). + +--- + +## 8. Migration Plan + +All work lands as small branches off `feature/update2026` (which carries the completed +hygiene/timeout/docs work) → merged to `master` in the order below. Each step is +releasable and CI-green on its own. No step requires a big-bang migration; users on +`1.4.x` keep working (protocol unchanged, kernel name unchanged). + +| Step | Branch | Contents | Release | +|------|--------|----------|---------| +| 1 | `chore/build-correctness` | P0-1, P0-6, P0-5 (hygiene half) | v1.4.6 (patch) | +| 2 | `fix/timeout-cancellation` | P0-2 | v1.4.7 (patch) — behavior fix, call out in release notes ("timeouts now actually stop leaking threads") | +| 3 | `ci/pr-matrix` | P0-3, P0-4 | no user release (infra) | +| 4 | `deps/refresh-2026` | P1-9 + P1-7 (JUnit 5, JaCoCo, Spotless/ErrorProne) | v1.5.0-rc1 | +| 5 | `feat/basekernel-2.4` | P1-1 (fork + release `ebpro/jupyter-jvm-basekernel` 2.4.0), then dep bump | v1.5.0-rc2 | +| 6 | `perf/statement-runner` | P1-2, P1-3, P1-4 | v1.5.0 | +| 7 | `feat/workspace-and-resolver` | P1-5, P1-6, P1-8 | v1.5.1 | +| 8 | `feat/engine-spi` | P2-1 phase 1 (SPI + JShell engine extraction only) | v1.6.0 (API-additive) | +| 9 | `feat/strict-sandbox` | P2-2 + P2-5 (pip kernelspec + doctor) | v2.0.0-rc1 | +| 10 | `feat/jdt-engine`, `feat/rich-output`, `feat/otel` | P2-1 phase 2, P2-3, P2-7 | v2.0.0 | +| 11 | continuous | P2-4, P2-6 soak/bench gates harden over releases | — | + +Compatibility & rollback notes: + +- **Protocol**: stays Jupyter messaging 5.3 over ZMQ; no notebook-side changes needed. + Rollback of any release = reinstall previous kernelspec (`jupyter kernelspec install + ijava-.zip --user`). +- **Engine**: JShell remains default through v2.x; JDT engine opt-in only; SPI is + additive so v1.6 consumers (custom magics/extensions) are unaffected. +- **Timeout semantics**: v1.4.7 changes a leak into a cancellation — code that + *depended* on timed-out cells continuing to run in the background (rare; anti-pattern) + is the only behavior break; document in release notes. +- **Java floor**: published artifact keeps `--release 21`; Java 25 is the development + and primary-tested runtime. Users on Java 17 are EOL (documented requirement: 21+). +- **Data**: `~/.jupyter/java-workspace` layout is preserved (P1-5 only adds the + `IJAVA_WORKSPACE` override); no migration of user files. +- **CI**: tag workflow untouched until P0-3 lands; after that, tag builds run on top of + the green PR pipeline (same runner image), so release risk drops, not rises. +- **Known environmental dependency**: `JavaDBMSMagics` requires Graphviz `dot` on PATH + (verified failure mode in this repo before `dot` was installed); `ijava doctor` (P2-5) + reports it preflight; until then, CI smoke includes `apt-get install graphviz`. + +--- + +## Appendix A — Files inspected (audit evidence base) + +- `build.gradle`, `settings.gradle`, `gradle.properties`, `gradle/wrapper/gradle-wrapper.properties` +- `.github/workflows/build-release.yml` +- `README.md`, `docs/magics.md`, `UPGRADE.md` +- `src/main/java/io/github/spencerpark/ijava/`: `IJava.java`, `JavaKernel.java` +- `.../execution/`: `CodeEvaluator.java`, `CodeEvaluatorBuilder.java`, `IJavaExecutionControl.java`, `IJavaExecutionControlProvider.java` +- `.../magics/`: `MagicsTool.java`, `MavenResolver.java`, `JavaCompilerMagics.java`, `JavaMagics.java`, `ShellMagics.java`, `SingleShellMagics.java`, `TimeItMagics.java`, `GitMermaidMagics.java` (+ registration in `JavaKernel.java:115-137`) +- `.../utils/RuntimeCompiler.java` +- `src/main/resources/`: `kernel.json`, `install.py`, `ijava-kernel-metadata.json`, `logback.xml`, `ijava-jshell-init.jshell`, `print.jshell` +- `src/test/java/io/github/spencerpark/ijava/magics/DuplicateMagicsTest.java` (+ 7 other test classes) +- Artifacts: `build/resources/main/ijava-kernel-metadata.json`, `build/libs/IJava-all.jar` (unzip-verified) +- `jupyter-jvm-basekernel-2.3.0-sources.jar` (Gradle cache) → extracted to + `/tmp/opencode/basekernel`: `BaseKernel.java`, `JupyterConnection.java`, + `ShellChannel.java`, `Loop.java`, `JupyterIO.java` + +## Appendix B — Verified vs inferred + +- **Verified**: everything tagged [V] in §2/§3, plus jar contents, CI trigger, loop + sleep, synchronized execute, handler-map sharing, placeholder version, hardcoded Maven + remotes, `cmd` read order, JUnit 4 + test count, 50 ms constant, 60 s default timeout + (this branch). +- **Inferred** [I]: all target numbers in §6 (to be measured by the P2-6 harness), + effort estimates, JDT-engine performance expectations, strict-mode overhead, and the + SOTA architectural choices in §4 (each with stated rationale/trade-off). diff --git a/docs/magics.md b/docs/magics.md index f6bf8ea..8ceec84 100644 --- a/docs/magics.md +++ b/docs/magics.md @@ -124,4 +124,176 @@ The cell magic is designed to make it very simple to copy and paste from any REA jupyter-jvm-basekernel 2.0.0-SNAPSHOT - ``` \ No newline at end of file + ``` + + The line form `%loadFromPOM [scopes...]` loads a local POM file. `pom` is an alias for both forms. + +## Fork extensions (ebpro/IJava) + +The magics below are provided by this fork on top of the original set. Every magic also supports `--help` / `-h`. + +### JDBC-backed magics + +`%%rdbmsSchema`, `%%sqlAsTable` and `%%tableSchema` operate against a JDBC database. Configure the connection with the system properties `jdbc.url` (required) and optionally `jdbc.user` / `jdbc.password` (for example in the `env` section of `kernel.json` or a startup script). Common drivers (H2, HSQLDB, Derby, SQLite, MySQL, PostgreSQL) are attempted automatically before obtaining a `Connection`. + +### %%rdbmsSchema + +Render the schema of a relational database as a PlantUML ER diagram (SVG or PNG). + +###### Cell magic + +* **arguments**: `[] [SVG|PNG] [--show-source] [handwritten] [include=] [exclude=] [scale=]` +* **body**: optional list of table names (one per line) to restrict the diagram + +### %%sqlAsTable + +Execute SQL and render the first `SELECT` result as an HTML table (or CSV). + +###### Cell magic + +* **arguments**: `[format=HTML|CSV] [max=] [showQuery]` (max defaults to 1000 rows) +* **body**: one or more SQL statements; the first `SELECT` is rendered + +### %%tableSchema / %tableSchema + +Show the detailed layout of one or more tables: columns with PK/FK/UNIQUE markers, types, nullability, autoincrement, optional DDL and sample rows. + +###### Line magic + +* **arguments**: `[] [--ddl] [--compact] [--sample=]` + +###### Cell magic + +* **arguments**: same as the line form +* **body**: table names, one per line + +### %%compile + +Compile the cell body with the platform `javac`, add the result to the notebook classpath, and print diagnostics. Supports annotation processors (e.g. Lombok). + +###### Cell magic + +* **arguments**: `[--verbose|-v] [--debug|-d] [--nowarn|-w] [--dry-run|-n] [--release=] [--enable-preview] [--output=] [--classpath=] [--processor=]* [--processor-path=] [--processor-option=]* [--class=] | ` +* **body**: Java source. A `package` declaration is added automatically when missing. + + ```java + %%compile --output=demo com.example.Calculator + public class Calculator { + public int add(int a, int b) { return a + b; } + } + ``` + +### %%mycompile + +Simpler compile variant: `%%mycompile ` with the source in the body. The package is inferred from the class name. + +### %%benchmark + +Compare the performance of several implementations in one cell and render an SVG bar/line chart. Implementations are separated by a line containing only `---`. + +###### Cell magic + +* **arguments**: `[iterations=] [warmup=] [--sweep var= start= end= step=] [--chart]` +* **body**: the implementations + + ```java + %%benchmark iterations=10 + int sum = 0; for (int i = 0; i < 1000; i++) sum += i; + --- + int sum = IntStream.range(0, 1000).sum(); + ``` + +> **Note:** timings are measured through jshell snippet evaluation, so they include snippet compilation and dispatch overhead. Use `%%benchmark` for classroom-level comparisons only. For publication-grade microbenchmarks use [JMH](https://github.com/openjdk/jmh), e.g. `%%maven org.openjdk.jmh:jmh-core:1.37`. + +### %%time / %%timeit + +Run the cell body several times and report min / median / avg / max in nanoseconds. + +###### Cell magic + +* **arguments**: `[warmup=] [iterations=]` (defaults: `warmup=1`, `iterations=5`) +* **aliases**: `time`, `timeit` + +### %%classDiagram / %classDiagram + +Generate a UML class diagram (PlantUML, rendered to SVG/PNG) for a class or a whole package using classpath scanning. + +###### Line / cell magic + +* **target**: `` or `--package=` +* **options**: `[--svg] [--png] [--uml] [--non-public] [--ancestors] [--depth=] [--interfaces-only] [--classes-only] [--exclude-inherited] [--max=] [--include=] [--exclude=] [--out=]` + * `--uml` prints the PlantUML source instead of rendering + * `--ancestors` follows superclasses/interfaces up to `--depth` + +### %%plantUML / %%plantUMLFile + +Render PlantUML. `%%plantUML` takes the diagram source in the body; `%%plantUMLFile` takes a path to a `.puml` file. Both accept `[SVG|PNG]` and `--show-source`. + +### %%shell / %cmd + +Execute shell commands. + +###### %%shell (cell) + +* **arguments**: `[--shell=] [--timeout=]` (default timeout 180s) +* **body**: the command(s) to run + +###### %cmd (line) + +* **arguments**: `` — runs a single command and prints its output + +### %%commonshell / %commonshellcmd + +Run commands in a *persistent* shell session (state such as `cd` or `export` survives between cells). `%%commonshell` takes the command in the body; `%commonshellcmd ` is the line form. + +### %%write / %write / %read / %load + +File helpers. + +* `%%write [path]` — write the cell body to `path` (a temp file is used when omitted) +* `%write [path]` — write a variable's value to `path` (or a temp file) +* `%read ` — read a file and return its content as a `String` +* `%load ` — load a `.java` / `.jshell` / `.jsh` / `.ijava` file into the notebook; plain file names are also searched under `docs/notebooks/` and the workspace + +### %list / %lineMagic / %cellMagic + +List the registered line magics, cell magics, or both. + +### %printWithName + +Toggle the "print with variable name or source" result decoration (defaults on). + +### %printerPrefix / print() + +`print(Object)` is a notebook function that prints the value prefixed with the name of the argument expression. `%printerPrefix ` sets a custom prefix (e.g. `%printerPrefix "db> "`); with no argument it shows the current prefix. + +### %reload-class + +Reload an already compiled class (by fully qualified name) after recompiling it with `%%compile`. + +### %class-info / %javadoc-html / %where + +* `%class-info ` — show class metadata (fields, methods, annotations) +* `%javadoc-html ` — render Javadoc for a class as HTML +* `%where ` (alias `%which`) — locate a class: containing jar/classpath entry and, when available, its source file + +### %classpath-snapshot + +Print the current notebook classpath (useful for reproducing a session). + +### %%javasrc* (source extraction) + +Extract Java source from files on disk (resolved via `--src=`) using JavaParser. All variants accept `[--src=] [--raw] [--fenced]`: + +* `%%javasrcClassByName ` — full class source +* `%%javasrcInterfaceByName ` — full interface source +* `%%javasrcConstructorByName ` — one constructor +* `%%javasrcMethodByName ` — one method (`methodRegex=` and `selectIndex=` supported) +* `%%javasrcMethodByAnnotationName ` — methods carrying an annotation +* `%%javasrcFieldByName ` — one field +* `%%javasrcJavadoc [memberName]` — Javadoc of a class or member +* `%%javasrcList ` — list classes/members found + +### %%loadFromPOM alias + +`pom` works as an alias for both the line and cell forms of [loadFromPOM](#loadfrompom). \ No newline at end of file diff --git a/notebooks/out/com/example/demo/A.class b/notebooks/out/com/example/demo/A.class deleted file mode 100644 index 06f2a05a4a07bd6494a54ec7369664898b6f5496..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 219 zcmZvWy$ZrW5QJyVpT=m!-oj2TycZB51g%61#r~2Ul8{RzB;spX2^Kzp4<%l%mW5en zhGoCc_w@#_f$yRN!-46+f=w7@{Ki?%iwiqMnTTtGy-JI;UK5Pj{Oq7h7{{e#;?CtY z7c3F7WPt2{iAT9g++*2PvDl`qv4ds%8B;h4h|p7Xq((t0 Y?JGCY9^8R$Ly0jUBh=>Px# diff --git a/notebooks/out/com/example/demo/B.class b/notebooks/out/com/example/demo/B.class deleted file mode 100644 index 9f1c2234e967e55e19a94857b57dc3055df7a15a..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 195 zcmX^0Z`VEs1_oCKUM>bE24;2!79Ivx1~x_pq2&Br{nU!Y+=84`{gl+)e0@ho1~!|_ zyv!0iMh0dL%`kQb4s6Pt7#Ucc^HWk88TfrN^HTjvbCXhwLK2g5fFfMM`K3k4scxAd z4x5u+R$^HqgCYYv&}tB11VW(YK#~*4lLhk`7+AHoGcaxhOLGB9kTe5O10w@BnC1Zh D!V4q1 diff --git a/notebooks/out/com/example/demo/C.class b/notebooks/out/com/example/demo/C.class deleted file mode 100644 index ce576a30c3291a3b0d2ca5aa4f1cc830773c6ff2..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 176 zcmX^0Z`VEs1_oCKZgvJHMh2ne{9OIiip1Q4oK*dk)ZBc1XLbe_Mh1bb#Ii*FoW#6z zegCAa)Z`LI2F40T24)RSPeuk7=lqmZMh1SL%)C^;(%hufqL9R-9H0nSaDHh~a;jS< zh{NWr2Qq|>fdQxwXeEedWME}r1Cs1Oo-~-xz`!h^wFWH70VF|^Kp`N>38a}AxB#KF BAV&ZI diff --git a/notebooks/out/com/example/demo/Hello.class b/notebooks/out/com/example/demo/Hello.class deleted file mode 100644 index fd5ae47eb2200914a0bfcf6cc53981ebadf8e690..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 304 zcmZ9G%}T>S5Xb-1G)Wt)ts;Vm5O1vq_W>$iMDbAcQ1QM=#;|3REomw~mYxI;K7bD; z&gLRGhxz!=Z$7?%KED9mU_U_*L5%(gAtJ(LrC+qNx-Qj2w&J`cM3<&E?G+)I&YlJs z5RUKIT9-aIu1a%Pt&Qa(&8^;SVkCqk(G1^@$z_M*jUCs%~(rufZZ{>~@-Leah;S580-&+r|1(En2sZJ%5#PIwB h^ezcuB;L0@I>avaB=_h^rvbr1{PqtFq&4maCckr`I(q;B diff --git a/notebooks/out/com/example/demo/LombokPerson.class b/notebooks/out/com/example/demo/LombokPerson.class deleted file mode 100644 index 86b36af5dfa0cfa2299439bab9d5eb4d4ecd1a8d..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1717 zcmah}TW=Fb6#izt_HN9Q8(>IHQc832Ex7j!c4&hI#ZnRwK_Im+Ozcszcs=8K$5DCj zkEr_6xAKyQRw`8Dp=w`>)Zf&Wo>?!jcHCC-dgh!tm+yS%%>429(_a8wLt_dSQVwhn zX=E4{TdG?XU-51)5Y@Kms_K^N?y1f#(GQhmuqE#bhWV`r{E$}zF88auy6?;VnhE53 zm_n8z#rMgGHM6AiJesmNA`62dG=_^FmP|7DfQJVS z)fV$a$psH@;3C7>F7Jqjk}a<9`I?SpsJYZ3!&(x3oVWQeSe8AkV3o4ged+5fQ9XBw zMU#zTX3LjiXVBdf{X2XwAWi=EKx)4$n)1*OeNt^osWjI1 z)+x~SLXPxnBrTG}Xib-X0{ekB3#i^IONIV}AL^aQ@GaE_UqqHLYpNa;seW9%=ii{2Q!qkxm_ze}%PODLui7 zNTkh7g}(31840I$NIG@dUVnxY3-<4rdjxNN!G40Xk-2Ruwh~0ysFEfJ$8rC}v;)ig z3poep=;yMLs%-Pr#pn$8hK;m=HBRC<8T1atZi3bnxvkpu{A}&OV835Cptp@!c?Ng3 z{0I(JaQ=QhKN%{G$8&nx=vlWIfdpgEDdtPjVxy=T-g-GPtCZeM%(O{ql0U`k!1(Bl z!(YMMG5oa{{!Hm-ycx|w>HLJIrblQ?;T=k8;a$8(t4jbrr0;!fkd&p}6?}@TSojBL Cms7p~ diff --git a/notebooks/out/src/com/example/demo/A.java b/notebooks/out/src/com/example/demo/A.java deleted file mode 100644 index 0414517..0000000 --- a/notebooks/out/src/com/example/demo/A.java +++ /dev/null @@ -1,3 +0,0 @@ -package com.example.demo; -public class A implements C { -} \ No newline at end of file diff --git a/notebooks/out/src/com/example/demo/B.java b/notebooks/out/src/com/example/demo/B.java deleted file mode 100644 index 7596cec..0000000 --- a/notebooks/out/src/com/example/demo/B.java +++ /dev/null @@ -1,3 +0,0 @@ -package com.example.demo; -public class B extends A { -} \ No newline at end of file diff --git a/notebooks/out/src/com/example/demo/C.java b/notebooks/out/src/com/example/demo/C.java deleted file mode 100644 index 72f6c70..0000000 --- a/notebooks/out/src/com/example/demo/C.java +++ /dev/null @@ -1,4 +0,0 @@ -package com.example.demo; -interface C { - default int x() { return 42; } -} \ No newline at end of file diff --git a/notebooks/out/src/com/example/demo/Hello.java b/notebooks/out/src/com/example/demo/Hello.java deleted file mode 100644 index 7048a6d..0000000 --- a/notebooks/out/src/com/example/demo/Hello.java +++ /dev/null @@ -1,4 +0,0 @@ -package com.example.demo; -public class Hello { - public static String greet() { return "Hello from compiled class"; } -} \ No newline at end of file diff --git a/notebooks/out/src/com/example/demo/LombokPerson.java b/notebooks/out/src/com/example/demo/LombokPerson.java deleted file mode 100644 index 4a08870..0000000 --- a/notebooks/out/src/com/example/demo/LombokPerson.java +++ /dev/null @@ -1,9 +0,0 @@ -package com.example.demo; -import lombok.Data; -import lombok.AllArgsConstructor; -@Data -@AllArgsConstructor -public class LombokPerson { - private String name; - private int age; -} \ No newline at end of file diff --git a/src/main/java/io/github/spencerpark/ijava/IJava.java b/src/main/java/io/github/spencerpark/ijava/IJava.java index 641e5c9..014fc18 100644 --- a/src/main/java/io/github/spencerpark/ijava/IJava.java +++ b/src/main/java/io/github/spencerpark/ijava/IJava.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2022 ${author} + * Copyright (c) 2022 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/JavaKernel.java b/src/main/java/io/github/spencerpark/ijava/JavaKernel.java index beb377e..8138d58 100644 --- a/src/main/java/io/github/spencerpark/ijava/JavaKernel.java +++ b/src/main/java/io/github/spencerpark/ijava/JavaKernel.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2022 ${author} + * Copyright (c) 2022 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -47,8 +47,6 @@ import java.util.Optional; import java.util.stream.Collectors; -import org.codehaus.plexus.util.cli.shell.Shell; - @Slf4j public class JavaKernel extends BaseKernel { public static String completeCodeSignifier() { diff --git a/src/main/java/io/github/spencerpark/ijava/execution/CodeEvaluator.java b/src/main/java/io/github/spencerpark/ijava/execution/CodeEvaluator.java index 9951996..27ccac2 100644 --- a/src/main/java/io/github/spencerpark/ijava/execution/CodeEvaluator.java +++ b/src/main/java/io/github/spencerpark/ijava/execution/CodeEvaluator.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/execution/CodeEvaluatorBuilder.java b/src/main/java/io/github/spencerpark/ijava/execution/CodeEvaluatorBuilder.java index 6e3b1ff..09c8b76 100644 --- a/src/main/java/io/github/spencerpark/ijava/execution/CodeEvaluatorBuilder.java +++ b/src/main/java/io/github/spencerpark/ijava/execution/CodeEvaluatorBuilder.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/execution/CompilationException.java b/src/main/java/io/github/spencerpark/ijava/execution/CompilationException.java index 1c4db29..0f225a9 100644 --- a/src/main/java/io/github/spencerpark/ijava/execution/CompilationException.java +++ b/src/main/java/io/github/spencerpark/ijava/execution/CompilationException.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/execution/EvaluationInterruptedException.java b/src/main/java/io/github/spencerpark/ijava/execution/EvaluationInterruptedException.java index 10cbfbb..8c7d79f 100644 --- a/src/main/java/io/github/spencerpark/ijava/execution/EvaluationInterruptedException.java +++ b/src/main/java/io/github/spencerpark/ijava/execution/EvaluationInterruptedException.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/execution/EvaluationTimeoutException.java b/src/main/java/io/github/spencerpark/ijava/execution/EvaluationTimeoutException.java index fbabce8..075dbb9 100644 --- a/src/main/java/io/github/spencerpark/ijava/execution/EvaluationTimeoutException.java +++ b/src/main/java/io/github/spencerpark/ijava/execution/EvaluationTimeoutException.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/execution/IJavaExecutionControl.java b/src/main/java/io/github/spencerpark/ijava/execution/IJavaExecutionControl.java index 9c14e44..3d93392 100644 --- a/src/main/java/io/github/spencerpark/ijava/execution/IJavaExecutionControl.java +++ b/src/main/java/io/github/spencerpark/ijava/execution/IJavaExecutionControl.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/execution/IJavaExecutionControlProvider.java b/src/main/java/io/github/spencerpark/ijava/execution/IJavaExecutionControlProvider.java index 600021d..2b9f2a5 100644 --- a/src/main/java/io/github/spencerpark/ijava/execution/IJavaExecutionControlProvider.java +++ b/src/main/java/io/github/spencerpark/ijava/execution/IJavaExecutionControlProvider.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -47,6 +47,14 @@ public class IJavaExecutionControlProvider implements ExecutionControlProvider { */ public static final String TIMEOUT_KEY = "timeout"; + /** + * Default per-statement timeout applied when no {@value #TIMEOUT_KEY} parameter is + * configured. Suits classroom use where a runaway statement should not hang the + * kernel indefinitely. Set {@code IJAVA_TIMEOUT=-1} to disable the timeout. + */ + public static final long DEFAULT_TIMEOUT = 60; + public static final TimeUnit DEFAULT_TIMEOUT_UNIT = TimeUnit.SECONDS; + private static final Pattern TIMEOUT_PATTERN = Pattern.compile("^(?-?\\d+)\\W*(?[A-Za-z]+)?$"); private final Map controllers = new WeakHashMap<>(); @@ -62,8 +70,8 @@ public String name() { @Override public ExecutionControl generate(ExecutionEnv env, Map parameters) throws Throwable { - long timeout = -1; - TimeUnit timeUnit = TimeUnit.MILLISECONDS; + long timeout = DEFAULT_TIMEOUT; + TimeUnit timeUnit = DEFAULT_TIMEOUT_UNIT; String timeoutRaw = parameters.get(TIMEOUT_KEY); if (timeoutRaw != null) { diff --git a/src/main/java/io/github/spencerpark/ijava/execution/IncompleteSourceException.java b/src/main/java/io/github/spencerpark/ijava/execution/IncompleteSourceException.java index e8f3c73..66f6d95 100644 --- a/src/main/java/io/github/spencerpark/ijava/execution/IncompleteSourceException.java +++ b/src/main/java/io/github/spencerpark/ijava/execution/IncompleteSourceException.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/execution/LazyInputStreamDelegate.java b/src/main/java/io/github/spencerpark/ijava/execution/LazyInputStreamDelegate.java index 9c23620..c8605e3 100644 --- a/src/main/java/io/github/spencerpark/ijava/execution/LazyInputStreamDelegate.java +++ b/src/main/java/io/github/spencerpark/ijava/execution/LazyInputStreamDelegate.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/execution/LazyOutputStreamDelegate.java b/src/main/java/io/github/spencerpark/ijava/execution/LazyOutputStreamDelegate.java index a720b50..0fcce36 100644 --- a/src/main/java/io/github/spencerpark/ijava/execution/LazyOutputStreamDelegate.java +++ b/src/main/java/io/github/spencerpark/ijava/execution/LazyOutputStreamDelegate.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/execution/MagicsSourceTransformer.java b/src/main/java/io/github/spencerpark/ijava/execution/MagicsSourceTransformer.java index b5abe31..fedd118 100644 --- a/src/main/java/io/github/spencerpark/ijava/execution/MagicsSourceTransformer.java +++ b/src/main/java/io/github/spencerpark/ijava/execution/MagicsSourceTransformer.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/magics/BenchmarkMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/BenchmarkMagics.java index f0ef6af..7289a52 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/BenchmarkMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/BenchmarkMagics.java @@ -19,7 +19,11 @@ public void benchmark(List args, String body) throws Exception { System.out.println("## %%benchmark - Compare implementations performance\n\n" + "Usage: %%benchmark [--help] [--sweep var= start= end= step=] [--chart] [iterations=] [warmup=]\\n\n" + "Provide one or more implementations separated by a line containing '---'.\n" + - "Example:\n%%benchmark iterations=5\ncode-for-impl-1\n---\ncode-for-impl-2\n"); + "Example:\n%%benchmark iterations=5\ncode-for-impl-1\n---\ncode-for-impl-2\n\n" + + "NOTE: timings are measured through jshell snippet evaluation, so they include\n" + + "snippet compilation and dispatch overhead. Use %%benchmark for classroom-level\n" + + "comparisons only. For publication-grade microbenchmarks use JMH, e.g.\n" + + " %%maven org.openjdk.jmh:jmh-core:1.37\n"); return; } diff --git a/src/main/java/io/github/spencerpark/ijava/magics/ClasspathMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/ClasspathMagics.java index 6146880..c0ed0dc 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/ClasspathMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/ClasspathMagics.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/magics/CompilerMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/CompilerMagics.java index 66f039d..1ba30c5 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/CompilerMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/CompilerMagics.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/magics/MagicsTool.java b/src/main/java/io/github/spencerpark/ijava/magics/MagicsTool.java index 53da942..636ca2b 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/MagicsTool.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/MagicsTool.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/magics/MavenResolver.java b/src/main/java/io/github/spencerpark/ijava/magics/MavenResolver.java index 2cfe641..f59bcf3 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/MavenResolver.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/MavenResolver.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/magics/PrinterMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/PrinterMagics.java index 6605330..ba5d794 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/PrinterMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/PrinterMagics.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/magics/ShellMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/ShellMagics.java index 3138151..7b90be9 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/ShellMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/ShellMagics.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/magics/TimeItMagics.java b/src/main/java/io/github/spencerpark/ijava/magics/TimeItMagics.java index 68cd909..fb5e4fb 100644 --- a/src/main/java/io/github/spencerpark/ijava/magics/TimeItMagics.java +++ b/src/main/java/io/github/spencerpark/ijava/magics/TimeItMagics.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/runtime/Display.java b/src/main/java/io/github/spencerpark/ijava/runtime/Display.java index 4ad646f..872ffad 100644 --- a/src/main/java/io/github/spencerpark/ijava/runtime/Display.java +++ b/src/main/java/io/github/spencerpark/ijava/runtime/Display.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/runtime/Kernel.java b/src/main/java/io/github/spencerpark/ijava/runtime/Kernel.java index 98d0b8c..11a26ee 100644 --- a/src/main/java/io/github/spencerpark/ijava/runtime/Kernel.java +++ b/src/main/java/io/github/spencerpark/ijava/runtime/Kernel.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/runtime/Magics.java b/src/main/java/io/github/spencerpark/ijava/runtime/Magics.java index c0f6ffc..0fb24ae 100644 --- a/src/main/java/io/github/spencerpark/ijava/runtime/Magics.java +++ b/src/main/java/io/github/spencerpark/ijava/runtime/Magics.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/utils/FileUtils.java b/src/main/java/io/github/spencerpark/ijava/utils/FileUtils.java index 7775594..d7b3a31 100644 --- a/src/main/java/io/github/spencerpark/ijava/utils/FileUtils.java +++ b/src/main/java/io/github/spencerpark/ijava/utils/FileUtils.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/utils/ResolveDependency.java b/src/main/java/io/github/spencerpark/ijava/utils/ResolveDependency.java index 4b16c62..aa891ed 100644 --- a/src/main/java/io/github/spencerpark/ijava/utils/ResolveDependency.java +++ b/src/main/java/io/github/spencerpark/ijava/utils/ResolveDependency.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/ijava/utils/RuntimeCompiler.java b/src/main/java/io/github/spencerpark/ijava/utils/RuntimeCompiler.java index 848ca14..3ea83fd 100644 --- a/src/main/java/io/github/spencerpark/ijava/utils/RuntimeCompiler.java +++ b/src/main/java/io/github/spencerpark/ijava/utils/RuntimeCompiler.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/jupyter/kernel/util/StringStyler.java b/src/main/java/io/github/spencerpark/jupyter/kernel/util/StringStyler.java index a929603..c836f0b 100644 --- a/src/main/java/io/github/spencerpark/jupyter/kernel/util/StringStyler.java +++ b/src/main/java/io/github/spencerpark/jupyter/kernel/util/StringStyler.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/java/io/github/spencerpark/jupyter/kernel/util/TextColor.java b/src/main/java/io/github/spencerpark/jupyter/kernel/util/TextColor.java index e0d3fc2..aeda199 100644 --- a/src/main/java/io/github/spencerpark/jupyter/kernel/util/TextColor.java +++ b/src/main/java/io/github/spencerpark/jupyter/kernel/util/TextColor.java @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2025 ${author} + * Copyright (c) 2025 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal diff --git a/src/main/resources/print.jshell b/src/main/resources/print.jshell index d97c6ae..b09bd78 100644 --- a/src/main/resources/print.jshell +++ b/src/main/resources/print.jshell @@ -1,7 +1,7 @@ /* * The MIT License (MIT) * - * Copyright (c) 2022 ${author} + * Copyright (c) 2022 ebpro * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal From c16a28e567959478876a99114a89b10ebddc6419 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Wed, 2 Sep 2026 09:26:23 +0200 Subject: [PATCH 32/49] fix(build): filter version placeholders into kernel metadata --- build.gradle | 12 +++++++++++- src/main/resources/ijava-kernel-metadata.json | 4 ++-- src/main/resources/kernel-metadata.json | 4 ++++ src/main/resources/kernel.json | 2 +- 4 files changed, 18 insertions(+), 4 deletions(-) create mode 100644 src/main/resources/kernel-metadata.json diff --git a/build.gradle b/build.gradle index 93b4205..c7ab712 100644 --- a/build.gradle +++ b/build.gradle @@ -6,7 +6,7 @@ plugins { group = 'io.github.spencerpark' // Allow overriding version from command line via `-Pversion=...` -version = (project.findProperty('version') ?: '1.4.5').toString() +version = (gradle.startParameter.projectProperties.get('version') ?: '1.4.5').toString() // Java configuration java { @@ -83,6 +83,16 @@ tasks.withType(JavaCompile).configureEach { options.release = 21 } +// Resource filtering +processResources { + filesMatching(['ijava-kernel-metadata.json', 'kernel-metadata.json', 'kernel.json']) { + expand( + project: rootProject.name, + version: project.version + ) + } +} + // Shadow JAR configuration shadowJar { archiveClassifier.set('all') diff --git a/src/main/resources/ijava-kernel-metadata.json b/src/main/resources/ijava-kernel-metadata.json index f200f68..8dc7911 100644 --- a/src/main/resources/ijava-kernel-metadata.json +++ b/src/main/resources/ijava-kernel-metadata.json @@ -1,4 +1,4 @@ { - "version": "@version@", - "project": "@project@" + "version": "${version}", + "project": "${project}" } \ No newline at end of file diff --git a/src/main/resources/kernel-metadata.json b/src/main/resources/kernel-metadata.json new file mode 100644 index 0000000..9ca8a85 --- /dev/null +++ b/src/main/resources/kernel-metadata.json @@ -0,0 +1,4 @@ +{ + "version": "${version}", + "project": "${project}" +} diff --git a/src/main/resources/kernel.json b/src/main/resources/kernel.json index 08da2bc..e0af8b7 100644 --- a/src/main/resources/kernel.json +++ b/src/main/resources/kernel.json @@ -2,7 +2,7 @@ "argv": [ "java", "-jar", - "@KERNEL_INSTALL_DIRECTORY@/@project@-@version@-all.jar", + "@KERNEL_INSTALL_DIRECTORY@/${project}-${version}-all.jar", "{connection_file}" ], "display_name": "Java", From b7c6730a16022a086aedd510bc35e46e3454628c Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Wed, 2 Sep 2026 16:38:48 +0200 Subject: [PATCH 33/49] chore(build): upgrade to JDK 25 and Gradle 9.7.1 --- .github/workflows/build-release.yml | 8 +- README.md | 10 +- build.gradle | 20 +- gradle/wrapper/gradle-wrapper.jar | Bin 54708 -> 43462 bytes gradle/wrapper/gradle-wrapper.properties | 15 +- gradlew | 301 ++++++++++++++--------- gradlew.bat | 56 +++-- settings.gradle | 6 +- 8 files changed, 249 insertions(+), 167 deletions(-) diff --git a/.github/workflows/build-release.yml b/.github/workflows/build-release.yml index 589c6f1..4d03352 100644 --- a/.github/workflows/build-release.yml +++ b/.github/workflows/build-release.yml @@ -38,11 +38,11 @@ jobs: with: fetch-depth: 0 - - name: Set up JDK 21 + - name: Set up JDK 25 uses: actions/setup-java@v4 with: distribution: 'temurin' - java-version: '21' + java-version: '25' cache: 'gradle' - name: Determine tag @@ -94,11 +94,11 @@ jobs: with: name: distribution - - name: Set up JDK 21 for smoke-test + - name: Set up JDK 25 for smoke-test uses: actions/setup-java@v4 with: distribution: 'temurin' - java-version: '21' + java-version: '25' - name: Run smoke test run: | diff --git a/README.md b/README.md index 2adcf89..c28d3e9 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ Fork from [SpencerPark](https://github.com/SpencerPark)/[IJava](https://github.com/SpencerPark/IJava), but with some new features and magics: -* Upgrade to jdk 17 and gradle 7.3.3 +* Upgrade to JDK 25 and Gradle 9.7.1 * Print with variable name or source ![timeout](docs/img/print-with-var-name.png) * add `print` function and `printerPrefix` line magic @@ -95,14 +95,14 @@ Currently the kernel supports ### Requirements -1. [Java JDK >= 21](http://www.oracle.com/technetwork/java/javase/downloads/index.html). **Not the JRE**. +1. [Java JDK >= 25](http://www.oracle.com/technetwork/java/javase/downloads/index.html). **Not the JRE**. 1. Ensure that the `java` command is in the PATH and is using a modern version. For example: ```bash > java -version - openjdk version "21.0.11" 2026-04-21 - OpenJDK Runtime Environment Temurin-21.0.11+10 (build 21.0.11+10) - OpenJDK 64-Bit Server VM Temurin-21.0.11+10 (build 21.0.11+10, mixed mode, sharing) + openjdk version "25.0.4" + OpenJDK Runtime Environment Temurin-25.0.4 (build 25.0.4) + OpenJDK 64-Bit Server VM Temurin-25.0.4 (build 25.0.4, mixed mode, sharing) ``` 2. Next ensure that `java` is in a location where the jdk was installed and not just the jre. Use diff --git a/build.gradle b/build.gradle index c7ab712..6e23d60 100644 --- a/build.gradle +++ b/build.gradle @@ -1,7 +1,6 @@ plugins { id 'java-library' - id 'com.github.johnrengelman.shadow' version '8.1.1' - id 'io.github.gradle-nexus.publish-plugin' version '1.3.0' + id 'com.gradleup.shadow' version '9.6.1' } group = 'io.github.spencerpark' @@ -11,7 +10,7 @@ version = (gradle.startParameter.projectProperties.get('version') ?: '1.4.5').to // Java configuration java { toolchain { - languageVersion = JavaLanguageVersion.of(21) + languageVersion = JavaLanguageVersion.of(25) } withJavadocJar() withSourcesJar() @@ -37,7 +36,8 @@ def versions = [ mavenResolver: '1.8.2', mavenProvider: '3.8.6', logback: '1.5.7', - junit: '4.13.2' + junit: '4.13.2', + lombok: '1.18.48' ] dependencies { @@ -70,8 +70,8 @@ dependencies { // ClassGraph for classpath scanning implementation 'io.github.classgraph:classgraph:4.8.168' // Lombok for annotations processing - compileOnly 'org.projectlombok:lombok:1.18.30' - annotationProcessor 'org.projectlombok:lombok:1.18.30' + compileOnly "org.projectlombok:lombok:${versions.lombok}" + annotationProcessor "org.projectlombok:lombok:${versions.lombok}" } @@ -80,15 +80,17 @@ tasks.withType(JavaCompile).configureEach { options.encoding = 'UTF-8' options.compilerArgs << '-parameters' options.deprecation = true - options.release = 21 + options.release = 25 } // Resource filtering +def kernelProjectName = rootProject.name +def kernelVersion = project.version processResources { filesMatching(['ijava-kernel-metadata.json', 'kernel-metadata.json', 'kernel.json']) { expand( - project: rootProject.name, - version: project.version + project: kernelProjectName, + version: kernelVersion ) } } diff --git a/gradle/wrapper/gradle-wrapper.jar b/gradle/wrapper/gradle-wrapper.jar index 736fb7d3f94c051b359fc7ae7212d351bc094bdd..d64cd4917707c1f8861d8cb53dd15194d4248596 100644 GIT binary patch literal 43462 zcma&NWl&^owk(X(xVyW%ySuwf;qI=D6|RlDJ2cR^yEKh!@I- zp9QeisK*rlxC>+~7Dk4IxIRsKBHqdR9b3+fyL=ynHmIDe&|>O*VlvO+%z5;9Z$|DJ zb4dO}-R=MKr^6EKJiOrJdLnCJn>np?~vU-1sSFgPu;pthGwf}bG z(1db%xwr#x)r+`4AGu$j7~u2MpVs3VpLp|mx&;>`0p0vH6kF+D2CY0fVdQOZ@h;A` z{infNyvmFUiu*XG}RNMNwXrbec_*a3N=2zJ|Wh5z* z5rAX$JJR{#zP>KY**>xHTuw?|-Rg|o24V)74HcfVT;WtQHXlE+_4iPE8QE#DUm%x0 zEKr75ur~W%w#-My3Tj`hH6EuEW+8K-^5P62$7Sc5OK+22qj&Pd1;)1#4tKihi=~8C zHiQSst0cpri6%OeaR`PY>HH_;CPaRNty%WTm4{wDK8V6gCZlG@U3$~JQZ;HPvDJcT1V{ z?>H@13MJcCNe#5z+MecYNi@VT5|&UiN1D4ATT+%M+h4c$t;C#UAs3O_q=GxK0}8%8 z8J(_M9bayxN}69ex4dzM_P3oh@ZGREjVvn%%r7=xjkqxJP4kj}5tlf;QosR=%4L5y zWhgejO=vao5oX%mOHbhJ8V+SG&K5dABn6!WiKl{|oPkq(9z8l&Mm%(=qGcFzI=eLu zWc_oCLyf;hVlB@dnwY98?75B20=n$>u3b|NB28H0u-6Rpl((%KWEBOfElVWJx+5yg z#SGqwza7f}$z;n~g%4HDU{;V{gXIhft*q2=4zSezGK~nBgu9-Q*rZ#2f=Q}i2|qOp z!!y4p)4o=LVUNhlkp#JL{tfkhXNbB=Ox>M=n6soptJw-IDI|_$is2w}(XY>a=H52d z3zE$tjPUhWWS+5h=KVH&uqQS=$v3nRs&p$%11b%5qtF}S2#Pc`IiyBIF4%A!;AVoI zXU8-Rpv!DQNcF~(qQnyyMy=-AN~U>#&X1j5BLDP{?K!%h!;hfJI>$mdLSvktEr*89 zdJHvby^$xEX0^l9g$xW-d?J;L0#(`UT~zpL&*cEh$L|HPAu=P8`OQZV!-}l`noSp_ zQ-1$q$R-gDL)?6YaM!=8H=QGW$NT2SeZlb8PKJdc=F-cT@j7Xags+Pr*jPtlHFnf- zh?q<6;)27IdPc^Wdy-mX%2s84C1xZq9Xms+==F4);O`VUASmu3(RlgE#0+#giLh-& zcxm3_e}n4{%|X zJp{G_j+%`j_q5}k{eW&TlP}J2wtZ2^<^E(O)4OQX8FDp6RJq!F{(6eHWSD3=f~(h} zJXCf7=r<16X{pHkm%yzYI_=VDP&9bmI1*)YXZeB}F? z(%QsB5fo*FUZxK$oX~X^69;x~j7ms8xlzpt-T15e9}$4T-pC z6PFg@;B-j|Ywajpe4~bk#S6(fO^|mm1hKOPfA%8-_iGCfICE|=P_~e;Wz6my&)h_~ zkv&_xSAw7AZ%ThYF(4jADW4vg=oEdJGVOs>FqamoL3Np8>?!W#!R-0%2Bg4h?kz5I zKV-rKN2n(vUL%D<4oj@|`eJ>0i#TmYBtYmfla;c!ATW%;xGQ0*TW@PTlGG><@dxUI zg>+3SiGdZ%?5N=8uoLA|$4isK$aJ%i{hECP$bK{J#0W2gQ3YEa zZQ50Stn6hqdfxJ*9#NuSLwKFCUGk@c=(igyVL;;2^wi4o30YXSIb2g_ud$ zgpCr@H0qWtk2hK8Q|&wx)}4+hTYlf;$a4#oUM=V@Cw#!$(nOFFpZ;0lc!qd=c$S}Z zGGI-0jg~S~cgVT=4Vo)b)|4phjStD49*EqC)IPwyeKBLcN;Wu@Aeph;emROAwJ-0< z_#>wVm$)ygH|qyxZaet&(Vf%pVdnvKWJn9`%DAxj3ot;v>S$I}jJ$FLBF*~iZ!ZXE zkvui&p}fI0Y=IDX)mm0@tAd|fEHl~J&K}ZX(Mm3cm1UAuwJ42+AO5@HwYfDH7ipIc zmI;1J;J@+aCNG1M`Btf>YT>~c&3j~Qi@Py5JT6;zjx$cvOQW@3oQ>|}GH?TW-E z1R;q^QFjm5W~7f}c3Ww|awg1BAJ^slEV~Pk`Kd`PS$7;SqJZNj->it4DW2l15}xP6 zoCl$kyEF%yJni0(L!Z&14m!1urXh6Btj_5JYt1{#+H8w?5QI%% zo-$KYWNMJVH?Hh@1n7OSu~QhSswL8x0=$<8QG_zepi_`y_79=nK=_ZP_`Em2UI*tyQoB+r{1QYZCpb?2OrgUw#oRH$?^Tj!Req>XiE#~B|~ z+%HB;=ic+R@px4Ld8mwpY;W^A%8%l8$@B@1m5n`TlKI6bz2mp*^^^1mK$COW$HOfp zUGTz-cN9?BGEp}5A!mDFjaiWa2_J2Iq8qj0mXzk; z66JBKRP{p%wN7XobR0YjhAuW9T1Gw3FDvR5dWJ8ElNYF94eF3ebu+QwKjtvVu4L zI9ip#mQ@4uqVdkl-TUQMb^XBJVLW(-$s;Nq;@5gr4`UfLgF$adIhd?rHOa%D);whv z=;krPp~@I+-Z|r#s3yCH+c1US?dnm+C*)r{m+86sTJusLdNu^sqLrfWed^ndHXH`m zd3#cOe3>w-ga(Dus_^ppG9AC>Iq{y%%CK+Cro_sqLCs{VLuK=dev>OL1dis4(PQ5R zcz)>DjEkfV+MO;~>VUlYF00SgfUo~@(&9$Iy2|G0T9BSP?&T22>K46D zL*~j#yJ?)^*%J3!16f)@Y2Z^kS*BzwfAQ7K96rFRIh>#$*$_Io;z>ux@}G98!fWR@ zGTFxv4r~v)Gsd|pF91*-eaZ3Qw1MH$K^7JhWIdX%o$2kCbvGDXy)a?@8T&1dY4`;L z4Kn+f%SSFWE_rpEpL9bnlmYq`D!6F%di<&Hh=+!VI~j)2mfil03T#jJ_s?}VV0_hp z7T9bWxc>Jm2Z0WMU?`Z$xE74Gu~%s{mW!d4uvKCx@WD+gPUQ zV0vQS(Ig++z=EHN)BR44*EDSWIyT~R4$FcF*VEY*8@l=218Q05D2$|fXKFhRgBIEE zdDFB}1dKkoO^7}{5crKX!p?dZWNz$m>1icsXG2N+((x0OIST9Zo^DW_tytvlwXGpn zs8?pJXjEG;T@qrZi%#h93?FP$!&P4JA(&H61tqQi=opRzNpm zkrG}$^t9&XduK*Qa1?355wd8G2CI6QEh@Ua>AsD;7oRUNLPb76m4HG3K?)wF~IyS3`fXuNM>${?wmB zpVz;?6_(Fiadfd{vUCBM*_kt$+F3J+IojI;9L(gc9n3{sEZyzR9o!_mOwFC#tQ{Q~ zP3-`#uK#tP3Q7~Q;4H|wjZHO8h7e4IuBxl&vz2w~D8)w=Wtg31zpZhz%+kzSzL*dV zwp@{WU4i;hJ7c2f1O;7Mz6qRKeASoIv0_bV=i@NMG*l<#+;INk-^`5w@}Dj~;k=|}qM1vq_P z|GpBGe_IKq|LNy9SJhKOQ$c=5L{Dv|Q_lZl=-ky*BFBJLW9&y_C|!vyM~rQx=!vun z?rZJQB5t}Dctmui5i31C_;_}CEn}_W%>oSXtt>@kE1=JW*4*v4tPp;O6 zmAk{)m!)}34pTWg8{i>($%NQ(Tl;QC@J@FfBoc%Gr&m560^kgSfodAFrIjF}aIw)X zoXZ`@IsMkc8_=w%-7`D6Y4e*CG8k%Ud=GXhsTR50jUnm+R*0A(O3UKFg0`K;qp1bl z7``HN=?39ic_kR|^R^~w-*pa?Vj#7|e9F1iRx{GN2?wK!xR1GW!qa=~pjJb-#u1K8 zeR?Y2i-pt}yJq;SCiVHODIvQJX|ZJaT8nO+(?HXbLefulKKgM^B(UIO1r+S=7;kLJ zcH}1J=Px2jsh3Tec&v8Jcbng8;V-`#*UHt?hB(pmOipKwf3Lz8rG$heEB30Sg*2rx zV<|KN86$soN(I!BwO`1n^^uF2*x&vJ$2d$>+`(romzHP|)K_KkO6Hc>_dwMW-M(#S zK(~SiXT1@fvc#U+?|?PniDRm01)f^#55;nhM|wi?oG>yBsa?~?^xTU|fX-R(sTA+5 zaq}-8Tx7zrOy#3*JLIIVsBmHYLdD}!0NP!+ITW+Thn0)8SS!$@)HXwB3tY!fMxc#1 zMp3H?q3eD?u&Njx4;KQ5G>32+GRp1Ee5qMO0lZjaRRu&{W<&~DoJNGkcYF<5(Ab+J zgO>VhBl{okDPn78<%&e2mR{jwVCz5Og;*Z;;3%VvoGo_;HaGLWYF7q#jDX=Z#Ml`H z858YVV$%J|e<1n`%6Vsvq7GmnAV0wW4$5qQ3uR@1i>tW{xrl|ExywIc?fNgYlA?C5 zh$ezAFb5{rQu6i7BSS5*J-|9DQ{6^BVQ{b*lq`xS@RyrsJN?-t=MTMPY;WYeKBCNg z^2|pN!Q^WPJuuO4!|P@jzt&tY1Y8d%FNK5xK(!@`jO2aEA*4 zkO6b|UVBipci?){-Ke=+1;mGlND8)6+P;8sq}UXw2hn;fc7nM>g}GSMWu&v&fqh

iViYT=fZ(|3Ox^$aWPp4a8h24tD<|8-!aK0lHgL$N7Efw}J zVIB!7=T$U`ao1?upi5V4Et*-lTG0XvExbf!ya{cua==$WJyVG(CmA6Of*8E@DSE%L z`V^$qz&RU$7G5mg;8;=#`@rRG`-uS18$0WPN@!v2d{H2sOqP|!(cQ@ zUHo!d>>yFArLPf1q`uBvY32miqShLT1B@gDL4XoVTK&@owOoD)OIHXrYK-a1d$B{v zF^}8D3Y^g%^cnvScOSJR5QNH+BI%d|;J;wWM3~l>${fb8DNPg)wrf|GBP8p%LNGN# z3EaIiItgwtGgT&iYCFy9-LG}bMI|4LdmmJt@V@% zb6B)1kc=T)(|L@0;wr<>=?r04N;E&ef+7C^`wPWtyQe(*pD1pI_&XHy|0gIGHMekd zF_*M4yi6J&Z4LQj65)S zXwdM{SwUo%3SbPwFsHgqF@V|6afT|R6?&S;lw=8% z3}@9B=#JI3@B*#4s!O))~z zc>2_4Q_#&+5V`GFd?88^;c1i7;Vv_I*qt!_Yx*n=;rj!82rrR2rQ8u5(Ejlo{15P% zs~!{%XJ>FmJ})H^I9bn^Re&38H{xA!0l3^89k(oU;bZWXM@kn$#aoS&Y4l^-WEn-fH39Jb9lA%s*WsKJQl?n9B7_~P z-XM&WL7Z!PcoF6_D>V@$CvUIEy=+Z&0kt{szMk=f1|M+r*a43^$$B^MidrT0J;RI` z(?f!O<8UZkm$_Ny$Hth1J#^4ni+im8M9mr&k|3cIgwvjAgjH z8`N&h25xV#v*d$qBX5jkI|xOhQn!>IYZK7l5#^P4M&twe9&Ey@@GxYMxBZq2e7?`q z$~Szs0!g{2fGcp9PZEt|rdQ6bhAgpcLHPz?f-vB?$dc*!9OL?Q8mn7->bFD2Si60* z!O%y)fCdMSV|lkF9w%x~J*A&srMyYY3{=&$}H zGQ4VG_?$2X(0|vT0{=;W$~icCI{b6W{B!Q8xdGhF|D{25G_5_+%s(46lhvNLkik~R z>nr(&C#5wwOzJZQo9m|U<;&Wk!_#q|V>fsmj1g<6%hB{jGoNUPjgJslld>xmODzGjYc?7JSuA?A_QzjDw5AsRgi@Y|Z0{F{!1=!NES-#*f^s4l0Hu zz468))2IY5dmD9pa*(yT5{EyP^G>@ZWumealS-*WeRcZ}B%gxq{MiJ|RyX-^C1V=0 z@iKdrGi1jTe8Ya^x7yyH$kBNvM4R~`fbPq$BzHum-3Zo8C6=KW@||>zsA8-Y9uV5V z#oq-f5L5}V<&wF4@X@<3^C%ptp6+Ce)~hGl`kwj)bsAjmo_GU^r940Z-|`<)oGnh7 zFF0Tde3>ui?8Yj{sF-Z@)yQd~CGZ*w-6p2U<8}JO-sRsVI5dBji`01W8A&3$?}lxBaC&vn0E$c5tW* zX>5(zzZ=qn&!J~KdsPl;P@bmA-Pr8T*)eh_+Dv5=Ma|XSle6t(k8qcgNyar{*ReQ8 zTXwi=8vr>!3Ywr+BhggHDw8ke==NTQVMCK`$69fhzEFB*4+H9LIvdt-#IbhZvpS}} zO3lz;P?zr0*0$%-Rq_y^k(?I{Mk}h@w}cZpMUp|ucs55bcloL2)($u%mXQw({Wzc~ z;6nu5MkjP)0C(@%6Q_I_vsWrfhl7Zpoxw#WoE~r&GOSCz;_ro6i(^hM>I$8y>`!wW z*U^@?B!MMmb89I}2(hcE4zN2G^kwyWCZp5JG>$Ez7zP~D=J^LMjSM)27_0B_X^C(M z`fFT+%DcKlu?^)FCK>QzSnV%IsXVcUFhFdBP!6~se&xxrIxsvySAWu++IrH;FbcY$ z2DWTvSBRfLwdhr0nMx+URA$j3i7_*6BWv#DXfym?ZRDcX9C?cY9sD3q)uBDR3uWg= z(lUIzB)G$Hr!){>E{s4Dew+tb9kvToZp-1&c?y2wn@Z~(VBhqz`cB;{E4(P3N2*nJ z_>~g@;UF2iG{Kt(<1PyePTKahF8<)pozZ*xH~U-kfoAayCwJViIrnqwqO}7{0pHw$ zs2Kx?s#vQr7XZ264>5RNKSL8|Ty^=PsIx^}QqOOcfpGUU4tRkUc|kc7-!Ae6!+B{o~7nFpm3|G5^=0#Bnm6`V}oSQlrX(u%OWnC zoLPy&Q;1Jui&7ST0~#+}I^&?vcE*t47~Xq#YwvA^6^} z`WkC)$AkNub|t@S!$8CBlwbV~?yp&@9h{D|3z-vJXgzRC5^nYm+PyPcgRzAnEi6Q^gslXYRv4nycsy-SJu?lMps-? zV`U*#WnFsdPLL)Q$AmD|0`UaC4ND07+&UmOu!eHruzV|OUox<+Jl|Mr@6~C`T@P%s zW7sgXLF2SSe9Fl^O(I*{9wsFSYb2l%-;&Pi^dpv!{)C3d0AlNY6!4fgmSgj_wQ*7Am7&$z;Jg&wgR-Ih;lUvWS|KTSg!&s_E9_bXBkZvGiC6bFKDWZxsD$*NZ#_8bl zG1P-#@?OQzED7@jlMJTH@V!6k;W>auvft)}g zhoV{7$q=*;=l{O>Q4a@ ziMjf_u*o^PsO)#BjC%0^h>Xp@;5$p{JSYDt)zbb}s{Kbt!T*I@Pk@X0zds6wsefuU zW$XY%yyRGC94=6mf?x+bbA5CDQ2AgW1T-jVAJbm7K(gp+;v6E0WI#kuACgV$r}6L? zd|Tj?^%^*N&b>Dd{Wr$FS2qI#Ucs1yd4N+RBUQiSZGujH`#I)mG&VKoDh=KKFl4=G z&MagXl6*<)$6P}*Tiebpz5L=oMaPrN+caUXRJ`D?=K9!e0f{@D&cZLKN?iNP@X0aF zE(^pl+;*T5qt?1jRC=5PMgV!XNITRLS_=9{CJExaQj;lt!&pdzpK?8p>%Mb+D z?yO*uSung=-`QQ@yX@Hyd4@CI^r{2oiu`%^bNkz+Nkk!IunjwNC|WcqvX~k=><-I3 zDQdbdb|!v+Iz01$w@aMl!R)koD77Xp;eZwzSl-AT zr@Vu{=xvgfq9akRrrM)}=!=xcs+U1JO}{t(avgz`6RqiiX<|hGG1pmop8k6Q+G_mv zJv|RfDheUp2L3=^C=4aCBMBn0aRCU(DQwX-W(RkRwmLeuJYF<0urcaf(=7)JPg<3P zQs!~G)9CT18o!J4{zX{_e}4eS)U-E)0FAt}wEI(c0%HkxgggW;(1E=>J17_hsH^sP z%lT0LGgbUXHx-K*CI-MCrP66UP0PvGqM$MkeLyqHdbgP|_Cm!7te~b8p+e6sQ_3k| zVcwTh6d83ltdnR>D^)BYQpDKlLk3g0Hdcgz2}%qUs9~~Rie)A-BV1mS&naYai#xcZ z(d{8=-LVpTp}2*y)|gR~;qc7fp26}lPcLZ#=JpYcn3AT9(UIdOyg+d(P5T7D&*P}# zQCYplZO5|7+r19%9e`v^vfSS1sbX1c%=w1;oyruXB%Kl$ACgKQ6=qNWLsc=28xJjg zwvsI5-%SGU|3p>&zXVl^vVtQT3o-#$UT9LI@Npz~6=4!>mc431VRNN8od&Ul^+G_kHC`G=6WVWM z%9eWNyy(FTO|A+@x}Ou3CH)oi;t#7rAxdIXfNFwOj_@Y&TGz6P_sqiB`Q6Lxy|Q{`|fgmRG(k+!#b*M+Z9zFce)f-7;?Km5O=LHV9f9_87; zF7%R2B+$?@sH&&-$@tzaPYkw0;=i|;vWdI|Wl3q_Zu>l;XdIw2FjV=;Mq5t1Q0|f< zs08j54Bp`3RzqE=2enlkZxmX6OF+@|2<)A^RNQpBd6o@OXl+i)zO%D4iGiQNuXd+zIR{_lb96{lc~bxsBveIw6umhShTX+3@ZJ=YHh@ zWY3(d0azg;7oHn>H<>?4@*RQbi>SmM=JrHvIG(~BrvI)#W(EAeO6fS+}mxxcc+X~W6&YVl86W9WFSS}Vz-f9vS?XUDBk)3TcF z8V?$4Q)`uKFq>xT=)Y9mMFVTUk*NIA!0$?RP6Ig0TBmUFrq*Q-Agq~DzxjStQyJ({ zBeZ;o5qUUKg=4Hypm|}>>L=XKsZ!F$yNTDO)jt4H0gdQ5$f|d&bnVCMMXhNh)~mN z@_UV6D7MVlsWz+zM+inZZp&P4fj=tm6fX)SG5H>OsQf_I8c~uGCig$GzuwViK54bcgL;VN|FnyQl>Ed7(@>=8$a_UKIz|V6CeVSd2(P z0Uu>A8A+muM%HLFJQ9UZ5c)BSAv_zH#1f02x?h9C}@pN@6{>UiAp>({Fn(T9Q8B z^`zB;kJ5b`>%dLm+Ol}ty!3;8f1XDSVX0AUe5P#@I+FQ-`$(a;zNgz)4x5hz$Hfbg z!Q(z26wHLXko(1`;(BAOg_wShpX0ixfWq3ponndY+u%1gyX)_h=v1zR#V}#q{au6; z!3K=7fQwnRfg6FXtNQmP>`<;!N137paFS%y?;lb1@BEdbvQHYC{976l`cLqn;b8lp zIDY>~m{gDj(wfnK!lpW6pli)HyLEiUrNc%eXTil|F2s(AY+LW5hkKb>TQ3|Q4S9rr zpDs4uK_co6XPsn_z$LeS{K4jFF`2>U`tbgKdyDne`xmR<@6AA+_hPNKCOR-Zqv;xk zu5!HsBUb^!4uJ7v0RuH-7?l?}b=w5lzzXJ~gZcxRKOovSk@|#V+MuX%Y+=;14i*%{)_gSW9(#4%)AV#3__kac1|qUy!uyP{>?U#5wYNq}y$S9pCc zFc~4mgSC*G~j0u#qqp9 z${>3HV~@->GqEhr_Xwoxq?Hjn#=s2;i~g^&Hn|aDKpA>Oc%HlW(KA1?BXqpxB;Ydx)w;2z^MpjJ(Qi(X!$5RC z*P{~%JGDQqojV>2JbEeCE*OEu!$XJ>bWA9Oa_Hd;y)F%MhBRi*LPcdqR8X`NQ&1L# z5#9L*@qxrx8n}LfeB^J{%-?SU{FCwiWyHp682F+|pa+CQa3ZLzBqN1{)h4d6+vBbV zC#NEbQLC;}me3eeYnOG*nXOJZEU$xLZ1<1Y=7r0(-U0P6-AqwMAM`a(Ed#7vJkn6plb4eI4?2y3yOTGmmDQ!z9`wzbf z_OY#0@5=bnep;MV0X_;;SJJWEf^E6Bd^tVJ9znWx&Ks8t*B>AM@?;D4oWUGc z!H*`6d7Cxo6VuyS4Eye&L1ZRhrRmN6Lr`{NL(wDbif|y&z)JN>Fl5#Wi&mMIr5i;x zBx}3YfF>>8EC(fYnmpu~)CYHuHCyr5*`ECap%t@y=jD>!_%3iiE|LN$mK9>- zHdtpy8fGZtkZF?%TW~29JIAfi2jZT8>OA7=h;8T{{k?c2`nCEx9$r zS+*&vt~2o^^J+}RDG@+9&M^K*z4p{5#IEVbz`1%`m5c2};aGt=V?~vIM}ZdPECDI)47|CWBCfDWUbxBCnmYivQ*0Nu_xb*C>~C9(VjHM zxe<*D<#dQ8TlpMX2c@M<9$w!RP$hpG4cs%AI){jp*Sj|*`m)5(Bw*A0$*i-(CA5#%>a)$+jI2C9r6|(>J8InryENI z$NohnxDUB;wAYDwrb*!N3noBTKPpPN}~09SEL18tkG zxgz(RYU_;DPT{l?Q$+eaZaxnsWCA^ds^0PVRkIM%bOd|G2IEBBiz{&^JtNsODs;5z zICt_Zj8wo^KT$7Bg4H+y!Df#3mbl%%?|EXe!&(Vmac1DJ*y~3+kRKAD=Ovde4^^%~ zw<9av18HLyrf*_>Slp;^i`Uy~`mvBjZ|?Ad63yQa#YK`4+c6;pW4?XIY9G1(Xh9WO8{F-Aju+nS9Vmv=$Ac0ienZ+p9*O%NG zMZKy5?%Z6TAJTE?o5vEr0r>f>hb#2w2U3DL64*au_@P!J!TL`oH2r*{>ffu6|A7tv zL4juf$DZ1MW5ZPsG!5)`k8d8c$J$o;%EIL0va9&GzWvkS%ZsGb#S(?{!UFOZ9<$a| zY|a+5kmD5N&{vRqkgY>aHsBT&`rg|&kezoD)gP0fsNYHsO#TRc_$n6Lf1Z{?+DLziXlHrq4sf(!>O{?Tj;Eh@%)+nRE_2VxbN&&%%caU#JDU%vL3}Cb zsb4AazPI{>8H&d=jUaZDS$-0^AxE@utGs;-Ez_F(qC9T=UZX=>ok2k2 ziTn{K?y~a5reD2A)P${NoI^>JXn>`IeArow(41c-Wm~)wiryEP(OS{YXWi7;%dG9v zI?mwu1MxD{yp_rrk!j^cKM)dc4@p4Ezyo%lRN|XyD}}>v=Xoib0gOcdXrQ^*61HNj z=NP|pd>@yfvr-=m{8$3A8TQGMTE7g=z!%yt`8`Bk-0MMwW~h^++;qyUP!J~ykh1GO z(FZ59xuFR$(WE;F@UUyE@Sp>`aVNjyj=Ty>_Vo}xf`e7`F;j-IgL5`1~-#70$9_=uBMq!2&1l zomRgpD58@)YYfvLtPW}{C5B35R;ZVvB<<#)x%srmc_S=A7F@DW8>QOEGwD6suhwCg z>Pa+YyULhmw%BA*4yjDp|2{!T98~<6Yfd(wo1mQ!KWwq0eg+6)o1>W~f~kL<-S+P@$wx*zeI|1t7z#Sxr5 zt6w+;YblPQNplq4Z#T$GLX#j6yldXAqj>4gAnnWtBICUnA&-dtnlh=t0Ho_vEKwV` z)DlJi#!@nkYV#$!)@>udAU*hF?V`2$Hf=V&6PP_|r#Iv*J$9)pF@X3`k;5})9^o4y z&)~?EjX5yX12O(BsFy-l6}nYeuKkiq`u9145&3Ssg^y{5G3Pse z9w(YVa0)N-fLaBq1`P!_#>SS(8fh_5!f{UrgZ~uEdeMJIz7DzI5!NHHqQtm~#CPij z?=N|J>nPR6_sL7!f4hD_|KH`vf8(Wpnj-(gPWH+ZvID}%?~68SwhPTC3u1_cB`otq z)U?6qo!ZLi5b>*KnYHWW=3F!p%h1;h{L&(Q&{qY6)_qxNfbP6E3yYpW!EO+IW3?@J z);4>g4gnl^8klu7uA>eGF6rIGSynacogr)KUwE_R4E5Xzi*Qir@b-jy55-JPC8c~( zo!W8y9OGZ&`xmc8;=4-U9=h{vCqfCNzYirONmGbRQlR`WWlgnY+1wCXbMz&NT~9*| z6@FrzP!LX&{no2!Ln_3|I==_4`@}V?4a;YZKTdw;vT<+K+z=uWbW(&bXEaWJ^W8Td z-3&1bY^Z*oM<=M}LVt>_j+p=2Iu7pZmbXrhQ_k)ysE9yXKygFNw$5hwDn(M>H+e1&9BM5!|81vd%r%vEm zqxY3?F@fb6O#5UunwgAHR9jp_W2zZ}NGp2%mTW@(hz7$^+a`A?mb8|_G*GNMJ) zjqegXQio=i@AINre&%ofexAr95aop5C+0MZ0m-l=MeO8m3epm7U%vZB8+I+C*iNFM z#T3l`gknX;D$-`2XT^Cg*vrv=RH+P;_dfF++cP?B_msQI4j+lt&rX2)3GaJx%W*Nn zkML%D{z5tpHH=dksQ*gzc|}gzW;lwAbxoR07VNgS*-c3d&8J|;@3t^ zVUz*J*&r7DFRuFVDCJDK8V9NN5hvpgGjwx+5n)qa;YCKe8TKtdnh{I7NU9BCN!0dq zczrBk8pE{{@vJa9ywR@mq*J=v+PG;?fwqlJVhijG!3VmIKs>9T6r7MJpC)m!Tc#>g zMtVsU>wbwFJEfwZ{vB|ZlttNe83)$iz`~#8UJ^r)lJ@HA&G#}W&ZH*;k{=TavpjWE z7hdyLZPf*X%Gm}i`Y{OGeeu^~nB8=`{r#TUrM-`;1cBvEd#d!kPqIgYySYhN-*1;L z^byj%Yi}Gx)Wnkosi337BKs}+5H5dth1JA{Ir-JKN$7zC)*}hqeoD(WfaUDPT>0`- z(6sa0AoIqASwF`>hP}^|)a_j2s^PQn*qVC{Q}htR z5-)duBFXT_V56-+UohKXlq~^6uf!6sA#ttk1o~*QEy_Y-S$gAvq47J9Vtk$5oA$Ct zYhYJ@8{hsC^98${!#Ho?4y5MCa7iGnfz}b9jE~h%EAAv~Qxu)_rAV;^cygV~5r_~?l=B`zObj7S=H=~$W zPtI_m%g$`kL_fVUk9J@>EiBH zOO&jtn~&`hIFMS5S`g8w94R4H40mdNUH4W@@XQk1sr17b{@y|JB*G9z1|CrQjd+GX z6+KyURG3;!*BQrentw{B2R&@2&`2}n(z-2&X7#r!{yg@Soy}cRD~j zj9@UBW+N|4HW4AWapy4wfUI- zZ`gSL6DUlgj*f1hSOGXG0IVH8HxK?o2|3HZ;KW{K+yPAlxtb)NV_2AwJm|E)FRs&& z=c^e7bvUsztY|+f^k7NXs$o1EUq>cR7C0$UKi6IooHWlK_#?IWDkvywnzg&ThWo^? z2O_N{5X39#?eV9l)xI(>@!vSB{DLt*oY!K1R8}_?%+0^C{d9a%N4 zoxHVT1&Lm|uDX%$QrBun5e-F`HJ^T$ zmzv)p@4ZHd_w9!%Hf9UYNvGCw2TTTbrj9pl+T9%-_-}L(tES>Or-}Z4F*{##n3~L~TuxjirGuIY#H7{%$E${?p{Q01 zi6T`n;rbK1yIB9jmQNycD~yZq&mbIsFWHo|ZAChSFPQa<(%d8mGw*V3fh|yFoxOOiWJd(qvVb!Z$b88cg->N=qO*4k~6;R==|9ihg&riu#P~s4Oap9O7f%crSr^rljeIfXDEg>wi)&v*a%7zpz<9w z*r!3q9J|390x`Zk;g$&OeN&ctp)VKRpDSV@kU2Q>jtok($Y-*x8_$2piTxun81@vt z!Vj?COa0fg2RPXMSIo26T=~0d`{oGP*eV+$!0I<(4azk&Vj3SiG=Q!6mX0p$z7I}; z9BJUFgT-K9MQQ-0@Z=^7R<{bn2Fm48endsSs`V7_@%8?Bxkqv>BDoVcj?K#dV#uUP zL1ND~?D-|VGKe3Rw_7-Idpht>H6XRLh*U7epS6byiGvJpr%d}XwfusjH9g;Z98H`x zyde%%5mhGOiL4wljCaWCk-&uE4_OOccb9c!ZaWt4B(wYl!?vyzl%7n~QepN&eFUrw zFIOl9c({``6~QD+43*_tzP{f2x41h(?b43^y6=iwyB)2os5hBE!@YUS5?N_tXd=h( z)WE286Fbd>R4M^P{!G)f;h<3Q>Fipuy+d2q-)!RyTgt;wr$(?9ox3;q+{E*ZQHhOn;lM`cjnu9 zXa48ks-v(~b*;MAI<>YZH(^NV8vjb34beE<_cwKlJoR;k6lJNSP6v}uiyRD?|0w+X@o1ONrH8a$fCxXpf? z?$DL0)7|X}Oc%h^zrMKWc-NS9I0Utu@>*j}b@tJ=ixQSJ={4@854wzW@E>VSL+Y{i z#0b=WpbCZS>kUCO_iQz)LoE>P5LIG-hv9E+oG}DtlIDF>$tJ1aw9^LuhLEHt?BCj& z(O4I8v1s#HUi5A>nIS-JK{v!7dJx)^Yg%XjNmlkWAq2*cv#tHgz`Y(bETc6CuO1VkN^L-L3j_x<4NqYb5rzrLC-7uOv z!5e`GZt%B782C5-fGnn*GhDF$%(qP<74Z}3xx+{$4cYKy2ikxI7B2N+2r07DN;|-T->nU&!=Cm#rZt%O_5c&1Z%nlWq3TKAW0w zQqemZw_ue--2uKQsx+niCUou?HjD`xhEjjQd3%rrBi82crq*~#uA4+>vR<_S{~5ce z-2EIl?~s z1=GVL{NxP1N3%=AOaC}j_Fv=ur&THz zyO!d9kHq|c73kpq`$+t+8Bw7MgeR5~`d7ChYyGCBWSteTB>8WAU(NPYt2Dk`@#+}= zI4SvLlyk#pBgVigEe`?NG*vl7V6m+<}%FwPV=~PvvA)=#ths==DRTDEYh4V5}Cf$z@#;< zyWfLY_5sP$gc3LLl2x+Ii)#b2nhNXJ{R~vk`s5U7Nyu^3yFg&D%Txwj6QezMX`V(x z=C`{76*mNb!qHHs)#GgGZ_7|vkt9izl_&PBrsu@}L`X{95-2jf99K)0=*N)VxBX2q z((vkpP2RneSIiIUEnGb?VqbMb=Zia+rF~+iqslydE34cSLJ&BJW^3knX@M;t*b=EA zNvGzv41Ld_T+WT#XjDB840vovUU^FtN_)G}7v)1lPetgpEK9YS^OWFkPoE{ovj^=@ zO9N$S=G$1ecndT_=5ehth2Lmd1II-PuT~C9`XVePw$y8J#dpZ?Tss<6wtVglm(Ok7 z3?^oi@pPio6l&!z8JY(pJvG=*pI?GIOu}e^EB6QYk$#FJQ%^AIK$I4epJ+9t?KjqA+bkj&PQ*|vLttme+`9G=L% ziadyMw_7-M)hS(3E$QGNCu|o23|%O+VN7;Qggp?PB3K-iSeBa2b}V4_wY`G1Jsfz4 z9|SdB^;|I8E8gWqHKx!vj_@SMY^hLEIbSMCuE?WKq=c2mJK z8LoG-pnY!uhqFv&L?yEuxo{dpMTsmCn)95xanqBrNPTgXP((H$9N${Ow~Is-FBg%h z53;|Y5$MUN)9W2HBe2TD`ct^LHI<(xWrw}$qSoei?}s)&w$;&!14w6B6>Yr6Y8b)S z0r71`WmAvJJ`1h&poLftLUS6Ir zC$bG9!Im_4Zjse)#K=oJM9mHW1{%l8sz$1o?ltdKlLTxWWPB>Vk22czVt|1%^wnN@*!l)}?EgtvhC>vlHm^t+ogpgHI1_$1ox9e;>0!+b(tBrmXRB`PY1vp-R**8N7 zGP|QqI$m(Rdu#=(?!(N}G9QhQ%o!aXE=aN{&wtGP8|_qh+7a_j_sU5|J^)vxq;# zjvzLn%_QPHZZIWu1&mRAj;Sa_97p_lLq_{~j!M9N^1yp3U_SxRqK&JnR%6VI#^E12 z>CdOVI^_9aPK2eZ4h&^{pQs}xsijXgFYRIxJ~N7&BB9jUR1fm!(xl)mvy|3e6-B3j zJn#ajL;bFTYJ2+Q)tDjx=3IklO@Q+FFM}6UJr6km7hj7th9n_&JR7fnqC!hTZoM~T zBeaVFp%)0cbPhejX<8pf5HyRUj2>aXnXBqDJe73~J%P(2C?-RT{c3NjE`)om! zl$uewSgWkE66$Kb34+QZZvRn`fob~Cl9=cRk@Es}KQm=?E~CE%spXaMO6YmrMl%9Q zlA3Q$3|L1QJ4?->UjT&CBd!~ru{Ih^in&JXO=|<6J!&qp zRe*OZ*cj5bHYlz!!~iEKcuE|;U4vN1rk$xq6>bUWD*u(V@8sG^7>kVuo(QL@Ki;yL zWC!FT(q{E8#on>%1iAS0HMZDJg{Z{^!De(vSIq&;1$+b)oRMwA3nc3mdTSG#3uYO_ z>+x;7p4I;uHz?ZB>dA-BKl+t-3IB!jBRgdvAbW!aJ(Q{aT>+iz?91`C-xbe)IBoND z9_Xth{6?(y3rddwY$GD65IT#f3<(0o#`di{sh2gm{dw*#-Vnc3r=4==&PU^hCv$qd zjw;>i&?L*Wq#TxG$mFIUf>eK+170KG;~+o&1;Tom9}}mKo23KwdEM6UonXgc z!6N(@k8q@HPw{O8O!lAyi{rZv|DpgfU{py+j(X_cwpKqcalcqKIr0kM^%Br3SdeD> zHSKV94Yxw;pjzDHo!Q?8^0bb%L|wC;4U^9I#pd5O&eexX+Im{ z?jKnCcsE|H?{uGMqVie_C~w7GX)kYGWAg%-?8|N_1#W-|4F)3YTDC+QSq1s!DnOML3@d`mG%o2YbYd#jww|jD$gotpa)kntakp#K;+yo-_ZF9qrNZw<%#C zuPE@#3RocLgPyiBZ+R_-FJ_$xP!RzWm|aN)S+{$LY9vvN+IW~Kf3TsEIvP+B9Mtm! zpfNNxObWQpLoaO&cJh5>%slZnHl_Q~(-Tfh!DMz(dTWld@LG1VRF`9`DYKhyNv z2pU|UZ$#_yUx_B_|MxUq^glT}O5Xt(Vm4Mr02><%C)@v;vPb@pT$*yzJ4aPc_FZ3z z3}PLoMBIM>q_9U2rl^sGhk1VUJ89=*?7|v`{!Z{6bqFMq(mYiA?%KbsI~JwuqVA9$H5vDE+VocjX+G^%bieqx->s;XWlKcuv(s%y%D5Xbc9+ zc(_2nYS1&^yL*ey664&4`IoOeDIig}y-E~_GS?m;D!xv5-xwz+G`5l6V+}CpeJDi^ z%4ed$qowm88=iYG+(`ld5Uh&>Dgs4uPHSJ^TngXP_V6fPyl~>2bhi20QB%lSd#yYn zO05?KT1z@?^-bqO8Cg`;ft>ilejsw@2%RR7;`$Vs;FmO(Yr3Fp`pHGr@P2hC%QcA|X&N2Dn zYf`MqXdHi%cGR@%y7Rg7?d3?an){s$zA{!H;Ie5exE#c~@NhQUFG8V=SQh%UxUeiV zd7#UcYqD=lk-}sEwlpu&H^T_V0{#G?lZMxL7ih_&{(g)MWBnCZxtXg znr#}>U^6!jA%e}@Gj49LWG@*&t0V>Cxc3?oO7LSG%~)Y5}f7vqUUnQ;STjdDU}P9IF9d9<$;=QaXc zL1^X7>fa^jHBu_}9}J~#-oz3Oq^JmGR#?GO7b9a(=R@fw@}Q{{@`Wy1vIQ#Bw?>@X z-_RGG@wt|%u`XUc%W{J z>iSeiz8C3H7@St3mOr_mU+&bL#Uif;+Xw-aZdNYUpdf>Rvu0i0t6k*}vwU`XNO2he z%miH|1tQ8~ZK!zmL&wa3E;l?!!XzgV#%PMVU!0xrDsNNZUWKlbiOjzH-1Uoxm8E#r`#2Sz;-o&qcqB zC-O_R{QGuynW14@)7&@yw1U}uP(1cov)twxeLus0s|7ayrtT8c#`&2~Fiu2=R;1_4bCaD=*E@cYI>7YSnt)nQc zohw5CsK%m?8Ack)qNx`W0_v$5S}nO|(V|RZKBD+btO?JXe|~^Qqur%@eO~<8-L^9d z=GA3-V14ng9L29~XJ>a5k~xT2152zLhM*@zlp2P5Eu}bywkcqR;ISbas&#T#;HZSf z2m69qTV(V@EkY(1Dk3`}j)JMo%ZVJ*5eB zYOjIisi+igK0#yW*gBGj?@I{~mUOvRFQR^pJbEbzFxTubnrw(Muk%}jI+vXmJ;{Q6 zrSobKD>T%}jV4Ub?L1+MGOD~0Ir%-`iTnWZN^~YPrcP5y3VMAzQ+&en^VzKEb$K!Q z<7Dbg&DNXuow*eD5yMr+#08nF!;%4vGrJI++5HdCFcGLfMW!KS*Oi@=7hFwDG!h2< zPunUEAF+HncQkbfFj&pbzp|MU*~60Z(|Ik%Tn{BXMN!hZOosNIseT?R;A`W?=d?5X zK(FB=9mZusYahp|K-wyb={rOpdn=@;4YI2W0EcbMKyo~-#^?h`BA9~o285%oY zfifCh5Lk$SY@|2A@a!T2V+{^!psQkx4?x0HSV`(w9{l75QxMk!)U52Lbhn{8ol?S) zCKo*7R(z!uk<6*qO=wh!Pul{(qq6g6xW;X68GI_CXp`XwO zxuSgPRAtM8K7}5E#-GM!*ydOOG_{A{)hkCII<|2=ma*71ci_-}VPARm3crFQjLYV! z9zbz82$|l01mv`$WahE2$=fAGWkd^X2kY(J7iz}WGS z@%MyBEO=A?HB9=^?nX`@nh;7;laAjs+fbo!|K^mE!tOB>$2a_O0y-*uaIn8k^6Y zSbuv;5~##*4Y~+y7Z5O*3w4qgI5V^17u*ZeupVGH^nM&$qmAk|anf*>r zWc5CV;-JY-Z@Uq1Irpb^O`L_7AGiqd*YpGUShb==os$uN3yYvb`wm6d=?T*it&pDk zo`vhw)RZX|91^^Wa_ti2zBFyWy4cJu#g)_S6~jT}CC{DJ_kKpT`$oAL%b^!2M;JgT zM3ZNbUB?}kP(*YYvXDIH8^7LUxz5oE%kMhF!rnPqv!GiY0o}NR$OD=ITDo9r%4E>E0Y^R(rS^~XjWyVI6 zMOR5rPXhTp*G*M&X#NTL`Hu*R+u*QNoiOKg4CtNPrjgH>c?Hi4MUG#I917fx**+pJfOo!zFM&*da&G_x)L(`k&TPI*t3e^{crd zX<4I$5nBQ8Ax_lmNRa~E*zS-R0sxkz`|>7q_?*e%7bxqNm3_eRG#1ae3gtV9!fQpY z+!^a38o4ZGy9!J5sylDxZTx$JmG!wg7;>&5H1)>f4dXj;B+@6tMlL=)cLl={jLMxY zbbf1ax3S4>bwB9-$;SN2?+GULu;UA-35;VY*^9Blx)Jwyb$=U!D>HhB&=jSsd^6yw zL)?a|>GxU!W}ocTC(?-%z3!IUhw^uzc`Vz_g>-tv)(XA#JK^)ZnC|l1`@CdX1@|!| z_9gQ)7uOf?cR@KDp97*>6X|;t@Y`k_N@)aH7gY27)COv^P3ya9I{4z~vUjLR9~z1Z z5=G{mVtKH*&$*t0@}-i_v|3B$AHHYale7>E+jP`ClqG%L{u;*ff_h@)al?RuL7tOO z->;I}>%WI{;vbLP3VIQ^iA$4wl6@0sDj|~112Y4OFjMs`13!$JGkp%b&E8QzJw_L5 zOnw9joc0^;O%OpF$Qp)W1HI!$4BaXX84`%@#^dk^hFp^pQ@rx4g(8Xjy#!X%+X5Jd@fs3amGT`}mhq#L97R>OwT5-m|h#yT_-v@(k$q7P*9X~T*3)LTdzP!*B} z+SldbVWrrwQo9wX*%FyK+sRXTa@O?WM^FGWOE?S`R(0P{<6p#f?0NJvnBia?k^fX2 zNQs7K-?EijgHJY}&zsr;qJ<*PCZUd*x|dD=IQPUK_nn)@X4KWtqoJNHkT?ZWL_hF? zS8lp2(q>;RXR|F;1O}EE#}gCrY~#n^O`_I&?&z5~7N;zL0)3Tup`%)oHMK-^r$NT% zbFg|o?b9w(q@)6w5V%si<$!U<#}s#x@0aX-hP>zwS#9*75VXA4K*%gUc>+yzupTDBOKH8WR4V0pM(HrfbQ&eJ79>HdCvE=F z|J>s;;iDLB^3(9}?biKbxf1$lI!*Z%*0&8UUq}wMyPs_hclyQQi4;NUY+x2qy|0J; zhn8;5)4ED1oHwg+VZF|80<4MrL97tGGXc5Sw$wAI#|2*cvQ=jB5+{AjMiDHmhUC*a zlmiZ`LAuAn_}hftXh;`Kq0zblDk8?O-`tnilIh|;3lZp@F_osJUV9`*R29M?7H{Fy z`nfVEIDIWXmU&YW;NjU8)EJpXhxe5t+scf|VXM!^bBlwNh)~7|3?fWwo_~ZFk(22% zTMesYw+LNx3J-_|DM~`v93yXe=jPD{q;li;5PD?Dyk+b? zo21|XpT@)$BM$%F=P9J19Vi&1#{jM3!^Y&fr&_`toi`XB1!n>sbL%U9I5<7!@?t)~ z;&H%z>bAaQ4f$wIzkjH70;<8tpUoxzKrPhn#IQfS%9l5=Iu))^XC<58D!-O z{B+o5R^Z21H0T9JQ5gNJnqh#qH^na|z92=hONIM~@_iuOi|F>jBh-?aA20}Qx~EpDGElELNn~|7WRXRFnw+Wdo`|# zBpU=Cz3z%cUJ0mx_1($X<40XEIYz(`noWeO+x#yb_pwj6)R(__%@_Cf>txOQ74wSJ z0#F3(zWWaR-jMEY$7C*3HJrohc79>MCUu26mfYN)f4M~4gD`}EX4e}A!U}QV8!S47 z6y-U-%+h`1n`*pQuKE%Av0@)+wBZr9mH}@vH@i{v(m-6QK7Ncf17x_D=)32`FOjjo zg|^VPf5c6-!FxN{25dvVh#fog=NNpXz zfB$o+0jbRkHH{!TKhE709f+jI^$3#v1Nmf80w`@7-5$1Iv_`)W^px8P-({xwb;D0y z7LKDAHgX<84?l!I*Dvi2#D@oAE^J|g$3!)x1Ua;_;<@#l1fD}lqU2_tS^6Ht$1Wl} zBESo7o^)9-Tjuz$8YQSGhfs{BQV6zW7dA?0b(Dbt=UnQs&4zHfe_sj{RJ4uS-vQpC zX;Bbsuju4%!o8?&m4UZU@~ZZjeFF6ex2ss5_60_JS_|iNc+R0GIjH1@Z z=rLT9%B|WWgOrR7IiIwr2=T;Ne?30M!@{%Qf8o`!>=s<2CBpCK_TWc(DX51>e^xh8 z&@$^b6CgOd7KXQV&Y4%}_#uN*mbanXq(2=Nj`L7H7*k(6F8s6{FOw@(DzU`4-*77{ zF+dxpv}%mFpYK?>N_2*#Y?oB*qEKB}VoQ@bzm>ptmVS_EC(#}Lxxx730trt0G)#$b zE=wVvtqOct1%*9}U{q<)2?{+0TzZzP0jgf9*)arV)*e!f`|jgT{7_9iS@e)recI#z zbzolURQ+TOzE!ymqvBY7+5NnAbWxvMLsLTwEbFqW=CPyCsmJ}P1^V30|D5E|p3BC5 z)3|qgw@ra7aXb-wsa|l^in~1_fm{7bS9jhVRkYVO#U{qMp z)Wce+|DJ}4<2gp8r0_xfZpMo#{Hl2MfjLcZdRB9(B(A(f;+4s*FxV{1F|4d`*sRNd zp4#@sEY|?^FIJ;tmH{@keZ$P(sLh5IdOk@k^0uB^BWr@pk6mHy$qf&~rI>P*a;h0C{%oA*i!VjWn&D~O#MxN&f@1Po# zKN+ zrGrkSjcr?^R#nGl<#Q722^wbYcgW@{+6CBS<1@%dPA8HC!~a`jTz<`g_l5N1M@9wn9GOAZ>nqNgq!yOCbZ@1z`U_N`Z>}+1HIZxk*5RDc&rd5{3qjRh8QmT$VyS;jK z;AF+r6XnnCp=wQYoG|rT2@8&IvKq*IB_WvS%nt%e{MCFm`&W*#LXc|HrD?nVBo=(8*=Aq?u$sDA_sC_RPDUiQ+wnIJET8vx$&fxkW~kP9qXKt zozR)@xGC!P)CTkjeWvXW5&@2?)qt)jiYWWBU?AUtzAN}{JE1I)dfz~7$;}~BmQF`k zpn11qmObXwRB8&rnEG*#4Xax3XBkKlw(;tb?Np^i+H8m(Wyz9k{~ogba@laiEk;2! zV*QV^6g6(QG%vX5Um#^sT&_e`B1pBW5yVth~xUs#0}nv?~C#l?W+9Lsb_5)!71rirGvY zTIJ$OPOY516Y|_014sNv+Z8cc5t_V=i>lWV=vNu#!58y9Zl&GsMEW#pPYPYGHQ|;vFvd*9eM==$_=vc7xnyz0~ zY}r??$<`wAO?JQk@?RGvkWVJlq2dk9vB(yV^vm{=NVI8dhsX<)O(#nr9YD?I?(VmQ z^r7VfUBn<~p3()8yOBjm$#KWx!5hRW)5Jl7wY@ky9lNM^jaT##8QGVsYeaVywmpv>X|Xj7gWE1Ezai&wVLt3p)k4w~yrskT-!PR!kiyQlaxl(( zXhF%Q9x}1TMt3~u@|#wWm-Vq?ZerK={8@~&@9r5JW}r#45#rWii};t`{5#&3$W)|@ zbAf2yDNe0q}NEUvq_Quq3cTjcw z@H_;$hu&xllCI9CFDLuScEMg|x{S7GdV8<&Mq=ezDnRZAyX-8gv97YTm0bg=d)(>N z+B2FcqvI9>jGtnK%eO%y zoBPkJTk%y`8TLf4)IXPBn`U|9>O~WL2C~C$z~9|0m*YH<-vg2CD^SX#&)B4ngOSG$ zV^wmy_iQk>dfN@Pv(ckfy&#ak@MLC7&Q6Ro#!ezM*VEh`+b3Jt%m(^T&p&WJ2Oqvj zs-4nq0TW6cv~(YI$n0UkfwN}kg3_fp?(ijSV#tR9L0}l2qjc7W?i*q01=St0eZ=4h zyGQbEw`9OEH>NMuIe)hVwYHsGERWOD;JxEiO7cQv%pFCeR+IyhwQ|y@&^24k+|8fD zLiOWFNJ2&vu2&`Jv96_z-Cd5RLgmeY3*4rDOQo?Jm`;I_(+ejsPM03!ly!*Cu}Cco zrQSrEDHNyzT(D5s1rZq!8#?f6@v6dB7a-aWs(Qk>N?UGAo{gytlh$%_IhyL7h?DLXDGx zgxGEBQoCAWo-$LRvM=F5MTle`M})t3vVv;2j0HZY&G z22^iGhV@uaJh(XyyY%} zd4iH_UfdV#T=3n}(Lj^|n;O4|$;xhu*8T3hR1mc_A}fK}jfZ7LX~*n5+`8N2q#rI$ z@<_2VANlYF$vIH$ zl<)+*tIWW78IIINA7Rr7i{<;#^yzxoLNkXL)eSs=%|P>$YQIh+ea_3k z_s7r4%j7%&*NHSl?R4k%1>Z=M9o#zxY!n8sL5>BO-ZP;T3Gut>iLS@U%IBrX6BA3k z)&@q}V8a{X<5B}K5s(c(LQ=%v1ocr`t$EqqY0EqVjr65usa=0bkf|O#ky{j3)WBR(((L^wmyHRzoWuL2~WTC=`yZ zn%VX`L=|Ok0v7?s>IHg?yArBcync5rG#^+u)>a%qjES%dRZoIyA8gQ;StH z1Ao7{<&}6U=5}4v<)1T7t!J_CL%U}CKNs-0xWoTTeqj{5{?Be$L0_tk>M9o8 zo371}S#30rKZFM{`H_(L`EM9DGp+Mifk&IP|C2Zu_)Ghr4Qtpmkm1osCf@%Z$%t+7 zYH$Cr)Ro@3-QDeQJ8m+x6%;?YYT;k6Z0E-?kr>x33`H%*ueBD7Zx~3&HtWn0?2Wt} zTG}*|v?{$ajzt}xPzV%lL1t-URi8*Zn)YljXNGDb>;!905Td|mpa@mHjIH%VIiGx- zd@MqhpYFu4_?y5N4xiHn3vX&|e6r~Xt> zZG`aGq|yTNjv;9E+Txuoa@A(9V7g?1_T5FzRI;!=NP1Kqou1z5?%X~Wwb{trRfd>i z8&y^H)8YnKyA_Fyx>}RNmQIczT?w2J4SNvI{5J&}Wto|8FR(W;Qw#b1G<1%#tmYzQ zQ2mZA-PAdi%RQOhkHy9Ea#TPSw?WxwL@H@cbkZwIq0B!@ns}niALidmn&W?!Vd4Gj zO7FiuV4*6Mr^2xlFSvM;Cp_#r8UaqIzHJQg_z^rEJw&OMm_8NGAY2)rKvki|o1bH~ z$2IbfVeY2L(^*rMRU1lM5Y_sgrDS`Z??nR2lX;zyR=c%UyGb*%TC-Dil?SihkjrQy~TMv6;BMs7P8il`H7DmpVm@rJ;b)hW)BL)GjS154b*xq-NXq2cwE z^;VP7ua2pxvCmxrnqUYQMH%a%nHmwmI33nJM(>4LznvY*k&C0{8f*%?zggpDgkuz&JBx{9mfb@wegEl2v!=}Sq2Gaty0<)UrOT0{MZtZ~j5y&w zXlYa_jY)I_+VA-^#mEox#+G>UgvM!Ac8zI<%JRXM_73Q!#i3O|)lOP*qBeJG#BST0 zqohi)O!|$|2SeJQo(w6w7%*92S})XfnhrH_Z8qe!G5>CglP=nI7JAOW?(Z29;pXJ9 zR9`KzQ=WEhy*)WH>$;7Cdz|>*i>=##0bB)oU0OR>>N<21e4rMCHDemNi2LD>Nc$;& zQRFthpWniC1J6@Zh~iJCoLOxN`oCKD5Q4r%ynwgUKPlIEd#?QViIqovY|czyK8>6B zSP%{2-<;%;1`#0mG^B(8KbtXF;Nf>K#Di72UWE4gQ%(_26Koiad)q$xRL~?pN71ZZ zujaaCx~jXjygw;rI!WB=xrOJO6HJ!!w}7eiivtCg5K|F6$EXa)=xUC za^JXSX98W`7g-tm@uo|BKj39Dl;sg5ta;4qjo^pCh~{-HdLl6qI9Ix6f$+qiZ$}s= zNguKrU;u+T@ko(Vr1>)Q%h$?UKXCY>3se%&;h2osl2D zE4A9bd7_|^njDd)6cI*FupHpE3){4NQ*$k*cOWZ_?CZ>Z4_fl@n(mMnYK62Q1d@+I zr&O))G4hMihgBqRIAJkLdk(p(D~X{-oBUA+If@B}j& zsHbeJ3RzTq96lB7d($h$xTeZ^gP0c{t!Y0c)aQE;$FY2!mACg!GDEMKXFOPI^)nHZ z`aSPJpvV0|bbrzhWWkuPURlDeN%VT8tndV8?d)eN*i4I@u zVKl^6{?}A?P)Fsy?3oi#clf}L18t;TjNI2>eI&(ezDK7RyqFxcv%>?oxUlonv(px) z$vnPzRH`y5A(x!yOIfL0bmgeMQB$H5wenx~!ujQK*nUBW;@Em&6Xv2%s(~H5WcU2R z;%Nw<$tI)a`Ve!>x+qegJnQsN2N7HaKzrFqM>`6R*gvh%O*-%THt zrB$Nk;lE;z{s{r^PPm5qz(&lM{sO*g+W{sK+m3M_z=4=&CC>T`{X}1Vg2PEfSj2x_ zmT*(x;ov%3F?qoEeeM>dUn$a*?SIGyO8m806J1W1o+4HRhc2`9$s6hM#qAm zChQ87b~GEw{ADfs+5}FJ8+|bIlIv(jT$Ap#hSHoXdd9#w<#cA<1Rkq^*EEkknUd4& zoIWIY)sAswy6fSERVm&!SO~#iN$OgOX*{9@_BWFyJTvC%S++ilSfCrO(?u=Dc?CXZ zzCG&0yVR{Z`|ZF0eEApWEo#s9osV>F{uK{QA@BES#&;#KsScf>y zvs?vIbI>VrT<*!;XmQS=bhq%46-aambZ(8KU-wOO2=en~D}MCToB_u;Yz{)1ySrPZ z@=$}EvjTdzTWU7c0ZI6L8=yP+YRD_eMMos}b5vY^S*~VZysrkq<`cK3>>v%uy7jgq z0ilW9KjVDHLv0b<1K_`1IkbTOINs0=m-22c%M~l=^S}%hbli-3?BnNq?b`hx^HX2J zIe6ECljRL0uBWb`%{EA=%!i^4sMcj+U_TaTZRb+~GOk z^ZW!nky0n*Wb*r+Q|9H@ml@Z5gU&W`(z4-j!OzC1wOke`TRAYGZVl$PmQ16{3196( zO*?`--I}Qf(2HIwb2&1FB^!faPA2=sLg(@6P4mN)>Dc3i(B0;@O-y2;lM4akD>@^v z=u>*|!s&9zem70g7zfw9FXl1bpJW(C#5w#uy5!V?Q(U35A~$dR%LDVnq@}kQm13{} zd53q3N(s$Eu{R}k2esbftfjfOITCL;jWa$}(mmm}d(&7JZ6d3%IABCapFFYjdEjdK z&4Edqf$G^MNAtL=uCDRs&Fu@FXRgX{*0<(@c3|PNHa>L%zvxWS={L8%qw`STm+=Rd zA}FLspESSIpE_^41~#5yI2bJ=9`oc;GIL!JuW&7YetZ?0H}$$%8rW@*J37L-~Rsx!)8($nI4 zZhcZ2^=Y+p4YPl%j!nFJA|*M^gc(0o$i3nlphe+~-_m}jVkRN{spFs(o0ajW@f3K{ zDV!#BwL322CET$}Y}^0ixYj2w>&Xh12|R8&yEw|wLDvF!lZ#dOTHM9pK6@Nm-@9Lnng4ZHBgBSrr7KI8YCC9DX5Kg|`HsiwJHg2(7#nS;A{b3tVO?Z% za{m5b3rFV6EpX;=;n#wltDv1LE*|g5pQ+OY&*6qCJZc5oDS6Z6JD#6F)bWxZSF@q% z+1WV;m!lRB!n^PC>RgQCI#D1br_o^#iPk>;K2hB~0^<~)?p}LG%kigm@moD#q3PE+ zA^Qca)(xnqw6x>XFhV6ku9r$E>bWNrVH9fum0?4s?Rn2LG{Vm_+QJHse6xa%nzQ?k zKug4PW~#Gtb;#5+9!QBgyB@q=sk9=$S{4T>wjFICStOM?__fr+Kei1 z3j~xPqW;W@YkiUM;HngG!;>@AITg}vAE`M2Pj9Irl4w1fo4w<|Bu!%rh%a(Ai^Zhi zs92>v5;@Y(Zi#RI*ua*h`d_7;byQSa*v9E{2x$<-_=5Z<7{%)}4XExANcz@rK69T0x3%H<@frW>RA8^swA+^a(FxK| zFl3LD*ImHN=XDUkrRhp6RY5$rQ{bRgSO*(vEHYV)3Mo6Jy3puiLmU&g82p{qr0F?ohmbz)f2r{X2|T2 z$4fdQ=>0BeKbiVM!e-lIIs8wVTuC_m7}y4A_%ikI;Wm5$9j(^Y z(cD%U%k)X>_>9~t8;pGzL6L-fmQO@K; zo&vQzMlgY95;1BSkngY)e{`n0!NfVgf}2mB3t}D9@*N;FQ{HZ3Pb%BK6;5#-O|WI( zb6h@qTLU~AbVW#_6?c!?Dj65Now7*pU{h!1+eCV^KCuPAGs28~3k@ueL5+u|Z-7}t z9|lskE`4B7W8wMs@xJa{#bsCGDFoRSNSnmNYB&U7 zVGKWe%+kFB6kb)e;TyHfqtU6~fRg)f|>=5(N36)0+C z`hv65J<$B}WUc!wFAb^QtY31yNleq4dzmG`1wHTj=c*=hay9iD071Hc?oYoUk|M*_ zU1GihAMBsM@5rUJ(qS?9ZYJ6@{bNqJ`2Mr+5#hKf?doa?F|+^IR!8lq9)wS3tF_9n zW_?hm)G(M+MYb?V9YoX^_mu5h-LP^TL^!Q9Z7|@sO(rg_4+@=PdI)WL(B7`!K^ND- z-uIuVDCVEdH_C@c71YGYT^_Scf_dhB8Z2Xy6vGtBSlYud9vggOqv^L~F{BraSE_t} zIkP+Hp2&nH^-MNEs}^`oMLy11`PQW$T|K(`Bu*(f@)mv1-qY(_YG&J2M2<7k;;RK~ zL{Fqj9yCz8(S{}@c)S!65aF<=&eLI{hAMErCx&>i7OeDN>okvegO87OaG{Jmi<|}D zaT@b|0X{d@OIJ7zvT>r+eTzgLq~|Dpu)Z&db-P4z*`M$UL51lf>FLlq6rfG)%doyp z)3kk_YIM!03eQ8Vu_2fg{+osaEJPtJ-s36R+5_AEG12`NG)IQ#TF9c@$99%0iye+ zUzZ57=m2)$D(5Nx!n)=5Au&O0BBgwxIBaeI(mro$#&UGCr<;C{UjJVAbVi%|+WP(a zL$U@TYCxJ=1{Z~}rnW;7UVb7+ZnzgmrogDxhjLGo>c~MiJAWs&&;AGg@%U?Y^0JhL ze(x6Z74JG6FlOFK(T}SXQfhr}RIFl@QXKnIcXYF)5|V~e-}suHILKT-k|<*~Ij|VF zC;t@=uj=hot~*!C68G8hTA%8SzOfETOXQ|3FSaIEjvBJp(A)7SWUi5!Eu#yWgY+;n zlm<$+UDou*V+246_o#V4kMdto8hF%%Lki#zPh}KYXmMf?hrN0;>Mv%`@{0Qn`Ujp) z=lZe+13>^Q!9zT);H<(#bIeRWz%#*}sgUX9P|9($kexOyKIOc`dLux}c$7It4u|Rl z6SSkY*V~g_B-hMPo_ak>>z@AVQ(_N)VY2kB3IZ0G(iDUYw+2d7W^~(Jq}KY=JnWS( z#rzEa&0uNhJ>QE8iiyz;n2H|SV#Og+wEZv=f2%1ELX!SX-(d3tEj$5$1}70Mp<&eI zCkfbByL7af=qQE@5vDVxx1}FSGt_a1DoE3SDI+G)mBAna)KBG4p8Epxl9QZ4BfdAN zFnF|Y(umr;gRgG6NLQ$?ZWgllEeeq~z^ZS7L?<(~O&$5|y)Al^iMKy}&W+eMm1W z7EMU)u^ke(A1#XCV>CZ71}P}0x)4wtHO8#JRG3MA-6g=`ZM!FcICCZ{IEw8Dm2&LQ z1|r)BUG^0GzI6f946RrBlfB1Vs)~8toZf~7)+G;pv&XiUO(%5bm)pl=p>nV^o*;&T z;}@oZSibzto$arQgfkp|z4Z($P>dTXE{4O=vY0!)kDO* zGF8a4wq#VaFpLfK!iELy@?-SeRrdz%F*}hjKcA*y@mj~VD3!it9lhRhX}5YOaR9$} z3mS%$2Be7{l(+MVx3 z(4?h;P!jnRmX9J9sYN#7i=iyj_5q7n#X(!cdqI2lnr8T$IfOW<_v`eB!d9xY1P=2q&WtOXY=D9QYteP)De?S4}FK6#6Ma z=E*V+#s8>L;8aVroK^6iKo=MH{4yEZ_>N-N z`(|;aOATba1^asjxlILk<4}f~`39dBFlxj>Dw(hMYKPO3EEt1@S`1lxFNM+J@uB7T zZ8WKjz7HF1-5&2=l=fqF-*@>n5J}jIxdDwpT?oKM3s8Nr`x8JnN-kCE?~aM1H!hAE z%%w(3kHfGwMnMmNj(SU(w42OrC-euI>Dsjk&jz3ts}WHqmMpzQ3vZrsXrZ|}+MHA7 z068obeXZTsO*6RS@o3x80E4ok``rV^Y3hr&C1;|ZZ0|*EKO`$lECUYG2gVFtUTw)R z4Um<0ZzlON`zTdvVdL#KFoMFQX*a5wM0Czp%wTtfK4Sjs)P**RW&?lP$(<}q%r68Z zS53Y!d@&~ne9O)A^tNrXHhXBkj~$8j%pT1%%mypa9AW5E&s9)rjF4@O3ytH{0z6riz|@< zB~UPh*wRFg2^7EbQrHf0y?E~dHlkOxof_a?M{LqQ^C!i2dawHTPYUE=X@2(3<=OOxs8qn_(y>pU>u^}3y&df{JarR0@VJn0f+U%UiF=$Wyq zQvnVHESil@d|8&R<%}uidGh7@u^(%?$#|&J$pvFC-n8&A>utA=n3#)yMkz+qnG3wd zP7xCnF|$9Dif@N~L)Vde3hW8W!UY0BgT2v(wzp;tlLmyk2%N|0jfG$%<;A&IVrOI< z!L)o>j>;dFaqA3pL}b-Je(bB@VJ4%!JeX@3x!i{yIeIso^=n?fDX`3bU=eG7sTc%g%ye8$v8P@yKE^XD=NYxTb zbf!Mk=h|otpqjFaA-vs5YOF-*GwWPc7VbaOW&stlANnCN8iftFMMrUdYNJ_Bnn5Vt zxfz@Ah|+4&P;reZxp;MmEI7C|FOv8NKUm8njF7Wb6Gi7DeODLl&G~}G4be&*Hi0Qw z5}77vL0P+7-B%UL@3n1&JPxW^d@vVwp?u#gVcJqY9#@-3X{ok#UfW3<1fb%FT`|)V~ggq z(3AUoUS-;7)^hCjdT0Kf{i}h)mBg4qhtHHBti=~h^n^OTH5U*XMgDLIR@sre`AaB$ zg)IGBET_4??m@cx&c~bA80O7B8CHR7(LX7%HThkeC*@vi{-pL%e)yXp!B2InafbDF zjPXf1mko3h59{lT6EEbxKO1Z5GF71)WwowO6kY|6tjSVSWdQ}NsK2x{>i|MKZK8%Q zfu&_0D;CO-Jg0#YmyfctyJ!mRJp)e#@O0mYdp|8x;G1%OZQ3Q847YWTyy|%^cpA;m zze0(5p{tMu^lDkpe?HynyO?a1$_LJl2L&mpeKu%8YvgRNr=%2z${%WThHG=vrWY@4 zsA`OP#O&)TetZ>s%h!=+CE15lOOls&nvC~$Qz0Ph7tHiP;O$i|eDwpT{cp>+)0-|; zY$|bB+Gbel>5aRN3>c0x)4U=|X+z+{ zn*_p*EQoquRL+=+p;=lm`d71&1NqBz&_ph)MXu(Nv6&XE7(RsS)^MGj5Q?Fwude-(sq zjJ>aOq!7!EN>@(fK7EE#;i_BGvli`5U;r!YA{JRodLBc6-`n8K+Fjgwb%sX;j=qHQ z7&Tr!)!{HXoO<2BQrV9Sw?JRaLXV8HrsNevvnf>Y-6|{T!pYLl7jp$-nEE z#X!4G4L#K0qG_4Z;Cj6=;b|Be$hi4JvMH!-voxqx^@8cXp`B??eFBz2lLD8RRaRGh zn7kUfy!YV~p(R|p7iC1Rdgt$_24i0cd-S8HpG|`@my70g^y`gu%#Tf_L21-k?sRRZHK&at(*ED0P8iw{7?R$9~OF$Ko;Iu5)ur5<->x!m93Eb zFYpIx60s=Wxxw=`$aS-O&dCO_9?b1yKiPCQmSQb>T)963`*U+Ydj5kI(B(B?HNP8r z*bfSBpSu)w(Z3j7HQoRjUG(+d=IaE~tv}y14zHHs|0UcN52fT8V_<@2ep_ee{QgZG zmgp8iv4V{k;~8@I%M3<#B;2R>Ef(Gg_cQM7%}0s*^)SK6!Ym+~P^58*wnwV1BW@eG z4sZLqsUvBbFsr#8u7S1r4teQ;t)Y@jnn_m5jS$CsW1um!p&PqAcc8!zyiXHVta9QC zY~wCwCF0U%xiQPD_INKtTb;A|Zf29(mu9NI;E zc-e>*1%(LSXB`g}kd`#}O;veb<(sk~RWL|f3ljxCnEZDdNSTDV6#Td({6l&y4IjKF z^}lIUq*ZUqgTPumD)RrCN{M^jhY>E~1pn|KOZ5((%F)G|*ZQ|r4zIbrEiV%42hJV8 z3xS)=!X1+=olbdGJ=yZil?oXLct8FM{(6ikLL3E%=q#O6(H$p~gQu6T8N!plf!96| z&Q3=`L~>U0zZh;z(pGR2^S^{#PrPxTRHD1RQOON&f)Siaf`GLj#UOk&(|@0?zm;Sx ztsGt8=29-MZs5CSf1l1jNFtNt5rFNZxJPvkNu~2}7*9468TWm>nN9TP&^!;J{-h)_ z7WsHH9|F%I`Pb!>KAS3jQWKfGivTVkMJLO-HUGM_a4UQ_%RgL6WZvrW+Z4ujZn;y@ zz9$=oO!7qVTaQAA^BhX&ZxS*|5dj803M=k&2%QrXda`-Q#IoZL6E(g+tN!6CA!CP* zCpWtCujIea)ENl0liwVfj)Nc<9mV%+e@=d`haoZ*`B7+PNjEbXBkv=B+Pi^~L#EO$D$ZqTiD8f<5$eyb54-(=3 zh)6i8i|jp(@OnRrY5B8t|LFXFQVQ895n*P16cEKTrT*~yLH6Z4e*bZ5otpRDri&+A zfNbK1D5@O=sm`fN=WzWyse!za5n%^+6dHPGX#8DyIK>?9qyX}2XvBWVqbP%%D)7$= z=#$WulZlZR<{m#gU7lwqK4WS1Ne$#_P{b17qe$~UOXCl>5b|6WVh;5vVnR<%d+Lnp z$uEmML38}U4vaW8>shm6CzB(Wei3s#NAWE3)a2)z@i{4jTn;;aQS)O@l{rUM`J@K& l00vQ5JBs~;vo!vr%%-k{2_Fq1Mn4QF81S)AQ99zk{{c4yR+0b! literal 54708 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 ZypaY2tb=~UE;0eV1Nd9`dw%@&{{Y^v%e4Ri diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties index 3098d50..fae6f65 100644 --- a/gradle/wrapper/gradle-wrapper.properties +++ b/gradle/wrapper/gradle-wrapper.properties @@ -1,13 +1,8 @@ -# Gradle distribution settings -distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip -distributionSha256Sum=9d926787066a081739e8200858338b4a69e837c3a821a33aca9db09dd4a41026 - -# Directory structure configuration distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists -zipStorePath=wrapper/dists -zipStoreBase=GRADLE_USER_HOME - -# Network settings +distributionSha256Sum=acd53f1edaf02f1a8ff99879f8a34b302661a057d9b063ae9e35b552f804d20a +distributionUrl=https\://services.gradle.org/distributions/gradle-9.7.1-bin.zip networkTimeout=10000 -validateDistributionUrl=true \ No newline at end of file +validateDistributionUrl=true +zipStoreBase=GRADLE_USER_HOME +zipStorePath=wrapper/dists diff --git a/gradlew b/gradlew index cccdd3d..1aa94a4 100755 --- a/gradlew +++ b/gradlew @@ -1,78 +1,127 @@ -#!/usr/bin/env sh +#!/bin/sh + +# +# Copyright © 2015-2021 the original authors. +# +# Licensed 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 +# +# https://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. +# ############################################################################## -## -## Gradle start up script for UN*X -## +# +# Gradle start up script for POSIX generated by Gradle. +# +# Important for running: +# +# (1) You need a POSIX-compliant shell to run this script. If your /bin/sh is +# noncompliant, but you have some other compliant shell such as ksh or +# bash, then to run this script, type that shell name before the whole +# command line, like: +# +# ksh Gradle +# +# Busybox and similar reduced shells will NOT work, because this script +# requires all of these POSIX shell features: +# * functions; +# * expansions «$var», «${var}», «${var:-default}», «${var+SET}», +# «${var#prefix}», «${var%suffix}», and «$( cmd )»; +# * compound commands having a testable exit status, especially «case»; +# * various built-in commands including «command», «set», and «ulimit». +# +# Important for patching: +# +# (2) This script targets any POSIX shell, so it avoids extensions provided +# by Bash, Ksh, etc; in particular arrays are avoided. +# +# The "traditional" practice of packing multiple parameters into a +# space-separated string is a well documented source of bugs and security +# problems, so this is (mostly) avoided, by progressively accumulating +# options in "$@", and eventually passing that to Java. +# +# Where the inherited environment variables (DEFAULT_JVM_OPTS, JAVA_OPTS, +# and GRADLE_OPTS) rely on word-splitting, this is performed explicitly; +# see the in-line comments for details. +# +# There are tweaks for specific operating systems such as AIX, CygWin, +# Darwin, MinGW, and NonStop. +# +# (3) This script is generated from the Groovy template +# https://github.com/gradle/gradle/blob/HEAD/subprojects/plugins/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt +# within the Gradle project. +# +# You can find Gradle at https://github.com/gradle/gradle/. +# ############################################################################## # Attempt to set APP_HOME + # Resolve links: $0 may be a link -PRG="$0" -# Need this for relative symlinks. -while [ -h "$PRG" ] ; do - ls=`ls -ld "$PRG"` - link=`expr "$ls" : '.*-> \(.*\)$'` - if expr "$link" : '/.*' > /dev/null; then - PRG="$link" - else - PRG=`dirname "$PRG"`"/$link" - fi +app_path=$0 + +# Need this for daisy-chained symlinks. +while + APP_HOME=${app_path%"${app_path##*/}"} # leaves a trailing /; empty if no leading path + [ -h "$app_path" ] +do + ls=$( ls -ld "$app_path" ) + link=${ls#*' -> '} + case $link in #( + /*) app_path=$link ;; #( + *) app_path=$APP_HOME$link ;; + esac done -SAVED="`pwd`" -cd "`dirname \"$PRG\"`/" >/dev/null -APP_HOME="`pwd -P`" -cd "$SAVED" >/dev/null - -APP_NAME="Gradle" -APP_BASE_NAME=`basename "$0"` -# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. -DEFAULT_JVM_OPTS="" +# This is normally unused +# shellcheck disable=SC2034 +APP_BASE_NAME=${0##*/} +# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036) +APP_HOME=$( cd "${APP_HOME:-./}" > /dev/null && pwd -P ) || exit # Use the maximum available, or set MAX_FD != -1 to use that value. -MAX_FD="maximum" +MAX_FD=maximum warn () { echo "$*" -} +} >&2 die () { echo echo "$*" echo exit 1 -} +} >&2 # OS specific support (must be 'true' or 'false'). cygwin=false msys=false darwin=false nonstop=false -case "`uname`" in - CYGWIN* ) - cygwin=true - ;; - Darwin* ) - darwin=true - ;; - MINGW* ) - msys=true - ;; - NONSTOP* ) - nonstop=true - ;; +case "$( uname )" in #( + CYGWIN* ) cygwin=true ;; #( + Darwin* ) darwin=true ;; #( + MSYS* | MINGW* ) msys=true ;; #( + NONSTOP* ) nonstop=true ;; esac CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar + # Determine the Java command to use to start the JVM. if [ -n "$JAVA_HOME" ] ; then if [ -x "$JAVA_HOME/jre/sh/java" ] ; then # IBM's JDK on AIX uses strange locations for the executables - JAVACMD="$JAVA_HOME/jre/sh/java" + JAVACMD=$JAVA_HOME/jre/sh/java else - JAVACMD="$JAVA_HOME/bin/java" + JAVACMD=$JAVA_HOME/bin/java fi if [ ! -x "$JAVACMD" ] ; then die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME @@ -81,92 +130,120 @@ Please set the JAVA_HOME variable in your environment to match the location of your Java installation." fi else - JAVACMD="java" - which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. + JAVACMD=java + if ! command -v java >/dev/null 2>&1 + then + die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. Please set the JAVA_HOME variable in your environment to match the location of your Java installation." + fi fi # Increase the maximum file descriptors if we can. -if [ "$cygwin" = "false" -a "$darwin" = "false" -a "$nonstop" = "false" ] ; then - MAX_FD_LIMIT=`ulimit -H -n` - if [ $? -eq 0 ] ; then - if [ "$MAX_FD" = "maximum" -o "$MAX_FD" = "max" ] ; then - MAX_FD="$MAX_FD_LIMIT" - fi - ulimit -n $MAX_FD - if [ $? -ne 0 ] ; then - warn "Could not set maximum file descriptor limit: $MAX_FD" - fi - else - warn "Could not query maximum file descriptor limit: $MAX_FD_LIMIT" - fi +if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then + case $MAX_FD in #( + max*) + # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked. + # shellcheck disable=SC2039,SC3045 + MAX_FD=$( ulimit -H -n ) || + warn "Could not query maximum file descriptor limit" + esac + case $MAX_FD in #( + '' | soft) :;; #( + *) + # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked. + # shellcheck disable=SC2039,SC3045 + ulimit -n "$MAX_FD" || + warn "Could not set maximum file descriptor limit to $MAX_FD" + esac fi -# For Darwin, add options to specify how the application appears in the dock -if $darwin; then - GRADLE_OPTS="$GRADLE_OPTS \"-Xdock:name=$APP_NAME\" \"-Xdock:icon=$APP_HOME/media/gradle.icns\"" -fi +# Collect all arguments for the java command, stacking in reverse order: +# * args from the command line +# * the main class name +# * -classpath +# * -D...appname settings +# * --module-path (only if needed) +# * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables. + +# For Cygwin or MSYS, switch paths to Windows format before running java +if "$cygwin" || "$msys" ; then + APP_HOME=$( cygpath --path --mixed "$APP_HOME" ) + CLASSPATH=$( cygpath --path --mixed "$CLASSPATH" ) + + JAVACMD=$( cygpath --unix "$JAVACMD" ) -# For Cygwin, switch paths to Windows format before running java -if $cygwin ; then - APP_HOME=`cygpath --path --mixed "$APP_HOME"` - CLASSPATH=`cygpath --path --mixed "$CLASSPATH"` - JAVACMD=`cygpath --unix "$JAVACMD"` - - # We build the pattern for arguments to be converted via cygpath - ROOTDIRSRAW=`find -L / -maxdepth 1 -mindepth 1 -type d 2>/dev/null` - SEP="" - for dir in $ROOTDIRSRAW ; do - ROOTDIRS="$ROOTDIRS$SEP$dir" - SEP="|" - done - OURCYGPATTERN="(^($ROOTDIRS))" - # Add a user-defined pattern to the cygpath arguments - if [ "$GRADLE_CYGPATTERN" != "" ] ; then - OURCYGPATTERN="$OURCYGPATTERN|($GRADLE_CYGPATTERN)" - fi # Now convert the arguments - kludge to limit ourselves to /bin/sh - i=0 - for arg in "$@" ; do - CHECK=`echo "$arg"|egrep -c "$OURCYGPATTERN" -` - CHECK2=`echo "$arg"|egrep -c "^-"` ### Determine if an option - - if [ $CHECK -ne 0 ] && [ $CHECK2 -eq 0 ] ; then ### Added a condition - eval `echo args$i`=`cygpath --path --ignore --mixed "$arg"` - else - eval `echo args$i`="\"$arg\"" + for arg do + if + case $arg in #( + -*) false ;; # don't mess with options #( + /?*) t=${arg#/} t=/${t%%/*} # looks like a POSIX filepath + [ -e "$t" ] ;; #( + *) false ;; + esac + then + arg=$( cygpath --path --ignore --mixed "$arg" ) fi - i=$((i+1)) + # Roll the args list around exactly as many times as the number of + # args, so each arg winds up back in the position where it started, but + # possibly modified. + # + # NB: a `for` loop captures its iteration list before it begins, so + # changing the positional parameters here affects neither the number of + # iterations, nor the values presented in `arg`. + shift # remove old arg + set -- "$@" "$arg" # push replacement arg done - case $i in - (0) set -- ;; - (1) set -- "$args0" ;; - (2) set -- "$args0" "$args1" ;; - (3) set -- "$args0" "$args1" "$args2" ;; - (4) set -- "$args0" "$args1" "$args2" "$args3" ;; - (5) set -- "$args0" "$args1" "$args2" "$args3" "$args4" ;; - (6) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" ;; - (7) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" ;; - (8) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" ;; - (9) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" "$args8" ;; - esac fi -# Escape application args -save () { - for i do printf %s\\n "$i" | sed "s/'/'\\\\''/g;1s/^/'/;\$s/\$/' \\\\/" ; done - echo " " -} -APP_ARGS=$(save "$@") - -# Collect all arguments for the java command, following the shell quoting and substitution rules -eval set -- $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS "\"-Dorg.gradle.appname=$APP_BASE_NAME\"" -classpath "\"$CLASSPATH\"" org.gradle.wrapper.GradleWrapperMain "$APP_ARGS" -# by default we should be in the correct project dir, but when run from Finder on Mac, the cwd is wrong -if [ "$(uname)" = "Darwin" ] && [ "$HOME" = "$PWD" ]; then - cd "$(dirname "$0")" +# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. +DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"' + +# Collect all arguments for the java command: +# * DEFAULT_JVM_OPTS, JAVA_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments, +# and any embedded shellness will be escaped. +# * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be +# treated as '${Hostname}' itself on the command line. + +set -- \ + "-Dorg.gradle.appname=$APP_BASE_NAME" \ + -classpath "$CLASSPATH" \ + org.gradle.wrapper.GradleWrapperMain \ + "$@" + +# Stop when "xargs" is not available. +if ! command -v xargs >/dev/null 2>&1 +then + die "xargs is not available" fi +# Use "xargs" to parse quoted args. +# +# With -n1 it outputs one arg per line, with the quotes and backslashes removed. +# +# In Bash we could simply go: +# +# readarray ARGS < <( xargs -n1 <<<"$var" ) && +# set -- "${ARGS[@]}" "$@" +# +# but POSIX shell has neither arrays nor command substitution, so instead we +# post-process each arg (as a line of input to sed) to backslash-escape any +# character that might be a shell metacharacter, then use eval to reverse +# that process (while maintaining the separation between arguments), and wrap +# the whole thing up as a single "set" statement. +# +# This will of course break if any of these variables contains a newline or +# an unmatched quote. +# + +eval "set -- $( + printf '%s\n' "$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS" | + xargs -n1 | + sed ' s~[^-[:alnum:]+,./:=@_]~\\&~g; ' | + tr '\n' ' ' + )" '"$@"' + exec "$JAVACMD" "$@" diff --git a/gradlew.bat b/gradlew.bat index f955316..93e3f59 100644 --- a/gradlew.bat +++ b/gradlew.bat @@ -1,4 +1,20 @@ -@if "%DEBUG%" == "" @echo off +@rem +@rem Copyright 2015 the original author or authors. +@rem +@rem Licensed under the Apache License, Version 2.0 (the "License"); +@rem you may not use this file except in compliance with the License. +@rem You may obtain a copy of the License at +@rem +@rem https://www.apache.org/licenses/LICENSE-2.0 +@rem +@rem Unless required by applicable law or agreed to in writing, software +@rem distributed under the License is distributed on an "AS IS" BASIS, +@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +@rem See the License for the specific language governing permissions and +@rem limitations under the License. +@rem + +@if "%DEBUG%"=="" @echo off @rem ########################################################################## @rem @rem Gradle startup script for Windows @@ -9,19 +25,23 @@ if "%OS%"=="Windows_NT" setlocal set DIRNAME=%~dp0 -if "%DIRNAME%" == "" set DIRNAME=. +if "%DIRNAME%"=="" set DIRNAME=. +@rem This is normally unused set APP_BASE_NAME=%~n0 set APP_HOME=%DIRNAME% +@rem Resolve any "." and ".." in APP_HOME to make it shorter. +for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi + @rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. -set DEFAULT_JVM_OPTS= +set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m" @rem Find java.exe if defined JAVA_HOME goto findJavaFromJavaHome set JAVA_EXE=java.exe %JAVA_EXE% -version >NUL 2>&1 -if "%ERRORLEVEL%" == "0" goto init +if %ERRORLEVEL% equ 0 goto execute echo. echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. @@ -35,7 +55,7 @@ goto fail set JAVA_HOME=%JAVA_HOME:"=% set JAVA_EXE=%JAVA_HOME%/bin/java.exe -if exist "%JAVA_EXE%" goto init +if exist "%JAVA_EXE%" goto execute echo. echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% @@ -45,38 +65,26 @@ echo location of your Java installation. goto fail -:init -@rem Get command-line arguments, handling Windows variants - -if not "%OS%" == "Windows_NT" goto win9xME_args - -:win9xME_args -@rem Slurp the command line arguments. -set CMD_LINE_ARGS= -set _SKIP=2 - -:win9xME_args_slurp -if "x%~1" == "x" goto execute - -set CMD_LINE_ARGS=%* - :execute @rem Setup the command line set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar + @rem Execute Gradle -"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %CMD_LINE_ARGS% +"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %* :end @rem End local scope for the variables with windows NT shell -if "%ERRORLEVEL%"=="0" goto mainEnd +if %ERRORLEVEL% equ 0 goto mainEnd :fail rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of rem the _cmd.exe /c_ return code! -if not "" == "%GRADLE_EXIT_CONSOLE%" exit 1 -exit /b 1 +set EXIT_CODE=%ERRORLEVEL% +if %EXIT_CODE% equ 0 set EXIT_CODE=1 +if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE% +exit /b %EXIT_CODE% :mainEnd if "%OS%"=="Windows_NT" endlocal diff --git a/settings.gradle b/settings.gradle index 323a75d..be83d81 100644 --- a/settings.gradle +++ b/settings.gradle @@ -15,12 +15,12 @@ buildCache { // Set Java compatibility ext { - minJavaVersion = JavaVersion.VERSION_21 - targetJavaVersion = JavaVersion.VERSION_21 + minJavaVersion = JavaVersion.VERSION_25 + targetJavaVersion = JavaVersion.VERSION_25 } // Verify Java version -def javaVersion = org.gradle.internal.jvm.Jvm.current().javaVersion +def javaVersion = JavaVersion.current() def minVersion = JavaVersion.toVersion(minJavaVersion) if (javaVersion < minVersion) { From 6387a40702167ec5f5380319837f65a76d979ced Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Wed, 2 Sep 2026 16:47:19 +0200 Subject: [PATCH 34/49] chore(build): vendor jupyter-jvm-basekernel as basekernel module Replace the Maven basekernel dependency with a local Gradle module, move the IJava-specific BaseKernel/StringStyler/TextColor classes into that module, align the Guava annotation stack, and harden Shadow duplicate handling. --- basekernel/LICENSE | 19 + basekernel/README.md | 7 + basekernel/build.gradle | 50 ++ .../channels/DefaultReplyEnvironment.java | 111 +++++ .../jupyter/channels/HeartbeatChannel.java | 86 ++++ .../jupyter/channels/IOPubChannel.java | 23 + .../jupyter/channels/JupyterConnection.java | 88 ++++ .../jupyter/channels/JupyterInputStream.java | 148 ++++++ .../jupyter/channels/JupyterOutputStream.java | 45 ++ .../jupyter/channels/JupyterSocket.java | 175 +++++++ .../spencerpark/jupyter/channels/Loop.java | 126 +++++ .../jupyter/channels/ReplyEnvironment.java | 60 +++ .../jupyter/channels/ShellChannel.java | 106 ++++ .../jupyter/channels/ShellHandler.java | 8 + .../channels/ShellReplyEnvironment.java | 49 ++ .../jupyter/channels/StdinChannel.java | 51 ++ .../jupyter/kernel/BaseKernel.java | 0 .../jupyter/kernel/DisplayStream.java | 41 ++ .../jupyter/kernel/ExpressionValue.java | 71 +++ .../spencerpark/jupyter/kernel/JupyterIO.java | 68 +++ .../kernel/KernelConnectionProperties.java | 111 +++++ .../jupyter/kernel/LanguageInfo.java | 219 +++++++++ .../jupyter/kernel/ReplacementOptions.java | 28 ++ .../spencerpark/jupyter/kernel/comm/Comm.java | 97 ++++ .../jupyter/kernel/comm/CommFactory.java | 20 + .../jupyter/kernel/comm/CommManager.java | 256 ++++++++++ .../jupyter/kernel/comm/CommTarget.java | 27 ++ .../jupyter/kernel/display/DisplayData.java | 175 +++++++ .../kernel/display/DisplayDataRenderable.java | 80 +++ .../kernel/display/MIMESuffixAssociation.java | 18 + .../jupyter/kernel/display/RenderContext.java | 130 +++++ .../kernel/display/RenderFunction.java | 6 + .../jupyter/kernel/display/RenderParams.java | 58 +++ .../kernel/display/RenderRequestTypes.java | 185 +++++++ .../jupyter/kernel/display/Renderer.java | 277 +++++++++++ .../jupyter/kernel/display/common/Image.java | 55 +++ .../jupyter/kernel/display/common/Text.java | 34 ++ .../jupyter/kernel/display/common/Url.java | 64 +++ .../kernel/display/mime/MIMEGroup.java | 112 +++++ .../kernel/display/mime/MIMESubtype.java | 38 ++ .../kernel/display/mime/MIMESuffix.java | 67 +++ .../jupyter/kernel/display/mime/MIMEType.java | 259 ++++++++++ .../display/mime/MIMETypeParseException.java | 33 ++ .../jupyter/kernel/history/HistoryEntry.java | 48 ++ .../kernel/history/HistoryManager.java | 146 ++++++ .../jupyter/kernel/magic/CellMagicArgs.java | 26 + .../kernel/magic/CellMagicParseContext.java | 28 ++ .../jupyter/kernel/magic/LineMagicArgs.java | 23 + .../kernel/magic/LineMagicParseContext.java | 44 ++ .../jupyter/kernel/magic/MagicParser.java | 117 +++++ .../kernel/magic/common/DisplayMagics.java | 71 +++ .../jupyter/kernel/magic/common/Load.java | 150 ++++++ .../jupyter/kernel/magic/common/Shell.java | 32 ++ .../kernel/magic/common/WriteFile.java | 39 ++ .../kernel/magic/registry/CellMagic.java | 14 + .../magic/registry/CellMagicFunction.java | 8 + .../kernel/magic/registry/LineMagic.java | 14 + .../magic/registry/LineMagicFunction.java | 8 + .../registry/MagicArgsParseException.java | 18 + .../jupyter/kernel/magic/registry/Magics.java | 231 +++++++++ .../kernel/magic/registry/MagicsArgs.java | 318 ++++++++++++ .../registry/UndefinedMagicException.java | 24 + .../jupyter/kernel/util/CharPredicate.java | 157 ++++++ .../jupyter/kernel/util/GlobFinder.java | 230 +++++++++ .../kernel/util/InheritanceIterator.java | 84 ++++ .../kernel/util/SimpleAutoCompleter.java | 104 ++++ .../jupyter/kernel/util/StringSearch.java | 66 +++ .../jupyter/kernel/util/StringStyler.java | 0 .../jupyter/kernel/util/TextColor.java | 0 .../jupyter/messages/ContentType.java | 5 + .../jupyter/messages/HMACGenerator.java | 49 ++ .../spencerpark/jupyter/messages/Header.java | 83 ++++ .../jupyter/messages/KernelTimestamp.java | 45 ++ .../spencerpark/jupyter/messages/Message.java | 119 +++++ .../jupyter/messages/MessageContext.java | 9 + .../jupyter/messages/MessageType.java | 123 +++++ .../jupyter/messages/ReplyType.java | 5 + .../jupyter/messages/RequestType.java | 5 + .../adapters/ExpressionValueAdapter.java | 38 ++ .../messages/adapters/HeaderAdapter.java | 41 ++ .../adapters/HistoryEntryAdapter.java | 36 ++ .../adapters/HistoryRequestAdapter.java | 30 ++ .../adapters/IdentityJsonElementAdapter.java | 39 ++ .../adapters/KernelTimestampAdapter.java | 22 + .../messages/adapters/MessageTypeAdapter.java | 22 + .../adapters/PublishStatusAdapter.java | 23 + .../messages/adapters/ReplyTypeAdapter.java | 35 ++ .../messages/comm/CommCloseCommand.java | 36 ++ .../jupyter/messages/comm/CommMsgCommand.java | 36 ++ .../messages/comm/CommOpenCommand.java | 44 ++ .../messages/publish/ErrorFormatter.java | 8 + .../messages/publish/PublishClearOutput.java | 29 ++ .../messages/publish/PublishDisplayData.java | 18 + .../messages/publish/PublishError.java | 55 +++ .../messages/publish/PublishExecuteInput.java | 38 ++ .../publish/PublishExecuteResult.java | 27 ++ .../messages/publish/PublishStatus.java | 44 ++ .../messages/publish/PublishStream.java | 39 ++ .../publish/PublishUpdateDisplayData.java | 21 + .../jupyter/messages/reply/CommInfoReply.java | 50 ++ .../jupyter/messages/reply/CompleteReply.java | 70 +++ .../jupyter/messages/reply/ErrorReply.java | 64 +++ .../jupyter/messages/reply/ExecuteReply.java | 66 +++ .../jupyter/messages/reply/HistoryReply.java | 34 ++ .../jupyter/messages/reply/InputReply.java | 31 ++ .../jupyter/messages/reply/InspectReply.java | 38 ++ .../messages/reply/InterruptReply.java | 21 + .../messages/reply/IsCompleteReply.java | 112 +++++ .../messages/reply/KernelInfoReply.java | 90 ++++ .../jupyter/messages/reply/ShutdownReply.java | 34 ++ .../messages/request/CommInfoRequest.java | 36 ++ .../messages/request/CompleteRequest.java | 40 ++ .../messages/request/ExecuteRequest.java | 107 +++++ .../messages/request/HistoryRequest.java | 150 ++++++ .../messages/request/InputRequest.java | 37 ++ .../messages/request/InspectRequest.java | 59 +++ .../messages/request/InterruptRequest.java | 21 + .../messages/request/IsCompleteRequest.java | 31 ++ .../messages/request/KernelInfoRequest.java | 21 + .../messages/request/ShutdownRequest.java | 34 ++ .../src/main/resources/kernel-metadata.json | 4 + .../RenderRequestTypesResolutionTest.java | 66 +++ .../jupyter/kernel/display/RendererTest.java | 454 ++++++++++++++++++ .../kernel/display/mime/MIMETypeTest.java | 51 ++ .../jupyter/kernel/magic/MagicParserTest.java | 142 ++++++ .../kernel/magic/registry/MagicsArgsTest.java | 196 ++++++++ .../kernel/magic/registry/MagicsTest.java | 283 +++++++++++ .../kernel/magic/registry/StaticMagics.java | 15 + .../jupyter/kernel/util/GlobFinderTest.java | 215 +++++++++ .../kernel/util/InheritanceIteratorTest.java | 83 ++++ build.gradle | 25 +- settings.gradle | 1 + 132 files changed, 9481 insertions(+), 5 deletions(-) create mode 100644 basekernel/LICENSE create mode 100644 basekernel/README.md create mode 100644 basekernel/build.gradle create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/channels/DefaultReplyEnvironment.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/channels/HeartbeatChannel.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/channels/IOPubChannel.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/channels/JupyterConnection.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/channels/JupyterInputStream.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/channels/JupyterOutputStream.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/channels/JupyterSocket.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/channels/Loop.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/channels/ReplyEnvironment.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/channels/ShellChannel.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/channels/ShellHandler.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/channels/ShellReplyEnvironment.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/channels/StdinChannel.java rename {src => basekernel/src}/main/java/io/github/spencerpark/jupyter/kernel/BaseKernel.java (100%) create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/DisplayStream.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/ExpressionValue.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/JupyterIO.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/KernelConnectionProperties.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/LanguageInfo.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/ReplacementOptions.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/comm/Comm.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/comm/CommFactory.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/comm/CommManager.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/comm/CommTarget.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/DisplayData.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/DisplayDataRenderable.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/MIMESuffixAssociation.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/RenderContext.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/RenderFunction.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/RenderParams.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/RenderRequestTypes.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/Renderer.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/common/Image.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/common/Text.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/common/Url.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMEGroup.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMESubtype.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMESuffix.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMEType.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMETypeParseException.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/history/HistoryEntry.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/history/HistoryManager.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/CellMagicArgs.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/CellMagicParseContext.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/LineMagicArgs.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/LineMagicParseContext.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/MagicParser.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/common/DisplayMagics.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/common/Load.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/common/Shell.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/common/WriteFile.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/CellMagic.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/CellMagicFunction.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/LineMagic.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/LineMagicFunction.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/MagicArgsParseException.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/Magics.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/MagicsArgs.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/UndefinedMagicException.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/CharPredicate.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/GlobFinder.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/InheritanceIterator.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/SimpleAutoCompleter.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/StringSearch.java rename {src => basekernel/src}/main/java/io/github/spencerpark/jupyter/kernel/util/StringStyler.java (100%) rename {src => basekernel/src}/main/java/io/github/spencerpark/jupyter/kernel/util/TextColor.java (100%) create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/ContentType.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/HMACGenerator.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/Header.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/KernelTimestamp.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/Message.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/MessageContext.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/MessageType.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/ReplyType.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/RequestType.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/ExpressionValueAdapter.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/HeaderAdapter.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/HistoryEntryAdapter.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/HistoryRequestAdapter.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/IdentityJsonElementAdapter.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/KernelTimestampAdapter.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/MessageTypeAdapter.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/PublishStatusAdapter.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/ReplyTypeAdapter.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/comm/CommCloseCommand.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/comm/CommMsgCommand.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/comm/CommOpenCommand.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/ErrorFormatter.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishClearOutput.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishDisplayData.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishError.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishExecuteInput.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishExecuteResult.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishStatus.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishStream.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishUpdateDisplayData.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/CommInfoReply.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/CompleteReply.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/ErrorReply.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/ExecuteReply.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/HistoryReply.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/InputReply.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/InspectReply.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/InterruptReply.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/IsCompleteReply.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/KernelInfoReply.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/ShutdownReply.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/CommInfoRequest.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/CompleteRequest.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/ExecuteRequest.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/HistoryRequest.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/InputRequest.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/InspectRequest.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/InterruptRequest.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/IsCompleteRequest.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/KernelInfoRequest.java create mode 100644 basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/ShutdownRequest.java create mode 100644 basekernel/src/main/resources/kernel-metadata.json create mode 100644 basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/display/RenderRequestTypesResolutionTest.java create mode 100644 basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/display/RendererTest.java create mode 100644 basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMETypeTest.java create mode 100644 basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/magic/MagicParserTest.java create mode 100644 basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/magic/registry/MagicsArgsTest.java create mode 100644 basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/magic/registry/MagicsTest.java create mode 100644 basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/magic/registry/StaticMagics.java create mode 100644 basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/util/GlobFinderTest.java create mode 100644 basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/util/InheritanceIteratorTest.java diff --git a/basekernel/LICENSE b/basekernel/LICENSE new file mode 100644 index 0000000..4dc0e0f --- /dev/null +++ b/basekernel/LICENSE @@ -0,0 +1,19 @@ +Copyright (c) 2017 Spencer Park + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/basekernel/README.md b/basekernel/README.md new file mode 100644 index 0000000..2ca64c9 --- /dev/null +++ b/basekernel/README.md @@ -0,0 +1,7 @@ +# jupyter-jvm-basekernel (vendored) + +This module is a vendored copy of [jupyter-jvm-basekernel](https://github.com/SpencerPark/jupyter-jvm-basekernel) v2.3.0. + +- Source revision: `dc59d998aa4f3c7316c9b3b2ef0c3f3ef3f85705` +- License: MIT, see `LICENSE` +- IJava-specific adaptations are applied to `BaseKernel`, `TextColor`, and `StringStyler` to preserve the existing IJava runtime behavior. diff --git a/basekernel/build.gradle b/basekernel/build.gradle new file mode 100644 index 0000000..38a2536 --- /dev/null +++ b/basekernel/build.gradle @@ -0,0 +1,50 @@ +import org.apache.tools.ant.filters.ReplaceTokens + +plugins { + id 'java-library' +} + +group = 'io.github.spencerpark' +version = '2.3.0-ijava.1' +description = 'Vendored jupyter-jvm-basekernel' + +base.archivesName.set('jupyter-jvm-basekernel') + +java { + toolchain { + languageVersion = JavaLanguageVersion.of(25) + } +} + +repositories { + mavenCentral() +} + +dependencies { + api 'org.zeromq:jeromq:0.6.0' + api 'com.google.code.gson:gson:2.10.1' + + testImplementation 'junit:junit:4.13.2' + testImplementation 'org.hamcrest:hamcrest-all:1.3' + testImplementation 'com.google.jimfs:jimfs:1.1' +} + +tasks.withType(JavaCompile).configureEach { + options.encoding = 'UTF-8' + options.deprecation = true + options.release = 25 + options.compilerArgs << '-parameters' +} + +processResources { + def tokens = [ + 'version': project.version, + 'project': 'jupyter-jvm-basekernel' + ] + inputs.properties(tokens) + filter ReplaceTokens, tokens: tokens +} + +test { + useJUnit() +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/DefaultReplyEnvironment.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/DefaultReplyEnvironment.java new file mode 100644 index 0000000..9d95270 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/DefaultReplyEnvironment.java @@ -0,0 +1,111 @@ +package io.github.spencerpark.jupyter.channels; + +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.Message; +import io.github.spencerpark.jupyter.messages.MessageContext; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.publish.PublishStatus; +import io.github.spencerpark.jupyter.messages.reply.ErrorReply; + +import java.util.Deque; +import java.util.LinkedList; + +public class DefaultReplyEnvironment implements ReplyEnvironment { + private final JupyterSocket shell; + private final JupyterSocket iopub; + + private final MessageContext context; + + private Deque deferred = new LinkedList<>(); + private boolean defer = false; + + public DefaultReplyEnvironment(JupyterSocket shell, JupyterSocket iopub, MessageContext context) { + this.shell = shell; + this.iopub = iopub; + this.context = context; + } + + public JupyterSocket getShell() { + return shell; + } + + public JupyterSocket getIopub() { + return iopub; + } + + public MessageContext getContext() { + return context; + } + + @Override + public void publish(Message msg) { + if (defer) { + deferred.push(() -> iopub.sendMessage(msg)); + this.defer = false; + } else { + iopub.sendMessage(msg); + } + } + + @Override + public void reply(Message msg) { + if (defer) { + deferred.push(() -> shell.sendMessage(msg)); + this.defer = false; + } else { + shell.sendMessage(msg); + } + } + + @Override + public ReplyEnvironment defer() { + this.defer = true; + return this; + } + + @Override + public void defer(Runnable action) { + this.deferred.push(action); + } + + @Override + public void resolveDeferrals() { + if (this.defer) + throw new IllegalStateException("Reply environment is in defer mode but a resolution was request."); + + while (!deferred.isEmpty()) + deferred.pop().run(); + } + + @Override + public > void publish(T content) { + publish(new Message<>(context, content.getType(), content)); + } + + @Override + public > void reply(T content) { + reply(new Message<>(context, content.getType(), content)); + } + + @Override + @SuppressWarnings("unchecked") + public void replyError(MessageType type, ErrorReply error) { + reply(new Message(context, type, error)); + } + + @Override + public void setStatusBusy() { + publish(PublishStatus.BUSY); + } + + @Override + public void setStatusIdle() { + publish(PublishStatus.IDLE); + } + + @Override + public void setBusyDeferIdle() { + setStatusBusy(); + defer().setStatusIdle(); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/HeartbeatChannel.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/HeartbeatChannel.java new file mode 100644 index 0000000..2442d6f --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/HeartbeatChannel.java @@ -0,0 +1,86 @@ +package io.github.spencerpark.jupyter.channels; + +import io.github.spencerpark.jupyter.kernel.KernelConnectionProperties; +import io.github.spencerpark.jupyter.messages.HMACGenerator; +import org.zeromq.SocketType; +import org.zeromq.ZMQ; + +import java.util.concurrent.atomic.AtomicInteger; +import java.util.logging.Level; +import java.util.logging.Logger; + +public class HeartbeatChannel extends JupyterSocket { + private static final long HB_DEFAULT_SLEEP_MS = 500; + + private static final AtomicInteger HEARTBEAT_ID = new AtomicInteger(); + + private final long sleep; + private volatile Loop pulse; + + public HeartbeatChannel(ZMQ.Context context, HMACGenerator hmacGenerator, long sleep) { + super(context, SocketType.REP, hmacGenerator, Logger.getLogger("HeartbeatChannel")); + this.sleep = sleep; + } + + public HeartbeatChannel(ZMQ.Context context, HMACGenerator hmacGenerator) { + this(context, hmacGenerator, HB_DEFAULT_SLEEP_MS); + } + + private boolean isBound() { + return this.pulse != null; + } + + @Override + public void bind(KernelConnectionProperties connProps) { + if (this.isBound()) + throw new IllegalStateException("Heartbeat channel already bound"); + + String channelThreadName = "Heartbeat-" + HEARTBEAT_ID.getAndIncrement(); + String addr = JupyterSocket.formatAddress(connProps.getTransport(), connProps.getIp(), connProps.getHbPort()); + + logger.log(Level.INFO, String.format("Binding %s to %s.", channelThreadName, addr)); + super.bind(addr); + + ZMQ.Poller poller = super.ctx.poller(1); + poller.register(this, ZMQ.Poller.POLLIN); + + this.pulse = new Loop(channelThreadName, this.sleep, () -> { + int events = poller.poll(0); + if (events > 0) { + byte[] msg = this.recv(); + if (msg == null) { + //Error during receive, just continue + super.logger.log(Level.SEVERE, "Poll returned 1 event but could not read the echo string"); + return; + } + if (!this.send(msg)) { + super.logger.log(Level.SEVERE, "Could not send heartbeat reply"); + } + super.logger.log(Level.FINEST, "Heartbeat pulse"); + } + }); + this.pulse.onClose(() -> { + logger.log(Level.INFO, channelThreadName + " shutdown."); + this.pulse = null; + }); + this.pulse.start(); + logger.log(Level.INFO, "Polling on " + channelThreadName); + } + + @Override + public void close() { + if (this.isBound()) + this.pulse.shutdown(); + + super.close(); + } + + @Override + public void waitUntilClose() { + if (this.pulse != null) { + try { + this.pulse.join(); + } catch (InterruptedException ignored) { } + } + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/IOPubChannel.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/IOPubChannel.java new file mode 100644 index 0000000..a72e96a --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/IOPubChannel.java @@ -0,0 +1,23 @@ +package io.github.spencerpark.jupyter.channels; + +import io.github.spencerpark.jupyter.kernel.KernelConnectionProperties; +import io.github.spencerpark.jupyter.messages.HMACGenerator; +import org.zeromq.SocketType; +import org.zeromq.ZMQ; + +import java.util.logging.Level; +import java.util.logging.Logger; + +public class IOPubChannel extends JupyterSocket { + public IOPubChannel(ZMQ.Context context, HMACGenerator hmacGenerator) { + super(context, SocketType.PUB, hmacGenerator, Logger.getLogger("IOPubChannel")); + } + + @Override + public void bind(KernelConnectionProperties connProps) { + String addr = JupyterSocket.formatAddress(connProps.getTransport(), connProps.getIp(), connProps.getIopubPort()); + + logger.log(Level.INFO, String.format("Binding iopub to %s.", addr)); + super.bind(addr); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/JupyterConnection.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/JupyterConnection.java new file mode 100644 index 0000000..c4a8dd7 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/JupyterConnection.java @@ -0,0 +1,88 @@ +package io.github.spencerpark.jupyter.channels; + +import io.github.spencerpark.jupyter.kernel.KernelConnectionProperties; +import io.github.spencerpark.jupyter.messages.Message; +import io.github.spencerpark.jupyter.messages.MessageContext; +import io.github.spencerpark.jupyter.messages.HMACGenerator; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.publish.PublishStatus; +import org.zeromq.ZMQ; + +import java.security.InvalidKeyException; +import java.security.NoSuchAlgorithmException; +import java.util.HashMap; +import java.util.Map; +import java.util.function.Consumer; + +public class JupyterConnection { + private final KernelConnectionProperties connProps; + + private boolean isConnected = false; + private final ZMQ.Context ctx; + + protected final HeartbeatChannel heartbeat; + protected final ShellChannel shell; + protected final ShellChannel control; + protected final StdinChannel stdin; + protected final IOPubChannel iopub; + + private final Map handlers; + + public JupyterConnection(KernelConnectionProperties connProps) throws NoSuchAlgorithmException, InvalidKeyException { + this.connProps = connProps; + this.ctx = ZMQ.context(1); + + HMACGenerator hmacGenerator = connProps.createHMACGenerator(); + + this.heartbeat = new HeartbeatChannel(this.ctx, hmacGenerator); + this.shell = new ShellChannel(this.ctx, hmacGenerator, false, this); + this.control = new ShellChannel(this.ctx, hmacGenerator, true, this); + this.stdin = new StdinChannel(this.ctx, hmacGenerator); + this.iopub = new IOPubChannel(this.ctx, hmacGenerator); + + this.handlers = new HashMap<>(); + } + + public void connect() { + if (!isConnected) { + forEachSocket(s -> s.bind(this.connProps)); + PublishStatus publishStatus = PublishStatus.STARTING; + this.getIOPub().sendMessage(new Message<>(null, PublishStatus.MESSAGE_TYPE, publishStatus)); + this.isConnected = true; + } + } + + public IOPubChannel getIOPub() { + return this.iopub; + } + + public void setHandler(MessageType type, ShellHandler handler) { + this.handlers.put(type, handler); + } + + @SuppressWarnings("unchecked") + public ShellHandler getHandler(MessageType type) { + return this.handlers.get(type); + } + + public ShellReplyEnvironment prepareReplyEnv(ShellChannel shell, MessageContext context) { + return new ShellReplyEnvironment(shell, this.stdin, this.iopub, context); + } + + private void forEachSocket(Consumer consumer) { + consumer.accept(this.heartbeat); + consumer.accept(this.shell); + consumer.accept(this.control); + consumer.accept(this.stdin); + consumer.accept(this.iopub); + } + + public void close() { + forEachSocket(JupyterSocket::close); + this.ctx.close(); + } + + public void waitUntilClose() { + forEachSocket(JupyterSocket::waitUntilClose); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/JupyterInputStream.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/JupyterInputStream.java new file mode 100644 index 0000000..a6b7cca --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/JupyterInputStream.java @@ -0,0 +1,148 @@ +package io.github.spencerpark.jupyter.channels; + +import java.io.InputStream; +import java.nio.charset.Charset; +import java.util.Objects; + +public class JupyterInputStream extends InputStream { + private final Charset encoding; + + private ShellReplyEnvironment env; + private boolean enabled; + private byte[] data = null; + private int bufferPos = 0; + + public JupyterInputStream(Charset encoding, ShellReplyEnvironment env, boolean enabled) { + this.encoding = encoding; + + this.env = env; + this.enabled = enabled; + } + + public JupyterInputStream(Charset encoding) { + this(encoding, null, false); + } + + public JupyterInputStream(ShellReplyEnvironment env, boolean enabled) { + this(JupyterSocket.UTF_8, env, enabled); + } + + public void setEnv(ShellReplyEnvironment env) { + this.env = env; + } + + public void setEnabled(boolean enabled) { + this.enabled = enabled; + } + + public void retractEnv(ShellReplyEnvironment env) { + if (this.env == env) + this.env = null; + } + + public boolean isAttached() { + return this.env != null; + } + + public Charset getEncoding() { + return encoding; + } + + public boolean isEnabled() { + return enabled; + } + + private byte[] readFromFrontend() { + if (this.enabled) + return this.env.readFromStdIn().getBytes(this.encoding); + return new byte[0]; + } + + @Override + public synchronized int read() { + if (this.data == null) { + if (this.env != null) { + //Buffer is empty and there is an environment to read from so + //ask the frontend for input + this.data = this.readFromFrontend(); + this.bufferPos = 0; + } else { + return -1; + } + } + if (this.bufferPos >= this.data.length) { + this.data = null; + if (this.env != null && this.enabled) { + this.data = this.readFromFrontend(); + this.bufferPos = 0; + } else { + return -1; + } + } + + return this.data[this.bufferPos++]; + } + + @Override + public int read(byte[] into, int intoOffset, int len) { + Objects.requireNonNull(into, "Target buffer cannot be null"); + + if (intoOffset < 0) + throw new IndexOutOfBoundsException("intoOffset must be >= 0 but was " + intoOffset); + else if (len < 0) + throw new IndexOutOfBoundsException("len must be >= 0 but was " + len); + else if (len > into.length - intoOffset) + throw new IndexOutOfBoundsException(String.format("Reading len (%d) bytes starting at %d would overflow the buffer.", len, intoOffset)); + + // If the request for some reason asks for 0 bytes then we don't have + // to do anything. + if (len == 0) + return 0; + + // If the first read "ends" then the entire read "ends". Otherwise + // any extra we can batch into this read is great! + int c = this.read(); + if (c == -1) + return -1; + + // Save the first read character, the rest will start at `intoOffset + 1`. + into[intoOffset] = (byte) c; + + // Check how much we can read without blocking. + int available = this.available(); + + // If no extra characters are available immediately then we will stop here + // with only the single first character read. + if (available <= 0) + return 1; + + // If the entire `len` is available in the buffer then that is how much + // we will read. Otherwise we only want to read the amount available so that + // there is no extra blocking read. + int amountToTakeFromBuffer = Math.min(available, len); + + System.arraycopy( + // Copy from the buffered data starting at the current position. + this.data, this.bufferPos, + // Copy into the given buffer starting at `intoOffset + 1` because + // we already read a single character. Don't worry about indexing + // issues as these were checked at the start. + into, intoOffset + 1, + // Copy whatever amount we decided we could take without blocking + // while remaining <= `len`. + amountToTakeFromBuffer + ); + + // Make sure to mark the amount we have taken from the buffer. + this.bufferPos += amountToTakeFromBuffer; + + // We have read what we copied into the buffer plus the initial single + // character that was read. + return amountToTakeFromBuffer + 1; + } + + @Override + public int available() { + return (this.data != null ? this.data.length : 0) - this.bufferPos; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/JupyterOutputStream.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/JupyterOutputStream.java new file mode 100644 index 0000000..b0959ae --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/JupyterOutputStream.java @@ -0,0 +1,45 @@ +package io.github.spencerpark.jupyter.channels; + +import java.io.ByteArrayOutputStream; +import java.util.function.BiConsumer; + +public class JupyterOutputStream extends ByteArrayOutputStream { + private static final int INITIAL_BUFFER_CAP = 1024; + + private ShellReplyEnvironment env; + private final BiConsumer write; + + public JupyterOutputStream(ShellReplyEnvironment env, BiConsumer write) { + super(INITIAL_BUFFER_CAP); + this.env = env; + this.write = write; + } + + public JupyterOutputStream(BiConsumer write) { + this(null, write); + } + + public void setEnv(ShellReplyEnvironment env) { + this.env = env; + } + + public void retractEnv(ShellReplyEnvironment env) { + if (this.env == env) + this.env = null; + } + + public boolean isAttached() { + return this.env != null; + } + + @Override + public void flush() { + if (this.env != null) { + String contents = new String(super.buf, 0, super.count, JupyterSocket.UTF_8); + if (!contents.isEmpty()) + this.write.accept(this.env, contents); + } + + super.reset(); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/JupyterSocket.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/JupyterSocket.java new file mode 100644 index 0000000..621e867 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/JupyterSocket.java @@ -0,0 +1,175 @@ +package io.github.spencerpark.jupyter.channels; + +import com.google.gson.Gson; +import com.google.gson.GsonBuilder; +import com.google.gson.JsonElement; +import com.google.gson.JsonParser; +import com.google.gson.reflect.TypeToken; +import io.github.spencerpark.jupyter.kernel.ExpressionValue; +import io.github.spencerpark.jupyter.kernel.KernelConnectionProperties; +import io.github.spencerpark.jupyter.kernel.history.HistoryEntry; +import io.github.spencerpark.jupyter.messages.*; +import io.github.spencerpark.jupyter.messages.adapters.*; +import io.github.spencerpark.jupyter.messages.publish.PublishStatus; +import io.github.spencerpark.jupyter.messages.reply.ErrorReply; +import io.github.spencerpark.jupyter.messages.request.HistoryRequest; +import org.zeromq.SocketType; +import org.zeromq.ZMQ; + +import java.lang.reflect.Type; +import java.nio.charset.Charset; +import java.util.*; +import java.util.logging.Logger; + +public abstract class JupyterSocket extends ZMQ.Socket { + protected static String formatAddress(String transport, String ip, int port) { + return transport + "://" + ip + ":" + Integer.toString(port); + } + + public static final Charset ASCII = Charset.forName("ascii"); + public static final Charset UTF_8 = Charset.forName("utf8"); + + private static final byte[] IDENTITY_BLOB_DELIMITER = "".getBytes(ASCII); // Comes from a python bytestring + private static final Gson replyGson = new GsonBuilder() + .registerTypeAdapter(HistoryEntry.class, HistoryEntryAdapter.INSTANCE) + .registerTypeAdapter(ExpressionValue.class, ExpressionValueAdapter.INSTANCE) + .create(); + private static final Gson gson = new GsonBuilder() + .registerTypeAdapter(KernelTimestamp.class, KernelTimestampAdapter.INSTANCE) + .registerTypeAdapter(Header.class, HeaderAdapter.INSTANCE) + .registerTypeAdapter(MessageType.class, MessageTypeAdapter.INSTANCE) + .registerTypeAdapter(PublishStatus.class, PublishStatusAdapter.INSTANCE) + .registerTypeAdapter(HistoryRequest.class, HistoryRequestAdapter.INSTANCE) + .registerTypeHierarchyAdapter(ReplyType.class, new ReplyTypeAdapter(replyGson)) + //.setPrettyPrinting() + .create(); + private static final JsonParser json = new JsonParser(); + private static final byte[] EMPTY_JSON_OBJECT = "{}".getBytes(UTF_8); + private static final Type JSON_OBJ_AS_MAP = new TypeToken>() { + }.getType(); + + public static final Logger JUPYTER_LOGGER = Logger.getLogger("Jupyter"); + + protected final ZMQ.Context ctx; + protected final HMACGenerator hmacGenerator; + protected final Logger logger; + protected boolean closed; + + protected JupyterSocket(ZMQ.Context context, SocketType type, HMACGenerator hmacGenerator, Logger logger) { + super(context, type); + this.ctx = context; + this.hmacGenerator = hmacGenerator; + logger.setParent(JUPYTER_LOGGER); + this.logger = logger; + this.closed = false; + } + + public abstract void bind(KernelConnectionProperties connProps); + + public synchronized Message readMessage() { + if (this.closed) + return null; + + List identities = new LinkedList<>(); + byte[] identity = super.recv(); + while (!Arrays.equals(IDENTITY_BLOB_DELIMITER, identity)) { + identities.add(identity); + identity = super.recv(); + } + + //A hex string + String receivedSig = super.recvStr(); + + byte[] headerRaw = super.recv(); + byte[] parentHeaderRaw = super.recv(); + byte[] metadataRaw = super.recv(); + byte[] contentRaw = super.recv(); + + List blobs = new LinkedList<>(); + while (super.hasReceiveMore()) blobs.add(super.recv()); + + String calculatedSig = this.hmacGenerator.calculateSignature(headerRaw, parentHeaderRaw, metadataRaw, contentRaw); + + if (calculatedSig != null && !calculatedSig.equals(receivedSig)) + throw new SecurityException("Message received had invalid signature"); + + Header header = gson.fromJson(new String(headerRaw, UTF_8), Header.class); + + Header parentHeader = null; + JsonElement parentHeaderJson = json.parse(new String(parentHeaderRaw, UTF_8)); + if (parentHeaderJson.isJsonObject() && parentHeaderJson.getAsJsonObject().size() > 0) + parentHeader = gson.fromJson(parentHeaderJson, Header.class); + + Map metadata = gson.fromJson(new String(metadataRaw, UTF_8), JSON_OBJ_AS_MAP); + Object content = gson.fromJson(new String(contentRaw, UTF_8), header.getType().getContentType()); + if (content instanceof ErrorReply) + header = new Header<>(header.getId(), header.getUsername(), header.getSessionId(), header.getTimestamp(), header.getType().error(), header.getVersion()); + + @SuppressWarnings("unchecked") + Message message = new Message(identities, header, parentHeader, metadata, content, blobs); + + logger.finer(() -> "Received from " + super.base().getSocketOptx(zmq.ZMQ.ZMQ_LAST_ENDPOINT) + ":\n" + gson.toJson(message)); + + return message; + } + + @SuppressWarnings("unchecked") + public Message readMessage(MessageType type) { + Message message = readMessage(); + if (message.getHeader().getType() != type) { + throw new RuntimeException("Expected a " + type + " message but received a " + message.getHeader().getType() + " message."); + } + return (Message) message; + } + + public synchronized void sendMessage(Message message) { + if (this.closed) + return; + + byte[] headerRaw = gson.toJson(message.getHeader()).getBytes(UTF_8); + byte[] parentHeaderRaw = message.hasParentHeader() + ? gson.toJson(message.getParentHeader()).getBytes(UTF_8) + : EMPTY_JSON_OBJECT; + byte[] metadata = message.hasMetadata() + ? gson.toJson(message.getMetadata()).getBytes(UTF_8) + : EMPTY_JSON_OBJECT; + byte[] content = gson.toJson(message.getContent()).getBytes(UTF_8); + + String hmac = hmacGenerator.calculateSignature(headerRaw, parentHeaderRaw, metadata, content); + + logger.finer(() -> "Sending to " + super.base().getSocketOptx(zmq.ZMQ.ZMQ_LAST_ENDPOINT) + ":\n" + gson.toJson(message)); + + message.getIdentities().forEach(super::sendMore); + super.sendMore(IDENTITY_BLOB_DELIMITER); + super.sendMore(hmac.getBytes(ASCII)); + super.sendMore(headerRaw); + super.sendMore(parentHeaderRaw); + super.sendMore(metadata); + + if (message.getBlobs() == null) + super.send(content); + else { + super.sendMore(content); + //The last call needs to be a "send" call so as long as "blobs.hasNext()" + //there will be something sent later and so the call needs to be "sendMore" + Iterator blobs = message.getBlobs().iterator(); + byte[] blob; + while (blobs.hasNext()) { + blob = blobs.next(); + if (blobs.hasNext()) + super.sendMore(blob); + else + super.send(blob); + } + } + } + + @Override + public void close() { + super.close(); + this.closed = true; + } + + public void waitUntilClose() { + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/Loop.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/Loop.java new file mode 100644 index 0000000..344afe2 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/Loop.java @@ -0,0 +1,126 @@ +package io.github.spencerpark.jupyter.channels; + +import java.util.Queue; +import java.util.concurrent.LinkedBlockingQueue; +import java.util.function.LongSupplier; +import java.util.function.ToLongFunction; +import java.util.logging.Logger; + +public class Loop extends Thread { + private final Logger logger; + + private volatile boolean running = false; + private final LongSupplier loopBody; + + private volatile Runnable onCloseCb; + private volatile ToLongFunction onErrorCb; + private final Queue runNextQueue; + + public Loop(String name, long sleep, Runnable target) { + this(name, () -> { + target.run(); + return sleep; + }); + } + + public Loop(String name, LongSupplier target) { + super(name); + + this.loopBody = target; + + this.runNextQueue = new LinkedBlockingQueue<>(); + + this.logger = Logger.getLogger("Loop-" + name); + } + + public void onClose(Runnable callback) { + if (this.onCloseCb != null) { + Runnable oldCallback = this.onCloseCb; + this.onCloseCb = () -> { + oldCallback.run(); + callback.run(); + }; + } else { + this.onCloseCb = callback; + } + } + + public void onError(ToLongFunction callback) { + if (this.onErrorCb == null) { + this.onErrorCb = callback; + return; + } + + // Adding a second handler will only be invoked if the + // previous one throws (or rethrows) the incoming exception. + // The callback is invoked with the rethrown exception. + ToLongFunction oldCallback = this.onErrorCb; + this.onErrorCb = t -> { + try { + return oldCallback.applyAsLong(t); + } catch (Throwable tPrime) { + return callback.applyAsLong(tPrime); + } + }; + } + + public void doNext(Runnable next) { + this.runNextQueue.offer(next); + } + + @Override + public void run() { + Runnable next; + while (this.running) { + long sleep; + try { + // Run the loop body + sleep = this.loopBody.getAsLong(); + + // Run all queued tasks + while ((next = this.runNextQueue.poll()) != null) + next.run(); + } catch (Throwable t) { + if (this.onErrorCb != null) + sleep = this.onErrorCb.applyAsLong(t); + else + throw t; + } + + if (sleep > 0) { + try { + Thread.sleep(sleep); + } catch (InterruptedException e) { + this.logger.info("Loop interrupted. Stopping..."); + this.running = false; + } + } else if (sleep < 0) { + this.logger.info("Loop interrupted by a negative sleep request. Stopping..."); + this.running = false; + } + } + + this.logger.info("Running loop shutdown callback."); + + if (this.onCloseCb != null) + this.onCloseCb.run(); + this.onCloseCb = null; + + this.logger.info("Loop stopped."); + } + + @Override + public synchronized void start() { + this.logger.info("Loop starting..."); + + this.running = true; + super.start(); + + this.logger.info("Loop started."); + } + + public void shutdown() { + this.running = false; + this.logger.info("Loop shutdown."); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/ReplyEnvironment.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/ReplyEnvironment.java new file mode 100644 index 0000000..17a0011 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/ReplyEnvironment.java @@ -0,0 +1,60 @@ +package io.github.spencerpark.jupyter.channels; + +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.Message; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.reply.ErrorReply; + +public interface ReplyEnvironment { + void publish(Message msg); + + void reply(Message msg); + + /** + * Defer the next message send until {@link #resolveDeferrals()}. Deferrals + * are resolve in a Last In First Out (LIFO) order. + *

+ * The use case that inspired this functionality is the busy-idle protocol + * component required by Jupyter. + * + * 

+     *      ShellReplyEnvironment env = ...;
+     *
+     *      env.setStatusBusy();
+     *      env.defer().setStatusIdle(); //Push idle message to defer stack
+     *
+     *      env.defer().reply(new ExecuteReply(...)); //Push reply to stack
+     *
+     *      env.writeToStdOut("Test"); //Write "Test" to std out now
+     *
+     *      env.resolveDeferrals();
+     *      //Send the reply
+     *      //Send the idle message
+     *
+ * + * @return this instance for call chaining + */ + ReplyEnvironment defer(); + + /** + * Defer an arbitrary action. See {@link #defer()} but instead of + * deferring the next message send, defer a specific action. + * + * @param action the action to run when the deferrals are resolved + */ + void defer(Runnable action); + + void resolveDeferrals(); + + > void publish(T content); + + > void reply(T content); + + void replyError(MessageType type, ErrorReply error); + + void setStatusBusy(); + + void setStatusIdle(); + + void setBusyDeferIdle(); +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/ShellChannel.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/ShellChannel.java new file mode 100644 index 0000000..4af0fd9 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/ShellChannel.java @@ -0,0 +1,106 @@ +package io.github.spencerpark.jupyter.channels; + +import io.github.spencerpark.jupyter.kernel.KernelConnectionProperties; +import io.github.spencerpark.jupyter.messages.HMACGenerator; +import io.github.spencerpark.jupyter.messages.Message; +import org.zeromq.SocketType; +import org.zeromq.ZMQ; + +import java.util.concurrent.atomic.AtomicInteger; +import java.util.logging.Level; +import java.util.logging.Logger; + +public class ShellChannel extends JupyterSocket { + private static final long SHELL_DEFAULT_LOOP_SLEEP_MS = 50; + private static final AtomicInteger SHELL_ID = new AtomicInteger(); + + private volatile Loop ioloop; + + private final boolean isControl; + private final JupyterConnection connection; + private final long sleep; + + public ShellChannel(ZMQ.Context context, HMACGenerator hmacGenerator, boolean isControl, JupyterConnection connection, long sleep) { + super(context, SocketType.ROUTER, hmacGenerator, Logger.getLogger(isControl ? "ControlChannel" : "ShellChannel")); + this.isControl = isControl; + this.connection = connection; + this.sleep = sleep; + } + + public ShellChannel(ZMQ.Context context, HMACGenerator hmacGenerator, boolean isControl, JupyterConnection connection) { + this(context, hmacGenerator, isControl, connection, SHELL_DEFAULT_LOOP_SLEEP_MS); + } + + private boolean isBound() { + return this.ioloop != null; + } + + @Override + @SuppressWarnings("unchecked") + public void bind(KernelConnectionProperties connProps) { + if (this.isBound()) + throw new IllegalStateException("Shell channel already bound"); + + String channelThreadName = "Shell-" + SHELL_ID.getAndIncrement(); + String addr = JupyterSocket.formatAddress(connProps.getTransport(), connProps.getIp(), + isControl ? connProps.getControlPort() : connProps.getShellPort()); + + logger.log(Level.INFO, String.format("Binding %s to %s.", channelThreadName, addr)); + super.bind(addr); + + ZMQ.Poller poller = super.ctx.poller(1); + poller.register(this, ZMQ.Poller.POLLIN); + + this.ioloop = new Loop(channelThreadName, this.sleep, () -> { + int events = poller.poll(0); + if (events > 0) { + Message message = super.readMessage(); + + ShellHandler handler = connection.getHandler(message.getHeader().getType()); + if (handler != null) { + super.logger.info("Handling message: " + message.getHeader().getType().getName()); + ShellReplyEnvironment env = connection.prepareReplyEnv(this, message); + try { + handler.handle(env, message); + } catch (Exception e) { + super.logger.log(Level.SEVERE, "Unhandled exception handling " + message.getHeader().getType().getName() + ". " + e.getClass().getSimpleName() + " - " + e.getLocalizedMessage()); + } finally { + env.resolveDeferrals(); + } + if (env.isMarkedForShutdown()) { + super.logger.info(channelThreadName + " shutting down connection as environment was marked for shutdown."); + this.connection.close(); + } + } else { + super.logger.log(Level.SEVERE, "Unhandled message: " + message.getHeader().getType().getName()); + } + } + }); + + this.ioloop.onClose(() -> { + logger.log(Level.INFO, channelThreadName + " shutdown."); + this.ioloop = null; + }); + + this.ioloop.start(); + + logger.log(Level.INFO, "Polling on " + channelThreadName); + } + + @Override + public void close() { + if (this.isBound()) + this.ioloop.shutdown(); + + super.close(); + } + + @Override + public void waitUntilClose() { + if (this.ioloop != null) { + try { + this.ioloop.join(); + } catch (InterruptedException ignored) { } + } + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/ShellHandler.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/ShellHandler.java new file mode 100644 index 0000000..6a53e7f --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/ShellHandler.java @@ -0,0 +1,8 @@ +package io.github.spencerpark.jupyter.channels; + +import io.github.spencerpark.jupyter.messages.Message; + +@FunctionalInterface +public interface ShellHandler { + public void handle(ShellReplyEnvironment env, Message message); +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/ShellReplyEnvironment.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/ShellReplyEnvironment.java new file mode 100644 index 0000000..27ac09b --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/ShellReplyEnvironment.java @@ -0,0 +1,49 @@ +package io.github.spencerpark.jupyter.channels; + +import io.github.spencerpark.jupyter.messages.MessageContext; +import io.github.spencerpark.jupyter.messages.publish.PublishStream; + +public class ShellReplyEnvironment extends DefaultReplyEnvironment { + private final StdinChannel stdin; + + private boolean requestShutdown = false; + + protected ShellReplyEnvironment(ShellChannel shell, StdinChannel stdin, JupyterSocket iopub, MessageContext context) { + super(shell, iopub, context); + this.stdin = stdin; + } + + @Override + public ShellReplyEnvironment defer() { + super.defer(); + return this; + } + + public void markForShutdown() { + this.requestShutdown = true; + } + + public boolean isMarkedForShutdown() { + return this.requestShutdown; + } + + public void writeToStdOut(String msg) { + publish(new PublishStream(PublishStream.StreamType.OUT, msg)); + } + + public void writeToStdErr(String msg) { + publish(new PublishStream(PublishStream.StreamType.ERR, msg)); + } + + public String readFromStdIn(String prompt, boolean isPassword) { + return this.stdin.getInput(super.getContext(), prompt, isPassword); + } + + public String readFromStdIn(String prompt) { + return this.readFromStdIn(prompt, false); + } + + public String readFromStdIn() { + return this.readFromStdIn("", false); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/StdinChannel.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/StdinChannel.java new file mode 100644 index 0000000..8c8f4f5 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/channels/StdinChannel.java @@ -0,0 +1,51 @@ +package io.github.spencerpark.jupyter.channels; + +import io.github.spencerpark.jupyter.kernel.KernelConnectionProperties; +import io.github.spencerpark.jupyter.messages.HMACGenerator; +import io.github.spencerpark.jupyter.messages.Message; +import io.github.spencerpark.jupyter.messages.MessageContext; +import io.github.spencerpark.jupyter.messages.reply.InputReply; +import io.github.spencerpark.jupyter.messages.request.InputRequest; +import org.zeromq.SocketType; +import org.zeromq.ZMQ; + +import java.util.logging.Level; +import java.util.logging.Logger; + +public class StdinChannel extends JupyterSocket { + public StdinChannel(ZMQ.Context context, HMACGenerator hmacGenerator) { + super(context, SocketType.ROUTER, hmacGenerator, Logger.getLogger("StdinChannel")); + } + + @Override + public void bind(KernelConnectionProperties connProps) { + String addr = JupyterSocket.formatAddress(connProps.getTransport(), connProps.getIp(), connProps.getStdinPort()); + + logger.log(Level.INFO, String.format("Binding stdin to %s.", addr)); + super.bind(addr); + } + + /** + * Ask the frontend for input. + *

+ * Do not ask for input if an execute request has `allow_stdin=False` + * + * @param context a message that the request with input was invoked by such as an execute request + * @param prompt a prompt string for the front end to include with the input request + * @param isPasswordRequest a flag specifying if the input request is for a password, if so + * the frontend should obscure the user input (for example with password + * dots or not echoing the input) + * + * @return the input string from the frontend. + */ + public synchronized String getInput(MessageContext context, String prompt, boolean isPasswordRequest) { + InputRequest content = new InputRequest(prompt, isPasswordRequest); + Message request = new Message<>(context, InputRequest.MESSAGE_TYPE, content); + + super.sendMessage(request); + + Message reply = super.readMessage(InputReply.MESSAGE_TYPE); + + return reply.getContent().getValue() + System.lineSeparator(); + } +} diff --git a/src/main/java/io/github/spencerpark/jupyter/kernel/BaseKernel.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/BaseKernel.java similarity index 100% rename from src/main/java/io/github/spencerpark/jupyter/kernel/BaseKernel.java rename to basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/BaseKernel.java diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/DisplayStream.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/DisplayStream.java new file mode 100644 index 0000000..ccf2809 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/DisplayStream.java @@ -0,0 +1,41 @@ +package io.github.spencerpark.jupyter.kernel; + +import io.github.spencerpark.jupyter.channels.ShellReplyEnvironment; +import io.github.spencerpark.jupyter.kernel.display.DisplayData; +import io.github.spencerpark.jupyter.messages.publish.PublishDisplayData; +import io.github.spencerpark.jupyter.messages.publish.PublishUpdateDisplayData; + +public class DisplayStream { + private ShellReplyEnvironment env; + + protected void setEnv(ShellReplyEnvironment env) { + this.env = env; + } + + protected void retractEnv(ShellReplyEnvironment env) { + if (this.env == env) + this.env = null; + } + + public boolean isAttached() { + return this.env != null; + } + + public void display(DisplayData data) { + if (this.env != null) + this.env.publish(new PublishDisplayData(data)); + } + + public void updateDisplay(DisplayData data) { + if (!data.hasDisplayId()) + throw new IllegalArgumentException("Data must have a display_id in order to update an existing display."); + + if (this.env != null) + this.env.publish(new PublishUpdateDisplayData(data)); + } + + public void updateDisplay(String id, DisplayData data) { + data.setDisplayId(id); + this.updateDisplay(data); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/ExpressionValue.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/ExpressionValue.java new file mode 100644 index 0000000..c3af9aa --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/ExpressionValue.java @@ -0,0 +1,71 @@ +package io.github.spencerpark.jupyter.kernel; + +import com.google.gson.annotations.SerializedName; +import io.github.spencerpark.jupyter.kernel.display.DisplayData; + +import java.util.List; + +public abstract class ExpressionValue { + + private ExpressionValue() { } // Seal the class + + /** + * Check if this {@link ExpressionValue} is a {@link ExpressionValue.Success Success} + * or not (an {@link ExpressionValue.Error Error}. If this method returns {@code true} + * then this object can be safely cast to a {@link ExpressionValue.Success} or if {@code false} + * then {@link ExpressionValue.Error}. + * + * @return true if this values is an instance of {@link ExpressionValue.Success} and + * false if {@link ExpressionValue.Error}. + */ + public abstract boolean isSuccess(); + + public static class Error extends ExpressionValue { + @SerializedName("ename") + protected final String errName; + @SerializedName("evalue") + protected final String errMsg; + @SerializedName("traceback") + protected final List stacktrace; + + public Error(String errName, String errMsg, List stacktrace) { + this.errName = errName; + this.errMsg = errMsg; + this.stacktrace = stacktrace; + } + + @Override + public boolean isSuccess() { + return false; + } + + public String getErrName() { + return this.errName; + } + + public String getErrMsg() { + return this.errMsg; + } + + public List getStacktrace() { + return this.stacktrace; + } + } + + public static class Success extends ExpressionValue { + protected final DisplayData data; + + public Success(DisplayData data) { + this.data = data; + } + + @Override + public boolean isSuccess() { + return true; + } + + public DisplayData getData() { + return this.data; + } + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/JupyterIO.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/JupyterIO.java new file mode 100644 index 0000000..1f02bfd --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/JupyterIO.java @@ -0,0 +1,68 @@ +package io.github.spencerpark.jupyter.kernel; + +import io.github.spencerpark.jupyter.channels.JupyterInputStream; +import io.github.spencerpark.jupyter.channels.JupyterOutputStream; +import io.github.spencerpark.jupyter.channels.JupyterSocket; +import io.github.spencerpark.jupyter.channels.ShellReplyEnvironment; + +import java.io.InputStream; +import java.io.PrintStream; +import java.io.UnsupportedEncodingException; +import java.nio.charset.Charset; + +public class JupyterIO { + private final JupyterOutputStream jupyterOut; + private final JupyterOutputStream jupyterErr; + private final JupyterInputStream jupyterIn; + + public final DisplayStream display; + + public final PrintStream out; + public final PrintStream err; + public final InputStream in; + + public JupyterIO(Charset encoding) { + this.jupyterOut = new JupyterOutputStream(ShellReplyEnvironment::writeToStdOut); + this.jupyterErr = new JupyterOutputStream(ShellReplyEnvironment::writeToStdErr); + this.jupyterIn = new JupyterInputStream(encoding); + + this.display = new DisplayStream(); + + try { + this.out = new PrintStream(this.jupyterOut, true, encoding.name()); + this.err = new PrintStream(this.jupyterErr, true, encoding.name()); + this.in = this.jupyterIn; + } catch (UnsupportedEncodingException e) { + throw new RuntimeException("Couldn't lookup the charset by name even though it is already a charset...", e); + } + } + + public JupyterIO() { + this(JupyterSocket.UTF_8); + } + + public boolean isAttached() { + return this.jupyterOut.isAttached() + && this.jupyterErr.isAttached() + && this.jupyterIn.isAttached() + && this.display.isAttached(); + } + + protected void setEnv(ShellReplyEnvironment env) { + this.jupyterOut.setEnv(env); + this.jupyterErr.setEnv(env); + this.jupyterIn.setEnv(env); + this.display.setEnv(env); + } + + protected void retractEnv(ShellReplyEnvironment env) { + this.jupyterOut.retractEnv(env); + this.jupyterErr.retractEnv(env); + this.jupyterIn.retractEnv(env); + this.display.retractEnv(env); + } + + protected void setJupyterInEnabled(boolean enabled) { + this.jupyterIn.setEnabled(enabled); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/KernelConnectionProperties.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/KernelConnectionProperties.java new file mode 100644 index 0000000..4624a3c --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/KernelConnectionProperties.java @@ -0,0 +1,111 @@ +package io.github.spencerpark.jupyter.kernel; + +import com.google.gson.Gson; +import com.google.gson.annotations.SerializedName; +import io.github.spencerpark.jupyter.messages.HMACGenerator; + +import java.security.InvalidKeyException; +import java.security.NoSuchAlgorithmException; + +public class KernelConnectionProperties { + + public static KernelConnectionProperties parse(String raw) { + return new Gson().fromJson(raw, KernelConnectionProperties.class); + } + + private String ip; + + @SerializedName("control_port") + private int controlPort; + @SerializedName("shell_port") + private int shellPort; + @SerializedName("stdin_port") + private int stdinPort; + @SerializedName("hb_port") + private int hbPort; + @SerializedName("iopub_port") + private int iopubPort; + + private String transport; + + @SerializedName("signature_scheme") + private String signatureScheme; + private String key; + + private KernelConnectionProperties() { + } + + public KernelConnectionProperties(String ip, int controlPort, int shellPort, int stdinPort, int hbPort, int iopubPort, String transport, String signatureScheme, String key) { + this.ip = ip; + this.controlPort = controlPort; + this.shellPort = shellPort; + this.stdinPort = stdinPort; + this.hbPort = hbPort; + this.iopubPort = iopubPort; + this.transport = transport; + this.signatureScheme = signatureScheme; + this.key = key; + } + + public String getIp() { + return ip; + } + + public int getControlPort() { + return controlPort; + } + + public int getShellPort() { + return shellPort; + } + + public int getStdinPort() { + return stdinPort; + } + + public int getHbPort() { + return hbPort; + } + + public int getIopubPort() { + return iopubPort; + } + + public String getTransport() { + return transport; + } + + public String getSignatureScheme() { + return signatureScheme; + } + + public String getKey() { + return key; + } + + public HMACGenerator createHMACGenerator() throws InvalidKeyException, NoSuchAlgorithmException { + if (key == null || key.isEmpty()) + return HMACGenerator.NO_AUTH_INSTANCE; + else + return new HMACGenerator(signatureScheme, key); + } + + public String toJsonString() { + return new Gson().toJson(this); + } + + @Override + public String toString() { + return "KernelConnectionProperties{" + + "ip='" + ip + '\'' + + ", controlPort=" + controlPort + + ", shellPort=" + shellPort + + ", stdinPort=" + stdinPort + + ", hbPort=" + hbPort + + ", iopubPort=" + iopubPort + + ", transport='" + transport + '\'' + + ", signatureScheme='" + signatureScheme + '\'' + + ", key='" + key + '\'' + + '}'; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/LanguageInfo.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/LanguageInfo.java new file mode 100644 index 0000000..71acf3a --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/LanguageInfo.java @@ -0,0 +1,219 @@ +package io.github.spencerpark.jupyter.kernel; + +import com.google.gson.annotations.SerializedName; + +import java.util.Map; + +public class LanguageInfo { + public static class Help { + protected String text; + protected String url; + + public Help(String text, String url) { + this.text = text; + this.url = url; + } + + public String getText() { + return text; + } + + public String getUrl() { + return url; + } + } + + public static class Builder { + private final String name; + private String version = null; + private String mimetype = "text/plain"; + private String fileExt = ".txt"; + private String pygmentsLexer = null; + private Object codemirrorMode = null; + private String exporter = null; + + public Builder(String name) { + this.name = name; + } + + /** + * Set the version for the language described by this info. It + * is recommended to be a semantic version (eg. 1.2.3) + * + * @param version the version string + * + * @return this builder for chaining + */ + public Builder version(String version) { + this.version = version; + return this; + } + + /** + * Set the mimetype for scripts written in this language. For example + * {@code text/html} or {@code application/javascript}. + * + * @param mimetype the mimetype for scripts written in this language. + * + * @return this builder for chaining + */ + public Builder mimetype(String mimetype) { + this.mimetype = mimetype; + return this; + } + + /** + * Set the file extension for scripts written in this language. For + * example {@code .py} or {@code .mlod}. This allows for a "Download as" + * menu option for this language. + * + * @param ext the file extension including the dot + * + * @return this builder for chaining + */ + public Builder fileExtension(String ext) { + this.fileExt = ext; + return this; + } + + /** + * Set the {@code pygments} lexer for syntax highlighting. By default + * it will be the language name. Use this to set it to something + * different. + *

+ * A list of the default installed lexers can be found + * on the pygments website + * + * @param lexer the name of the lexer + * + * @return this builder for chaining + */ + public Builder pygments(String lexer) { + this.pygmentsLexer = lexer; + return this; + } + + /** + * Set the {@code codemirror} mode for syntax highlighting in the + * notebook. By default it will be the language name. Use this to set it + * to something different. See default modes + * and the codemirror mode option + *

+ * This may also be a mimetype or a language config (see {@link #codemirror(Map)}) + * + * @param mode the code mirror mode + * + * @return this builder for chaining + */ + public Builder codemirror(String mode) { + this.codemirrorMode = mode; + return this; + } + + /** + * Set the {@code codemirror} mode for syntax highlighting in the + * notebook. By default it will be the the language name. Use this to set it + * to something different. For setting the mode by name use {@link #codemirror(String)}. + *

+ * This is a language config + * + * @param mode the code mirror mode config. Must contain a {@code "name"} key + * + * @return this builder for chaining + */ + public Builder codemirror(Map mode) { + this.codemirrorMode = mode; + return this; + } + + /** + * Set the exported for scripts written in this language. By default it just uses + * the {@code "script"} exporter which exports all of the code cells into a file. + * + * @param exporter the name of the exporter if a custom one is also being loaded by + * the kernel + * + * @return this builder for chaining + */ + public Builder exporter(String exporter) { + this.exporter = exporter; + return this; + } + + public LanguageInfo build() { + return new LanguageInfo(name, version, mimetype, fileExt, pygmentsLexer, codemirrorMode, exporter); + } + } + + protected final String name; + + /** + * Semantic version string. X.Y.Z. Language version + */ + protected final String version; + + protected String mimetype; + + @SerializedName("file_extension") + protected String fileExtension; + + /** + * If not defined defaults to {@link #name} + */ + @SerializedName("pygments_lexer") + protected String pygmentsLexer; + + /** + * If not defined defaults to {@link #name}. + *

+ * It may be a {@link String} describing the name of the lexer or the + * MIME type. Otherwise it may be a json object with a `name` field for + * the name/MIME type of the lexer as well as other configuration options. + */ + @SerializedName("codemirror_mode") + protected Object codemirrorMode; + + /** + * If not defined defaults to the general 'script' + */ + @SerializedName("nbconvert_exporter") + protected String nbconvertExporter; + + public LanguageInfo(String name, String version, String mimetype, String fileExtension, String pygmentsLexer, Object codemirrorMode, String nbconvertExporter) { + this.name = name; + this.version = version; + this.mimetype = mimetype; + this.fileExtension = fileExtension; + this.pygmentsLexer = pygmentsLexer; + this.codemirrorMode = codemirrorMode; + this.nbconvertExporter = nbconvertExporter; + } + + public String getName() { + return name; + } + + public String getVersion() { + return version; + } + + public String getMimetype() { + return mimetype; + } + + public String getFileExtension() { + return fileExtension; + } + + public String getPygmentsLexer() { + return pygmentsLexer; + } + + public Object getCodemirrorMode() { + return codemirrorMode; + } + + public String getNbconvertExporter() { + return nbconvertExporter; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/ReplacementOptions.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/ReplacementOptions.java new file mode 100644 index 0000000..dc99c14 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/ReplacementOptions.java @@ -0,0 +1,28 @@ +package io.github.spencerpark.jupyter.kernel; + +import java.util.List; + +public class ReplacementOptions { + private final List replacements; + + private final int sourceStart; + private final int sourceEnd; + + public ReplacementOptions(List replacements, int sourceStart, int sourceEnd) { + this.replacements = replacements; + this.sourceStart = sourceStart; + this.sourceEnd = sourceEnd; + } + + public List getReplacements() { + return replacements; + } + + public int getSourceStart() { + return sourceStart; + } + + public int getSourceEnd() { + return sourceEnd; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/comm/Comm.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/comm/Comm.java new file mode 100644 index 0000000..bf291eb --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/comm/Comm.java @@ -0,0 +1,97 @@ +package io.github.spencerpark.jupyter.kernel.comm; + +import com.google.gson.JsonElement; +import com.google.gson.JsonObject; +import io.github.spencerpark.jupyter.messages.Message; +import io.github.spencerpark.jupyter.messages.comm.CommCloseCommand; +import io.github.spencerpark.jupyter.messages.comm.CommMsgCommand; + +import java.util.List; +import java.util.Map; + +public abstract class Comm { + private final CommManager manager; + private final String id; + private final String targetName; + + private boolean closed = false; + + public Comm(CommManager manager, String id, String targetName) { + this(manager, id, targetName, null); + } + + public Comm(CommManager manager, String id, String targetName, JsonElement initializationData) { + this.manager = manager; + this.id = id; + this.targetName = targetName; + } + + public String getID() { + return this.id; + } + + public String getTargetName() { + return this.targetName; + } + + public boolean isClosed() { + return closed; + } + + public void send(JsonObject data) { + this.manager.messageComm(this.getID(), data); + } + + public void send(JsonObject data, Map metadata, List blobs) { + this.manager.messageComm(this.getID(), data, metadata, blobs); + } + + /** + * A callback for when the kernel receives a message who's destination is + * this comm. This handler gets access to the entire message so that if desired + * the comms may make use of the low level blob segments or want to make use of + * the parent, identities, etc. + *

+ * The data that most comms would be interested in is the {@link CommMsgCommand#getData()} + * which is the payload attached to a message when sent via the frontend's {@code comm.send({})} + * function. Since this can be any arbitrary JSON serializable thing is is given as a + * {@link com.google.gson.JsonElement}. It is recommended to deserialize it this handler to avoid + * passing the JsonElement to too many other classes in case the serialization library changes in + * the future. + * + * @param message the message received from the frontend that is targeted at this comm + */ + protected abstract void onMessage(Message message); + + /** + * Invoked when this comm is closed. The similar {@link Comm#close()} method is used + * to close this comm where as this {@code onClose} is a callback to clean up this comm + * when it is closed either by this side or as the result of a message from the frontend. + *

+ *
If {@code sending}:
+ *
+ * then this method is free to modify the {@code closeMessage} to add any additional data + * to the {@link CommCloseCommand#getData()} or the {@link Message#getBlobs()}. The message + * will be sent after the execution of this method. + *
+ *
If {@code !sending}:
+ *
+ * then this method may be interested in using the destructuring data in {@link CommCloseCommand#getData()} + * that is snt by the front-end upon triggering th close. + *
+ *
+ * + * @param closeMessage the message triggering the close if from. This may contain some destructuring + * parameters in {@link CommCloseCommand#getData()} if the frontend component + * decided to send something. + * @param sending a boolean flag signaling if the close is the being triggered by this side + * ({@code sending == true}) or from the front-end ({@code sending == false}). + */ + protected abstract void onClose(Message closeMessage, boolean sending); + + public final void close() { + if (this.closed) return; + this.manager.closeComm(this); + this.closed = true; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/comm/CommFactory.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/comm/CommFactory.java new file mode 100644 index 0000000..55d4b1b --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/comm/CommFactory.java @@ -0,0 +1,20 @@ +package io.github.spencerpark.jupyter.kernel.comm; + +import io.github.spencerpark.jupyter.messages.Message; +import io.github.spencerpark.jupyter.messages.comm.CommOpenCommand; + +@FunctionalInterface +public interface CommFactory { + + /** + * Create a new {@link Comm} and optionally attach data to the open message before it is sent. + * @param manager the {@link CommManager} that will be responsible for transporting messages + * to and from the created {@link Comm}. + * @param id the id of the new {@link Comm} + * @param target the name of the target on the front-end to communicate with + * @param openMessageToSend the message that will be sent after creating the comm. There are 2 places to attach + * additional data to the send + * @return a new comm. If data must be immediately sent it should be appended to the {@code openMessageToSend}. + */ + public T produce(CommManager manager, String id, String target, Message openMessageToSend); +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/comm/CommManager.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/comm/CommManager.java new file mode 100644 index 0000000..939d76e --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/comm/CommManager.java @@ -0,0 +1,256 @@ +package io.github.spencerpark.jupyter.kernel.comm; + +import com.google.gson.JsonObject; +import io.github.spencerpark.jupyter.channels.JupyterSocket; +import io.github.spencerpark.jupyter.channels.ReplyEnvironment; +import io.github.spencerpark.jupyter.messages.Message; +import io.github.spencerpark.jupyter.messages.MessageContext; +import io.github.spencerpark.jupyter.messages.comm.CommCloseCommand; +import io.github.spencerpark.jupyter.messages.comm.CommMsgCommand; +import io.github.spencerpark.jupyter.messages.comm.CommOpenCommand; +import io.github.spencerpark.jupyter.messages.reply.CommInfoReply; +import io.github.spencerpark.jupyter.messages.request.CommInfoRequest; + +import java.util.*; + +/** + * A CommManager is responsible for keeping track of a group of comms created by any + * of their registered {@link CommTarget}s. + */ +public class CommManager implements Iterable { + protected Map targets; + protected Map comms; + protected JupyterSocket iopub; + protected MessageContext context; + + public CommManager() { + this.targets = new HashMap<>(); + this.comms = new HashMap<>(); + this.iopub = null; + } + + public void setIOPubChannel(JupyterSocket iopub) { + this.iopub = iopub; + } + + public void setMessageContext(MessageContext context) { + this.context = context; + } + + @Override + public Iterator iterator() { + return this.comms.values().iterator(); + } + + /** + * Lookup a comm by its unique id. If the id is unknown + * to this manager it may return null. + * + * @param id the comm id + * + * @return the {@link Comm} with the associated id or null if the id is unknown + */ + public Comm getCommByID(String id) { + return this.comms.get(id); + } + + /** + * Register a new comm that this manager should forward messages to in the event that + * it receives one addressed to a comm with the the {@code comm}'s id. + * + * @param comm the comm to register with this handler + */ + public void registerComm(Comm comm) { + this.comms.put(comm.getID(), comm); + } + + /** + * Unregister a comm from this manager. This prevents the manager from forwarding messages + * to a previously {@link #registerComm(Comm) registered} comm with the {@code id}. + * + * @param id the id of the destination to unregister + * + * @return the comm that was unregistered or null if nothing was unregistered. + */ + public Comm unregisterComm(String id) { + return this.comms.remove(id); + } + + /** + * Open a communication with the frontend. In the event that the front end does + * not have a target registered with the {@code targetName} the expected behaviour is for + * it to send a {@code comm_close} message as soon as possible but there is never any + * confirmation that the comm is open. + * + * @param targetName the name of the target on the frontend to message + * @param factory a comm producer. This is used to create the comm. + * @param the type of {@link Comm} that the {@code factory} produces. + * + * @return a comm who's {@link Comm#send(JsonObject) send} method is targeted at a new comm + * create on the frontend by the target registered with the {@code targetName} or + * {@code null} if the manager could not open the comm. + *

+ * The latter may happen if the manager is not connected to the frontend + */ + public T openComm(String targetName, CommFactory factory) { + if (this.iopub == null) + return null; + String id = UUID.randomUUID().toString(); + + CommOpenCommand content = new CommOpenCommand(id, targetName, new JsonObject()); + Message message = new Message<>(this.context, CommOpenCommand.MESSAGE_TYPE, content); + + T comm = factory.produce(this, id, targetName, message); + + this.iopub.sendMessage(message); + + this.registerComm(comm); + + return comm; + } + + /** + * Send a message to a comm's frontend component. See {@link Comm#send(JsonObject, Map, List)} as well as + * {@link Comm#send(JsonObject)} which is more likely the method to use as the metadata and blobs are lower level + * constructs exposed for completeness but are often not necessary. + *

+ * See {@link #messageComm(String, JsonObject)} for the higher level partner to this method. + * + * @param commID the id of the target comm (or the id of the sending comm as both share the same id) + * @param data the data to send to the frontend + * @param metadata any metadata to attach to the message being sent. May be {@code null} if no metadata is present. + * @param blobs any additional raw data to attach to the message. May be {@code null} if no blobs are present. + */ + public void messageComm(String commID, JsonObject data, Map metadata, List blobs) { + CommMsgCommand content = new CommMsgCommand(commID, data); + Message message = new Message<>(this.context, CommMsgCommand.MESSAGE_TYPE, content, blobs, metadata); + + this.iopub.sendMessage(message); + } + + /** + * Send a message to a comm's frontend component. See {@link Comm#send(JsonObject)} + * + * @param commID the id of the target comm (or the id of the sending comm as both share the same id) + * @param data the data to send to the frontend + */ + public void messageComm(String commID, JsonObject data) { + this.messageComm(commID, data, null, null); + } + + /** + * Close both sides of a communication. This should be invoked whenever a comm is no longer + * is use or destroyed as a counterpart is living in the frontend. Failing to invoke this may + * leak comm instances on the frontend as well as possibly leaving the manager holding on to + * dead references. See {@link Comm#close()}. + * + * @param comm the comm to close + */ + public void closeComm(Comm comm) { + CommCloseCommand content = new CommCloseCommand(comm.getID(), new JsonObject()); + Message message = new Message<>(this.context, CommCloseCommand.MESSAGE_TYPE, content); + + this.iopub.sendMessage(message); + + Comm unregistered = this.unregisterComm(comm.getID()); + if (unregistered != null) + unregistered.onClose(message, true); + } + + /** + * Register a target for comm creation at the frontend's request. A target must + * first be registered in the kernel so that the frontend may ask to create a new + * comm for speaking with the target. + * + * @param targetName the name of the target which must be specified by frontend's + * opening up the communication + * @param target a {@link CommTarget} responsible for creating new comms at this + * target name + */ + public void registerTarget(String targetName, CommTarget target) { + this.targets.put(targetName, target); + } + + /** + * Unregister a target. This doesn't unregister comms with that target name but rather + * prevents the target from creating anything new. + *

+ * See also {@link #registerTarget(String, CommTarget)} + * + * @param targetName the name of the target to unregister + */ + public void unregisterTarget(String targetName) { + this.targets.remove(targetName); + } + + /** + * Lookup a target with the given name. See {@link #registerTarget(String, CommTarget)} + * + * @param targetName the target name to lookup + * + * @return the {@link CommTarget} registered with the {@code targetName} + */ + public CommTarget getTarget(String targetName) { + return this.targets.get(targetName); + } + + // Default comm message handlers. These shouldn't need to be overridden but are more like + // lambda targets that capture this comm manager in it's scope. + + public void handleCommOpenCommand(ReplyEnvironment env, Message commOpenCommandMessage) { + CommOpenCommand openCommand = commOpenCommandMessage.getContent(); + + env.setBusyDeferIdle(); + + CommTarget target = this.getTarget(openCommand.getTargetName()); + if (target == null) { + CommCloseCommand closeCommand = new CommCloseCommand(openCommand.getCommID(), new JsonObject()); + env.publish(closeCommand); + } else { + Comm comm = target.createComm(this, openCommand.getCommID(), openCommand.getTargetName(), commOpenCommandMessage); + this.registerComm(comm); + } + } + + public void handleCommMsgCommand(ReplyEnvironment env, Message commMsgCommandMessage) { + CommMsgCommand msgCommand = commMsgCommandMessage.getContent(); + + env.setBusyDeferIdle(); + + Comm comm = this.getCommByID(msgCommand.getCommID()); + if (comm != null) { + comm.onMessage(commMsgCommandMessage); + } + } + + public void handleCommCloseCommand(ReplyEnvironment env, Message commCloseCommandMessage) { + CommCloseCommand closeCommand = commCloseCommandMessage.getContent(); + + env.setBusyDeferIdle(); + + Comm comm = this.unregisterComm(closeCommand.getCommID()); + if (comm != null) { + comm.onClose(commCloseCommandMessage, false); + } + } + + public void handleCommInfoRequest(ReplyEnvironment env, Message commInfoRequestMessage) { + CommInfoRequest request = commInfoRequestMessage.getContent(); + + env.setBusyDeferIdle(); + + Map comms = new LinkedHashMap<>(); + + String targetNameFilter = request.getTargetName(); + if (targetNameFilter != null) { + this.forEach(comm -> { + if (targetNameFilter.equals(comm.getTargetName())) + comms.put(comm.getID(), new CommInfoReply.CommInfo(comm.getTargetName())); + }); + } else { + this.forEach(comm -> comms.put(comm.getID(), new CommInfoReply.CommInfo(comm.getTargetName()))); + } + + env.reply(new CommInfoReply(comms)); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/comm/CommTarget.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/comm/CommTarget.java new file mode 100644 index 0000000..7d6193f --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/comm/CommTarget.java @@ -0,0 +1,27 @@ +package io.github.spencerpark.jupyter.kernel.comm; + +import io.github.spencerpark.jupyter.messages.Message; +import io.github.spencerpark.jupyter.messages.comm.CommOpenCommand; + +@FunctionalInterface +public interface CommTarget { + /** + * Create a new comm as a result of the frontend making a {@code comm_open} request. This + * is designed to be a constructor reference to a class that extends {@link Comm} overriding + * the {@link Comm#onMessage(Message)}. + * + * For example a plain no-op handler may be {@code CommTarget noop = Comm::new;}. Which would create + * comms that do nothing when the receive a message. + * + * @param commManager the manager that will be responsible for forwarding messages from + * the frontend + * @param id the id for the comm. This will be unique. + * @param targetName the name of this target + * @param msg the entire message that the manager received commanding it to open the comm. This may + * carry additional data in the messages content. Specifically the {@link + * CommOpenCommand#getData() data field}. + * + * @return the newly created comm + */ + public Comm createComm(CommManager commManager, String id, String targetName, Message msg); +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/DisplayData.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/DisplayData.java new file mode 100644 index 0000000..e3d1f99 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/DisplayData.java @@ -0,0 +1,175 @@ +package io.github.spencerpark.jupyter.kernel.display; + +import com.google.gson.annotations.SerializedName; +import io.github.spencerpark.jupyter.kernel.display.mime.MIMEType; + +import java.util.Collections; +import java.util.LinkedHashMap; +import java.util.Map; +import java.util.Set; + +public class DisplayData { + public static final String DISPLAY_ID_KEY = "display_id"; + + public static final DisplayData EMPTY = new DisplayData(Collections.emptyMap()); + + public static final DisplayData EMPTY_STRING = new DisplayData(""); + + public static DisplayData emptyIfNull(DisplayData bundle) { + return bundle == null ? EMPTY : bundle; + } + + private final Map data; + + private Map metadata = new LinkedHashMap<>(); + + @SerializedName("transient") + private Map transientData = null; + + private DisplayData(Map data) { + this.data = data; + } + + public DisplayData(DisplayData that) { + this.data = that.data; + this.metadata = that.metadata; + this.transientData = that.transientData; + } + + public DisplayData(String textData) { + this(); + this.putText(textData); + } + + public DisplayData() { + this(new LinkedHashMap<>()); + } + + private void ensureTransientDataInitialized() { + if (this.transientData == null) + this.transientData = new LinkedHashMap<>(); + } + + public void putData(String mimeType, Object data) { + this.data.put(mimeType, data); + } + + public void putMetaData(String key, Object value) { + this.metadata.put(key, value); + } + + /** + * Add a data point (key-value pair) to the transient data dictionary. This is + * not always applicable but in such cases there is no harm in adding it but the + * front-end may just ignore it. + *

+ * As of writing this the only transient data key supported by iPython is + * {@code display_id} which is only used in the {@code display_data} and + * {@code update_display_data} messages. + *

+ * Third parties may utilize this for other purposes as well. + * + * @param key the data key + * @param value the data value + */ + public void putTransientData(String key, Object value) { + this.ensureTransientDataInitialized(); + this.transientData.put(key, value); + } + + public void putData(MIMEType type, Object data) { + this.putData(type.toString(), data); + } + + public void putMetaData(MIMEType type, Object data) { + this.putMetaData(type.toString(), data); + } + + public void putData(MIMEType type, Object data, Object metadata) { + this.putData(type, data); + this.putMetaData(type, metadata); + } + + public Object getData(MIMEType type) { + return this.data.get(type.toString()); + } + + public boolean hasDataForType(MIMEType type) { + return this.data.containsKey(type.toString()); + } + + public void assign(DisplayData data) { + this.data.putAll(data.data); + + if (this.metadata == null) + this.metadata = data.metadata; + else if (data.metadata != null) + this.metadata.putAll(data.metadata); + + if (this.transientData == null) + this.transientData = data.transientData; + else if (data.transientData != null) + this.transientData.putAll(data.transientData); + } + + public void setDisplayId(String id) { + this.putTransientData(DISPLAY_ID_KEY, id); + } + + public boolean hasDisplayId() { + return this.transientData != null + && this.transientData.containsKey(DISPLAY_ID_KEY); + } + + public String getDisplayId() { + if (this.transientData == null) return null; + + Object id = this.transientData.get(DISPLAY_ID_KEY); + if (id == null) return null; + + return String.valueOf(id); + } + + public void putText(String text) { + this.putData("text/plain", text); + } + + public void putHTML(String html) { + this.putData("text/html", html); + } + + public void putLatex(String latex) { + this.putData("text/latex", latex); + } + + /** + * Add some latex math to the output. + * + * @param math the latex math code EXCLUDING the starting and + * trailing {@code $$} or other latex math mode switchers + */ + public void putMath(String math) { + this.putLatex("$$" + math + "$$"); + } + + public void putMarkdown(String markdown) { + this.putData("text/markdown", markdown); + } + + public void putJavaScript(String javascript) { + this.putData("application/javascript", javascript); + } + + public void putJSON(String json) { + this.putData("application/json", json); + } + + public void putJSON(String json, boolean expanded) { + this.putJSON(json); + this.putMetaData("expanded", expanded); + } + + public void putSVG(String svg) { + this.putData("image/svg+xml", svg); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/DisplayDataRenderable.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/DisplayDataRenderable.java new file mode 100644 index 0000000..5d9b8ba --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/DisplayDataRenderable.java @@ -0,0 +1,80 @@ +package io.github.spencerpark.jupyter.kernel.display; + +import io.github.spencerpark.jupyter.kernel.display.mime.MIMEType; + +import java.util.Collections; +import java.util.Set; +import java.util.function.BiConsumer; + +@FunctionalInterface +public interface DisplayDataRenderable { + static Set ANY = Collections.singleton(MIMEType.ANY); + + /** + * Specifies a set of {@link MIMEType}s that this class may be rendered as. + *

+ * NOTE: Specifying the supported render types does not prevent {@link #render(RenderContext)} + * from being invoked with other types. Implementations should handle these cases gracefully + * with a no-op. + *

+ * When used in conjunction with {@link Renderer} this annotation provides information to the + * routing algorithm. + *

+ * In particular {@link Renderer#render(Object)} will request that the object + * is rendered as the {@link #getPreferredRenderTypes()} types. + * + * @return The set of {@link MIMEType}s that this object can be rendered as. + */ + public default Set getSupportedRenderTypes() { + return DisplayDataRenderable.ANY; + } + + /** + * Species a subset of {@link #getSupportedRenderTypes()} in which this class + * prefers to be rendered as. + *

+ * For example a class may support rendering as {@code application/json} and + * {@code application/xml} but when given a choice should only be rendered as + * {@code application/json}. In this case {@code getPreferredRenderTypes()} should + * be {@code "application/json"}. + * + * @return a set of {@link MIMEType}s that this class + * prefers to be rendered as. + */ + public default Set getPreferredRenderTypes() { + return this.getSupportedRenderTypes(); + } + + /** + * Render this object into the {@link RenderContext#getOutputContainer()} based on the requested types + * from the {@code context}. Implementations may also use the {@code context} + * to delegate rendering. + *

+ * Implementations should test if the {@link RenderContext#wantsDataRenderedAs(MIMEType)} + * for all of the supported types and if true store the rendered data in the container + * at the resolved MIME type, not the supported one. Use the type returned + * by {@link RenderContext#resolveRequestedType(MIMEType)}. + *

+ * For convenience implementations may use {@link RenderContext#renderIfRequested(MIMEType, BiConsumer)} + * which streamlines these operations: + * 

+     * {@code private static MIMEType PNG = MIMEType.parse("image/png");
+     *     private String renderAsPNG() {...}
+     *     public void render(RenderContext context) {
+     *         context.renderIfRequested(PNG, (type, out) -> {
+     *             out.putData(type, this.renderAsPNG());
+     *         });
+     *         // or to store the return value of renderAsPNG at the correct
+     *         // type use
+     *         context.renderIfRequested(PNG, this::renderAsPNG);
+     *         // or if you need the type to make a rendering decision and then store
+     *         // the return value at the correct type
+     *         context.renderIfRequested(PNG, type -> this.renderAsPNG());
+     *     }
+     * }
+     *
+ * + * @param context the context that the render is taking place in. + */ + public void render(RenderContext context); +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/MIMESuffixAssociation.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/MIMESuffixAssociation.java new file mode 100644 index 0000000..74b4988 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/MIMESuffixAssociation.java @@ -0,0 +1,18 @@ +package io.github.spencerpark.jupyter.kernel.display; + +import io.github.spencerpark.jupyter.kernel.display.mime.MIMEType; + +@FunctionalInterface +public interface MIMESuffixAssociation { + static final MIMESuffixAssociation NONE = s -> null; + + /** + * Returns the delegate MIME type associated with a suffix. For example the + * suffix {@code json} is associated with the {@code application/json} type. + * + * @param suffix the suffix to resolve + * + * @return the delegate {@link MIMEType} + */ + MIMEType resolveSuffix(String suffix); +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/RenderContext.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/RenderContext.java new file mode 100644 index 0000000..1fae2c4 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/RenderContext.java @@ -0,0 +1,130 @@ +package io.github.spencerpark.jupyter.kernel.display; + +import io.github.spencerpark.jupyter.kernel.display.mime.MIMEType; + +import java.util.Collections; +import java.util.Map; +import java.util.function.BiConsumer; +import java.util.function.Function; +import java.util.function.Supplier; + +public class RenderContext { + private final RenderRequestTypes requestedTypes; + private final Renderer renderer; + private final Map params; + private final DisplayData out; + + public RenderContext(RenderRequestTypes requestedTypes, Renderer renderer, Map params, DisplayData out) { + this.requestedTypes = requestedTypes; + this.renderer = renderer; + this.params = params; + this.out = out; + } + + public Renderer getRenderer() { + return this.renderer; + } + + public DisplayData getOutputContainer() { + return this.out; + } + + public Map getParams() { + return Collections.unmodifiableMap(this.params); + } + + public Object getParameter(String key) { + return this.params.get(key); + } + + public Object getParameter(String key, Object defaultValue) { + return this.params.getOrDefault(key, defaultValue); + } + + public String getParameterAsString(String key) { + Object value = this.getParameter(key); + return value == null ? null : String.valueOf(value); + } + + public String getParameterAsString(String key, String defaultValue) { + String value = this.getParameterAsString(key); + return value == null ? defaultValue : value; + } + + public Integer getParameterAsInt(String key) { + Object value = this.getParameter(key); + return value == null + ? null + : value instanceof Number + ? ((Number) value).intValue() + : Integer.parseInt(String.valueOf(value)); + } + + public Integer getParameterAsInt(String key, Integer defaultValue) { + Integer value = this.getParameterAsInt(key); + return value == null ? defaultValue : value; + } + + public Double getParameterAsDouble(String key) { + Object value = this.getParameter(key); + return value == null + ? null + : value instanceof Number + ? ((Number) value).doubleValue() + : Double.parseDouble(String.valueOf(value)); + } + + public Double getParameterAsDouble(String key, Double defaultValue) { + Double value = this.getParameterAsDouble(key); + return value == null ? defaultValue : value; + } + + public Boolean getParameterAsBoolean(String key) { + Object value = this.getParameter(key); + return value == null + ? null + : value instanceof Boolean + ? (Boolean) value + : Boolean.parseBoolean(String.valueOf(value)); + } + + public Boolean getParameterAsBoolean(String key, Boolean defaultValue) { + Boolean value = this.getParameterAsBoolean(key); + return value == null ? defaultValue : value; + } + + public boolean wantsDataRenderedAs(MIMEType type) { + return this.requestedTypes.resolveSupportedType(type) != null; + } + + public MIMEType resolveRequestedType(MIMEType supported) { + return this.requestedTypes.resolveSupportedType(supported); + } + + public boolean renderIfRequested(MIMEType supportedType, BiConsumer renderFunction) { + MIMEType resolvedType = this.requestedTypes.resolveSupportedType(supportedType); + if (resolvedType != null) { + renderFunction.accept(resolvedType, this.getOutputContainer()); + return true; + } + return false; + } + + public boolean renderIfRequested(MIMEType supportedType, Function renderFunction) { + MIMEType resolvedType = this.requestedTypes.resolveSupportedType(supportedType); + if (resolvedType != null) { + this.getOutputContainer().putData(resolvedType, renderFunction.apply(resolvedType)); + return true; + } + return false; + } + + public boolean renderIfRequested(MIMEType supportedType, Supplier render) { + MIMEType resolvedType = this.requestedTypes.resolveSupportedType(supportedType); + if (resolvedType != null) { + this.getOutputContainer().putData(resolvedType, render.get()); + return true; + } + return false; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/RenderFunction.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/RenderFunction.java new file mode 100644 index 0000000..db17669 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/RenderFunction.java @@ -0,0 +1,6 @@ +package io.github.spencerpark.jupyter.kernel.display; + +@FunctionalInterface +public interface RenderFunction { + void render(T data, RenderContext context); +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/RenderParams.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/RenderParams.java new file mode 100644 index 0000000..3d73074 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/RenderParams.java @@ -0,0 +1,58 @@ +package io.github.spencerpark.jupyter.kernel.display; + +import java.util.LinkedHashMap; +import java.util.Map; + +/** + * A utility class for inline map construction for use in the context of rendering. + * + * See: {@link Renderer#render(Object, Map)} and {@link Renderer#renderAs(Object, Map, String...)} + * which take a parameter map. + */ +public class RenderParams extends LinkedHashMap { + //TODO use the path map from MellowD to support a getAll query or one with wildcard patterns + public static class Param { + public final String key; + public final T value; + + public Param(String key, T value) { + this.key = key; + this.value = value; + } + } + + public static Param param(String key, T value) { + return new Param<>(key, value); + } + + public static RenderParams paramsOf(Param... params) { + RenderParams renderParams = new RenderParams(); + for (Param p : params) + renderParams.put(p.key, p.value); + return renderParams; + } + + public static RenderParams paramsOf(String key, Object value) { + RenderParams renderParams = new RenderParams(); + renderParams.put(key, value); + return renderParams; + } + + public RenderParams with(String key, Object value) { + this.put(key, value); + return this; + } + + public RenderParams with(Param param) { + this.put(param.key, param.value); + return this; + } + + public RenderParams and(String key, Object value) { + return with(key, value); + } + + public RenderParams and(Param param) { + return with(param); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/RenderRequestTypes.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/RenderRequestTypes.java new file mode 100644 index 0000000..fd42eab --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/RenderRequestTypes.java @@ -0,0 +1,185 @@ +package io.github.spencerpark.jupyter.kernel.display; + +import io.github.spencerpark.jupyter.kernel.display.mime.MIMEType; + +import java.util.*; + +/** + * A smarter set of {@link MIMEType}s. + */ +public class RenderRequestTypes { + public static class Builder { + private final MIMESuffixAssociation suffixAssociation; + + private boolean requestsWildcard; + private final Set entireGroupRequests; + private final Set requestedTypes; + + public Builder(MIMESuffixAssociation suffixAssociation) { + this.suffixAssociation = suffixAssociation; + + this.requestsWildcard = false; + this.entireGroupRequests = new LinkedHashSet<>(); + this.requestedTypes = new LinkedHashSet<>(); + } + + public Builder withType(String type) { + MIMEType mimeType = MIMEType.parse(type); + return this.withType(mimeType); + } + + public Builder withType(MIMEType type) { + if (type.isWildcard()) + this.requestsWildcard = true; + else if (!type.hasSubtype() || type.subtypeIsWildcard()) + this.entireGroupRequests.add(type.getGroup()); + else + this.requestedTypes.add(type); + return this; + } + + public RenderRequestTypes build() { + return new RenderRequestTypes( + this.suffixAssociation, + this.requestsWildcard, + this.requestsWildcard || this.entireGroupRequests.isEmpty() + ? Collections.emptySet() + : this.entireGroupRequests, + this.requestsWildcard || this.requestedTypes.isEmpty() + ? Collections.emptySet() + : this.requestedTypes + ); + } + } + + private final MIMESuffixAssociation suffixAssociation; + + private final boolean requestsWildcard; + private final Set entireGroupRequests; + private final Set requestedTypes; + private final Map> requestedTypesByGroup; + + private RenderRequestTypes(MIMESuffixAssociation suffixAssociation, boolean requestsWildcard, Set entireGroupRequests, Set requestedTypes) { + this.suffixAssociation = suffixAssociation; + this.requestsWildcard = requestsWildcard; + this.entireGroupRequests = entireGroupRequests; + this.requestedTypes = requestedTypes; + + this.requestedTypesByGroup = new LinkedHashMap<>(); + requestedTypes.forEach(t -> + this.requestedTypesByGroup.compute(t.getGroup(), (k, v) -> { + List l = v == null ? new LinkedList<>() : v; + l.add(t); + return l; + }) + ); + } + + /** + * Resolve the requested {@link MIMEType} from a supported type. This query usually returns + * {@code null} or the original {@code supportedType} except in special cases with the suffix. + *

+ * If the {@code supportedType} with the {@link MIMEType#getSuffix() suffix} dropped is requested + * then the resolved type is the {@code supportedType} with the {@link MIMEType#getSuffix() suffix} dropped. + *

+ * If the {@code supportedType}'s {@link MIMEType#getSuffix() suffix} has a {@link MIMESuffixAssociation#resolveSuffix(String) resolved suffix type} + * (like {@code +json} being compatible with {@code application/json}) and the {@link MIMESuffixAssociation#resolveSuffix(String) resolved suffix type} + * is requested, then the {@link MIMESuffixAssociation#resolveSuffix(String) resolved suffix type} is the resolved type. + * + * @param supportedType the type to resolve to one of the requested types. + * + * @return the requested type or {@code null} if the type is not requested. + */ + public MIMEType resolveSupportedType(MIMEType supportedType) { + if (supportedType.isWildcard() || supportedType.subtypeIsWildcard()) + throw new IllegalArgumentException("Cannot resolve type of wildcard MIME type: '" + supportedType.toString() + "'"); + + // Everything is supported + if (this.requestsWildcard) + return supportedType; + + // If the exact type is supported or the group is supported then the exact type + // is supported. + if (this.requestedTypes.contains(supportedType) + || this.entireGroupRequests.contains(supportedType.getGroup())) + return supportedType; + + if (supportedType.hasSuffix()) { + // If dropping the supported type without the suffix is supported then that + // is compatible and is the resolved type. + MIMEType withoutSuffix = supportedType.withoutSuffix(); + if (this.requestedTypes.contains(withoutSuffix)) + return withoutSuffix; + + // If the type association of the suffix is supported then use the association. + MIMEType suffixDelegate = this.suffixAssociation.resolveSuffix(supportedType.getSuffix()); + if (suffixDelegate != null && ( + this.requestedTypes.contains(suffixDelegate) + || this.entireGroupRequests.contains(suffixDelegate.getGroup()))) + return suffixDelegate; + } + + // The type is not supported + return null; + } + + public boolean isRequestedExactly(MIMEType type) { + return this.requestsWildcard + || this.entireGroupRequests.contains(type.getGroup()) + || this.requestedTypes.contains(type); + } + + public void removeFulfilledRequests(DisplayData out) { + this.requestedTypes.removeIf(t -> { + if (out.hasDataForType(t)) { + this.requestedTypesByGroup.compute(t.getGroup(), (k, v) -> { + if (v == null) return null; + v.remove(t); + return v.isEmpty() ? null : v; + }); + return true; + } + return false; + }); + } + + /** + * Check if the request wants something rendered as any of the supported types. + * + * @param supported a set of supported types + * + * @return true if any of the supported types is requested + */ + public boolean anyRequestedIsSupported(Set supported) { + // The request wants everything. As long as something is supported, it is requested. + if (this.requestsWildcard) + return !supported.isEmpty(); + + for (MIMEType t : supported) { + // If any request is supported then as long as the request is not empty, something + // is requested. + if (t.isWildcard() && !this.isEmpty()) + return true; + + // If an entire group is supported then as long as that group is requested or + // something requested has the same group, something is requested. + if (t.subtypeIsWildcard() && ( + this.entireGroupRequests.contains(t.getGroup()) + || this.requestedTypesByGroup.containsKey(t.getGroup()))) + return true; + + // If the supported type can be resolved then it must be requested. + if (this.resolveSupportedType(t) != null) + return true; + } + + // Nothing supported is requested. + return false; + } + + public boolean isEmpty() { + return !this.requestsWildcard + && this.entireGroupRequests.isEmpty() + && this.requestedTypes.isEmpty(); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/Renderer.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/Renderer.java new file mode 100644 index 0000000..d68b591 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/Renderer.java @@ -0,0 +1,277 @@ +package io.github.spencerpark.jupyter.kernel.display; + +import io.github.spencerpark.jupyter.kernel.display.mime.MIMEType; +import io.github.spencerpark.jupyter.kernel.util.InheritanceIterator; + +import java.util.*; + +/** + * A default renderer may be set and maps a group to a specific subtype. + *

+ * A suffix may be mapped to a type. + *

+ * A type has a default mime type (may be a list) and is always also rendered + * as text/plain with toString(). + *

+ * A type must also have other supported types. + *

+ * Objects that implement the render interface override their default renders + * but in the event that renderAs (or displayAs) is invoked the specified types + * override the defaults. + */ +public class Renderer { + private static class RenderFunctionProps { + private final RenderFunction function; + private final Set supportedTypes; + private final Set preferredTypes; + + public RenderFunctionProps(RenderFunction function, Set supportedTypes, Set preferredTypes) { + this.function = function; + this.supportedTypes = supportedTypes; + this.preferredTypes = preferredTypes; + } + + public RenderFunction getFunction() { + return function; + } + + public Set getSupportedTypes() { + return supportedTypes; + } + + public Set getPreferredTypes() { + return preferredTypes; + } + } + + public class RenderRegistration { + private final Set supported; + private final Set preferred; + private final Set> types; + + public RenderRegistration(Class type) { + this.supported = new LinkedHashSet<>(); + this.preferred = new LinkedHashSet<>(); + this.types = new LinkedHashSet<>(); + this.types.add(type); + } + + public RenderRegistration supporting(MIMEType... types) { + Collections.addAll(this.supported, types); + return this; + } + + public RenderRegistration preferring(MIMEType... types) { + supporting(types); + Collections.addAll(this.preferred, types); + return this; + } + + public RenderRegistration supporting(String... types) { + for (String type : types) + this.supported.add(MIMEType.parse(type)); + return this; + } + + public RenderRegistration preferring(String... types) { + supporting(types); + for (String type : types) + this.preferred.add(MIMEType.parse(type)); + return this; + } + + public RenderRegistration onType(Class type) { + this.types.add(type); + return this; + } + + public void register(RenderFunction function) { + Set supported = this.supported.isEmpty() ? DisplayDataRenderable.ANY : this.supported; + Set preferred = this.preferred.isEmpty() ? supported : this.preferred; + Renderer.this.register(supported, preferred, types, function); + } + } + + private final Map> renderFunctions; + private final Map suffixMappings; + + public Renderer() { + this.renderFunctions = new HashMap<>(); + this.suffixMappings = new HashMap<>(); + } + + public RenderRegistration createRegistration(Class type) { + return new RenderRegistration<>(type); + } + + public void register(Set supported, Set preferred, Set> types, RenderFunction function) { + RenderFunctionProps props = new RenderFunctionProps(function, supported, preferred); + + types.forEach(c -> this.renderFunctions.compute(c, (k, v) -> { + List functions = v != null ? v : new LinkedList<>(); + functions.add(props); + return functions; + })); + } + + private static DisplayData finalizeDisplayData(DisplayData data, Object value) { + if (!data.hasDataForType(MIMEType.TEXT_PLAIN)) + data.putText(String.valueOf(value)); + + return data; + } + + /** + * Render the object with the preferred render type. + *

+ * The rendering algorithm is as follows: + *

    + *
  1. + * The object is rendered as {@code text/plain} with {@link String#valueOf(Object)}. + *
    2. + *
  2. + * If the object is {@link DisplayDataRenderable} ask it to render itself as the {@link DisplayDataRenderable#getPreferredRenderTypes() preferred types}. + *
    3. + *
  3. + * Else iterate over the implemented with the {@link InheritanceIterator} until a render function is found. Use this + * function to render the object. + *
    4. + *
+ * + * @param value the object to render. + * @param params a map of parameters that render functions may use. + * + * @return the data container holding the rendered view of the {@code value}. + */ + @SuppressWarnings("unchecked") + public DisplayData render(Object value, Map params) { + DisplayData out = new DisplayData(); + + if (value instanceof DisplayDataRenderable) { + DisplayDataRenderable renderable = (DisplayDataRenderable) value; + + RenderRequestTypes.Builder requestTypes = new RenderRequestTypes.Builder(this.suffixMappings::get); + requestTypes.withType(MIMEType.TEXT_PLAIN); + renderable.getPreferredRenderTypes().forEach(requestTypes::withType); + + renderable.render(new RenderContext(requestTypes.build(), this, params, out)); + + return finalizeDisplayData(out, value); + } + + Iterator inheritedTypes = new InheritanceIterator(value.getClass()); + while (inheritedTypes.hasNext()) { + Class type = inheritedTypes.next(); + + List allRenderFunctionProps = this.renderFunctions.get(type); + if (allRenderFunctionProps != null && !allRenderFunctionProps.isEmpty()) { + for (RenderFunctionProps renderFunctionProps : allRenderFunctionProps) { + RenderRequestTypes.Builder requestTypes = new RenderRequestTypes.Builder(this.suffixMappings::get); + requestTypes.withType(MIMEType.TEXT_PLAIN); + renderFunctionProps.getPreferredTypes().forEach(requestTypes::withType); + + renderFunctionProps.getFunction().render( + value, + new RenderContext(requestTypes.build(), this, params, out) + ); + } + + return finalizeDisplayData(out, value); + } + } + + return finalizeDisplayData(out, value); + } + + /** + * A {@link #render(Object, Map)} variant that supplies an empty parameter map. + * + * @param value the object to render. + * + * @return a {@link DisplayData} container with all the rendered data. + */ + public DisplayData render(Object value) { + return render(value, new LinkedHashMap<>()); + } + + /** + * Render the object as the specified types if possible. + *

+ * The rendering algorithm is as follows: + *

    + *
  1. + * The object is rendered as {@code text/plain} with {@link String#valueOf(Object)} no + * matter what types are requested. + *
    2. + *
  2. + * If the object is {@link DisplayDataRenderable} and any of it's {@link DisplayDataRenderable#getSupportedRenderTypes() supported types} + * are requested, it is asked to render itself. + *
    3. + *
  3. + * While all of the requested types have not be rendered yet: + *
      + *
    1. + * For every type in the {@link InheritanceIterator}, apply the same scheme as step 2. + *
      2. + *
    2. + * Remove all rendered types from the request. + *
      3. + *
    + *
    4. + *
+ * + * @param value the object to render. + * @param params a map of parameters that render functions may use. + * @param types the {@link MIMEType#parse(String) MIME types} to render the object as. + * + * @return a {@link DisplayData} container with all the rendered data. + */ + @SuppressWarnings("unchecked") + public DisplayData renderAs(Object value, Map params, String... types) { + DisplayData out = new DisplayData(); + + RenderRequestTypes.Builder builder = new RenderRequestTypes.Builder(this.suffixMappings::get); + builder.withType(MIMEType.TEXT_PLAIN); + for (String type : types) + builder.withType(type); + + RenderRequestTypes requestTypes = builder.build(); + RenderContext context = new RenderContext(requestTypes, this, params, out); + + if (value instanceof DisplayDataRenderable) { + DisplayDataRenderable renderable = (DisplayDataRenderable) value; + if (requestTypes.anyRequestedIsSupported(renderable.getSupportedRenderTypes())) { + renderable.render(context); + requestTypes.removeFulfilledRequests(out); + } + } + + Iterator inheritedTypes = new InheritanceIterator(value.getClass()); + while (inheritedTypes.hasNext() && !requestTypes.isEmpty()) { + Class type = inheritedTypes.next(); + List allRenderFunctionProps = this.renderFunctions.get(type); + if (allRenderFunctionProps != null) { + for (RenderFunctionProps renderFunctionProps : allRenderFunctionProps) { + if (requestTypes.anyRequestedIsSupported(renderFunctionProps.getSupportedTypes())) { + renderFunctionProps.getFunction().render(value, context); + requestTypes.removeFulfilledRequests(out); + } + } + } + } + + return finalizeDisplayData(out, value); + } + + /** + * A {@link #renderAs(Object, Map, String...)} variant that supplies an empty parameter map. + * + * @param value the object to render. + * @param types the {@link MIMEType#parse(String) MIME types} to render the object as. + * + * @return a {@link DisplayData} container with all the rendered data. + */ + public DisplayData renderAs(Object value, String... types) { + return this.renderAs(value, new LinkedHashMap<>(), types); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/common/Image.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/common/Image.java new file mode 100644 index 0000000..d3bbbcb --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/common/Image.java @@ -0,0 +1,55 @@ +package io.github.spencerpark.jupyter.kernel.display.common; + +import io.github.spencerpark.jupyter.kernel.display.RenderContext; +import io.github.spencerpark.jupyter.kernel.display.Renderer; +import io.github.spencerpark.jupyter.kernel.display.mime.MIMEType; + +import javax.imageio.ImageIO; +import java.io.ByteArrayOutputStream; +import java.io.IOException; +import java.io.InputStream; +import java.util.Base64; + +public class Image { + public static final MIMEType PNG = MIMEType.IMAGE_PNG; + public static final MIMEType JPEG = MIMEType.IMAGE_JPEG; + public static final MIMEType GIF = MIMEType.IMAGE_GIF; + public static final MIMEType SVG = MIMEType.IMAGE_SVG; + + public static void registerAll(Renderer renderer) { + renderer.createRegistration(java.awt.image.RenderedImage.class) + .preferring(PNG) + .supporting(JPEG, GIF) + .register(Image::renderImage); + renderer.createRegistration(InputStream.class) + .preferring(PNG) + .supporting(JPEG, GIF) + .register(Image::renderImageFromStream); + } + + private static String imageTob64(java.awt.image.RenderedImage image, String fmt) { + ByteArrayOutputStream out = new ByteArrayOutputStream(); + + try { + ImageIO.write(image, fmt, Base64.getEncoder().wrap(out)); + + return out.toString("UTF-8"); + } catch (IOException e) { + throw new RuntimeException(e); + } + } + + public static void renderImage(java.awt.image.RenderedImage data, RenderContext context) { + context.renderIfRequested(PNG, () -> imageTob64(data, "png")); + context.renderIfRequested(JPEG, () -> imageTob64(data, "jpeg")); + context.renderIfRequested(GIF, () -> imageTob64(data, "gif")); + } + + public static void renderImageFromStream(InputStream data, RenderContext context) { + try { + renderImage(ImageIO.read(data), context); + } catch (IOException e) { + throw new RuntimeException(e); + } + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/common/Text.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/common/Text.java new file mode 100644 index 0000000..a92fff2 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/common/Text.java @@ -0,0 +1,34 @@ +package io.github.spencerpark.jupyter.kernel.display.common; + +import io.github.spencerpark.jupyter.kernel.display.RenderContext; +import io.github.spencerpark.jupyter.kernel.display.Renderer; +import io.github.spencerpark.jupyter.kernel.display.mime.MIMEType; + +public class Text { + public static MIMEType JS = MIMEType.APPLICATION_JAVASCRIPT; + public static MIMEType PLAIN = MIMEType.TEXT_PLAIN; + public static MIMEType MARKDOWN = MIMEType.TEXT_MARKDOWN; + public static MIMEType LATEX = MIMEType.TEXT_LATEX; + public static MIMEType HTML = MIMEType.TEXT_HTML; + public static MIMEType CSS = MIMEType.TEXT_CSS; + public static MIMEType SVG = MIMEType.IMAGE_SVG; + public static MIMEType JSON = MIMEType.APPLICATION_JSON; + + public static void registerAll(Renderer renderer) { + renderer.createRegistration(CharSequence.class) + .preferring(PLAIN) + .supporting(JS, MARKDOWN, LATEX, HTML, CSS, SVG) + .register(Text::renderCharSequence); + } + + public static void renderCharSequence(CharSequence data, RenderContext context) { + context.renderIfRequested(JS, () -> data); + context.renderIfRequested(PLAIN, () -> data); + context.renderIfRequested(MARKDOWN, () -> data); + context.renderIfRequested(LATEX, () -> data); + context.renderIfRequested(HTML, () -> data); + context.renderIfRequested(CSS, () -> data); + context.renderIfRequested(SVG, () -> data); + context.renderIfRequested(JSON, () -> data); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/common/Url.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/common/Url.java new file mode 100644 index 0000000..3e3a9d6 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/common/Url.java @@ -0,0 +1,64 @@ +package io.github.spencerpark.jupyter.kernel.display.common; + +import io.github.spencerpark.jupyter.kernel.display.DisplayData; +import io.github.spencerpark.jupyter.kernel.display.RenderContext; +import io.github.spencerpark.jupyter.kernel.display.Renderer; +import io.github.spencerpark.jupyter.kernel.display.mime.MIMEType; + +import java.io.IOException; +import java.io.UnsupportedEncodingException; +import java.net.URLEncoder; +import java.util.Collections; +import java.util.Map; + +public class Url { + public static String EMBED_KEY = "embed"; + public static String HTML_TAG_KEY = "url.html.tag"; + public static String HTML_SRC_ATTR_KEY = "url.html.src-attr"; + + public static void registerAll(Renderer renderer) { + renderer.createRegistration(java.net.URL.class) + .supporting(MIMEType.ANY) + .register(Url::renderUrl); + renderer.createRegistration(java.net.URLConnection.class) + .supporting(MIMEType.ANY) + .register((conn, ctx) -> renderUrl(conn.getURL(), ctx)); + } + + public static void renderUrl(java.net.URL url, RenderContext context) { + if (context.getParameterAsBoolean(EMBED_KEY, false)) { + try { + Object content = url.getContent(); + DisplayData rendered = context.getRenderer().render(content, context.getParams()); + context.getOutputContainer().assign(rendered); + } catch (IOException e) { + e.printStackTrace(); + } + } else { + context.renderIfRequested(MIMEType.TEXT_HTML, () -> { + String tag = context.getParameterAsString(HTML_TAG_KEY, "a"); + String srcAttr = context.getParameterAsString(HTML_SRC_ATTR_KEY, "src"); + return renderHTML(tag, srcAttr, url, Collections.emptyMap()); + }); + } + } + + private static String renderHTML(String tag, String srcAttr, java.net.URL url, Map attrs) { + String encodedUrl; + try { + encodedUrl = URLEncoder.encode(url.toExternalForm(), "UTF-8"); + } catch (UnsupportedEncodingException e) { + throw new RuntimeException(e); // Should never happen... + } + + //TODO add some html rendering utilities for the url and html entity encoding + StringBuilder html = new StringBuilder("<"); + html.append(tag); + html.append(" ").append(srcAttr).append("=\"").append(encodedUrl).append('"'); + attrs.forEach((attr, val) -> { + if (val != null) + html.append(" ").append(attr).append("=\"").append(val).append("\""); + }); + return html.toString(); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMEGroup.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMEGroup.java new file mode 100644 index 0000000..a0fcbe2 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMEGroup.java @@ -0,0 +1,112 @@ +package io.github.spencerpark.jupyter.kernel.display.mime; + +import java.util.Objects; + +public class MIMEGroup { + public enum Type { + APPLICATION, + AUDIO, + EXAMPLE, + FONT, + IMAGE, + MESSAGE, + MODEL, + MULTIPART, + TEXT, + VIDEO, + OTHER; + + private final String groupName; + + Type() { + this.groupName = this.name().toLowerCase(); + } + + public String groupName() { + return this.groupName; + } + + @Override + public String toString() { + return this.groupName; + } + } + + public static final MIMEGroup APPLICATION = new MIMEGroup(Type.APPLICATION); + public static final MIMEGroup AUDIO = new MIMEGroup(Type.AUDIO); + public static final MIMEGroup EXAMPLE = new MIMEGroup(Type.EXAMPLE); + public static final MIMEGroup FONT = new MIMEGroup(Type.FONT); + public static final MIMEGroup IMAGE = new MIMEGroup(Type.IMAGE); + public static final MIMEGroup MESSAGE = new MIMEGroup(Type.MESSAGE); + public static final MIMEGroup MODEL = new MIMEGroup(Type.MODEL); + public static final MIMEGroup MULTIPART = new MIMEGroup(Type.MULTIPART); + public static final MIMEGroup TEXT = new MIMEGroup(Type.TEXT); + public static final MIMEGroup VIDEO = new MIMEGroup(Type.VIDEO); + + public static MIMEGroup of(String name) { + switch (name.toLowerCase()) { + case "application": + return APPLICATION; + case "audio": + return AUDIO; + case "example": + return EXAMPLE; + case "font": + return FONT; + case "image": + return IMAGE; + case "message": + return MESSAGE; + case "model": + return MODEL; + case "multipart": + return MULTIPART; + case "text": + return TEXT; + case "video": + return VIDEO; + default: + return new MIMEGroup(name); + } + } + + private final String name; + private final Type type; + + private MIMEGroup(Type type) { + this.name = type.groupName(); + this.type = type; + } + + private MIMEGroup(String other) { + this.name = other; + this.type = Type.OTHER; + } + + public String getName() { + return name; + } + + public Type getType() { + return type; + } + + @Override + public boolean equals(Object o) { + if (this == o) return true; + if (o == null || getClass() != o.getClass()) return false; + MIMEGroup mimeGroup = (MIMEGroup) o; + return (this.type == mimeGroup.type && this.type != Type.OTHER) + || Objects.equals(this.name, mimeGroup.name); + } + + @Override + public int hashCode() { + return Objects.hash(name, type); + } + + @Override + public String toString() { + return this.name; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMESubtype.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMESubtype.java new file mode 100644 index 0000000..ed20879 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMESubtype.java @@ -0,0 +1,38 @@ +package io.github.spencerpark.jupyter.kernel.display.mime; + +public class MIMESubtype { + public static class Tree { + public static final Tree VENDOR = new Tree("vnd"); + public static final Tree PERSONAL = new Tree("prs"); + public static final Tree UNREGISTERED = new Tree("x"); + + public static Tree of(String name) { + switch (name.toLowerCase()) { + case "vnd": return VENDOR; + default: + return new Tree(name); + } + } + + private final String name; + + private Tree(String name) { + this.name = name; + } + + public String getName() { + return name; + } + + @Override + public String toString() { + return getName() + "."; + } + } + + public enum Application { + JSON, + XML, + + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMESuffix.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMESuffix.java new file mode 100644 index 0000000..3697dcf --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMESuffix.java @@ -0,0 +1,67 @@ +package io.github.spencerpark.jupyter.kernel.display.mime; + +/** + * RFC 6839 for the + * +xml, +json, +ber, +der, +fastinfoset, +wbxml, +zip + *

+ * RFC 7049 for the + * +cbor + */ +public class MIMESuffix { + public static final MIMESuffix XML = new MIMESuffix("xml", MIMEType.APPLICATION_XML); + public static final MIMESuffix JSON = new MIMESuffix("json", MIMEType.APPLICATION_JSON); + public static final MIMESuffix BER = new MIMESuffix("ber", null); + public static final MIMESuffix DER = new MIMESuffix("der", null); + public static final MIMESuffix FASTINFOSET = new MIMESuffix("fastinfoset", MIMEType.APPLICATION_FASTINFOSET); + public static final MIMESuffix WBXML = new MIMESuffix("wbxml", MIMEType.APPLICATION_VND_WAP_WBXML); + public static final MIMESuffix ZIP = new MIMESuffix("zip", MIMEType.APPLICATION_ZIP); + public static final MIMESuffix CBOR = new MIMESuffix("cbor", MIMEType.APPLICATION_CBOR); + + public static MIMESuffix of(String name) { + if (name == null) return null; + switch (name.toLowerCase()) { + case "xml": + return XML; + case "json": + return JSON; + case "ber": + return BER; + case "der": + return DER; + case "fastinfoset": + return FASTINFOSET; + case "wbxml": + return WBXML; + case "zip": + return ZIP; + case "cbor": + return CBOR; + default: + return new MIMESuffix(name.toLowerCase(), null); + } + } + + public static MIMESuffix of(MIMEType type) { + return MIMESuffix.of(type.getSuffix()); + } + + private final String suffix; + private final MIMEType delegate; + + private MIMESuffix(String suffix, MIMEType delegate) { + this.suffix = suffix; + this.delegate = delegate; + } + + public String getSuffix() { + return this.suffix; + } + + public MIMEType getDelegate() { + return this.delegate; + } + + public boolean hasDelegate() { + return this.delegate != null; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMEType.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMEType.java new file mode 100644 index 0000000..023c3ca --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMEType.java @@ -0,0 +1,259 @@ +package io.github.spencerpark.jupyter.kernel.display.mime; + +import io.github.spencerpark.jupyter.kernel.util.CharPredicate; + +import java.util.Locale; +import java.util.Objects; + +public class MIMEType { + //TODO look into caching parsed strings in a weakmap? + + private static final CharPredicate RESTRICTED_NAME_CHAR = CharPredicate.builder() + .inRange('a', 'z') + .inRange('A', 'Z') + .inRange('0', '9') + .match("!#$&-^_") + .build(); + + private static final String WILDCARD = "*"; + + public static final MIMEType ANY = new MIMEType(WILDCARD, null, WILDCARD, null); + + public static final MIMEType APPLICATION_XML = MIMEType.parse("application/xml"); + public static final MIMEType APPLICATION_JSON = MIMEType.parse("application/json"); + public static final MIMEType APPLICATION_JAVASCRIPT = MIMEType.parse("application/javascript"); + public static final MIMEType APPLICATION_PDF = MIMEType.parse("application/pdf"); + + public static final MIMEType APPLICATION_FASTINFOSET = MIMEType.parse("application/fastinfoset"); + public static final MIMEType APPLICATION_VND_WAP_WBXML = MIMEType.parse("application/vnd.wap.wbxml"); + public static final MIMEType APPLICATION_ZIP = MIMEType.parse("application/zip"); + /** + * There is a cbor {@code <->} json conversion that can happen. + */ + public static final MIMEType APPLICATION_CBOR = MIMEType.parse("application/cbor"); + + public static final MIMEType TEXT_HTML = MIMEType.parse("text/html"); + public static final MIMEType TEXT_MARKDOWN = MIMEType.parse("text/markdown"); + public static final MIMEType TEXT_LATEX = MIMEType.parse("text/latex"); + public static final MIMEType TEXT_PLAIN = MIMEType.parse("text/plain"); + public static final MIMEType TEXT_CSS = MIMEType.parse("text/css"); + + public static final MIMEType IMAGE_PNG = MIMEType.parse("image/png"); + public static final MIMEType IMAGE_JPEG = MIMEType.parse("image/jpeg"); + public static final MIMEType IMAGE_GIF = MIMEType.parse("image/gif"); + public static final MIMEType IMAGE_SVG = MIMEType.parse("image/svg+xml"); + + /** + * Construct a {@link MIMEType} from a string representation. The grammar + * is from RFC 6838 Section 4.2. + * 

+     *     type-name = restricted-name
+     *     subtype-name = restricted-name
+     *
+     *     restricted-name = restricted-name-first *126restricted-name-chars
+     *     restricted-name-first  = ALPHA / DIGIT
+     *     restricted-name-chars  = ALPHA / DIGIT / "!" / "#" /
+     *                              "$" / "&" / "-" / "^" / "_"
+     *     restricted-name-chars =/ "." ; Characters before first dot always
+     *                                  ; specify a facet name
+     *     restricted-name-chars =/ "+" ; Characters after last plus always
+     *                                  ; specify a structured syntax suffix
+     *
+ * The parser makes some modifications to the specification: + *
    + *
  1. No length restriction on the segments
    2. + *
  2. A subtype may also match exactly "*"
    3. + *
+ * + * @param raw the MIME type represented by a string + * + * @return the {@link MIMEType} represented by the string + * + * @throws MIMETypeParseException if the string representation doesn't match + * the specification + */ + public static MIMEType parse(String raw) throws MIMETypeParseException { + if (WILDCARD.equals(raw)) + return ANY; + + String type = null; + String tree = null; + String subtype; + String suffix = null; + + int subtypeStart = 0; + int pos = -1; + + while (++pos < raw.length()) { + char c = raw.charAt(pos); + switch (c) { + case '+': + case '.': + continue; + } + if (RESTRICTED_NAME_CHAR.test(c)) + continue; + if (c != '/') + throw new MIMETypeParseException(raw, pos, String.format("Expected '/' but got %c", c)); + type = raw.substring(0, pos); + subtypeStart = pos + 1; + break; + } + + if (pos == raw.length()) { + return new MIMEType(raw, null, null, null); + } else if (subtypeStart + 1 == raw.length() && raw.charAt(pos + 1) == '*') { + return new MIMEType(type, null, WILDCARD, null); + } + + int lastSuffixStartPos = -1; + while (++pos < raw.length()) { + char c = raw.charAt(pos); + switch (c) { + case '.': + if (tree == null) { + tree = raw.substring(subtypeStart, pos); + subtypeStart = pos + 1; + } + continue; + case '+': + lastSuffixStartPos = pos; + continue; + } + if (RESTRICTED_NAME_CHAR.test(c)) + continue; + + throw new MIMETypeParseException(raw, pos, String.format("Unexpected char '%c'", c)); + } + + if (lastSuffixStartPos != -1) { + subtype = raw.substring(subtypeStart, lastSuffixStartPos); + suffix = raw.substring(lastSuffixStartPos + 1); + } else { + subtype = raw.substring(subtypeStart); + } + + return new MIMEType(type, tree, subtype, suffix); + } + + private final String group; + private final String tree; + private final String subtype; + private final String suffix; + + public MIMEType(String group, String tree, String subtype, String suffix) { + if (group == null) + throw new IllegalArgumentException("Group must be given."); + + this.group = group.toLowerCase(Locale.ENGLISH); + this.tree = tree != null ? tree.toLowerCase(Locale.ENGLISH) : null; + this.subtype = subtype != null ? subtype.toLowerCase(Locale.ENGLISH) : null; + this.suffix = suffix != null ? suffix.toLowerCase(Locale.ENGLISH) : null; + } + + public String getGroup() { + return group; + } + + public String getTree() { + return tree; + } + + public String getSubtype() { + return subtype; + } + + public String getSuffix() { + return suffix; + } + + public boolean hasTree() { + return this.tree != null; + } + + public boolean hasSubtype() { + return this.subtype != null; + } + + public boolean hasSuffix() { + return this.suffix != null; + } + + public MIMEType withoutSuffix() { + return !this.hasSuffix() + ? this + : new MIMEType(this.group, this.tree, this.subtype, null); + } + + public boolean subtypeIsWildcard() { + return WILDCARD.equals(this.subtype); + } + + public boolean isWildcard() { + return WILDCARD.equals(this.group); + } + + public boolean groupEquals(String group) { + return this.getGroup().equalsIgnoreCase(group); + } + + public boolean treeEquals(String tree) { + return this.hasTree() + ? this.getTree().equalsIgnoreCase(tree) + : tree == null; + } + + public boolean subtypeEquals(String subtype) { + return this.hasSubtype() + ? this.getSubtype().equalsIgnoreCase(subtype) + : subtype == null; + } + + public boolean suffixEquals(String suffix) { + return this.hasSuffix() + ? this.getSuffix().equalsIgnoreCase(suffix) + : suffix == null; + } + + public boolean hasSameGroupAs(MIMEType other) { + return this.getGroup().equals(other.getGroup()); + } + + public boolean hasSameTreeAs(MIMEType other) { + return Objects.equals(this.getTree(), other.getTree()); + } + + public boolean hasSameSubtypeAs(MIMEType other) { + return Objects.equals(this.getSubtype(), other.getSubtype()); + } + + public boolean hasSameSuffixAs(MIMEType other) { + return Objects.equals(this.getSuffix(), other.getSubtype()); + } + + @Override + public boolean equals(Object o) { + if (this == o) return true; + if (o == null || getClass() != o.getClass()) return false; + MIMEType mimeType = (MIMEType) o; + return Objects.equals(group, mimeType.group) && + Objects.equals(tree, mimeType.tree) && + Objects.equals(subtype, mimeType.subtype) && + Objects.equals(suffix, mimeType.suffix); + } + + @Override + public int hashCode() { + return Objects.hash(group, tree, subtype, suffix); + } + + @Override + public String toString() { + StringBuilder sb = new StringBuilder(getGroup()); + if (hasSubtype()) sb.append('/'); + if (hasTree()) sb.append(getTree()).append('.'); + if (hasSubtype()) sb.append(getSubtype()); + if (hasSuffix()) sb.append('+').append(getSuffix()); + return sb.toString(); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMETypeParseException.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMETypeParseException.java new file mode 100644 index 0000000..66e020b --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMETypeParseException.java @@ -0,0 +1,33 @@ +package io.github.spencerpark.jupyter.kernel.display.mime; + +public class MIMETypeParseException extends RuntimeException { + private final String raw; + private final int position; + private final String problem; + + public MIMETypeParseException(String raw, int position, String problem) { + super(raw + '@' + position + ": " + problem); + this.raw = raw; + this.position = position; + this.problem = problem; + } + + public MIMETypeParseException(String raw, int position, String problem, Throwable cause) { + super(raw + '@' + position + ": " + problem, cause); + this.raw = raw; + this.position = position; + this.problem = problem; + } + + public String getSource() { + return raw; + } + + public int getPosition() { + return position; + } + + public String getProblem() { + return problem; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/history/HistoryEntry.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/history/HistoryEntry.java new file mode 100644 index 0000000..567d909 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/history/HistoryEntry.java @@ -0,0 +1,48 @@ +package io.github.spencerpark.jupyter.kernel.history; + +public class HistoryEntry { + protected final int session; + + protected final int cellNumber; + + protected final String input; + + /** + * null if output was specified as false in the request + */ + protected final String output; + + public HistoryEntry(int session, int cellNumber, String input) { + this.session = session; + this.cellNumber = cellNumber; + this.input = input; + this.output = null; + } + + public HistoryEntry(int session, int cellNumber, String input, String output) { + this.session = session; + this.cellNumber = cellNumber; + this.input = input; + this.output = output; + } + + public int getSession() { + return session; + } + + public int getCellNumber() { + return cellNumber; + } + + public String getInput() { + return input; + } + + public String getOutput() { + return output; + } + + public boolean hasOutput() { + return output != null; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/history/HistoryManager.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/history/HistoryManager.java new file mode 100644 index 0000000..f643022 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/history/HistoryManager.java @@ -0,0 +1,146 @@ +package io.github.spencerpark.jupyter.kernel.history; + +import java.util.Collections; +import java.util.EnumSet; +import java.util.List; +import java.util.Set; + +public interface HistoryManager { + public enum ResultFlag { + /** + * Signals that the results should include the transformed output rather than + * the raw output. + */ + TRANSFORMED_INPUT, + + /** + * Signals that the results should include the cell output in addition to the + * input. When set, the manager should take care to include an empty string + * when there is no output rather than {@code null}. + */ + INCLUDE_OUTPUT, + + /** + * Signals that all results should include unique inputs only. + */ + UNIQUE, + } + + /** + * Lookup a specified range of input cells executed by the kernel that this manager + * is working for. + * + * @param sessionOffset an offset index describing the session to search. The current session is represented by 0, + * the previous by -1, and so on. + * @param startCell the index (inclusive) of the first cell to include in the results. + * @param endCell the index (exclusive) of the last cell to include in the results. + * @param flags result affecting flags. Inclusion in the set specifies that the flag is set. + * + * @return a list of history entries in the range. + */ + public default List lookupRange(int sessionOffset, int startCell, int endCell, Set flags) { + return null; + } + + /** + * Lookup a specified range of input cells executed by the kernel that this manager + * is working for. + * + * @param sessionOffset an offset index describing the session to search. The current session is represented by 0, + * the previous by -1, and so on. + * @param startCell the index (inclusive) of the first cell to include in the results. + * @param endCell the index (exclusive) of the last cell to include in the results. + * @param flags result affecting flags. Inclusion in the set specifies that the flag is set. + * + * @return a list of history entries in the range or {@code null} if the method is not supported. + */ + public default List lookupRange(int sessionOffset, int startCell, int endCell, ResultFlag... flags) { + Set flagSet = EnumSet.noneOf(ResultFlag.class); + Collections.addAll(flagSet, flags); + return lookupRange(sessionOffset, startCell, endCell, flagSet); + } + + /** + * Lookup the last {@code length} input cells executed by the kernel that this manager + * is working for. + * + * @param length the number of results to include in the results. + * @param flags result affecting flags. Inclusion in the set specifies that the flag is set. + * + * @return a list of the last {@code length} entries in the history or {@code null} if the method is not supported. + */ + public default List lookupTail(int length, Set flags) { + return null; + } + + /** + * Lookup the last {@code length} input cells executed by the kernel that this manager + * is working for. + * + * @param length the number of results to include in the results. + * @param flags result affecting flags. Inclusion in the set specifies that the flag is set. + * + * @return a list of the last {@code length} entries in the history or {@code null} if the method is not supported. + */ + public default List lookupTail(int length, ResultFlag... flags) { + Set flagSet = EnumSet.noneOf(ResultFlag.class); + Collections.addAll(flagSet, flags); + return lookupTail(length, flagSet); + } + + /** + * Lookup the last {@code length} input cells that match the {@code pattern}. + *

+ * The {@code pattern} is an sqlite glob. More specifically: + *

    + *
  • asterisk ({@code *}) matches 0 or more of any characters
    • + *
  • question mark ({@code ?}) matches exactly 1 of any character
    • + *
  • + * list wildcard ({@code []}) matches any character from the list + *
      + *
    • character ranges are supported with {@code [a-z]} syntax to match {@code a} to {@code z} inclusive
      • + *
    • starting a list wildcard with {@code ^} negates the wildcard
      • + *
    + *
    • + *
+ * + * @param pattern a glob pattern that input cells must match. + * @param length the number of results to include in the results. + * @param flags result affecting flags. Inclusion in the set specifies that the flag is set. + * + * @return a list of the last {@code length} entries in the history that match the {@code pattern} or {@code null} + * if the method is not supported. + */ + public default List search(String pattern, int length, Set flags) { + return null; + } + + /** + * Lookup the last {@code length} input cells that match the {@code pattern}. + *

+ * The {@code pattern} is an sqlite glob. More specifically: + *

    + *
  • asterisk ({@code *}) matches 0 or more of any characters
    • + *
  • question mark ({@code ?}) matches exactly 1 of any character
    • + *
  • + * list wildcard ({@code []}) matches any character from the list + *
      + *
    • character ranges are supported with {@code [a-z]} syntax to match {@code a} to {@code z} inclusive
      • + *
    • starting a list wildcard with {@code ^} negates the wildcard
      • + *
    + *
    • + *
+ * + * @param pattern a glob pattern that input cells must match. + * @param length the number of results to include in the results. + * @param flags result affecting flags. Inclusion in the set specifies that the flag is set. + * + * @return a list of the last {@code length} entries in the history that match the {@code pattern} or {@code null} + * if the method is not supported. + */ + public default List search(String pattern, int length, ResultFlag... flags) { + Set flagSet = EnumSet.noneOf(ResultFlag.class); + Collections.addAll(flagSet, flags); + return search(pattern, length, flagSet); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/CellMagicArgs.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/CellMagicArgs.java new file mode 100644 index 0000000..0619be1 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/CellMagicArgs.java @@ -0,0 +1,26 @@ +package io.github.spencerpark.jupyter.kernel.magic; + +import java.util.List; + +public interface CellMagicArgs extends LineMagicArgs { + public static CellMagicArgs of(String name, List args, String body) { + return new CellMagicArgs() { + @Override + public String getBody() { + return body; + } + + @Override + public String getName() { + return name; + } + + @Override + public List getArgs() { + return args; + } + }; + } + + public String getBody(); +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/CellMagicParseContext.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/CellMagicParseContext.java new file mode 100644 index 0000000..29555a7 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/CellMagicParseContext.java @@ -0,0 +1,28 @@ +package io.github.spencerpark.jupyter.kernel.magic; + +public interface CellMagicParseContext { + public static CellMagicParseContext of(CellMagicArgs args, String rawArgsLine, String rawCell) { + return new CellMagicParseContext() { + @Override + public CellMagicArgs getMagicCall() { + return args; + } + + @Override + public String getRawArgsLine() { + return rawArgsLine; + } + + @Override + public String getRawCell() { + return rawCell; + } + }; + } + + public CellMagicArgs getMagicCall(); + + public String getRawArgsLine(); + + public String getRawCell(); +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/LineMagicArgs.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/LineMagicArgs.java new file mode 100644 index 0000000..a7b01a8 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/LineMagicArgs.java @@ -0,0 +1,23 @@ +package io.github.spencerpark.jupyter.kernel.magic; + +import java.util.List; + +public interface LineMagicArgs { + public static LineMagicArgs of(String name, List args) { + return new LineMagicArgs() { + @Override + public String getName() { + return name; + } + + @Override + public List getArgs() { + return args; + } + }; + } + + public String getName(); + + public List getArgs(); +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/LineMagicParseContext.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/LineMagicParseContext.java new file mode 100644 index 0000000..4990dc1 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/LineMagicParseContext.java @@ -0,0 +1,44 @@ +package io.github.spencerpark.jupyter.kernel.magic; + +public interface LineMagicParseContext { + public static LineMagicParseContext of(LineMagicArgs args, String raw, String rawCell, String rawContextPrefix) { + return new LineMagicParseContext() { + @Override + public LineMagicArgs getMagicCall() { + return args; + } + + @Override + public String getRaw() { + return raw; + } + + @Override + public String getRawCell() { + return rawCell; + } + + @Override + public String getRawContextPrefix() { + return rawContextPrefix; + } + }; + } + + public LineMagicArgs getMagicCall(); + + public String getRaw(); + + public String getRawCell(); + + public String getRawContextPrefix(); + + public default String getLinePrefix() { + String cellPrefix = getRawContextPrefix(); + return cellPrefix.substring(cellPrefix.lastIndexOf('\n') + 1); + } + + public default String getEntireLine() { + return getLinePrefix() + getRaw(); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/MagicParser.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/MagicParser.java new file mode 100644 index 0000000..848cfc8 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/MagicParser.java @@ -0,0 +1,117 @@ +package io.github.spencerpark.jupyter.kernel.magic; + +import java.util.LinkedList; +import java.util.List; +import java.util.function.Function; +import java.util.regex.Matcher; +import java.util.regex.Pattern; + +public class MagicParser { + protected static List split(String args) { + args = args.trim(); + + List split = new LinkedList<>(); + + StringBuilder current = new StringBuilder(); + boolean inQuotes = false; + boolean escape = false; + for (char c : args.toCharArray()) { + switch (c) { + case ' ': + case '\t': + if (inQuotes) { + current.append(c); + } else if (current.length() > 0) { + // If whitespace is closing the string the add the current and reset + split.add(current.toString()); + current.setLength(0); + } + break; + case '\\': + if (escape) { + current.append("\\\\"); + escape = false; + } else { + escape = true; + } + break; + case '\"': + if (escape) { + current.append('"'); + escape = false; + } else { + if (current.length() > 0 && inQuotes) { + split.add(current.toString()); + current.setLength(0); + inQuotes = false; + } else { + inQuotes = true; + } + } + break; + default: + current.append(c); + } + } + + if (current.length() > 0) { + split.add(current.toString()); + } + + return split; + } + + private final Pattern lineMagicPattern; + private final Pattern cellMagicPattern; + + public MagicParser() { + this("^%", "%%"); + } + + public MagicParser(String lineMagicStart, String cellMagicStart) { + this.lineMagicPattern = Pattern.compile(lineMagicStart + "(?\\w.*?)$", Pattern.MULTILINE); + this.cellMagicPattern = Pattern.compile("^(?" + cellMagicStart + "(?\\w.*?))\\R(?(?sU).+?)$"); + } + + public String transformLineMagics(String cell, Function transformer) { + StringBuffer transformedCell = new StringBuffer(); + + Matcher m = this.lineMagicPattern.matcher(cell); + while (m.find()) { + String raw = m.group(); + String rawArgs = m.group("args"); + List split = split(rawArgs); + + LineMagicArgs args = LineMagicArgs.of(split.get(0), split.subList(1, split.size())); + LineMagicParseContext ctx = LineMagicParseContext.of(args, raw, cell, cell.substring(0, m.start())); + + String transformed = transformer.apply(ctx); + if (transformed == null) transformed = raw; + + m.appendReplacement(transformedCell, Matcher.quoteReplacement(transformed)); + } + m.appendTail(transformedCell); + + return transformedCell.toString(); + } + + public CellMagicParseContext parseCellMagic(String cell) { + Matcher m = this.cellMagicPattern.matcher(cell); + + if (!m.matches()) return null; + + String rawArgsLine = m.group("argsLine"); + String rawArgs = m.group("args"); + String body = m.group("body"); + List split = split(rawArgs); + + CellMagicArgs args = CellMagicArgs.of(split.get(0), split.subList(1, split.size()), body); + return CellMagicParseContext.of(args, rawArgsLine, cell); + } + + public String transformCellMagic(String cell, Function transformer) { + CellMagicParseContext ctx = this.parseCellMagic(cell); + + return ctx == null ? cell : transformer.apply(ctx); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/common/DisplayMagics.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/common/DisplayMagics.java new file mode 100644 index 0000000..fe37d1b --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/common/DisplayMagics.java @@ -0,0 +1,71 @@ +package io.github.spencerpark.jupyter.kernel.magic.common; + +import io.github.spencerpark.jupyter.kernel.DisplayStream; +import io.github.spencerpark.jupyter.kernel.display.DisplayData; +import io.github.spencerpark.jupyter.kernel.display.Renderer; +import io.github.spencerpark.jupyter.kernel.display.mime.MIMEType; +import io.github.spencerpark.jupyter.kernel.magic.registry.CellMagic; +import io.github.spencerpark.jupyter.kernel.magic.registry.MagicsArgs; + +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; + +public class DisplayMagics { + private static final MagicsArgs HTML_ARGS = MagicsArgs.builder() + .keyword("isolated", MagicsArgs.KeywordSpec.ONCE) + .onlyKnownFlags().onlyKnownKeywords() + .build(); + + private final Renderer renderer; + private final DisplayStream out; + + public DisplayMagics(Renderer renderer, DisplayStream out) { + this.renderer = renderer; + this.out = out; + } + + @CellMagic + public void html(List args, String body) { + Map> vals = HTML_ARGS.parse(args); + boolean isolated = !vals.get("isolated").isEmpty(); + + DisplayData data = this.renderer.renderAs(body, MIMEType.TEXT_HTML.toString()); + + if (isolated) { + Map meta = new LinkedHashMap<>(); + meta.put("isolated", true); + data.putMetaData(MIMEType.TEXT_HTML, meta); + } + + this.out.display(data); + } + + @CellMagic + public void markdown(List args, String body) { + this.out.display( + this.renderer.renderAs(body, MIMEType.TEXT_MARKDOWN.toString()) + ); + } + + @CellMagic + public void svg(List args, String body) { + this.out.display( + this.renderer.renderAs(body, MIMEType.IMAGE_SVG.toString()) + ); + } + + @CellMagic + public void latex(List args, String body) { + this.out.display( + this.renderer.renderAs(body, MIMEType.TEXT_LATEX.toString()) + ); + } + + @CellMagic(aliases = "js") + public void javascript(List args, String body) { + this.out.display( + this.renderer.renderAs(body, MIMEType.APPLICATION_JAVASCRIPT.toString()) + ); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/common/Load.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/common/Load.java new file mode 100644 index 0000000..c46522a --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/common/Load.java @@ -0,0 +1,150 @@ +package io.github.spencerpark.jupyter.kernel.magic.common; + +import com.google.gson.Gson; +import com.google.gson.GsonBuilder; +import com.google.gson.stream.JsonReader; +import io.github.spencerpark.jupyter.kernel.magic.registry.LineMagic; +import io.github.spencerpark.jupyter.kernel.magic.registry.MagicsArgs; + +import java.io.FileNotFoundException; +import java.io.IOException; +import java.io.Reader; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.nio.file.Paths; +import java.util.Collections; +import java.util.List; +import java.util.Map; +import java.util.function.Consumer; +import java.util.stream.Collectors; + +public class Load { + @FunctionalInterface + public static interface Executor { + public void execute(String code) throws Exception; + } + + private static final ThreadLocal GSON = ThreadLocal.withInitial(() -> + new GsonBuilder().create()); + + private static final MagicsArgs LOAD_ARGS = MagicsArgs.builder() + .required("source") + .onlyKnownFlags().onlyKnownKeywords() + .build(); + + // This slightly verbose implementation is designed to take advantage of gson as a streaming parser + // in which we can only take what we need on the fly and pass each cell to the handler without needing + // to keep the entire notebook in memory. + // This should be a big help for larger notebooks. + private static void forEachCell(Path notebookPath, Executor handle) throws Exception { + try (Reader in = Files.newBufferedReader(notebookPath, StandardCharsets.UTF_8)) { + JsonReader reader = GSON.get().newJsonReader(in); + reader.beginObject(); + while (reader.hasNext()) { + String name = reader.nextName(); + if (!name.equals("cells")) { + reader.skipValue(); + continue; + } + + // Parsing cells + reader.beginArray(); + while (reader.hasNext()) { + Boolean isCode = null; + String source = null; + + reader.beginObject(); + while (reader.hasNext()) { + // If the cell type was parsed and wasn't code, then don't + // bother doing any more work. Skip the rest. + if (isCode != null && !isCode) { + reader.skipValue(); + continue; + } + + switch (reader.nextName()) { + case "cell_type": + // We are only concerned with code cells. + String cellType = reader.nextString(); + isCode = cellType.equals("code"); + break; + case "source": + // "source" is an array of lines. + StringBuilder srcBuilder = new StringBuilder(); + reader.beginArray(); + while (reader.hasNext()) + srcBuilder.append(reader.nextString()); + reader.endArray(); + source = srcBuilder.toString(); + break; + default: + reader.skipValue(); + break; + } + } + reader.endObject(); + + // Found a code cell! + if (isCode != null && isCode) + handle.execute(source); + } + reader.endArray(); + } + reader.endObject(); + } + } + + private final List fileExtensions; + private final Executor exec; + + public Load(List fileExtensions, Executor exec) { + this.fileExtensions = fileExtensions == null + ? Collections.emptyList() + : fileExtensions.stream() + .map(e -> e.startsWith(".") ? e : "." + e) + .collect(Collectors.toList()); + this.exec = exec; + } + + @LineMagic + public void load(List args) throws Exception { + Map> vals = LOAD_ARGS.parse(args); + + Path sourcePath = Paths.get(vals.get("source").get(0)).toAbsolutePath(); + + if (Files.isRegularFile(sourcePath)) { + if (sourcePath.getFileName().toString().endsWith(".ipynb")) { + // Execute a notebook, run all cells in there. + Load.forEachCell(sourcePath, this.exec); + return; + } + + String sourceContents = new String(Files.readAllBytes(sourcePath), StandardCharsets.UTF_8); + this.exec.execute(sourceContents); + return; + } + + String file = sourcePath.getFileName().toString(); + + // Try and see if adding any of the supported extensions gives a file. + for (String extension : this.fileExtensions) { + Path scriptPath = sourcePath.resolveSibling(file + extension); + if (Files.isRegularFile(scriptPath)) { + String sourceContents = new String(Files.readAllBytes(scriptPath), StandardCharsets.UTF_8); + this.exec.execute(sourceContents); + return; + } + } + + // Try a notebook last. + Path scriptPath = sourcePath.resolveSibling(file + ".ipynb"); + if (Files.isRegularFile(scriptPath)) { + // Execute a notebook, run all cells in there. + Load.forEachCell(scriptPath, this.exec); + return; + } + + throw new FileNotFoundException("Could not find any source at '" + sourcePath + "'. Also tried with extensions: [.ipynb, " + this.fileExtensions.stream().collect(Collectors.joining(", ")) + "]."); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/common/Shell.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/common/Shell.java new file mode 100644 index 0000000..ca5ce40 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/common/Shell.java @@ -0,0 +1,32 @@ +package io.github.spencerpark.jupyter.kernel.magic.common; + +import io.github.spencerpark.jupyter.kernel.magic.registry.LineMagic; + +import java.io.BufferedReader; +import java.io.InputStreamReader; +import java.util.LinkedList; +import java.util.List; + +public class Shell { + @LineMagic + public static List sh(List args) throws Exception { + Process p = new ProcessBuilder() + .command(args) + .start(); + + List output = new LinkedList<>(); + BufferedReader reader = new BufferedReader(new InputStreamReader(p.getInputStream())); + + String line; + while ((line = reader.readLine()) != null) + output.add(line); + + try { + p.waitFor(); + } catch (InterruptedException e) { + p.destroy(); + } + + return output; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/common/WriteFile.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/common/WriteFile.java new file mode 100644 index 0000000..3a5409a --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/common/WriteFile.java @@ -0,0 +1,39 @@ +package io.github.spencerpark.jupyter.kernel.magic.common; + +import io.github.spencerpark.jupyter.kernel.magic.registry.CellMagic; +import io.github.spencerpark.jupyter.kernel.magic.registry.MagicsArgs; + +import java.io.File; +import java.io.FileOutputStream; +import java.io.OutputStreamWriter; +import java.nio.charset.Charset; +import java.nio.file.FileAlreadyExistsException; +import java.util.List; +import java.util.Map; + +public class WriteFile { + private static final MagicsArgs WRITEFILE_ARGS = MagicsArgs.builder() + .required("filename") + .flag("append", 'a') + .onlyKnownFlags().onlyKnownKeywords() + .build(); + + @CellMagic + public static Void writefile(List args, String body) throws Exception { + Map> vals = WRITEFILE_ARGS.parse(args); + + String fileName = vals.get("filename").get(0); + boolean append = !vals.get("append").isEmpty(); + + File file = new File(fileName); + + if (file.isDirectory()) + throw new FileAlreadyExistsException("Cannot write to file " + fileName + ". It is a directory."); + + try (OutputStreamWriter fileOut = new OutputStreamWriter(new FileOutputStream(file, append), Charset.forName("utf8"))) { + fileOut.write(body); + } + + return null; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/CellMagic.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/CellMagic.java new file mode 100644 index 0000000..88de0fa --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/CellMagic.java @@ -0,0 +1,14 @@ +package io.github.spencerpark.jupyter.kernel.magic.registry; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +@Target(ElementType.METHOD) +@Retention(RetentionPolicy.RUNTIME) +public @interface CellMagic { + String value() default ""; + + String[] aliases() default {}; +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/CellMagicFunction.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/CellMagicFunction.java new file mode 100644 index 0000000..b9df5a1 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/CellMagicFunction.java @@ -0,0 +1,8 @@ +package io.github.spencerpark.jupyter.kernel.magic.registry; + +import java.util.List; + +@FunctionalInterface +public interface CellMagicFunction { + public T execute(List args, String body) throws Exception; +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/LineMagic.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/LineMagic.java new file mode 100644 index 0000000..776ce1c --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/LineMagic.java @@ -0,0 +1,14 @@ +package io.github.spencerpark.jupyter.kernel.magic.registry; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +@Target(ElementType.METHOD) +@Retention(RetentionPolicy.RUNTIME) +public @interface LineMagic { + String value() default ""; + + String[] aliases() default {}; +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/LineMagicFunction.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/LineMagicFunction.java new file mode 100644 index 0000000..1298bfb --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/LineMagicFunction.java @@ -0,0 +1,8 @@ +package io.github.spencerpark.jupyter.kernel.magic.registry; + +import java.util.List; + +@FunctionalInterface +public interface LineMagicFunction { + public T execute(List args) throws Exception; +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/MagicArgsParseException.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/MagicArgsParseException.java new file mode 100644 index 0000000..f7e4a1d --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/MagicArgsParseException.java @@ -0,0 +1,18 @@ +package io.github.spencerpark.jupyter.kernel.magic.registry; + +public class MagicArgsParseException extends RuntimeException { + public MagicArgsParseException() { + } + + public MagicArgsParseException(String format, Object... args) { + super(String.format(format, args)); + } + + public MagicArgsParseException(String message, Throwable cause) { + super(message, cause); + } + + public MagicArgsParseException(Throwable cause) { + super(cause); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/Magics.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/Magics.java new file mode 100644 index 0000000..e2d7fc3 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/Magics.java @@ -0,0 +1,231 @@ +package io.github.spencerpark.jupyter.kernel.magic.registry; + +import java.lang.reflect.*; +import java.util.HashMap; +import java.util.List; +import java.util.Map; + +public class Magics { + private final Map> lineMagics; + private final Map> cellMagics; + + public Magics() { + this.lineMagics = new HashMap<>(); + this.cellMagics = new HashMap<>(); + } + + // Magic application + + public T applyLineMagic(String name, List args) throws Exception { + @SuppressWarnings("unchecked") + LineMagicFunction magic = (LineMagicFunction) this.lineMagics.get(name); + + if (magic == null) + throw new UndefinedMagicException(name, true); + + return magic.execute(args); + } + + public T applyCellMagic(String name, List args, String body) throws Exception { + @SuppressWarnings("unchecked") + CellMagicFunction magic = (CellMagicFunction) this.cellMagics.get(name); + + if (magic == null) + throw new UndefinedMagicException(name, false); + + return magic.execute(args, body); + } + + // Magic registration + + public void registerLineMagic(String name, LineMagicFunction magic) { + this.lineMagics.put(name, magic); + } + + public void registerCellMagic(String name, CellMagicFunction magic) { + this.cellMagics.put(name, magic); + } + + public &CellMagicFunction> void registerLineCellMagic(String name, T magic) { + this.lineMagics.put(name, magic); + this.cellMagics.put(name, magic); + } + + // Reflective magic registration + + public void registerMagics(Object magics) { + registerMagics(magics.getClass(), magics); + } + + public void registerMagics(Class magicsClass) { + registerMagics(magicsClass, null); + } + + private void registerMagics(Class magicsClass, Object magics) { + for (Method method : magicsClass.getDeclaredMethods()) { + LineMagic lineMagic = method.getAnnotation(LineMagic.class); + CellMagic cellMagic = method.getAnnotation(CellMagic.class); + + if (lineMagic == null && cellMagic == null) continue; + + if (method.getParameterCount() == 0) { + // Magic function with no arguments + registerNoArgsReflectionMagic(magics, method, lineMagic, cellMagic); + } else if (lineMagic != null && cellMagic != null) { + // Line cell magic with some arguments + registerLineCellReflectionMagic(magics, method, lineMagic, cellMagic); + } else if (lineMagic != null) { + // Just line magic + registerLineReflectionMagic(magics, method, lineMagic); + } else { + // Just cell magic + registerCellReflectionMagic(magics, method, cellMagic); + } + } + } + + private static Object invoke(Method m, Object instance, Object... args) throws Exception { + try { + return m.invoke(instance, args); + } catch (InvocationTargetException e) { + Throwable cause = e.getCause(); + if (cause instanceof Exception) + throw ((Exception) cause); + throw new RuntimeException(cause.getMessage(), cause); + } + } + + private static class NoArgsReflectionMagicFunction implements LineMagicFunction, CellMagicFunction { + private final Object instance; + private final Method method; + + NoArgsReflectionMagicFunction(Object instance, Method method) { + this.instance = instance; + this.method = method; + } + + @Override + public Object execute(List args, String body) throws Exception { + return invoke(method, instance); + } + + @Override + public Object execute(List args) throws Exception { + return invoke(method, instance); + } + } + + private static class LineCellReflectionMagicFunction implements LineMagicFunction, CellMagicFunction { + private final Object instance; + private final Method method; + + LineCellReflectionMagicFunction(Object instance, Method method) { + this.instance = instance; + this.method = method; + } + + @Override + public Object execute(List args, String body) throws Exception { + return invoke(method, instance, args, body); + } + + @Override + public Object execute(List args) throws Exception { + return invoke(method, instance, args, null); + } + } + + private static class LineReflectionMagicFunction implements LineMagicFunction { + private final Object instance; + private final Method method; + + LineReflectionMagicFunction(Object instance, Method method) { + this.instance = instance; + this.method = method; + } + + @Override + public Object execute(List args) throws Exception { + return invoke(method, instance, args); + } + } + + private static class CellReflectionMagicFunction implements CellMagicFunction { + private final Object instance; + private final Method method; + + CellReflectionMagicFunction(Object instance, Method method) { + this.instance = instance; + this.method = method; + } + + @Override + public Object execute(List args, String body) throws Exception { + return invoke(method, instance, args, body); + } + } + + private boolean isValidBodyParam(Parameter param) { + return !param.getType().isAssignableFrom(String.class); + } + + private boolean isValidArgsParam(Parameter param) { + if (!param.getType().isAssignableFrom(List.class)) return true; + + Type parameterizedType = param.getParameterizedType(); + if (parameterizedType instanceof ParameterizedType) { + Type genericType = ((ParameterizedType) parameterizedType).getActualTypeArguments()[0]; + return !String.class.equals(genericType); + } + + return false; + } + + private void registerLineMagic(Method method, LineMagic lineMagic, LineMagicFunction func) { + registerLineMagic(lineMagic.value().isEmpty() ? method.getName() : lineMagic.value(), func); + for (String alias : lineMagic.aliases()) + registerLineMagic(alias, func); + } + + private void registerCellMagic(Method method, CellMagic cellMagic, CellMagicFunction func) { + registerCellMagic(cellMagic.value().isEmpty() ? method.getName() : cellMagic.value(), func); + for (String alias : cellMagic.aliases()) + registerCellMagic(alias, func); + } + + private void registerNoArgsReflectionMagic(Object instance, Method method, LineMagic lineMagic, CellMagic cellMagic) { + NoArgsReflectionMagicFunction func = new NoArgsReflectionMagicFunction(instance, method); + + if (lineMagic != null) + registerLineMagic(method, lineMagic, func); + + if (cellMagic != null) + registerCellMagic(method, cellMagic, func); + } + + private void registerLineCellReflectionMagic(Object instance, Method method, LineMagic lineMagic, CellMagic cellMagic) { + Parameter[] params = method.getParameters(); + if (params.length != 2 || isValidArgsParam(params[0]) || isValidBodyParam(params[1])) + throw new IllegalArgumentException("Line-cell magic must accept a List and String as parameters. (Magic arguments and possible cell body)"); + + LineCellReflectionMagicFunction func = new LineCellReflectionMagicFunction(instance, method); + registerLineMagic(method, lineMagic, func); + registerCellMagic(method, cellMagic, func); + } + + private void registerLineReflectionMagic(Object instance, Method method, LineMagic lineMagic) { + Parameter[] params = method.getParameters(); + if (params.length != 1 || isValidArgsParam(params[0])) + throw new IllegalArgumentException("Line magic must accept a List as a parameter. (Magic arguments)"); + + registerLineMagic(method, lineMagic, new LineReflectionMagicFunction(instance, method)); + } + + private void registerCellReflectionMagic(Object instance, Method method, CellMagic cellMagic) { + Parameter[] params = method.getParameters(); + if (params.length != 2 || isValidArgsParam(params[0]) || isValidBodyParam(params[1])) + throw new IllegalArgumentException("Cell magic must accept a List and String as parameters. (Magic arguments and cell body)"); + + registerCellMagic(method, cellMagic, new CellReflectionMagicFunction(instance, method)); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/MagicsArgs.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/MagicsArgs.java new file mode 100644 index 0000000..46ec35b --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/MagicsArgs.java @@ -0,0 +1,318 @@ +package io.github.spencerpark.jupyter.kernel.magic.registry; + +import java.util.*; +import java.util.regex.Matcher; +import java.util.regex.Pattern; + +public class MagicsArgs { + public enum KeywordSpec { + ONCE, + COLLECT, + REPLACE + } + + public static MagicsArgsBuilder builder() { + return new MagicsArgsBuilder(); + } + + public static class MagicsArgsBuilder { + private final List requiredPositional = new LinkedList<>(); + private final List optionalPositional = new LinkedList<>(); + private String varargs; + + private boolean acceptAnyKeyword = true; + private boolean acceptAnyFlag = true; + + private final Map> keywords = new LinkedHashMap<>(); + private final Map flags = new LinkedHashMap<>(); + private final Map flagDefaultValues = new LinkedHashMap<>(); + + public MagicsArgsBuilder required(String name) { + if (!this.optionalPositional.isEmpty() || this.varargs != null) + throw new IllegalStateException("Schema cannot have required positional arguments after optional ones."); + + this.requiredPositional.add(name); + + return this; + } + + public MagicsArgsBuilder optional(String name) { + this.optionalPositional.add(name); + + return this; + } + + public MagicsArgsBuilder varargs(String name) { + if (this.varargs != null) + throw new IllegalStateException("Schema already has varargs: " + this.varargs); + + this.varargs = name; + + return this; + } + + // --keyword value or --keyword=value + public MagicsArgsBuilder keyword(String name, KeywordSpec spec, KeywordSpec... specRest) { + this.keywords.put(name, EnumSet.of(spec, specRest)); + + return this; + } + + public MagicsArgsBuilder keyword(String name) { + return this.keyword(name, KeywordSpec.COLLECT); + } + + public MagicsArgsBuilder flag(String name, char shortName, String value) { + this.keyword(name); + this.flags.put(shortName, name); + this.flagDefaultValues.put(name, value); + + return this; + } + + public MagicsArgsBuilder flag(String name, char shortName) { + this.keyword(name); + this.flags.put(shortName, name); + + return this; + } + + public MagicsArgsBuilder anyKeyword() { + this.acceptAnyKeyword = true; + + return this; + } + + public MagicsArgsBuilder onlyKnownKeywords() { + this.acceptAnyKeyword = false; + + return this; + } + + public MagicsArgsBuilder anyFlag() { + this.acceptAnyFlag = true; + + return this; + } + + public MagicsArgsBuilder onlyKnownFlags() { + this.acceptAnyFlag = false; + + return this; + } + + private KeywordAggregator buildKeyword(Set spec) { + if (spec.contains(KeywordSpec.ONCE)) { + return (name, value, rest, args) -> { + if (args.containsKey(name) && !args.get(name).isEmpty()) + throw new MagicArgsParseException("'%s' may only be specified once.", name); + + if (value != null) { + args.put(name, Collections.singletonList(value)); + + return rest; + } else { + if (rest.isEmpty()) + throw new MagicArgsParseException("'%s' is a keyword argument but no value was supplied.", name); + + args.put(name, Collections.singletonList(rest.get(0))); + + return rest.subList(1, rest.size()); + } + }; + } else if (spec.contains(KeywordSpec.REPLACE)) { + return (name, value, rest, args) -> { + if (value != null) { + args.put(name, Collections.singletonList(value)); + + return rest; + } else { + if (rest.isEmpty()) + throw new MagicArgsParseException("'%s' is a keyword argument but no value was supplied.", name); + + args.put(name, Collections.singletonList(rest.get(0))); + + return rest.subList(1, rest.size()); + } + }; + } else /*default: if (spec.contains(KeywordSpec.COLLECT))*/ { + return (name, value, rest, args) -> { + args.compute(name, (k, values) -> { + if (values == null) + values = new LinkedList<>(); + + if (value != null) { + values.add(value); + } else { + if (rest.isEmpty()) + throw new MagicArgsParseException("'%s' is a keyword argument but no value was supplied.", name); + + values.add(rest.get(0)); + } + + return values; + }); + + return value != null ? rest : rest.subList(1, rest.size()); + }; + } + } + + public MagicsArgs build() { + Map kw = new HashMap<>(this.keywords.size()); + this.keywords.forEach((name, spec) -> + kw.put(name, this.buildKeyword(spec))); + + return new MagicsArgs( + new ArrayList<>(this.requiredPositional), + new ArrayList<>(this.optionalPositional), + this.varargs, + kw, + this.flags, + this.flagDefaultValues, + this.acceptAnyKeyword ? this.buildKeyword(EnumSet.noneOf(KeywordSpec.class)) : null, + this.acceptAnyFlag ? this.buildKeyword(EnumSet.noneOf(KeywordSpec.class)) : null + ); + } + } + + @FunctionalInterface + private static interface KeywordAggregator { + /** + * Consume the argument. + * + * @param name the name of the argument + * @param value the value attached to the keyword or null + * @param rest the remaining arguments + * @param args the collection to append to + * + * @return the new {@code rest} + */ + public List consume(String name, String value, List rest, Map> args) throws MagicArgsParseException; + } + + private static final Pattern KEYWORD_ARG_PATTERN = Pattern.compile("^--(?[^=]+)(?:=(?.+))?$"); + private static final Pattern FLAG_ARG_PATTERN = Pattern.compile("^-(?[a-zA-Z]+)$"); + + private final List positional; + private final List optional; + private final String varargs; + + private final Map keywords; + private final Map keywordFromFlag; + private final Map flagSuppliedDefaults; + + private final KeywordAggregator defaultKeywordAggregator; + private final KeywordAggregator defaultFlagAggregator; + + public MagicsArgs(List positional, List optional, String varargs, Map keywords, Map keywordFromFlag, Map flagSuppliedDefaults, KeywordAggregator defaultKeywordAggregator, KeywordAggregator defaultFlagAggregator) { + this.positional = positional; + this.optional = optional; + this.varargs = varargs; + this.keywords = keywords; + this.keywordFromFlag = keywordFromFlag; + this.flagSuppliedDefaults = flagSuppliedDefaults; + this.defaultKeywordAggregator = defaultKeywordAggregator; + this.defaultFlagAggregator = defaultFlagAggregator; + } + + public Map> parse(List args) throws MagicArgsParseException { + Map> collectedArgs = new LinkedHashMap<>(); + this.positional.forEach(a -> collectedArgs.put(a, new LinkedList<>())); + this.optional.forEach(a -> collectedArgs.put(a, new LinkedList<>())); + if (this.varargs != null) + collectedArgs.put(this.varargs, new LinkedList<>()); + this.keywords.keySet().forEach(a -> collectedArgs.put(a, new LinkedList<>())); + + int positionalsMatched = 0; + + while (!args.isEmpty()) { + String arg = args.get(0); + args = args.subList(1, args.size()); + + Matcher m = KEYWORD_ARG_PATTERN.matcher(arg); + if (m.matches()) { + String name = m.group("name"); + String value = m.group("val"); + + KeywordAggregator aggregator = this.keywords.getOrDefault(name, this.defaultKeywordAggregator); + + if (aggregator == null) + throw new MagicArgsParseException("Unknown keyword argument '%s'.", name); + + args = aggregator.consume(name, value, args, collectedArgs); + + continue; + } + + m = FLAG_ARG_PATTERN.matcher(arg); + if (m.matches()) { + String flags = m.group("flags"); + for (int i = 0; i < flags.length(); i++) { + char c = flags.charAt(i); + + String name = this.keywordFromFlag.getOrDefault(c, Character.toString(c)); + + KeywordAggregator aggregator = this.keywords.getOrDefault(name, this.defaultFlagAggregator); + + if (aggregator == null) + throw new MagicArgsParseException("Unknown flag argument '%s'.", name); + + args = aggregator.consume(name, this.flagSuppliedDefaults.getOrDefault(name, ""), args, collectedArgs); + } + + continue; + } + + if (positionalsMatched < this.positional.size()) + collectedArgs.compute(this.positional.get(positionalsMatched), (n, values) -> { + values = values != null ? values : new LinkedList<>(); + values.add(arg); + return values; + }); + else if (positionalsMatched < this.positional.size() + this.optional.size()) + collectedArgs.compute(this.optional.get(positionalsMatched - this.positional.size()), (n, values) -> { + values = values != null ? values : new LinkedList<>(); + values.add(arg); + return values; + }); + else if (this.varargs != null) + collectedArgs.compute(this.varargs, (n, values) -> { + values = values != null ? values : new LinkedList<>(); + values.add(arg); + return values; + }); + else + throw new MagicArgsParseException("Too many positional arguments."); + + positionalsMatched += 1; + } + + if (positionalsMatched < this.positional.size()) + throw new MagicArgsParseException("Missing required positional arguments: %s", this.positional.subList(positionalsMatched, this.positional.size())); + + return collectedArgs; + } + + @Override + public String toString() { + StringJoiner s = new StringJoiner(" "); + + this.positional.forEach(s::add); + this.optional.forEach(a -> s.add("[" + a + "]")); + if (this.varargs != null) + s.add(this.varargs + "..."); + + this.keywordFromFlag.keySet().forEach(c -> s.add("-" + c)); + if (this.defaultFlagAggregator != null) + s.add("-*"); + + this.keywords.keySet().stream() + .filter(a -> !this.keywordFromFlag.values().contains(a)) + .forEach(a -> s.add("--" + a)); + if (this.defaultKeywordAggregator != null) + s.add("--**"); + + return s.toString(); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/UndefinedMagicException.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/UndefinedMagicException.java new file mode 100644 index 0000000..3baf52a --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/magic/registry/UndefinedMagicException.java @@ -0,0 +1,24 @@ +package io.github.spencerpark.jupyter.kernel.magic.registry; + +public class UndefinedMagicException extends RuntimeException { + private final String name; + private final boolean line; + + public UndefinedMagicException(String name, boolean line) { + super("Undefined " + (line ? "line" : "cell") + " magic '" + name + "'"); + this.name = name; + this.line = line; + } + + public String getMagicName() { + return name; + } + + public boolean isLineMagic() { + return line; + } + + public boolean isCellMagic() { + return !line; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/CharPredicate.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/CharPredicate.java new file mode 100644 index 0000000..7665513 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/CharPredicate.java @@ -0,0 +1,157 @@ +package io.github.spencerpark.jupyter.kernel.util; + +import java.util.*; + +@FunctionalInterface +public interface CharPredicate { + + public boolean test(char c); + + public default CharPredicate and(CharPredicate condition) { + return c -> this.test(c) && condition.test(c); + } + + public default CharPredicate or(CharPredicate condition) { + return c -> this.test(c) || condition.test(c); + } + + public default CharPredicate not() { + return new NotCharPredicate(this); + } + + public static class NotCharPredicate implements CharPredicate { + private final CharPredicate test; + + public NotCharPredicate(CharPredicate test) { + this.test = test; + } + + @Override + public boolean test(char c) { + return !this.test.test(c); + } + + @Override + public CharPredicate not() { + return this.test; + } + } + + /** + * Match characters that fall between the given character bounds (inclusive). + * + * @param low the lower bound of the range (inclusive) + * @param high the upper bound of the range (inclusive) + * + * @return a predicate that returns true when testing a character in this range + * and false otherwise. + */ + public static CharPredicate inRange(char low, char high) { + return c -> low <= c && c <= high; + } + + /** + * Match a character that is the same as the {@code match} character. + * + * @param match the character to match with + * + * @return a predicate that returns true when testing a character that is + * the same as the {@code match} character and false otherwise. + */ + public static CharPredicate match(char match) { + return c -> c == match; + } + + /** + * Match any character in the {@code chars} string. + * + * @param chars a set of chars to match + * + * @return a predicate that returns true when testing a character that is + * the same as any character in the {@code chars} and false otherwise. + */ + public static CharPredicate anyOf(String chars) { + int[] cs = chars.chars().sorted().distinct().toArray(); + return c -> { + for (int cmpTo : cs) { + if (cmpTo == c) return true; + if (c < cmpTo) return false; + } + return false; + }; + } + + public static class CharRange { + public final char low; + public final char high; + + public CharRange(char low, char high) { + this.low = low; + this.high = high; + } + } + + public static Builder builder() { + return new Builder(); + } + + public static class Builder { + private final List segments; + + public Builder() { + this.segments = new LinkedList<>(); + } + + public Builder inRange(char low, char high) { + if (high < low) + throw new IllegalArgumentException("Low char must be strictly less than high (low: " + low + ", high: " + high + ")"); + + this.segments.add(new CharRange(low, high)); + return this; + } + + public Builder match(char c) { + this.segments.add(new CharRange(c, c)); + return this; + } + + public Builder match(String chars) { + chars.chars().forEach(c -> this.segments.add(new CharRange((char) c, (char) c))); + return this; + } + + public CharPredicate build() { + List ranges = new ArrayList<>(this.segments.size()); + + if (!this.segments.isEmpty()) { + this.segments.sort((range1, range2) -> + range1.low != range2.low + ? range1.low - range2.low + : range1.high - range2.high); + + Iterator itr = this.segments.iterator(); + CharRange prev = itr.next(); + while (itr.hasNext()) { + CharRange next = itr.next(); + if (prev.high < next.low) { + ranges.add(prev); + prev = next; + } else { + prev = new CharRange(prev.low, (char) Math.max(prev.high, next.high)); + } + } + ranges.add(prev); + } + + CharRange[] test = ranges.toArray(new CharRange[ranges.size()]); + + return c -> { + for (CharRange range : test) { + if (c < range.low) return false; + if (c <= range.high) return true; + } + return false; + }; + } + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/GlobFinder.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/GlobFinder.java new file mode 100644 index 0000000..0cb0f2f --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/GlobFinder.java @@ -0,0 +1,230 @@ +package io.github.spencerpark.jupyter.kernel.util; + +import java.io.IOException; +import java.nio.file.*; +import java.nio.file.attribute.BasicFileAttributes; +import java.util.*; +import java.util.regex.Matcher; +import java.util.regex.Pattern; + +/** + * A simplified glob implementation designed for finding files. The current implementation supports + * {@code "*"} to match 0 or more characters between {@code "/"} and {@code "?"} to + * match a single character. A glob ending in {@code "/"} will match all files in a directories matching + * the glob. + *

+ * Important note for Windows file systems: Globs should use {@code "/"} to separate the + * glob despite it not being the platform separator. + */ +public class GlobFinder { + private static class GlobSegment { + public enum FilterRestriction { + ONLY_FILES(true, false), + ONLY_DIRECTORIES(false, true), + ANYTHING(true, true); + + private final boolean acceptsFiles; + private final boolean acceptsDirectories; + + FilterRestriction(boolean acceptsFiles, boolean acceptsDirectories) { + this.acceptsFiles = acceptsFiles; + this.acceptsDirectories = acceptsDirectories; + } + + public boolean acceptsFiles() { + return acceptsFiles; + } + + public boolean acceptsDirectories() { + return acceptsDirectories; + } + } + + public static final GlobSegment ANY = new GlobSegment(Pattern.compile("^.*$")); + + private final String literal; + private final Pattern regex; + + public GlobSegment(String literal) { + this.literal = literal; + this.regex = null; + } + + public GlobSegment(Pattern regex) { + this.literal = null; + this.regex = regex; + } + + public boolean isLiteral() { + return this.literal != null; + } + + public DirectoryStream.Filter filter(FilterRestriction restriction) { + return s -> { + BasicFileAttributes attributes = Files.readAttributes(s, BasicFileAttributes.class); + + if ((attributes.isRegularFile() && !restriction.acceptsFiles()) || (attributes.isDirectory() && !restriction.acceptsDirectories())) + return false; + + Path pathName = s.getFileName(); + + if (pathName == null) + return false; + + String name = pathName.toString(); + return this.literal != null + ? this.literal.equals(name) + : this.regex.matcher(name).matches(); + }; + } + + @Override + public String toString() { + return this.isLiteral() ? this.literal : this.regex.pattern(); + } + } + + private static final Pattern GLOB_SEGMENT_COMPONENT = Pattern.compile( + "" + + "(?[^*?]+)" + + "|(?\\*)" + + "|(?\\?)" + + "|(?:\\\\(?[*?]))" + ); + + private static final Pattern SPLITTER = Pattern.compile("/+"); + + private final Path base; + private final List segments; + private final boolean isExplicitDirectory; + + public GlobFinder(FileSystem fs, String glob) { + // Split with "/" but match with the actual separator + String[] segments = SPLITTER.split(glob); + this.isExplicitDirectory = glob.endsWith("/"); + + List matchers = new ArrayList<>(segments.length); + int lastBaseSegmentIdx = 0; + + for (int i = 0; i < segments.length; i++) { + String segment = segments[i]; + + StringBuilder pattern = new StringBuilder(); + StringBuilder lit = new StringBuilder(); + int wildcards = 0; + int singleWildcards = 0; + + Matcher m = GLOB_SEGMENT_COMPONENT.matcher(segment); + while (m.find()) { + String literal = m.group("literal"); + if (literal == null) literal = m.group("escaped"); + if (literal != null) { + pattern.append(Pattern.quote(literal)); + lit.append(literal); + continue; + } + + String wildcard = m.group("wildcard"); + if (wildcard != null) { + pattern.append(".*"); + wildcards++; + continue; + } + + String singleWildcard = m.group("singleWildcard"); + // There are only 4 groups, 3 of which have been checked and are null so this + // on must be non-null. + assert singleWildcard != null : "Glob construction pattern incomplete."; + pattern.append("."); + singleWildcards++; + } + + assert m.hitEnd() : "Glob construction missed some characters."; + + if (wildcards == 0 && singleWildcards == 0) { + matchers.add(new GlobSegment(lit.toString())); + if (lastBaseSegmentIdx == i) lastBaseSegmentIdx++; + } else { + matchers.add(new GlobSegment(Pattern.compile("^" + pattern.toString() + "$"))); + } + } + + // Cannot use the very nice `new File(glob).isAbsolute()` solution as this is restricted to the default file + // system and doesn't use the `fs`. Additionally `Paths.get(glob).isAbsolute()` will fail with an illegal path + // exception when trying to parse a windows path with a * in it for example. Therefor we need a clean segment. + boolean isAbsolute = lastBaseSegmentIdx > 0 && fs.getPath(segments[0] + fs.getSeparator()).isAbsolute(); + String firstSeg = isAbsolute ? segments[0] + fs.getSeparator() : "." + fs.getSeparator(); + + this.base = fs.getPath(firstSeg, Arrays.copyOfRange(segments, isAbsolute ? 1 : 0, lastBaseSegmentIdx)); + this.segments = matchers.subList(lastBaseSegmentIdx, matchers.size()); + } + + public GlobFinder(String glob) { + this(FileSystems.getDefault(), glob); + } + + public Iterable computeMatchingPaths() throws IOException { + if (this.segments.isEmpty()) { + if (Files.exists(this.base)) + return Collections.singletonList(this.base); + else + return Collections.emptyList(); + } + + List paths = new ArrayList<>(); + GlobSegment head = this.segments.get(0); + List tail = this.segments.subList(1, this.segments.size()); + + collectExplicit(GlobSegment.FilterRestriction.ANYTHING, this.base, head, tail, paths); + + return paths; + } + + private void collectExplicit(GlobSegment.FilterRestriction finalFilterRestriction, Path dir, GlobSegment segment, List segments, Collection into) throws IOException { + boolean isMoreSegments = !segments.isEmpty(); + // Should match files if there are more segments in which case this must be a directory so + // we can continue. Otherwise we let the search determine if a file is acceptable. + GlobSegment.FilterRestriction filterRestriction = isMoreSegments ? GlobSegment.FilterRestriction.ONLY_DIRECTORIES : finalFilterRestriction; + + try (DirectoryStream files = Files.newDirectoryStream(dir, segment.filter(filterRestriction))) { + GlobSegment head = isMoreSegments ? segments.get(0) : null; + List tail = isMoreSegments ? segments.subList(1, segments.size()) : Collections.emptyList(); + + for (Path p : files) { + if (isMoreSegments) + collectExplicit(finalFilterRestriction, p, head, tail, into); + else + into.add(p); + } + } + } + + public Iterable computeMatchingFiles() throws IOException { + if (this.segments.isEmpty()) { + if (Files.isDirectory(this.base) && this.isExplicitDirectory) + return Files.newDirectoryStream(this.base, Files::isRegularFile); + if (Files.isRegularFile(this.base)) + return Collections.singleton(this.base); + return Collections.emptyList(); + } + + List paths = new ArrayList<>(); + GlobSegment head = this.segments.get(0); + List tail; + + // If explicitly ends with a "/" then the pattern means match all files in this directory + // otherwise we assume the last pattern is a file matcher. + if (this.isExplicitDirectory) { + tail = new ArrayList<>(this.segments.size() + 1); + Collections.copy(tail, this.segments.subList(1, this.segments.size())); + tail.add(GlobSegment.ANY); + } else { + tail = this.segments.subList(1, this.segments.size()); + } + + collectExplicit(GlobSegment.FilterRestriction.ONLY_FILES, this.base, head, tail, paths); + + return paths; + } +} + diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/InheritanceIterator.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/InheritanceIterator.java new file mode 100644 index 0000000..61b1996 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/InheritanceIterator.java @@ -0,0 +1,84 @@ +package io.github.spencerpark.jupyter.kernel.util; + +import java.util.*; + +/** + * Iterate over the types that an object is an {@code instanceof}. {@link Class}es in + * the iteration will not be duplicated (once a class is seen it will not be seen again + * even if, for example, an interface is declared to be implemented by 2 classes). + *

+ * Example: + * 

+ * {@code interface I {}
+ *   interface J extends I {}
+ *   interface K extends J, I {} // Redundant but allowed
+ *   interface L extends J, K {}
+ *
+ *   class D {}
+ *   class E extends D implements L {}
+ *   class F extends E implements J, K {}
+ * }
+ *
+ * Iterating over {@code new InheritanceIterator(F.class)} will yield: + * {@code F.class, J.class, K.class, I.class, E.class, L.class, D.class, Object.class} + */ +public class InheritanceIterator implements Iterator { + private final Set observedInterfaces; + + private Class concrete; + private Iterator implementedInterfaces; + + public InheritanceIterator(Class root) { + this.concrete = root; + this.observedInterfaces = new LinkedHashSet<>(); + } + + /** + * Construct an iterator that walks the implemented interfaces by the current {@link #concrete} + * class. The should skip all {@link #observedInterfaces}. + * + * @return and iterator over the implemented interfaces. + */ + private Iterator initializeImplementedInterfaces() { + List implemented = new LinkedList<>(); + getAllInterfaces(implemented, this.concrete.getInterfaces()); + return implemented.iterator(); + } + + private void getAllInterfaces(List allInterfaces, Class[] declaredImplementations) { + for (Class implementedInterface : declaredImplementations) { + if (this.observedInterfaces.add(implementedInterface)) + allInterfaces.add(implementedInterface); + } + + for (Class implementedInterface : declaredImplementations) + getAllInterfaces(allInterfaces, implementedInterface.getInterfaces()); + } + + @Override + public boolean hasNext() { + return this.implementedInterfaces == null + || this.implementedInterfaces.hasNext() + || this.concrete.getSuperclass() != null; + } + + @Override + public Class next() { + if (this.implementedInterfaces == null) { + this.implementedInterfaces = this.initializeImplementedInterfaces(); + return this.concrete; + } + + if (this.implementedInterfaces.hasNext()) + return this.implementedInterfaces.next(); + + Class superClass = this.concrete.getSuperclass(); + if (superClass != null) { + this.concrete = superClass; + this.implementedInterfaces = this.initializeImplementedInterfaces(); + return superClass; + } + + throw new NoSuchElementException(); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/SimpleAutoCompleter.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/SimpleAutoCompleter.java new file mode 100644 index 0000000..ecefde0 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/SimpleAutoCompleter.java @@ -0,0 +1,104 @@ +package io.github.spencerpark.jupyter.kernel.util; + +import java.util.*; + +/** + * A utility class to implement a prefix based auto completion algorithm. It + * is a good basic implementation for completing keywords or identifiers that + * have already been parsed or are in the current cell. + */ +public class SimpleAutoCompleter { + + public static Builder builder() { + return new Builder(); + } + + public static class Builder { + private Collection keywords; + private boolean caseSensitive = true; + private Comparator resultsSorter = null; + + private Builder() { + this.keywords = new ArrayList<>(); + } + + public Builder withKeywords(String... keywords) { + Collections.addAll(this.keywords, keywords); + return this; + } + + public Builder withKeywords(Collection keywords) { + this.keywords.addAll(keywords); + return this; + } + + public Builder caseSensitive() { + this.caseSensitive = true; + return this; + } + + public Builder caseInsensitive() { + this.caseSensitive = false; + return this; + } + + private void addSorter(Comparator comparator) { + this.resultsSorter = this.resultsSorter == null ? comparator : this.resultsSorter.thenComparing(comparator); + } + + public Builder preferShort() { + addSorter(SHORTER_BETTER); + return this; + } + + public Builder preferLong() { + addSorter(LONGER_BETTER); + return this; + } + + public Builder preferSmallerChars() { + addSorter(this.caseSensitive ? LOWER_ALPHA_BETTER_CASE : LOWER_ALPHA_BETTER_NO_CASE); + return this; + } + + public Builder preferLargerChars() { + addSorter(this.caseSensitive ? HIGHER_ALPHA_BETTER_CASE : HIGHER_ALPHA_BETTER_NO_CASE); + return this; + } + + public SimpleAutoCompleter build() { + return new SimpleAutoCompleter( + this.keywords, + this.caseSensitive, + this.resultsSorter + ); + } + } + + private static final Comparator SHORTER_BETTER = Comparator.comparingInt(String::length); + private static final Comparator LONGER_BETTER = SHORTER_BETTER.reversed(); + + private static final Comparator LOWER_ALPHA_BETTER_CASE = String::compareTo; + private static final Comparator HIGHER_ALPHA_BETTER_CASE = LOWER_ALPHA_BETTER_CASE.reversed(); + + private static final Comparator LOWER_ALPHA_BETTER_NO_CASE = String::compareToIgnoreCase; + private static final Comparator HIGHER_ALPHA_BETTER_NO_CASE = LOWER_ALPHA_BETTER_NO_CASE.reversed(); + + protected final SortedSet keywords; + protected final Comparator resultsSorter; + + public SimpleAutoCompleter(Collection keywords, boolean caseSensitive, Comparator resultsSorter) { + this.keywords = new TreeSet<>(caseSensitive ? String::compareTo : String::compareToIgnoreCase); + this.keywords.addAll(keywords); + this.resultsSorter = resultsSorter; + } + + public List autocomplete(String prefix) { + SortedSet results = keywords.subSet(prefix, prefix + Character.MAX_VALUE); + List sortedResults = new ArrayList<>(results.size()); + sortedResults.addAll(results); + if (this.resultsSorter != null && sortedResults.size() > 1) + sortedResults.sort(this.resultsSorter); + return sortedResults; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/StringSearch.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/StringSearch.java new file mode 100644 index 0000000..cb8c3e5 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/StringSearch.java @@ -0,0 +1,66 @@ +package io.github.spencerpark.jupyter.kernel.util; + +public class StringSearch { + public static class Range { + private final int low; + private final int high; + + public Range(int low, int high) { + this.low = low; + this.high = high; + } + + public int getLow() { + return low; + } + + public int getHigh() { + return high; + } + + public int getLength() { + return high - low; + } + + public String extractSubString(String original) { + return original.substring(low, high); + } + } + + /** + * Find the longest substring such that all characters in the substring match the + * {@code test}. + * + * @param code the code to preform the search in. + * @param at the position to start the search at. The returned range will contain this + * position. It is usually the position of a cursor. + * @param test a predicate that must evaluate to true if a character should be included in + * the match. + * + * @return a range specifying the bounds of the longest match containing the {@code at} + * position. If nothing matches then this returns {@code null}. + */ + public static Range findLongestMatchingAt(String code, int at, CharPredicate test) { + if (test == null || at < 0 || at > code.length()) + return null; + + int start, end; + if (at < code.length() && test.test(code.charAt(at))) { + //The code[at] is a valid char and so worst case start = end is the entire string + start = end = at; + } else if (at > 0 && test.test(code.charAt(at - 1))) { + //The code[at] isn't valid but the previous one is a good starting point + //which may happen if "at" is immediately following a word + start = end = at - 1; + } else { + return null; + } + + while (start > 0 && test.test(code.charAt(start - 1))) + start--; + while (end < code.length() - 1 && test.test(code.charAt(end + 1))) + end++; + + return new Range(start, end + 1); + } +} diff --git a/src/main/java/io/github/spencerpark/jupyter/kernel/util/StringStyler.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/StringStyler.java similarity index 100% rename from src/main/java/io/github/spencerpark/jupyter/kernel/util/StringStyler.java rename to basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/StringStyler.java diff --git a/src/main/java/io/github/spencerpark/jupyter/kernel/util/TextColor.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/TextColor.java similarity index 100% rename from src/main/java/io/github/spencerpark/jupyter/kernel/util/TextColor.java rename to basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/util/TextColor.java diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/ContentType.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/ContentType.java new file mode 100644 index 0000000..4ab280d --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/ContentType.java @@ -0,0 +1,5 @@ +package io.github.spencerpark.jupyter.messages; + +public interface ContentType { + public MessageType getType(); +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/HMACGenerator.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/HMACGenerator.java new file mode 100644 index 0000000..213850a --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/HMACGenerator.java @@ -0,0 +1,49 @@ +package io.github.spencerpark.jupyter.messages; + +import io.github.spencerpark.jupyter.channels.JupyterSocket; + +import javax.crypto.Mac; +import javax.crypto.spec.SecretKeySpec; +import java.security.InvalidKeyException; +import java.security.NoSuchAlgorithmException; + +public class HMACGenerator { + private static final int MASK_INT_TO_BYTE = 0xFF; + private static final int MASK_BYTE_LOWER = 0x0F; + + public static final HMACGenerator NO_AUTH_INSTANCE = new HMACGenerator() { + @Override + public String calculateSignature(byte[]... messageParts) { + return ""; + } + }; + + private final Mac mac; + + public HMACGenerator(String algorithm, String key) throws NoSuchAlgorithmException, InvalidKeyException { + this.mac = Mac.getInstance(algorithm.replace("-", "")); + this.mac.init(new SecretKeySpec(key.getBytes(JupyterSocket.ASCII), algorithm)); + } + + private HMACGenerator() { + this.mac = null; + } + + private final static char[] HEX_CHAR = "0123456789abcdef".toCharArray(); + + public synchronized String calculateSignature(byte[]... messageParts) { + for (byte[] part : messageParts) + this.mac.update(part); + + byte[] sig = this.mac.doFinal(); + + char[] hex = new char[sig.length * 2]; + for (int j = 0; j < sig.length; j++) { + int b = sig[j] & MASK_INT_TO_BYTE; + hex[j * 2] = HEX_CHAR[b >>> 4]; + hex[j * 2 + 1] = HEX_CHAR[b & MASK_BYTE_LOWER]; + } + + return new String(hex); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/Header.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/Header.java new file mode 100644 index 0000000..58020fd --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/Header.java @@ -0,0 +1,83 @@ +package io.github.spencerpark.jupyter.messages; + +import com.google.gson.annotations.SerializedName; + +import java.util.UUID; + +public class Header { + public static final String KERNEL_USERNAME = "kernel"; + public static final String PROTOCOL_VERISON = "5.3"; + + private final String id; + private final String username; + + @SerializedName("session") + private final String sessionId; + + @SerializedName("date") + private final KernelTimestamp timestamp; + + @SerializedName("msg_type") + private final MessageType type; + + private final String version; + + public Header(MessageType type) { + this("", type); + } + + public Header(String sessionId, MessageType type) { + this( + UUID.randomUUID().toString(), + KERNEL_USERNAME, + sessionId, + KernelTimestamp.now(), + type, + PROTOCOL_VERISON + ); + } + + public Header(MessageContext ctx, MessageType type) { + this( + UUID.randomUUID().toString(), + ctx != null ? ctx.getHeader().getUsername() : KERNEL_USERNAME, + ctx != null ? ctx.getHeader().getSessionId() : null, + KernelTimestamp.now(), + type, + PROTOCOL_VERISON + ); + } + + public Header(String id, String username, String sessionId, KernelTimestamp timestamp, MessageType type, String version) { + this.id = id; + this.username = username; + this.sessionId = sessionId; + this.timestamp = timestamp; + this.type = type; + this.version = version; + } + + public String getId() { + return id; + } + + public String getUsername() { + return username; + } + + public String getSessionId() { + return sessionId; + } + + public KernelTimestamp getTimestamp() { + return timestamp; + } + + public MessageType getType() { + return type; + } + + public String getVersion() { + return version; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/KernelTimestamp.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/KernelTimestamp.java new file mode 100644 index 0000000..1fb03ec --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/KernelTimestamp.java @@ -0,0 +1,45 @@ +package io.github.spencerpark.jupyter.messages; + +import java.text.DateFormat; +import java.text.ParseException; +import java.text.SimpleDateFormat; +import java.util.Date; +import java.util.TimeZone; + +/** + * A lazy date parser + */ +public class KernelTimestamp { + public static KernelTimestamp now() { + return new KernelTimestamp(new Date()); + } + + private static final ThreadLocal DATE_FORMAT = ThreadLocal.withInitial(() -> { + DateFormat format = new SimpleDateFormat("yyyy-MM-dd'T'HH:mmZ"); + format.setTimeZone(TimeZone.getTimeZone("UTC")); + return format; + }); + + private String serialized; + private Date date; + + public KernelTimestamp(String serialized) { + this.serialized = serialized; + } + + public KernelTimestamp(Date date) { + this.date = date; + } + + public Date getDate() { + try { + return date != null ? date : (date = DATE_FORMAT.get().parse(serialized)); + } catch (ParseException e) { + throw new RuntimeException("Invalid date string '" + serialized + "'", e); + } + } + + public String getDateString() { + return serialized != null ? serialized : (serialized = DATE_FORMAT.get().format(date)); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/Message.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/Message.java new file mode 100644 index 0000000..f912d04 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/Message.java @@ -0,0 +1,119 @@ +package io.github.spencerpark.jupyter.messages; + +import java.util.*; + +public class Message implements MessageContext { + private List identities; + + private Header header; + + /** + * Optional, in a chain of messages this is copied from + * the parent so the client can better track where the messages + * come from. + */ + private Header parentHeader; + + private Map metadata; + + private T content; + + private List blobs; + + public Message(MessageContext ctx, MessageType type, T content) { + this(ctx, type, content, null, null); + } + + public Message(MessageContext ctx, MessageType type, T content, List blobs, Map metadata) { + this( + ctx != null ? ctx.getIdentities() : Collections.emptyList(), + new Header<>(ctx, type), + ctx != null ? ctx.getHeader() : null, + metadata, + content, + blobs + ); + } + + public Message(Header header, T content) { + this(Collections.emptyList(), header, null, null, content, null); + } + + public Message(Header header, T content, Map metadata, List blobs) { + this(Collections.emptyList(), header, null, metadata, content, blobs); + } + + public Message(List identities, Header header, T content) { + this(identities, header, null, null, content, null); + } + + public Message(List identities, Header header, Header parentHeader, Map metadata, T content, List blobs) { + this.identities = identities; + this.header = header; + this.parentHeader = parentHeader; + this.metadata = metadata; + this.content = content; + this.blobs = blobs; + } + + @Override + public List getIdentities() { + return identities; + } + + @Override + public Header getHeader() { + return header; + } + + public boolean hasParentHeader() { + return parentHeader != null; + } + + public Header getParentHeader() { + return parentHeader; + } + + public boolean hasMetadata() { + return metadata != null; + } + + public Map getMetadata() { + return metadata; + } + + public Map getNonNullMetadata() { + if (this.hasMetadata()) + return this.getMetadata(); + this.metadata = new LinkedHashMap<>(); + return this.metadata; + } + + public T getContent() { + return content; + } + + public List getBlobs() { + return blobs; + } + + @Override + public String toString() { + StringBuilder sb = new StringBuilder("Message {\n"); + sb.append("\tidentities = [\n"); + for (byte[] id : identities) + sb.append("\t\t").append(Arrays.toString(id)).append("\n"); + sb.append("\t]\n"); + sb.append("\theader = ").append(header).append("\n"); + sb.append("\tparentHeader = ").append(parentHeader).append("\n"); + sb.append("\tmetadata = ").append(metadata).append("\n"); + sb.append("\tcontent = ").append(content).append("\n"); + sb.append("\tblobs = [\n"); + if (blobs != null) + for (byte[] blob : blobs) + sb.append("\t\t").append(Arrays.toString(blob)).append("\n"); + sb.append("\t]\n"); + sb.append("}\n"); + return sb.toString(); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/MessageContext.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/MessageContext.java new file mode 100644 index 0000000..314980d --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/MessageContext.java @@ -0,0 +1,9 @@ +package io.github.spencerpark.jupyter.messages; + +import java.util.List; + +public interface MessageContext { + public List getIdentities(); + + public Header getHeader(); +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/MessageType.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/MessageType.java new file mode 100644 index 0000000..61e0713 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/MessageType.java @@ -0,0 +1,123 @@ +package io.github.spencerpark.jupyter.messages; + +import io.github.spencerpark.jupyter.messages.comm.CommCloseCommand; +import io.github.spencerpark.jupyter.messages.comm.CommMsgCommand; +import io.github.spencerpark.jupyter.messages.comm.CommOpenCommand; +import io.github.spencerpark.jupyter.messages.publish.*; +import io.github.spencerpark.jupyter.messages.reply.*; +import io.github.spencerpark.jupyter.messages.request.*; + +import java.util.HashMap; +import java.util.Map; +import java.util.concurrent.atomic.AtomicInteger; + +public class MessageType { + private static final AtomicInteger NEXT_ID = new AtomicInteger(0); + + private static final Map> TYPE_BY_NAME = new HashMap<>(); + + public static MessageType getType(String name) { + MessageType type = TYPE_BY_NAME.get(name); + return type == null ? UNKNOWN : type; + } + + //Request + public static final MessageType EXECUTE_REQUEST = new MessageType<>("execute_request", ExecuteRequest.class); + public static final MessageType INSPECT_REQUEST = new MessageType<>("inspect_request", InspectRequest.class); + public static final MessageType COMPLETE_REQUEST = new MessageType<>("complete_request", CompleteRequest.class); + public static final MessageType HISTORY_REQUEST = new MessageType<>("history_request", HistoryRequest.class); + public static final MessageType IS_COMPLETE_REQUEST = new MessageType<>("is_complete_request", IsCompleteRequest.class); + public static final MessageType COMM_INFO_REQUEST = new MessageType<>("comm_info_request", CommInfoRequest.class); + public static final MessageType KERNEL_INFO_REQUEST = new MessageType<>("kernel_info_request", KernelInfoRequest.class); + public static final MessageType SHUTDOWN_REQUEST = new MessageType<>("shutdown_request", ShutdownRequest.class); + public static final MessageType INTERRUPT_REQUEST = new MessageType<>("interrupt_request", InterruptRequest.class); + + //Reply + public static final MessageType EXECUTE_REPLY = new MessageType<>("execute_reply", ExecuteReply.class); + public static final MessageType INSPECT_REPLY = new MessageType<>("inspect_reply", InspectReply.class); + public static final MessageType COMPLETE_REPLY = new MessageType<>("complete_reply", CompleteReply.class); + public static final MessageType HISTORY_REPLY = new MessageType<>("history_reply", HistoryReply.class); + public static final MessageType IS_COMPLETE_REPLY = new MessageType<>("is_complete_reply", IsCompleteReply.class); + public static final MessageType COMM_INFO_REPLY = new MessageType<>("comm_info_reply", CommInfoReply.class); + public static final MessageType KERNEL_INFO_REPLY = new MessageType<>("kernel_info_reply", KernelInfoReply.class); + public static final MessageType SHUTDOWN_REPLY = new MessageType<>("shutdown_reply", ShutdownReply.class); + public static final MessageType INTERRUPT_REPLY = new MessageType<>("interrupt_reply", InterruptReply.class); + + //Publish + public static final MessageType PUBLISH_STREAM = new MessageType<>("stream", PublishStream.class); + public static final MessageType PUBLISH_DISPLAY_DATA = new MessageType<>("display_data", PublishDisplayData.class); + public static final MessageType PUBLISH_UPDATE_DISPLAY_DATA = new MessageType<>("update_display_data", PublishUpdateDisplayData.class); + public static final MessageType PUBLISH_EXECUTE_INPUT = new MessageType<>("execute_input", PublishExecuteInput.class); + public static final MessageType PUBLISH_EXECUTION_RESULT = new MessageType<>("execute_result", PublishExecuteResult.class); + public static final MessageType PUBLISH_ERROR = new MessageType<>("error", PublishError.class); + public static final MessageType PUBLISH_STATUS = new MessageType<>("status", PublishStatus.class); + public static final MessageType PUBLISH_CLEAR_OUTPUT = new MessageType<>("clear_output", PublishClearOutput.class); + + //Stdin + public static final MessageType INPUT_REQUEST = new MessageType<>("input_request", InputRequest.class); + + public static final MessageType INPUT_REPLY = new MessageType<>("input_reply", InputReply.class); + + //Comm + public static final MessageType COMM_OPEN_COMMAND = new MessageType<>("comm_open", CommOpenCommand.class); + public static final MessageType COMM_MSG_COMMAND = new MessageType<>("comm_msg", CommMsgCommand.class); + public static final MessageType COMM_CLOSE_COMMAND = new MessageType<>("comm_close", CommCloseCommand.class); + + public static final MessageType UNKNOWN = new MessageType<>("none", Object.class); + + private final String name; + private final Class contentType; + private final int id; + private final MessageType errorType; + + private MessageType(String name, Class contentType) { + this(name, contentType, false); + } + + private MessageType(String name, Class contentType, boolean isErrorType) { + this.name = name; + this.contentType = contentType; + this.id = NEXT_ID.getAndIncrement(); + if (!isErrorType) { + TYPE_BY_NAME.put(name, this); + this.errorType = new MessageType<>(name, ErrorReply.class, true); + } else { + this.errorType = null; + } + } + + public String getName() { + return this.name; + } + + public Class getContentType() { + return this.contentType; + } + + public MessageType error() { + return this.errorType; + } + + public boolean isError() { + return this.errorType == null; + } + + public boolean isErrorFor(MessageType other) { + return this.isError() && this == other.error(); + } + + @Override + public String toString() { + return name; + } + + @Override + public int hashCode() { + return id; + } + + @Override + public boolean equals(Object obj) { + return this == obj; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/ReplyType.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/ReplyType.java new file mode 100644 index 0000000..bac9dd2 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/ReplyType.java @@ -0,0 +1,5 @@ +package io.github.spencerpark.jupyter.messages; + +public interface ReplyType { + public MessageType getRequestType(); +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/RequestType.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/RequestType.java new file mode 100644 index 0000000..eea1d4d --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/RequestType.java @@ -0,0 +1,5 @@ +package io.github.spencerpark.jupyter.messages; + +public interface RequestType { + public MessageType getReplyType(); +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/ExpressionValueAdapter.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/ExpressionValueAdapter.java new file mode 100644 index 0000000..f9baad1 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/ExpressionValueAdapter.java @@ -0,0 +1,38 @@ +package io.github.spencerpark.jupyter.messages.adapters; + +import com.google.gson.*; +import io.github.spencerpark.jupyter.kernel.display.DisplayData; +import io.github.spencerpark.jupyter.kernel.ExpressionValue; + +import java.lang.reflect.Type; + +/** + * Decode/encode an {@link ExpressionValue} as either a {@link ExpressionValue.Error} or {@link ExpressionValue.Success} + * based on the {@code "status"} field. + */ +public class ExpressionValueAdapter implements JsonSerializer, JsonDeserializer { + public static final ExpressionValueAdapter INSTANCE = new ExpressionValueAdapter(); + + private ExpressionValueAdapter() { } + + @Override + public ExpressionValue deserialize(JsonElement jsonElement, Type type, JsonDeserializationContext ctx) throws JsonParseException { + if (jsonElement.isJsonObject()) { + JsonElement status = jsonElement.getAsJsonObject().get("status"); + if (status != null && status.isJsonPrimitive() + && status.getAsString().equalsIgnoreCase("error")) + return ctx.deserialize(jsonElement, ExpressionValue.Error.class); + } + + DisplayData data = ctx.deserialize(jsonElement, DisplayData.class); + return new ExpressionValue.Success(data); + } + + @Override + public JsonElement serialize(ExpressionValue exprVal, Type type, JsonSerializationContext ctx) { + if (exprVal.isSuccess()) + return ctx.serialize(exprVal, ExpressionValue.Success.class); + else + return ctx.serialize(exprVal, ExpressionValue.Error.class); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/HeaderAdapter.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/HeaderAdapter.java new file mode 100644 index 0000000..93ed349 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/HeaderAdapter.java @@ -0,0 +1,41 @@ +package io.github.spencerpark.jupyter.messages.adapters; + +import com.google.gson.*; +import io.github.spencerpark.jupyter.messages.Header; +import io.github.spencerpark.jupyter.messages.KernelTimestamp; +import io.github.spencerpark.jupyter.messages.MessageType; + +import java.lang.reflect.Type; + +public class HeaderAdapter implements JsonSerializer
, JsonDeserializer
{ + public static final HeaderAdapter INSTANCE = new HeaderAdapter(); + + private HeaderAdapter() { } + + @Override + public Header deserialize(JsonElement element, Type type, JsonDeserializationContext ctx) throws JsonParseException { + JsonObject object = element.getAsJsonObject(); + return new Header<>( + object.get("msg_id").getAsString(), + object.get("username").getAsString(), + object.get("session").getAsString(), + ctx.deserialize(object.get("date"), KernelTimestamp.class), + ctx.deserialize(object.get("msg_type"), MessageType.class), + object.get("version").getAsString() + ); + } + + @Override + public JsonElement serialize(Header header, Type type, JsonSerializationContext ctx) { + JsonObject object = new JsonObject(); + + object.addProperty("msg_id", header.getId()); + object.addProperty("username", header.getUsername()); + object.addProperty("session", header.getSessionId()); + object.add("date", ctx.serialize(header.getTimestamp())); + object.add("msg_type", ctx.serialize(header.getType())); + object.addProperty("version", header.getVersion()); + + return object; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/HistoryEntryAdapter.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/HistoryEntryAdapter.java new file mode 100644 index 0000000..8205c23 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/HistoryEntryAdapter.java @@ -0,0 +1,36 @@ +package io.github.spencerpark.jupyter.messages.adapters; + +import com.google.gson.JsonArray; +import com.google.gson.JsonElement; +import com.google.gson.JsonSerializationContext; +import com.google.gson.JsonSerializer; +import io.github.spencerpark.jupyter.kernel.history.HistoryEntry; + +import java.lang.reflect.Type; + +public class HistoryEntryAdapter implements JsonSerializer { + public static final HistoryEntryAdapter INSTANCE = new HistoryEntryAdapter(); + + private HistoryEntryAdapter() { } + + @Override + public JsonElement serialize(HistoryEntry src, Type type, JsonSerializationContext ctx) { + JsonArray tuple = new JsonArray(); + + tuple.add(src.getSession()); + tuple.add(src.getCellNumber()); + + if (src.hasOutput()) { + JsonArray ioPair = new JsonArray(); + + ioPair.add(src.getInput()); + ioPair.add(src.getOutput()); + + tuple.add(ioPair); + } else { + tuple.add(src.getInput()); + } + + return tuple; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/HistoryRequestAdapter.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/HistoryRequestAdapter.java new file mode 100644 index 0000000..fc9cf3c --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/HistoryRequestAdapter.java @@ -0,0 +1,30 @@ +package io.github.spencerpark.jupyter.messages.adapters; + +import com.google.gson.*; +import io.github.spencerpark.jupyter.messages.request.HistoryRequest; + +import java.lang.reflect.Type; + +public class HistoryRequestAdapter implements JsonDeserializer { + public static final HistoryRequestAdapter INSTANCE = new HistoryRequestAdapter(); + + private HistoryRequestAdapter() { } + + @Override + public HistoryRequest deserialize(JsonElement element, Type type, JsonDeserializationContext ctx) throws JsonParseException { + JsonObject object = element.getAsJsonObject(); + JsonPrimitive accessTypeRaw = object.getAsJsonPrimitive("hist_access_type"); + + HistoryRequest.AccessType accessType = ctx.deserialize(accessTypeRaw, HistoryRequest.AccessType.class); + switch (accessType) { + case RANGE: + return ctx.deserialize(element, HistoryRequest.Range.class); + case TAIL: + return ctx.deserialize(element, HistoryRequest.Tail.class); + case SEARCH: + return ctx.deserialize(element, HistoryRequest.Search.class); + default: + throw new IllegalArgumentException("Unknown hist_access_type " + String.valueOf(accessTypeRaw)); + } + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/IdentityJsonElementAdapter.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/IdentityJsonElementAdapter.java new file mode 100644 index 0000000..6c86d8a --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/IdentityJsonElementAdapter.java @@ -0,0 +1,39 @@ +package io.github.spencerpark.jupyter.messages.adapters; + +import com.google.gson.Gson; +import com.google.gson.GsonBuilder; +import com.google.gson.JsonElement; +import com.google.gson.TypeAdapter; +import com.google.gson.stream.JsonReader; +import com.google.gson.stream.JsonWriter; + +import java.io.IOException; + +/** + * A {@link JsonElement} type adapter that serializes null whether it is enabled on the + * writer or not. It must be explicitly enabled with the {@link com.google.gson.annotations.JsonAdapter @JsonAdapter} + * annotation. + */ +public class IdentityJsonElementAdapter extends TypeAdapter { + private static final ThreadLocal GSON = ThreadLocal.withInitial(() -> + new GsonBuilder().serializeNulls().create()); + + @Override + public void write(JsonWriter out, JsonElement value) throws IOException { + if (out.getSerializeNulls()) { + GSON.get().toJson(value, out); + } else { + out.setSerializeNulls(true); + try { + GSON.get().toJson(value, out); + } finally { + out.setSerializeNulls(false); + } + } + } + + @Override + public JsonElement read(JsonReader in) throws IOException { + return GSON.get().fromJson(in, JsonElement.class); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/KernelTimestampAdapter.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/KernelTimestampAdapter.java new file mode 100644 index 0000000..69e4eea --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/KernelTimestampAdapter.java @@ -0,0 +1,22 @@ +package io.github.spencerpark.jupyter.messages.adapters; + +import com.google.gson.*; +import io.github.spencerpark.jupyter.messages.KernelTimestamp; + +import java.lang.reflect.Type; + +public class KernelTimestampAdapter implements JsonSerializer, JsonDeserializer { + public static final KernelTimestampAdapter INSTANCE = new KernelTimestampAdapter(); + + private KernelTimestampAdapter() { } + + @Override + public KernelTimestamp deserialize(JsonElement element, Type type, JsonDeserializationContext ctx) { + return new KernelTimestamp(element.getAsString()); + } + + @Override + public JsonElement serialize(KernelTimestamp timestamp, Type type, JsonSerializationContext ctx) { + return new JsonPrimitive(timestamp.getDateString()); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/MessageTypeAdapter.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/MessageTypeAdapter.java new file mode 100644 index 0000000..e2801a6 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/MessageTypeAdapter.java @@ -0,0 +1,22 @@ +package io.github.spencerpark.jupyter.messages.adapters; + +import com.google.gson.*; +import io.github.spencerpark.jupyter.messages.MessageType; + +import java.lang.reflect.Type; + +public class MessageTypeAdapter implements JsonSerializer>, JsonDeserializer> { + public static final MessageTypeAdapter INSTANCE = new MessageTypeAdapter(); + + private MessageTypeAdapter() { } + + @Override + public MessageType deserialize(JsonElement jsonElement, Type type, JsonDeserializationContext ctx) throws JsonParseException { + return MessageType.getType(jsonElement.getAsString()); + } + + @Override + public JsonElement serialize(MessageType messageType, Type type, JsonSerializationContext ctx) { + return new JsonPrimitive(messageType.getName()); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/PublishStatusAdapter.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/PublishStatusAdapter.java new file mode 100644 index 0000000..7e13950 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/PublishStatusAdapter.java @@ -0,0 +1,23 @@ +package io.github.spencerpark.jupyter.messages.adapters; + +import com.google.gson.*; +import io.github.spencerpark.jupyter.messages.publish.PublishStatus; + +import java.lang.reflect.Type; + +public class PublishStatusAdapter implements JsonDeserializer { + public static final PublishStatusAdapter INSTANCE = new PublishStatusAdapter(); + + private PublishStatusAdapter() { } + + @Override + public PublishStatus deserialize(JsonElement element, Type type, JsonDeserializationContext ctx) throws JsonParseException { + PublishStatus.State state = ctx.deserialize(element.getAsJsonObject().get("execution_result"), PublishStatus.State.class); + switch (state) { + case BUSY: return PublishStatus.BUSY; + case IDLE: return PublishStatus.IDLE; + case STARTING: return PublishStatus.STARTING; + default: return null; + } + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/ReplyTypeAdapter.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/ReplyTypeAdapter.java new file mode 100644 index 0000000..0d1fdc9 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/ReplyTypeAdapter.java @@ -0,0 +1,35 @@ +package io.github.spencerpark.jupyter.messages.adapters; + +import com.google.gson.*; +import io.github.spencerpark.jupyter.messages.ReplyType; +import io.github.spencerpark.jupyter.messages.reply.ErrorReply; + +import java.lang.reflect.Type; + +public class ReplyTypeAdapter implements JsonDeserializer> { + private final Gson replyGson; + + /** + * Important: the given instance must not have this type + * adapter registered or deserialization with this deserializer will + * cause a stack overflow exception. + * + * @param replyGson the gson instance to use when deserializing replies. + */ + public ReplyTypeAdapter(Gson replyGson) { + this.replyGson = replyGson; + } + + @Override + public ReplyType deserialize(JsonElement jsonElement, Type type, JsonDeserializationContext ctx) throws JsonParseException { + // If the reply is an error, decode as an ErrorReply instead of the content type + if (jsonElement.isJsonObject()) { + JsonElement status = jsonElement.getAsJsonObject().get("status"); + if (status != null && status.isJsonPrimitive() + && status.getAsString().equalsIgnoreCase("error")) + return this.replyGson.fromJson(jsonElement, ErrorReply.class); + } + + return this.replyGson.fromJson(jsonElement, type); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/comm/CommCloseCommand.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/comm/CommCloseCommand.java new file mode 100644 index 0000000..69ac292 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/comm/CommCloseCommand.java @@ -0,0 +1,36 @@ +package io.github.spencerpark.jupyter.messages.comm; + +import com.google.gson.JsonObject; +import com.google.gson.annotations.JsonAdapter; +import com.google.gson.annotations.SerializedName; +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.adapters.IdentityJsonElementAdapter; + +public class CommCloseCommand implements ContentType { + public static final MessageType MESSAGE_TYPE = MessageType.COMM_CLOSE_COMMAND; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @SerializedName("comm_id") + protected final String commId; + + @JsonAdapter(IdentityJsonElementAdapter.class) + protected final JsonObject data; + + public CommCloseCommand(String commId, JsonObject data) { + this.commId = commId; + this.data = data; + } + + public String getCommID() { + return commId; + } + + public JsonObject getData() { + return data; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/comm/CommMsgCommand.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/comm/CommMsgCommand.java new file mode 100644 index 0000000..235413a --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/comm/CommMsgCommand.java @@ -0,0 +1,36 @@ +package io.github.spencerpark.jupyter.messages.comm; + +import com.google.gson.JsonObject; +import com.google.gson.annotations.JsonAdapter; +import com.google.gson.annotations.SerializedName; +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.adapters.IdentityJsonElementAdapter; + +public class CommMsgCommand implements ContentType { + public static final MessageType MESSAGE_TYPE = MessageType.COMM_MSG_COMMAND; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @SerializedName("comm_id") + protected final String commId; + + @JsonAdapter(IdentityJsonElementAdapter.class) + protected final JsonObject data; + + public CommMsgCommand(String commId, JsonObject data) { + this.commId = commId; + this.data = data; + } + + public String getCommID() { + return commId; + } + + public JsonObject getData() { + return data; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/comm/CommOpenCommand.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/comm/CommOpenCommand.java new file mode 100644 index 0000000..5a37acf --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/comm/CommOpenCommand.java @@ -0,0 +1,44 @@ +package io.github.spencerpark.jupyter.messages.comm; + +import com.google.gson.JsonObject; +import com.google.gson.annotations.JsonAdapter; +import com.google.gson.annotations.SerializedName; +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.adapters.IdentityJsonElementAdapter; + +public class CommOpenCommand implements ContentType { + public static final MessageType MESSAGE_TYPE = MessageType.COMM_OPEN_COMMAND; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @SerializedName("comm_id") + protected final String commId; + + @SerializedName("target_name") + protected final String targetName; + + @JsonAdapter(IdentityJsonElementAdapter.class) + protected final JsonObject data; + + public CommOpenCommand(String commId, String targetName, JsonObject data) { + this.commId = commId; + this.targetName = targetName; + this.data = data; + } + + public String getCommID() { + return commId; + } + + public String getTargetName() { + return targetName; + } + + public JsonObject getData() { + return data; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/ErrorFormatter.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/ErrorFormatter.java new file mode 100644 index 0000000..2bf60c9 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/ErrorFormatter.java @@ -0,0 +1,8 @@ +package io.github.spencerpark.jupyter.messages.publish; + +import java.util.List; + +@FunctionalInterface +public interface ErrorFormatter { + List format(Exception e); +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishClearOutput.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishClearOutput.java new file mode 100644 index 0000000..508c244 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishClearOutput.java @@ -0,0 +1,29 @@ +package io.github.spencerpark.jupyter.messages.publish; + +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; + +public class PublishClearOutput implements ContentType { + public static final MessageType MESSAGE_TYPE = MessageType.PUBLISH_CLEAR_OUTPUT; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + public static final PublishClearOutput NOW = new PublishClearOutput(false); + public static final PublishClearOutput BEFORE_NEXT_OUTPUT = new PublishClearOutput(true); + + /** + * Wait to clear the output until the + */ + private final boolean wait; + + private PublishClearOutput(boolean wait) { + this.wait = wait; + } + + public boolean shouldWait() { + return wait; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishDisplayData.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishDisplayData.java new file mode 100644 index 0000000..1c48ed4 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishDisplayData.java @@ -0,0 +1,18 @@ +package io.github.spencerpark.jupyter.messages.publish; + +import io.github.spencerpark.jupyter.kernel.display.DisplayData; +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; + +public class PublishDisplayData extends DisplayData implements ContentType { + public static final MessageType MESSAGE_TYPE = MessageType.PUBLISH_DISPLAY_DATA; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + public PublishDisplayData(DisplayData data) { + super(data); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishError.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishError.java new file mode 100644 index 0000000..6ff2303 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishError.java @@ -0,0 +1,55 @@ +package io.github.spencerpark.jupyter.messages.publish; + +import com.google.gson.annotations.SerializedName; +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.reply.ErrorReply; + +import java.util.Arrays; +import java.util.List; +import java.util.stream.Collectors; + +/** + * See also {@link ErrorReply} + */ +public class PublishError implements ContentType { + public static final MessageType MESSAGE_TYPE = MessageType.PUBLISH_ERROR; + + public static PublishError of(Exception exception, ErrorFormatter formatter) { + String name = exception.getClass().getSimpleName(); + String msg = exception.getLocalizedMessage(); + List stacktrace = formatter.format(exception); + + return new PublishError(name, msg == null ? "" : msg, stacktrace); + } + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @SerializedName("ename") + protected final String errName; + @SerializedName("evalue") + protected final String errMsg; + @SerializedName("traceback") + protected final List stacktrace; + + public PublishError(String errName, String errMsg, List stacktrace) { + this.errName = errName; + this.errMsg = errMsg; + this.stacktrace = stacktrace; + } + + public String getErrorName() { + return errName; + } + + public String getErrorMessage() { + return errMsg; + } + + public List getStacktrace() { + return stacktrace; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishExecuteInput.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishExecuteInput.java new file mode 100644 index 0000000..0dc4bee --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishExecuteInput.java @@ -0,0 +1,38 @@ +package io.github.spencerpark.jupyter.messages.publish; + +import com.google.gson.annotations.SerializedName; +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; + +public class PublishExecuteInput implements ContentType { + public static final MessageType MESSAGE_TYPE = MessageType.PUBLISH_EXECUTE_INPUT; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + /** + * The code that is currently being executed + */ + private final String code; + + /** + * The current execution count + */ + @SerializedName("execution_count") + private final int count; + + public PublishExecuteInput(String code, int count) { + this.code = code; + this.count = count; + } + + public String getCode() { + return code; + } + + public int getCount() { + return count; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishExecuteResult.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishExecuteResult.java new file mode 100644 index 0000000..d0b82fb --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishExecuteResult.java @@ -0,0 +1,27 @@ +package io.github.spencerpark.jupyter.messages.publish; + +import com.google.gson.annotations.SerializedName; +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.kernel.display.DisplayData; +import io.github.spencerpark.jupyter.messages.MessageType; + +public class PublishExecuteResult extends DisplayData implements ContentType { + public static final MessageType MESSAGE_TYPE = MessageType.PUBLISH_EXECUTION_RESULT; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @SerializedName("execution_count") + private final int count; + + public PublishExecuteResult(int count, DisplayData data) { + super(data); + this.count = count; + } + + public int getCount() { + return count; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishStatus.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishStatus.java new file mode 100644 index 0000000..5ed1fc2 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishStatus.java @@ -0,0 +1,44 @@ +package io.github.spencerpark.jupyter.messages.publish; + +import com.google.gson.annotations.SerializedName; +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; + +public class PublishStatus implements ContentType { + public static final MessageType MESSAGE_TYPE = MessageType.PUBLISH_STATUS; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + public static final PublishStatus BUSY = new PublishStatus(State.BUSY); + public static final PublishStatus IDLE = new PublishStatus(State.IDLE); + public static final PublishStatus STARTING = new PublishStatus(State.STARTING); + + public static PublishStatus forState(State state) { + switch (state) { + case BUSY: return BUSY; + case IDLE: return IDLE; + case STARTING: return STARTING; + default: return null; + } + } + + public enum State { + @SerializedName("busy") BUSY, + @SerializedName("idle") IDLE, + @SerializedName("starting") STARTING + } + + @SerializedName("execution_state") + private final State state; + + private PublishStatus(State state) { + this.state = state; + } + + public State getState() { + return state; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishStream.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishStream.java new file mode 100644 index 0000000..f1d11c6 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishStream.java @@ -0,0 +1,39 @@ +package io.github.spencerpark.jupyter.messages.publish; + +import com.google.gson.annotations.SerializedName; +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; + +public class PublishStream implements ContentType { + public static final MessageType MESSAGE_TYPE = MessageType.PUBLISH_STREAM; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + public enum StreamType { + @SerializedName("stdout") OUT, + @SerializedName("stderr") ERR + } + + /** + * One of 'stdout' or 'stderr' + */ + @SerializedName("name") + private final StreamType type; + private final String text; + + public PublishStream(StreamType type, String text) { + this.type = type; + this.text = text; + } + + public StreamType getStreamType() { + return type; + } + + public String getText() { + return text; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishUpdateDisplayData.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishUpdateDisplayData.java new file mode 100644 index 0000000..ac719f9 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/publish/PublishUpdateDisplayData.java @@ -0,0 +1,21 @@ +package io.github.spencerpark.jupyter.messages.publish; + +import io.github.spencerpark.jupyter.kernel.display.DisplayData; +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; + +public class PublishUpdateDisplayData extends DisplayData implements ContentType { + public static final MessageType MESSAGE_TYPE = MessageType.PUBLISH_UPDATE_DISPLAY_DATA; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + public PublishUpdateDisplayData(DisplayData data) { + super(data); + + if (!data.hasDisplayId()) + throw new IllegalArgumentException("In order to update a display, the data must have a display_id."); + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/CommInfoReply.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/CommInfoReply.java new file mode 100644 index 0000000..4bbe5d0 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/CommInfoReply.java @@ -0,0 +1,50 @@ +package io.github.spencerpark.jupyter.messages.reply; + +import com.google.gson.annotations.SerializedName; +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.ReplyType; +import io.github.spencerpark.jupyter.messages.request.CommInfoRequest; + +import java.util.Map; + +public class CommInfoReply implements ContentType, ReplyType { + public static final MessageType MESSAGE_TYPE = MessageType.COMM_INFO_REPLY; + public static final MessageType REQUEST_MESSAGE_TYPE = MessageType.COMM_INFO_REQUEST; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @Override + public MessageType getRequestType() { + return REQUEST_MESSAGE_TYPE; + } + + public static class CommInfo { + @SerializedName("target_name") + protected final String targetName; + + public CommInfo(String targetName) { + this.targetName = targetName; + } + + public String getTargetName() { + return targetName; + } + } + + /** + * A map of uuid to target_name for the comms + */ + protected final Map comms; + + public CommInfoReply(Map comms) { + this.comms = comms; + } + + public Map getComms() { + return comms; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/CompleteReply.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/CompleteReply.java new file mode 100644 index 0000000..7adcfa7 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/CompleteReply.java @@ -0,0 +1,70 @@ +package io.github.spencerpark.jupyter.messages.reply; + +import com.google.gson.annotations.SerializedName; +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.ReplyType; +import io.github.spencerpark.jupyter.messages.request.CompleteRequest; + +import java.util.List; +import java.util.Map; + +public class CompleteReply implements ContentType, ReplyType { + public static final MessageType MESSAGE_TYPE = MessageType.COMPLETE_REPLY; + public static final MessageType REQUEST_MESSAGE_TYPE = MessageType.COMPLETE_REQUEST; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @Override + public MessageType getRequestType() { + return REQUEST_MESSAGE_TYPE; + } + + protected final String status = "ok"; + + protected final List matches; + + /** + * The starting position in the request's code to replace with a match + */ + @SerializedName("cursor_start") + protected final int cursorStart; + + /** + * The end position in the request's code to replace with a match + */ + @SerializedName("cursor_end") + protected final int cursorEnd; + + protected final Map metadata; + + public CompleteReply(List matches, int cursorStart, int cursorEnd, Map metadata) { + this.matches = matches; + this.cursorStart = cursorStart; + this.cursorEnd = cursorEnd; + this.metadata = metadata; + } + + public String getStatus() { + return status; + } + + public List getMatches() { + return matches; + } + + public int getCursorStart() { + return cursorStart; + } + + public int getCursorEnd() { + return cursorEnd; + } + + public Map getMetadata() { + return metadata; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/ErrorReply.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/ErrorReply.java new file mode 100644 index 0000000..6251c7c --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/ErrorReply.java @@ -0,0 +1,64 @@ +package io.github.spencerpark.jupyter.messages.reply; + +import com.google.gson.annotations.SerializedName; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.ReplyType; + +import java.util.Arrays; +import java.util.List; +import java.util.stream.Collectors; + +public class ErrorReply implements ReplyType { + @Override + public MessageType getRequestType() { + return MessageType.UNKNOWN; + } + + public static ErrorReply of(Exception exception) { + String name = exception.getClass().getSimpleName(); + String msg = exception.getLocalizedMessage(); + List stacktrace = Arrays.stream(exception.getStackTrace()) + .map(StackTraceElement::toString) + .collect(Collectors.toList()); + + return new ErrorReply(name, msg == null ? "" : msg, stacktrace); + } + + protected final String status = "error"; + @SerializedName("ename") + protected final String errName; + @SerializedName("evalue") + protected final String errMsg; + @SerializedName("traceback") + protected final List stacktrace; + + //Present for the execute_reply in erroneous execution + @SerializedName("execution_count") + protected Integer count; + + public ErrorReply(String errName, String errMsg, List stacktrace) { + this.errName = errName; + this.errMsg = errMsg; + this.stacktrace = stacktrace; + } + + public void setExecutionCount(int count) { + this.count = count; + } + + public String getStatus() { + return status; + } + + public String getErrorName() { + return errName; + } + + public String getErrorMessage() { + return errMsg; + } + + public List getStacktrace() { + return stacktrace; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/ExecuteReply.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/ExecuteReply.java new file mode 100644 index 0000000..72f4f38 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/ExecuteReply.java @@ -0,0 +1,66 @@ +package io.github.spencerpark.jupyter.messages.reply; + +import com.google.gson.annotations.SerializedName; +import io.github.spencerpark.jupyter.kernel.ExpressionValue; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.ReplyType; +import io.github.spencerpark.jupyter.messages.publish.PublishDisplayData; +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.request.ExecuteRequest; + +import java.util.Map; + +public class ExecuteReply implements ContentType, ReplyType { + public static final MessageType MESSAGE_TYPE = MessageType.EXECUTE_REPLY; + public static final MessageType REQUEST_MESSAGE_TYPE = MessageType.EXECUTE_REQUEST; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @Override + public MessageType getRequestType() { + return REQUEST_MESSAGE_TYPE; + } + + public enum Status { + @SerializedName("ok") OK, + @SerializedName("error") ERROR + } + + private final Status status; + + @SerializedName("execution_count") + protected final int executionCount; + + /** + * The values are either {@link ErrorReply} or {@link PublishDisplayData} + */ + @SerializedName("user_expressions") + protected final Map evaluatedUserExpr; + + public ExecuteReply(int executionCount, Map evaluatedUserExpr) { + this.status = Status.OK; + this.executionCount = executionCount; + this.evaluatedUserExpr = evaluatedUserExpr; + } + + public ExecuteReply(int executionCount) { + this.status = Status.ERROR; + this.executionCount = executionCount; + this.evaluatedUserExpr = null; + } + + public Status getStatus() { + return status; + } + + public int getExecutionCount() { + return executionCount; + } + + public Map getEvaluatedUserExpr() { + return evaluatedUserExpr; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/HistoryReply.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/HistoryReply.java new file mode 100644 index 0000000..3d8d84d --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/HistoryReply.java @@ -0,0 +1,34 @@ +package io.github.spencerpark.jupyter.messages.reply; + +import io.github.spencerpark.jupyter.kernel.history.HistoryEntry; +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.ReplyType; +import io.github.spencerpark.jupyter.messages.request.HistoryRequest; + +import java.util.List; + +public class HistoryReply implements ContentType, ReplyType { + public static final MessageType MESSAGE_TYPE = MessageType.HISTORY_REPLY; + public static final MessageType REQUEST_MESSAGE_TYPE = MessageType.HISTORY_REQUEST; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @Override + public MessageType getRequestType() { + return REQUEST_MESSAGE_TYPE; + } + + protected final List history; + + public HistoryReply(List history) { + this.history = history; + } + + public List getHistory() { + return history; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/InputReply.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/InputReply.java new file mode 100644 index 0000000..d12af3d --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/InputReply.java @@ -0,0 +1,31 @@ +package io.github.spencerpark.jupyter.messages.reply; + +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.ReplyType; +import io.github.spencerpark.jupyter.messages.request.InputRequest; + +public class InputReply implements ContentType, ReplyType { + public static final MessageType MESSAGE_TYPE = MessageType.INPUT_REPLY; + public static final MessageType REQUEST_MESSAGE_TYPE = MessageType.INPUT_REQUEST; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @Override + public MessageType getRequestType() { + return REQUEST_MESSAGE_TYPE; + } + + protected String value; + + public InputReply(String value) { + this.value = value; + } + + public String getValue() { + return value; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/InspectReply.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/InspectReply.java new file mode 100644 index 0000000..cd8e824 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/InspectReply.java @@ -0,0 +1,38 @@ +package io.github.spencerpark.jupyter.messages.reply; + +import io.github.spencerpark.jupyter.kernel.display.DisplayData; +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.ReplyType; +import io.github.spencerpark.jupyter.messages.request.InspectRequest; + +public class InspectReply extends DisplayData implements ContentType, ReplyType { + public static final MessageType MESSAGE_TYPE = MessageType.INSPECT_REPLY; + public static final MessageType REQUEST_MESSAGE_TYPE = MessageType.INSPECT_REQUEST; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @Override + public MessageType getRequestType() { + return REQUEST_MESSAGE_TYPE; + } + + protected final String status = "ok"; + protected final boolean found; + + public InspectReply(boolean found, DisplayData data) { + super(data); + this.found = found; + } + + public String getStatus() { + return status; + } + + public boolean isFound() { + return found; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/InterruptReply.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/InterruptReply.java new file mode 100644 index 0000000..402a926 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/InterruptReply.java @@ -0,0 +1,21 @@ +package io.github.spencerpark.jupyter.messages.reply; + +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.ReplyType; +import io.github.spencerpark.jupyter.messages.request.InterruptRequest; + +public class InterruptReply implements ContentType, ReplyType { + public static final MessageType MESSAGE_TYPE = MessageType.INTERRUPT_REPLY; + public static final MessageType REQUEST_MESSAGE_TYPE = MessageType.INTERRUPT_REQUEST; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @Override + public MessageType getRequestType() { + return REQUEST_MESSAGE_TYPE; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/IsCompleteReply.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/IsCompleteReply.java new file mode 100644 index 0000000..ea942e8 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/IsCompleteReply.java @@ -0,0 +1,112 @@ +package io.github.spencerpark.jupyter.messages.reply; + +import com.google.gson.annotations.SerializedName; +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.ReplyType; +import io.github.spencerpark.jupyter.messages.request.IsCompleteRequest; + +public class IsCompleteReply implements ContentType, ReplyType { + public static final MessageType MESSAGE_TYPE = MessageType.IS_COMPLETE_REPLY; + public static final MessageType REQUEST_MESSAGE_TYPE = MessageType.IS_COMPLETE_REQUEST; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @Override + public MessageType getRequestType() { + return REQUEST_MESSAGE_TYPE; + } + + public static final IsCompleteReply VALID_CODE = new IsCompleteReply(Status.VALID_CODE); + public static final IsCompleteReply INVALID_CODE = new IsCompleteReply(Status.INVALID_CODE); + public static final IsCompleteReply UNKNOWN = new IsCompleteReply(Status.UNKNOWN); + + private static final IsCompleteReply[] COMMON_INDENTS = { + new IsCompleteReply(Status.NOT_FINISHED, ""), + new IsCompleteReply(Status.NOT_FINISHED, " "), + new IsCompleteReply(Status.NOT_FINISHED, " "), + new IsCompleteReply(Status.NOT_FINISHED, " "), + new IsCompleteReply(Status.NOT_FINISHED, " "), + new IsCompleteReply(Status.NOT_FINISHED, " "), + new IsCompleteReply(Status.NOT_FINISHED, " "), + new IsCompleteReply(Status.NOT_FINISHED, " "), + new IsCompleteReply(Status.NOT_FINISHED, " "), + new IsCompleteReply(Status.NOT_FINISHED, "\t"), + new IsCompleteReply(Status.NOT_FINISHED, "\t\t") + }; + + /** + * Try to resolve the indent to a common, shared instance, otherwise + * create a new one. Since many indent replies will be a short sequence + * or whitespace or an empty string we can cache some of these. + * + * @param indent the indent to suggest the frontend prefixes the next + * line with + * + * @return a reply describing the indent suggestion + */ + public static IsCompleteReply getIncompleteReplyWithIndent(String indent) { + switch (indent) { + case "": + return COMMON_INDENTS[0]; + case " ": + return COMMON_INDENTS[1]; + case " ": + return COMMON_INDENTS[2]; + case " ": + return COMMON_INDENTS[3]; + case " ": + return COMMON_INDENTS[4]; + case " ": + return COMMON_INDENTS[5]; + case " ": + return COMMON_INDENTS[6]; + case " ": + return COMMON_INDENTS[7]; + case " ": + return COMMON_INDENTS[8]; + case "\t": + return COMMON_INDENTS[9]; + case "\t\t": + return COMMON_INDENTS[10]; + default: + return new IsCompleteReply(Status.NOT_FINISHED, indent); + } + } + + public enum Status { + @SerializedName("complete") VALID_CODE, + @SerializedName("incomplete") NOT_FINISHED, + @SerializedName("invalid") INVALID_CODE, + @SerializedName("unknown") UNKNOWN + } + + protected final Status status; + + /** + * If status is INVALID_CODE this is a hint for the front end on what + * to use for the indent on the next line. + */ + protected final String indent; + + private IsCompleteReply(Status status) { + this.status = status; + this.indent = ""; + } + + private IsCompleteReply(Status status, String indent) { + this.status = status; + this.indent = indent; + } + + public Status getStatus() { + return status; + } + + public String getIndent() { + return indent; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/KernelInfoReply.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/KernelInfoReply.java new file mode 100644 index 0000000..52526b7 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/KernelInfoReply.java @@ -0,0 +1,90 @@ +package io.github.spencerpark.jupyter.messages.reply; + +import com.google.gson.annotations.SerializedName; +import io.github.spencerpark.jupyter.kernel.LanguageInfo; +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.ReplyType; +import io.github.spencerpark.jupyter.messages.request.KernelInfoRequest; + +import java.util.List; + +public class KernelInfoReply implements ContentType, ReplyType { + public static final MessageType MESSAGE_TYPE = MessageType.KERNEL_INFO_REPLY; + public static final MessageType REQUEST_MESSAGE_TYPE = MessageType.KERNEL_INFO_REQUEST; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @Override + public MessageType getRequestType() { + return REQUEST_MESSAGE_TYPE; + } + + /** + * Semantic version string. X.Y.Z + */ + @SerializedName("protocol_version") + protected String protocolVersion; + + /** + * Ex. 'ipython' for IPython + */ + @SerializedName("implementation") + protected String implementationName; + + /** + * Semantic version string for the kernel + */ + @SerializedName("implementation_version") + protected String implementationVersion; + + @SerializedName("language_info") + protected LanguageInfo langInfo; + + /** + * An optional banner text about the kernel. + */ + protected String banner; + + /** + * Optional help links about the kernel language + */ + @SerializedName("help_links") + protected List helpLinks; + + public KernelInfoReply(String protocolVersion, String implementationName, String implementationVersion, LanguageInfo langInfo, String banner, List helpLinks) { + this.protocolVersion = protocolVersion; + this.implementationName = implementationName; + this.implementationVersion = implementationVersion; + this.langInfo = langInfo; + this.banner = banner; + this.helpLinks = helpLinks; + } + + public String getProtocolVersion() { + return protocolVersion; + } + + public String getImplementationName() { + return implementationName; + } + + public String getImplementationVersion() { + return implementationVersion; + } + + public LanguageInfo getLangInfo() { + return langInfo; + } + + public String getBanner() { + return banner; + } + + public List getHelpLinks() { + return helpLinks; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/ShutdownReply.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/ShutdownReply.java new file mode 100644 index 0000000..f4780f1 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/reply/ShutdownReply.java @@ -0,0 +1,34 @@ +package io.github.spencerpark.jupyter.messages.reply; + +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.ReplyType; +import io.github.spencerpark.jupyter.messages.request.ShutdownRequest; + +public class ShutdownReply implements ContentType, ReplyType { + public static final MessageType MESSAGE_TYPE = MessageType.SHUTDOWN_REPLY; + public static final MessageType REQUEST_MESSAGE_TYPE = MessageType.SHUTDOWN_REQUEST; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @Override + public MessageType getRequestType() { + return REQUEST_MESSAGE_TYPE; + } + + public static final ShutdownReply SHUTDOWN_AND_RESTART = new ShutdownReply(true); + public static final ShutdownReply SHUTDOWN = new ShutdownReply(false); + + protected boolean restart; + + private ShutdownReply(boolean restart) { + this.restart = restart; + } + + public boolean isRestart() { + return restart; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/CommInfoRequest.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/CommInfoRequest.java new file mode 100644 index 0000000..ee7baa9 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/CommInfoRequest.java @@ -0,0 +1,36 @@ +package io.github.spencerpark.jupyter.messages.request; + +import com.google.gson.annotations.SerializedName; +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.RequestType; +import io.github.spencerpark.jupyter.messages.reply.CommInfoReply; + +public class CommInfoRequest implements ContentType, RequestType { + public static final MessageType MESSAGE_TYPE = MessageType.COMM_INFO_REQUEST; + public static final MessageType REPLY_MESSAGE_TYPE = MessageType.COMM_INFO_REPLY; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @Override + public MessageType getReplyType() { + return REPLY_MESSAGE_TYPE; + } + + /** + * An optional target name + */ + @SerializedName("target_name") + protected final String targetName; + + public CommInfoRequest(String targetName) { + this.targetName = targetName; + } + + public String getTargetName() { + return targetName; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/CompleteRequest.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/CompleteRequest.java new file mode 100644 index 0000000..3dddc00 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/CompleteRequest.java @@ -0,0 +1,40 @@ +package io.github.spencerpark.jupyter.messages.request; + +import com.google.gson.annotations.SerializedName; +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.RequestType; +import io.github.spencerpark.jupyter.messages.reply.CompleteReply; + +public class CompleteRequest implements ContentType, RequestType { + public static final MessageType MESSAGE_TYPE = MessageType.COMPLETE_REQUEST; + public static final MessageType REPLY_MESSAGE_TYPE = MessageType.COMPLETE_REPLY; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @Override + public MessageType getReplyType() { + return REPLY_MESSAGE_TYPE; + } + + protected final String code; + + @SerializedName("cursor_pos") + protected final int cursorPos; + + public CompleteRequest(String code, int cursorPos) { + this.code = code; + this.cursorPos = cursorPos; + } + + public String getCode() { + return code; + } + + public int getCursorPos() { + return cursorPos; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/ExecuteRequest.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/ExecuteRequest.java new file mode 100644 index 0000000..6478513 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/ExecuteRequest.java @@ -0,0 +1,107 @@ +package io.github.spencerpark.jupyter.messages.request; + +import com.google.gson.annotations.SerializedName; +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.RequestType; +import io.github.spencerpark.jupyter.messages.reply.ExecuteReply; + +import java.util.Map; + +public class ExecuteRequest implements ContentType, RequestType { + public static final MessageType MESSAGE_TYPE = MessageType.EXECUTE_REQUEST; + public static final MessageType REPLY_MESSAGE_TYPE = MessageType.EXECUTE_REPLY; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @Override + public MessageType getReplyType() { + return REPLY_MESSAGE_TYPE; + } + + /** + * The source code to execute. May be a multiline string. + */ + protected final String code; + + /** + * silent -> !store_history + * + * if silent: + * - no broadcast on IOPUB channel + * - no execute_result reply + * + * Default: {@code false} + */ + protected final boolean silent; + + /** + * if storeHistory: + * - populate history + */ + @SerializedName("store_history") + protected final boolean storeHistory; + + /** + * A bank of {@code name -> code} that need to be evaluated. + * + * The idea behind it is that a front end may always want {@code path -> `pwd`} + * so that they can display where the kernel is. + */ + @SerializedName("user_expressions") + protected final Map userExpr; + + @SerializedName("allow_stdin") + protected final boolean stdinEnabled; + + @SerializedName("stop_on_error") + protected final boolean stopOnError; + + public ExecuteRequest(String code, boolean silent, boolean storeHistory, Map userExpr, boolean stdinEnabled, boolean stopOnError) { + this.code = code; + this.silent = silent; + this.storeHistory = storeHistory; + this.userExpr = userExpr; + this.stdinEnabled = stdinEnabled; + this.stopOnError = stopOnError; + } + + public String getCode() { + return code; + } + + public boolean isSilent() { + return silent; + } + + public boolean shouldStoreHistory() { + return storeHistory; + } + + public Map getUserExpr() { + return userExpr; + } + + public boolean isStdinEnabled() { + return stdinEnabled; + } + + public boolean shouldStopOnError() { + return stopOnError; + } + + @Override + public String toString() { + return "ExecuteRequest{" + + "code='" + code + '\'' + + ", silent=" + silent + + ", storeHistory=" + storeHistory + + ", userExpr=" + userExpr + + ", stdinEnabled=" + stdinEnabled + + ", stopOnError=" + stopOnError + + '}'; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/HistoryRequest.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/HistoryRequest.java new file mode 100644 index 0000000..9fd9d48 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/HistoryRequest.java @@ -0,0 +1,150 @@ +package io.github.spencerpark.jupyter.messages.request; + +import com.google.gson.annotations.SerializedName; +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.RequestType; +import io.github.spencerpark.jupyter.messages.reply.HistoryReply; + +public class HistoryRequest implements ContentType, RequestType { + public static final MessageType MESSAGE_TYPE = MessageType.HISTORY_REQUEST; + public static final MessageType REPLY_MESSAGE_TYPE = MessageType.HISTORY_REPLY; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @Override + public MessageType getReplyType() { + return REPLY_MESSAGE_TYPE; + } + + public enum AccessType { + @SerializedName("range") RANGE, + @SerializedName("tail") TAIL, + @SerializedName("search") SEARCH, + } + + /** + * If true, include the output associated with the inputs. + */ + protected final boolean output; + + /** + * If true, return the raw input history, else the transformed input. + */ + protected final boolean raw; + + @SerializedName("hist_access_type") + protected final AccessType accessType; + + private HistoryRequest(boolean output, boolean raw, AccessType accessType) { + this.output = output; + this.raw = raw; + this.accessType = accessType; + } + + public boolean includeOutput() { + return output; + } + + public boolean useRaw() { + return raw; + } + + public AccessType getAccessType() { + return accessType; + } + + public static class Range extends HistoryRequest { + /** + * A session index that counts up each time the kernel + * starts. If negative the number is counting back from + * the current session. + */ + protected final int session; + + /** + * Start cell (execution count number) within the session. + */ + protected final int start; + + /** + * Stop cell (execution count number) with the session. + */ + protected final int stop; + + public Range(boolean output, boolean raw, int session, int start, int stop) { + super(output, raw, AccessType.RANGE); + this.session = session; + this.start = start; + this.stop = stop; + } + + public int getSessionIndex() { + return session; + } + + public int getStart() { + return start; + } + + public int getStop() { + return stop; + } + } + + public static class Tail extends HistoryRequest { + /** + * Get the last n executions + */ + protected final int n; + + public Tail(boolean output, boolean raw, int n) { + super(output, raw, AccessType.TAIL); + this.n = n; + } + + public int getMaxReturnLength() { + return n; + } + } + + public static class Search extends HistoryRequest { + /** + * Get the last n executions + */ + protected final int n; + + /** + * Glob primary filter with '*' and '?'. Default to '*' + */ + protected final String pattern; + + /** + * If true, omit duplicate entries in the return. Defaults + * to false. + */ + protected final boolean unique; + + public Search(boolean output, boolean raw, int n, String pattern, boolean unique) { + super(output, raw, AccessType.SEARCH); + this.n = n; + this.pattern = pattern; + this.unique = unique; + } + + public int getMaxReturnLength() { + return n; + } + + public String getPattern() { + return pattern; + } + + public boolean filterUnique() { + return unique; + } + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/InputRequest.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/InputRequest.java new file mode 100644 index 0000000..328a309 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/InputRequest.java @@ -0,0 +1,37 @@ +package io.github.spencerpark.jupyter.messages.request; + +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.RequestType; +import io.github.spencerpark.jupyter.messages.reply.InputReply; + +public class InputRequest implements ContentType, RequestType { + public static final MessageType MESSAGE_TYPE = MessageType.INPUT_REQUEST; + public static final MessageType REPLY_MESSAGE_TYPE = MessageType.INPUT_REPLY; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @Override + public MessageType getReplyType() { + return REPLY_MESSAGE_TYPE; + } + + protected String prompt; + protected boolean password; + + public InputRequest(String prompt, boolean password) { + this.prompt = prompt; + this.password = password; + } + + public String getPrompt() { + return prompt; + } + + public boolean isPassword() { + return password; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/InspectRequest.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/InspectRequest.java new file mode 100644 index 0000000..0ef44e2 --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/InspectRequest.java @@ -0,0 +1,59 @@ +package io.github.spencerpark.jupyter.messages.request; + +import com.google.gson.annotations.SerializedName; +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.RequestType; +import io.github.spencerpark.jupyter.messages.reply.InspectReply; + +public class InspectRequest implements ContentType, RequestType { + public static final MessageType MESSAGE_TYPE = MessageType.INSPECT_REQUEST; + public static final MessageType REPLY_MESSAGE_TYPE = MessageType.INSPECT_REPLY; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @Override + public MessageType getReplyType() { + return REPLY_MESSAGE_TYPE; + } + + /** + * The code that the request wants inspected + */ + protected final String code; + + /** + * The character index within the code in which the cursor is + * at. This allows for an inspection + */ + @SerializedName("cursor_pos") + protected final int cursorPos; + + /** + * Either 0 or 1. 0 is the default and in IPython level 1 + * includes the source in the inspection. + */ + @SerializedName("detail_level") + protected final int detailLevel; + + public InspectRequest(String code, int cursorPos, int detailLevel) { + this.code = code; + this.cursorPos = cursorPos; + this.detailLevel = detailLevel; + } + + public String getCode() { + return code; + } + + public int getCursorPos() { + return cursorPos; + } + + public int getDetailLevel() { + return detailLevel; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/InterruptRequest.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/InterruptRequest.java new file mode 100644 index 0000000..39b119a --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/InterruptRequest.java @@ -0,0 +1,21 @@ +package io.github.spencerpark.jupyter.messages.request; + +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.RequestType; +import io.github.spencerpark.jupyter.messages.reply.InterruptReply; + +public class InterruptRequest implements ContentType, RequestType { + public static final MessageType MESSAGE_TYPE = MessageType.INTERRUPT_REQUEST; + public static final MessageType REPLY_MESSAGE_TYPE = MessageType.INTERRUPT_REPLY; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @Override + public MessageType getReplyType() { + return REPLY_MESSAGE_TYPE; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/IsCompleteRequest.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/IsCompleteRequest.java new file mode 100644 index 0000000..44a682a --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/IsCompleteRequest.java @@ -0,0 +1,31 @@ +package io.github.spencerpark.jupyter.messages.request; + +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.RequestType; +import io.github.spencerpark.jupyter.messages.reply.IsCompleteReply; + +public class IsCompleteRequest implements ContentType, RequestType { + public static final MessageType MESSAGE_TYPE = MessageType.IS_COMPLETE_REQUEST; + public static final MessageType REPLY_MESSAGE_TYPE = MessageType.IS_COMPLETE_REPLY; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @Override + public MessageType getReplyType() { + return REPLY_MESSAGE_TYPE; + } + + protected final String code; + + public IsCompleteRequest(String code) { + this.code = code; + } + + public String getCode() { + return code; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/KernelInfoRequest.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/KernelInfoRequest.java new file mode 100644 index 0000000..a41e04c --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/KernelInfoRequest.java @@ -0,0 +1,21 @@ +package io.github.spencerpark.jupyter.messages.request; + +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.RequestType; +import io.github.spencerpark.jupyter.messages.reply.KernelInfoReply; + +public class KernelInfoRequest implements ContentType, RequestType { + public static final MessageType MESSAGE_TYPE = MessageType.KERNEL_INFO_REQUEST; + public static final MessageType REPLY_MESSAGE_TYPE = MessageType.KERNEL_INFO_REPLY; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @Override + public MessageType getReplyType() { + return REPLY_MESSAGE_TYPE; + } +} diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/ShutdownRequest.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/ShutdownRequest.java new file mode 100644 index 0000000..25c9b2e --- /dev/null +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/request/ShutdownRequest.java @@ -0,0 +1,34 @@ +package io.github.spencerpark.jupyter.messages.request; + +import io.github.spencerpark.jupyter.messages.ContentType; +import io.github.spencerpark.jupyter.messages.MessageType; +import io.github.spencerpark.jupyter.messages.RequestType; +import io.github.spencerpark.jupyter.messages.reply.ShutdownReply; + +public class ShutdownRequest implements ContentType, RequestType { + public static final MessageType MESSAGE_TYPE = MessageType.SHUTDOWN_REQUEST; + public static final MessageType REPLY_MESSAGE_TYPE = MessageType.SHUTDOWN_REPLY; + + @Override + public MessageType getType() { + return MESSAGE_TYPE; + } + + @Override + public MessageType getReplyType() { + return REPLY_MESSAGE_TYPE; + } + + public static final ShutdownRequest SHUTDOWN_AND_RESTART = new ShutdownRequest(true); + public static final ShutdownRequest SHUTDOWN = new ShutdownRequest(false); + + protected boolean restart; + + private ShutdownRequest(boolean restart) { + this.restart = restart; + } + + public boolean isRestart() { + return restart; + } +} diff --git a/basekernel/src/main/resources/kernel-metadata.json b/basekernel/src/main/resources/kernel-metadata.json new file mode 100644 index 0000000..f200f68 --- /dev/null +++ b/basekernel/src/main/resources/kernel-metadata.json @@ -0,0 +1,4 @@ +{ + "version": "@version@", + "project": "@project@" +} \ No newline at end of file diff --git a/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/display/RenderRequestTypesResolutionTest.java b/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/display/RenderRequestTypesResolutionTest.java new file mode 100644 index 0000000..f73374f --- /dev/null +++ b/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/display/RenderRequestTypesResolutionTest.java @@ -0,0 +1,66 @@ +package io.github.spencerpark.jupyter.kernel.display; + +import io.github.spencerpark.jupyter.kernel.display.mime.MIMEType; +import org.junit.Test; +import org.junit.runner.RunWith; +import org.junit.runners.Parameterized; + +import java.util.Arrays; +import java.util.Collection; +import java.util.Collections; +import java.util.List; + +import static org.junit.Assert.assertEquals; + +@RunWith(Parameterized.class) +public class RenderRequestTypesResolutionTest { + @Parameterized.Parameters + public static Collection data() { + return Arrays.asList(new Object[][]{ + { "image/svg+xml", "image/svg+xml", Collections.singletonList("image/svg+xml") }, + { "image/svg+xml", "image/svg", Collections.singletonList("image/svg") }, + { "image/svg+xml", "image/svg+xml", Collections.singletonList("image/*") }, + { "image/svg+xml", "image/svg+xml", Collections.singletonList("image") }, + { "image/svg+xml", "application/xml", Collections.singletonList("application/xml") }, + { "image/svg+xml", "application/xml", Collections.singletonList("application/*") }, + { "image/svg+xml", "application/xml", Collections.singletonList("application") }, + { "image/svg+xml", "image/svg+xml", Collections.singletonList("*") }, + + { "image/svg", "image/svg", Collections.singletonList("image/svg") }, + + { "image/svg", null, Collections.singletonList("application/xml") }, + { "image/svg+xml", null, Collections.singletonList("application/json") }, + }); + } + + private final MIMEType supported; + private final MIMEType expected; + private final RenderRequestTypes requestTypes; + + public RenderRequestTypesResolutionTest(String supported, String expected, List requestTypes) { + this.supported = supported == null ? null : MIMEType.parse(supported); + this.expected = expected == null ? null : MIMEType.parse(expected); + + RenderRequestTypes.Builder builder = new RenderRequestTypes.Builder(group -> { + switch (group) { + case "xml": + return MIMEType.APPLICATION_XML; + case "json": + return MIMEType.APPLICATION_JSON; + default: + return null; + } + }); + requestTypes.stream() + .map(MIMEType::parse) + .forEach(builder::withType); + this.requestTypes = builder.build(); + } + + @Test + public void test() { + MIMEType actual = this.requestTypes.resolveSupportedType(this.supported); + + assertEquals(expected, actual); + } +} \ No newline at end of file diff --git a/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/display/RendererTest.java b/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/display/RendererTest.java new file mode 100644 index 0000000..156b7c1 --- /dev/null +++ b/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/display/RendererTest.java @@ -0,0 +1,454 @@ +package io.github.spencerpark.jupyter.kernel.display; + +import io.github.spencerpark.jupyter.kernel.display.mime.MIMEType; +import org.junit.Before; +import org.junit.Test; + +import java.util.*; + +import static org.junit.Assert.*; + +public class RendererTest { + private Renderer renderer; + + @Before + public void setUp() throws Exception { + this.renderer = new Renderer(); + this.renderer.createRegistration(D.class) + .preferring(MIMEType.TEXT_HTML) + .supporting(MIMEType.TEXT_LATEX) + .register((D d, RenderContext ctx) -> { + ctx.renderIfRequested(MIMEType.TEXT_HTML, d::html); + ctx.renderIfRequested(MIMEType.TEXT_LATEX, () -> "\\d"); + }); + this.renderer.createRegistration(F.class) + .supporting(MIMEType.ANY) + .register((F f, RenderContext ctx) -> { + ctx.renderIfRequested(MIMEType.TEXT_HTML, f::html); + ctx.renderIfRequested(MIMEType.TEXT_CSS, f::css); + ctx.renderIfRequested(MIMEType.APPLICATION_JAVASCRIPT, f::js); + }); + this.renderer.createRegistration(H.class) + .supporting(MIMEType.parse("text/*")) + .supporting(MIMEType.APPLICATION_JAVASCRIPT) + .register((H h, RenderContext ctx) -> { + ctx.renderIfRequested(MIMEType.TEXT_HTML, h::html); + ctx.renderIfRequested(MIMEType.TEXT_CSS, h::css); + ctx.renderIfRequested(MIMEType.APPLICATION_JAVASCRIPT, h::js); + }); + this.renderer.createRegistration(J.class) + .supporting(MIMEType.TEXT_PLAIN) + .supporting(MIMEType.APPLICATION_JAVASCRIPT) + .register((J j, RenderContext ctx) -> { + ctx.renderIfRequested(MIMEType.APPLICATION_JAVASCRIPT, j::js); + ctx.renderIfRequested(MIMEType.TEXT_PLAIN, j::pretty); + }); + } + + class A { + @Override + public String toString() { + return "A"; + } + } + + class B implements DisplayDataRenderable { + @Override + public Set getSupportedRenderTypes() { + return Collections.singleton(MIMEType.TEXT_MARKDOWN); + } + + @Override + public Set getPreferredRenderTypes() { + return Collections.singleton(MIMEType.TEXT_MARKDOWN); + } + + @Override + public void render(RenderContext context) { + context.renderIfRequested(MIMEType.TEXT_MARKDOWN, () -> "**B**"); + } + + @Override + public String toString() { + return "B"; + } + } + + class C implements DisplayDataRenderable { + private final Set supported = new LinkedHashSet<>(); + + C() { + this.supported.add(MIMEType.TEXT_MARKDOWN); + this.supported.add(MIMEType.TEXT_CSS); + } + + @Override + public Set getSupportedRenderTypes() { + return supported; + } + + @Override + public Set getPreferredRenderTypes() { + return Collections.singleton(MIMEType.TEXT_CSS); + } + + @Override + public void render(RenderContext context) { + context.renderIfRequested(MIMEType.TEXT_MARKDOWN, () -> "**C**"); + context.renderIfRequested(MIMEType.TEXT_CSS, () -> ".c{}"); + } + + @Override + public String toString() { + return "C"; + } + } + + class D { + public String html() { + return ""; + } + + @Override + public String toString() { + return "D"; + } + } + + class E implements DisplayDataRenderable { + @Override + public Set getSupportedRenderTypes() { + return Collections.singleton(MIMEType.ANY); + } + + @Override + public void render(RenderContext context) { + context.renderIfRequested(MIMEType.TEXT_HTML, () -> ""); + context.renderIfRequested(MIMEType.TEXT_CSS, () -> ".e{}"); + context.renderIfRequested(MIMEType.APPLICATION_JAVASCRIPT, () -> "e();"); + } + + @Override + public String toString() { + return "E"; + } + } + + class F { + public String html() { + return ""; + } + + public String css() { + return ".f{}"; + } + + public String js() { + return "f();"; + } + + @Override + public String toString() { + return "F"; + } + } + + class G implements DisplayDataRenderable { + @Override + public Set getSupportedRenderTypes() { + return new LinkedHashSet<>(Arrays.asList(MIMEType.parse("text/*"), MIMEType.APPLICATION_JAVASCRIPT)); + } + + @Override + public void render(RenderContext context) { + context.renderIfRequested(MIMEType.TEXT_HTML, () -> ""); + context.renderIfRequested(MIMEType.TEXT_CSS, () -> ".g{}"); + context.renderIfRequested(MIMEType.TEXT_LATEX, () -> "\\g"); + context.renderIfRequested(MIMEType.APPLICATION_JAVASCRIPT, () -> "g();"); + } + + @Override + public String toString() { + return "G"; + } + } + + class H { + public String html() { + return ""; + } + + public String css() { + return ".h{}"; + } + + public String js() { + return "h();"; + } + + @Override + public String toString() { + return "H"; + } + } + + class I implements DisplayDataRenderable { + @Override + public Set getSupportedRenderTypes() { + return new LinkedHashSet<>(Arrays.asList(MIMEType.TEXT_PLAIN, MIMEType.APPLICATION_JAVASCRIPT)); + } + + @Override + public void render(RenderContext context) { + context.renderIfRequested(MIMEType.APPLICATION_JAVASCRIPT, () -> "i();"); + context.renderIfRequested(MIMEType.TEXT_PLAIN, () -> "I!"); + } + + @Override + public String toString() { + return "I"; + } + } + + class J { + public String js() { + return "j();"; + } + + public String pretty() { + return "J!"; + } + + @Override + public String toString() { + return "J"; + } + } + + @Test + public void rendersPlainText() { + DisplayData data = this.renderer.render(new A()); + + assertEquals("A", data.getData(MIMEType.TEXT_PLAIN)); + } + + @Test + public void alwaysRendersPlainText() { + DisplayData data = this.renderer.render(new B()); + + assertEquals("B", data.getData(MIMEType.TEXT_PLAIN)); + } + + @Test + public void rendersPreferred() { + DisplayData data = this.renderer.render(new B()); + + assertEquals("**B**", data.getData(MIMEType.TEXT_MARKDOWN)); + } + + @Test + public void rendersJustPreferred() { + DisplayData data = this.renderer.render(new C()); + + assertEquals(".c{}", data.getData(MIMEType.TEXT_CSS)); + assertEquals("C", data.getData(MIMEType.TEXT_PLAIN)); + assertNull(data.getData(MIMEType.TEXT_MARKDOWN)); + } + + @Test + public void rendersExternal() { + DisplayData data = this.renderer.render(new D()); + + assertEquals("", data.getData(MIMEType.TEXT_HTML)); + assertEquals("D", data.getData(MIMEType.TEXT_PLAIN)); + assertNull(data.getData(MIMEType.TEXT_LATEX)); + } + + @Test + public void rendersAs() { + DisplayData data = this.renderer.renderAs(new C(), "text/markdown"); + + assertEquals("**C**", data.getData(MIMEType.TEXT_MARKDOWN)); + assertEquals("C", data.getData(MIMEType.TEXT_PLAIN)); + assertNull(data.getData(MIMEType.TEXT_CSS)); + } + + @Test + public void rendersAsExternal() { + DisplayData data = this.renderer.renderAs(new D(), "text/latex"); + + assertEquals("\\d", data.getData(MIMEType.TEXT_LATEX)); + assertEquals("D", data.getData(MIMEType.TEXT_PLAIN)); + assertNull(data.getData(MIMEType.TEXT_HTML)); + } + + @Test + public void supportsPreferringAll() { + DisplayData data = this.renderer.render(new E()); + + assertEquals("", data.getData(MIMEType.TEXT_HTML)); + assertEquals(".e{}", data.getData(MIMEType.TEXT_CSS)); + assertEquals("e();", data.getData(MIMEType.APPLICATION_JAVASCRIPT)); + assertEquals("E", data.getData(MIMEType.TEXT_PLAIN)); + } + + @Test + public void supportsPreferringAllExternal() { + DisplayData data = this.renderer.render(new F()); + + assertEquals("", data.getData(MIMEType.TEXT_HTML)); + assertEquals(".f{}", data.getData(MIMEType.TEXT_CSS)); + assertEquals("f();", data.getData(MIMEType.APPLICATION_JAVASCRIPT)); + assertEquals("F", data.getData(MIMEType.TEXT_PLAIN)); + } + + @Test + public void supportsPreferringAllRequestingAll() { + DisplayData data = this.renderer.renderAs(new E(), "*"); + + assertEquals("", data.getData(MIMEType.TEXT_HTML)); + assertEquals(".e{}", data.getData(MIMEType.TEXT_CSS)); + assertEquals("e();", data.getData(MIMEType.APPLICATION_JAVASCRIPT)); + assertEquals("E", data.getData(MIMEType.TEXT_PLAIN)); + } + + @Test + public void supportsPreferringAllRequestingAllExternal() { + DisplayData data = this.renderer.renderAs(new F(), "*"); + + assertEquals("", data.getData(MIMEType.TEXT_HTML)); + assertEquals(".f{}", data.getData(MIMEType.TEXT_CSS)); + assertEquals("f();", data.getData(MIMEType.APPLICATION_JAVASCRIPT)); + assertEquals("F", data.getData(MIMEType.TEXT_PLAIN)); + } + + @Test + public void supportsPreferringAllRequestingSome() { + DisplayData data = this.renderer.renderAs(new E(), "text/html"); + + assertEquals("", data.getData(MIMEType.TEXT_HTML)); + assertNull(data.getData(MIMEType.TEXT_CSS)); + assertNull(data.getData(MIMEType.APPLICATION_JAVASCRIPT)); + assertEquals("E", data.getData(MIMEType.TEXT_PLAIN)); + } + + @Test + public void supportsPreferringAllRequestingSomeExternal() { + DisplayData data = this.renderer.renderAs(new F(), "text/html"); + + assertEquals("", data.getData(MIMEType.TEXT_HTML)); + assertNull(data.getData(MIMEType.TEXT_CSS)); + assertNull(data.getData(MIMEType.APPLICATION_JAVASCRIPT)); + assertEquals("F", data.getData(MIMEType.TEXT_PLAIN)); + } + + @Test + public void supportsPreferringAllRequestingGroup() { + DisplayData data = this.renderer.renderAs(new E(), "text/*"); + + assertEquals("", data.getData(MIMEType.TEXT_HTML)); + assertEquals(".e{}", data.getData(MIMEType.TEXT_CSS)); + assertNull(data.getData(MIMEType.APPLICATION_JAVASCRIPT)); + assertEquals("E", data.getData(MIMEType.TEXT_PLAIN)); + } + + @Test + public void supportsPreferringAllRequestingGroupExternal() { + DisplayData data = this.renderer.renderAs(new F(), "text/*"); + + assertEquals("", data.getData(MIMEType.TEXT_HTML)); + assertEquals(".f{}", data.getData(MIMEType.TEXT_CSS)); + assertNull(data.getData(MIMEType.APPLICATION_JAVASCRIPT)); + assertEquals("F", data.getData(MIMEType.TEXT_PLAIN)); + } + + @Test + public void supportsPreferringGroup() { + DisplayData data = this.renderer.render(new G()); + + assertEquals("", data.getData(MIMEType.TEXT_HTML)); + assertEquals(".g{}", data.getData(MIMEType.TEXT_CSS)); + assertEquals("g();", data.getData(MIMEType.APPLICATION_JAVASCRIPT)); + assertEquals("G", data.getData(MIMEType.TEXT_PLAIN)); + } + + @Test + public void supportsPreferringGroupExternal() { + DisplayData data = this.renderer.render(new H()); + + assertEquals("", data.getData(MIMEType.TEXT_HTML)); + assertEquals(".h{}", data.getData(MIMEType.TEXT_CSS)); + assertEquals("h();", data.getData(MIMEType.APPLICATION_JAVASCRIPT)); + assertEquals("H", data.getData(MIMEType.TEXT_PLAIN)); + } + + @Test + public void supportsPreferringGroupRequestingSome() { + DisplayData data = this.renderer.renderAs(new G(), "text/html"); + + assertEquals("", data.getData(MIMEType.TEXT_HTML)); + assertNull(data.getData(MIMEType.TEXT_CSS)); + assertNull(data.getData(MIMEType.APPLICATION_JAVASCRIPT)); + assertEquals("G", data.getData(MIMEType.TEXT_PLAIN)); + } + + @Test + public void supportsPreferringGroupRequestingSomeExternal() { + DisplayData data = this.renderer.renderAs(new H(), "text/html"); + + assertEquals("", data.getData(MIMEType.TEXT_HTML)); + assertNull(data.getData(MIMEType.TEXT_CSS)); + assertNull(data.getData(MIMEType.APPLICATION_JAVASCRIPT)); + assertEquals("H", data.getData(MIMEType.TEXT_PLAIN)); + } + + @Test + public void supportsPreferringGroupRequestingGroup() { + DisplayData data = this.renderer.renderAs(new G(), "text/*"); + + assertEquals("", data.getData(MIMEType.TEXT_HTML)); + assertEquals(".g{}", data.getData(MIMEType.TEXT_CSS)); + assertNull(data.getData(MIMEType.APPLICATION_JAVASCRIPT)); + assertEquals("G", data.getData(MIMEType.TEXT_PLAIN)); + } + + @Test + public void supportsPreferringGroupRequestingGroupExternal() { + DisplayData data = this.renderer.renderAs(new H(), "text/*"); + + assertEquals("", data.getData(MIMEType.TEXT_HTML)); + assertEquals(".h{}", data.getData(MIMEType.TEXT_CSS)); + assertNull(data.getData(MIMEType.APPLICATION_JAVASCRIPT)); + assertEquals("H", data.getData(MIMEType.TEXT_PLAIN)); + } + + @Test + public void supportsOverridingTextRepresentation() { + DisplayData data = this.renderer.render(new I()); + + assertEquals("I!", data.getData(MIMEType.TEXT_PLAIN)); + } + + @Test + public void supportsOverridingTextRepresentationExternal() { + DisplayData data = this.renderer.render(new J()); + + assertEquals("J!", data.getData(MIMEType.TEXT_PLAIN)); + } + + @Test + public void supportsOverridingTextRepresentationWhenNotRequested() { + DisplayData data = this.renderer.renderAs(new I(), "application/javascript"); + + assertEquals("i();", data.getData(MIMEType.APPLICATION_JAVASCRIPT)); + assertEquals("I!", data.getData(MIMEType.TEXT_PLAIN)); + } + + @Test + public void supportsOverridingTextRepresentationWhenNotRequestedExternal() { + DisplayData data = this.renderer.renderAs(new J(), "application/javascript"); + + assertEquals("j();", data.getData(MIMEType.APPLICATION_JAVASCRIPT)); + assertEquals("J!", data.getData(MIMEType.TEXT_PLAIN)); + } +} \ No newline at end of file diff --git a/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMETypeTest.java b/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMETypeTest.java new file mode 100644 index 0000000..8db81f2 --- /dev/null +++ b/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/display/mime/MIMETypeTest.java @@ -0,0 +1,51 @@ +package io.github.spencerpark.jupyter.kernel.display.mime; + +import org.junit.Test; +import org.junit.runner.RunWith; +import org.junit.runners.Parameterized; +import org.junit.runners.Parameterized.Parameters; + +import java.util.Arrays; + +import static org.junit.Assert.*; + +@RunWith(Parameterized.class) +public class MIMETypeTest { + @Parameters(name = "{index}: MIMEType.parse({0}) = new MIMEType({1}, {2}, {3}, {4})") + public static Iterable data() { + return Arrays.asList(new Object[][]{ + { "application/json", "application", null, "json", null }, + { "application/xhtml+xml", "application", null, "xhtml", "xml" }, + { "image/*", "image", null, "*", null }, + { "image/", "image", null, "", null }, + { "video", "video", null, null, null }, + { "video", "video", null, null, null }, + { "application/vnd.media", "application", "vnd", "media", null }, + { "application/vnd.media.producer", "application", "vnd", "media.producer", null }, + { "application/vnd.media.producer+suffix", "application", "vnd", "media.producer", "suffix" }, + { "application/vnd.media.named+producer+suffix", "application", "vnd", "media.named+producer", "suffix" }, + }); + } + + private String raw; + private String type; + private String tree; + private String subtype; + private String suffix; + + public MIMETypeTest(String raw, String type, String tree, String subtype, String suffix) { + this.raw = raw; + this.type = type; + this.tree = tree; + this.subtype = subtype; + this.suffix = suffix; + } + + @Test + public void test() { + MIMEType parsed = MIMEType.parse(this.raw); + MIMEType expected = new MIMEType(this.type, this.tree, this.subtype, this.suffix); + + assertEquals(expected, parsed); + } +} \ No newline at end of file diff --git a/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/magic/MagicParserTest.java b/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/magic/MagicParserTest.java new file mode 100644 index 0000000..6498df4 --- /dev/null +++ b/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/magic/MagicParserTest.java @@ -0,0 +1,142 @@ +package io.github.spencerpark.jupyter.kernel.magic; + +import org.junit.Before; +import org.junit.Test; + +import java.util.Arrays; +import java.util.List; +import java.util.stream.Collectors; +import java.util.stream.Stream; + +import static org.junit.Assert.assertEquals; +import static org.junit.Assert.assertNotNull; + +public class MagicParserTest { + public static List split(String args) { + return MagicParser.split(args); + } + + private MagicParser inlineParser; + private MagicParser solParser; + + @Before + public void setUp() throws Exception { + this.inlineParser = new MagicParser("//%", "//%%"); + this.solParser = new MagicParser("^\\s*//%", "//%%"); + } + + @Test + public void transformLineMagics() { + String cell = Stream.of( + "//%magicName arg1 arg2", + "Inline magic = //%magicName2 arg1", + "//Just a comment", + "//%magicName3 arg1 \"arg2 arg2\"" + ).collect(Collectors.joining("\n")); + + String transformedCell = this.inlineParser.transformLineMagics(cell, ctx -> + "**" + ctx.getMagicCall().getName() + "-" + ctx.getMagicCall().getArgs().stream().collect(Collectors.joining(",")) + ); + + String expectedTransformedCell = Stream.of( + "**magicName-arg1,arg2", + "Inline magic = **magicName2-arg1", + "//Just a comment", + "**magicName3-arg1,arg2 arg2" + ).collect(Collectors.joining("\n")); + + assertEquals(expectedTransformedCell, transformedCell); + } + + @Test + public void parseCellMagic() { + String cell = Stream.of( + "//%%cellMagicName arg1 \"arg2 arg2\" arg3 ", + "This is the body", + "with multiple lines" + ).collect(Collectors.joining("\n")); + + CellMagicParseContext ctx = this.inlineParser.parseCellMagic(cell); + + assertNotNull(ctx); + assertEquals("cellMagicName", ctx.getMagicCall().getName()); + assertEquals(Arrays.asList("arg1", "arg2 arg2", "arg3"), ctx.getMagicCall().getArgs()); + assertEquals("This is the body\nwith multiple lines", ctx.getMagicCall().getBody()); + assertEquals("//%%cellMagicName arg1 \"arg2 arg2\" arg3 ", ctx.getRawArgsLine()); + assertEquals(cell, ctx.getRawCell()); + } + + @Test + public void transformCellMagic() { + String cell = Stream.of( + "//%%cellMagicName arg1 \"arg2 arg2\" arg3 ", + "This is the body", + "with multiple lines" + ).collect(Collectors.joining("\n")); + + String transformedCell = this.inlineParser.transformCellMagic(cell, ctx -> + ctx.getMagicCall().getName() + "(" + ctx.getMagicCall().getArgs().stream().collect(Collectors.joining(",")) + ")" + "\n" + + ctx.getMagicCall().getBody() + ); + + String expectedTransformedCell = "cellMagicName(arg1,arg2 arg2,arg3)\nThis is the body\nwith multiple lines"; + + assertEquals(expectedTransformedCell, transformedCell); + } + + @Test + public void dontTransformNonMagicCell() { + String cell = Stream.of( + "//%cellMagicName arg1 \"arg2 arg2\" arg3 ", + "This is the body", + "with multiple lines" + ).collect(Collectors.joining("\n")); + + String transformedCell = this.inlineParser.transformCellMagic(cell, ctx -> "transformer applied"); + + assertEquals(cell, transformedCell); + } + + @Test + public void startOfLineParserSkipsInlineMagics() { + String cell = "System.out.printf(\"Fmt //%s string\", \"test\");"; + + String transformedCell = this.solParser.transformLineMagics(cell, ctx -> ""); + + assertEquals(cell, transformedCell); + } + + @Test + public void startOfLineParserAllowsWhitespace() { + String cell = Stream.of( + "//%sol", + " //%sol2", + "\t//%sol3" + ).collect(Collectors.joining("\n")); + + String transformedCell = this.solParser.transformLineMagics(cell, ctx -> ctx.getMagicCall().getName()); + String expectedTransformedCell = Stream.of( + "sol", + "sol2", + "sol3" + ).collect(Collectors.joining("\n")); + + assertEquals(expectedTransformedCell, transformedCell); + } + + @Test + public void startOfLineParserSkipsInline() { + String cell = Stream.of( + "//%sol", + "Not //%sol" + ).collect(Collectors.joining("\n")); + + String transformedCell = this.solParser.transformLineMagics(cell, ctx -> ctx.getMagicCall().getName()); + String expectedTransformedCell = Stream.of( + "sol", + "Not //%sol" + ).collect(Collectors.joining("\n")); + + assertEquals(expectedTransformedCell, transformedCell); + } +} \ No newline at end of file diff --git a/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/magic/registry/MagicsArgsTest.java b/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/magic/registry/MagicsArgsTest.java new file mode 100644 index 0000000..f8eb19f --- /dev/null +++ b/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/magic/registry/MagicsArgsTest.java @@ -0,0 +1,196 @@ +package io.github.spencerpark.jupyter.kernel.magic.registry; + +import io.github.spencerpark.jupyter.kernel.magic.MagicParserTest; +import org.hamcrest.Matcher; +import org.junit.Rule; +import org.junit.Test; +import org.junit.rules.ExpectedException; +import org.junit.runner.RunWith; +import org.junit.runners.Parameterized; + +import java.util.Arrays; +import java.util.Collection; +import java.util.List; +import java.util.Map; +import java.util.function.Consumer; + +import static org.hamcrest.Matchers.allOf; +import static org.hamcrest.Matchers.hasEntry; +import static org.junit.Assert.assertThat; + +@RunWith(Parameterized.class) +public class MagicsArgsTest { + private static MagicsArgs args(Consumer config) { + MagicsArgs.MagicsArgsBuilder builder = MagicsArgs.builder(); + config.accept(builder); + return builder.build(); + } + + private static List list(String... args) { + return Arrays.asList(args); + } + + @Parameterized.Parameters(name = "{index}: \"{0}\" with \"{1}\"") + public static Collection data() { + return Arrays.asList(new Object[][]{ + { args(b -> b.required("a")), + "value-a", + hasEntry("a", list("value-a")) }, + { args(b -> b.required("a").optional("b")), + "value-a", + allOf( + hasEntry("a", list("value-a")), + hasEntry("b", list()) + ) }, + { args(b -> b.required("a").optional("b")), + "value-a value-b", + allOf( + hasEntry("a", list("value-a")), + hasEntry("b", list("value-b")) + ) }, + { args(b -> b.required("a").optional("b").varargs("c")), + "value-a value-b", + allOf( + hasEntry("a", list("value-a")), + hasEntry("b", list("value-b")), + hasEntry("c", list()) + ) }, + { args(b -> b.required("a").optional("b").varargs("c")), + "value-a value-b value-c", + allOf( + hasEntry("a", list("value-a")), + hasEntry("b", list("value-b")), + hasEntry("c", list("value-c")) + ) }, + { args(b -> b.required("a").optional("b").varargs("c")), + "value-a value-b value-c-1 value-c-2", + allOf( + hasEntry("a", list("value-a")), + hasEntry("b", list("value-b")), + hasEntry("c", list("value-c-1", "value-c-2")) + ) }, + { args(b -> b.required("a").required("b").varargs("c")), + "value-a value-b value-c-1 value-c-2", + allOf( + hasEntry("a", list("value-a")), + hasEntry("b", list("value-b")), + hasEntry("c", list("value-c-1", "value-c-2")) + ) }, + { args(b -> b.optional("a")), "", hasEntry("a", list()) }, + { args(b -> b.optional("a").varargs("b")), + "", + allOf( + hasEntry("a", list()), + hasEntry("b", list()) + ) }, + { args(b -> b.optional("a").varargs("b")), + "value-a", + allOf( + hasEntry("a", list("value-a")), + hasEntry("b", list()) + ) }, + { args(b -> b.optional("a").varargs("b")), + "value-a", allOf( + hasEntry("a", list("value-a")), + hasEntry("b", list()) + ) }, + { args(b -> b.varargs("a")), + "", + hasEntry("a", list()) }, + { args(b -> b.varargs("a")), + "value-a", + hasEntry("a", list("value-a")) }, + { args(b -> b.required("a").optional("a")), + "value-a extra-a", + hasEntry("a", list("value-a", "extra-a")) }, + { args(b -> b.required("a").optional("a")), + "value-a", + hasEntry("a", list("value-a")) }, + { args(b -> b.required("a").varargs("a")), + "value-a extra-a extra-a-2", + hasEntry("a", list("value-a", "extra-a", "extra-a-2")) }, + + // FLAGS + { args(b -> {}), "-f", hasEntry("f", list("")) }, + { args(b -> {}), "-fff", hasEntry("f", list("", "", "")) }, + { args(b -> {}), "-fg -g", allOf( + hasEntry("f", list("")), + hasEntry("g", list("", "")) + ) }, + { args(b -> b.flag("test", 'f')), "", hasEntry("test", list()) }, + { args(b -> b.flag("verbose", 'v', "true")), + "-v", + hasEntry("verbose", list("true")) }, + + // KEYWORDS + { args(b -> {}), "--f=10", hasEntry("f", list("10")) }, + { args(b -> {}), "--f=10 --f=11", hasEntry("f", list("10", "11")) }, + { args(b -> {}), "--f 10 --f=11 --f 12", hasEntry("f", list("10", "11", "12")) }, + { args(b -> b.keyword("test")), "--test=10 --test 11 --test=12", hasEntry("test", list("10", "11", "12")) }, + { args(b -> b.keyword("test", MagicsArgs.KeywordSpec.REPLACE)), + "--test=10 --test 11 --test=12", + hasEntry("test", list("12")) }, + { args(b -> b.keyword("test")), "", hasEntry("test", list()) }, + + // FLAGS and KEYWORDS + { args(b -> b.flag("log-level", 'v', "100").keyword("log-level")), + "-v --log-level=200 --log-level 300", + hasEntry("log-level", list("100", "200", "300")) }, + + // POSITIONALS and FLAGS and KEYWORDS + { args(b -> b.required("a").optional("b").flag("log-level", 'v', "100").keyword("log-level")), + "-v value-a --log-level=200 value-b --log-level 300", + allOf( + hasEntry("log-level", list("100", "200", "300")), + hasEntry("a", list("value-a")), + hasEntry("b", list("value-b")) + ) }, + + // Exceptions + { args(b -> b.required("a")), "", null }, + { args(b -> b.required("a")), "value-a extra-a", null }, + { args(b -> b.optional("a")), "value-a extra-a", null }, + { args(b -> b.onlyKnownKeywords()), "--unknown=val", null }, + { args(b -> b.onlyKnownKeywords()), "--unknown val", null }, + { args(b -> b.onlyKnownFlags()), "-idk", null }, + { args(b -> b.flag("test", 'i').onlyKnownFlags()), "-idk", null }, + { args(b -> b.keyword("a", MagicsArgs.KeywordSpec.ONCE)), "--a a --a not-ok...", null }, + + // Strange + { args(b -> b.keyword("a")), + "\"--a=value with spaces\"", + hasEntry("a", list("value with spaces")) }, + { args(b -> b.keyword("a")), + "--a=\"value with spaces\"", + hasEntry("a", list("value with spaces")) }, + { args(b -> b.keyword("a")), + "--a \"value with spaces\"", + hasEntry("a", list("value with spaces")) }, + }); + } + + @Rule + public final ExpectedException exception = ExpectedException.none(); + + private MagicsArgs schema; + private String args; + private Matcher>> test; + + public MagicsArgsTest(MagicsArgs schema, String args, Matcher>> test) { + this.schema = schema; + this.args = args; + this.test = test; + } + + @Test + public void test() { + List rawArgs = MagicParserTest.split(this.args); + if (this.test == null) + exception.expect(MagicArgsParseException.class); + + Map> args = this.schema.parse(rawArgs); + + if (this.test != null) + assertThat(args, this.test); + } +} \ No newline at end of file diff --git a/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/magic/registry/MagicsTest.java b/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/magic/registry/MagicsTest.java new file mode 100644 index 0000000..8065d9f --- /dev/null +++ b/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/magic/registry/MagicsTest.java @@ -0,0 +1,283 @@ +package io.github.spencerpark.jupyter.kernel.magic.registry; + +import org.junit.Before; +import org.junit.Test; + +import java.util.*; + +import static org.junit.Assert.assertEquals; +import static org.junit.Assert.fail; + +public class MagicsTest { + private Magics magics; + + @Before + public void setUp() { + magics = new Magics(); + } + + @Test + public void lineMagic() throws Exception { + magics.registerLineMagic("test", args -> args); + + List args = Arrays.asList("arg1", "arg2"); + List out = magics.applyLineMagic("test", args); + + assertEquals(args, out); + } + + @Test + public void cellMagic() throws Exception { + magics.registerCellMagic("test", (args, body) -> { + List out = new LinkedList<>(); + out.addAll(args); + out.add(body); + return out; + }); + + List args = Arrays.asList("arg1", "arg2"); + String body = "body"; + List out = magics.applyCellMagic("test", args, body); + + List expected = new LinkedList<>(); + expected.addAll(args); + expected.add(body); + + assertEquals(expected, out); + } + + @Test + public void lineCellMagic() throws Exception { + class Magic implements LineMagicFunction>, CellMagicFunction> { + @Override + public List execute(List args, String body) throws Exception { + List out = new LinkedList<>(); + out.addAll(args); + out.add(body); + return out; + } + + @Override + public List execute(List args) throws Exception { + return args; + } + } + + magics.registerLineCellMagic("test", new Magic()); + + List args = Arrays.asList("arg1", "arg2"); + String body = "body"; + + List lineOut = magics.applyLineMagic("test", args); + List cellOut = magics.applyCellMagic("test", args, body); + + List expectedCell = new LinkedList<>(); + expectedCell.addAll(args); + expectedCell.add(body); + + assertEquals(args, lineOut); + assertEquals(expectedCell, cellOut); + } + + @Test + public void reflectionLineMagics() throws Exception { + class Magic { + @LineMagic + public void list(List args) { + } + + @LineMagic + public void iterable(Iterable args) { + } + + @LineMagic("named") + public void unusedName(List args) { + } + + @LineMagic + public int returnInt(List args) { + return args.size(); + } + } + + magics.registerMagics(new Magic()); + + List args = Arrays.asList("arg1", "arg2"); + + magics.applyLineMagic("list", args); + magics.applyLineMagic("iterable", args); + magics.applyLineMagic("named", args); + assertEquals((Integer) 2, magics.applyLineMagic("returnInt", args)); + + try { + magics.applyLineMagic("unusedName", args); + fail("named magic was also registered under the method name"); + } catch (UndefinedMagicException ignored) { + } + } + + @Test(expected = IllegalArgumentException.class) + public void badReflectionLineMagicsType() { + class BadMagic { + @LineMagic + public void set(Set args) { + } + } + + magics.registerMagics(new BadMagic()); + } + + @Test(expected = IllegalArgumentException.class) + public void badReflectionLineMagicsTypeParam() { + class BadMagic { + @LineMagic + public void intList(List args) { + } + } + + magics.registerMagics(new BadMagic()); + } + + @Test + public void reflectionCellMagics() throws Exception { + class Magic { + @CellMagic + public void list(List args, String body) { + } + + @CellMagic + public void iterable(Iterable args, String body) { + } + + @CellMagic("named") + public void unusedName(List args, String body) { + } + + @CellMagic + public int returnInt(List args, String body) { + return args.size(); + } + } + + magics.registerMagics(new Magic()); + + List args = Arrays.asList("arg1", "arg2"); + String body = "body"; + + magics.applyCellMagic("list", args, body); + magics.applyCellMagic("iterable", args, body); + magics.applyCellMagic("named", args, body); + assertEquals((Integer) 2, magics.applyCellMagic("returnInt", args, body)); + + try { + magics.applyCellMagic("unusedName", args, body); + fail("named magic was also registered under the method name"); + } catch (UndefinedMagicException ignored) { + } + } + + @Test(expected = IllegalArgumentException.class) + public void badReflectionCellMagicsType() { + class BadMagic { + @LineMagic + public void set(Set args, String body) { + } + } + + magics.registerMagics(new BadMagic()); + } + + @Test(expected = IllegalArgumentException.class) + public void badReflectionCellMagicsTypeParam() { + class BadMagic { + @LineMagic + public void intList(List args, String body) { + } + } + + magics.registerMagics(new BadMagic()); + } + + @Test(expected = IllegalArgumentException.class) + public void badReflectionCellMagicsBodyTypeParam() { + class BadMagic { + @LineMagic + public void body(List args, Character body) { + } + } + + magics.registerMagics(new BadMagic()); + } + + @Test + public void reflectionLineCellMagics() throws Exception { + class Magic { + @LineMagic + @CellMagic + public void list(List args, String body) { + } + + @LineMagic + @CellMagic + public void iterable(Iterable args, String body) { + } + + @LineMagic("lineNamed") + @CellMagic("cellNamed") + public void unusedName(List args, String body) { + } + + @LineMagic + @CellMagic + public int returnInt(List args, String body) { + return args.size() + (body == null ? 1 : 2); + } + } + + magics.registerMagics(new Magic()); + + List args = Arrays.asList("arg1", "arg2"); + String body = "body"; + + magics.applyLineMagic("list", args); + magics.applyLineMagic("iterable", args); + magics.applyLineMagic("lineNamed", args); + assertEquals((Integer) 3, magics.applyLineMagic("returnInt", args)); + + magics.applyCellMagic("list", args, body); + magics.applyCellMagic("iterable", args, body); + magics.applyCellMagic("cellNamed", args, body); + assertEquals((Integer) 4, magics.applyCellMagic("returnInt", args, body)); + + try { + magics.applyCellMagic("unusedName", args, body); + fail("named magic was also registered under the method name"); + } catch (UndefinedMagicException ignored) { + } + } + + @Test + public void statefulMagic() throws Exception { + class Magic { + private int i = 0; + + @LineMagic + public int getAndIncrement() { + return i++; + } + } + + magics.registerMagics(new Magic()); + + for (int i = 0; i < 3; i++) + assertEquals((Integer) i, magics.applyLineMagic("getAndIncrement", Collections.emptyList())); + } + + @Test + public void staticMagic() throws Exception { + magics.registerMagics(StaticMagics.class); + + assertEquals((Integer) 0, magics.applyLineMagic("staticMagic", Collections.emptyList())); + assertEquals("body", magics.applyCellMagic("staticMagic", Collections.emptyList(), "body")); + } +} \ No newline at end of file diff --git a/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/magic/registry/StaticMagics.java b/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/magic/registry/StaticMagics.java new file mode 100644 index 0000000..7049d68 --- /dev/null +++ b/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/magic/registry/StaticMagics.java @@ -0,0 +1,15 @@ +package io.github.spencerpark.jupyter.kernel.magic.registry; + +import java.util.List; + +public class StaticMagics { + @LineMagic + public static int staticMagic(List args) { + return args.size(); + } + + @CellMagic("staticMagic") + public static String staticCellMagic(List args, String body) { + return body; + } +} diff --git a/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/util/GlobFinderTest.java b/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/util/GlobFinderTest.java new file mode 100644 index 0000000..4eea019 --- /dev/null +++ b/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/util/GlobFinderTest.java @@ -0,0 +1,215 @@ +package io.github.spencerpark.jupyter.kernel.util; + +import com.google.common.jimfs.Configuration; +import com.google.common.jimfs.Jimfs; +import org.junit.After; +import org.junit.Before; +import org.junit.Test; +import org.junit.runner.RunWith; +import org.junit.runners.Parameterized; + +import java.nio.file.FileAlreadyExistsException; +import java.nio.file.FileSystem; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.*; +import java.util.function.Function; +import java.util.function.Predicate; +import java.util.stream.Collectors; +import java.util.stream.Stream; +import java.util.stream.StreamSupport; + +import static org.junit.Assert.assertEquals; + +@RunWith(Parameterized.class) +public class GlobFinderTest { + private static final Configuration WIN_FS = Configuration.windows().toBuilder().setWorkingDirectory("C:/dir-a").build(); + private static final Configuration UNIX_FS = Configuration.unix().toBuilder().setWorkingDirectory("/dir-a").build(); + private static final Configuration OSX_FS = Configuration.osX().toBuilder().setWorkingDirectory("/dir-a").build(); + + private static final Set TEST_FILES_ALL = setOf("a.txt", "b.txt", "c.txt", "a.pdf", "b.c.pdf", "abc.svg"); + private static final Set TEST_DIRS_ALL = setOf("dir-a", "dir-b", "dir.c"); + + private static Set allFilesMapped(Function mapper) { + return TEST_FILES_ALL + .stream() + .map(mapper) + .collect(Collectors.toSet()); + } + + private static Set allFilesFilterMapped(Predicate filter, Function mapper) { + return TEST_FILES_ALL + .stream() + .filter(filter) + .map(mapper) + .collect(Collectors.toSet()); + } + + private static Set allDirsMapped(Function mapper) { + return TEST_DIRS_ALL + .stream() + .map(mapper) + .collect(Collectors.toSet()); + } + + private static Set allDirsFlatMapped(Function> mapper) { + return TEST_DIRS_ALL + .stream() + .map(mapper) + .flatMap(Set::stream) + .collect(Collectors.toSet()); + } + + private static Set allFilesAndDirsMapped(Function mapper) { + return Stream.concat(TEST_FILES_ALL.stream(), TEST_DIRS_ALL.stream()) + .map(mapper) + .collect(Collectors.toSet()); + } + + private static Set allFilesAndDirsFilterMapped(Predicate filter, Function mapper) { + return Stream.concat(TEST_FILES_ALL.stream(), TEST_DIRS_ALL.stream()) + .filter(filter) + .map(mapper) + .collect(Collectors.toSet()); + } + + private static Set setOf(String... files) { + return Arrays.stream(files).collect(Collectors.toSet()); + } + + @Parameterized.Parameters(name = "{index} :: {1}") + public static Collection data() { + return Arrays.asList(new Object[][]{ + { WIN_FS, "C:/*", allFilesMapped(s -> "C:/" + s), allFilesAndDirsMapped(s -> "C:/" + s) }, + { UNIX_FS, "/*", allFilesMapped(s -> "/" + s), allFilesAndDirsMapped(s -> "/" + s) }, + { OSX_FS, "/*", allFilesMapped(s -> "/" + s), allFilesAndDirsMapped(s -> "/" + s) }, + + // Implicit * appended with trailing / in file mode but not path mode. + { WIN_FS, "C:/*/", allDirsFlatMapped(d -> allFilesMapped(s -> "C:/" + d + "/" + s)), allFilesAndDirsMapped(s -> "C:/" + s) }, + { UNIX_FS, "/*/", allDirsFlatMapped(d -> allFilesMapped(s -> "/" + d + "/" + s)), allFilesAndDirsMapped(s -> "/" + s) }, + { OSX_FS, "/*/", allDirsFlatMapped(d -> allFilesMapped(s -> "/" + d + "/" + s)), allFilesAndDirsMapped(s -> "/" + s) }, + + { WIN_FS, "C:/c.txt", setOf("C:/c.txt"), setOf("C:/c.txt") }, + { UNIX_FS, "/c.txt", setOf("/c.txt"), setOf("/c.txt") }, + { OSX_FS, "/c.txt", setOf("/c.txt"), setOf("/c.txt") }, + + { WIN_FS, "C:/*/c.txt", allDirsMapped(d -> "C:/" + d + "/c.txt"), allDirsMapped(d -> "C:/" + d + "/c.txt") }, + { UNIX_FS, "/*/c.txt", allDirsMapped(d -> "/" + d + "/c.txt"), allDirsMapped(d -> "/" + d + "/c.txt") }, + { OSX_FS, "/*/c.txt", allDirsMapped(d -> "/" + d + "/c.txt"), allDirsMapped(d -> "/" + d + "/c.txt") }, + + { WIN_FS, "C:/dir-b/*.txt", allFilesFilterMapped(f -> f.endsWith(".txt"), f -> "C:/dir-b/" + f), allFilesFilterMapped(f -> f.endsWith(".txt"), f -> "C:/dir-b/" + f) }, + { UNIX_FS, "/dir-b/*.txt", allFilesFilterMapped(f -> f.endsWith(".txt"), f -> "/dir-b/" + f), allFilesFilterMapped(f -> f.endsWith(".txt"), f -> "/dir-b/" + f) }, + { OSX_FS, "/dir-b/*.txt", allFilesFilterMapped(f -> f.endsWith(".txt"), f -> "/dir-b/" + f), allFilesFilterMapped(f -> f.endsWith(".txt"), f -> "/dir-b/" + f) }, + + { WIN_FS, "*.pdf", allFilesFilterMapped(f -> f.endsWith(".pdf"), f -> "./" + f), allFilesFilterMapped(f -> f.endsWith(".pdf"), f -> "./" + f) }, + { UNIX_FS, "*.pdf", allFilesFilterMapped(f -> f.endsWith(".pdf"), f -> "./" + f), allFilesFilterMapped(f -> f.endsWith(".pdf"), f -> "./" + f) }, + { OSX_FS, "*.pdf", allFilesFilterMapped(f -> f.endsWith(".pdf"), f -> "./" + f), allFilesFilterMapped(f -> f.endsWith(".pdf"), f -> "./" + f) }, + + { WIN_FS, "*/dir.c/*.svg", allDirsFlatMapped(d -> allFilesFilterMapped(f -> f.endsWith(".svg"), f -> "./" + d + "/dir.c/" + f)), allDirsFlatMapped(d -> allFilesFilterMapped(f -> f.endsWith(".svg"), f -> "./" + d + "/dir.c/" + f)) }, + { UNIX_FS, "*/dir.c/*.svg", allDirsFlatMapped(d -> allFilesFilterMapped(f -> f.endsWith(".svg"), f -> "./" + d + "/dir.c/" + f)), allDirsFlatMapped(d -> allFilesFilterMapped(f -> f.endsWith(".svg"), f -> "./" + d + "/dir.c/" + f)) }, + { OSX_FS, "*/dir.c/*.svg", allDirsFlatMapped(d -> allFilesFilterMapped(f -> f.endsWith(".svg"), f -> "./" + d + "/dir.c/" + f)), allDirsFlatMapped(d -> allFilesFilterMapped(f -> f.endsWith(".svg"), f -> "./" + d + "/dir.c/" + f)) }, + + { WIN_FS, "?.pdf", setOf("C:/dir-a/a.pdf"), setOf("C:/dir-a/a.pdf") }, + { UNIX_FS, "?.pdf", setOf("/dir-a/a.pdf"), setOf("/dir-a/a.pdf") }, + { OSX_FS, "?.pdf", setOf("/dir-a/a.pdf"), setOf("/dir-a/a.pdf") }, + + { WIN_FS, "C:/dir-?/?.pdf", setOf("C:/dir-a/a.pdf", "C:/dir-b/a.pdf"), setOf("C:/dir-a/a.pdf", "C:/dir-b/a.pdf") }, + { UNIX_FS, "/dir-?/?.pdf", setOf("/dir-a/a.pdf", "/dir-b/a.pdf"), setOf("/dir-a/a.pdf", "/dir-b/a.pdf") }, + { OSX_FS, "/dir-?/?.pdf", setOf("/dir-a/a.pdf", "/dir-b/a.pdf"), setOf("/dir-a/a.pdf", "/dir-b/a.pdf") }, + + { WIN_FS, "C:/dir.c/abc.svg", setOf("C:/dir.c/abc.svg"), setOf("C:/dir.c/abc.svg") }, + { UNIX_FS, "/dir.c/abc.svg", setOf("/dir.c/abc.svg"), setOf("/dir.c/abc.svg") }, + { OSX_FS, "/dir.c/abc.svg", setOf("/dir.c/abc.svg"), setOf("/dir.c/abc.svg") }, + + { WIN_FS, "C:/bad", Collections.emptySet(), Collections.emptySet() }, + { UNIX_FS, "/bad", Collections.emptySet(), Collections.emptySet() }, + { OSX_FS, "/bad", Collections.emptySet(), Collections.emptySet() }, + + { WIN_FS, "C:/*/*/*/*/*/*/*", Collections.emptySet(), Collections.emptySet() }, + { UNIX_FS, "/*/*/*/*/*/*/*", Collections.emptySet(), Collections.emptySet() }, + { OSX_FS, "/*/*/*/*/*/*/*", Collections.emptySet(), Collections.emptySet() }, + + { WIN_FS, "C:/dir-?/", allDirsFlatMapped(d -> !d.startsWith("dir-") ? Collections.emptySet() : allFilesMapped(f -> "C:/" + d + "/" + f)), setOf("C:/dir-a", "C:/dir-b") }, + { UNIX_FS, "/dir-?/", allDirsFlatMapped(d -> !d.startsWith("dir-") ? Collections.emptySet() : allFilesMapped(f -> "/" + d + "/" + f)), setOf("/dir-a", "/dir-b") }, + { OSX_FS, "/dir-?/", allDirsFlatMapped(d -> !d.startsWith("dir-") ? Collections.emptySet() : allFilesMapped(f -> "/" + d + "/" + f)), setOf("/dir-a", "/dir-b") }, + + { WIN_FS, "C:/*c*", allFilesFilterMapped(f -> f.contains("c"), f -> "C:/" + f), allFilesAndDirsFilterMapped(f -> f.contains("c"), f -> "C:/" + f) }, + { UNIX_FS, "/*c*", allFilesFilterMapped(f -> f.contains("c"), f -> "/" + f), allFilesAndDirsFilterMapped(f -> f.contains("c"), f -> "/" + f) }, + { OSX_FS, "/*c*", allFilesFilterMapped(f -> f.contains("c"), f -> "/" + f), allFilesAndDirsFilterMapped(f -> f.contains("c"), f -> "/" + f) }, + }); + } + + private final Configuration fsConfig; + private final String glob; + private final Set files; + private final Set paths; + + private FileSystem fs; + + public GlobFinderTest(Configuration fsConfig, String glob, Set files, Set paths) { + this.fsConfig = fsConfig; + this.glob = glob; + this.files = files; + this.paths = paths; + } + + @Before + public void setUp() throws Exception { + this.fs = Jimfs.newFileSystem(this.fsConfig); + + List roots = StreamSupport.stream(this.fs.getRootDirectories().spliterator(), false).collect(Collectors.toList()); + roots.add(this.fs.getPath(".")); + + for (Path dir1 : roots) { + for (String dir2 : new String[]{ ".", "dir-a", "dir-b", "dir.c" }) { + for (String dir3 : new String[]{ ".", "dir-a", "dir-b", "dir.c" }) { + for (String dir4 : new String[]{ ".", "dir-a", "dir-b", "dir.c" }) { + Files.createDirectories(this.fs.getPath(dir1.toString(), dir2, dir3, dir4)); + + for (String file : TEST_FILES_ALL) { + try { + Files.createFile(this.fs.getPath(dir1.toString(), dir2, dir3, dir4, file)); + } catch (FileAlreadyExistsException ignore) {} + } + } + } + } + } + } + + @After + public void tearDown() throws Exception { + this.fs = null; + } + + @Test + public void test() throws Exception { + GlobFinder finder = new GlobFinder(this.fs, this.glob); + + assertEquals( + String.format("Glob files: '%s'", this.glob), + this.files.stream() + .map(this.fs::getPath) + .map(Path::normalize) + .map(Path::toAbsolutePath) + .collect(Collectors.toSet()), + StreamSupport.stream(finder.computeMatchingFiles().spliterator(), false) + .map(Path::normalize) + .map(Path::toAbsolutePath) + .collect(Collectors.toSet()) + ); + + assertEquals( + String.format("Glob paths: '%s'", this.glob), + this.paths.stream() + .map(this.fs::getPath) + .map(Path::normalize) + .map(Path::toAbsolutePath) + .collect(Collectors.toSet()), + StreamSupport.stream(finder.computeMatchingPaths().spliterator(), false) + .map(Path::normalize) + .map(Path::toAbsolutePath) + .collect(Collectors.toSet()) + ); + } +} \ No newline at end of file diff --git a/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/util/InheritanceIteratorTest.java b/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/util/InheritanceIteratorTest.java new file mode 100644 index 0000000..54b7b8f --- /dev/null +++ b/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/util/InheritanceIteratorTest.java @@ -0,0 +1,83 @@ +package io.github.spencerpark.jupyter.kernel.util; + +import org.junit.Test; +import org.junit.runner.RunWith; +import org.junit.runners.Parameterized; + +import java.util.*; + +import static org.junit.Assert.assertEquals; + +@RunWith(Parameterized.class) +public class InheritanceIteratorTest { + interface I {} + + interface J extends I {} + + interface K extends J, I {} + + interface L extends J, K {} + + class A {} + + class B extends A {} + + class C extends B {} + + class D {} + + class E extends D implements L {} + + class F extends E implements J, K {} + + interface M {} + + interface N {} + + interface O extends N {} + + interface P extends N, M {} + + interface Q extends P, M {} + + class G implements N, O {} + + class H implements Q {} + + @Parameterized.Parameters + public static Collection data() { + return Arrays.asList(new Object[][]{ + { A.class, Arrays.asList(A.class, Object.class) }, + { B.class, Arrays.asList(B.class, A.class, Object.class) }, + { C.class, Arrays.asList(C.class, B.class, A.class, Object.class) }, + { int.class, Collections.singletonList(int.class) }, + { D.class, Arrays.asList(D.class, Object.class) }, + { E.class, Arrays.asList(E.class, L.class, J.class, K.class, I.class, D.class, Object.class) }, + { F.class, Arrays.asList(F.class, J.class, K.class, I.class, E.class, L.class, D.class, Object.class) }, + { G.class, Arrays.asList(G.class, N.class, O.class, Object.class) }, + { H.class, Arrays.asList(H.class, Q.class, P.class, M.class, N.class, Object.class) }, + }); + } + + private final Class root; + private final List expectedOrder; + + public InheritanceIteratorTest(Class root, List expectedOrder) { + this.root = root; + this.expectedOrder = expectedOrder; + } + + private List collectIteration(Class root) { + List data = new LinkedList<>(); + InheritanceIterator it = new InheritanceIterator(root); + while (it.hasNext()) data.add(it.next()); + return data; + } + + @Test + public void test() { + List actual = collectIteration(this.root); + + assertEquals(this.expectedOrder, actual); + } +} \ No newline at end of file diff --git a/build.gradle b/build.gradle index 6e23d60..9f8a5d5 100644 --- a/build.gradle +++ b/build.gradle @@ -31,7 +31,6 @@ repositories { // Dependency versions def versions = [ - jupyterKernel: '2.3.0', gson: '2.10.1', mavenResolver: '1.8.2', mavenProvider: '3.8.6', @@ -40,10 +39,16 @@ def versions = [ lombok: '1.18.48' ] -dependencies { - implementation("io.github.spencerpark:jupyter-jvm-basekernel:${versions.jupyterKernel}") { - exclude group: 'com.google.code.gson', module: 'gson' +configurations.all { + resolutionStrategy { + force 'com.google.guava:guava:33.5.0-jre' + force 'com.google.guava:failureaccess:1.0.3' + force 'com.google.errorprone:error_prone_annotations:2.41.0' } +} + +dependencies { + implementation project(':basekernel') implementation "com.google.code.gson:gson:${versions.gson}" // Maven resolver dependencies @@ -65,7 +70,9 @@ dependencies { implementation 'com.github.javaparser:javaparser-symbol-solver-core:3.25.8' // PlantUML for diagrams //implementation 'net.sourceforge.plantuml:plantuml:1.2024.1' - implementation 'net.sourceforge.plantuml:plantuml:1.2026.0' + implementation('net.sourceforge.plantuml:plantuml:1.2026.0') { + transitive = false + } // ClassGraph for classpath scanning implementation 'io.github.classgraph:classgraph:4.8.168' @@ -98,7 +105,15 @@ processResources { // Shadow JAR configuration shadowJar { archiveClassifier.set('all') + duplicatesStrategy = DuplicatesStrategy.EXCLUDE mergeServiceFiles() + exclude 'module-info.class' + exclude 'META-INF/versions/*/module-info.class' + exclude 'META-INF/MANIFEST.MF' + exclude 'META-INF/*.SF' + exclude 'META-INF/*.DSA' + exclude 'META-INF/*.RSA' + exclude 'META-INF/INDEX.LIST' manifest { attributes( 'Main-Class': 'io.github.spencerpark.ijava.IJava', diff --git a/settings.gradle b/settings.gradle index be83d81..a78cda5 100644 --- a/settings.gradle +++ b/settings.gradle @@ -4,6 +4,7 @@ // Project identification rootProject.name = 'IJava' +include 'basekernel' // Enable build cache buildCache { From 4717f6e4525a361a408788da1c817b23edae3109 Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Wed, 2 Sep 2026 17:55:05 +0200 Subject: [PATCH 35/49] chore(release): prepare v1.4.6 release --- .github/workflows/build-release.yml | 14 ++++++-------- .gitignore | 1 + UPGRADE.md | 23 +++++++++++++++++------ build.gradle | 2 +- src/main/resources/install.py | 6 +++--- 5 files changed, 28 insertions(+), 18 deletions(-) diff --git a/.github/workflows/build-release.yml b/.github/workflows/build-release.yml index 4d03352..0314a73 100644 --- a/.github/workflows/build-release.yml +++ b/.github/workflows/build-release.yml @@ -63,7 +63,7 @@ jobs: - name: Build package run: | chmod +x ./gradlew - ./gradlew --no-daemon -Pversion=${{ steps.set-tag.outputs.tag }} clean packDist + ./gradlew --no-daemon -Pversion=${{ steps.set-tag.outputs.tag }} clean build shadowJar packDist - name: Prepare artifact and checksum run: | @@ -110,16 +110,14 @@ jobs: JAR=$(find smoke -name "*.jar" | head -n1) python3 -m venv venv - ./venv/bin/pip install jupyter nbconvert jupyter-client + ./venv/bin/pip install jupyter-client nbconvert - # Simplified kernel install - mkdir -p kernel_meta - echo "{\"argv\":[\"java\",\"-jar\",\"$(realpath $JAR)\",\"{connection_file}\"],\"display_name\":\"Java\",\"language\":\"java\"}" > kernel_meta/kernel.json - ./venv/bin/jupyter kernelspec install --sys-prefix --name ijavatest --replace ./kernel_meta + # Install through the release installer + ./venv/bin/python smoke/install.py --sys-prefix --replace # Create and execute test notebook - echo '{"cells":[{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["System.out.println(\"Hello\");"]}],"metadata":{},"nbformat":4,"nbformat_minor":4}' > test.ipynb - ./venv/bin/jupyter nbconvert --to notebook --execute test.ipynb --ExecutePreprocessor.kernel_name=ijavatest + echo '{"cells":[{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["System.out.println(\"Hello from IJava\");","42"]}],"metadata":{},"nbformat":4,"nbformat_minor":4}' > test.ipynb + ./venv/bin/python -m nbconvert --to notebook --execute test.ipynb --ExecutePreprocessor.kernel_name=java publish: name: Create Release diff --git a/.gitignore b/.gitignore index b793267..21e4b3b 100644 --- a/.gitignore +++ b/.gitignore @@ -20,6 +20,7 @@ tests/ .envrc .use-google-ai +.opencode/ # Eclipse diff --git a/UPGRADE.md b/UPGRADE.md index 5715a7a..1ba9bec 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -1,9 +1,20 @@ -Updated: +# IJava 1.4.6 -1. fix `CompilerMagics.compile` auto generated package path error -2. remain `JupyterIO.jupyterXXX.env`, keep thread stdout rewrite to jupyter +## Highlights +- Vendored `jupyter-jvm-basekernel` into the repository as a Gradle module for a reproducible, self-contained build. +- Upgraded the build to JDK 25 and Gradle 9.7.1. +- Hardened the Shadow JAR packaging pipeline for duplicate classes, service files, and kernel metadata. +- Fixed kernel installation so `--replace` is honored and installed kernel paths are handled robustly. +- Improved the release smoke test to install through the real `install.py` path. -TODO: +## Upgrade instructions +1. Download `IJava-1.4.6.zip`. +2. Unzip it. +3. Install the kernel with the same Python environment used by Jupyter: + - `python install.py --user --replace` + - or `python install.py --sys-prefix --replace` +4. Restart Jupyter. -1. reload `CompilerMagics.compile` class? DirectExecutionControl > DefaultLoaderDelegate -2. thread stdout JupyterIO.retractEnv; BaseKernel.replaceOutputStreams +## Requirements +- Java JDK 25. +- A Jupyter-compatible environment with `jupyter_client` available for installation. diff --git a/build.gradle b/build.gradle index 9f8a5d5..f46daa5 100644 --- a/build.gradle +++ b/build.gradle @@ -5,7 +5,7 @@ plugins { group = 'io.github.spencerpark' // Allow overriding version from command line via `-Pversion=...` -version = (gradle.startParameter.projectProperties.get('version') ?: '1.4.5').toString() +version = (gradle.startParameter.projectProperties.get('version') ?: '1.4.6').toString() // Java configuration java { diff --git a/src/main/resources/install.py b/src/main/resources/install.py index 67391f8..37c86b9 100644 --- a/src/main/resources/install.py +++ b/src/main/resources/install.py @@ -160,13 +160,13 @@ def __call__(self, parser, namespace, value, option_string=None): setattr(args, "env", {}) # Install the kernel - install_dest = KernelSpecManager().install_kernel_spec( + install_dest = str(KernelSpecManager().install_kernel_spec( os.path.join(os.path.dirname(os.path.abspath(__file__)), 'java'), kernel_name='java', user=args.user, prefix=sys.prefix if args.sys_prefix else args.prefix, - ## replace=args.replace - ) + replace=args.replace + )) # Connect the self referencing token left in the kernel.json to point to it's install location. From 857050dbd9737f6f64c081362680bc2238e7f4ba Mon Sep 17 00:00:00 2001 From: Emmanuel Bruno Date: Wed, 2 Sep 2026 20:24:18 +0200 Subject: [PATCH 36/49] fix: address Copilot review findings - harden URL display HTML escaping - parse publish status execution_state safely - bound PathResolver fallback search - guard PlantUML null inputs - clamp TimeIt parameters - skip shell tests when /bin/sh is unavailable --- .../jupyter/kernel/display/common/Url.java | 53 ++++++++++++----- .../adapters/PublishStatusAdapter.java | 22 +++++-- .../kernel/display/common/UrlTest.java | 58 +++++++++++++++++++ .../adapters/PublishStatusAdapterTest.java | 52 +++++++++++++++++ docs/sample_java/com/example/Product.java | 2 +- .../IJavaExecutionControlProvider.java | 5 +- .../ijava/magics/JavaPlantUMLMagics.java | 19 +++--- .../ijava/magics/PathResolver.java | 35 +++++++++-- .../ijava/magics/TimeItMagics.java | 4 +- .../ijava/magics/ShellMagicsTest.java | 5 ++ 10 files changed, 218 insertions(+), 37 deletions(-) create mode 100644 basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/display/common/UrlTest.java create mode 100644 basekernel/src/test/java/io/github/spencerpark/jupyter/messages/adapters/PublishStatusAdapterTest.java diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/common/Url.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/common/Url.java index 3e3a9d6..9fac1bd 100644 --- a/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/common/Url.java +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/kernel/display/common/Url.java @@ -6,10 +6,10 @@ import io.github.spencerpark.jupyter.kernel.display.mime.MIMEType; import java.io.IOException; -import java.io.UnsupportedEncodingException; -import java.net.URLEncoder; import java.util.Collections; +import java.util.Locale; import java.util.Map; +import java.util.Set; public class Url { public static String EMBED_KEY = "embed"; @@ -37,28 +37,51 @@ public static void renderUrl(java.net.URL url, RenderContext context) { } else { context.renderIfRequested(MIMEType.TEXT_HTML, () -> { String tag = context.getParameterAsString(HTML_TAG_KEY, "a"); - String srcAttr = context.getParameterAsString(HTML_SRC_ATTR_KEY, "src"); + String srcAttr = context.getParameterAsString(HTML_SRC_ATTR_KEY, "href"); return renderHTML(tag, srcAttr, url, Collections.emptyMap()); }); } } - private static String renderHTML(String tag, String srcAttr, java.net.URL url, Map attrs) { - String encodedUrl; - try { - encodedUrl = URLEncoder.encode(url.toExternalForm(), "UTF-8"); - } catch (UnsupportedEncodingException e) { - throw new RuntimeException(e); // Should never happen... - } + private static final Set HTML_VOID_ELEMENTS = Set.of("area", "base", "br", "col", "embed", "hr", + "img", "input", "link", "meta", "param", "source", "track", "wbr"); - //TODO add some html rendering utilities for the url and html entity encoding + private static String renderHTML(String tag, String srcAttr, java.net.URL url, Map attrs) { + String safeTag = sanitizeHtmlName(tag, "a"); + String safeSrcAttr = sanitizeHtmlName(srcAttr, "href"); + String externalForm = url.toExternalForm(); StringBuilder html = new StringBuilder("<"); - html.append(tag); - html.append(" ").append(srcAttr).append("=\"").append(encodedUrl).append('"'); + html.append(safeTag); + html.append(" ").append(safeSrcAttr).append("=\"").append(escapeHtml(externalForm)).append('"'); + if (safeTag.equals("a") && !attrs.containsKey("target")) + html.append(" target=\"_blank\""); attrs.forEach((attr, val) -> { - if (val != null) - html.append(" ").append(attr).append("=\"").append(val).append("\""); + if (val != null) { + String safeAttr = sanitizeHtmlName(attr, attr); + html.append(" ").append(safeAttr).append("=\"").append(escapeHtml(val)).append('"'); + } }); + if (HTML_VOID_ELEMENTS.contains(safeTag.toLowerCase(Locale.ROOT))) { + html.append(" />"); + } else { + html.append(">").append(escapeHtml(externalForm)).append("'); + } return html.toString(); } + + private static String sanitizeHtmlName(String value, String defaultValue) { + if (value == null || !value.matches("[A-Za-z][A-Za-z0-9-]*")) + return defaultValue; + return value; + } + + private static String escapeHtml(String value) { + if (value == null) + return ""; + return value.replace("&", "&") + .replace("<", "<") + .replace(">", ">") + .replace("\"", """) + .replace("'", "'"); + } } diff --git a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/PublishStatusAdapter.java b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/PublishStatusAdapter.java index 7e13950..6ce0377 100644 --- a/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/PublishStatusAdapter.java +++ b/basekernel/src/main/java/io/github/spencerpark/jupyter/messages/adapters/PublishStatusAdapter.java @@ -12,12 +12,22 @@ private PublishStatusAdapter() { } @Override public PublishStatus deserialize(JsonElement element, Type type, JsonDeserializationContext ctx) throws JsonParseException { - PublishStatus.State state = ctx.deserialize(element.getAsJsonObject().get("execution_result"), PublishStatus.State.class); - switch (state) { - case BUSY: return PublishStatus.BUSY; - case IDLE: return PublishStatus.IDLE; - case STARTING: return PublishStatus.STARTING; - default: return null; + if (element == null || !element.isJsonObject()) + return null; + + JsonObject object = element.getAsJsonObject(); + JsonElement stateElement = object.get("execution_state"); + if (stateElement == null || stateElement.isJsonNull()) + return null; + + PublishStatus.State state; + try { + state = ctx.deserialize(stateElement, PublishStatus.State.class); + } catch (JsonParseException | IllegalArgumentException e) { + return null; } + if (state == null) + return null; + return PublishStatus.forState(state); } } diff --git a/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/display/common/UrlTest.java b/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/display/common/UrlTest.java new file mode 100644 index 0000000..9363381 --- /dev/null +++ b/basekernel/src/test/java/io/github/spencerpark/jupyter/kernel/display/common/UrlTest.java @@ -0,0 +1,58 @@ +package io.github.spencerpark.jupyter.kernel.display.common; + +import io.github.spencerpark.jupyter.kernel.display.DisplayData; +import io.github.spencerpark.jupyter.kernel.display.Renderer; +import io.github.spencerpark.jupyter.kernel.display.mime.MIMEType; +import org.junit.Before; +import org.junit.Test; + +import java.net.MalformedURLException; +import java.net.URI; +import java.net.URL; +import java.util.Map; + +import static org.junit.Assert.assertEquals; +import static org.junit.Assert.assertNotNull; + +public class UrlTest { + + private Renderer renderer; + + @Before + public void setUp() { + renderer = new Renderer(); + Url.registerAll(renderer); + } + + @Test + public void rendersWellFormedAnchorByDefault() throws MalformedURLException { + URL url = URI.create("https://example.com/?a=1&b=2").toURL(); + DisplayData data = renderer.renderAs(url, "text/html"); + String html = (String) data.getData(MIMEType.TEXT_HTML); + assertNotNull(html); + assertEquals("https://example.com/?a=1&b=2", html); + } + + @Test + public void rendersPlainUrlAsText() throws MalformedURLException { + URL url = URI.create("https://example.com/?a=1&b=2").toURL(); + DisplayData data = renderer.renderAs(url, "text/plain"); + assertEquals("https://example.com/?a=1&b=2", data.getData(MIMEType.TEXT_PLAIN)); + } + + @Test + public void rendersCustomVoidTagWithoutClosingTag() throws MalformedURLException { + URL url = URI.create("https://example.com/image.png").toURL(); + Map params = Map.of(Url.HTML_TAG_KEY, "img", Url.HTML_SRC_ATTR_KEY, "src"); + DisplayData data = renderer.renderAs(url, params, "text/html"); + assertEquals("", (String) data.getData(MIMEType.TEXT_HTML)); + } + + @Test + public void sanitizesUnsafeHtmlNames() throws MalformedURLException { + URL url = URI.create("https://example.com/").toURL(); + Map params = Map.of(Url.HTML_TAG_KEY, "