Assignment Details Part 1 of 7: AssignmentDetails return object and supporting classes

src/main/java/cloud/eppo/api/AllocationDetails.java

@@ -0,0 +1,30 @@
+package cloud.eppo.api;
+
+/**
+ * Details about an allocation evaluation, including its key, evaluation status, and position in the
+ * allocation list.
+ */
+public class AllocationDetails {
+  private final String key;
+  private final AllocationEvaluationCode allocationEvaluationCode;
+  private final int orderPosition;
+
+  public AllocationDetails(
+      String key, AllocationEvaluationCode allocationEvaluationCode, int orderPosition) {
+    this.key = key;
+    this.allocationEvaluationCode = allocationEvaluationCode;
+    this.orderPosition = orderPosition;
+  }
+
+  public String getKey() {
+    return key;
+  }
+
+  public AllocationEvaluationCode getAllocationEvaluationCode() {
+    return allocationEvaluationCode;
+  }
+
+  public int getOrderPosition() {
+    return orderPosition;
+  }
+}

src/main/java/cloud/eppo/api/AllocationEvaluationCode.java

@@ -0,0 +1,61 @@
+package cloud.eppo.api;
+
+/**
+ * Enum representing the result code of an allocation evaluation within a flag.
+ *
+ * <p>Allocations are evaluated in order, and this code indicates why an allocation was or was not
+ * selected.
+ */
+public enum AllocationEvaluationCode {
+  /** Allocation rules matched and the allocation was selected. */
+  MATCH("MATCH"),
+
+  /** Allocation rules did not match the subject attributes. */
+  FAILING_RULE("FAILING_RULE"),
+
+  /** Current time is before the allocation's start time. */
+  BEFORE_START_TIME("BEFORE_START_TIME"),
+
+  /** Current time is after the allocation's end time. */
+  AFTER_END_TIME("AFTER_END_TIME"),
+
+  /** Subject was not selected due to traffic exposure percentage. */
+  TRAFFIC_EXPOSURE_MISS("TRAFFIC_EXPOSURE_MISS"),
+
+  /** Allocation was not evaluated (e.g., a previous allocation matched). */
+  UNEVALUATED("UNEVALUATED");
+
+  private final String code;
+
+  AllocationEvaluationCode(String code) {
+    this.code = code;
+  }
+
+  /** Returns the string representation of this allocation evaluation code. */
+  public String getCode() {
+    return code;
+  }
+
+  /**
+   * Parses a string code into an AllocationEvaluationCode enum.
+   *
+   * @param code the string code to parse
+   * @return the corresponding AllocationEvaluationCode, or null if not recognized
+   */
+  public static AllocationEvaluationCode fromString(String code) {
+    if (code == null) {
+      return null;
+    }
+    for (AllocationEvaluationCode evaluationCode : values()) {
+      if (evaluationCode.code.equals(code)) {
+        return evaluationCode;
+      }
+    }
+    return null;
+  }
+
+  @Override
+  public String toString() {
+    return code;
+  }
+}

src/main/java/cloud/eppo/api/AssignmentDetails.java

@@ -0,0 +1,31 @@
+package cloud.eppo.api;
+
+/**
+ * Contains both the assigned variation value and comprehensive evaluation details explaining why
+ * that variation was assigned.
+ *
+ * @param <T> The type of the variation value (Boolean, Integer, Double, String, etc.)
+ */
+public class AssignmentDetails<T> {
+  private final T variation;
+  private final String action;
+  private final EvaluationDetails evaluationDetails;
+
+  public AssignmentDetails(T variation, String action, EvaluationDetails evaluationDetails) {
+    this.variation = variation;
+    this.action = action;
+    this.evaluationDetails = evaluationDetails;
+  }
+
+  public T getVariation() {
+    return variation;
+  }
+
+  public String getAction() {
+    return action;
+  }
+
+  public EvaluationDetails getEvaluationDetails() {
+    return evaluationDetails;
+  }
+}

src/main/java/cloud/eppo/api/EvaluationDetails.java

@@ -0,0 +1,271 @@
+package cloud.eppo.api;
+
+import java.util.ArrayList;
+import java.util.Date;
+import java.util.List;
+
+/**
+ * Contains comprehensive debugging information about a flag evaluation. This includes why a
+ * particular variation was assigned, which allocations matched or didn't match, and other metadata
+ * useful for understanding flag behavior.
+ */
+public class EvaluationDetails {
+  private final String environmentName;
+  private final Date configFetchedAt;
+  private final Date configPublishedAt;
+  private final FlagEvaluationCode flagEvaluationCode;
+  private final String flagEvaluationDescription;
+  private final String banditKey;
+  private final String banditAction;
+  private final String variationKey;
+  private final EppoValue variationValue;
+  private final MatchedRule matchedRule;
+  private final AllocationDetails matchedAllocation;
+  private final List<AllocationDetails> unmatchedAllocations;
+  private final List<AllocationDetails> unevaluatedAllocations;
+
+  public EvaluationDetails(
+      String environmentName,
+      Date configFetchedAt,
+      Date configPublishedAt,
+      FlagEvaluationCode flagEvaluationCode,
+      String flagEvaluationDescription,
+      String banditKey,
+      String banditAction,
+      String variationKey,
+      EppoValue variationValue,
+      MatchedRule matchedRule,
+      AllocationDetails matchedAllocation,
+      List<AllocationDetails> unmatchedAllocations,
+      List<AllocationDetails> unevaluatedAllocations) {
+    this.environmentName = environmentName;
+    this.configFetchedAt = configFetchedAt;
+    this.configPublishedAt = configPublishedAt;
+    this.flagEvaluationCode = flagEvaluationCode;
+    this.flagEvaluationDescription = flagEvaluationDescription;
+    this.banditKey = banditKey;
+    this.banditAction = banditAction;
+    this.variationKey = variationKey;
+    this.variationValue = variationValue;
+    this.matchedRule = matchedRule;
+    this.matchedAllocation = matchedAllocation;
+    this.unmatchedAllocations = unmatchedAllocations;
+    this.unevaluatedAllocations = unevaluatedAllocations;
+  }
+
+  public String getEnvironmentName() {
+    return environmentName;
+  }
+
+  public Date getConfigFetchedAt() {
+    return configFetchedAt;
+  }
+
+  public Date getConfigPublishedAt() {
+    return configPublishedAt;
+  }
+
+  public FlagEvaluationCode getFlagEvaluationCode() {
+    return flagEvaluationCode;
+  }
+
+  public String getFlagEvaluationDescription() {
+    return flagEvaluationDescription;
+  }
+
+  public String getBanditKey() {
+    return banditKey;
+  }
+
+  public String getBanditAction() {
+    return banditAction;
+  }
+
+  public String getVariationKey() {
+    return variationKey;
+  }
+
+  public EppoValue getVariationValue() {
+    return variationValue;
+  }
+
+  public MatchedRule getMatchedRule() {
+    return matchedRule;
+  }
+
+  public AllocationDetails getMatchedAllocation() {
+    return matchedAllocation;
+  }
+
+  public List<AllocationDetails> getUnmatchedAllocations() {
+    return unmatchedAllocations;
+  }
+
+  public List<AllocationDetails> getUnevaluatedAllocations() {
+    return unevaluatedAllocations;
+  }
+
+  public boolean evaluationSuccessful() {
+    return !flagEvaluationCode.isError();
+  }
+
+  /** Creates a new Builder for constructing EvaluationDetails. */
+  public static Builder builder() {
+    return new Builder();
+  }
+
+  /**
+   * Creates a default EvaluationDetails for error conditions or when no flag was matched. This is a
+   * convenience factory method for common error scenarios.
+   */
+  public static EvaluationDetails buildDefault(
+      String environmentName,
+      Date configFetchedAt,
+      Date configPublishedAt,
+      FlagEvaluationCode flagEvaluationCode,
+      String flagEvaluationDescription,
+      EppoValue variationValue) {
+    return builder()
+        .environmentName(environmentName)
+        .configFetchedAt(configFetchedAt)
+        .configPublishedAt(configPublishedAt)
+        .flagEvaluationCode(flagEvaluationCode)
+        .flagEvaluationDescription(flagEvaluationDescription)
+        .variationValue(variationValue)
+        .build();
+  }
+
+  /**
+   * Creates a new Builder initialized with values from an existing EvaluationDetails. Useful for
+   * creating a modified copy.
+   */
+  public static Builder builder(EvaluationDetails copyFrom) {
+    return new Builder()
+        .environmentName(copyFrom.environmentName)
+        .configFetchedAt(copyFrom.configFetchedAt)
+        .configPublishedAt(copyFrom.configPublishedAt)
+        .flagEvaluationCode(copyFrom.flagEvaluationCode)
+        .flagEvaluationDescription(copyFrom.flagEvaluationDescription)
+        .banditKey(copyFrom.banditKey)
+        .banditAction(copyFrom.banditAction)
+        .variationKey(copyFrom.variationKey)
+        .variationValue(copyFrom.variationValue)
+        .matchedRule(copyFrom.matchedRule)
+        .matchedAllocation(copyFrom.matchedAllocation)
+        .unmatchedAllocations(copyFrom.unmatchedAllocations)
+        .unevaluatedAllocations(copyFrom.unevaluatedAllocations);
+  }
+
+  /** Builder for constructing EvaluationDetails instances. */
+  public static class Builder {
+    private String environmentName = "Unknown";
+    private Date configFetchedAt;
+    private Date configPublishedAt;
+    private FlagEvaluationCode flagEvaluationCode;
+    private String flagEvaluationDescription;
+    private String banditKey;
+    private String banditAction;
+    private String variationKey;
+    private EppoValue variationValue;
+    private MatchedRule matchedRule;
+    private AllocationDetails matchedAllocation;
+    private List<AllocationDetails> unmatchedAllocations = new ArrayList<>();
+    private List<AllocationDetails> unevaluatedAllocations = new ArrayList<>();
+
+    public Builder environmentName(String environmentName) {
+      this.environmentName = environmentName != null ? environmentName : "Unknown";
+      return this;
+    }
+
+    public Builder configFetchedAt(Date configFetchedAt) {
+      this.configFetchedAt = configFetchedAt;
+      return this;
+    }
+
+    public Builder configPublishedAt(Date configPublishedAt) {
+      this.configPublishedAt = configPublishedAt;
+      return this;
+    }
+
+    public Builder flagEvaluationCode(FlagEvaluationCode flagEvaluationCode) {
+      this.flagEvaluationCode = flagEvaluationCode;
+      return this;
+    }
+
+    public Builder flagEvaluationDescription(String flagEvaluationDescription) {
+      this.flagEvaluationDescription = flagEvaluationDescription;
+      return this;
+    }
+
+    public Builder banditKey(String banditKey) {
+      this.banditKey = banditKey;
+      return this;
+    }
+
+    public Builder banditAction(String banditAction) {
+      this.banditAction = banditAction;
+      return this;
+    }
+
+    public Builder variationKey(String variationKey) {
+      this.variationKey = variationKey;
+      return this;
+    }
+
+    public Builder variationValue(EppoValue variationValue) {
+      this.variationValue = variationValue;
+      return this;
+    }
+
+    public Builder matchedRule(MatchedRule matchedRule) {
+      this.matchedRule = matchedRule;
+      return this;
+    }
+
+    public Builder matchedAllocation(AllocationDetails matchedAllocation) {
+      this.matchedAllocation = matchedAllocation;
+      return this;
+    }
+
+    public Builder unmatchedAllocations(List<AllocationDetails> unmatchedAllocations) {
+      this.unmatchedAllocations =
+          unmatchedAllocations != null ? new ArrayList<>(unmatchedAllocations) : new ArrayList<>();
+      return this;
+    }
+
+    public Builder addUnmatchedAllocation(AllocationDetails allocation) {
+      this.unmatchedAllocations.add(allocation);
+      return this;
+    }
+
+    public Builder unevaluatedAllocations(List<AllocationDetails> unevaluatedAllocations) {
+      this.unevaluatedAllocations =
+          unevaluatedAllocations != null
+              ? new ArrayList<>(unevaluatedAllocations)
+              : new ArrayList<>();
+      return this;
+    }
+
+    public Builder addUnevaluatedAllocation(AllocationDetails allocation) {
+      this.unevaluatedAllocations.add(allocation);
+      return this;
+    }
+
+    public EvaluationDetails build() {
+      return new EvaluationDetails(
+          environmentName,
+          configFetchedAt,
+          configPublishedAt,
+          flagEvaluationCode,
+          flagEvaluationDescription,
+          banditKey,
+          banditAction,
+          variationKey,
+          variationValue,
+          matchedRule,
+          matchedAllocation,
+          unmatchedAllocations,
+          unevaluatedAllocations);
+    }
+  }
+}