Java SDK

Fluent FindOptions, typed IoT models, resilient streaming fallback.

Install

implementation files('libs/seshat-java-sdk.jar')

Initialize Client

SeshatClient client = new SeshatClient(SeshatClientOptions.builder()
  .host("localhost") // seshat host
  .apiKey("")
  .secret("")
  .company("")
  .build());

Sensors

var fo = client.sensors.findOpts().name("temp").tag("critical").all(true);
client.sensors.findEachPage(fo, page -> {
  // page.json, page.page, page.limit
  return true;
});

Functions overview: find performs a single page fetch returning sensors and total count. findEachPage iterates sequential pages invoking your handler with items + pagination until all pages consumed or handler returns false. findHandler (not shown) lets you inspect pagination metadata only (total/page/limit) across pages when all(true) is set—useful for progress reporting before calling findEachPage. All filters combine with AND semantics; null/empty values are omitted from the query string. Errors halt iteration immediately.

FindOptions parameters

• name(String): Case-insensitive substring filter on resource names.
• key(String): Exact key filter (unique identifier when available).
• tag(String): Comma-separated tags; matches items having any of them. Example: tag("prod,critical").
• machine(String) / collector(String): Filter by owning machine/collector id or name (aliases).
• limit(Integer): Page size for pagination. When omitted, API default is used. Ignored if all(true).
• page(Integer): 1-based page index for manual paging. Ignored when using handlers or when all(true).
• all(Boolean): Auto-paginate across all pages. Overrides limit/page.

Notes: filters combine with AND; server may cap page size; same options also apply to the Machines service.

IoTQueryOptions (Java) – fluent setters

• page(int), perPage(int)
• sortBy("date"|"value"), sortOrder("asc"|"desc") or shortcuts sortByDateDesc(), etc.
• start(String), end(String) (RFC3339 or epoch)
• value(String), min(double), max(double)

IoT Data

// Query last values by sensor with filters
var q = SensorsService.IoTQueryOptions.create()
  .perPage(100)
  .sortByDateDesc()
  .start("2024-01-01T00:00:00Z")
  .end("2024-01-02T00:00:00Z");
var resp = client.sensors.getIoTData("sensor-1", q);
// Changes endpoint
var changes = client.sensors.getIoTDataChanges("sensor-1", q);
if (resp != null && resp.items != null) {
  resp.items.forEach(rec -> {
    // rec.timestamp, rec.value, rec.metadata
  });
}

Machines Listing

var mo = new com.seshat.sdk.services.MachinesService.FindOptions().tag("production");
var res = client.machines.find(mo);
if (res != null) {
  var list = res.data; var total = res.total;
}

Machines functions parallel Sensors: single find() for one page; paging helpers (if exposed) follow the same page iteration semantics. Filters combine via AND; empty values omitted. Use to collect inventory of machine IDs prior to sensor queries.

Live

// Basic live streaming (simple stream)
client.live.addListener(new com.seshat.sdk.live.SensorsLiveStream.Listener(){
  @Override public void onValue(seshat.v1.Seshat.ReadValueResponse v){
    System.out.println(v.getSensorId()+" -> type="+v.getType());
  }
  @Override public void onError(Throwable t){ t.printStackTrace(); }
  @Override public void onCompleted(){ System.out.println("live completed"); }
});
client.live.start(java.util.List.of("sensor123", "sensor456"));

Connections

Each sensor is linked to a connection. The endpoints a sensor reads from or writes to are called connections (for example an MQTT client or a PostgreSQL database). To publish data to an MQTT connection, you can use advanced write to set payload type and parameters like topic.

// Advanced: boolean write with 'topic' parameter
var adv = new com.seshat.sdk.services.ConnectionsService.AdvancedItem();
adv.anyValue = java.util.Map.of("value", true); // original object (also serialized)
adv.typeOverride = 16; // bool
var p = new com.seshat.sdk.services.ConnectionsService.Parameter();
p.key = "topic"; p.value = "67333c8d615f8c6cd6f07c38/67333c8d615f8c6cd6f07c39".getBytes();
adv.parameters = java.util.List.of(p);
client.connections.writeAdvanced("mqtt://0.0.0.0:8888", java.util.List.of(adv));

// Restart connection
client.connections.restart("mqtt://0.0.0.0:8888");

Events

var resp = client.events.trigger("rebuild-cache", java.util.Map.of("fast", true));
var list = client.events.list();

Error handling

try {
  var fo = client.sensors.findOpts().name("temp");
  var res = client.sensors.find(fo);
} catch (IOException e) {
  // log + retry/backoff
}

try {
  var q = SensorsService.IoTQueryOptions.create().perPage(100).sortByDateDesc();
  var data = client.sensors.getIoTData("sensor123", q);
} catch (IOException e) {
  // network / server error
}