From d2e61eb68878c2a3f524cb7e4cfb8bbbc1eaa220 Mon Sep 17 00:00:00 2001 From: Justin Abrahms Date: Mon, 13 Jun 2022 23:43:08 -0700 Subject: [PATCH] Add javadoc to interfaces and tidy them up. Fixes #14 --- .../openfeature/javasdk/BaseEvaluation.java | 4 +++ .../java/dev/openfeature/javasdk/Client.java | 22 ++++++++++++- .../openfeature/javasdk/FeatureProvider.java | 3 ++ .../dev/openfeature/javasdk/Features.java | 3 ++ .../javasdk/FlagEvaluationDetails.java | 4 +++ .../javasdk/FlagEvaluationLifecycle.java | 8 ----- .../java/dev/openfeature/javasdk/Hook.java | 31 +++++++++++++++++++ .../dev/openfeature/javasdk/HookContext.java | 5 +++ .../dev/openfeature/javasdk/Metadata.java | 3 ++ .../dev/openfeature/javasdk/NoOpProvider.java | 3 ++ .../openfeature/javasdk/OpenFeatureAPI.java | 5 +++ 11 files changed, 82 insertions(+), 9 deletions(-) delete mode 100644 lib/src/main/java/dev/openfeature/javasdk/FlagEvaluationLifecycle.java diff --git a/lib/src/main/java/dev/openfeature/javasdk/BaseEvaluation.java b/lib/src/main/java/dev/openfeature/javasdk/BaseEvaluation.java index 9f06853d..bccdfe5d 100644 --- a/lib/src/main/java/dev/openfeature/javasdk/BaseEvaluation.java +++ b/lib/src/main/java/dev/openfeature/javasdk/BaseEvaluation.java @@ -1,5 +1,9 @@ package dev.openfeature.javasdk; +/** + * We differ between the evaluation results that providers return and what is given to the end users. This is a common interface between them. + * @param The type of flag being evaluated. + */ public interface BaseEvaluation { /** * Returns the resolved value of the evaluation. diff --git a/lib/src/main/java/dev/openfeature/javasdk/Client.java b/lib/src/main/java/dev/openfeature/javasdk/Client.java index b57c344d..cbe1bc91 100644 --- a/lib/src/main/java/dev/openfeature/javasdk/Client.java +++ b/lib/src/main/java/dev/openfeature/javasdk/Client.java @@ -1,5 +1,25 @@ package dev.openfeature.javasdk; -public interface Client extends FlagEvaluationLifecycle, Features { +import java.util.List; + +/** + * Interface used to resolve flags of varying types. + */ +public interface Client extends Features { Metadata getMetadata(); + + /** + * Adds hooks for evaluation. + * + * Hooks are run in the order they're added in the before stage. They are run in reverse order for all other stages. + * + * @param hooks The hook to add. + */ + void addHooks(Hook... hooks); + + /** + * Fetch the hooks associated to this client. + * @return A list of {@link Hook}s. + */ + List getClientHooks(); } diff --git a/lib/src/main/java/dev/openfeature/javasdk/FeatureProvider.java b/lib/src/main/java/dev/openfeature/javasdk/FeatureProvider.java index 014b5ccd..c1310831 100644 --- a/lib/src/main/java/dev/openfeature/javasdk/FeatureProvider.java +++ b/lib/src/main/java/dev/openfeature/javasdk/FeatureProvider.java @@ -1,5 +1,8 @@ package dev.openfeature.javasdk; +/** + * The interface implemented by upstream flag providers to resolve flags for their service. + */ public interface FeatureProvider { Metadata getMetadata(); ProviderEvaluation getBooleanEvaluation(String key, Boolean defaultValue, EvaluationContext ctx, FlagEvaluationOptions options); diff --git a/lib/src/main/java/dev/openfeature/javasdk/Features.java b/lib/src/main/java/dev/openfeature/javasdk/Features.java index beff9849..d831b3a6 100644 --- a/lib/src/main/java/dev/openfeature/javasdk/Features.java +++ b/lib/src/main/java/dev/openfeature/javasdk/Features.java @@ -1,5 +1,8 @@ package dev.openfeature.javasdk; +/** + * An API for the type-specific fetch methods we offer end users. + */ public interface Features { Boolean getBooleanValue(String key, Boolean defaultValue); diff --git a/lib/src/main/java/dev/openfeature/javasdk/FlagEvaluationDetails.java b/lib/src/main/java/dev/openfeature/javasdk/FlagEvaluationDetails.java index 1df0a144..5a7307ef 100644 --- a/lib/src/main/java/dev/openfeature/javasdk/FlagEvaluationDetails.java +++ b/lib/src/main/java/dev/openfeature/javasdk/FlagEvaluationDetails.java @@ -5,6 +5,10 @@ import lombok.Data; import javax.annotation.Nullable; +/** + * Contains information about how the evaluation happened, including any resolved values. + * @param the type of the flag being evaluated. + */ @Data @Builder public class FlagEvaluationDetails implements BaseEvaluation { String flagKey; diff --git a/lib/src/main/java/dev/openfeature/javasdk/FlagEvaluationLifecycle.java b/lib/src/main/java/dev/openfeature/javasdk/FlagEvaluationLifecycle.java deleted file mode 100644 index ee5bce40..00000000 --- a/lib/src/main/java/dev/openfeature/javasdk/FlagEvaluationLifecycle.java +++ /dev/null @@ -1,8 +0,0 @@ -package dev.openfeature.javasdk; - -import java.util.List; - -public interface FlagEvaluationLifecycle { - void addHooks(Hook... hooks); - List getClientHooks(); -} diff --git a/lib/src/main/java/dev/openfeature/javasdk/Hook.java b/lib/src/main/java/dev/openfeature/javasdk/Hook.java index 5d38b16e..35dd19db 100644 --- a/lib/src/main/java/dev/openfeature/javasdk/Hook.java +++ b/lib/src/main/java/dev/openfeature/javasdk/Hook.java @@ -4,11 +4,42 @@ import com.google.common.collect.ImmutableMap; import java.util.Optional; +/** + * An extension point which can run around flag resolution. They are intended to be used as a way to add custom logic + * to the lifecycle of flag evaluation. + * @param The type of the flag being evaluated. + */ public interface Hook { + /** + * Runs before flag is resolved. + * @param ctx Information about the particular flag evaluation + * @param hints An immutable mapping of data for users to communicate to the hooks. + * @return An optional {@link EvaluationContext}. If returned, it will be merged with the EvaluationContext instances from other hooks, the client and API. + */ default Optional before(HookContext ctx, ImmutableMap hints) { return Optional.empty(); } + + /** + * Runs after a flag is resolved. + * @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. + */ default void after(HookContext ctx, FlagEvaluationDetails details, ImmutableMap hints) {} + + /** + * Run when evaluation encounters an error. This will always run. Errors thrown will be swallowed. + * @param ctx Information about the particular flag evaluation + * @param error The exception that was thrown. + * @param hints An immutable mapping of data for users to communicate to the hooks. + */ default void error(HookContext ctx, Exception error, ImmutableMap hints) {} + + /** + * Run after flag evaluation, including any error processing. This will always run. Errors will be swallowed. + * @param ctx Information about the particular flag evaluation + * @param hints An immutable mapping of data for users to communicate to the hooks. + */ default void finallyAfter(HookContext ctx, ImmutableMap hints) {} } diff --git a/lib/src/main/java/dev/openfeature/javasdk/HookContext.java b/lib/src/main/java/dev/openfeature/javasdk/HookContext.java index e61e0fc9..1d3669bf 100644 --- a/lib/src/main/java/dev/openfeature/javasdk/HookContext.java +++ b/lib/src/main/java/dev/openfeature/javasdk/HookContext.java @@ -5,6 +5,11 @@ import lombok.NonNull; import lombok.Value; import lombok.With; +/** + * A data class to hold immutable context that {@link Hook} instances use. + * + * @param the type for the flag being evaluated + */ @Value @Builder @With public class HookContext { @NonNull String flagKey; diff --git a/lib/src/main/java/dev/openfeature/javasdk/Metadata.java b/lib/src/main/java/dev/openfeature/javasdk/Metadata.java index c0c06e96..d1c291fd 100644 --- a/lib/src/main/java/dev/openfeature/javasdk/Metadata.java +++ b/lib/src/main/java/dev/openfeature/javasdk/Metadata.java @@ -1,5 +1,8 @@ package dev.openfeature.javasdk; +/** + * Holds identifying information about a given entity + */ public interface Metadata { public String getName(); } diff --git a/lib/src/main/java/dev/openfeature/javasdk/NoOpProvider.java b/lib/src/main/java/dev/openfeature/javasdk/NoOpProvider.java index f3365520..ff5aa734 100644 --- a/lib/src/main/java/dev/openfeature/javasdk/NoOpProvider.java +++ b/lib/src/main/java/dev/openfeature/javasdk/NoOpProvider.java @@ -2,6 +2,9 @@ package dev.openfeature.javasdk; import lombok.Getter; +/** + * A {@link FeatureProvider} that simply returns the default values passed to it. + */ public class NoOpProvider implements FeatureProvider { public static final String PASSED_IN_DEFAULT = "Passed in default"; @Getter diff --git a/lib/src/main/java/dev/openfeature/javasdk/OpenFeatureAPI.java b/lib/src/main/java/dev/openfeature/javasdk/OpenFeatureAPI.java index aca5d61f..55e44aa2 100644 --- a/lib/src/main/java/dev/openfeature/javasdk/OpenFeatureAPI.java +++ b/lib/src/main/java/dev/openfeature/javasdk/OpenFeatureAPI.java @@ -8,6 +8,11 @@ import java.util.ArrayList; import java.util.Arrays; import java.util.List; +/** + * A global singleton which holds base configuration for the OpenFeature library. + * + * Configuration here will be shared across all {@link Client}s. + */ public class OpenFeatureAPI { @Getter @Setter private FeatureProvider provider; private static OpenFeatureAPI api;