Package com.launchdarkly.sdk

Class EvaluationReason

java.lang.Object
com.launchdarkly.sdk.EvaluationReason
All Implemented Interfaces:
JsonSerializable
public final class EvaluationReason extends Object implements JsonSerializable
Describes the reason that a flag evaluation produced a particular value.

This is returned within EvaluationDetail by the SDK's "variation detail" methods such as boolVariationDetail.

Note that while EvaluationReason has subclasses as an implementation detail, the subclasses are not public and may be removed in the future. Always use methods of the base class such as getKind() or getRuleIndex() to inspect the reason.

LaunchDarkly defines a standard JSON encoding for evaluation reasons, used in analytics events. EvaluationReason can be converted to and from JSON in any of these ways:

  1. With JsonSerialization.
  2. With Gson, if and only if you configure your Gson instance with LDGson.
  3. With Jackson, if and only if you configure your ObjectMapper instance with LDJackson.

  • Method Details

    • getKind

      public EvaluationReason.Kind getKind()
      Returns an enum indicating the general category of the reason.
      Returns:
      a EvaluationReason.Kind value

    • getRuleIndex

      public int getRuleIndex()
      The index of the rule that was matched (0 for the first rule in the feature flag), if the kind is EvaluationReason.Kind.RULE_MATCH. Otherwise this returns -1.
      Returns:
      the rule index or -1

    • getRuleId

      public String getRuleId()
      The unique identifier of the rule that was matched, if the kind is EvaluationReason.Kind.RULE_MATCH. Otherwise null.

      Unlike the rule index, this identifier will not change if other rules are added or deleted.

      Returns:
      the rule identifier or null

    • getPrerequisiteKey

      public String getPrerequisiteKey()
      The key of the prerequisite flag that did not return the desired variation, if the kind is EvaluationReason.Kind.PREREQUISITE_FAILED. Otherwise null.
      Returns:
      the prerequisite flag key or null

    • isInExperiment

      public boolean isInExperiment()
      Whether the evaluation was part of an experiment. Returns true if the evaluation resulted in an experiment rollout *and* served one of the variations in the experiment. Otherwise it returns false.
      Returns:
      whether the evaluation was part of an experiment

    • getErrorKind

      public EvaluationReason.ErrorKind getErrorKind()
      An enumeration value indicating the general category of error, if the kind is EvaluationReason.Kind.PREREQUISITE_FAILED. Otherwise null.
      Returns:
      the error kind or null

    • getException

      public Exception getException()
      The exception that caused the error condition, if the kind is EvaluationReason.Kind.ERROR and the errorKind is EvaluationReason.ErrorKind.EXCEPTION. Otherwise null.

      Note that the exception will not be included in the JSON serialization of the reason when it appears in analytics events; it is only provided informationally for use by application code.

      Returns:
      the exception instance

    • getBigSegmentsStatus

      public EvaluationReason.BigSegmentsStatus getBigSegmentsStatus()
      Describes the validity of Big Segment information, if and only if the flag evaluation required querying at least one Big Segment. Otherwise it returns null.

      Big Segments are a specific type of user segments. For more information, read the LaunchDarkly documentation .

      Returns:
      the EvaluationReason.BigSegmentsStatus from the evaluation or null

    • withBigSegmentsStatus

      public EvaluationReason withBigSegmentsStatus(EvaluationReason.BigSegmentsStatus bigSegmentsStatus)
      Returns a copy of this EvaluationReason with a specific EvaluationReason.BigSegmentsStatus value.
      Parameters:
      bigSegmentsStatus - the new property value
      Returns:
      a new reason object

    • toString

      public String toString()
      Returns a simple string representation of the reason.

      This is a convenience method for debugging and any other use cases where a human-readable string is helpful. The exact format of the string is subject to change; if you need to make programmatic decisions based on the reason properties, use other methods like getKind().

      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object other)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • off

      public static EvaluationReason off()
      Returns an instance whose kind is EvaluationReason.Kind.OFF.
      Returns:
      a reason object

    • fallthrough

      public static EvaluationReason fallthrough()
      Returns an instance whose kind is EvaluationReason.Kind.FALLTHROUGH.
      Returns:
      a reason object

    • fallthrough

      public static EvaluationReason fallthrough(boolean inExperiment)
      Returns an instance whose kind is EvaluationReason.Kind.FALLTHROUGH and where the inExperiment parameter represents whether the evaluation was part of an experiment.
      Parameters:
      inExperiment - whether the evaluation was part of an experiment
      Returns:
      a reason object

    • targetMatch

      public static EvaluationReason targetMatch()
      Returns an instance whose kind is EvaluationReason.Kind.TARGET_MATCH.
      Returns:
      a reason object

    • ruleMatch

      public static EvaluationReason ruleMatch(int ruleIndex, String ruleId)
      Returns an instance whose kind is EvaluationReason.Kind.RULE_MATCH.
      Parameters:
      ruleIndex - the rule index
      ruleId - the rule identifier
      Returns:
      a reason object

    • ruleMatch

      public static EvaluationReason ruleMatch(int ruleIndex, String ruleId, boolean inExperiment)
      Returns an instance whose kind is EvaluationReason.Kind.RULE_MATCH and where the inExperiment parameter represents whether the evaluation was part of an experiment.
      Parameters:
      ruleIndex - the rule index
      ruleId - the rule identifier
      inExperiment - whether the evaluation was part of an experiment
      Returns:
      a reason object

    • prerequisiteFailed

      public static EvaluationReason prerequisiteFailed(String prerequisiteKey)
      Returns an instance whose kind is EvaluationReason.Kind.PREREQUISITE_FAILED.
      Parameters:
      prerequisiteKey - the flag key of the prerequisite that failed
      Returns:
      a reason object

    • error

      public static EvaluationReason error(EvaluationReason.ErrorKind errorKind)
      Returns an instance whose kind is EvaluationReason.Kind.ERROR.
      Parameters:
      errorKind - describes the type of error
      Returns:
      a reason object

    • exception

      public static EvaluationReason exception(Exception exception)
      Returns an instance whose kind is EvaluationReason.Kind.ERROR, with an exception instance.

      Note that the exception will not be included in the JSON serialization of the reason when it appears in analytics events; it is only provided informationally for use by application code.

      Parameters:
      exception - the exception that caused the error
      Returns:
      a reason object