Liteguard

Appearance

Java SDK Guide ​

This guide covers adding Liteguard to a Java application.

Prerequisites ​

  • A Project Client Token from your Liteguard project. Follow the Getting Started guide through the Copy a Project Client Token step if you do not have one yet.
  • Java 17 or later.

Add the dependency ​

Maven ​

xml
<dependency>
  <groupId>io.liteguard</groupId>
  <artifactId>liteguard</artifactId>
  <version>0.5.0</version>
</dependency>

Gradle ​

groovy
implementation 'io.liteguard:liteguard:0.5.0'

Check the releases page for the latest version.

Initialize the client ​

LiteguardClient implements AutoCloseable, so use a try-with-resources block or call close() explicitly on shutdown.

java
import io.liteguard.LiteguardClient;
import io.liteguard.ClientOptions;

var options = ClientOptions.builder()
    .environment(System.getenv("LITEGUARD_ENV"))
    .build();

var client = new LiteguardClient(System.getenv("LITEGUARD_TOKEN"), options);

The constructor fetches the initial bundle synchronously before returning.

Do not commit your token to source control. Read it from environment variables or a secrets manager.

Spring Boot ​

java
@Configuration
public class LiteguardConfig {

    @Bean(destroyMethod = "close")
    public LiteguardClient liteguardClient() {
        var options = ClientOptions.builder()
            .environment(System.getenv("LITEGUARD_ENV"))
            .build();
        return new LiteguardClient(System.getenv("LITEGUARD_TOKEN"), options);
    }
}

Declaring destroyMethod = "close" ensures the client is shut down cleanly when the application context closes.

Evaluate a guard ​

client.isOpen(guardName) reads from the locally cached bundle. No network call occurs per check.

java
if (client.isOpen("payments.checkout")) {
    // guarded code path
}

Passing properties ​

Pass a Map<String, Object> to match against rules configured in the Liteguard UI:

java
if (client.isOpen("payments.checkout", Map.of(
    "user_id", userId,
    "plan", plan
))) {
    // guarded code path
}

Scopes ​

Create a LiteguardScope once per request with the caller's properties and reuse it for multiple guard checks:

java
var scope = client.createScope(Map.of(
    "user_id", userId,
    "plan", plan
));

if (scope.isOpen("payments.checkout")) {
    // ...
}

if (scope.isOpen("billing.invoice_download")) {
    // ...
}

Scopes are immutable. Use scope.withProperties(Map.of(...)) to derive a modified variant.

Servlet filter example ​

java
public class LiteguardFilter implements Filter {

    private final LiteguardClient client;

    public LiteguardFilter(LiteguardClient client) {
        this.client = client;
    }

    @Override
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
            throws IOException, ServletException {
        var httpReq = (HttpServletRequest) req;
        var scope = client.createScope(Map.of(
            "user_id", httpReq.getAttribute("userId")
        ));
        httpReq.setAttribute("liteguardScope", scope);
        chain.doFilter(req, res);
    }
}

Retrieve the scope further down the stack with request.getAttribute("liteguardScope").

Shut down cleanly ​

With try-with-resources:

java
try (var client = new LiteguardClient(token, options)) {
    runApplication(client);
}

Or with an explicit close call:

java
Runtime.getRuntime().addShutdownHook(new Thread(client::close));

close() flushes buffered telemetry and stops background threads.

Verify in Liteguard ​

After calling isOpen at least once, open the Guards tab and confirm your guard appears. See Your First Guard to configure its behavior.

Next steps ​