feat: Complete OpenFeature API module with interface segregation and ServiceLoader

This commit establishes a stable, production-ready API module that separates core
OpenFeature contracts from SDK implementation details:

## Core Features
- **ServiceLoader Pattern**: Automatic implementation discovery with priority-based selection
- **Interface Segregation**: Clean separation via OpenFeatureCore, OpenFeatureHooks,
  OpenFeatureContext, and OpenFeatureEventHandling interfaces
- **No-op Fallback**: Safe default implementation for API-only consumers
- **Backward Compatibility**: Existing user code continues to work seamlessly

## Architecture
- **openfeature-api**: Minimal module with core contracts, interfaces, and data types
- **Abstract OpenFeatureAPI**: ServiceLoader singleton that combines all interfaces
- **NoOpOpenFeatureAPI**: Safe fallback when no SDK implementation is available
- **Clean Dependencies**: Only essential dependencies (slf4j, lombok, spotbugs)

## Key Components
- Core interfaces and data structures (Client, FeatureProvider, Value, Structure, etc.)
- Exception hierarchy with proper error codes
- Event handling contracts for advanced SDK functionality
- Double-checked locking singleton pattern for thread-safe initialization

The API module compiles successfully and passes all tests, providing a stable
foundation for multiple SDK implementations.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: aepfli

mvnw

@@ -42,6 +42,26 @@
             <version>4.8.6</version>
             <scope>provided</scope>
         </dependency>
+        
+        <!-- Test dependencies -->
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <version>5.11.4</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <version>5.14.2</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <version>3.26.3</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <build>

openfeature-api/pom.xml

@@ -12,6 +12,11 @@
 public interface EvaluationContext extends Structure {
 
     String TARGETING_KEY = "targetingKey";
+    
+    /**
+     * Empty evaluation context for use as a default.
+     */
+    EvaluationContext EMPTY = new ImmutableContext();
 
     String getTargetingKey();
 

openfeature-api/src/main/java/dev/openfeature/api/EvaluationContext.java

@@ -14,11 +14,11 @@ public class EventDetails extends ProviderEventDetails {
     private String domain;
     private String providerName;
 
-    static EventDetails fromProviderEventDetails(ProviderEventDetails providerEventDetails, String providerName) {
+    public static EventDetails fromProviderEventDetails(ProviderEventDetails providerEventDetails, String providerName) {
         return fromProviderEventDetails(providerEventDetails, providerName, null);
     }
 
-    static EventDetails fromProviderEventDetails(
+    public static EventDetails fromProviderEventDetails(
             ProviderEventDetails providerEventDetails, String providerName, String domain) {
         return builder()
                 .domain(domain)

openfeature-api/src/main/java/dev/openfeature/api/EventDetails.java

@@ -10,12 +10,9 @@
  */
 class NoOpClient implements Client {
 
-    private static final ImmutableMetadata CLIENT_METADATA = 
-        ImmutableMetadata.builder().name("No-op Client").build();
-
     @Override
-    public Metadata getMetadata() {
-        return CLIENT_METADATA;
+    public ClientMetadata getMetadata() {
+        return () -> "no-op";
     }
 
     @Override
@@ -48,7 +45,7 @@ public FlagEvaluationDetails<Boolean> getBooleanDetails(String key, Boolean defa
         return FlagEvaluationDetails.<Boolean>builder()
                 .flagKey(key)
                 .value(defaultValue)
-                .reason(Reason.DEFAULT)
+                .reason(Reason.DEFAULT.toString())
                 .build();
     }
 
@@ -82,7 +79,7 @@ public FlagEvaluationDetails<String> getStringDetails(String key, String default
         return FlagEvaluationDetails.<String>builder()
                 .flagKey(key)
                 .value(defaultValue)
-                .reason(Reason.DEFAULT)
+                .reason(Reason.DEFAULT.toString())
                 .build();
     }
 
@@ -116,7 +113,7 @@ public FlagEvaluationDetails<Integer> getIntegerDetails(String key, Integer defa
         return FlagEvaluationDetails.<Integer>builder()
                 .flagKey(key)
                 .value(defaultValue)
-                .reason(Reason.DEFAULT)
+                .reason(Reason.DEFAULT.toString())
                 .build();
     }
 
@@ -150,7 +147,7 @@ public FlagEvaluationDetails<Double> getDoubleDetails(String key, Double default
         return FlagEvaluationDetails.<Double>builder()
                 .flagKey(key)
                 .value(defaultValue)
-                .reason(Reason.DEFAULT)
+                .reason(Reason.DEFAULT.toString())
                 .build();
     }
 
@@ -184,7 +181,7 @@ public FlagEvaluationDetails<Value> getObjectDetails(String key, Value defaultVa
         return FlagEvaluationDetails.<Value>builder()
                 .flagKey(key)
                 .value(defaultValue)
-                .reason(Reason.DEFAULT)
+                .reason(Reason.DEFAULT.toString())
                 .build();
     }
 
@@ -223,6 +220,11 @@ public void track(String eventName, EvaluationContext context) {
         // No-op - silently ignore
     }
 
+    @Override
+    public void track(String eventName, TrackingEventDetails details) {
+        // No-op - silently ignore
+    }
+
     @Override
     public void track(String eventName, EvaluationContext context, TrackingEventDetails details) {
         // No-op - silently ignore

openfeature-api/src/main/java/dev/openfeature/api/NoOpClient.java

@@ -2,6 +2,7 @@
 
 import java.util.Collections;
 import java.util.List;
+import java.util.function.Consumer;
 
 /**
  * No-operation implementation of OpenFeatureAPI that provides safe defaults.
@@ -39,7 +40,7 @@ public void setProvider(String domain, FeatureProvider provider) {
 
     @Override
     public Metadata getProviderMetadata() {
-        return ImmutableMetadata.builder().name("No-op Provider").build();
+        return () -> "No-op Provider";
     }
 
     @Override
@@ -71,4 +72,17 @@ public OpenFeatureAPI setEvaluationContext(EvaluationContext evaluationContext)
     public EvaluationContext getEvaluationContext() {
         return EvaluationContext.EMPTY;
     }
+
+    // Implementation of OpenFeatureEventHandling interface
+    
+    @Override
+    public void addHandler(String domain, ProviderEvent event, Consumer<EventDetails> handler) {
+        // No-op - silently ignore
+    }
+    
+    @Override
+    public void removeHandler(String domain, ProviderEvent event, Consumer<EventDetails> handler) {
+        // No-op - silently ignore
+    }
+    
 }

openfeature-api/src/main/java/dev/openfeature/api/NoOpOpenFeatureAPI.java

@@ -1,6 +1,7 @@
 package dev.openfeature.api;
 
 import java.util.ServiceLoader;
+import java.util.function.Consumer;
 
 /**
  * Main abstract class that combines all OpenFeature interfaces.
@@ -10,7 +11,8 @@
 public abstract class OpenFeatureAPI implements 
         OpenFeatureCore, 
         OpenFeatureHooks, 
-        OpenFeatureContext {
+        OpenFeatureContext,
+        OpenFeatureEventHandling {
 
     private static volatile OpenFeatureAPI instance;
     private static final Object lock = new Object();
@@ -83,5 +85,6 @@ protected static void resetInstance() {
         }
     }
 
+
     // All methods from the implemented interfaces are abstract and must be implemented by concrete classes
 }

openfeature-api/src/main/java/dev/openfeature/api/OpenFeatureAPI.java

@@ -0,0 +1,32 @@
+package dev.openfeature.api;
+
+import java.util.function.Consumer;
+
+/**
+ * Interface for advanced event handling capabilities.
+ * This interface provides domain-specific event handler management
+ * which is typically used by SDK implementations but not required
+ * for basic API usage.
+ */
+public interface OpenFeatureEventHandling {
+    
+    /**
+     * Add event handlers for domain-specific provider events.
+     * This method is used by SDK implementations to manage client-level event handlers.
+     * 
+     * @param domain the domain for which to add the handler
+     * @param event the provider event to listen for
+     * @param handler the event handler to add
+     */
+    void addHandler(String domain, ProviderEvent event, Consumer<EventDetails> handler);
+    
+    /**
+     * Remove event handlers for domain-specific provider events.
+     * This method is used by SDK implementations to manage client-level event handlers.
+     * 
+     * @param domain the domain for which to remove the handler
+     * @param event the provider event to stop listening for
+     * @param handler the event handler to remove
+     */
+    void removeHandler(String domain, ProviderEvent event, Consumer<EventDetails> handler);
+}

openfeature-api/src/main/java/dev/openfeature/api/OpenFeatureEventHandling.java

@@ -16,7 +16,7 @@ public enum ProviderState {
      * @param event event to compare
      * @return boolean if matches.
      */
-    boolean matchesEvent(ProviderEvent event) {
+    public boolean matchesEvent(ProviderEvent event) {
         return this == READY && event == ProviderEvent.PROVIDER_READY
                 || this == STALE && event == ProviderEvent.PROVIDER_STALE
                 || this == ERROR && event == ProviderEvent.PROVIDER_ERROR;