MACRO NEPAL
Feature Flag Mastery: Implementing Split.io in Java for Controlled Releases
awiskar acharya
November 18, 2025
8:38 am

Feature flags (feature toggles) are a powerful technique that allows you to deploy code changes safely, perform A/B testing, and manage feature releases without redeploying your application. Split.io is a leading feature flag and experimentation platform that provides sophisticated targeting, real-time control, and detailed metrics.

What are Feature Flags?

Feature flags are conditional statements that control whether features are enabled for specific users, environments, or conditions. They enable:

  • Trunk-based development without feature branches
  • Gradual rollouts and canary releases
  • Instant kill switches for problematic features
  • A/B testing and experimentation
  • User-specific targeting and personalization

Split.io Architecture

[Java Application] → [Split SDK] → [Split Cloud] ← [Split UI]
|                  |              |             |
Check feature       Local cache    Rule storage   Management
flags locally      with polling    and targeting   console

Hands-On Tutorial: Implementing Split.io in Spring Boot

Let's build a complete e-commerce application with feature flags for controlled rollouts, experimentation, and operational control.

Step 1: Project Setup and Dependencies

Maven Dependencies (pom.xml):

<properties>
<spring-boot.version>3.2.0</spring-boot.version>
<split.version>4.4.2</split.version>
</properties>
<dependencies>
<!-- Spring Boot -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<version>${spring-boot.version}</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
<version>${spring-boot.version}</version>
</dependency>
<!-- Split.io SDK -->
<dependency>
<groupId>io.split.client</groupId>
<artifactId>split-client-java</artifactId>
<version>${split.version}</version>
</dependency>
<!-- Configuration -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-configuration-processor</artifactId>
<version>${spring-boot.version}</version>
<optional>true</optional>
</dependency>
<!-- Caching -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-cache</artifactId>
<version>${spring-boot.version}</version>
</dependency>
<!-- Monitoring -->
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-core</artifactId>
</dependency>
</dependencies>

Step 2: Configuration

application.yml:

split:
io:
api-key: ${SPLIT_IO_API_KEY:localhost}
# Use 'localhost' for development without API key
environment: ${SPLIT_IO_ENVIRONMENT:development}
# Configuration options
features-refresh-rate: 30
segments-refresh-rate: 60
impressions-refresh-rate: 30
metrics-refresh-rate: 30
connection-timeout: 15000
read-timeout: 15000
# Localhost mode (for development)
localhost-feature-flags:
new-checkout-ui: on
premium-features: off
recommendation-engine: on:user_premium
search-v2: off
promotional-banner: on:50%
app:
feature-flags:
# Feature names
new-checkout-ui: new_checkout_ui
premium-features: premium_features
recommendation-engine: recommendation_engine_v2
search-v2: search_algorithm_v2
promotional-banner: promotional_banner_holiday
dark-mode: dark_mode_toggle
payment-methods: new_payment_methods

Split.io Configuration Class:

@Configuration
@ConfigurationProperties(prefix = "split.io")
@Validated
public class SplitIOConfig {
@NotBlank
private String apiKey;
private String environment = "development";
private int featuresRefreshRate = 30;
private int segmentsRefreshRate = 60;
private int impressionsRefreshRate = 30;
private int metricsRefreshRate = 30;
private int connectionTimeout = 15000;
private int readTimeout = 15000;
private Map<String, String> localhostFeatureFlags = new HashMap<>();
// Getters and setters
public String getApiKey() { return apiKey; }
public void setApiKey(String apiKey) { this.apiKey = apiKey; }
public String getEnvironment() { return environment; }
public void setEnvironment(String environment) { this.environment = environment; }
public int getFeaturesRefreshRate() { return featuresRefreshRate; }
public void setFeaturesRefreshRate(int featuresRefreshRate) { this.featuresRefreshRate = featuresRefreshRate; }
public int getSegmentsRefreshRate() { return segmentsRefreshRate; }
public void setSegmentsRefreshRate(int segmentsRefreshRate) { this.segmentsRefreshRate = segmentsRefreshRate; }
public int getImpressionsRefreshRate() { return impressionsRefreshRate; }
public void setImpressionsRefreshRate(int impressionsRefreshRate) { this.impressionsRefreshRate = impressionsRefreshRate; }
public int getMetricsRefreshRate() { return metricsRefreshRate; }
public void setMetricsRefreshRate(int metricsRefreshRate) { this.metricsRefreshRate = metricsRefreshRate; }
public int getConnectionTimeout() { return connectionTimeout; }
public void setConnectionTimeout(int connectionTimeout) { this.connectionTimeout = connectionTimeout; }
public int getReadTimeout() { return readTimeout; }
public void setReadTimeout(int readTimeout) { this.readTimeout = readTimeout; }
public Map<String, String> getLocalhostFeatureFlags() { return localhostFeatureFlags; }
public void setLocalhostFeatureFlags(Map<String, String> localhostFeatureFlags) { this.localhostFeatureFlags = localhostFeatureFlags; }
}

Step 3: Split.io Client Factory

@Configuration
@EnableCaching
public class SplitIOConfiguration {
private static final Logger logger = LoggerFactory.getLogger(SplitIOConfiguration.class);
private final SplitIOConfig config;
public SplitIOConfiguration(SplitIOConfig config) {
this.config = config;
}
@Bean
@Primary
public SplitClient splitClient() {
try {
SplitClientConfig clientConfig = SplitClientConfig.builder()
.setBlockUntilReadyTimeout(10000)
.featuresRefreshRate(config.getFeaturesRefreshRate())
.segmentsRefreshRate(config.getSegmentsRefreshRate())
.impressionsRefreshRate(config.getImpressionsRefreshRate())
.metricsRefreshRate(config.getMetricsRefreshRate())
.connectionTimeout(config.getConnectionTimeout())
.readTimeout(config.getReadTimeout())
.build();
SplitFactory splitFactory;
if ("localhost".equals(config.getApiKey())) {
logger.info("Initializing Split.io in LOCALHOST mode");
splitFactory = localhostSplitFactory();
} else {
logger.info("Initializing Split.io in PRODUCTION mode");
splitFactory = SplitFactoryBuilder.build(config.getApiKey(), clientConfig);
}
splitFactory.client().blockUntilReady();
logger.info("Split.io client initialized successfully");
return splitFactory.client();
} catch (Exception e) {
logger.error("Failed to initialize Split.io client", e);
throw new RuntimeException("Split.io initialization failed", e);
}
}
@Bean
public SplitManager splitManager(SplitClient splitClient) {
return splitClient.getSplitManager();
}
/**
* Localhost factory for development without API key
*/
private SplitFactory localhostSplitFactory() {
Map<String, String> featureFlags = config.getLocalhostFeatureFlags();
LocalhostSplitFactory localhostFactory = new LocalhostSplitFactory();
// Set up local feature flags
featureFlags.forEach((featureName, treatment) -> {
localhostFactory.getFeatureFlagRegistry().register(
featureName, 
parseLocalhostTreatment(treatment)
);
});
return localhostFactory;
}
/**
* Parse localhost treatment strings like "on", "off", "on:50%", "on:user_premium"
*/
private Consumer<LocalhostSplit> parseLocalhostTreatment(String treatment) {
if ("on".equalsIgnoreCase(treatment)) {
return split -> split.setTreatment("on");
} else if ("off".equalsIgnoreCase(treatment)) {
return split -> split.setTreatment("off");
} else if (treatment.startsWith("on:")) {
String target = treatment.substring(3);
if (target.endsWith("%")) {
// Percentage rollout
int percentage = Integer.parseInt(target.substring(0, target.length() - 1));
return split -> split.setTreatment("on", percentage);
} else {
// Targeted rollout
return split -> split.setTreatment("on", Collections.singleton(target));
}
}
return split -> split.setTreatment("off");
}
@PreDestroy
public void destroy() {
try {
if (splitClient() != null) {
splitClient().destroy();
logger.info("Split.io client destroyed successfully");
}
} catch (Exception e) {
logger.error("Error destroying Split.io client", e);
}
}
}

Step 4: Feature Flag Service

@Service
@Slf4j
public class FeatureFlagService {
private final SplitClient splitClient;
private final SplitManager splitManager;
private final ObjectMapper objectMapper;
// Feature flag names (should match Split.io dashboard)
public static final String NEW_CHECKOUT_UI = "new_checkout_ui";
public static final String PREMIUM_FEATURES = "premium_features";
public static final String RECOMMENDATION_ENGINE_V2 = "recommendation_engine_v2";
public static final String SEARCH_ALGORITHM_V2 = "search_algorithm_v2";
public static final String PROMOTIONAL_BANNER = "promotional_banner_holiday";
public static final String DARK_MODE = "dark_mode_toggle";
public static final String NEW_PAYMENT_METHODS = "new_payment_methods";
public FeatureFlagService(SplitClient splitClient, 
SplitManager splitManager,
ObjectMapper objectMapper) {
this.splitClient = splitClient;
this.splitManager = splitManager;
this.objectMapper = objectMapper;
}
/**
* Basic feature flag check with user context
*/
public boolean isFeatureEnabled(String featureFlag, UserContext userContext) {
return "on".equals(getTreatment(featureFlag, userContext));
}
/**
* Get treatment with user context
*/
public String getTreatment(String featureFlag, UserContext userContext) {
try {
String treatment = splitClient.getTreatment(
userContext.getUserId(), 
featureFlag, 
userContext.getAttributes()
);
log.debug("Feature flag '{}' treatment for user {}: {}", 
featureFlag, userContext.getUserId(), treatment);
return treatment;
} catch (Exception e) {
log.error("Error getting treatment for feature flag: {}", featureFlag, e);
return "off"; // Fail safe
}
}
/**
* Get treatment with JSON configuration
*/
public <T> T getTreatmentWithConfig(String featureFlag, 
UserContext userContext, 
Class<T> configType) {
try {
SplitResult result = splitClient.getTreatmentWithConfig(
userContext.getUserId(),
featureFlag,
userContext.getAttributes()
);
log.debug("Feature flag '{}' treatment with config for user {}: {}", 
featureFlag, userContext.getUserId(), result.treatment());
// Parse configuration if provided
if ("on".equals(result.treatment()) && 
result.config() != null && 
!result.config().trim().isEmpty()) {
try {
return objectMapper.readValue(result.config(), configType);
} catch (Exception e) {
log.error("Failed to parse feature flag config for {}: {}", 
featureFlag, result.config(), e);
}
}
return null;
} catch (Exception e) {
log.error("Error getting treatment with config for feature flag: {}", featureFlag, e);
return null;
}
}
/**
* Track feature flag exposure for analytics
*/
public void trackExposure(String featureFlag, UserContext userContext, String treatment) {
try {
splitClient.track(
userContext.getUserId(),
"user",
"feature_flag_exposure",
null, // value
createEventProperties(featureFlag, treatment, userContext)
);
log.debug("Tracked feature flag exposure: {} - {} for user {}", 
featureFlag, treatment, userContext.getUserId());
} catch (Exception e) {
log.error("Error tracking feature flag exposure: {}", featureFlag, e);
}
}
/**
* Get all available feature flags
*/
public List<SplitView> getAllFeatureFlags() {
try {
return splitManager.splits();
} catch (Exception e) {
log.error("Error getting feature flags list", e);
return Collections.emptyList();
}
}
/**
* Check if feature flag exists
*/
public boolean featureFlagExists(String featureFlag) {
try {
return splitManager.split(featureFlag) != null;
} catch (Exception e) {
log.error("Error checking if feature flag exists: {}", featureFlag, e);
return false;
}
}
/**
* Bulk check multiple feature flags
*/
public Map<String, Boolean> bulkCheckFeatures(UserContext userContext, String... featureFlags) {
Map<String, Boolean> results = new HashMap<>();
for (String featureFlag : featureFlags) {
results.put(featureFlag, isFeatureEnabled(featureFlag, userContext));
}
return results;
}
/**
* Feature flag with percentage rollout
*/
public boolean isFeatureEnabledForPercentage(String featureFlag, 
UserContext userContext, 
int fallbackPercentage) {
String treatment = getTreatment(featureFlag, userContext);
if ("on".equals(treatment)) {
return true;
} else if ("off".equals(treatment)) {
return false;
} else {
// Handle percentage-based treatments
return isUserInPercentage(userContext.getUserId(), fallbackPercentage);
}
}
private boolean isUserInPercentage(String userId, int percentage) {
// Simple hash-based percentage calculation
int hash = Math.abs(userId.hashCode()) % 100;
return hash < percentage;
}
private Map<String, Object> createEventProperties(String featureFlag, 
String treatment, 
UserContext userContext) {
Map<String, Object> properties = new HashMap<>();
properties.put("feature_flag", featureFlag);
properties.put("treatment", treatment);
properties.put("user_id", userContext.getUserId());
properties.put("timestamp", Instant.now().toString());
properties.put("environment", getEnvironment());
// Add user attributes for segmentation
if (userContext.getAttributes() != null) {
properties.putAll(userContext.getAttributes());
}
return properties;
}
private String getEnvironment() {
return System.getenv().getOrDefault("SPLIT_ENV", "development");
}
}

Step 5: User Context Model

public class UserContext {
private final String userId;
private final Map<String, Object> attributes;
public UserContext(String userId) {
this(userId, new HashMap<>());
}
public UserContext(String userId, Map<String, Object> attributes) {
this.userId = userId;
this.attributes = attributes != null ? new HashMap<>(attributes) : new HashMap<>();
}
// Builder pattern for fluent creation
public static UserContext of(String userId) {
return new UserContext(userId);
}
public UserContext withAttribute(String key, Object value) {
this.attributes.put(key, value);
return this;
}
public UserContext withAttributes(Map<String, Object> additionalAttributes) {
this.attributes.putAll(additionalAttributes);
return this;
}
public UserContext withPlan(String plan) {
return withAttribute("plan", plan);
}
public UserContext withCountry(String country) {
return withAttribute("country", country);
}
public UserContext withDevice(String device) {
return withAttribute("device", device);
}
public UserContext withRegistrationDate(LocalDate registrationDate) {
return withAttribute("registration_date", registrationDate.toString());
}
// Getters
public String getUserId() { return userId; }
public Map<String, Object> getAttributes() { return Collections.unmodifiableMap(attributes); }
// Common attribute keys
public static class Attributes {
public static final String PLAN = "plan";
public static final String COUNTRY = "country";
public static final String DEVICE = "device";
public static final String REGISTRATION_DATE = "registration_date";
public static final String USER_AGE = "user_age";
public static final String SEGMENT = "segment";
}
// Common user segments
public static class Segments {
public static final String BETA_TESTERS = "beta_testers";
public static final String PREMIUM_USERS = "premium_users";
public static final String NEW_USERS = "new_users";
public static final String POWER_USERS = "power_users";
}
}

Step 6: Feature-Specific Services

Checkout Service with Feature Flags:

@Service
@Slf4j
public class CheckoutService {
private final FeatureFlagService featureFlagService;
private final PaymentService paymentService;
public CheckoutService(FeatureFlagService featureFlagService,
PaymentService paymentService) {
this.featureFlagService = featureFlagService;
this.paymentService = paymentService;
}
/**
* Process checkout with feature-flagged improvements
*/
public CheckoutResult processCheckout(CheckoutRequest request, UserContext userContext) {
log.info("Processing checkout for user: {}", userContext.getUserId());
// Check if new checkout UI is enabled for this user
boolean newCheckoutEnabled = featureFlagService.isFeatureEnabled(
FeatureFlagService.NEW_CHECKOUT_UI, userContext
);
// Track exposure for analytics
featureFlagService.trackExposure(
FeatureFlagService.NEW_CHECKOUT_UI, 
userContext, 
newCheckoutEnabled ? "on" : "off"
);
CheckoutResult result;
if (newCheckoutEnabled) {
result = processCheckoutV2(request, userContext);
} else {
result = processCheckoutV1(request, userContext);
}
return result;
}
/**
* New checkout flow with additional features
*/
private CheckoutResult processCheckoutV2(CheckoutRequest request, UserContext userContext) {
log.info("Using new checkout flow for user: {}", userContext.getUserId());
// Check for additional feature flags
boolean newPaymentMethods = featureFlagService.isFeatureEnabled(
FeatureFlagService.NEW_PAYMENT_METHODS, userContext
);
CheckoutConfig config = featureFlagService.getTreatmentWithConfig(
FeatureFlagService.NEW_CHECKOUT_UI,
userContext,
CheckoutConfig.class
);
// Apply configuration from feature flag
if (config != null) {
applyCheckoutConfig(request, config);
}
// Process with new payment methods if enabled
if (newPaymentMethods) {
return paymentService.processWithNewMethods(request, userContext);
} else {
return paymentService.processWithLegacyMethods(request, userContext);
}
}
/**
* Legacy checkout flow
*/
private CheckoutResult processCheckoutV1(CheckoutRequest request, UserContext userContext) {
log.info("Using legacy checkout flow for user: {}", userContext.getUserId());
return paymentService.processWithLegacyMethods(request, userContext);
}
private void applyCheckoutConfig(CheckoutRequest request, CheckoutConfig config) {
if (config.getMaxCartSize() > 0 && request.getItems().size() > config.getMaxCartSize()) {
throw new CartSizeExceededException("Cart size exceeds maximum allowed");
}
if (config.isExpressCheckoutEnabled()) {
request.setExpressCheckout(true);
}
}
// Configuration DTO for feature flag
public static class CheckoutConfig {
private boolean expressCheckoutEnabled;
private int maxCartSize = 50;
private double discountThreshold = 100.0;
private List<String> allowedPaymentMethods;
// Getters and setters
public boolean isExpressCheckoutEnabled() { return expressCheckoutEnabled; }
public void setExpressCheckoutEnabled(boolean expressCheckoutEnabled) { this.expressCheckoutEnabled = expressCheckoutEnabled; }
public int getMaxCartSize() { return maxCartSize; }
public void setMaxCartSize(int maxCartSize) { this.maxCartSize = maxCartSize; }
public double getDiscountThreshold() { return discountThreshold; }
public void setDiscountThreshold(double discountThreshold) { this.discountThreshold = discountThreshold; }
public List<String> getAllowedPaymentMethods() { return allowedPaymentMethods; }
public void setAllowedPaymentMethods(List<String> allowedPaymentMethods) { this.allowedPaymentMethods = allowedPaymentMethods; }
}
}

Recommendation Service with Experimentation:

@Service
@Slf4j
public class RecommendationService {
private final FeatureFlagService featureFlagService;
private final LegacyRecommendationEngine legacyEngine;
private final AIV2RecommendationEngine aiV2Engine;
public RecommendationService(FeatureFlagService featureFlagService,
LegacyRecommendationEngine legacyEngine,
AIV2RecommendationEngine aiV2Engine) {
this.featureFlagService = featureFlagService;
this.legacyEngine = legacyEngine;
this.aiV2Engine = aiV2Engine;
}
/**
* Get recommendations with A/B testing between algorithms
*/
public List<Product> getRecommendations(UserContext userContext, String context) {
String treatment = featureFlagService.getTreatment(
FeatureFlagService.RECOMMENDATION_ENGINE_V2, 
userContext
);
// Track which algorithm was used
featureFlagService.trackExposure(
FeatureFlagService.RECOMMENDATION_ENGINE_V2,
userContext,
treatment
);
List<Product> recommendations;
switch (treatment) {
case "on":
recommendations = aiV2Engine.getRecommendations(userContext.getUserId(), context);
break;
case "off":
recommendations = legacyEngine.getRecommendations(userContext.getUserId(), context);
break;
case "v3": // Experimental third algorithm
recommendations = getExperimentalRecommendations(userContext, context);
break;
default:
recommendations = legacyEngine.getRecommendations(userContext.getUserId(), context);
break;
}
// Track recommendation performance
trackRecommendationMetrics(userContext, treatment, recommendations.size());
return recommendations;
}
/**
* Get personalized recommendations with configuration
*/
public List<Product> getPersonalizedRecommendations(UserContext userContext, 
RecommendationRequest request) {
RecommendationConfig config = featureFlagService.getTreatmentWithConfig(
FeatureFlagService.RECOMMENDATION_ENGINE_V2,
userContext,
RecommendationConfig.class
);
if (config != null) {
return getRecommendationsWithConfig(userContext, request, config);
} else {
return getRecommendations(userContext, request.getContext());
}
}
private List<Product> getRecommendationsWithConfig(UserContext userContext, 
RecommendationRequest request,
RecommendationConfig config) {
// Apply configuration from feature flag
request.setMaxResults(config.getMaxRecommendations());
request.setDiversityFactor(config.getDiversityFactor());
if (config.isPersonalizationEnabled()) {
return aiV2Engine.getPersonalizedRecommendations(userContext.getUserId(), request);
} else {
return legacyEngine.getRecommendations(userContext.getUserId(), request.getContext());
}
}
private List<Product> getExperimentalRecommendations(UserContext userContext, String context) {
// Experimental algorithm - could be another service
log.info("Using experimental recommendation algorithm for user: {}", userContext.getUserId());
return legacyEngine.getRecommendations(userContext.getUserId(), context);
}
private void trackRecommendationMetrics(UserContext userContext, String treatment, int count) {
try {
Map<String, Object> properties = new HashMap<>();
properties.put("treatment", treatment);
properties.put("recommendation_count", count);
properties.put("user_segment", userContext.getAttributes().get("segment"));
featureFlagService.track(
"recommendations_generated",
userContext,
properties
);
} catch (Exception e) {
log.error("Failed to track recommendation metrics", e);
}
}
// Configuration DTO
public static class RecommendationConfig {
private int maxRecommendations = 10;
private double diversityFactor = 0.3;
private boolean personalizationEnabled = true;
private double confidenceThreshold = 0.7;
// Getters and setters
public int getMaxRecommendations() { return maxRecommendations; }
public void setMaxRecommendations(int maxRecommendations) { this.maxRecommendations = maxRecommendations; }
public double getDiversityFactor() { return diversityFactor; }
public void setDiversityFactor(double diversityFactor) { this.diversityFactor = diversityFactor; }
public boolean isPersonalizationEnabled() { return personalizationEnabled; }
public void setPersonalizationEnabled(boolean personalizationEnabled) { this.personalizationEnabled = personalizationEnabled; }
public double getConfidenceThreshold() { return confidenceThreshold; }
public void setConfidenceThreshold(double confidenceThreshold) { this.confidenceThreshold = confidenceThreshold; }
}
}

Step 7: REST Controllers

@RestController
@RequestMapping("/api")
@Slf4j
public class EcommerceController {
private final CheckoutService checkoutService;
private final RecommendationService recommendationService;
private final FeatureFlagService featureFlagService;
public EcommerceController(CheckoutService checkoutService,
RecommendationService recommendationService,
FeatureFlagService featureFlagService) {
this.checkoutService = checkoutService;
this.recommendationService = recommendationService;
this.featureFlagService = featureFlagService;
}
@PostMapping("/checkout")
public ResponseEntity<CheckoutResult> checkout(@RequestBody CheckoutRequest request,
@RequestHeader("X-User-Id") String userId) {
UserContext userContext = UserContext.of(userId)
.withPlan("premium")
.withCountry("US")
.withDevice("web");
CheckoutResult result = checkoutService.processCheckout(request, userContext);
return ResponseEntity.ok(result);
}
@GetMapping("/recommendations")
public ResponseEntity<List<Product>> getRecommendations(
@RequestParam(defaultValue = "homepage") String context,
@RequestHeader("X-User-Id") String userId) {
UserContext userContext = UserContext.of(userId)
.withAttribute("context", context);
List<Product> recommendations = recommendationService.getRecommendations(userContext, context);
return ResponseEntity.ok(recommendations);
}
@GetMapping("/features")
public ResponseEntity<Map<String, Object>> getFeatureFlags(@RequestHeader("X-User-Id") String userId) {
UserContext userContext = UserContext.of(userId);
Map<String, Boolean> features = featureFlagService.bulkCheckFeatures(userContext,
FeatureFlagService.NEW_CHECKOUT_UI,
FeatureFlagService.PREMIUM_FEATURES,
FeatureFlagService.RECOMMENDATION_ENGINE_V2,
FeatureFlagService.SEARCH_ALGORITHM_V2,
FeatureFlagService.PROMOTIONAL_BANNER,
FeatureFlagService.DARK_MODE
);
Map<String, Object> response = new HashMap<>();
response.put("userId", userId);
response.put("features", features);
response.put("timestamp", Instant.now().toString());
return ResponseEntity.ok(response);
}
@GetMapping("/features/{featureName}")
public ResponseEntity<FeatureFlagResponse> getFeatureFlag(
@PathVariable String featureName,
@RequestHeader("X-User-Id") String userId) {
UserContext userContext = UserContext.of(userId);
String treatment = featureFlagService.getTreatment(featureName, userContext);
FeatureFlagResponse response = new FeatureFlagResponse();
response.setFeatureName(featureName);
response.setUserId(userId);
response.setTreatment(treatment);
response.setEnabled("on".equals(treatment));
response.setTimestamp(Instant.now().toString());
return ResponseEntity.ok(response);
}
}
// Response DTOs
class FeatureFlagResponse {
private String featureName;
private String userId;
private String treatment;
private boolean enabled;
private String timestamp;
// Getters and setters
public String getFeatureName() { return featureName; }
public void setFeatureName(String featureName) { this.featureName = featureName; }
public String getUserId() { return userId; }
public void setUserId(String userId) { this.userId = userId; }
public String getTreatment() { return treatment; }
public void setTreatment(String treatment) { this.treatment = treatment; }
public boolean isEnabled() { return enabled; }
public void setEnabled(boolean enabled) { this.enabled = enabled; }
public String getTimestamp() { return timestamp; }
public void setTimestamp(String timestamp) { this.timestamp = timestamp; }
}

Step 8: Monitoring and Health Checks

@Component
public class SplitIOHealthIndicator implements HealthIndicator {
private final SplitClient splitClient;
private final SplitManager splitManager;
public SplitIOHealthIndicator(SplitClient splitClient, SplitManager splitManager) {
this.splitClient = splitClient;
this.splitManager = splitManager;
}
@Override
public Health health() {
try {
// Check if client is ready
if (!splitClient.isReady()) {
return Health.down()
.withDetail("service", "split.io")
.withDetail("status", "not_ready")
.build();
}
// Get some basic metrics
List<SplitView> splits = splitManager.splits();
long activeSplits = splits.stream()
.filter(split -> split.status.equals("ACTIVE"))
.count();
Map<String, Object> details = new HashMap<>();
details.put("total_splits", splits.size());
details.put("active_splits", activeSplits);
details.put("ready", true);
return Health.up()
.withDetail("service", "split.io")
.withDetails(details)
.build();
} catch (Exception e) {
return Health.down()
.withDetail("service", "split.io")
.withDetail("error", e.getMessage())
.build();
}
}
}
@RestController
@RequestMapping("/api/admin")
@Slf4j
public class FeatureFlagAdminController {
private final FeatureFlagService featureFlagService;
private final SplitManager splitManager;
public FeatureFlagAdminController(FeatureFlagService featureFlagService,
SplitManager splitManager) {
this.featureFlagService = featureFlagService;
this.splitManager = splitManager;
}
@GetMapping("/features")
public ResponseEntity<List<SplitView>> getAllFeatures() {
try {
List<SplitView> features = featureFlagService.getAllFeatureFlags();
return ResponseEntity.ok(features);
} catch (Exception e) {
log.error("Failed to get feature flags", e);
return ResponseEntity.status(500).build();
}
}
@PostMapping("/features/{featureName}/test")
public ResponseEntity<Map<String, Object>> testFeatureFlag(
@PathVariable String featureName,
@RequestBody TestFeatureRequest request) {
try {
UserContext userContext = UserContext.of(request.getUserId())
.withAttributes(request.getAttributes());
String treatment = featureFlagService.getTreatment(featureName, userContext);
Map<String, Object> response = new HashMap<>();
response.put("featureName", featureName);
response.put("userId", request.getUserId());
response.put("treatment", treatment);
response.put("enabled", "on".equals(treatment));
response.put("attributes", request.getAttributes());
return ResponseEntity.ok(response);
} catch (Exception e) {
log.error("Failed to test feature flag: {}", featureName, e);
return ResponseEntity.status(500).build();
}
}
}
class TestFeatureRequest {
private String userId;
private Map<String, Object> attributes;
// Getters and setters
public String getUserId() { return userId; }
public void setUserId(String userId) { this.userId = userId; }
public Map<String, Object> getAttributes() { return attributes; }
public void setAttributes(Map<String, Object> attributes) { this.attributes = attributes; }
}

Step 9: Testing Utilities

@Configuration
@Profile("test")
public class TestSplitIOConfiguration {
@Bean
public SplitClient testSplitClient() {
return new TestSplitClient();
}
@Bean
public SplitManager testSplitManager() {
return new TestSplitManager();
}
/**
* Test implementation for unit tests
*/
public static class TestSplitClient implements SplitClient {
private final Map<String, String> featureFlags = new HashMap<>();
public TestSplitClient() {
// Default test flags
featureFlags.put("new_checkout_ui", "off");
featureFlags.put("premium_features", "on");
featureFlags.put("recommendation_engine_v2", "off");
}
@Override
public String getTreatment(String key, String splitName) {
return featureFlags.getOrDefault(splitName, "off");
}
@Override
public String getTreatment(String key, String splitName, Map<String, Object> attributes) {
return getTreatment(key, splitName);
}
@Override
public SplitResult getTreatmentWithConfig(String key, String splitName, Map<String, Object> attributes) {
String treatment = getTreatment(key, splitName);
return new SplitResult(treatment, null);
}
// Implement other methods with default behavior...
@Override
public void destroy() {}
@Override
public boolean track(String key, String trafficType, String eventType) { return true; }
@Override
public boolean track(String key, String trafficType, String eventType, double value) { return true; }
@Override
public boolean track(String key, String trafficType, String eventType, Map<String, Object> properties) { return true; }
@Override
public boolean track(String key, String trafficType, String eventType, double value, Map<String, Object> properties) { return true; }
@Override
public void blockUntilReady() {}
@Override
public boolean isReady() { return true; }
// Helper method for tests
public void setTreatment(String featureFlag, String treatment) {
featureFlags.put(featureFlag, treatment);
}
}
public static class TestSplitManager implements SplitManager {
@Override
public List<SplitView> splits() { return Collections.emptyList(); }
@Override
public SplitView split(String splitName) { return null; }
@Override
public List<String> splitNames() { return Collections.emptyList(); }
@Override
public void blockUntilReady() {}
}
}

Running the Application

  1. Get Split.io API Key:
  • Sign up at Split.io
  • Create your feature flags in the dashboard
  • Get your API key from workspace settings
  1. Set environment variable:
   export SPLIT_IO_API_KEY=your_api_key_here
  1. Run the application:
   mvn spring-boot:run
  1. Test feature flags:
   curl -H "X-User-Id: user123" http://localhost:8080/api/features/new_checkout_ui

Best Practices

1. Naming Conventions

// Good naming
"checkout_ui_v2"
"search_algorithm_2024"
"promo_banner_holiday"
// Avoid
"new_feature" // Too vague
"test_flag"   // Not descriptive

2. Flag Lifecycle Management

  • Development: Localhost mode with hardcoded treatments
  • Staging: Targeted to internal users
  • Production: Gradual rollout with metrics
  • Cleanup: Remove flags after full rollout

3. Monitoring and Alerting

  • Track feature flag exposure rates
  • Monitor performance impact of new features
  • Set up alerts for unexpected treatment distributions
  • Log feature flag decisions for debugging

Conclusion

Implementing Split.io feature flags in Java provides:

  • Safe deployments with instant rollback capabilities
  • Gradual feature rollouts to mitigate risk
  • A/B testing infrastructure for data-driven decisions
  • User segmentation for personalized experiences
  • Operational control without code deployments

By following this comprehensive implementation, you can build a robust feature flag system that enables continuous delivery while maintaining stability and control over your production environment.

Category : JAVA

Leave a Reply

Your email address will not be published. Required fields are marked *


Macro Nepal Helper