replica-core/me.aartikov.replica.keyed/KeyedPhysicalReplica

KeyedPhysicalReplica

interface KeyedPhysicalReplica<K : Any, T : Any> : KeyedReplica<K, T>

Keyed replica replicates multiple chunks of data - different chunks for different keys. Internally it uses PhysicalReplica for individual data chunks.

The difference between KeyedReplica and KeyedPhysicalReplica is that the latter has a richer API. KeyedReplica has minimalistic read-only API, whereas KeyedPhysicalReplica allows to cancel requests, modify data, execute optimistic updates.

Functions

beginOptimisticUpdate

abstract suspend fun beginOptimisticUpdate(key: K, update: OptimisticUpdate<T>)

Begins optimistic update for a given key. Observed data will be transformed by update function immediately.

cancel

abstract fun cancel(key: K)

Cancels current request if it is in progress for a given key.

clear

abstract suspend fun clear(key: K, removeFromStorage: Boolean = true)

Cancels current request and clears data for a given key.

clearAll

abstract suspend fun clearAll()

Cancels network requests and clears data in all child replicas.

clearError

abstract suspend fun clearError(key: K)

Clears error stored in ReplicaState for a given key.

commitOptimisticUpdate

abstract suspend fun commitOptimisticUpdate(key: K, update: OptimisticUpdate<T>)

Commits optimistic update for a given key. Child replica forgets previous data.

getCurrentState

abstract fun getCurrentState(key: K): ReplicaState<T>?

Returns current ReplicaState for a given key.

getData

abstract suspend fun getData(key: K, forceRefresh: Boolean = false): T

Loads and returns data for a given key. Throws an exception on error. It never returns stale data. It makes a network request if data is stale.

invalidate

abstract suspend fun invalidate(key: K, mode: InvalidationMode = InvalidationMode.RefreshIfHasObservers)

Makes data stale if it is exists for a given key. It also could call a refresh depending on InvalidationMode.

makeFresh

abstract suspend fun makeFresh(key: K)

Makes data fresh if it is exists for a given key.

mutateData

abstract suspend fun mutateData(key: K, transform: (T) -> T)

Modifies current data with transform function if it is exists for a given key.

observe

abstract fun observe( observerCoroutineScope: CoroutineScope, observerActive: StateFlow<Boolean>, key: StateFlow<K?>): ReplicaObserver<T>

Starts to observe a keyed replica. Returned ReplicaObserver gives access to replica state and error events.

onEachReplica

abstract suspend fun onEachReplica(action: suspend PhysicalReplica<T>.(K) -> Unit)

Executes an action on each child PhysicalReplica.

onExistingReplica

abstract suspend fun onExistingReplica(key: K, action: suspend PhysicalReplica<T>.() -> Unit)

Executes an action on a PhysicalReplica with a given key. If the replica doesn't exist the action is not executed.

onReplica

abstract suspend fun onReplica(key: K, action: suspend PhysicalReplica<T>.() -> Unit)

Executes an action on a PhysicalReplica with a given key. If the replica doesn't exist it is created.

refresh

abstract fun refresh(key: K)

Loads fresh data from a network for a given key.

revalidate

abstract fun revalidate(key: K)

Loads fresh data from a network for a given key if it is stale.

rollbackOptimisticUpdate

abstract suspend fun rollbackOptimisticUpdate(key: K, update: OptimisticUpdate<T>)

Rollbacks optimistic update for a given key. Observed data will be replaced to the previous one.

setData

abstract suspend fun setData(key: K, data: T)

Replace current data with new data for a given key.

Properties

coroutineScope

abstract val coroutineScope: CoroutineScope

A coroutine scope that represents life time of a keyed replica.

eventFlow

abstract val eventFlow: Flow<KeyedReplicaEvent<K, T>>

Notifies that some KeyedReplicaEvent has occurred.

abstract val id: ReplicaId

Unique identifier

name

abstract val name: String

Human readable name, used for debugging

settings

abstract val settings: KeyedReplicaSettings<K, T>

Settings, see: KeyedReplicaSettings

stateFlow

abstract val stateFlow: StateFlow<KeyedReplicaState>

Provides KeyedReplicaState as an observable value.

Extensions

cancelAll

suspend fun <K : Any, T : Any> KeyedPhysicalReplica<T, K>.cancelAll()

Cancels network requests in all child replicas.

cancelByTags

suspend fun <K : Any, T : Any> KeyedPhysicalReplica<T, K>.cancelByTags(predicate: (Set<ReplicaTag>) -> Boolean)

Cancels network requests in child replicas with the matching tags.

clearByTags

suspend fun <K : Any, T : Any> KeyedPhysicalReplica<T, K>.clearByTags(predicate: (Set<ReplicaTag>) -> Boolean)

Cancels network requests and clears data in child replicas with the matching tags.

currentState

val <K : Any, T : Any> KeyedPhysicalReplica<K, T>.currentState: KeyedReplicaState

Returns current KeyedReplicaState.

invalidateAll

suspend fun <K : Any, T : Any> KeyedPhysicalReplica<T, K>.invalidateAll(mode: InvalidationMode = InvalidationMode.RefreshIfHasObservers)

Makes all child replicas stale.

invalidateByTags

suspend fun <K : Any, T : Any> KeyedPhysicalReplica<T, K>.invalidateByTags(mode: InvalidationMode = InvalidationMode.RefreshIfHasObservers, predicate: (Set<ReplicaTag>) -> Boolean)

Makes child replicas with the matching tags stale.