Documentation

Learn the concepts and tools behind Pod-OS

Java SDK

The pod-os-java-client library targets Java 17+ with wire-faithful AIP framing, concurrent mode via CompletableFuture correlation, auto-reconnect, full Intent coverage, and environment-gated validation (PODOS_VALIDATE=1).

Repository: github.com/PointOfData/pod-os-java-client

Runtime dependency: slf4j-api 2.x (plus the Java standard library).

Build / dependency

mvn clean package

<dependency>
    <groupId>com.pointofdata</groupId>
    <artifactId>pod-os-java-client</artifactId>
    <version>1.0.0</version>
</dependency>

Connect and send

import com.pointofdata.podos.PodOsClient;
import com.pointofdata.podos.config.Config;
import com.pointofdata.podos.message.*;

Config cfg = new Config();
cfg.host             = "gateway-nlb.example.com";
cfg.port             = "62312";
cfg.gatewayActorName = "zeroth.customer.example.com";
cfg.clientName       = "my-java-app";
cfg.enableConcurrentMode = true;

try (PodOsClient client = PodOsClient.newClient(cfg)) {
    Message msg = new Message();
    msg.to      = "Foobar@zeroth.customer.example.com";
    msg.from    = client.getClientName() + "@" + client.getGatewayActorName();
    msg.intent  = IntentTypes.INSTANCE.StoreEvent;

    msg.event = new EventFields();
    msg.event.id        = "evt-001";
    msg.event.owner     = "my-java-app";
    msg.event.timestamp = MessageUtils.getTimestamp();
    msg.event.locationSeparator = "|";

    msg.payload = new PayloadFields();
    msg.payload.data     = "{ \"sensor\": \"temp\", \"value\": 22.5 }";
    msg.payload.mimeType = "application/json";

    Message response = client.sendMessage(msg, Duration.ofSeconds(10));
    System.out.println("Status: " + response.processingStatus());
}

On explicit close(), the client sends fire-and-forget GatewayDisconnect (message type 6) on the authenticated primary connection.

Configuration highlights

Field Default Description
host / port "" / "62312" Gateway dial target
gatewayActorName required FQN of the gateway you dialed
clientName required Unique per TCP connection
enableConcurrentMode false Background receiver + multi in-flight
keepaliveInterval 30s AIP Keepalive; Duration.ZERO disables
connectionLivenessTimeout 90s Pending-request liveness backstop
logLevel 0 0=off … 4=DEBUG

Supported Intents (summary)

ENM requests (MEM_REQ / message type 1000): StoreEvent, StoreData, StoreBatchEvents, StoreBatchTags, GetEvent, GetEventsForTags, LinkEvent, UnlinkEvent, StoreBatchLinks.

Gateway / Actor: GatewayId, GatewayDisconnect, GatewayStreamOn / Off, ActorEcho, StatusRequest / Status, and related control Intents.

Lookup helpers: IntentTypes.INSTANCE.intentFromCommand(...), intentFromMessageTypeInt(...), intentFromMessageTypeAndCommand(...).

Reading links

GetEvent and GetEventsForTags put Linked on response.eventRecords[].links. strength is the returned or matched object toward its neighbor (sourceUniqueId → targetUniqueId). StoreBatchLinks and LinkEvent still send LinkFields (strengthA, strengthB). Walkthrough: Query data.

Validation

export PODOS_VALIDATE=1

Pre-send struct validation and post-receive wire validation produce dual-audience errors (engineer + LLM JSON), matching the other SDKs.

Socket Actor health

import com.pointofdata.podos.Health;

cfg.enableConcurrentMode = true;
PodOsClient client = PodOsClient.newClient(cfg);
Health.respondToHealthChecks(client);

Related