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)",
]
)