Realm JavaScript

Realm~App.Sync.Session

An object encapsulating an Atlas Device Sync session. Sessions represent the communication between the client (and a local Realm file on disk), and the server. Sessions are always created by the SDK and vended out through various APIs. The lifespans of sessions associated with Realms are managed automatically.

Members

config

Gets the Sync-part of the configuration that the corresponding Realm was constructed with.

Type:
object
state

Gets the current state of the session. Can be either:

  • "active": The sync session is actively communicating or attempting to communicate with Atlas App Services. A session may be considered active even if it is not currently connected. To find out if a session is online, check its connection state.
  • "inactive": The sync session is not attempting to communicate with Atlas App Services due to the user logging out or synchronization being paused.
  • "invalid": The sync session encountered a non-recoverable error and is permanently invalid. Create a new Session to continue syncing.
Type:
string
url

Gets the URL of the Realm Object Server that this session is connected to.

Type:
string
user

Gets the User that this session was created with.

Type:
User

Methods

addConnectionNotification(callback)

Registers a connection notification on the session object. This will be notified about changes to the underlying connection to the Realm Object Server.

Parameters:
  • callback
    • Type: callback(newState, oldState)

    • called with the following arguments:

      • newState - the new state of the connection
      • oldState - the state the connection transitioned from.
addProgressNotification(direction, mode, callback)

Register a progress notification callback on a session object

Parameters:
  • direction
    • Type: string

    • The progress direction to register for. Can be either:

      • download - report download progress
      • upload - report upload progress
  • mode
    • Type: string

    • The progress notification mode to use for the registration. Can be either:

      • reportIndefinitely - the registration will stay active until the callback is unregistered
      • forCurrentlyOutstandingWork - the registration will be active until only the currently transferable bytes are synced
  • callback
    • Type: callback(transferred, transferable)

    • called with the following arguments:

      • transferred - the current number of bytes already transferred
      • transferable - the total number of transferable bytes (the number of bytes already transferred plus the number of bytes pending transfer)
connectionState()

Gets the current state of the connection to the server. Multiple sessions might share the same underlying connection. In that case, any connection change is sent to all sessions.

Can be either:

  • Realm.App.Sync.ConnectionState.Disconnected: No connection to the server is available.
  • Realm.App.Sync.ConnectionState.Connecting: An attempt to connect to the server is in progress.
  • Realm.App.Sync.ConnectionState.Connected: The connection to the server is active and data can be synchronized.

Data will only be synchronized with the Realm ObjectServer if this method returns Connected and state() returns Active or Dying.

downloadAllServerChanges(timeout)

This method returns a promise that does not resolve successfully until all known remote changes have been downloaded and applied to the Realm or the specified timeout is hit in which case it will be rejected. If the method times out, the download will still continue in the background.

This method cannot be called before the Realm has been opened.

Parameters:
  • timeout

    • maximum amount of time to wait in milliseconds before the promise will be rejected. If no timeout is specified the method will wait forever.

isConnected()

Returns true if the session is currently active and connected to the server, false if not.

pause()

Pause a sync session.

This method is asynchronous so in order to know when the session has started you will need to add a connection notification with addConnectionNotification.

This method is idempotent so it will be a no-op if the session is already paused.

removeConnectionNotification(callback)

Unregister a state notification callback that was previously registered with addStateNotification. Calling the function multiple times with the same callback is ignored.

Parameters:
  • callback
    • Type: callback(oldState, newState)

    • a previously registered state callback.

removeProgressNotification(callback)

Unregister a progress notification callback that was previously registered with addProgressNotification. Calling the function multiple times with the same callback is ignored.

Parameters:
  • callback
    • Type: callback(transferred, transferable)

    • a previously registered progress callback

resume()

Resumes a sync session that has been paused.

This method is asynchronous so in order to know when the session has started you will need to add a connection notification with addConnectionNotification.

This method is idempotent so it will be a no-op if the session is already started.

uploadAllLocalChanges(timeout)

This method returns a promise that does not resolve successfully until all known local changes have been uploaded to the server or the specified timeout is hit in which case it will be rejected. If the method times out, the upload will still continue in the background.

This method cannot be called before the Realm has been opened.

Parameters:
  • timeout

    • maximum amount of time to wait in milliseconds before the promise is rejected. If no timeout is specified the method will wait forever.