feat: events

pom.xml

@@ -178,21 +178,6 @@
 
   <build>
     <plugins>
-      <plugin>
-        <groupId>org.codehaus.mojo</groupId>
-        <artifactId>build-helper-maven-plugin</artifactId>
-        <version>3.4.0</version>
-        <executions>
-          <execution>
-            <phase>validate</phase>
-            <id>get-cpu-count</id>
-            <goals>
-              <goal>cpu-count</goal>
-            </goals>
-          </execution>
-        </executions>
-      </plugin>
-
       <plugin>
         <groupId>org.cyclonedx</groupId>
         <artifactId>cyclonedx-maven-plugin</artifactId>
@@ -261,9 +246,6 @@
           <argLine>
             ${surefireArgLine}
           </argLine>
-          <!-- fork a new JVM to isolate test suites, especially important with singletons -->
-          <forkCount>${cpu.count}</forkCount>
-          <reuseForks>false</reuseForks>
           <excludes>
             <!-- tests to exclude -->
             <exclude>${testExclusions}</exclude>

src/main/java/dev/openfeature/sdk/Client.java

@@ -5,7 +5,7 @@
 /**
  * Interface used to resolve flags of varying types.
  */
-public interface Client extends Features {
+public interface Client extends Features, EventHandling<Client> {
     Metadata getMetadata();
 
     /**

src/main/java/dev/openfeature/sdk/EventDetails.java

@@ -0,0 +1,28 @@
+package dev.openfeature.sdk;
+
+import edu.umd.cs.findbugs.annotations.Nullable;
+import lombok.Data;
+import lombok.experimental.SuperBuilder;
+
+/**
+ * The details of a particular event.
+ */
+@Data @SuperBuilder(toBuilder = true)
+public class EventDetails extends ProviderEventDetails {
+    private String clientName;
+
+    static EventDetails fromProviderEventDetails(ProviderEventDetails providerEventDetails) {
+        return EventDetails.fromProviderEventDetails(providerEventDetails, null);
+    }
+
+    static EventDetails fromProviderEventDetails(
+            ProviderEventDetails providerEventDetails,
+            @Nullable String clientName) {
+        return EventDetails.builder()
+                .clientName(clientName)
+                .flagsChanged(providerEventDetails.getFlagsChanged())
+                .eventMetadata(providerEventDetails.getEventMetadata())
+                .message(providerEventDetails.getMessage())
+                .build();
+    }
+}

src/main/java/dev/openfeature/sdk/EventHandling.java

@@ -0,0 +1,64 @@
+package dev.openfeature.sdk;
+
+import java.util.function.Consumer;
+
+/**
+ * Interface for attaching event handlers.
+ */
+public interface EventHandling<T> {
+
+    /**
+     * Add a handler for the {@link ProviderEvent#PROVIDER_READY} event.
+     * Shorthand for {@link #on(ProviderEvent, Consumer)}
+     * 
+     * @param handler behavior to add with this event
+     * @return this
+     */
+    T onProviderReady(Consumer<EventDetails> handler);
+
+    /**
+     * Add a handler for the {@link ProviderEvent#PROVIDER_CONFIGURATION_CHANGED} event.
+     * Shorthand for {@link #on(ProviderEvent, Consumer)}
+     * 
+     * @param handler behavior to add with this event
+     * @return this
+     */
+    T onProviderConfigurationChanged(Consumer<EventDetails> handler);
+
+    /**
+     * Add a handler for the {@link ProviderEvent#PROVIDER_STALE} event.
+     * Shorthand for {@link #on(ProviderEvent, Consumer)}
+     * 
+     * @param handler behavior to add with this event
+     * @return this
+     */
+    T onProviderError(Consumer<EventDetails> handler);
+
+    /**
+     * Add a handler for the {@link ProviderEvent#PROVIDER_ERROR} event.
+     * Shorthand for {@link #on(ProviderEvent, Consumer)}
+     * 
+     * @param handler behavior to add with this event
+     * @return this
+     */
+    T onProviderStale(Consumer<EventDetails> handler);
+
+    /**
+     * Add a handler for the specified {@link ProviderEvent}.
+     * 
+     * @param event event type
+     * @param handler behavior to add with this event
+     * @return this
+     */
+    T on(ProviderEvent event, Consumer<EventDetails> handler);
+
+    /**
+     * Remove the previously attached handler by reference.
+     * If the handler doesn't exists, no-op.
+     * 
+     * @param event event type
+     * @param handler to be removed
+     * @return this
+     */
+    T removeHandler(ProviderEvent event, Consumer<EventDetails> handler);
+}

src/main/java/dev/openfeature/sdk/EventProvider.java

@@ -0,0 +1,83 @@
+package dev.openfeature.sdk;
+
+import dev.openfeature.sdk.internal.TriConsumer;
+
+/**
+ * Abstract EventProvider. Providers must extend this class to support events.
+ * Emit events with {@link #emit(ProviderEvent, ProviderEventDetails)}. Please
+ * note that the SDK will automatically emit
+ * {@link ProviderEvent#PROVIDER_READY } or
+ * {@link ProviderEvent#PROVIDER_ERROR } accordingly when
+ * {@link FeatureProvider#initialize(EvaluationContext)} completes successfully
+ * or with error, so these events need not be emitted manually during
+ * initialization.
+ *
+ * @see FeatureProvider
+ */
+public abstract class EventProvider implements FeatureProvider {
+
+    private TriConsumer<EventProvider, ProviderEvent, ProviderEventDetails> onEmit = null;
+
+    void detach() {
+        this.onEmit = null;
+    }
+
+    void attach(TriConsumer<EventProvider, ProviderEvent, ProviderEventDetails> onEmit) {
+        if (this.onEmit == null) {
+            this.onEmit = onEmit;
+        }
+    }
+
+    /**
+     * Emit the specified {@link ProviderEvent}.
+     * 
+     * @param event   The event type
+     * @param details The details of the event
+     */
+    public void emit(ProviderEvent event, ProviderEventDetails details) {
+        if (this.onEmit != null) {
+            this.onEmit.accept(this, event, details);
+        }
+    }
+
+    /**
+     * Emit a {@link ProviderEvent#PROVIDER_READY} event.
+     * Shorthand for {@link #emit(ProviderEvent, ProviderEventDetails)}
+     * 
+     * @param details The details of the event
+     */
+    public void emitProviderReady(ProviderEventDetails details) {
+        emit(ProviderEvent.PROVIDER_READY, details);
+    }
+
+    /**
+     * Emit a
+     * {@link ProviderEvent#PROVIDER_CONFIGURATION_CHANGED}
+     * event. Shorthand for {@link #emit(ProviderEvent, ProviderEventDetails)}
+     * 
+     * @param details The details of the event
+     */
+    public void emitProviderConfigurationChanged(ProviderEventDetails details) {
+        emit(ProviderEvent.PROVIDER_CONFIGURATION_CHANGED, details);
+    }
+
+    /**
+     * Emit a {@link ProviderEvent#PROVIDER_STALE} event.
+     * Shorthand for {@link #emit(ProviderEvent, ProviderEventDetails)}
+     * 
+     * @param details The details of the event
+     */
+    public void emitProviderStale(ProviderEventDetails details) {
+        emit(ProviderEvent.PROVIDER_STALE, details);
+    }
+
+    /**
+     * Emit a {@link ProviderEvent#PROVIDER_ERROR} event.
+     * Shorthand for {@link #emit(ProviderEvent, ProviderEventDetails)}
+     * 
+     * @param details The details of the event
+     */
+    public void emitProviderError(ProviderEventDetails details) {
+        emit(ProviderEvent.PROVIDER_ERROR, details);
+    }
+}

src/main/java/dev/openfeature/sdk/EventSupport.java

@@ -0,0 +1,115 @@
+package dev.openfeature.sdk;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+import java.util.UUID;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.function.Consumer;
+
+import edu.umd.cs.findbugs.annotations.Nullable;
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Util class for storing and running handlers.
+ */
+@Slf4j
+class EventSupport {
+
+    // we use a v4 uuid as a "placeholder" for anonymous clients, since
+    // ConcurrentHashMap doesn't support nulls
+    private static final String defaultClientUuid = UUID.randomUUID().toString();
+    private static final ExecutorService taskExecutor = Executors.newCachedThreadPool();
+    private final Map<String, HandlerStore> handlerStores = new ConcurrentHashMap<>();
+    private final HandlerStore globalHandlerStore = new HandlerStore();
+
+    public void runClientHandlers(@Nullable String clientName, ProviderEvent event, EventDetails eventDetails) {
+        clientName = Optional.ofNullable(clientName)
+                .orElse(defaultClientUuid);
+
+        // run handlers if they exist
+        Optional.ofNullable(handlerStores.get(clientName))
+                .filter(store -> Optional.of(store).isPresent())
+                .map(store -> store.handlerMap.get(event))
+                .ifPresent(handlers -> handlers
+                        .forEach(handler -> runHandler(handler, eventDetails)));
+    }
+
+    public void runGlobalHandlers(ProviderEvent event, EventDetails eventDetails) {
+        globalHandlerStore.handlerMap.get(event)
+                .forEach(handler -> {
+                    runHandler(handler, eventDetails);
+                });
+    }
+
+    public void addClientHandler(@Nullable String clientName, ProviderEvent event, Consumer<EventDetails> handler) {
+        final String name = Optional.ofNullable(clientName)
+                .orElse(defaultClientUuid);
+
+        // lazily create and cache a HandlerStore if it doesn't exist
+        HandlerStore store = Optional.ofNullable(this.handlerStores.get(name))
+                .orElseGet(() -> {
+                    HandlerStore newStore = new HandlerStore();
+                    this.handlerStores.put(name, newStore);
+                    return newStore;
+                });
+        store.addHandler(event, handler);
+    }
+
+    public void removeClientHandler(String clientName, ProviderEvent event, Consumer<EventDetails> handler) {
+        clientName = Optional.ofNullable(clientName)
+                .orElse(defaultClientUuid);
+        this.handlerStores.get(clientName).removeHandler(event, handler);
+    }
+
+    public void addGlobalHandler(ProviderEvent event, Consumer<EventDetails> handler) {
+        this.globalHandlerStore.addHandler(event, handler);
+    }
+
+    public void removeGlobalHandler(ProviderEvent event, Consumer<EventDetails> handler) {
+        this.globalHandlerStore.removeHandler(event, handler);
+    }
+
+    public Set<String> getAllClientNames() {
+        return this.handlerStores.keySet();
+    }
+
+    public void runHandler(Consumer<EventDetails> handler, EventDetails eventDetails) {
+        taskExecutor.submit(() -> {
+            try {
+                handler.accept(eventDetails);
+            } catch (Exception e) {
+                log.error("Exception in event handler {}", handler, e);
+            }
+        });
+    }
+
+    public void shutdown() {
+        taskExecutor.shutdown();
+    }
+
+    static class HandlerStore {
+
+        private final Map<ProviderEvent, List<Consumer<EventDetails>>> handlerMap;
+
+        {
+            handlerMap = new ConcurrentHashMap<ProviderEvent, List<Consumer<EventDetails>>>();
+            handlerMap.put(ProviderEvent.PROVIDER_READY, new ArrayList<>());
+            handlerMap.put(ProviderEvent.PROVIDER_CONFIGURATION_CHANGED, new ArrayList<>());
+            handlerMap.put(ProviderEvent.PROVIDER_ERROR, new ArrayList<>());
+            handlerMap.put(ProviderEvent.PROVIDER_STALE, new ArrayList<>());
+        }
+
+        void addHandler(ProviderEvent event, Consumer<EventDetails> handler) {
+            handlerMap.get(event).add(handler);
+        }
+
+        void removeHandler(ProviderEvent event, Consumer<EventDetails> handler) {
+            handlerMap.get(event).remove(handler);
+        }
+    }
+}

src/main/java/dev/openfeature/sdk/FeatureProvider.java

@@ -4,7 +4,9 @@
 import java.util.List;
 
 /**
- * The interface implemented by upstream flag providers to resolve flags for their service.
+ * The interface implemented by upstream flag providers to resolve flags for
+ * their service. If you want to support realtime events with your provider, you
+ * should extend {@link EventProvider}
  */
 public interface FeatureProvider {
     Metadata getMetadata();
@@ -24,27 +26,43 @@ default List<Hook> getProviderHooks() {
     ProviderEvaluation<Value> getObjectEvaluation(String key, Value defaultValue, EvaluationContext ctx);
 
     /**
-     * This method is called before a provider is used to evaluate flags. Providers can overwrite this method,
-     * if they have special initialization needed prior being called for flag evaluation.
+     * This method is called before a provider is used to evaluate flags. Providers
+     * can overwrite this method,
+     * if they have special initialization needed prior being called for flag
+     * evaluation.
      * <p>
-     * It is ok, if the method is expensive as it is executed in the background. All runtime exceptions will be
+     * It is ok, if the method is expensive as it is executed in the background. All
+     * runtime exceptions will be
      * caught and logged.
      * </p>
      */
-    default void initialize() {
+    default void initialize(EvaluationContext evaluationContext) throws Exception {
         // Intentionally left blank
     }
 
     /**
-     * This method is called when a new provider is about to be used to evaluate flags, or the SDK is shut down.
-     * Providers can overwrite this method, if they have special shutdown actions needed.
+     * This method is called when a new provider is about to be used to evaluate
+     * flags, or the SDK is shut down.
+     * Providers can overwrite this method, if they have special shutdown actions
+     * needed.
      * <p>
-     * It is ok, if the method is expensive as it is executed in the background. All runtime exceptions will be
+     * It is ok, if the method is expensive as it is executed in the background. All
+     * runtime exceptions will be
      * caught and logged.
      * </p>
      */
     default void shutdown() {
         // Intentionally left blank
     }
 
+    /**
+     * Returns a representation of the current readiness of the provider.
+     * Providers which do not implement this method are assumed to be ready immediately.
+     * 
+     * @return ProviderState
+     */
+    default ProviderState getState() {
+        return ProviderState.READY;
+    }
+
 }