Release 4.18.0

CHANGES.txt

@@ -1,3 +1,6 @@
+4.18.0 (Sep 12, 2025)
+- Added new configuration for Fallback Treatments, which allows setting a treatment value and optional config to be returned in place of "control", either globally or by flag. Read more in our docs.
+
 4.17.0 (Aug 22, 2025)
 - Added a maximum size payload when posting unique keys telemetry in batches
 - Added ProxyConfiguration parameter to support proxies, including Harness Forward Proxy, allowing also for more secured authentication options: MTLS, Bearer token and user/password authentication. Read more in our docs.

client/pom.xml

@@ -5,9 +5,9 @@
     <parent>
         <groupId>io.split.client</groupId>
         <artifactId>java-client-parent</artifactId>
-        <version>4.17.0</version>
+        <version>4.18.0</version>
     </parent>
-    <version>4.17.0</version>
+    <version>4.18.0</version>
     <artifactId>java-client</artifactId>
     <packaging>jar</packaging>
     <name>Java Client</name>

client/src/main/java/io/split/client/SplitClientConfig.java

@@ -1,5 +1,7 @@
 package io.split.client;
 
+import io.split.client.dtos.FallbackTreatment;
+import io.split.client.dtos.FallbackTreatmentsConfiguration;
 import io.split.client.dtos.ProxyConfiguration;
 import io.split.client.impressions.ImpressionListener;
 import io.split.client.impressions.ImpressionsManager;
@@ -16,10 +18,13 @@
 import java.util.HashSet;
 import java.util.LinkedHashSet;
 import java.util.List;
+import java.util.Map;
 import java.util.Properties;
 import java.util.concurrent.ThreadFactory;
 import java.io.InputStream;
 
+import static io.split.inputValidation.FallbackTreatmentValidator.isValidByFlagTreatment;
+import static io.split.inputValidation.FallbackTreatmentValidator.isValidTreatment;
 import static io.split.inputValidation.FlagSetsValidator.cleanup;
 
 /**
@@ -91,6 +96,7 @@ private HttpScheme() {
     private final CustomStorageWrapper _customStorageWrapper;
     private final StorageMode _storageMode;
     private final ThreadFactory _threadFactory;
+    private final FallbackTreatmentsConfiguration _fallbackTreatments;
 
     // Proxy configs
     private final ProxyConfiguration _proxyConfiguration;
@@ -163,7 +169,8 @@ private SplitClientConfig(String endpoint,
                               HashSet<String> flagSetsFilter,
                               int invalidSets,
                               CustomHeaderDecorator customHeaderDecorator,
-                              CustomHttpModule alternativeHTTPModule) {
+                              CustomHttpModule alternativeHTTPModule,
+                              FallbackTreatmentsConfiguration fallbackTreatments) {
         _endpoint = endpoint;
         _eventsEndpoint = eventsEndpoint;
         _featuresRefreshRate = pollForFeatureChangesEveryNSeconds;
@@ -218,6 +225,7 @@ private SplitClientConfig(String endpoint,
         _invalidSets = invalidSets;
         _customHeaderDecorator = customHeaderDecorator;
         _alternativeHTTPModule = alternativeHTTPModule;
+        _fallbackTreatments = fallbackTreatments;
 
         Properties props = new Properties();
         try {
@@ -436,6 +444,8 @@ public boolean isSdkEndpointOverridden() {
 
     public CustomHttpModule alternativeHTTPModule() { return _alternativeHTTPModule; }
 
+    public FallbackTreatmentsConfiguration fallbackTreatments() { return _fallbackTreatments; }
+
     public static final class Builder {
         private String _endpoint = SDK_ENDPOINT;
         private boolean _endpointSet = false;
@@ -494,6 +504,7 @@ public static final class Builder {
         private int _invalidSetsCount = 0;
         private CustomHeaderDecorator _customHeaderDecorator = null;
         private CustomHttpModule _alternativeHTTPModule = null;
+        private FallbackTreatmentsConfiguration _fallbackTreatments;
 
         public Builder() {
         }
@@ -1022,6 +1033,17 @@ public Builder alternativeHTTPModule(CustomHttpModule alternativeHTTPModule) {
             return this;
         }
 
+        /**
+         * Fallback Treatments
+         *
+         * @param fallbackTreatments
+         * @return this builder
+         */
+        public Builder fallbackTreatments(FallbackTreatmentsConfiguration fallbackTreatments) {
+            _fallbackTreatments = fallbackTreatments;
+            return this;
+        }
+
         /**
          * Thread Factory
          *
@@ -1158,6 +1180,25 @@ private void verifyProxy() {
             }
         }
 
+        private void verifyFallbackTreatments() {
+            if (_fallbackTreatments == null)
+                return;
+
+            FallbackTreatment processedGlobalFallbackTreatment = _fallbackTreatments.getGlobalFallbackTreatment();
+            Map<String, FallbackTreatment> processedByFlagFallbackTreatment = _fallbackTreatments.getByFlagFallbackTreatment();
+
+            if (_fallbackTreatments.getGlobalFallbackTreatment() != null) {
+                processedGlobalFallbackTreatment = new FallbackTreatment(
+                        isValidTreatment(_fallbackTreatments.getGlobalFallbackTreatment().getTreatment(), "Fallback treatments"),
+                        _fallbackTreatments.getGlobalFallbackTreatment().getConfig());
+            }
+
+            if (_fallbackTreatments.getByFlagFallbackTreatment() != null) {
+                processedByFlagFallbackTreatment = isValidByFlagTreatment(_fallbackTreatments.getByFlagFallbackTreatment(), "config");
+            }
+            _fallbackTreatments = new FallbackTreatmentsConfiguration(processedGlobalFallbackTreatment, processedByFlagFallbackTreatment);
+        }
+
         public SplitClientConfig build() {
 
             verifyRates();
@@ -1172,6 +1213,8 @@ public SplitClientConfig build() {
 
             verifyProxy();
 
+            verifyFallbackTreatments();
+
             if (_numThreadsForSegmentFetch <= 0) {
                 throw new IllegalArgumentException("Number of threads for fetching segments MUST be greater than zero");
             }
@@ -1230,7 +1273,8 @@ public SplitClientConfig build() {
                     _flagSetsFilter,
                     _invalidSetsCount,
                     _customHeaderDecorator,
-                    _alternativeHTTPModule);
+                    _alternativeHTTPModule,
+                    _fallbackTreatments);
         }
     }
 }

client/src/main/java/io/split/client/SplitClientImpl.java

@@ -3,9 +3,7 @@
 import com.google.gson.GsonBuilder;
 import io.split.client.api.Key;
 import io.split.client.api.SplitResult;
-import io.split.client.dtos.DecoratedImpression;
-import io.split.client.dtos.EvaluationOptions;
-import io.split.client.dtos.Event;
+import io.split.client.dtos.*;
 import io.split.client.events.EventsStorageProducer;
 import io.split.client.impressions.Impression;
 import io.split.client.impressions.ImpressionsManager;
@@ -14,7 +12,6 @@
 import io.split.engine.evaluator.Evaluator;
 import io.split.engine.evaluator.EvaluatorImp;
 import io.split.engine.evaluator.Labels;
-import io.split.grammar.Treatments;
 import io.split.inputValidation.EventsValidator;
 import io.split.inputValidation.KeyValidator;
 import io.split.inputValidation.SplitNameValidator;
@@ -49,7 +46,6 @@
  * @author adil
  */
 public final class SplitClientImpl implements SplitClient {
-    public static final SplitResult SPLIT_RESULT_CONTROL = new SplitResult(Treatments.CONTROL, null);
     private static final String CLIENT_DESTROY = "Client has already been destroyed - no calls possible";
     private static final String CATCHALL_EXCEPTION = "CatchAll Exception";
     private static final String MATCHING_KEY = "matchingKey";
@@ -66,6 +62,7 @@ public final class SplitClientImpl implements SplitClient {
     private final TelemetryEvaluationProducer _telemetryEvaluationProducer;
     private final TelemetryConfigProducer _telemetryConfigProducer;
     private final FlagSetsFilter _flagSetsFilter;
+    private final FallbackTreatmentCalculator _fallbackTreatmentCalculator;
 
     public SplitClientImpl(SplitFactory container,
                            SplitCacheConsumer splitCacheConsumer,
@@ -76,7 +73,8 @@ public SplitClientImpl(SplitFactory container,
                            Evaluator evaluator,
                            TelemetryEvaluationProducer telemetryEvaluationProducer,
                            TelemetryConfigProducer telemetryConfigProducer,
-                           FlagSetsFilter flagSetsFilter) {
+                           FlagSetsFilter flagSetsFilter,
+                           FallbackTreatmentCalculator fallbackTreatmentCalculator) {
         _container = container;
         _splitCacheConsumer = checkNotNull(splitCacheConsumer);
         _impressionManager = checkNotNull(impressionManager);
@@ -87,6 +85,7 @@ public SplitClientImpl(SplitFactory container,
         _telemetryEvaluationProducer = checkNotNull(telemetryEvaluationProducer);
         _telemetryConfigProducer = checkNotNull(telemetryConfigProducer);
         _flagSetsFilter = flagSetsFilter;
+        _fallbackTreatmentCalculator = fallbackTreatmentCalculator;
     }
 
     @Override
@@ -492,31 +491,34 @@ private SplitResult getTreatmentWithConfigInternal(String matchingKey, String bu
 
             if (_container.isDestroyed()) {
                 _log.error(CLIENT_DESTROY);
-                return SPLIT_RESULT_CONTROL;
+                return checkFallbackTreatment(featureFlag);
             }
 
             if (!KeyValidator.isValid(matchingKey, MATCHING_KEY, _config.maxStringLength(), methodEnum.getMethod())) {
-                return SPLIT_RESULT_CONTROL;
+                return checkFallbackTreatment(featureFlag);
             }
 
             if (!KeyValidator.bucketingKeyIsValid(bucketingKey, _config.maxStringLength(), methodEnum.getMethod())) {
-                return SPLIT_RESULT_CONTROL;
+                return checkFallbackTreatment(featureFlag);
             }
 
             Optional<String> splitNameResult = SplitNameValidator.isValid(featureFlag, methodEnum.getMethod());
             if (!splitNameResult.isPresent()) {
-                return SPLIT_RESULT_CONTROL;
+                return checkFallbackTreatment(featureFlag);
             }
             featureFlag = splitNameResult.get();
             long start = System.currentTimeMillis();
 
             EvaluatorImp.TreatmentLabelAndChangeNumber result = _evaluator.evaluateFeature(matchingKey, bucketingKey, featureFlag, attributes);
-
-            if (result.treatment.equals(Treatments.CONTROL) && result.label.equals(Labels.DEFINITION_NOT_FOUND) && _gates.isSDKReady()) {
-                _log.warn(String.format(
-                        "%s: you passed \"%s\" that does not exist in this environment, " +
-                                "please double check what feature flags exist in the Split user interface.", methodEnum.getMethod(), featureFlag));
-                return SPLIT_RESULT_CONTROL;
+            String label = result.label;
+            if (result.label != null && result.label.contains(Labels.DEFINITION_NOT_FOUND)) {
+                if (_gates.isSDKReady()) {
+                    _log.warn(String.format(
+                            "%s: you passed \"%s\" that does not exist in this environment, " +
+                            "please double check what feature flags exist in the Split user interface.", methodEnum.getMethod(), featureFlag));
+                    return checkFallbackTreatment(featureFlag);
+                }
+                label = result.label.replace(Labels.DEFINITION_NOT_FOUND, Labels.NOT_READY);
             }
 
             recordStats(
@@ -526,7 +528,7 @@ private SplitResult getTreatmentWithConfigInternal(String matchingKey, String bu
                     start,
                     result.treatment,
                     String.format("sdk.%s", methodEnum.getMethod()),
-                    _config.labelsEnabled() ? result.label : null,
+                    _config.labelsEnabled() ? label : null,
                     result.changeNumber,
                     attributes,
                     result.track,
@@ -541,8 +543,17 @@ private SplitResult getTreatmentWithConfigInternal(String matchingKey, String bu
             } catch (Exception e1) {
                 // ignore
             }
-            return SPLIT_RESULT_CONTROL;
+            return checkFallbackTreatment(featureFlag);
+        }
+    }
+
+    private SplitResult checkFallbackTreatment(String featureName) {
+        FallbackTreatment fallbackTreatment = _fallbackTreatmentCalculator.resolve(featureName, "");
+        String config = null;
+        if (fallbackTreatment.getConfig() != null) {
+            config = fallbackTreatment.getConfig();
         }
+        return new SplitResult(fallbackTreatment.getTreatment(), config);
     }
 
     private String validateProperties(Map<String, Object> properties) {
@@ -563,6 +574,7 @@ private Map<String, SplitResult> getTreatmentsWithConfigInternal(String matching
             _log.error(String.format("%s: featureFlagNames must be a non-empty array", methodEnum.getMethod()));
             return new HashMap<>();
         }
+
         try {
             checkSDKReady(methodEnum, featureFlagNames);
             Map<String, SplitResult> result = validateBeforeEvaluate(featureFlagNames, matchingKey, methodEnum, bucketingKey);
@@ -601,47 +613,47 @@ private Map<String, SplitResult> getTreatmentsBySetsWithConfigInternal(String ma
         if (cleanFlagSets.isEmpty()) {
             return new HashMap<>();
         }
-        List<String> featureFlagNames = new ArrayList<>();
-        try {
-            checkSDKReady(methodEnum);
-            Map<String, SplitResult> result = validateBeforeEvaluateByFlagSets(matchingKey, methodEnum,bucketingKey);
-            if(result != null) {
-                return result;
-            }
-            Map<String, EvaluatorImp.TreatmentLabelAndChangeNumber> evaluatorResult = _evaluator.evaluateFeaturesByFlagSets(matchingKey,
-                    bucketingKey, new ArrayList<>(cleanFlagSets), attributes);
+        checkSDKReady(methodEnum);
+        Map<String, SplitResult> result = validateBeforeEvaluateByFlagSets(matchingKey, methodEnum,bucketingKey);
+        if(result != null) {
+            return result;
+        }
+        Map<String, EvaluatorImp.TreatmentLabelAndChangeNumber> evaluatorResult = _evaluator.evaluateFeaturesByFlagSets(matchingKey,
+                bucketingKey, new ArrayList<>(cleanFlagSets), attributes);
 
-            return processEvaluatorResult(evaluatorResult, methodEnum, matchingKey, bucketingKey, attributes, initTime,
-                    validateProperties(evaluationOptions.getProperties()));
-        } catch (Exception e) {
-            try {
+        evaluatorResult.entrySet().forEach(flag -> {
+            if (flag.getValue().label != null &&
+                    flag.getValue().label.contains(io.split.engine.evaluator.Labels.EXCEPTION)) {
                 _telemetryEvaluationProducer.recordException(methodEnum);
-                _log.error(CATCHALL_EXCEPTION, e);
-            } catch (Exception e1) {
-                // ignore
             }
-            return createMapControl(featureFlagNames);
-        }
+        });
+        return processEvaluatorResult(evaluatorResult, methodEnum, matchingKey, bucketingKey, attributes, initTime,
+                validateProperties(evaluationOptions.getProperties()));
     }
+
     private Map<String, SplitResult> processEvaluatorResult(Map<String, EvaluatorImp.TreatmentLabelAndChangeNumber> evaluatorResult,
                                                             MethodEnum methodEnum, String matchingKey, String bucketingKey, Map<String,
                                                             Object> attributes, long initTime, String properties){
         List<DecoratedImpression> decoratedImpressions = new ArrayList<>();
         Map<String, SplitResult> result = new HashMap<>();
-        evaluatorResult.keySet().forEach(t -> {
-            if (evaluatorResult.get(t).treatment.equals(Treatments.CONTROL) && evaluatorResult.get(t).label.
-                    equals(Labels.DEFINITION_NOT_FOUND) && _gates.isSDKReady()) {
-                _log.warn(String.format("%s: you passed \"%s\" that does not exist in this environment please double check " +
-                        "what feature flags exist in the Split user interface.", methodEnum.getMethod(), t));
-                result.put(t, SPLIT_RESULT_CONTROL);
-            } else {
-                result.put(t, new SplitResult(evaluatorResult.get(t).treatment, evaluatorResult.get(t).configurations));
-                decoratedImpressions.add(
-                        new DecoratedImpression(
-                                new Impression(matchingKey, bucketingKey, t, evaluatorResult.get(t).treatment, System.currentTimeMillis(),
-                        evaluatorResult.get(t).label, evaluatorResult.get(t).changeNumber, attributes, properties),
-                                evaluatorResult.get(t).track));
+        evaluatorResult.keySet().forEach(flag -> {
+            String label = evaluatorResult.get(flag).label;
+            if (evaluatorResult.get(flag).label != null &&
+                    evaluatorResult.get(flag).label.contains(Labels.DEFINITION_NOT_FOUND)) {
+                if (_gates.isSDKReady()) {
+                    _log.warn(String.format("%s: you passed \"%s\" that does not exist in this environment please double check " +
+                            "what feature flags exist in the Split user interface.", methodEnum.getMethod(), flag));
+                    result.put(flag, checkFallbackTreatment(flag));
+                    return;
+                }
+                label = evaluatorResult.get(flag).label.replace(Labels.DEFINITION_NOT_FOUND, Labels.NOT_READY);
             }
+            result.put(flag, new SplitResult(evaluatorResult.get(flag).treatment, evaluatorResult.get(flag).configurations));
+            decoratedImpressions.add(
+                    new DecoratedImpression(
+                            new Impression(matchingKey, bucketingKey, flag, evaluatorResult.get(flag).treatment, System.currentTimeMillis(),
+                    label, evaluatorResult.get(flag).changeNumber, attributes, properties),
+                            evaluatorResult.get(flag).track));
         });
         _telemetryEvaluationProducer.recordLatency(methodEnum, System.currentTimeMillis() - initTime);
         if (!decoratedImpressions.isEmpty()) {
@@ -735,7 +747,7 @@ private void checkSDKReady(MethodEnum methodEnum) {
 
     private Map<String, SplitResult> createMapControl(List<String> featureFlags) {
         Map<String, SplitResult> result = new HashMap<>();
-        featureFlags.forEach(s -> result.put(s, SPLIT_RESULT_CONTROL));
+        featureFlags.forEach(s -> result.put(s, checkFallbackTreatment(s)));
         return result;
     }
 }