IJava

A Jupyter kernel for executing Java code. The kernel executes code via the new JShell tool. Some of the additional commands should be supported as needed 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.

Contents

• Try online
• Features
• Requirements
• Installing
  • Install pre-build binary
  • Install from source
• Configuring
  • List of options
  • Changing VM/compiler options
  • Configuring startup scripts
• Run

Try Online

Clicking on the badges 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. (See also kernel.md) 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

1. Java JDK >= 9. 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.

   1. Ensure that the

      java

      command is in the PATH and is using version 9. For example:

      bash
      > 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 [email protected] followed by your java version.
   

   If the kernel cannot start with an error along the lines of

   text
   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

   .

2. Some jupyter-like environment to use the kernel in.

   A non-exhaustive list of options:

*   [Jupyter](http://jupyter.org/install)
*   [JupyterLab](http://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html)
*   [nteract](https://nteract.io/desktop)

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

jupyter kernelspec remove java

1. Download the release from the releases tab. A prepackaged distribution will be in an artifact named

   ijava-$version.zip

   .

2. Unzip it into a temporary location. It should have at least the

   install.py

   and

   java

   folder extracted in there.

3. 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
   

4. 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.

1. Download the project. ```bash

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

2. Build and install the kernel.

   On *nix

   ./gradlew installKernel

   On windows

   gradlew installKernel

   See all available options for configuring the install path with

   gradlew -q help --task installKernel

   . Pass the

   --default

   ,

   --user

   ,

   --sys-prefix

   ,

   --prefix

   ,

   --path

   , or

   --legacy

   options to change the install location. Also use the

   --param

   flag (repeatedly) to set (or add) parameter values with the parameter names (not environment variable) specified in the configuration section below. For example

   --param classpath:/my/classpath/root

   to append to the classpath list.

Configuring

Configuring the kernel can be done via environment variables. These can be set on the system or inside the

kernel.json

python3 install.py -h

gradlew installKernel --param ...:...

List of options

| Environment variable | Parameter name | Default | Description | |----------------------|----------------|---------|-------------| |

IJAVA_COMPILER_OPTS

comp-opts

""

javac

-parameters

IJAVA_TIMEOUT

timeout

"-1"

1

TimeUnit

"30 SECONDS"

IJAVA_CLASSPATH

classpath

""

IJAVA_STARTUP_SCRIPTS_PATH

startup-scripts-path

""

.jshell

IJAVA_STARTUP_SCRIPT

startup-script

""

import my.utils;

void sleep(long time) { try {Thread.sleep(time); } catch (InterruptedException e) { throw new RuntimeException(e); }}

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

jupyter notebook

Note: users on any OS should use

/

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

--comp-opts

javac

The kernel VM parameters must currently be assigned in the

kernel.json

env

argv

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

and the

kernel.json

For example to enable assertions, set a limit on the heap size to

128m

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

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: ```java In [1]: String helloWorld = "Hello world!"

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