Skip to main content

Migrating from Legacy Java SDK to Java Core

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 evaluates 3-5x faster 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​

repositories {
    mavenCentral()
}

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

Java Core SDK​

Java Core requires both the core library and a platform-specific native library:

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​

FeatureLegacy Java SDKJava Core SDK
Packagecom.statsig.sdk.*com.statsig.*
Main ClassStatsig (static methods)Statsig (instance methods)
OptionsStatsigOptionsStatsigOptions.Builder()
UserStatsigUserStatsigUser.Builder()
Check GateStatsig.checkGateSync()statsig.checkGate()
Get ConfigStatsig.getConfigSync()statsig.getDynamicConfig()
Get ExperimentStatsig.getExperimentSync()statsig.getExperiment()
Get LayerStatsig.getLayerSync()statsig.getLayer()
Log EventStatsig.logEvent()statsig.logEvent()

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​

  1. Update Dependencies

    • Replace com.statsig:serversdk with com.statsig:javacore
    • Add the platform-specific dependency

  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

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: