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
AuthError
ChangeEvent
Credentials
IncompatibleSyncedRealmError
Session
Subscription
User
Realm.Sync.addListener(serverUrl, adminUser, filterRegex, name, changeCallback)
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.

  • 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.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.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.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, 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.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.setLogLevel(log_level)
static

Set the sync log level.

Parameters:
  • log_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

LogLevel
Type:
"all" or "trace" or "debug" or "detail" or "info" or "warn" or "error" or "fatal" or "off"
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.