diff --git a/specification.json b/specification.json index d9f1302c..db14ddc2 100644 --- a/specification.json +++ b/specification.json @@ -28,6 +28,13 @@ "RFC 2119 keyword": "MUST", "children": [] }, + { + "id": "Requirement 1.1.2.4", + "machine_id": "requirement_1_1_2_4", + "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.1.3", "machine_id": "requirement_1_1_3", @@ -63,13 +70,6 @@ "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 index d04701f6..cb81a958 100644 --- a/specification/sections/01-flag-evaluation.md +++ b/specification/sections/01-flag-evaluation.md @@ -54,6 +54,24 @@ Provider instances which are bound to multiple names won't be shut down until th see: [shutdown](./02-providers.md#25-shutdown), [setting a provider](#setting-a-provider) +#### Requirement 1.1.2.4 + +> 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`. + #### Requirement 1.1.3 > The `API` **MUST** provide a function to bind a given `provider` to one or more client `name`s. If the client-name already has a bound provider, it is overwritten with the new mapping. @@ -112,24 +130,6 @@ 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