Перейти до змісту

Java Client for Remote Configuration

This is a library that simplifies communicating with the Joystick API for using remote configurations with your Java project. With remote configurations, you can instantly change the behavior and appearance of your application without code changes.

Joystick is a modern remote config platform where you manage all of your configurable parameters. We are natively multi-environment, preserve your version history, have advanced work-flow & permissions management, and much more. Have one API to use for any JSON configs.

Provided client is supporting Java 8+.


Before using the Joystick Java SDK in your project, you need to add maven dependency:



Using Joystick to get remote configurations in your Java project is a breeze.

// Add imports
import com.fasterxml.jackson.databind.JsonNode;
import com.getjoystick.sdk.Joystick;
import com.getjoystick.sdk.client.Client;
import com.getjoystick.sdk.client.ClientConfig;
import com.getjoystick.sdk.util.JoystickMapper;

// Get apiKey from environment variables java
String joystickApiKey = System.getenv("JOYSTICK_API_KEY");

// Initialize a client with a Joystick API Key
ClientConfig config = ClientConfig.builder().setApiKey(joystickApiKey).build();
Client client = Joystick.create(config);

// Request a single configuration as com.fasterxml.jackson.databind.JsonNode object
JsonNode content = client.getContent("idOfMyContent");

// Transform joystick response to custom class
MyCustomClass myObj = JoystickMapper.toObject(content, MyCustomClass.class);

// Request multiple configurations at the same time
List<String> contentIds = ImmutableList.of("contentId1", "contentId2");
Map<String, JsonNode> contentsMap = client.getContents(contentIds);

Specifying Additional Parameters

When creating the Joystick client, you can specify additional parameters which will be used by all API calls to the Joystick API. These additional parameters are used for AB Testing (userId), segmentation (params), and backward-compatible version delivery (semVer).

For more details see API documentation.

// Initializing a client with options
ClientConfig config = ClientConfig.builder()
    .setUserId("userId") // Any string
    .setSemVer("0.0.1") // String in the format of semantic versioning
    .setParams(ImmutableMap.of("Location", "Earth")) // Key-value pairs of strings, numbers, or booleans

Various Ways of Getting Configuration Content

With our Joystick java SDK, you can easily get the configuration response in different ways.

Single Configuration

Response Config as JSON Config as Serialized String
Config content only getContent getContentSerialized
Config content with additional meta data getFullContent getFullContentSerialized

Multiple Configurations

Response Config as JSON Config as Serialized String
Multiple configs content only getContents getContentsSerialized
Multiple configs content with additional meta data getFullContents getFullContentsSerialized

Error handling

The client can raise different types of exceptions with the base class of JoystickException.

try {
    Map<String, JsonNode> contentsMap = client.getContents(
        ImmutableList.of("contentId1", "contentId2")
catch (ApiHttpException e) {
    // Handle HTTP error (i.e. timeout, or invalid HTTP code)
catch (MultipleContentsApiException e) {
    // Handle API exception (i.e. content is not found, or some of the keys can't be retrieved)


By default, the client uses ApiCacheLRU, based on guava in memory Cache.

You can specify your own cache implementation by implementing the interface ApiCache. Sample code snippet could be found in examples

public class CaffeineCustomCache<K, V> implements ApiCache<K, V> {
    //implementation of base methods

// Setting custom cache
ClientConfig config = ClientConfig.builder()
    .setCache(new CaffeineCustomCache<>())

Default cache expiration is set to 300 seconds. It can be changed during ClientConfig build

// Setting CacheExpirationSeconds
ClientConfig config = ClientConfig.builder()

Refresh option

To ignore the existing cache when requesting a config, pass this option as true.

JoystickContentOptions options = new JoystickContentOptions(true);

JsonNode content = client.getContent("idOfMyContent", options);

// OR

Map<String, JsonNode> contentsMap = client.getContents(
        ImmutableList.of("contentId1", "contentId2"),


The MIT. Please see License File for more information.