Migrating from Legacy Java/Kotlin SDK to Java Core

This guide covers migrating from the legacy Java/Kotlin Server SDK to the Java Core SDK. The Java Core SDK offers significant performance improvements and new features, built on a shared Rust core library.

Why migrate

• Performance: Java Core achieves faster evaluation times and lower CPU consumption, making it more efficient than the legacy SDK.
• New Features: Access to Parameter Stores, CMAB (Contextual Multi-Armed Bandits), observabilityClient, and more.
• Future Support: All new features and improvements are only available in Java Core.
• Maintenance: The legacy Java SDK is in maintenance mode and only receives critical bug fixes.

Installation differences

Legacy Java/Kotlin SDK

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.statsig:serversdk:X.X.X'
}

Java Core SDK

The recommended approach is to use the "uber" JAR (available since version 0.4.0). The uber JAR contains both the core library and native libraries for all supported platforms in a single package. The uber JAR simplifies dependency management and deployment across different environments.

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.statsig:javacore:X.X.X:uber' // Uber JAR with all native libraries (recommended)
}

The uber JAR includes native libraries for Linux glibc (x86_64, arm64), macOS (x86_64, arm64), and Windows (x86_64). For Alpine Linux or other musl-based systems, use the platform-specific installation approach.

API differences

Key package and class changes

Initialization

import com.statsig.sdk.Statsig;

StatsigOptions options = new StatsigOptions();
// Customize options as needed
// options.initTimeoutMs = 9999;
Future initFuture = Statsig.initializeAsync("server-secret-key", options);
initFuture.get();

Checking gates

StatsigUser user = new StatsigUser("user_id");
Boolean isFeatureOn = Statsig.checkGateSync(user, "use_new_feature");

if (isFeatureOn) {
  // Gate is on, use new feature
} else {
  // Gate is off
}

Getting configs

DynamicConfig config = Statsig.getConfigSync(user, "awesome_product_details");

String itemName = config.getString("product_name", "Awesome Product v1");
Double price = config.getDouble("price", 10.0);
Boolean shouldDiscount = config.getBoolean("discount", false);

Getting experiments

DynamicConfig experiment = Statsig.getExperimentSync(user, "new_user_promo_title");

String promoTitle = experiment.getString("title", "Welcome to Statsig!");
Double discount = experiment.getDouble("discount", 0.1);

Getting layers

Layer layer = Statsig.getLayerSync(user, "user_promo_experiments");

String promoTitle = layer.getString("title", "Welcome to Statsig!");
Double discount = layer.getDouble("discount", 0.1);

Logging events

Statsig.logEvent(user, "purchase", 2.99, Map.of("item_name", "remove_ads"));

Configuration options differences

StatsigOptions options = new StatsigOptions();
options.setInitTimeoutMs(3000);
options.setTier("staging");
options.setLocalMode(false);
options.setApi("https://api.statsig.com/v1");
options.setRulesetsSyncIntervalMs(10 * 1000);
options.setIdListsSyncIntervalMs(60 * 1000);
options.setDisableAllLogging(false);

Migration steps

New features in Java Core

Parameter stores

Java Core introduces Parameter Stores, which let you manage parameters across multiple feature gates, experiments, and dynamic configs:

ParameterStore parameterStore = statsig.getParameterStore(user, "my_parameter_store");
String value = parameterStore.getString("parameter_name", "default_value");

Improved performance

Java Core offers significantly better performance:

• Faster evaluation times
• More efficient network usage
• Reduced CPU usage
• Better memory management

Troubleshooting

Common issues

1. Missing Platform-Specific Dependency

   • Error: java.lang.UnsatisfiedLinkError: no statsig_jni in java.library.path
   • Solution: Add the correct platform-specific dependency

2. Incompatible Method Calls

   • Error: java.lang.NoSuchMethodError
   • Solution: Update method calls to match the new API

3. Configuration Differences

   • Issue: Features not evaluating as expected
   • Solution: Verify options are correctly configured in the new format

Need help

If you encounter any issues during migration, reach out:

• Statsig Slack Community
• GitHub Issues