IJava

(JupyterLab Binder )

A Jupyter kernel for executing Java code. The kernel executes code via the new JShell tool. Some of the additional commands should be supported in the future via a syntax similar to the ipython magics.

The kernel is fully functional. Check out the list of features further down in the README. Any requests for new ones or prioritizing current requests are welcomed in the issues along with bug requests, installation help, or other questions.

If you are interested in building your own kernel that runs on the JVM check out the related project that this kernel is build on, jupyter-jvm-basekernel.

For Maven dependency resolution, the kernel is using ShrinkWrap resolvers.

Try online
Features
Requirements
Installing
- Install pre-build binary
- Install from source
Configuring
Run

Try Online

Clicking on the (JupyterLab Binder ) badge at the top (or right here) will spawn a jupyter server running this kernel. The binder base is the ijava-binder project.

Features

Currently the kernel supports

Code execution.
Autocompletion (TAB in Jupyter notebook).
Code inspection (Shift-TAB up to 4 times in Jupyter notebook).
Colored, friendly, error message displays.
Add maven dependencies at runtime (See also magics.md and Try the example ).
Display rich output (See also display.md and maven magic). Chart library in the demo photo is XChart with the sample code taken from their README. (Try the example )
eval function. Note: the signature is Object eval(String) throws Exception. This evaluates the expression (a cell) in the user scope and returns the actual evaluation result instead of a serialized one.
Configurable evaluation timeout

Requirements

Java JDK >=9. Not the JRE
1. Ensure that the java command is in the PATH and is using version 9. For example:
```
> java -version
java version "9"
Java(TM) SE Runtime Environment (build 9+181)
Java HotSpot(TM) 64-Bit Server VM (build 9+181, mixed mode)
```
2. Next ensure that java is in a location where the jdk was installed and not just the jre. Use the java --list-modules command to do this. The list should contain jdk.jshell.
  - On *nix java --list-modules | grep "jdk.jshell"
  - On windows java --list-modules | findstr "jdk.jshell"
  Both should output jdk.jshell@ followed by your java version.
If the kernel cannot start with an error along the lines of
```
Exception in thread "main" java.lang.NoClassDefFoundError: jdk/jshell/JShellException
        ...
Caused by: java.lang.ClassNotFoundException: jdk.jshell.JShellException
        ...
```
then double check that java is referring to the command for the jdk and not the jre.
Some jupyter-like environment to use the kernel in.

A non-exhaustive list of options:
- Jupyter - main option
- JupyterLab
- nteract

Installing

After meeting the requirements, the kernel can be installed locally. Any time you wish to remove a kernel you may use jupyter kernelspec remove java.

Install pre-built binary

Get the latest release of the software with no compilation needed. See Install from source for building the the latest commit.

Note: if you have an old installation or a debug one from running gradlew installKernel it is suggested that it is first removed via jupyter kernelspec remove java.

Download the release from the releases tab. A prepackaged distribution will be in an artifact named ijava-$version.zip.
Unzip it into a temporary location. It should have at least the install.py and java folder extracted in there.
Run the installer with the same python command used to install jupyter. The installer is a python script and has the same options as jupyter kernelspec install but additionally supports configuring some of the kernel properties mentioned further below in the README.
```
# Pass the -h option to see the help page
> python3 install.py -h

# Otherwise a common install command is
> python3 install.py --sys-prefix
```
Check that it installed with jupyter kernelspec list which should contain java.

Install from source

Get the latest version of the kernel but possibly run into some issues with installing. This is also the route to take if you wish to contribute to the kernel.

Download the project.

> git clone https://github.com/SpencerPark/IJava.git
> cd IJava/

Build and install the kernel.

On *nix chmod u+x gradlew && ./gradlew installKernel

On windows gradlew installKernel

Configuring

Configuring the kernel can be done via environment variables. These can be set on the system or inside the kernel.json. To find where the kernel is installed run

> jupyter kernelspec list
Available kernels:
  java           .../kernels/java
  python3        .../python35/share/jupyter/kernels/python3

and the kernel.json file will be in the given directory.

List of options

IJAVA_COMPILER_OPTS - default: "" - 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 - default: "-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 may be given following the duration number (ex "30 SECONDS").

IJAVA_CLASSPATH - default: "" - 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.

IJAVA_STARTUP_SCRIPTS_PATH - default: "" - A file path seperator delimited list of .jshell scripts to run on startup. This includes ijava-jshell-init.jshell and 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.

IJAVA_STARTUP_SCRIPT - default: "" - 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.

Simple glob syntax

Options that support this glob syntax may reference a set of files with a single path-like string. Basic glob queries are supported including:

* to match 0 or more characters up to the next path boundary /
? to match a single character
A path ending in / implicitly adds a * to match all files in the resolved directory

Any relative paths are resolved from the notebook server's working directory. For example the glob *.jar will match all jars is the directory that the jupyter notebook command was run.

Note: users on any OS should use / as a path separator.

Changing VM/compiler options

See the List of options section for all of the configuration options.

To change compiler options use the IJAVA_COMPILER_OPTS environment variable with a string of flags as if running the javac command.

The IJAVA_COMPILER_OPTS and kernel VM parameters can be assigned in the kernel.json by adding/editing a JSON dictionary at the env key and changing the argv list.

For example to enable assertions, set a limit on the heap size to 128m, and enable parameter names in reflection:

{
- "argv": [ "java", "-jar", "{connection_file}"],
+ "argv": [ "java", "-ea", "-Xmx128m", "-jar", "{connection_file}"],
  "display_name": "Java",
  "language": "java",
  "env": {
+     "IJAVA_COMPILER_OPTS" : "-parameters"
  }
}

Configuring startup scripts

See the List of options section for all of the configuration options.

To setup a startup script such as an init.jshell script, set the IJAVA_STARTUP_SCRIPTS_PATH to init.jshell in the kernel.json. This will try to execute an init.jshell script in the working directory of kernel.

If desired use an absolute path to use a global init file.

{
  "argv": [ "java", "-jar", "{connection_file}"],
  "display_name": "Java",
  "language": "java",
  "env": {
+     "IJAVA_STARTUP_SCRIPTS_PATH": "init.jshell"
  }

Run

This is where the documentation diverges, each environment has it's own way of selecting a kernel. To test from command line with Jupyter's console application run:

jupyter console --kernel=java

Then at the prompt try:

In [1]: String helloWorld = "Hello world!"

In [2]: helloWorld
Out[2]: "Hello world!"

victor-mariano-leite/IJava