feat: blocking setProvider (#201)

Signed-off-by: Thomas Poignant <[email protected]> Signed-off-by: Thomas Poignant <[email protected]> Co-authored-by: Todd Baert <[email protected]>
open-feature · Aug 15, 2023 · 4b21642 · 4b21642
1 parent 8e8c344
commit 4b21642
Show file tree

Hide file tree

Showing 2 changed files with 25 additions and 0 deletions.
diff --git a/specification.json b/specification.json
@@ -63,6 +63,13 @@
             "RFC 2119 keyword": "MUST NOT",
             "children": []
         },
+        {
+            "id": "Requirement 1.1.8",
+            "machine_id": "requirement_1_1_8",
+            "content": "The `API` SHOULD provide functions to set a provider and wait for the `initialize` function to return or throw.",
+            "RFC 2119 keyword": "SHOULD",
+            "children": []
+        },
         {
             "id": "Requirement 1.2.1",
             "machine_id": "requirement_1_2_1",

diff --git a/specification/sections/01-flag-evaluation.md b/specification/sections/01-flag-evaluation.md
@@ -112,6 +112,24 @@ See [setting a provider](#setting-a-provider) for details.
 
 Clients may be created in critical code paths, and even per-request in server-side HTTP contexts. Therefore, in keeping with the principle that OpenFeature should never cause abnormal execution of the first party application, this function should never throw. Abnormal execution in initialization should instead occur during provider registration.
 
+#### Requirement 1.1.8
+
+> The `API` **SHOULD** provide functions to set a provider and wait for the `initialize` function to return or throw.
+
+This function not only sets the provider, but ensures that the provider is ready (or in error) before returning or settling.
+
+```java
+// default client
+OpenFeatureAPI.getInstance().setProviderAndWait(myprovider); // this method blocks until the provider is ready or in error
+Client client = OpenFeatureAPI.getInstance().getClient(); 
+
+// named client
+OpenFeatureAPI.getInstance().setProviderAndWait('client-name', myprovider); // this method blocks until the provider is ready or in error
+Client client = OpenFeatureAPI.getInstance().getClient('client-name');
+```
+
+Though it's possible to use [events](./05-events.md) to await provider readiness, such functions can make things simpler for `application authors` and `integrators`.
+
 ### 1.2. Client Usage
 
 #### Requirement 1.2.1