Decide methods for the Java SDK

22 min

Use the decide methods to return feature flag decisions for a user. Each decision includes whether the flag is enabled and which variation the user receives.

Decide

Returns a decision for a specific feature flag and user.

Minimum SDK version – v3.8+

Description

The decide method handles the variation decision for an individual experiment. It returns a decision result for a flag key for a user in an OptimizelyDecision object and contains the data required to deliver the flag rule.

This method ensures that Feature Experimentation properly buckets the user in experiment analytics, and you should use it if there is no need for pre-rendering decisions.

Decide is a method of the UserContext object. See OptimizelyUserContext for details.

See OptimizelyDecision for details of the returned decision object.

Key features

Single experiment decision – Returns the variation for a specific experiment.

Bucketing in results – Ensures Feature Experimentation records the user in the experiment results page for proper analysis.

Complement to decide all method – If you use the decide all method to pre-fetch variations, you should also call the decide method for each experiment that the user interacts with. This dual approach guarantees that Feature Experimentation accurately tracks the user's participation and that the correct variation is served through caching.

CMAB support – For CMAB experiments, decisions are automatically cached to reduce latency. The cache is invalidated when CMAB attributes change or TTL expires. Use CMAB-specific decide options (IGNORE_CMAB_CACHE, INVALIDATE_USER_CMAB_CACHE, and RESET_CMAB_CACHE) to override default caching behavior. See the following CMAB cache control information.

Parameters

The following table describes the parameters for the decide method:

Parameter	Type	Description
flagKey	String	The key of the feature flag
options (optional)	Array	An array of OptimizelyDecideOption enums.

Returns

The decide method returns an OptimizelyDecision object.

If the method encounters a critical error (for example, SDK not ready or invalid flag key), then it returns a decision with a null variationKey field and populates the Reasons field with error messages (regardless of the OptimizelyDecideOption.INCLUDE_REASONS option).

Example decide

import com.optimizely.ab.Optimizely;
import com.optimizely.ab.OptimizelyUserContext;
import com.optimizely.ab.optimizelydecision.OptimizelyDecision;
import com.optimizely.ab.optimizelyjson.OptimizelyJSON;
import com.fasterxml.jackson.core.JsonParseException;

import java.util.HashMap;
import java.util.List;
import java.util.Map;

// Create the user and decide which flag rule and variation they bucket into 
Map<String, Object> attributes = new HashMap<>();
attributes.put("logged_in", true);
OptimizelyUserContext user = optimizely.createUserContext(userId, attributes);

OptimizelyDecision decision = user.decide("product_sort");

// The variation key. If null, decision failed with a critical error.
String variationKey = decision.getVariationKey();

// The flag enabled state
boolean enabled = decision.getEnabled();

// All variable values
OptimizelyJSON variables = decision.getVariables();

// String variable value
String sortMethod = null;
try {
    sortMethod = variables.getValue("sort_method", String.class);
} catch (JsonParseException e) {
    e.printStackTrace();
}

// An alternative way to access a variable value
Boolean vb = (Boolean) variables.toMap().get("k_boolean");

// Flag key for which the decision was made
String flagKey = decision.getFlagKey();

// A copy of the user context for which the decision was made
OptimizelyUserContext userContext = decision.getUserContext();
   
// Reasons for the decision
List<String> reasons = decision.getReasons();

Side Effect

Invokes the decision notification listener if this listener is enabled.

Decide all

Returns decisions for all active (unarchived) flags for a user.

Minimum SDK version – v3.8+

Description

Use the decide all method to retrieve decisions for all active flags before rendering content. This is particularly useful when you need to serve the correct cached version of your page or component based on the user's variation. For example when using an edge worker or cloud function.

Key features

Pre-rendering decision – Lets you know all variation assignments ahead of time.

Cache control – Lets you serve the correct cached content based on the user's pre-determined variations.

Delay experiment tracking – Use DISABLE_DECISION_EVENT to prevent the SDK from recording a decision before the user sees the feature. This ensures that participation is only tracked when the experience is delivered.

CMAB support – For CMAB experiments (SDK v5.2.0+), decisions are automatically cached to reduce latency. The cache is invalidated when CMAB attributes change or TTL expires. Use CMAB-specific decide options (ignoreCmabCache, invalidateUserCmabCache, resetCmabCache) to override default caching behavior. See CMAB cache control.

Parameters

The following table describes the parameters for the decide all method:

Parameter	Type	Description
options (optional)	Array	Array of OptimizelyDecideOption enums.

Returns

The decide all method returns a map of OptimizelyDecision objects. For information, see OptimizelyDecision.

If the method fails for all flags (for example, the SDK is not ready or the user context is invalid), it returns an empty map. If the method detects an error for a specific flag, it returns error messages in the Reasons field of the decision for that flag.

Example decideAll

import com.optimizely.ab.optimizelydecision.OptimizelyDecideOption;
import com.optimizely.ab.optimizelydecision.OptimizelyDecision;

import java.util.Arrays;
import java.util.List;
import java.util.Map;
import java.util.Set;

// Make decisions for all active (unarchived) flags in the project for a user
List<OptimizelyDecideOption> options = Arrays.asList(OptimizelyDecideOption.ENABLED_FLAGS_ONLY);
Map<String, OptimizelyDecision> decisions = user.decideAll(options);

Set<String> allKeys = decisions.keySet();
OptimizelyDecision decisionForFlag1 = decisions.get("flag_1");

Side effect

Invokes the decision notification listener for each decision if this listener is enabled.

Decide for keys

Returns a map of flag decisions for specified flag keys.

Minimum SDK version – v3.8+

Description

Returns a map of decisions for the specified flag keys.

Parameters

The following table describes the parameters for the decide for keys method:

Parameter	Type	Description
keys	Array	Array of string flag keys.
options (optional)	Array	Array of OptimizelyDecideOption enums.

Returns

Returns a map of OptimizelyDecision.

Example decideForKeys

// Make decisions for specific flags
List<String> keys = Arrays.asList("flag-1", "flag-2");
Map<String, OptimizelyDecision> decisions = user.decideForKeys(keys);
        
OptimizelyDecision decision1 = decisions.get("flag-1");
OptimizelyDecision decision2 = decisions.get("flag-2");

Side effect

Invokes the decision notification listener for each decision if this listener is enabled.

OptimizelyDecideOption

The following table lists the OptimizelyDecideOption enum with an explanation what happens if you set them. In addition to setting these options individually for a decide method, you can also set them as global defaults when you instantiate the Optimizely client. See Initialize the Java SDK.

OptimizelyDecideOption enum	If set
OptimizelyDecideOption.DISABLE_DECISION_EVENT	Prevents the SDK from dispatching an impression event when serving a variation. This disables decision tracking on the Optimizely Experiment Results page and the decision notification listener.
OptimizelyDecideOption.ENABLED_FLAGS_ONLY	Returns decisions only for flags that are currently enabled. Used with the decide all method and decide for keys method. When this option is not set, the Android SDK returns all decisions regardless of whether the flag is enabled.
OptimizelyDecideOption.IGNORE_USER_PROFILE_SERVICE	Bypasses the user profile service (both lookup and save) for the decision. When this option is not set, user profile service overrides audience targeting, traffic allocation, and experiment mutual exclusion groups.
OptimizelyDecideOption.INCLUDE_REASONS	Adds log messages to the reasons field of the decision. Critical errors are always returned, even if this option is not set.
OptimizelyDecideOption.EXCLUDE_VARIABLES	Excludes flag variable values from the decision result. Use this option to minimize the returned decision by skipping large JSON variables.
OptimizelyDecideOption.IGNORE_CMAB_CACHE	Bypasses the CMAB cache and fetches a fresh decision from the CMAB service. Use when you need real-time decisions that reflect the latest context.
OptimizelyDecideOption.INVALIDATE_USER_CMAB_CACHE	Removes the cached CMAB decision for this user and experiment before making the decision. Use when user context has changed significantly and you want to ensure a fresh decision.
OptimizelyDecideOption.RESET_CMAB_CACHE	Clears all entries from the CMAB cache before making the decision. Use sparingly for testing or cache corruption scenarios.

The following code sample shows how to implement the OptimizelyDecideOption as a global default and locally in a decide method call.

import com.optimizely.ab.Optimizely;
import com.optimizely.ab.OptimizelyUserContext;
import com.optimizely.ab.config.HttpProjectConfigManager;
import com.optimizely.ab.config.ProjectConfigManager;
import com.optimizely.ab.optimizelydecision.OptimizelyDecideOption;
import com.optimizely.ab.optimizelydecision.OptimizelyDecision;

import java.util.Arrays;
import java.util.List;
import java.util.Map;

// Set global default decide options when initializing the client
ProjectConfigManager configManager = HttpProjectConfigManager.builder()
    .withSdkKey(sdkKey)
    .build();
    
List<OptimizelyDecideOption> defaultOptions = Arrays.asList(OptimizelyDecideOption.DISABLE_DECISION_EVENT);

Optimizely optimizely = Optimizely.builder()
    .withConfigManager(configManager)
    .withDefaultDecideOptions(defaultOptions)
    .build();

// Set additional options in a decide call
OptimizelyUserContext user = optimizely.createUserContext("user123");
List<OptimizelyDecideOption> additionalOptions = Arrays.asList(
    OptimizelyDecideOption.ENABLED_FLAGS_ONLY, 
    OptimizelyDecideOption.DISABLE_DECISION_EVENT
);

Map<String, OptimizelyDecision> decisions = user.decideAll(additionalOptions);

CMAB cache control

Minimum SDK version – v4.3.0+

For Contextual Multi-Armed Bandit (CMAB) experiments, the Java SDK automatically caches variation assignments to reduce latency and API calls. The cache stores decisions based on user ID, experiment ID, and CMAB attribute values.

Automatic cache invalidation

The cache is automatically invalidated when

The cached entry's TTL expires (default: 30 minutes).

CMAB attribute values change for a user (detected through attribute hash comparison).

Manual cache control

Use CMAB-specific decide options to control cache behavior on a per-decision basis.

import com.optimizely.ab.Optimizely;
import com.optimizely.ab.OptimizelyFactory;
import com.optimizely.ab.OptimizelyUserContext;
import com.optimizely.ab.optimizelydecision.OptimizelyDecideOption;
import com.optimizely.ab.optimizelydecision.OptimizelyDecision;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

// Initialize the Optimizely client
Optimizely optimizelyClient = OptimizelyFactory.newDefaultInstance("SDK_KEY_HERE");

// Example 1: Use default cmab and caching logic
Map<String, Object> attributes = new HashMap<>();
attributes.put("age", 25);
attributes.put("location", "US");
OptimizelyUserContext user = optimizelyClient.createUserContext("user123", attributes);
OptimizelyDecision decision = user.decide("my-cmab-flag");

// Example 2: Invalidate cache when user context changes significantly
Map<String, Object> updatedAttributes = new HashMap<>();
updatedAttributes.put("age", 26);
updatedAttributes.put("location", "UK");  // Context changed
OptimizelyUserContext updatedUser = optimizelyClient.createUserContext("user123", updatedAttributes);
OptimizelyDecision decision2 = updatedUser.decide("my-cmab-flag", Arrays.asList(
    OptimizelyDecideOption.INVALIDATE_USER_CMAB_CACHE  // Clear cached decision for this user
));

// Example 3: Reset entire CMAB cache (use sparingly)
OptimizelyDecision decision3 = user.decide("my-cmab-flag", Arrays.asList(
    OptimizelyDecideOption.RESET_CMAB_CACHE  // Clear all CMAB cache entries
));

CMAB decision reasons

When using INCLUDE_REASONS, CMAB-related information appears in the decision's reasons field.

OptimizelyDecision decision = user.decide("my-cmab-flag", Arrays.asList(
    OptimizelyDecideOption.INCLUDE_REASONS
));

// Print CMAB-related decision reasons
for (String reason : decision.getReasons()) {
    System.out.println(reason);
    // Examples:
    // "Failed to fetch CMAB data for experiment exp_001"
    // "Successfully fetched CMAB decision CmabDecision{variationId='1802219', cmabUUID='7ca158c0-e664-4a13-952b-11f996192738'} for experiment exp_001."
}

Configure cache settings

Configure CMAB cache settings (size, TTL) at client initialization time using the builder pattern.

import com.optimizely.ab.Optimizely;
import com.optimizely.ab.config.HttpProjectConfigManager;
import com.optimizely.ab.cmab.DefaultCmabClient;
import com.optimizely.ab.cmab.service.DefaultCmabService;
import com.optimizely.ab.event.BatchEventProcessor;

// Create CMAB service with custom cache settings
DefaultCmabClient cmabClient = new DefaultCmabClient();
DefaultCmabService cmabService = DefaultCmabService.builder()
    .withClient(cmabClient)
    .withCmabCacheSize(5000)                    // Set cache size (default: 10000)
    .withCmabCacheTimeoutInSecs(3600)           // Set TTL in seconds (default: 1800 = 30 minutes)
    .build();

// Or provide a custom cache implementation
import com.optimizely.ab.internal.Cache;
import com.optimizely.ab.internal.DefaultLRUCache;
import com.optimizely.ab.cmab.service.CmabCacheValue;

Cache<CmabCacheValue> customCache = new DefaultLRUCache<>(5000, 3600);
DefaultCmabService cmabServiceWithCustomCache = DefaultCmabService.builder()
    .withClient(cmabClient)
    .withCustomCache(customCache)
    .build();

// Build Optimizely client with custom CMAB service
HttpProjectConfigManager configManager = HttpProjectConfigManager.builder()
    .withSdkKey("SDK_KEY_HERE")
    .build();

Optimizely optimizelyClient = Optimizely.builder()
    .withConfigManager(configManager)
    .withCmabService(cmabService)
    .build();

Configure CMAB cache settings (size, TTL, and timeout) at client initialization time. See Initialize the Java SDK and Configure the CMAB cache for the Java SDK for details.

Source files

The language and platform source files containing the implementation for Java are available on GitHub.