yorkie/dev.yorkie.core/Client

Client

class Client(host: String, options: Client.Options, unaryClient: OkHttpClient = OkHttpClient.Builder() .build(), streamClient: OkHttpClient = OkHttpClient.Builder() .connectTimeout(5, TimeUnit.MINUTES) .readTimeout(0, TimeUnit.MILLISECONDS) .writeTimeout(0, TimeUnit.MILLISECONDS) .callTimeout(0, TimeUnit.MILLISECONDS) .build()) : Closeable

Client that can communicate with the server. It has Documents and sends changes of the documents in local to the server to synchronize with other replicas in remote.

A single-threaded, Closeable is used as default. Therefore you need to close the client, when the client is no longer needed. If you provide your own dispatcher, it is up to you to decide close is needed or not.

Constructors

Client

constructor(host: String, options: Client.Options, unaryClient: OkHttpClient = OkHttpClient.Builder() .build(), streamClient: OkHttpClient = OkHttpClient.Builder() .connectTimeout(5, TimeUnit.MINUTES) .readTimeout(0, TimeUnit.MILLISECONDS) .writeTimeout(0, TimeUnit.MILLISECONDS) .callTimeout(0, TimeUnit.MILLISECONDS) .build())

Types

ClientCondition

enum ClientCondition : Enum<Client.ClientCondition>

ClientCondition represents the condition of the client.

Companion

object Companion

DeactivateOptions

data class DeactivateOptions(val keepalive: Boolean? = null, val synchronous: Boolean? = null)

DeactivateOptions are user-settable options used when deactivating clients.

Options

data class Options(val key: String = UUID.randomUUID().toString(), val apiKey: String? = null, val metadata: Map<String, String> = emptyMap(), val fetchAuthToken: suspend (shouldRefresh: Boolean) -> String? = null, val syncLoopDuration: Duration = 50.milliseconds, val reconnectStreamDelay: Duration = 1_000.milliseconds, val channelHeartbeatInterval: Duration = 5_000.milliseconds, val documentPollInterval: Duration = 3_000.milliseconds, val watchFallbackDelay: Duration = 10_000.milliseconds)

User-settable options used when defining Client.

Status

sealed interface Status

Represents the status of the client.

SyncMode

enum SyncMode : Enum<Client.SyncMode>

SyncMode defines synchronization modes for the PushPullChanges API.

Properties

isActive

val isActive: Boolean

service

@VisibleForTesting

var service: <Error class: unknown class>

shouldRefreshToken

var shouldRefreshToken: Boolean

status

val status: StateFlow<Client.Status>

Functions

activateAsync

fun activateAsync(): Deferred<OperationResult>

Activates this Client. That is, it registers itself to the server and receives a unique ID from the server. The given ID is used to distinguish different clients.

attachChannel

fun attachChannel(channel: Channel, isRealtime: Boolean? = null): Deferred<OperationResult>

attachChannel attaches the given channel counter to this client. It registers the channel locally; the server is notified by the first RefreshChannel heartbeat, which creates the session and — for a client that never called activateAsync — activates the client lazily.

attachDocument

fun attachDocument(document: Document, initialPresence: P = emptyMap(), syncMode: Client.SyncMode = SyncMode.Realtime, schema: String? = null, disableGC: Boolean = false, disablePresence: Boolean = false): Deferred<OperationResult>

Attaches the given Document to this Client. It tells the server that this Client will synchronize the given document.

attachPresence

fun ~~attachPresence~~(presence: Presence, isRealtime: Boolean? = null): Deferred<OperationResult>

authToken

@VisibleForTesting

suspend fun authToken(shouldRefresh: Boolean): String?

broadcast

fun broadcast(key: String, topic: String, payload: String, options: Document.BroadcastOptions = Document.BroadcastOptions()): Deferred<OperationResult>

changeSyncMode

fun changeSyncMode(document: Document, syncMode: Client.SyncMode)

Changes the sync mode of the document.

open override fun close()

createRevision

fun createRevision(document: Document, label: String, description: String = ""): Deferred<RevisionSummary>

Creates a revision snapshot for the given document with the given label and optional description. The document must be attached to this client.

deactivateAsync

fun deactivateAsync(deactivateOptions: Client.DeactivateOptions = DeactivateOptions()): Deferred<OperationResult>

Deactivates this Client.

detachChannel

fun detachChannel(channel: Channel): Deferred<OperationResult>

detachChannel detaches the given channel counter from this client. Cleanup is local-only: heartbeats stop and the server reclaims the session via TTL. No RPC is sent.

detachDocument

fun detachDocument(document: Document, keepalive: Boolean = false): Deferred<OperationResult>

Detaches the given document from this Client. It tells the server that this client will no longer synchronize the given Document.

detachPresence

fun ~~detachPresence~~(presence: Presence): Deferred<OperationResult>

getRevision

fun getRevision(document: Document, revisionId: String): Deferred<RevisionSummary>

Retrieves the revision identified by revisionId for the given document, including its full snapshot. The document must be attached to this client.

has

fun has(key: String): Boolean

has checks if the given resource is attached to this client.

listRevisions

fun listRevisions(document: Document, pageSize: Int = 10, offset: Int = 0, isForward: Boolean = false): Deferred<List<RevisionSummary>>

Lists revisions for the given document. The document must be attached.

peekChannel

fun peekChannel(channelKey: String): Deferred<Result<Long>>

peekChannel reads the current session count of a channel without creating a session on the server. Use this when the caller only needs to display the count (e.g. "N people writing") without contributing to it and without receiving broadcasts.

removeDocument

fun removeDocument(document: Document): Deferred<OperationResult>

Removes the given document.

requireClientId

fun requireClientId(): String

restoreRevision

fun restoreRevision(document: Document, revisionId: String): Deferred<OperationResult>

Restores the given document to the state captured by the revision with revisionId. The document must be attached to this client.

syncAsync

fun syncAsync(resource: Attachable? = null): Deferred<OperationResult>

Pushes local changes of the attached documents to the server and receives changes of the remote replica from the server then apply them to local documents.