io.realm

Class SyncConfiguration

java.lang.Object

io.realm.RealmConfiguration

io.realm.SyncConfiguration

public class SyncConfiguration
extends RealmConfiguration

A SyncConfiguration is used to setup a Realm that can be synchronized between devices using the Realm Object Server.

A valid SyncUser is required to create a SyncConfiguration. See SyncCredentials and SyncUser.logInAsync(SyncCredentials, String, SyncUser.Callback) for more information on how to get a user object.

A minimal SyncConfiguration can be found below.

 
 SyncUser user = SyncUser.current();
 String url = "realm://myinstance.cloud.realm.io/default";
 SyncConfiguration config = new SyncConfiguration.Builder(user, url).build();
 
 

Synchronized Realms come in two forms:

• Query-based synchronization: This is the default mode. The Realm will only synchronize data you have queried for. This means the Realm on the device is initially empty and will gradually fill up as you start to query for data. This is useful if the server side Realm is too large to fit on the device or contains data from multiple users. Data synchronized this way can also be removed from the device again without being deleted on the server.
• Full synchronization Enable this mode by setting SyncConfiguration.Builder.fullSynchronization(). In this mode the entire Realm is synchronized in the background without having to query for data first. This means that data generally will be available quicker but should only be used if the server side Realm is small and doesn't contain data the device is not allowed to see.

Synchronized Realms only support additive migrations which can be detected and performed automatically, so the following builder options are not accessible compared to a normal Realm:

• deleteRealmIfMigrationNeeded()
• migration(Migration)

Synchronized Realms are created by using Realm.getInstance(RealmConfiguration) and Realm.getDefaultInstance() like ordinary unsynchronized Realms.

See Also:

The docs for more information about the two types of synchronization.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SyncConfiguration.Builder Builder used to construct instances of a SyncConfiguration in a fluent manner.

Field Summary

Fields inherited from class io.realm.RealmConfiguration

DEFAULT_REALM_NAME, KEY_LENGTH

Method Summary

Modifier and Type	Method and Description
static SyncConfiguration	automatic() Deprecated. use SyncUser.getDefaultConfiguration() instead.
static SyncConfiguration	automatic(SyncUser user) Deprecated. use SyncUser.getDefaultConfiguration() instead.
boolean	equals(Object o)
static RealmConfiguration	forRecovery(String canonicalPath) Returns a RealmConfiguration appropriate to open a read-only, non-synced Realm to recover any pending changes.
static RealmConfiguration	forRecovery(String canonicalPath, byte[] encryptionKey, Object... modules) Returns a RealmConfiguration appropriate to open a read-only, non-synced Realm to recover any pending changes.
SyncSession.ErrorHandler	getErrorHandler()
long	getInitialRemoteDataTimeout(TimeUnit unit) Returns the timeout defined when downloading any initial data the first time the Realm is opened.
String	getServerCertificateAssetName() Returns the name of certificate stored under the assets, to be used to validate the TLS connection to the Realm Object Server.
String	getServerCertificateFilePath() Returns the name of the certificate copied from assets into internal storage, so it can be used to validate the TLS connection to the Realm Object Server.
URI	getServerUrl() Returns the fully disambiguated URI for the remote Realm i.e., the /~/ placeholder has been replaced by the proper user ID.
OsRealmConfig.SyncSessionStopPolicy	getSessionStopPolicy() NOTE: Only for internal usage.
String	getUrlPrefix() Returns the url prefix used when establishing a sync connection to the Realm Object Server.
SyncUser	getUser() Returns the user.
int	hashCode()
boolean	isFullySynchronizedRealm() Returns whether this configuration is for a fully synchronized Realm or not.
boolean	isPartialRealm() Deprecated. use isFullySynchronizedRealm() instead.
boolean	shouldDeleteRealmOnLogout() Returns true if the Realm file must be deleted once the SyncUser owning it logs out.
boolean	shouldWaitForInitialRemoteData() Returns true if the Realm will download all known changes from the remote server before being opened the first time.
boolean	syncClientValidateSsl() Whether the Realm Object Server certificate should be validated in order to establish a valid TLS connection.
String	toString()

Methods inherited from class io.realm.RealmConfiguration

getCompactOnLaunchCallback, getDurability, getEncryptionKey, getMigration, getPath, getRealmDirectory, getRealmFileName, getRealmObjectClasses, getRxFactory, getSchemaVersion, isReadOnly, isRecoveryConfiguration, shouldDeleteRealmIfMigrationNeeded

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Method Detail

forRecovery

public static RealmConfiguration forRecovery(String canonicalPath,
                                             byte[] encryptionKey,
                                             Object... modules)

Returns a RealmConfiguration appropriate to open a read-only, non-synced Realm to recover any pending changes. This is useful when trying to open a backup/recovery Realm (after a client reset).

Parameters:

canonicalPath - the absolute path to the Realm file defined by this configuration.

encryptionKey - the key used to encrypt/decrypt the Realm file.

modules - if specified it will restricts Realm schema to the provided module.

Returns:

RealmConfiguration that can be used offline

forRecovery

public static RealmConfiguration forRecovery(String canonicalPath)

Returns a RealmConfiguration appropriate to open a read-only, non-synced Realm to recover any pending changes. This is useful when trying to open a backup/recovery Realm (after a client reset). Note: This will use the default Realm module (composed of all RealmModel), and assume no encryption should be used as well.

Parameters:

canonicalPath - the absolute path to the Realm file defined by this configuration.

Returns:

RealmConfiguration that can be used offline

automatic

@Deprecated
public static SyncConfiguration automatic()

Deprecated. use SyncUser.getDefaultConfiguration() instead.

Creates an automatic default configuration based on the the currently logged in user.

This configuration will point to the default Realm on the server where the user was authenticated.

Returns:

The constructed SyncConfiguration.

Throws:

IllegalStateException - if no user are logged in, or multiple users have. Only one should be logged in when calling this method.

automatic

@Deprecated
public static SyncConfiguration automatic(SyncUser user)

Deprecated. use SyncUser.getDefaultConfiguration() instead.

Creates an automatic default configuration for the provided user.

This configuration will point to the default Realm on the server where the user was authenticated.

Returns:

The constructed SyncConfiguration.

Throws:

IllegalArgumentException - if no user was provided or the user isn't valid.

equals

public boolean equals(Object o)

Overrides:

equals in class RealmConfiguration

hashCode

public int hashCode()

Overrides:

hashCode in class RealmConfiguration

toString

public String toString()

Overrides:

toString in class RealmConfiguration

getUser

public SyncUser getUser()

Returns the user.

Returns:

the user.

getServerUrl

public URI getServerUrl()

Returns the fully disambiguated URI for the remote Realm i.e., the /~/ placeholder has been replaced by the proper user ID.

Returns:

URI identifying the remote Realm this local Realm is synchronized with.

getErrorHandler

public SyncSession.ErrorHandler getErrorHandler()

shouldDeleteRealmOnLogout

public boolean shouldDeleteRealmOnLogout()

Returns true if the Realm file must be deleted once the SyncUser owning it logs out.

Returns:

true if the Realm file must be deleted if the SyncUser logs out. false if the file is allowed to remain behind.

getServerCertificateAssetName

public String getServerCertificateAssetName()

Returns the name of certificate stored under the assets, to be used to validate the TLS connection to the Realm Object Server.

Returns:

name of the certificate to be copied from the assets.

See Also:

getServerCertificateFilePath()

getServerCertificateFilePath

public String getServerCertificateFilePath()

Returns the name of the certificate copied from assets into internal storage, so it can be used to validate the TLS connection to the Realm Object Server.

Returns:

absolute path to the certificate.

See Also:

getServerCertificateAssetName()

syncClientValidateSsl

public boolean syncClientValidateSsl()

Whether the Realm Object Server certificate should be validated in order to establish a valid TLS connection.

Returns:

true to validate the remote certificate, or false to bypass certificate validation.

shouldWaitForInitialRemoteData

public boolean shouldWaitForInitialRemoteData()

Returns true if the Realm will download all known changes from the remote server before being opened the first time.

Returns:

true if all remote changes will be downloaded before the Realm can be opened. false if the Realm can be opened immediately.

getInitialRemoteDataTimeout

public long getInitialRemoteDataTimeout(TimeUnit unit)

Returns the timeout defined when downloading any initial data the first time the Realm is opened.

This value is only applicable if shouldWaitForInitialRemoteData() returns true.

Returns:

the time Realm will wait for all changes to be downloaded before it is aborted and an exception is thrown.

See Also:

SyncConfiguration.Builder.waitForInitialRemoteData(long, TimeUnit)

getSessionStopPolicy

public OsRealmConfig.SyncSessionStopPolicy getSessionStopPolicy()

NOTE: Only for internal usage. May change without warning. Returns the stop policy for the session for this Realm once the Realm has been closed.

Returns:

the stop policy used by the session once the Realm is closed.

isPartialRealm

@Deprecated
public boolean isPartialRealm()

Deprecated. use isFullySynchronizedRealm() instead.

Whether this configuration is for a query-based Realm.

Query-based synchronization allows a synchronized Realm to be opened in such a way that only objects queried by the user are synchronized to the device.

Returns:

true to open a query-based Realm false otherwise.

isFullySynchronizedRealm

public boolean isFullySynchronizedRealm()

Returns whether this configuration is for a fully synchronized Realm or not.

See Also:

for more details.

getUrlPrefix

public String getUrlPrefix()

Returns the url prefix used when establishing a sync connection to the Realm Object Server.