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, EventBus<Client> {
     Metadata getMetadata();
 
     /**

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

@@ -0,0 +1,64 @@
+package dev.openfeature.sdk;
+
+import java.util.function.Consumer;
+
+/**
+ * Interface for attaching event handlers.
+ */
+public interface EventBus<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/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/EventProvider.java

@@ -0,0 +1,95 @@
+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;
+
+    /**
+     * "Attach" this EventProvider to an SDK, which allows events to propagate from this provider.
+     * No-op if the same onEmit is already attached. 
+     *
+     *  @param onEmit the function to run when a provider emits events.
+     */
+    void attach(TriConsumer<EventProvider, ProviderEvent, ProviderEventDetails> onEmit) {
+        if (this.onEmit != null && this.onEmit != onEmit) {
+            // if we are trying to attach this provider to a different onEmit, something has gone wrong
+            throw new IllegalStateException("Provider " + this.getMetadata().getName() + " is already attached.");
+        } else {
+            this.onEmit = onEmit;
+        }
+    }
+
+    /**
+     * "Detach" this EventProvider from an SDK, stopping propagation of all events.
+     */
+    void detach() {
+        this.onEmit = null;
+    }
+
+    /**
+     * 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);
+    }
+}