Realm.Sync

When opening a Realm created with Realm Mobile Platform v1.x, it is automatically migrated to the v2.x format. In case this migration is not possible, an exception is thrown. The exception´s message property will be equal to IncompatibleSyncedRealmException. The Realm is backed up, and the property configuration is a {Realm~Configuration} which refers to it. You can open it as a local, read-only Realm, and copy objects to a new synced Realm.

Related Classes

Adapter
AsyncOpenTask
AuthError
ChangeEvent
Credentials
IncompatibleSyncedRealmError
LocalRealm
NamedSubscription
Session
Subscription
User
Realm.Sync._hasExistingSessions()
static

Returns true if Realm still has a reference to any sync sessions regardless of their state. If false is returned it means that no sessions currently exist.

Realm.Sync.addListener(serverUrl, adminUser, filterRegex, worker)
static

Add a sync listener to listen to changes across multiple Realms.

Parameters:
  • serverUrl
    • Type: string
    • The sync server to listen to.

  • adminUser
    • Type: SyncUser
    • an admin user obtained by calling User.login with admin credentials.

  • filterRegex
    • Type: string
    • A regular expression used to determine which changed Realms should trigger events. Use .* to match all Realms.

  • worker
    • Type: Realm.Worker
    • Worker to deliver events to.

      Only available in the Enterprise Edition.

Realm.Sync.addListener(config, eventName, changeCallback)
static

Add a sync listener to listen to changes across multiple Realms.

Parameters:
  • config
    • Type: Realm.Sync.RealmListenerConfiguration
    • The configuration object for Realms being observed.

  • eventName
    • Type: string
    • The name of the event to observe.

  • changeCallback
    • Type: function
    • The callback to invoke with the events.

      Registers the changeCallback to be called each time the given event occurs on the specified server. Only events on Realms with a virtual path that matches the filter regex are emitted.

      Currently supported events:

      • 'available': Emitted whenever there is a new Realm which has a virtual path matching the filter regex, either due to the Realm being newly created or the listener being added. The virtual path (i.e. the portion of the URL after the protocol and hostname) is passed as an argument.
      • 'change': Emitted whenever the data within a Realm matching the filter regex has changed. A ChangeEvent argument is passed containing information about which Realm changed and what objects within the Realm changed.
      • 'delete': Emitted whenever a Realm matching the filter regex has been deleted from the server. The virtual path of the Realm being deleted is passed as an argument.

      Only available in the Enterprise Edition.

Realm.Sync.addListener(serverUrl, adminUser, filterRegex, name, changeCallback)
staticDeprecated: Use `addListener(config, eventName, changeCallback)` instead`.

Add a sync listener to listen to changes across multiple Realms.

Parameters:
  • serverUrl
    • Type: string
    • The sync server to listen to.

  • adminUser
    • Type: SyncUser
    • an admin user obtained by calling User.login with admin credentials.

  • filterRegex
    • Type: string
    • A regular expression used to determine which changed Realms should trigger events. Use .* to match all Realms.

  • name
    • Type: string
    • The name of the event.

  • changeCallback
    • Type: function
    • The callback to invoke with the events.

      Registers the changeCallback to be called each time the given event occurs on the specified server. Only events on Realms with a virtual path that matches the filter regex are emitted.

      Currently supported events:

      • 'available': Emitted whenever there is a new Realm which has a virtual path matching the filter regex, either due to the Realm being newly created or the listener being added. The virtual path (i.e. the portion of the URL after the protocol and hostname) is passed as an argument.
      • 'change': Emitted whenever the data within a Realm matching the filter regex has changed. A ChangeEvent argument is passed containing information about which Realm changed and what objects within the Realm changed.
      • 'delete': Emitted whenever a Realm matching the filter regex has been deleted from the server. The virtual path of the Realm being deleted is passed as an argument.

      Only available in the Enterprise Edition.

Realm.Sync.initiateClientReset(path)
static

Initiate a client reset. The Realm must be closed prior to the reset.

Parameters:
  • path optional
    • Type: string
    • The path to the Realm to reset. Throws error if reset is not possible.

Example:
{
  const config = { sync: { user, url: 'realm://localhost:9080/~/myrealm' } };
  config.sync.error = (sender, error) => {
    if (error.name === 'ClientReset') {
      Realm.Sync.initiateClientReset(original_path);
      // copy required objects from Realm at error.config.path
    }
  }
}
Realm.Sync.localListenerRealms(regex)[LocalRealm, ...]
static

Returns a list of local Realms previously downloaded via the global notifier.

Parameters:
  • regex
    • Type: string
    • The regular expression used to filter the returned Realms by virtual path.

Returns: [LocalRealm, ...] An array of LocalRealm.
Realm.Sync.reconnect()
static

Calling this method will force Realm to attempt to reconnect to the server immediately.

Realm will reconnect automatically, but by using exponential backoff. This means that if the device is offline for a long time, restoring the connection after it comes back online can take longer than expected. In situations where it is possible to detect the network condition (e.g. Airplane mode). Manually calling this method can provide a smoother user experience.

Realm.Sync.removeAllListeners()Promise<void>
static

Remove all previously registered listeners.

Returns: Promise<void> A promise which is resolved when all workers (if any) have finished shutting down.
Realm.Sync.removeListener(filterRegex, name, changeCallback)
static

Remove a previously registered sync listener.

Parameters:
  • filterRegex
    • Type: string
    • The regular expression previously used to register the listener.

  • name
    • Type: string
    • The event name.

  • changeCallback
    • Type: function
    • The previously registered callback to be removed.

Realm.Sync.removeListener(filterRegex, worker)Promise<void>
static

Remove a previously registered sync listener.

Parameters:
  • filterRegex
    • Type: string
    • The regular expression previously used to register the listener.

  • worker
    • Type: string
    • The worker registered as a listener.

Returns: Promise<void> A promise which is resolved when the worker has finished shutting down.
Realm.Sync.setLogger(logger)
static

Capture the sync client's log.

Parameters:
Realm.Sync.setLogLevel(level)
static

Set the sync log level.

Parameters:
  • level
Realm.Sync.setUserAgent(the)
static

Set the application part of the User-Agent string that will be sent to the Realm Object Server when a session is created.

This method can only be called up to the point where the first Realm is opened. After that, the User-Agent can no longer be changed.

Parameters:
  • the
    • Type: string
    • user agent description

ClientResyncMode

This describes the client resync modes.

Type:
"recover" or "discard" or "manual"
Properties:
  • "recover"
    • Realm will compare the local Realm with the Realm on the server and automatically transfer any changes from the local Realm that makes sense to the Realm provided by the server. This is the default mode for fully synchronized Realms. It is not yet supported by query-based Realms.

  • "discard"
    • The local Realm will be discarded and replaced with the server side Realm. All local changes will be lost. This mode is not yet supported by query-based Realms.

Realm.Sync.downloadBeforeOpenBehavior

The default behavior settings if you want to fully synchronize a Realm before it is opened. If this takes more than 30 seconds, an exception will be thrown.

Type:
Object
logCallback(level, message)

A callback passed to Realm.Sync.setLogger when instrumenting the Realm Sync client with a custom logger.

Parameters:
  • level
    • Type: number
    • The level of the log entry between 0 and 8 inclusively. Use this as an index into ['all', 'trace', 'debug', 'detail', 'info', 'warn', 'error', 'fatal', 'off'] to get the name of the level.

  • message
    • Type: string
    • The message of the log entry.

LogLevel
Type:
"all" or "trace" or "debug" or "detail" or "info" or "warn" or "error" or "fatal" or "off"
Realm.Sync.openLocalRealmBehavior

The default behavior settings if you want to open a synchronized Realm immediately and start working on it. If this is the first time you open the Realm, it will be empty while the server data is being downloaded in the background.

Type:
Object
RealmListenerConfiguration

This describes the different options used when adding a Global Notifier listener.

Type:
Object
Properties:
  • serverUrl
    • Type: string
    • The sync server to listen to.

  • adminUser
    • Type: SyncUser
    • an admin user obtained by calling User.login with admin credentials.

  • filterRegex
    • Type: string
    • A regular expression used to determine which changed Realms should trigger events. Use .* to match all Realms.

  • sslConfiguration
    • Type: Realm.Sync.SSLConfiguration
    • SSL configuration used by the Realms being observed.

SSLCertificateValidationInfo
Type:
Object
Properties:
  • serverAddress
    • Type: string
  • serverPort
    • Type: number
  • pemCertificate
    • Type: string
  • acceptedByOpenSSL
    • Type: boolean
    • true if OpenSSL has accepted the certificate, and false if OpenSSL has rejected it. It is generally safe to return true when acceptedByOpenSSL is true. If acceptedByOpenSSL is false, an independent verification should be made.

  • depth
    • Type: number
    • Specifies the position of the certificate in the chain. depth = 0 represents the actual server certificate. The root certificate has the highest depth. The certificate of highest depth will be presented first.

SSLConfiguration

This describes the different options used to create a Realm instance with Realm Platform synchronization.

Type:
Object
Properties:
  • validate
    • Type: boolean
    • Indicating if SSL certificates must be validated. Default is true.

  • certificatePath
    • Type: string
    • A path where to find trusted SSL certificates.

  • validateCallback
    • Type: sslValidateCallback
    • A callback function used to accept or reject the server's SSL certificate.

sslValidateCallback(validationInfo)boolean

When the sync client has received the server's certificate chain, it presents every certificate in the chain to the Realm.Sync~sslValidateCallback callback.

The return value of the callback decides whether the certificate is accepted (true) or rejected (false). Realm.Sync~sslValidateCallback is only respected on platforms where OpenSSL is used for the sync client, e.g. Linux. The callback is not allowed to throw exceptions. If the operations needed to verify the certificate lead to an exception, the exception must be caught explicitly before returning. The return value would typically be false in case of an exception.

Parameters:
Returns: boolean
SyncConfiguration

This describes the different options used to create a Realm instance with Realm Platform synchronization.

Type:
Object
Properties:
  • url
    • Type: string
    • A string which contains a valid Realm Sync url.

  • error optional
    • Type: function
    • A callback function which is called in error situations. The error callback can take up to five optional arguments: name, message, isFatal, category, and code.

  • validate_ssl optional
    • Type: boolean
    • Indicating if SSL certificates must be validated.

  • ssl_trust_certificate_path optional
    • Type: string
    • A path where to find trusted SSL certificates.

  • open_ssl_verify_callback optional
    • Type: sslValidateCallback
    • A callback function used to accept or reject the server's SSL certificate.

  • partial optional
    • Type: boolean
    • Whether this Realm should be opened in 'query-based synchronization' mode. Query-based synchronisation only synchronizes those objects that match the query specified in contrast to the normal mode of operation that synchronises all objects in a remote Realm.

  • fullSynchronization optional
    • Type: boolean
    • Whether this Realm should be opened in query-based or full synchronization mode. The default is query-based mode which only synchronizes objects that have been subscribed to. A fully synchronized Realm will synchronize the entire Realm in the background, irrespectively of the data being used or not.

  • custom_http_headers optional
    • Type: Object
    • A map (string, string) of custom HTTP headers.

  • customQueryBasedSyncIdentifier optional
    • Type: string
    • A custom identifier to append to the Realm url rather than the default identifier which is comprised of the user id and a random string. It allows you to reuse query based Realms across different devices.

  • clientResyncMode optional
    • Type: string
    • A Client Resync is triggered if the device and server cannot agree on a common shared history for the Realm file, thus making it impossible for the device to upload or receive any changes. This can happen if the server is rolled back or restored from backup. Just having the device offline will not trigger a Client Resync. The three different modes are 'recover', 'discard', and 'manual' with 'manual' as the default value for query-based sync and 'recover' for full sync. Query-based synced Realm only support 'manual'.

  • newRealmFileBehavior optional
    • Type: Object
    • Whether to create a new file and sync in background or wait for the file to be synced.

  • existingRealmFileBehavior optional
    • Type: Object
    • Whether to open existing file and sync in background or wait for the sync of the file to complete and then open.