From 4a4f2c836c31556bccc5edc9883b867a855a3dda Mon Sep 17 00:00:00 2001 From: Nicky Bondarenko Date: Fri, 26 Jul 2024 12:25:52 +0200 Subject: [PATCH] docs: Add docs to public APIs --- .../java/com/spotify/confidence/Confidence.kt | 48 +++++++++++++++++++ .../spotify/confidence/ConfidenceContext.kt | 22 +++++++++ .../com/spotify/confidence/EventSender.kt | 15 ++++++ 3 files changed, 85 insertions(+) diff --git a/Confidence/src/main/java/com/spotify/confidence/Confidence.kt b/Confidence/src/main/java/com/spotify/confidence/Confidence.kt index a46b1c46..91ab4cfb 100644 --- a/Confidence/src/main/java/com/spotify/confidence/Confidence.kt +++ b/Confidence/src/main/java/com/spotify/confidence/Confidence.kt @@ -80,13 +80,28 @@ class Confidence internal constructor( } } + /** + * Apply a flag + * @param flagName name of the flag. + * @param resolveToken resolve token. + */ fun apply(flagName: String, resolveToken: String) { flagApplier.apply(flagName, resolveToken) debugLogger?.logFlag("Apply", flagName) } + /** + * @return flag value for a specific flag. + * @param key expects dot-notation to retrieve a specific entry in the flag's value, e.g. "flagname.myentry" + * @param default returned in case of errors or in case of the variant's rule indicating to use the default value. + */ fun getValue(key: String, default: T) = getFlag(key, default).value + /** + * @return evaluation data for a specific flag. Evaluation data includes the variant's name and reason/error information. + * @param key expects dot-notation to retrieve a specific entry in the flag's value, e.g. "flagname.myentry" + * @param default returned in case of errors or in case of the variant's rule indicating to use the default value. + */ fun getFlag( key: String, default: T @@ -116,8 +131,16 @@ class Confidence internal constructor( debugLogger?.logContext("PutContext", contextMap.value) } + /** + * Check if cache is empty + */ fun isStorageEmpty(): Boolean = diskStorage.read() == FlagResolution.EMPTY + /** + * Mutate context by adding an entry and removing another + * @param context context to add. + * @param removedKeys key to remove from context. + */ @Synchronized fun putContext(context: Map, removedKeys: List) { val map = contextMap.value.toMutableMap() @@ -192,16 +215,29 @@ class Confidence internal constructor( } } + /** + * Activating the cache means that the flag data on disk is loaded into memory, so consumers can access flag values. + */ fun activate() { val resolveResponse = diskStorage.read() cache.refresh(resolveResponse) } + /** + * Fetch latest flag evaluations and store them on disk. Note that "activate" must be called for this data to be + * made available in the app session. + */ fun asyncFetch() { currentFetchJob?.cancel() currentFetchJob = fetch() } + /** + * Fetch latest flag evaluations and store them on disk. Regardless of the fetch outcome (success or failure), this + * function activates the cache after the fetch. + * Activating the cache means that the flag data on disk is loaded into memory, so consumers can access flag values. + * Fetching is best-effort, so no error is propagated. Errors can still be thrown if something goes wrong access data on disk. + */ suspend fun fetchAndActivate() = kotlinx.coroutines.withContext(dispatcher) { currentFetchJob?.cancel() currentFetchJob = fetch() @@ -245,7 +281,19 @@ class Confidence internal constructor( internal const val VISITOR_ID_CONTEXT_KEY = "visitor_id" +/** + * Confidence instance, which can be used for flag evaluation and event tracking. + */ object ConfidenceFactory { + /** + * Create a Factory Confidence instance. + * @param context application context. + * @param clientSecret confidence clientSecret, which is found in Confidence console. + * @param initialContext can be set initially, e.g. targeting_key:value. + * @param region region of operation. + * @param dispatcher coroutine dispatcher. + * @param loggingLevel allows to print warnings or debugging information to the local console. + */ fun create( context: Context, clientSecret: String, diff --git a/Confidence/src/main/java/com/spotify/confidence/ConfidenceContext.kt b/Confidence/src/main/java/com/spotify/confidence/ConfidenceContext.kt index 950a0239..aed804f7 100644 --- a/Confidence/src/main/java/com/spotify/confidence/ConfidenceContext.kt +++ b/Confidence/src/main/java/com/spotify/confidence/ConfidenceContext.kt @@ -1,15 +1,37 @@ package com.spotify.confidence interface ConfidenceContextProvider { + /** + * @return context of given instance, including parent context if applicable. + */ fun getContext(): Map } typealias ConfidenceFieldsType = Map interface Contextual : ConfidenceContextProvider { + /** + * Create a new Confidence child instance based on an existing Confidence instance + * @param context additional context. + */ fun withContext(context: Map): Contextual + /** + * Add entry to context + * @param context context to add. + */ fun putContext(context: Map) + + /** + * Add entry to context + * @param key key of the entry. + * @param value value of the entry. + */ fun putContext(key: String, value: ConfidenceValue) + + /** + * Remove entry from context + * @param key key of the context to be removed. + */ fun removeContext(key: String) } \ No newline at end of file diff --git a/Confidence/src/main/java/com/spotify/confidence/EventSender.kt b/Confidence/src/main/java/com/spotify/confidence/EventSender.kt index ed5b89f5..99414fe5 100644 --- a/Confidence/src/main/java/com/spotify/confidence/EventSender.kt +++ b/Confidence/src/main/java/com/spotify/confidence/EventSender.kt @@ -1,15 +1,30 @@ package com.spotify.confidence interface EventSender : Contextual { + /** + * Store a custom event to be tracked + * @param eventName name of the event. + * @param data any additional data that needs to be tracked. + */ fun track( eventName: String, data: ConfidenceFieldsType = mapOf() ) + /** + * Track Android-specific events like activities. + * @param eventProducer an eventProducer that produces the event, e.g. AndroidLifecycleEventProducer. + */ fun track(eventProducer: EventProducer) + /** + * Safely stop a Confidence instance + */ fun stop() + /** + * Manually flush events from storage. + */ fun flush() override fun withContext(context: Map): EventSender