Create your own plugin

This guide walks you through creating a plugin in Deephaven using Java or Groovy. Plugins written in Java or Groovy are JVM extensions that add custom functionality to the server, such as custom object types and JavaScript plugins that the server serves to the web UI.

You implement a Deephaven plugin with the Java plugin API in the io.deephaven.plugin package.

This guide focuses on creating object type plugins, which register custom objects that the server can export and clients can fetch. An object type plugin communicates with clients in one of two ways:

  • Fetch-only: The plugin extends ObjectTypeBase.FetchOnly and serializes the object once, as a single payload, when a client fetches it. The client can't send messages back to the object.
  • Bidirectional: The plugin extends ObjectTypeBase and implements its compatibleClientConnection method to return a custom MessageStream. The client and server can then exchange messages for as long as the connection is open, for example to call methods on the server-side object.

This guide builds a fetch-only plugin and a Groovy client that fetches it. To call a bidirectional plugin from the Java client, see Work with bidirectional plugins. The Python version of this guide walks through a complete bidirectional plugin in Python.

Create the plugin

Project layout

This example creates an object type plugin class called ExampleObjectType, which manages objects of class ExampleObject. The project directory, ExamplePlugin, does not need to match either name.

Create the following directory and file structure for your plugin project:

If you write the plugin in Groovy, use this structure instead:

Note

This guide uses Gradle for building the plugin.

Plugin components

A plugin project has five pieces, each covered below in the order you create them:

  • The object itself (ExampleObject).
  • The object type (ExampleObjectType), an ObjectType that recognizes and serializes your object.
  • The registration class (ExamplePluginRegistration), a Registration that registers the object type.
  • The ServiceLoader configuration file that names the registration class.
  • The Gradle build file.

Create the object

First, create the object class that your plugin manages:

Or in Groovy:

Create the object type

Next, create the object type class that recognizes and serializes ExampleObject. It extends ObjectTypeBase.FetchOnly, which implements compatibleClientConnection for you. You implement writeCompatibleObjectTo, which writes the object's bytes once. Here's an example in Java:

Or in Groovy:

The name method returns the type name, ExampleObject, that clients use to fetch these objects. If you change it, update the client in Client implementation as well.

Create the registration class

Create a registration class that registers ExampleObjectType with the server:

Or in Groovy:

To register more than one object type from the same plugin, call callback.register once for each:

Or in Groovy:

Create the ServiceLoader configuration file

Create the ServiceLoader configuration file at src/main/resources/META-INF/services/io.deephaven.plugin.Registration:

At startup, the server uses Java's ServiceLoader mechanism to read this file and load the registration class it names.

Create the Gradle build file

Create a build.gradle file for your plugin:

Build and install the plugin

Build the plugin

If the project doesn't have a Gradle wrapper yet, create one with gradle wrapper. Then build your plugin:

This creates build/libs/ExamplePlugin.jar. The build file sets no version, so Gradle names the JAR after the project folder.

Install the plugin

To install your plugin, add the JAR to the Deephaven server's classpath and restart the server. The server loads the plugin at startup.

Server built from source

If you run Deephaven from a build of the source code:

  1. From the root of the deephaven-core repository, build the server and its start script with ./gradlew server-jetty-app:installDist.
  2. Start the server with the EXTRA_CLASSPATH environment variable set to the plugin JAR, as in the command below.

The command also passes two options in START_OPTS:

  • -Ddeephaven.console.type=groovy starts the server with a Groovy console instead of the default Python console.
  • -Dauthentication.psk sets the pre-shared key that clients supply when they connect. Outside of testing, replace YOUR_PASSWORD_HERE with a secure key.

See Install and use Java packages for more about building the server and using EXTRA_CLASSPATH.

Docker deployment

For Docker deployments, save a Dockerfile in the root folder of the plugin project, ExamplePlugin/, that extends Deephaven's Groovy server image, server-slim:

Important

The Docker Compose file below sets the pre-shared key to YOUR_PASSWORD_HERE for demonstration purposes. The pre-shared key is the password that clients supply when they connect to the server. Change this to a more secure key in production.

Save the following Docker Compose file in the same folder:

With those two files in hand, docker compose up --build builds the image with the plugin installed and starts the server. Use --build again whenever you rebuild the plugin JAR.

Server-side testing

To test your plugin on the server side, create instances of your custom objects so clients can access them. Once the server is running with your plugin installed, locally or in Docker, open the Deephaven IDE at http://localhost:10000/ide/, log in with the pre-shared key you set, and run the following script in the Groovy console:

Clients can then access these objects through the Deephaven client APIs. The plugin's ObjectType implementation serializes each object.

Client-side implementation

Set up the client project

To interact with your plugin from a client application written in Groovy, use the Java client library to connect to and communicate with your plugin objects on the server.

First, create a separate Groovy project for the client. Put the client class from Client implementation at src/main/groovy/com/example/client/ExamplePluginClient.groovy, and give the project its own build.gradle:

Client implementation

Important

Replace YOUR_PASSWORD_HERE with the pre-shared key you set when starting the server.

Create a Groovy client that fetches the exampleObject variable created by the server-side test script. The client connects with the Java client session API and refers to the server object by a typed ticket, which pairs a client-side reference to the object with the object's type. The type, ExampleObject, must match the value that the plugin's name method returns.

For more about using plugin objects from Java, see Use plugins from the Java client.

Client-side testing

To test your client-side implementation:

  1. Start the Deephaven server with your plugin installed.

  2. Create test objects on the server with the script in Server-side testing.

  3. Build and run the client. If the client project doesn't have a Gradle wrapper yet, create one with gradle wrapper first:

The client prints Fetched object: Hello from server plugin!, the bytes that ExampleObjectType wrote for the exampleObject variable.