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.
Project setup options
Section titled “Project setup options”- 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.
- 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.
Install
Section titled “Install”From Maven Central
Section titled “From Maven Central”<dependency> <groupId>ai.sourceorrery</groupId> <artifactId>sourceorrery</artifactId> <version>0.3.1</version></dependency>implementation("ai.sourceorrery:sourceorrery:0.3.1") // Gradleai.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.
From the GitHub release
Section titled “From the GitHub release”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):
Invoke-WebRequest https://github.com/Netizine/sourceorrery/releases/download/v0.3.1/sourceorrery-0.3.1.jar -OutFile sourceorrery-0.3.1.jarmvn install:install-file "-Dfile=sourceorrery-0.3.1.jar" "-DgroupId=ai.sourceorrery" "-DartifactId=sourceorrery" "-Dversion=0.3.1" "-Dpackaging=jar"curl -LO https://github.com/Netizine/sourceorrery/releases/download/v0.3.1/sourceorrery-0.3.1.jarmvn install:install-file -Dfile=sourceorrery-0.3.1.jar -DgroupId=ai.sourceorrery -DartifactId=sourceorrery -Dversion=0.3.1 -Dpackaging=jarcurl -LO https://github.com/Netizine/sourceorrery/releases/download/v0.3.1/sourceorrery-0.3.1.jarmvn install:install-file -Dfile=sourceorrery-0.3.1.jar -DgroupId=ai.sourceorrery -DartifactId=sourceorrery -Dversion=0.3.1 -Dpackaging=jarWithout 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.
From source
Section titled “From source”See Building from source below.
Get a secret
Section titled “Get a secret”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 vaultWith 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(); // Stringvalue.use(bytes -> { ... }); // a copy that is wiped afterwardsvalue.length();value.close(); // zeroise; expose() throws IllegalStateException afterwardsvalue.toString(); // "[REDACTED]"Errors
Section titled “Errors”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.
Load a project
Section titled “Load a project”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.
Threads
Section titled “Threads”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.
Building from source
Section titled “Building from source”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:
git clone https://github.com/Netizine/sourceorrerycd sourceorrerygit checkout v0.3.1 # or stay on main for the newest changescargo build --release -p sourceorrery-ffiBuild the jar and install it into your local Maven repository
(~/.m2), where your project’s build finds it:
cd bindings/javamvn 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:
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:
cargo build --release -p sourceorrery-cli -p sourceorrery-ffieval "$(bash scripts/ci/fixture-vault.sh)" # a throwaway vault, the variables the tests read, SOURCEORRERY_NATIVE_DIRcd bindings/javamvn testjava --enable-native-access=ALL-UNNAMED -cp target/classes examples/GetSecret.java "$SOURCEORRERY_TEST_VAULT" database-passwordcd ../..python tests/conformance/sdk/harness.py --runner javaWithout 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).