Java

The Java SDK is ai.fireweave:fireweave-sdk 2.3.0 on Maven Central. It evaluates control points through client.controlPoints() and registers targets through client.registerTarget(). Those are the two v1 capabilities. The wire protocol uses flagKey.

Artifact versions are not uniform. fireweave-sdk is 2.3.0. fireweave-openfeature, fireweave-adapter-posthog, and fireweave-testing remain at 0.1.0 and are leftover pre-v1 artifacts. Do not add them as if they ship with 2.3.0.

Types live under ai.fireweave.sdk.{domain,application,infrastructure.adapters}. There is no facade re-export package.

Supported versions

	Value
Artifact	`ai.fireweave:fireweave-sdk` 2.3.0
Java	11+ (`maven.compiler.release`)
Runtime dependencies	none

CI exercises JDK 11 and 25. Document 11+ from the POM.

Install

<dependency>
  <groupId>ai.fireweave</groupId>
  <artifactId>fireweave-sdk</artifactId>
  <version>2.3.0</version>
</dependency>

Do not add fireweave-openfeature or fireweave-adapter-posthog. For offline tests, use Fireweave.init(InitOptions.local(…)) — you do not need fireweave-testing.

Initialize

Fireweave.init is the single entry point. mode is required and never inferred. Init throws FireweaveException (kind Configuration) when mode is missing, remote credentials are blank, apiUrl fails the host allowlist, or local mode is combined with credentials.

import ai.fireweave.sdk.application.Fireweave;
import ai.fireweave.sdk.application.FireweaveClient;
import ai.fireweave.sdk.application.InitOptions;
import ai.fireweave.sdk.domain.EvaluationContext;

import java.util.Map;

FireweaveClient client = Fireweave.init(InitOptions.local(Map.of("new-checkout", true)));

boolean enabled = client.controlPoints()
    .getBooleanValue("new-checkout", false,
        EvaluationContext.builder().targetingKey("user_42").build());

client.close();

Production — Java does not call System.getenv. Read env in your app and pass the values in:

FireweaveClient client = Fireweave.init(InitOptions.remote(apiKey, apiUrl));

FireweaveClient implements AutoCloseable. Lower-level construction:

import ai.fireweave.sdk.application.FireweaveConfig;
import ai.fireweave.sdk.application.FireweaveRuntime;
import ai.fireweave.sdk.infrastructure.adapters.FireweaveLocalAdapter;

FireweaveRuntime runtime = new FireweaveRuntime(
    FireweaveConfig.builder().build(),
    new FireweaveLocalAdapter(Map.of("new-checkout", true)));
runtime.initialize();
FireweaveClient client = new FireweaveClient(runtime);

Configuration and authentication

Option	Mode	Description
`InitOptions.remote(apiKey, apiUrl)`	`remote`	fw-server credentials (required)
`allowedHosts`	`remote`	SSRF allowlist override on the builder
`InitOptions.local(Map)`	`local`	Seeded boolean map

Auth: Authorization: Bearer <key>. Paths: POST /v1/flags/evaluate, POST /v1/targets/register. Default FireweaveConfig.DEFAULT_ALLOWED_HOSTS lists Fireweave hosts, loopback, and five leftover PostHog hostnames. Those PostHog entries are a pre-existing allowlist leftover — there is no PostHog adapter in this SDK. https is required off-loopback. Opt out with ALLOW_ANY_HOST = "*". See Configuration and auth.

Targets

registerTarget is on the client. It never throws.

import ai.fireweave.sdk.application.RegisterTargetOptions;
import ai.fireweave.sdk.domain.JsonValue;
import ai.fireweave.sdk.domain.TargetKind;

var result = client.registerTarget("user_42", RegisterTargetOptions.builder()
    .kind(TargetKind.USER)
    .property("plan", JsonValue.of("pro"))
    .build());
if (!result.ok()) {
    System.out.println("registerTarget failed " + result.error());
}

There is also registerTarget(targetingKey) with empty options. In local mode the adapter records the target in-process and traces [fireweave:local]. Recorded targets are readable via FireweaveLocalAdapter#getRegisteredTargets(). See Targeting and targets.

Control points

client.controlPoints() is the documented namespace. client.flags() is the same object (@Deprecated in Javadoc only, silent at runtime). FlagType: BOOLEAN, STRING, NUMBER, OBJECT. There is no separate INTEGER / FLOAT in v1.

import ai.fireweave.sdk.domain.EvaluationContext;
import ai.fireweave.sdk.domain.FlagType;
import ai.fireweave.sdk.domain.JsonValue;

EvaluationContext ctx = EvaluationContext.builder().targetingKey("user_42").build();

boolean on = client.controlPoints().getBooleanValue("new-checkout", false, ctx);
String theme = client.controlPoints().getStringValue("checkout-theme", "classic", ctx);
double ratio = client.controlPoints().getNumberValue("discount", 0.0, ctx);
JsonValue payload = client.controlPoints().getObjectValue("config", JsonValue.ofNull(), ctx);

var details = client.controlPoints().getBooleanDetails("new-checkout", false, ctx);
var decision = client.controlPoints().evaluate(
    "new-checkout", FlagType.BOOLEAN, JsonValue.of(false), ctx, null);

Nine methods: getBooleanValue, getStringValue, getNumberValue, getObjectValue, getBooleanDetails, getStringDetails, getNumberDetails, getObjectDetails, evaluate. Evaluation never throws. getNumberValue returns double. Integers beyond Java int range that used to go through an OpenFeature integer resolver are not a native path anymore. See Control points.

Adapters

Adapter	Module	Use
`FireweaveRemoteAdapter`	`fireweave-sdk`	Production fw-server
`FireweaveLocalAdapter`	`fireweave-sdk`	Dev boolean map
`InMemoryAdapter`	`fireweave-testing` (tree / leftover 0.1.0)	Fixture-driven tests

Prefer Fireweave.init for both local and remote. Do not treat fireweave-testing@0.1.0 as part of the 2.3.0 line. See Adapters.

Errors

ErrorKind enum (15 kinds) + FireweaveException + FireweaveError value type. Evaluation returns defaults; registerTarget returns RegisterTargetResult. Init throws on configuration failure. See Errors.

Testing

Use InitOptions.local(…). The repo test-server stub does not implement /v1/targets/register. See Testing.

Shutdown

client.close(); // runtime.shutdown(); idempotent; bounded by shutdownTimeoutMs (default 10s)

v1 reads are side-effect free. There is no exposure queue to flush. See Initialize, ready, shutdown.

Not in this SDK

FireweaveProvider / fireweave-openfeature as a current 2.3.0 artifact
releases(), exposures(), signals(), capabilities(), guardrails()
System.getenv for FW_*
A live PostHog adapter
Implicit flush of a removed exposure queue

Quickstart

Offline evaluate in every language.

Compatibility

Seven-language surface and the 2.3.0 / 0.1.0 Java skew.

Get Started

SDKs

Concepts

Production

CLI

Terraform

Testing

Troubleshooting

Migration

Reference

Supported versions

Install

Initialize

Configuration and authentication

Targets

Control points

Adapters

Errors

Testing

Shutdown

Not in this SDK

Next

Quickstart

Compatibility

​Supported versions

​Install

​Initialize

​Configuration and authentication

​Targets

​Control points

​Adapters

​Errors

​Testing

​Shutdown

​Not in this SDK

​Next

Quickstart

Compatibility

Supported versions

Install

Initialize

Configuration and authentication

Targets

Control points

Adapters

Errors

Testing

Shutdown

Not in this SDK

Next