Groovy Jupyter Kernel

A native Jupyter kernel for the Apache Groovy language. By "native" we mean the kernel is written in Groovy and handles the ZeroMQ message queues directly.

Contents

1. Installation
   a. From Source
   a. Manually
2. Docker
3. Creating a Kernel for a Groovy DSL
4. Contributing

Documentation

The Maven generated site (API docs etc.) is available here.

Installation

From Source

Building the Groovy Jupyter Kernel project requires Maven 3.x or higher.

$> git clone https://github.com/lappsgrid-incubator/jupyter-groovy-kernel.git 
$> cd jupyter-groovy-kernel
$> mvn clean package
$> ./install.sh <kernel directory>

Where <kernel directory> is a directory where the kernel jar file will be copied and can be any directory on your system.

If you do not have Maven installed you can use the mvnw (Linus/OS X) or mvnw.cmd (Windows) Maven Wrapper scripts to build the project.

$> ./mvnw clean package

Manually

Download and expand the Groovy Kernel archive and then run the install.sh script.

$> wget http://www.lappsgrid.org/downloads/jupyter-groovy-kernel-latest.tgz
$> tar xzf jupyter-groovy-kernel-latest.tgz
$> cd jupyter-groovy-kernel
$> ./install.sh <kernel directory>

Where <kernel directory> is a directory where the kernel jar file will be copied and can be any directory on your system.

Notes

By default the install.sh script will install the Jupyter kernel to the system kernel directory. This is typically /usr/local/share/juptyer on Linux/MacOS systems and %PROGRAMDATA%\jupyter\kernels on Windows systems. To install the Jupyter kernel to the User's directory you must either:

• Edit the install.script and add the --user option to the kernelspec command, or
• Edit the kernel.json file to set the argv paramater to the location of the Jupyter Groovy kernel and then run the jupyter kernelspec install command.

Docker

A Docker image containing the Groovy Kernel is available from the Docker Hub. To save notebooks outside of the Docker container you will need to mount a local directory as /home/jovyan/work inside the container.

docker run -p 8888:8888 -v /path/to/local/directory:/home/jovyan/work lappsgrid/jupyter-groovy-kernel

Please refer to the Docker Hub website for a list of the current Docker images available.

Creating a Kernel for a Groovy DSL

The short version

To create a Jupyter kernel for a Groovy DSL you will need to:

1. Add the Groovy Jupyter kernel project as a dependency.
2. Implement the GroovyContext interface to provide a CompilerConfiguration, base script, and/or MetaClass object for compiling user code.
3. Pass your GroovyContext to the GroovyKernel constructor

The long version

The Groovy kernel uses objects that implement the org.lappsgrid.jupyter.groovy.context.GroovyContext interface to configure the Groovy compiler and to obtain MetaClass instances that are attached to the compiled script objects.

interface GroovyContext {
    CompilerConfiguration getCompilerConfiguration();
    MetaClass getMetaClass(Class aClass);
}

There is also a DefaultGroovyContext class that implements both methods and returns a default CompilerConfiguration object and default ExapandoMetaClass. You can use the DefaultGroovyContext class if you only want/need to implement one of the GroovyContext methods.

To create a Jupyter kernel for a Groovy DSL implement the GroovyContext interface and pass that object to the GroovyKernel constructor.

class CustomContext extends DefaultGroovyContext {
    ...
}

class CustomJupyterKernel {
    static void main(String[] args) {
        GroovyContext context = new CustomContext()
        GroovyKernel kernel = new GroovyKernel(context)
        kernel.connectionFile = new File(args[0])
        kernel.run()
}

See the Lappsgrid Services DSL Jupyter kernel for an example of implementing a Jupyter kernel for a Groovy DSL using the Groovy Jupyter kernel.

Contributing

If you would like to contribute to the Jupyter Groovy Kernel please Fork this repository, make your changes, and then submit a pull request targeting the develop branch.