jolt-java-api

A small, fast Java client for the Jolt in-memory messaging broker.

• Plain TCP + NDJSON (newline-delimited JSON)
• No external dependencies (standard library only)
• Supports:
  • auth
  • sub / unsub
  • pub
  • ping
• Designed for low latency and high throughput

---

1. Requirements

• Java 8 or newer
• A running Jolt server (the Go broker):
  • Example: ./broker -config=config.json
  • Default port: 8080 (unless changed in config.json)

---

2. Project structure

jolt-java-api/
  src/
    main/
      java/
        io/
          jolt/
            api/
              config/
                JoltConfig.java
              exception/
                JoltException.java
              response/
                JoltErrorResponse.java
                JoltResponseParser.java
              message/
                JoltMessageHandler.java
                JoltTopicMessage.java
              builder/
                JoltRequestBuilder.java
              JoltClient.java
  pom.xml
  README.md

Place all API classes under src/main/java/io/jolt/api.

If you are not using Maven/Gradle, just ensure the package io.jolt.api matches the directory layout where you compile.

---

3. Building

3.1 Using javac directly

From the jolt-java-api root (where src lives):

javac -d out $(find src/main/java -name "*.java")

On Windows (PowerShell):

javac -d out (Get-ChildItem -Recurse src\main\java\*.java).FullName

This compiles all classes to the out directory.

To run a sample app (if you have e.g. io.jolt.example.JoltExampleApp):

java -cp out io.jolt.example.JoltExampleApp

3.2 Using Maven (optional)

If you use Maven, a minimal pom.xml could look like:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>io.jolt</groupId>
  <artifactId>jolt-java-api</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>

  <name>jolt-java-api</name>
  <description>Java client for the Jolt messaging broker</description>

  <build>
    <sourceDirectory>src/main/java</sourceDirectory>
  </build>
</project>

Build:

mvn package

The JAR will be in target/jolt-java-api-0.1.0.jar.

---

4. Basic usage

4.1 Include the API

Either:

• Add compiled classes (out) to your application’s classpath, or
• Add the built JAR (jolt-java-api-0.1.0.jar) to your project’s dependencies.

Import in your Java code:

import io.jolt.api.*;

4.2 Connect to Jolt

JoltConfig config = JoltConfig.newBuilder()
        .host("127.0.0.1")  // Jolt server host
        .port(8080)         // Jolt server port
        .build();

JoltMessageHandler handler = new JoltMessageHandler() {
    @Override
    public void onOk(String rawLine) {
        System.out.println("[OK] " + rawLine);
    }

    @Override
    public void onError(JoltErrorResponse error, String rawLine) {
        System.err.println("[ERROR] " + error.getError());
    }

    @Override
    public void onTopicMessage(JoltTopicMessage msg, String rawLine) {
        System.out.println("[MSG] " + msg.getTopic() + " -> " + msg.getData());
    }

    @Override
    public void onDisconnected(Throwable cause) {
        System.err.println("[DISCONNECTED] " +
                (cause != null ? cause.getMessage() : "closed"));
    }
};

JoltClient client = new JoltClient(config, handler);
client.connect();

4.3 Authenticate (if server security is enabled)

If your config.json for the server has "security": { "enabled": true, ... }, you must authenticate:

client.auth("username", "password");

If security is disabled on the server, this call still returns {"ok":true} and you can also skip it completely.

4.4 Subscribe and publish

Subscribe to a topic:

client.subscribe("chat.room1");

Publish a message:

client.publish("chat.room1", "hello from jolt-java-api");

When a message is delivered, your onTopicMessage handler receives it.

4.5 Ping

client.ping();

You’ll receive an {"ok":true} response in onOk.

4.6 Closing the client

client.close();

This closes the TCP connection and stops the reader thread.

---

5. Minimal complete example

import io.jolt.api.*;

public class JoltExampleApp {

    public static void main(String[] args) throws Exception {
        // 1. Configure connection
        JoltConfig config = JoltConfig.newBuilder()
                .host("127.0.0.1")
                .port(8080)
                .build();

        // 2. Define how to handle messages
        JoltMessageHandler handler = new JoltMessageHandler() {
            @Override
            public void onOk(String rawLine) {
                System.out.println("[OK] " + rawLine);
            }

            @Override
            public void onError(JoltErrorResponse error, String rawLine) {
                System.err.println("[ERROR] " + error.getError());
            }

            @Override
            public void onTopicMessage(JoltTopicMessage msg, String rawLine) {
                System.out.println("[MSG] " + msg.getTopic() + " -> " + msg.getData());
            }

            @Override
            public void onDisconnected(Throwable cause) {
                System.err.println("[DISCONNECTED] " +
                        (cause != null ? cause.getMessage() : "closed"));
            }
        };

        // 3. Create client and connect
        JoltClient client = new JoltClient(config, handler);
        client.connect();

        // 4. Authenticate if your Jolt server requires it
        //    (adjust username/password to match server config.json)
        client.auth("jolt-chat", "some password");

        // 5. Subscribe and publish
        client.subscribe("chat.room1");
        client.publish("chat.room1", "hello from Java!");

        // 6. Keep app running for a while to receive messages
        Thread.sleep(10_000);

        // 7. Clean shutdown
        client.close();
    }
}

Compile and run (without Maven):

javac -cp out -d out src/main/java/io/jolt/example/JoltExampleApp.java
java -cp out io.jolt.example.JoltExampleApp

(Adjust classpath and paths if your structure is different.)

---

6. Notes

• This API does not provide TLS. To secure transport:
  • Run Jolt behind a TLS-terminating proxy (e.g. Nginx, HAProxy), or
  • Use OS-level tunnels (SSH, VPN).
• All JSON is built manually with escaping for safety and performance.
• The client uses a single background thread for reading and a synchronized writer for sending, which keeps it simple and efficient.

For more advanced features (topic-specific handlers, reconnection, etc.), you can build thin wrappers on top of this core API.