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), which contains both the core library and native libraries for all supported platforms in a single package. This 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