Skip to main content

Java SDK

The official Java SDK for Toggly provides a comprehensive solution for feature flag management in Java applications.

Quick reference

Grab the printable Java cheat sheet (download PDF) — Spring Boot, MVC, WebFlux, Servlet, Caffeine, Redis.

Features​

  • Local evaluation - No required runtime dependencies for flag evaluation; telemetry uses optional gRPC dependencies
  • Spring Boot integration - Client configuration plus explicit provider and aspect registration
  • Spring MVC integration - Interceptors, annotations, and argument resolvers
  • Spring WebFlux support - Reactive APIs and filters
  • Servlet integration - Jakarta Servlet hosts, including Tomcat 11
  • Distributed caching - Caffeine and Redis support
  • Deterministic rollouts - Consistent user experience across requests
  • Thread-safe - Safe for concurrent use

Installation​

<!-- Core (required) -->
<dependency>
    <groupId>io.toggly</groupId>
    <artifactId>toggly-core</artifactId>
    <version>1.5.1</version>
</dependency>

<!-- Spring Boot Starter (recommended) -->
<dependency>
    <groupId>io.toggly</groupId>
    <artifactId>toggly-spring-boot-starter</artifactId>
    <version>1.5.1</version>
</dependency>

Quick Start​

Plain Java​

Use the core dependency above in a Maven project with these compiler settings inside pom.xml:

<properties>
    <maven.compiler.release>17</maven.compiler.release>
</properties>
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.16.0</version>
        </plugin>
    </plugins>
</build>

Create src/main/java/example/FirstFlag.java. Set TOGGLY_APP_KEY to your application's key and create a my-feature flag in its Production environment. Start with the flag OFF.

FirstFlag.java
package example;

import io.toggly.core.TogglyClient;
import io.toggly.core.config.TogglyConfig;

public class FirstFlag {
    public static void main(String[] args) {
        String appKey = System.getenv("TOGGLY_APP_KEY");
        if (appKey == null || appKey.isBlank()) {
            throw new IllegalStateException("Set TOGGLY_APP_KEY before starting");
        }
        TogglyConfig config = TogglyConfig.builder()
            .appKey(appKey)
            .environment("Production")
            .refreshIntervalSeconds(30)
            .enableUsageTracking(false)
            .enableMetrics(false)
            .registerContextsOnStartup(false)
            .onError((message, error) -> System.err.println(message))
            .build();

        try (TogglyClient client = new TogglyClient(config)) {
            client.refresh(); // Attempt the first download before evaluation.
            System.out.println(client.isEnabled("my-feature") ? "ON" : "OFF");
        }
    }
}

From the project directory, compile and run with the core JAR on the classpath:

mvn compile dependency:copy-dependencies
java -cp 'target/classes:target/dependency/*' example.FirstFlag

Expect OFF; enable the flag in Toggly and run again to see ON. If the first download fails or the key is undefined, the default is OFF and the callback reports download errors. A completed refresh() is an attempted download, not proof of success. This small program disables telemetry and schema registration so it needs only the core evaluation dependency.

In a server, create one long-lived client at application startup and close it at shutdown. Keep it open to receive polling and live updates; do not create a client for each request. The first evaluation can download definitions synchronously when no snapshot is available.

Spring Boot​

Follow the complete Spring setup, including an explicit HTTP provider bean. The guide covers native AOP registration, MVC request context and the Boot 4 Actuator compatibility boundary.

Runnable applications​

The Java Servlet sample includes startup, shutdown, request context, feature gates, an Order entity and a step-by-step dashboard recipe. Follow its README to run it on Tomcat 11; its missing-key mode displays setup instructions and returns 503 on guarded routes.

The Java Spring MVC sample shows native interceptors, controller gates, boolean argument injection and request-aware template rendering. Its README includes run commands and the dashboard setup recipe.

With User Context​

Target features to specific users or groups:

EvaluationContext context = EvaluationContext.builder()
    .identity("user-123")
    .addGroup("beta-testers")
    .trait("plan", "premium")
    .trait("country", "US")
    .build();

if (client.isEnabled("premium-feature", context)) {
    // Feature is enabled for this user
}

Available Modules​

ModuleDescription
toggly-coreLocal flag evaluation; optional telemetry dependencies
toggly-spring-boot-starterSpring Boot auto-configuration
toggly-spring-mvcSpring MVC interceptors and annotations
toggly-spring-webfluxReactive WebFlux support
toggly-servletPlain servlet integration
toggly-cache-caffeineCaffeine in-memory caching
toggly-cache-redisRedis distributed caching

Requirements​

  • Java 17 or higher
  • The Spring guide uses Boot 4.1.1 and Spring Framework 7.0.9; read its Actuator compatibility section.
  • Servlet integration uses jakarta.servlet, not legacy javax.servlet; the runnable sample uses Servlet 6.1 / Tomcat 11.

Java 17 is the SDK minimum. The runnable Servlet sample uses JDK 26.0.2.1; a host runtime version is separate from that minimum.

Next Steps​