Install and use Java packages

You can add JARs to the classpath of the Deephaven Community server process (the worker that runs your queries) to make Java packages available to your queries. A JAR is a Java archive file that packages compiled classes. The classpath is the list of locations that the Java Virtual Machine (JVM) loads classes from. This guide covers three deployment options: Docker, the production application, and building from source. After you install the JARs with any of them, see Use the package and Use Java packages in query strings.

Once installed, you can import a package's classes into a Groovy script and call them there. You can also call them from query strings, the string formulas you pass to table operations. Query strings need the full class name unless you import the class first. The Use Java packages in query strings section covers both options.

Caution

Be careful 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 starts from the server-slim image, which runs the Groovy console, and adds plexus-utils-4.0.2.jar to /apps/libs in the image. The Deephaven Docker images include /apps/libs/* in the JVM classpath at startup:

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

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:

Mount the JAR into the container manually

Adding JARs to a Docker container does not require building a custom image. Instead, you can mount a folder into the container that contains whatever JARs you wish to use. Mount your local JAR directory to /apps/libs, which the images already include on the classpath, so the JARs are available when the container starts.

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

Next, see Use the package.

Production application

The Production application uses the environment variable EXTRA_CLASSPATH to include additional JARs in the classpath. Set it in the environment where the production application runs, for example EXTRA_CLASSPATH="/path/to/libs/*". See Configure the production application for more details, including other configuration options.

Next, see Use the package.

Build from source

As with the production application, you add JARs to Deephaven built from source code by setting the EXTRA_CLASSPATH environment variable. The difference is how you launch the server.

Follow the steps in Build and launch Deephaven from source code up to the point where you would start the server. Then, instead of running ./gradlew server-jetty-app:run -Pgroovy, run this:

Running installDist creates the directory ./server/jetty-app/build/install/server-jetty/bin, which contains a start script. The -Pgroovy flag selects the Groovy console. Without it, the start script runs the Python server.

Set the EXTRA_CLASSPATH environment variable when you run the start script.

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:

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

Next, see Use the package.

Use the package

Once a JAR is on the classpath, import its classes into a Groovy script as you would any other Java class. The following code imports the org.codehaus.plexus.util.StringUtils class and calls its static abbreviate method:

Use Java packages in query strings

You can also call the package's classes in query strings, the string formulas you pass to table operations such as update.

Query strings need the full class name, such as org.codehaus.plexus.util.StringUtils, unless you import the class into the query library first. For example, ExecutionContext.getContext().getQueryLibrary().importClass(org.codehaus.plexus.util.StringUtils.class) makes the short name StringUtils available to query strings. See Groovy in query strings for more examples.

The following code calls org.codehaus.plexus.util.StringUtils.abbreviate from the Plexus Common Utilities library to abbreviate a string. The example creates a one-row table with emptyTable and adds a column that calls the method.