feat: move factory to isolated package and warn on multi-instance provider binding

Author: marcozabel

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

@@ -9,6 +9,7 @@
 import java.util.List;
 import java.util.Optional;
 import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ConcurrentLinkedQueue;
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.Consumer;
@@ -22,6 +23,15 @@
 @Slf4j
 @SuppressWarnings("PMD.UnusedLocalVariable")
 public class OpenFeatureAPI implements EventBus<OpenFeatureAPI> {
+
+    /**
+     * Global registry tracking which API instance each provider is currently bound to.
+     * Used to detect violations of spec requirement 1.8.4 (a provider SHOULD NOT be
+     * registered with more than one API instance simultaneously).
+     */
+    private static final ConcurrentHashMap<FeatureProvider, OpenFeatureAPI> GLOBAL_PROVIDER_REGISTRY =
+            new ConcurrentHashMap<>();
+
     // package-private multi-read/single-write lock (instance-level for isolation)
     final AutoCloseableReentrantReadWriteLock lock;
     private final ConcurrentLinkedQueue<Hook> apiHooks;
@@ -30,7 +40,7 @@ public class OpenFeatureAPI implements EventBus<OpenFeatureAPI> {
     private final AtomicReference<EvaluationContext> evaluationContext = new AtomicReference<>();
     private TransactionContextPropagator transactionContextPropagator;
 
-    protected OpenFeatureAPI() {
+    public OpenFeatureAPI() {
         this(new AutoCloseableReentrantReadWriteLock());
     }
 
@@ -338,6 +348,31 @@ public void clearHooks() {
         this.apiHooks.clear();
     }
 
+    /**
+     * Registers a provider with the global registry, warning if it is already
+     * bound to a different API instance (spec requirement 1.8.4).
+     */
+    void registerGlobalProvider(FeatureProvider provider) {
+        GLOBAL_PROVIDER_REGISTRY.compute(provider, (p, existing) -> {
+            if (existing != null && existing != this) {
+                log.warn(
+                        "Provider "
+                                + provider.getClass().getName()
+                                + " is already registered with another API instance. "
+                                + "A provider SHOULD NOT be bound to more than one API instance "
+                                + "simultaneously (spec requirement 1.8.4).");
+            }
+            return this;
+        });
+    }
+
+    /**
+     * Removes the provider from the global registry if this instance is the current owner.
+     */
+    void deregisterGlobalProvider(FeatureProvider provider) {
+        GLOBAL_PROVIDER_REGISTRY.remove(provider, this);
+    }
+
     /**
      * Shut down and reset the current status of OpenFeature API.
      * This call cleans up all active providers and attempts to shut down internal

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

@@ -173,6 +173,8 @@ private void prepareAndInitializeProvider(
                 newStateManager = new FeatureProviderStateManager(newProvider);
                 // only run afterSet if new provider is not already attached
                 afterSet.accept(newProvider);
+                // spec 1.8.4: warn if this provider is already bound to another API instance
+                openFeatureAPI.registerGlobalProvider(newProvider);
             } else {
                 newStateManager = existing;
             }
@@ -236,6 +238,8 @@ private void initializeProvider(
     private void shutDownOld(FeatureProviderStateManager oldManager, Consumer<FeatureProvider> afterShutdown) {
         synchronized (registerStateManagerLock) {
             if (oldManager != null && !isStateManagerRegistered(oldManager)) {
+                // spec 1.8.4: release the provider from the global registry
+                openFeatureAPI.deregisterGlobalProvider(oldManager.getProvider());
                 shutdownProvider(oldManager);
                 afterShutdown.accept(oldManager.getProvider());
             }
@@ -327,7 +331,11 @@ List<FeatureProviderStateManager> prepareShutdown() {
      * @param managersToShutdown the managers to shut down (from prepareShutdown)
      */
     void completeShutdown(List<FeatureProviderStateManager> managersToShutdown) {
-        managersToShutdown.forEach(this::shutdownProvider);
+        managersToShutdown.forEach(m -> {
+            // spec 1.8.4: release all providers from the global registry on shutdown
+            openFeatureAPI.deregisterGlobalProvider(m.getProvider());
+            shutdownProvider(m);
+        });
         taskExecutor.shutdown();
         try {
             if (!taskExecutor.awaitTermination(EventSupport.SHUTDOWN_TIMEOUT_SECONDS, TimeUnit.SECONDS)) {

…enfeature/sdk/OpenFeatureAPIFactory.java …/sdk/isolated/OpenFeatureAPIFactory.javasrc/main/java/dev/openfeature/sdk/OpenFeatureAPIFactory.java renamed to src/main/java/dev/openfeature/sdk/isolated/OpenFeatureAPIFactory.java src/main/java/dev/openfeature/sdk/OpenFeatureAPIFactory.java renamed to src/main/java/dev/openfeature/sdk/isolated/OpenFeatureAPIFactory.java

@@ -1,4 +1,6 @@
-package dev.openfeature.sdk;
+package dev.openfeature.sdk.isolated;
+
+import dev.openfeature.sdk.OpenFeatureAPI;
 
 /**
  * Factory for creating isolated OpenFeature API instances.
@@ -8,12 +10,18 @@
  * transaction context propagators. Instances do not share state with the
  * global singleton ({@link OpenFeatureAPI#getInstance()}) or with each other.
  *
+ * <p>This class lives in a distinct package ({@code dev.openfeature.sdk.isolated})
+ * to make isolated instances intentionally less discoverable than the global
+ * singleton, reducing the chance of accidental use when the singleton would be
+ * appropriate.
+ *
  * <p>This is useful for dependency injection frameworks, testing scenarios,
  * and applications composed of multiple submodules requiring distinct providers.
  *
  * <p><strong>Spec references:</strong>
  * <ul>
  *   <li>Requirement 1.8.1 &mdash; factory function for isolated instances</li>
+ *   <li>Requirement 1.8.3 &mdash; factory in a distinct package/module</li>
  * </ul>
  *
  * @see <a href="https://openfeature.dev/specification/sections/flag-evaluation#18-isolated-api-instances">

src/test/java/dev/openfeature/sdk/isolated/IsolatedAPISingeltonTest.java

@@ -6,7 +6,6 @@
 import dev.openfeature.sdk.ImmutableContext;
 import dev.openfeature.sdk.NoOpTransactionContextPropagator;
 import dev.openfeature.sdk.OpenFeatureAPI;
-import dev.openfeature.sdk.OpenFeatureAPIFactory;
 import dev.openfeature.sdk.providers.memory.InMemoryProvider;
 import java.util.Map;
 import org.junit.jupiter.api.AfterEach;

src/test/java/dev/openfeature/sdk/isolated/IsolatedAPITest.java

@@ -1,13 +1,16 @@
 package dev.openfeature.sdk.isolated;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.contains;
 
 import dev.openfeature.sdk.ImmutableContext;
 import dev.openfeature.sdk.NoOpProvider;
 import dev.openfeature.sdk.NoOpTransactionContextPropagator;
 import dev.openfeature.sdk.OpenFeatureAPI;
-import dev.openfeature.sdk.OpenFeatureAPIFactory;
 import dev.openfeature.sdk.ThreadLocalTransactionContextPropagator;
+import org.mockito.Mockito;
+import org.simplify4u.slf4jmock.LoggerMock;
+import org.slf4j.Logger;
 import dev.openfeature.sdk.providers.memory.Flag;
 import dev.openfeature.sdk.providers.memory.InMemoryProvider;
 import java.util.Map;
@@ -201,4 +204,27 @@ void clientUsesItsOwnInstanceProvider() throws Exception {
         // api2 has NoOpProvider, so it returns the default
         assertThat(client2.getBooleanValue("flag1", false)).isFalse();
     }
+
+    /**
+     * Requirement 1.8.4 — a warning is logged when the same provider instance
+     * is registered with more than one API instance simultaneously.
+     */
+    @Test
+    @DisplayName("warn when same provider bound to multiple API instances (req 1.8.4)")
+    void warnWhenProviderBoundToMultipleInstances() {
+        Logger mockLogger = Mockito.mock(Logger.class);
+        LoggerMock.setMock(OpenFeatureAPI.class, mockLogger);
+        try {
+            OpenFeatureAPI api1 = OpenFeatureAPIFactory.createAPI();
+            OpenFeatureAPI api2 = OpenFeatureAPIFactory.createAPI();
+
+            NoOpProvider provider = new NoOpProvider();
+            api1.setProvider(provider);
+            api2.setProvider(provider);
+
+            Mockito.verify(mockLogger).warn(contains("1.8.4"));
+        } finally {
+            LoggerMock.setMock(OpenFeatureAPI.class, null);
+        }
+    }
 }