replica-core/me.aartikov.replica.single/PhysicalReplica

PhysicalReplica

interface PhysicalReplica<T : Any> : Replica<T>

Replica is a primitive for data replication. The replica's task is to represent some chunk of data from a server on a client side. Replica is configured by Fetcher and ReplicaSettings. Replica loads missing data when an active observer connects (see: Replica.observe). Replica keeps track of data staleness. Replica refreshes stale data when an active observer is connected. Replica deduplicates network requests (it doesn't coll a new request if another one is in progress). Replica cancels network request when a last observer is disconnected. Replica clears data when it has no observers for a long time.

The difference between Replica and PhysicalReplica is that the latter has a richer API. Replica has minimalistic read-only API, whereas PhysicalReplica allows to cancel requests, modify data, execute optimistic updates. PhysicalReplica extends Replica, but not all replicas are physical replicas. There are lightweight virtual replicas created by combining other replicas (see: replica-algebra module for more details).

Functions

beginOptimisticUpdate

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

Begins optimistic update. Observed data will be transformed by update function immediately.

abstract fun cancel()

Cancels current request if it is in progress.

abstract suspend fun clear(removeFromStorage: Boolean = true)

Cancels current request and clears data.

abstract suspend fun clearError()

Clears error stored in ReplicaState.

commitOptimisticUpdate

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

Commits optimistic update. Replica forgets previous data.

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

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

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

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

abstract suspend fun makeFresh()

Makes data fresh if it is exists.

abstract suspend fun mutateData(transform: (T) -> T)

Modifies current data with transform function if it is exists.

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

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

abstract fun refresh()

Loads fresh data from a network.

abstract fun revalidate()

Loads fresh data from a network if it is stale.

rollbackOptimisticUpdate

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

Rollbacks optimistic update. Observed data will be replaced to the previous one.

abstract suspend fun setData(data: T)

Replace current data with new data.

Properties

abstract val coroutineScope: CoroutineScope

A coroutine scope that represents life time of a replica.

abstract val eventFlow: Flow<ReplicaEvent<T>>

Notifies that some ReplicaEvent has occurred.

abstract val id: ReplicaId

Unique identifier

abstract val name: String

Human readable name, used for debugging

abstract val settings: ReplicaSettings

Settings, see: ReplicaSettings

abstract val stateFlow: StateFlow<ReplicaState<T>>

Provides ReplicaState as an observable value.

abstract val tags: Set<ReplicaTag>

Tags that can be used for bulk operations

Extensions

val <T : Any> PhysicalReplica<T>.currentState: ReplicaState<T>

Returns current ReplicaState.