Installation

The Java SDK is a typed shell over the FlexiQ Rust core, bound through a hand-written JNI layer. Baseline: Java 17. The Rust core ships as a per-platform classifier artifact next to a native-free main jar — add both.

plugins { id("com.google.osdetector") version "1.7.3" }

dependencies {
    implementation("org.byteveda:flexiq:1.0.0")
    runtimeOnly("org.byteveda:flexiq:1.0.0:${osdetector.classifier}") // native library
    annotationProcessor("org.byteveda:flexiq-processor:1.0.0") // compile-time TaskHandler bindings
}

<!-- os-maven-plugin resolves ${os.detected.classifier} -->
<build>
  <extensions>
    <extension>
      <groupId>kr.motd.maven</groupId>
      <artifactId>os-maven-plugin</artifactId>
      <version>1.7.1</version>
    </extension>
  </extensions>
</build>

<dependency>
  <groupId>org.byteveda</groupId>
  <artifactId>flexiq</artifactId>
  <version>1.0.0</version>
</dependency>
<dependency>
  <groupId>org.byteveda</groupId>
  <artifactId>flexiq</artifactId>
  <version>1.0.0</version>
  <classifier>${os.detected.classifier}</classifier>
  <scope>runtime</scope>
</dependency>

<!-- The processor is wired through the compiler plugin, not a dependency -->
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <configuration>
    <annotationProcessorPaths>
      <path>
        <groupId>org.byteveda</groupId>
        <artifactId>flexiq-processor</artifactId>
        <version>1.0.0</version>
      </path>
    </annotationProcessorPaths>
  </configuration>
</plugin>

The flexiq-processor artifact is optional but recommended: it turns @TaskHandler-annotated methods into typed Task constants at compile time — zero runtime reflection, GraalVM-native-image friendly. See Tasks.

Companion artifacts: org.byteveda:flexiq-test (in-memory backend for unit tests, no native library) and org.byteveda:flexiq-spring (Spring Boot 3 starter).

Native library artifacts

The Rust core is published as one classifier artifact per platform:

• linux-x86_64 / linux-aarch64
• osx-x86_64 / osx-aarch64
• windows-x86_64

Each classifier jar carries only its own library; the runtime resolves the matching one from the classpath. Deploying to several platforms from one build? Add multiple classifier dependencies — extra platforms cost nothing at runtime.

Anything outside that list — Windows on ARM, or an OS beyond Linux, macOS, and Windows — has no published artifact. The loader fails at startup with an UnsatisfiedLinkError naming the platform it detected rather than trying a binary built for another one. Those platforms are still supported by building the native library from source and pointing -Dflexiq.native.lib at it.

At runtime the platform binary is extracted (content-addressed, safe under concurrent processes) and loaded. Two system properties tune this: -Dflexiq.native.lib=/abs/path loads an explicit library instead — for local development against a fresh build, or a custom-feature build with no classifier artifact at all (the main jar is native-free and works standalone this way) — and -Dflexiq.native.workdir=/var/lib/myapp/flexiq-native relocates extraction on hardened noexec /tmp hosts.

Pick a backend

import org.byteveda.flexiq.FlexiQ;

FlexiQ.builder().sqlite("flexiq.db").open();                   // SQLite (default)
FlexiQ.builder().postgres(System.getenv("PG_URL")).open();
FlexiQ.builder().redis("redis://localhost").open();

FlexiQ.builder().open() with no backend configured uses SQLite at .flexiq/flexiq.db. SQLite needs nothing else — the whole queue lives in one file. Next: the quickstart.