Install and use Java packages

You can add JARs to the classpath in Deephaven Community workers to make Java packages available to your queries. All of Deephaven's deployment options support this, and this guide covers them all.

Once installed, a package can be imported and used like any other Java package.

Caution

Care should be taken when adding JARs to Deephaven workers. Java packages may be missing dependencies or have dependencies that conflict with Deephaven's.

The examples in this guide add the Plexus Common Utilities library to a Deephaven Community instance.

Docker

If you Run Deephaven with Docker, you can either build a custom Docker image or mount a volume containing the JAR into the container.

Build a custom Docker image

To build a custom Docker image, create a Dockerfile that downloads the JAR and adds it to the image. The following Dockerfile adds plexus-utils-4.0.2.jar to /apps/libs in the image. The Deephaven Docker images automatically include /apps/libs/* in the JVM classpath at startup:

FROM ghcr.io/deephaven/server:latest
ADD https://repo1.maven.org/maven2/org/codehaus/plexus/plexus-utils/4.0.2/plexus-utils-4.0.2.jar /apps/libs/plexus-utils-4.0.2.jar

You then need to build your image. If you use Docker without Compose, run docker build and docker run:

docker build --tag deephaven-plexus-utils .
docker run --rm --name deephaven-with-plexus-utils -p 10000:10000 deephaven-plexus-utils

Alternatively, if you use Docker Compose, you can have Compose build the image for you. The following YAML assumes that the Dockerfile lives in the same directory:

services:
  deephaven:
    build: .
    ports:
      - "${DEEPHAVEN_PORT:-10000}:10000"
    volumes:
      - ./data:/data
    environment:
      - START_OPTS=-Xmx4g

Mount the JAR into the container manually

Adding JARs to a Docker container does not require building a custom image. Instead, you can simply mount a folder into the container that contains whatever JARs you wish to use. Since the Deephaven Docker images automatically include /apps/libs/* in the JVM classpath, mounting your local JAR directory to /apps/libs makes them immediately available.

The following command assumes you've placed the JAR file into a folder called /home/user/java/libs:

docker run --rm -v /home/user/java/libs:/apps/libs -p 10000:10000 ghcr.io/deephaven/server:latest

Production application

The Production application uses the environment variable EXTRA_CLASSPATH to include additional JARs in the classpath. See Configure the production application for more details, including other configuration options.

Build from source

Adding Java packages to Deephaven built from source code is similar to the production application. It does, however, change how you launch Deephaven built from source.

Rather than run ./gradlew server-jetty-app:run, run this instead:

./gradlew server-jetty-app:installDist

This creates the directory ./server/jetty-app/build/install/server-jetty/bin, which contains a start script that you can pass additional parameters to, such as an EXTRA_CLASSPATH environment variable.

Caution

Use quotes around the classpath value to prevent shell expansion of asterisks. The JVM needs to receive the literal * character to include all JARs in the directory.

You can pass it directly to the command:

EXTRA_CLASSPATH="/path/to/libs/*:/apps/libs/*" ./server/jetty-app/build/install/server-jetty/bin/start

Or you can export the environment variable before running the script:

export EXTRA_CLASSPATH="/path/to/libs/*:/apps/libs/*"
./server/jetty-app/build/install/server-jetty/bin/start

Use Java packages in query strings

Not only can you import and use the extra Java packages in normal Python code, but you can also call them in query strings. You'll need to provide the full package name unless you construct an instance of the class beforehand. The following code calls org.codehaus.plexus.util.StringUtils.abbreviate from the Plexus Common Utilities library to abbreviate a string.

from deephaven import empty_table

source = empty_table(1).update(
    [
        "StringColumn = `Hello world`",
        "Abbreviated = org.codehaus.plexus.util.StringUtils.abbreviate(StringColumn, 9)",
    ]
)