Skip to content

Commit

Permalink
chore: update readme for events (#507)
Browse files Browse the repository at this point in the history
Signed-off-by: Todd Baert <[email protected]>
  • Loading branch information
toddbaert authored Jul 13, 2023
1 parent 40d1f0a commit c115e96
Showing 1 changed file with 76 additions and 29 deletions.
105 changes: 76 additions & 29 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@

<h2 align="center">OpenFeature Java SDK</h2>

[![Specification](https://img.shields.io/static/v1?label=Specification&message=v0.5.2&color=yellow)](https://github.com/open-feature/spec/tree/v0.5.2)
[![Specification](https://img.shields.io/static/v1?label=Specification&message=v0.6.0&color=yellow)](https://github.com/open-feature/spec/tree/v0.6.0)
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/dev.openfeature/sdk/badge.svg)](https://maven-badges.herokuapp.com/maven-central/dev.openfeature/sdk)
[![javadoc](https://javadoc.io/badge2/dev.openfeature/sdk/javadoc.svg)](https://javadoc.io/doc/dev.openfeature/sdk)
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
Expand All @@ -28,13 +28,13 @@

Standardizing feature flags unifies tools and vendors behind a common interface which avoids vendor lock-in at the code level. Additionally, it offers a framework for building extensions and integrations and allows providers to focus on their unique value proposition.

## 🔍 Requirements:
## 🔍 Requirements

- Java 8+ (compiler target is 1.8)

Note that this library is intended to be used in server-side contexts and has not been evaluated for use in mobile devices.

## 📦 Installation:
## 📦 Installation

### Maven

Expand Down Expand Up @@ -76,16 +76,14 @@ dependencies {

We publish SBOMs with all of our releases as of 0.3.0. You can find them in Maven Central alongside the artifacts.

## 🌟 Features:
## 🌟 Features

- support for various backend [providers](https://openfeature.dev/docs/reference/concepts/provider)
- easy integration and extension via [hooks](https://openfeature.dev/docs/reference/concepts/hooks)
- bool, string, numeric, and object flag types
- [context-aware](https://openfeature.dev/docs/reference/concepts/evaluation-context) evaluation

## 🚀 Usage:

### Basics:
## 🚀 Usage

```java
public void example(){
Expand All @@ -102,7 +100,7 @@ public void example(){
}
```

### Context-aware evaluation:
### Context-aware evaluation

Sometimes the value of a flag must take into account some dynamic criteria about the application or user, such as the user location, IP, email address, or the location of the server.
In OpenFeature, we refer to this as [`targeting`](https://openfeature.dev/specification/glossary#targeting).
Expand All @@ -127,9 +125,73 @@ EvaluationContext reqCtx = new ImmutableContext(targetingKey, attributes);
boolean flagValue = client.getBooleanValue("some-flag", false, reqCtx);
```

### Events

Events allow you to react to state changes in the provider or underlying flag management system, such as flag definition changes, provider readiness, or error conditions.
Initialization events (`PROVIDER_READY` on success, `PROVIDER_ERROR` on failure) are dispatched for every provider.
Some providers support additional events, such as `PROVIDER_CONFIGURATION_CHANGED`.
Please refer to the documentation of the provider you're using to see what events are supported.

```java
// add an event handler to a client
client.onProviderConfigurationChanged((EventDetails eventDetails) -> {
// do something when the provider's flag settings change
});

// add an event handler to the global API
OpenFeatureAPI.getInstance().onProviderStale((EventDetails eventDetails) -> {
// do something when the provider's cache goes stale
});
```

### Hooks

A hook is a mechanism that allows for adding arbitrary behavior at well-defined points of the flag evaluation life-cycle.
Use cases include validating the resolved flag value, modifying or adding data to the evaluation context, logging, telemetry, and tracking.

```java
public class MyHook implements Hook {
/**
*
* @param ctx Information about the particular flag evaluation
* @param details Information about how the flag was resolved, including any resolved values.
* @param hints An immutable mapping of data for users to communicate to the hooks.
*/
@Override
public void after(HookContext ctx, FlagEvaluationDetails details, Map hints) {
System.out.println("After evaluation!");
}
}
```

See [here](https://openfeature.dev/ecosystem?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=Hook&instant_search%5BrefinementList%5D%5Btechnology%5D%5B0%5D=Java) for a catalog of available hooks.

### Logging:

The Java SDK uses SLF4J. See the [SLF4J manual](https://slf4j.org/manual.html) for complete documentation.

### Named clients

Clients can be given a name.
A name is a logical identifier which can be used to associate clients with a particular provider.
If a name has no associated provider, clients with that name use the global provider.

```java
FeatureProvider scopedProvider = new MyProvider();

// set this provider for clients named "my-name"
OpenFeatureAPI.getInstance().setProvider("my-name", provider);

// create a client bound to the provider above
Client client = OpenFeatureAPI.getInstance().getClient("my-name");
```

### Providers:

To develop a provider, you need to create a new project and include the OpenFeature SDK as a dependency. This can be a new repository or included in [the existing contrib repository](https://github.com/open-feature/java-sdk-contrib) available under the OpenFeature organization. Finally, you’ll then need to write the provider itself. This can be accomplished by implementing the `FeatureProvider` interface exported by the OpenFeature SDK.
To develop a provider, you need to create a new project and include the OpenFeature SDK as a dependency.
This can be a new repository or included in [the existing contrib repository](https://github.com/open-feature/java-sdk-contrib) available under the OpenFeature organization.
Finally, you’ll then need to write the provider itself.
This can be accomplished by implementing the `FeatureProvider` interface exported by the OpenFeature SDK.

```java
public class MyProvider implements FeatureProvider {
Expand Down Expand Up @@ -167,31 +229,16 @@ public class MyProvider implements FeatureProvider {

See [here](https://openfeature.dev/ecosystem?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=Provider&instant_search%5BrefinementList%5D%5Btechnology%5D%5B0%5D=Java) for a catalog of available providers.

### Hooks:
### Shutdown

A hook is a mechanism that allows for adding arbitrary behavior at well-defined points of the flag evaluation life-cycle. Use cases include validating the resolved flag value, modifying or adding data to the evaluation context, logging, telemetry, and tracking.
The OpenFeature API provides a close function to perform a cleanup of all registered providers.
This should only be called when your application is in the process of shutting down.

```java
public class MyHook implements Hook {
/**
*
* @param ctx Information about the particular flag evaluation
* @param details Information about how the flag was resolved, including any resolved values.
* @param hints An immutable mapping of data for users to communicate to the hooks.
*/
@Override
public void after(HookContext ctx, FlagEvaluationDetails details, Map hints) {
System.out.println("After evaluation!");
}
}
// shut down all providers
OpenFeatureAPI.getInstance().shutdown();
```

See [here](https://openfeature.dev/ecosystem?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=Hook&instant_search%5BrefinementList%5D%5Btechnology%5D%5B0%5D=Java) for a catalog of available hooks.

### Logging:

The Java SDK uses SLF4J. See the [SLF4J manual](https://slf4j.org/manual.html) for complete documentation.

### Complete API documentation:

See [here](https://www.javadoc.io/doc/dev.openfeature/sdk/latest/index.html) for the complete API documentation.
Expand Down

0 comments on commit c115e96

Please sign in to comment.