Skip to content

Java

The read-only Java SDK (Foreign Function and Memory API): install it from Maven Central, the release or source, open a vault, get a secret, handle typed exceptions, load a project.

6 min read
  1. Option 1: Set up with the CLI. Follow the CLI installation guide, then create the vault and set its secret values in your own terminal.
  2. Option 2: Set up with an AI coding agent. Run sourceorrery init --integration all, then ask your agent to set up SourceOrrery for the project without showing values. You keep vault keys and new values private. The agent setup guide works with an existing CLI installation.
<dependency>
<groupId>ai.sourceorrery</groupId>
<artifactId>sourceorrery</artifactId>
<version>0.3.1</version>
</dependency>
implementation("ai.sourceorrery:sourceorrery:0.3.1") // Gradle

ai.sourceorrery:sourceorrery on Maven Central (opens in a new tab) is one jar that embeds the native library for Windows, macOS and Linux (x64 and arm64), so the same dependency serves every platform. Every file is signed with the release key; Supply chain shows how to check it.

Requires Java 22 or newer: the binding uses the Foreign Function and Memory API (java.lang.foreign) over the C ABI, with no JNI code and no third-party dependency. The jar extracts the native library on first use; set SOURCEORRERY_NATIVE_DIR to use a library from elsewhere. Run with --enable-native-access=ALL-UNNAMED (or grant it to your module) to silence the restricted-method warning.

The same jar, sourceorrery-0.3.1.jar, is attached to the v0.3.1 release (opens in a new tab). Install it into your local Maven repository, then depend on it with the coordinates above (in Gradle, with mavenLocal() among the repositories):

Terminal window
Invoke-WebRequest https://github.com/Netizine/sourceorrery/releases/download/v0.3.1/sourceorrery-0.3.1.jar -OutFile sourceorrery-0.3.1.jar
mvn install:install-file "-Dfile=sourceorrery-0.3.1.jar" "-DgroupId=ai.sourceorrery" "-DartifactId=sourceorrery" "-Dversion=0.3.1" "-Dpackaging=jar"

Without a local repository, put the jar on the classpath directly: implementation(files("libs/sourceorrery-0.3.1.jar")) in Gradle, or --class-path sourceorrery-0.3.1.jar on the java command line.

See Building from source below.

import ai.sourceorrery.Secret;
import ai.sourceorrery.SecretReader;
try (SecretReader reader = SecretReader.open("development");
Secret secret = reader.get("database-password")) {
connect(secret.value().exposeText());
} // closing zeroises the value and releases the vault

With the default options, SOURCEORRERY_HOME locates the vault; this machine’s key in the OS credential store opens it, else the recovery key: an explicit one, SOURCEORRERY_RECOVERY_KEY, then a file or SOURCEORRERY_RECOVERY_KEY_FILE. SecretReader.open(vault, OpenOptions.defaults().withHome(..).withRecoveryKey(..).withRecoveryKeyFile(..).withEnvironment(false)) overrides any of that. The SDK never prompts and never asks the vault’s view check.

A secret the vault keeps at a provider (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) is read there through the vault’s connection, with the same calls: the connection signs in with the credentials it stores, or with the provider’s own sign-in on the machine. No provider is contacted until a secret it keeps is read.

Call Returns
reader.get(name) Secret for the newest accessible version
reader.get(name, version) Secret for exactly that version
reader.properties(name) / properties(name, Optional.of(version)) SecretProperties record (policy not applied)
reader.resolve("sourceorrery://development/database-password") Secret
reader.descriptor() VaultDescriptor record (no values)

Secret is a record of properties() (vault, name, version, enabled, contentType, tags, notBefore, expiresOn, createdOn, updatedOn as Instant, recoveryLevel, reference()) and value(), a SecretValue:

value.expose(); // byte[] (a copy)
value.exposeText(); // String
value.use(bytes -> { ... }); // a copy that is wiped afterwards
value.length();
value.close(); // zeroise; expose() throws IllegalStateException afterwards
value.toString(); // "[REDACTED]"

Every failure is a SourceOrreryException (unchecked) or a subclass, with code(), detail(), hint() and getMessage() (detail plus hint):

try (SecretReader reader = SecretReader.open("development")) {
reader.get("database-password");
} catch (VaultLockedException e) {
System.err.println(e.hint()); // which recovery-key sources were tried
} catch (SecretNotFoundException e) {
System.err.println(e.hint()); // "Store it with `sourceorrery secret set ...`"
} catch (SourceOrreryException e) {
System.err.println(e.code() + ": " + e.getMessage());
}

Classes: VaultNotFoundException, VaultLockedException, MigrationRequiredException, VaultMismatchException, SecretNotFoundException, VersionNotFoundException, SecretDeletedException, PolicyException with SecretDisabledException, SecretNotYetValidException (isTransient()), SecretExpiredException, IntegrityException, UnsupportedException, InvalidArgumentException, InvalidNameException, ManifestException, PermissionDeniedException, StorageException, UnauthenticatedException (the provider that stores the secret refused the credentials), ProviderUnavailableException (the provider could not be reached; isTransient()). See the SDK overview.

try (Project project = Project.load("sourceorrery.toml")) { // or Project.load() to discover it
for (ProjectSecret secret : project.secrets()) {
environment.put(secret.env(), secret.value().exposeText());
}
}

Project.load resolves every [secrets.*] entry the way sourceorrery run does and throws the first required secret’s exception if one cannot be read.

A SecretReader may be shared between platform or virtual threads, which read at the same time. close() waits for the calls already running, then frees the native reader once; a call made after close() was called throws IllegalStateException, and close() from inside a call is refused.

You need Git, Rust 1.91.1 or newer installed with rustup, and a C compiler (on Linux also pkg-config and libdbus-1-dev); Building from source has the commands for each platform. For this SDK, also a JDK, 22 or newer (CI uses Temurin 25), and Maven.

Get the code and build the native library the jar calls:

Terminal window
git clone https://github.com/Netizine/sourceorrery
cd sourceorrery
git checkout v0.3.1 # or stay on main for the newest changes
cargo build --release -p sourceorrery-ffi

Build the jar and install it into your local Maven repository (~/.m2), where your project’s build finds it:

Terminal window
cd bindings/java
mvn install -DskipTests # ai.sourceorrery:sourceorrery:<version>, jar in target/

The version is the one committed in the repository, not the release’s; Get the code shows how to stamp the release version first. A jar built this way carries no native library (the release workflow embeds one per platform), so tell it where yours is when your application runs:

Terminal window
export SOURCEORRERY_NATIVE_DIR=/path/to/sourceorrery/target/release
# PowerShell: $env:SOURCEORRERY_NATIVE_DIR = "C:\path\to\sourceorrery\target\release"

To run the tests, the example and the conformance harness, build the CLI too, which creates the test vault, and run the rest in Bash (Git Bash on Windows) from the repository root:

Terminal window
cargo build --release -p sourceorrery-cli -p sourceorrery-ffi
eval "$(bash scripts/ci/fixture-vault.sh)" # a throwaway vault, the variables the tests read, SOURCEORRERY_NATIVE_DIR
cd bindings/java
mvn test
java --enable-native-access=ALL-UNNAMED -cp target/classes examples/GetSecret.java "$SOURCEORRERY_TEST_VAULT" database-password
cd ../..
python tests/conformance/sdk/harness.py --runner java

Without the fixture’s variables, mvn test skips the tests that read a vault. What the fixture script creates: The SDK test vault. Source: bindings/java (opens in a new tab).