Package 

Interface FlagsClient

  • 
public interface FlagsClient

    Client interface for evaluating feature flags and experiments.

    This interface defines the public API that applications use to retrieve feature flag values. It follows the OpenFeature specification closely, to simplify implementing the OpenFeature Provider API on top.

    To create a FlagsClient, use the Builder:

    // Default client
val client = FlagsClient.Builder().build()

// Named client
val client = FlagsClient.Builder("analytics").build()

// With custom configuration
val client = FlagsClient.Builder("analytics")
    .useCustomExposureEndpoint("https://custom.endpoint.com/exposure")
    .build()

    To retrieve an existing FlagsClient, use get:

    val client = FlagsClient.get("analytics")

    • Method Detail

      • setEvaluationContext

         abstract Unit setEvaluationContext(EvaluationContext context, EvaluationContextCallback callback)

        Sets the EvaluationContext for flag resolution.

        The context is used to determine which flag values to return based on user targeting rules. This method triggers a background fetch of updated flag evaluations.

        This method returns immediately without blocking. The actual context update and flag fetching happen asynchronously on a background thread.

        Parameters:
        context - The EvaluationContext containing targeting key and attributes.
        callback - Optional callback to notify when the operation completes or fails.

      • resolveBooleanValue

         abstract Boolean resolveBooleanValue(String flagKey, Boolean defaultValue)

        Resolves a boolean flag value.

        Parameters:
        flagKey - The unique identifier of the flag to resolve.
        defaultValue - The value to return if the flag cannot be retrieved or parsed.

      • resolveStringValue

         abstract String resolveStringValue(String flagKey, String defaultValue)

        Resolves a string flag value.

        Parameters:
        flagKey - The unique identifier of the flag to resolve.
        defaultValue - The value to return if the flag cannot be retrieved or parsed.

      • resolveDoubleValue

         abstract Double resolveDoubleValue(String flagKey, Double defaultValue)

        Resolves a numeric flag value.

        Parameters:
        flagKey - The unique identifier of the flag to resolve.
        defaultValue - The value to return if the flag cannot be retrieved or parsed.

      • resolveIntValue

         abstract Integer resolveIntValue(String flagKey, Integer defaultValue)

        Resolves an integer flag value.

        Parameters:
        flagKey - The unique identifier of the flag to resolve.
        defaultValue - The value to return if the flag cannot be retrieved or parsed.

      • resolveStructureValue

         abstract JSONObject resolveStructureValue(String flagKey, JSONObject defaultValue)

        Resolves a structured flag value as a JSONObject.

        Parameters:
        flagKey - The unique identifier of the flag to resolve.
        defaultValue - The value to return if the flag cannot be retrieved or parsed.

      • resolveStructureValue

         abstract Map<String, Object> resolveStructureValue(String flagKey, Map<String, Object> defaultValue)

        Resolves a structured flag value as a Map.

        The returned Map contains only primitives (String, Int, Long, Double, Boolean), null values, nested Maps, and Lists. All nested structures are recursively converted.

        This method is useful for integrations that prefer working with Kotlin collections over JSON types.

        Parameters:
        flagKey - The unique identifier of the flag to resolve.
        defaultValue - The map to return if the flag cannot be retrieved or parsed.

      • resolve

         abstract <T extends Any> ResolutionDetails<T> resolve(String flagKey, T defaultValue)

        Resolves a flag value with detailed resolution information.

        This is the core resolution method that provides comprehensive details about the flag resolution process, including the resolved value, variant identifier, resolution reason, error information, and any associated metadata.

        // Boolean flag
val boolResult = client.resolve("feature-enabled", false)
if (boolResult.errorCode == null) {
    println("Feature is ${boolResult.value}, variant: ${boolResult.variant}")
}

// String flag
val stringResult = client.resolve("api-endpoint", "https://default.com")
println("Using endpoint: ${stringResult.value}")

// With metadata
val result = client.resolve("experiment", "control")
result.flagMetadata?.let { metadata ->
    println("Experiment metadata: $metadata")
}
        Parameters:
        flagKey - The unique identifier of the flag to resolve.
        defaultValue - The value to return if the flag cannot be retrieved or parsed.

      • getState

         abstract StateObservable getState()

        Observable interface for tracking client state changes.

        Provides three ways to observe state:

        Example:

        // Synchronous
val current = client.state.getCurrentState()

// Callback
client.state.addListener(listener)