Migrating from Legacy Java/Kotlin SDK to Java Core

Learn how to migrate from the legacy Java/Kotlin Server SDK to the new Java Core SDK with improved performance and new features

This guide will help you migrate from the legacy Java/Kotlin Server SDK to the new Java Core SDK. The Java Core SDK offers significant performance improvements and new features, as it’s 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 will only be available in Java Core
• Maintenance: The legacy Java SDK is in maintenance mode and will only receive critical bug fixes

Installation Differences

Legacy Java/Kotlin SDK

gradle

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.

gradle

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.

Advanced: Platform-Specific Installation

If you need more control over dependencies or want to minimize the JAR size for a specific platform, you can install the core library and platform-specific native library separately:

gradle

repositories {
    mavenCentral()
}

dependencies {
    // Core library (required)
    implementation 'com.statsig:javacore:X.X.X'
    
    // Platform-specific library (required)
    implementation 'com.statsig:javacore:X.X.X:YOUR-OS-ARCHITECTURE'
}

To determine the correct platform-specific dependency, you can run this code:

import com.statsig.*;

StatsigOptions options = new StatsigOptions.Builder().build();
Statsig statsig = new Statsig("your-secret-key", options);

This will output the appropriate dependency for your system.

API Differences

Key Package and Class Changes

Feature	Legacy Java SDK	Java Core SDK
Package	com.statsig.sdk.*	com.statsig.*
Main Class	Statsig (static methods)	Statsig (instance methods)
Options	StatsigOptions	StatsigOptions.Builder()
User	StatsigUser	StatsigUser.Builder()
Check Gate	Statsig.checkGateSync()	statsig.checkGate()
Get Config	Statsig.getConfigSync()	statsig.getDynamicConfig()
Get Experiment	Statsig.getExperimentSync()	statsig.getExperiment()
Get Layer	Statsig.getLayerSync()	statsig.getLayer()
Log Event	Statsig.logEvent()	statsig.logEvent()

Initialization

Legacy Java SDK

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

Legacy Java SDK

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

Legacy Java SDK

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

Legacy Java SDK

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

Legacy Java SDK

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

Legacy Java SDK

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

Configuration Options Differences

Legacy Java SDK

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

Java Migration Steps

1. Update Dependencies

   • Replace com.statsig:serversdk with com.statsig:javacore:X.X.X:uber (recommended)
   • Alternatively, use platform-specific dependencies if you need to minimize JAR size

2. Update Imports

   • Replace import com.statsig.sdk.* with import com.statsig.*

3. Update Initialization

   • Change from static methods to instance methods
   • Use the builder pattern for options and StatsigUser
   • Replace new StatsigUser("user_id") with new StatsigUser.Builder().setUserID("user_id").build()
   • Initialize with new Statsig(key, options) and call initialize()

4. Update User Creation

   • Use the builder pattern: new StatsigUser.Builder().setUserID("user_id").build()

5. Update Method Calls

   • Replace static methods with instance methods
   • Remove Sync suffix from method names
   • Update method signatures as needed

6. Test Thoroughly

   • Verify all feature gates, experiments, and configs work as expected
   • Check that event logging is functioning correctly

Kotlin Migration Steps

1. Update Dependencies

   • Replace com.statsig:serversdk with com.statsig:javacore:X.X.X:uber (recommended)
   • Alternatively, use platform-specific dependencies if you need to minimize JAR size

2. Update Imports

   • Replace import com.statsig.sdk.* with import com.statsig.*

3. Update Initialization

   • Change from static methods to instance methods
   • Replace .apply {} blocks with the builder pattern
   • Replace val user = StatsigUser("user_id") with val user = StatsigUser.Builder().setUserID("user_id").build()
   • Initialize with val statsig = Statsig("key", options) and call initialize()

4. Update User Creation

   • Use the builder pattern: val user = StatsigUser.Builder().setUserID("user_id").build()

5. Update Method Calls

   • Replace static methods with instance methods
   • Remove Sync suffix from method names
   • Update method signatures as needed
   • Replace mapOf("key" to "value") with appropriate map creation methods

6. Test Thoroughly

   • Verify all feature gates, experiments, and configs work as expected
   • Check that event logging is functioning correctly

New Features in Java Core

Parameter Stores

Java Core introduces Parameter Stores, which allow you to 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, please reach out to us:

• Statsig Slack Community
• GitHub Issues