Overview
The layered architecture behind the client — from the public FlexiQ interface down to the native core.
The layered architecture behind the client — from the public FlexiQ interface down to the native core.
import org.byteveda.flexiq.FlexiQ;
try (FlexiQ flexiq = FlexiQ.builder().sqlite("flexiq.db").open()) {
// flexiq is the client — every operation in this reference goes through it
}The public API is a thin, typed shell over the Rust core. App code only ever touches the first layer below; the rest exist so the SDK stays testable and the native boundary stays narrow.
| Layer | Package | Role |
|---|---|---|
FlexiQ | org.byteveda.flexiq | The public entry point. An AutoCloseable interface built via FlexiQ.builder()...open(). Every method documented in this reference is declared here. |
DefaultFlexiQ | org.byteveda.flexiq (package-private) | The only implementation of FlexiQ. Owns predicates, gates, interceptors, resources, and middleware; delegates producer/inspection/admin calls to a QueueBackend and job-await polling to CoreFacade. |
CoreFacade | org.byteveda.flexiq.core | Translation and durable-emulation layer between the typed API and the backend's JSON wire views — e.g. awaitJob polls getJobJson until the job reaches a terminal status. |
QueueBackend | org.byteveda.flexiq.spi | The SPI every backend implements. App code depends only on this interface; it's also what a test fake targets (see Testing). |
JniQueueBackend | org.byteveda.flexiq.internal (package-private) | The production QueueBackend — calls into the native shell over JNI. All scheduling, storage, and locking lives in the Rust core; this layer only marshals JSON and bytes across the boundary. |
A call like flexiq.enqueue(task, payload) flows FlexiQ (interface) →
DefaultFlexiQ (serializes the payload, runs gates/interceptors/middleware)
→ QueueBackend (JniQueueBackend in production) → the native core.
Queue is a handle, not the clientFlexiQ.queue(name) returns a Queue — a handle to one named queue, not
the client itself:
public interface Queue {
String name();
void pause();
void resume();
boolean isPaused();
}Everything else — enqueue, inspect, workers, workflows, locks, periodics —
lives on FlexiQ. Reach for Queue only to pause or resume one named
queue; see FlexiQ.
Every package lives under org.byteveda.flexiq:
| Package | Contents |
|---|---|
| (root) | FlexiQ, Queue, NamedQueue, FlexiQException |
task | Task, EnqueueOptions, RetryPolicy |
annotation | @TaskHandler, @Resource, @Compressed, @Encrypted |
worker | Worker, Worker.Builder, Handler, HandlerRegistry |
workflows | Workflow, Step, Canvas, WorkflowRun, gates, sagas, analysis |
resources | Worker dependency injection — scopes, pools, ResourceContext |
serialization | Serializer, JsonSerializer, MsgpackSerializer, CborSerializer, payload codecs |
locks | Lock, LockInfo |
predicates | Enqueue-time gates — Predicate, EnqueueGate, Recipes |
interception | Enqueue interceptors — Interceptor, Interception |
proxies | Non-serializable argument proxies — ProxyHandler, ProxySession |
middleware | Middleware, EnqueueContext, TaskContext |
events | EventName, OutcomeEvent |
errors | The FlexiQException hierarchy |
model | Wire-view records — Job, QueueStats, WorkerInfo, … |
scheduling | PeriodicTask |
autoscale | AutoscaleOptions, Autoscaler |
batch | Batcher |
webhooks | Webhook, WebhookManager |
contrib | Optional integrations (Micrometer, Sentry) |
dashboard | Dashboard asset serving |
cli | The flexiq command |
spi | QueueBackend — the interface every backend implements |
core | CoreFacade — translation and durable emulation |
internal | JniQueueBackend and the JNI transport (package-private) |
| Artifact | Contents |
|---|---|
org.byteveda:flexiq | The SDK itself. |
org.byteveda:flexiq-test | InMemoryFlexiQ / InMemoryQueueBackend — see Testing. |
org.byteveda:flexiq-spring | The Spring Boot 3 starter. |