Java HTTP Client

Manage Traverse databases, queries, and imports from Java over HTTP.

Install

Add the dependency to your pom.xml:

<dependency>
    <groupId>com.truespar</groupId>
    <artifactId>traverse-http</artifactId>
    <version>0.8.0</version>
</dependency>

Connect

import com.truespar.traverse.http.TraverseHttpClient;
import com.truespar.traverse.http.TraverseHttpOptions;

var client = new TraverseHttpClient("http://localhost:7691");

// With API key authentication
var options = new TraverseHttpOptions()
    .apiKey("tvs_your_api_key");
var client = new TraverseHttpClient("http://localhost:7691", options);

Try-with-Resources

The client implements AutoCloseable:

try (var client = new TraverseHttpClient("http://localhost:7691", options)) {
    var health = client.health();
    System.out.println(health.version());
}

Health Check

var health = client.health();
System.out.println(health.status());      // "ok"
System.out.println(health.version());     // server version
System.out.println(health.uptimeSecs());  // seconds since start

// Quick readiness probe (returns boolean, never throws)
if (client.ready()) {
    System.out.println("Server is ready");
}

List Databases

var databases = client.listDatabases();
for (var db : databases) {
    System.out.println(db.name() + " default=" + db.isDefault());
}

Create & Drop Database

client.createDatabase("mydb");
client.dropDatabase("mydb");

Run a Query

import java.util.Map;

var result = client.query(
    "MATCH (n:Person) WHERE n.age > $min_age RETURN n.name, n.age",
    Map.of("min_age", 25),
    "mydb"
);
for (var row : result.rows()) {
    System.out.println(row);
}

System.out.println(result.columns());  // [n.name, n.age]
System.out.println(result.timeMs());   // query time in milliseconds

GQL Dialect

New in 0.8.0: the four-argument query overload takes a dialect - pass "gql". Check features.gql in the health response to detect support.

QueryResponse result = client.query(
    "MATCH (n:Person) FILTER n.age > 30 RETURN n.name", null, null, "gql");

Import Cypher

var result = client.importCypher(
    "CREATE (a:Person {name: 'Alice'});\nCREATE (b:Person {name: 'Bob'});",
    "mydb"
);
System.out.println(result.executed() + " of " + result.totalStatements() + " statements");

Schema

var schema = client.getSchema("mydb");
System.out.println(schema.labels());
System.out.println(schema.relationshipTypes());
System.out.println(schema.indexes());

Aliases

// Create an alias
client.createAlias("production", "mydb");

// List aliases
for (var alias : client.listAliases()) {
    System.out.println(alias.alias() + " -> " + alias.database());
}

// Update and drop
client.alterAlias("production", "mydb_v2");
client.dropAlias("production");

File Upload

try (var stream = new FileInputStream("backup.tvdb")) {
    var result = client.uploadFile("backup.tvdb", stream);
    System.out.println(result.sizeBytes());
}

Save & Close

// Persist all databases to disk
client.save();

// Close the HTTP client
client.close();

Constructor Options

import java.time.Duration;

var options = new TraverseHttpOptions()
    .apiKey("tvs_...")
    .timeout(Duration.ofSeconds(30))              // API request timeout
    .fileTransferTimeout(Duration.ofMinutes(10))  // file upload/download timeout
    .allowUntrustedCertificate(true);             // skip TLS verification

var client = new TraverseHttpClient("https://traverse.example.com", options);