Local development with Deephaven libraries

This guide explains how to build Java or Groovy projects that depend on Deephaven Community libraries. This is useful for creating utilities, custom functions, or extensions that work with Deephaven tables.

Set up your project

Deephaven publishes artifacts to Maven Central, so no credentials are required.

Gradle

Add the Maven Central repository and Deephaven dependencies to your build.gradle:

plugins {
    id 'java'
    id 'groovy'
}

repositories {
    mavenCentral()
}

def dhcVersion = '42.7' // Use the version that matches your Deephaven server

dependencies {
    implementation "io.deephaven:deephaven-engine-api:$dhcVersion"
    implementation "io.deephaven:deephaven-engine-table:$dhcVersion"
    implementation "io.deephaven:deephaven-Configuration:$dhcVersion"
    implementation "io.deephaven:deephaven-configs:$dhcVersion"
    implementation "io.deephaven:deephaven-engine-time:$dhcVersion"
    implementation "io.deephaven:deephaven-log-factory:$dhcVersion"
    runtimeOnly "io.deephaven:deephaven-log-to-slf4j:$dhcVersion"
    runtimeOnly 'org.slf4j:slf4j-simple:2.0.9'
    // Align with the Groovy version Deephaven itself uses to avoid a
    // conflicting Groovy runtime on the classpath.
    implementation "org.codehaus.groovy:groovy:3.0.25"
}

Maven

Add dependencies to your pom.xml:

<properties>
    <dhc.version>42.7</dhc.version> <!-- Use the version that matches your Deephaven server -->
</properties>

<dependencies>
    <dependency>
        <groupId>io.deephaven</groupId>
        <artifactId>deephaven-engine-api</artifactId>
        <version>${dhc.version}</version>
    </dependency>
    <dependency>
        <groupId>io.deephaven</groupId>
        <artifactId>deephaven-engine-table</artifactId>
        <version>${dhc.version}</version>
    </dependency>
    <dependency>
        <groupId>io.deephaven</groupId>
        <artifactId>deephaven-Configuration</artifactId>
        <version>${dhc.version}</version>
    </dependency>
    <dependency>
        <groupId>io.deephaven</groupId>
        <artifactId>deephaven-configs</artifactId>
        <version>${dhc.version}</version>
    </dependency>
    <dependency>
        <groupId>io.deephaven</groupId>
        <artifactId>deephaven-engine-time</artifactId>
        <version>${dhc.version}</version>
    </dependency>
    <dependency>
        <groupId>io.deephaven</groupId>
        <artifactId>deephaven-log-factory</artifactId>
        <version>${dhc.version}</version>
    </dependency>
    <dependency>
        <groupId>io.deephaven</groupId>
        <artifactId>deephaven-log-to-slf4j</artifactId>
        <version>${dhc.version}</version>
    </dependency>
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-simple</artifactId>
        <version>2.0.9</version>
    </dependency>
    <!-- Align with the Groovy version Deephaven itself uses to avoid a
         conflicting Groovy runtime on the classpath. -->
    <dependency>
        <groupId>org.codehaus.groovy</groupId>
        <artifactId>groovy</artifactId>
        <version>3.0.25</version>
    </dependency>
</dependencies>

To compile Groovy sources, add the gmavenplus-plugin to your build. Also pin a modern maven-surefire-plugin version so Maven executes JUnit Jupiter tests, since Surefire versions older than 2.22.0 silently run zero Jupiter tests:

<build>
    <plugins>
        <plugin>
            <groupId>org.codehaus.gmavenplus</groupId>
            <artifactId>gmavenplus-plugin</artifactId>
            <version>3.0.2</version>
            <executions>
                <execution>
                    <goals>
                        <goal>addSources</goal>
                        <goal>addTestSources</goal>
                        <goal>compile</goal>
                        <goal>compileTests</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.2.5</version>
        </plugin>
    </plugins>
</build>

Common dependencies by use case

The dependencies you need depend on what your project does. Here are common patterns:

Use case	Dependencies
Table operations (`select`, `where`, `join`)	`deephaven-engine-api`, `deephaven-engine-table`
Read/write CSV files	`deephaven-extensions-csv`
Read/write Parquet files	`deephaven-extensions-parquet-table`
Configuration utilities	`deephaven-Configuration`
Default configuration properties	`deephaven-configs`
Date/time utilities	`deephaven-engine-time`
Logging	`deephaven-log-factory`, `deephaven-log-to-slf4j`

Browse all available modules on Maven Central.

Local unit testing

To use Deephaven table operations in unit tests, you need to open an ExecutionContext.

Note: Advanced use cases like the Barrage Java client may require an additional JVM argument: --add-opens=java.base/java.nio=ALL-UNNAMED.

Example test setup

Add deephaven-engine-test-utils (for TestExecutionContext) and JUnit Jupiter as test dependencies. Gradle 9 also requires you to declare the JUnit Platform launcher. The logging sink from the base setup above is already available on the test classpath:

dependencies {
    testImplementation "io.deephaven:deephaven-engine-test-utils:$dhcVersion"
    testImplementation "org.junit.jupiter:junit-jupiter:5.10.2"
    testRuntimeOnly "org.junit.platform:junit-platform-launcher"
}

test {
    useJUnitPlatform()
}

Or in Maven:

<dependency>
    <groupId>io.deephaven</groupId>
    <artifactId>deephaven-engine-test-utils</artifactId>
    <version>${dhc.version}</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>5.10.2</version>
    <scope>test</scope>
</dependency>

Use JUnit with an ExecutionContext to test table operations:

import io.deephaven.engine.context.ExecutionContext;
import io.deephaven.engine.context.TestExecutionContext;
import io.deephaven.engine.table.Table;
import io.deephaven.util.SafeCloseable;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.*;

public class MyTableUtilsTest {

    private static ExecutionContext executionContext;
    private static SafeCloseable executionContextCloseable;

    @BeforeAll
    public static void setUp() {
        executionContext = TestExecutionContext.createForUnitTests();
        executionContextCloseable = executionContext.open();
    }

    @AfterAll
    public static void tearDown() {
        executionContextCloseable.close();
    }

    @Test
    public void testTableOperation() {
        // Your test code here
    }
}

Reading test data

Add the appropriate extensions as dependencies:

dependencies {
    implementation "io.deephaven:deephaven-extensions-csv:$dhcVersion"
    implementation "io.deephaven:deephaven-extensions-parquet-table:$dhcVersion"
}

Load test data from CSV or Parquet files in your test resources. Reading the CSV file and converting the Parquet resource URL to a URI both throw checked exceptions, so the test method declares throws Exception:

import io.deephaven.csv.CsvTools;
import io.deephaven.engine.table.Table;
import io.deephaven.parquet.table.ParquetTools;
import org.junit.jupiter.api.Test;

import java.nio.file.Paths;

@Test
public void testReadTestData() throws Exception {
    // Read CSV from test resources
    Table csvTable = CsvTools.readCsv(getClass().getResourceAsStream("/test-data.csv"));

    // Read Parquet from test resources
    String parquetPath = Paths.get(getClass().getResource("/test-data.parquet").toURI()).toString();
    Table parquetTable = ParquetTools.readTable(parquetPath);
}

See CsvTools.readCsv and ParquetTools.readTable for more options.