Merge pull request #17 from open-feature/mocked-logger

Add javadoc to interfaces and tidy them up.

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 <T> The type of flag being evaluated.
+ */
 public interface BaseEvaluation<T> {
     /**
      * Returns the resolved value of the evaluation.

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<Hook> getClientHooks();
 }

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<Boolean> getBooleanEvaluation(String key, Boolean defaultValue, EvaluationContext ctx, FlagEvaluationOptions options);

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);

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 <T> the type of the flag being evaluated.
+ */
 @Data @Builder
 public class FlagEvaluationDetails<T> implements BaseEvaluation<T> {
     String flagKey;

lib/src/main/java/dev/openfeature/javasdk/FlagEvaluationLifecycle.java

@@ -1,8 +0,0 @@
-package dev.openfeature.javasdk;
-
-import java.util.List;
-
-public interface FlagEvaluationLifecycle {
-    void addHooks(Hook... hooks);
-    List<Hook> getClientHooks();
-}

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 <T> The type of the flag being evaluated.
+ */
 public interface Hook<T> {
+    /**
+     * 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<EvaluationContext> before(HookContext<T> ctx, ImmutableMap<String, Object> 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<T> ctx, FlagEvaluationDetails<T> details, ImmutableMap<String, Object> 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<T> ctx, Exception error, ImmutableMap<String, Object> 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<T> ctx, ImmutableMap<String, Object> hints) {}
 }

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 <T> the type for the flag being evaluated
+ */
 @Value @Builder @With
 public class HookContext<T> {
     @NonNull String flagKey;

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();
 }

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

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;