Constructor Detail

Builder

Creates an instance of the Builder for the SyncConfiguration. This SyncConfiguration
will be for a fully synchronized Realm.

Opening a synchronized Realm requires a valid user and an unique URI that identifies that Realm. In URIs,
/~/ can be used as a placeholder for a user ID in case the Realm should only be available to one
user e.g., "realm://objectserver.realm.io/~/default".

The URL cannot end with .realm, .realm.lock or .realm.management.

The /~/ will automatically be replaced with the user ID when creating the SyncConfiguration.

Moreover, the URI defines the local location on disk. The default location of a synchronized Realm file is
/data/data/<packageName>/files/realm-object-server/<user-id>/<last-path-segment>, but this behavior
can be overwritten using name(String) and directory(File).

Many Android devices are using FAT32 file systems. FAT32 file systems have a limitation that
file names cannot be longer than 255 characters. Moreover, the entire URI should not exceed 256 characters.
If file name and underlying path are too long to handle for FAT32, a shorter unique name will be generated.
See also @{link https://msdn.microsoft.com/en-us/library/aa365247(VS.85).aspx}.

Parameters:

user - the user for this Realm. An authenticated SyncUser is required to open any Realm managed
by a Realm Object Server.

uri - URI identifying the Realm. If only a path like /~/default is given, the configuration will
assume the file is located on the same server returned by SyncUser.getAuthenticationUrl().

directory

Sets the local root directory where synchronized Realm files can be saved.

Synchronized Realms will not be saved directly in the provided directory, but instead in a
subfolder that matches the path defined by Realm URI. As Realm server URIs are unique
this means that multiple users can save their Realms on disk without the risk of them overwriting
each other files.

schemaVersion

Synced Realms only support additive schema changes which can be applied without requiring a manual
migration. The schema version will only be used as an indication to the underlying storage layer to remove
or add indexes. These will be recalculated if the provided schema version differ from the version in the
Realm file.
WARNING: There is no guarantee that the value inserted here is the same returned by BaseRealm.getVersion().
Due to the nature of synced Realms, the value can both be higher and lower.

It will be lower if another client with a lesser schemaVersion connected to the server for
the first time after this schemaVersion was used.

It will be higher if another client with a higher schemaVersion connected to the server after
this Realm was created.

modules

Replaces the existing module(s) with one or more RealmModules. Using this method will replace the
current schema for this Realm with the schema defined by the provided modules.

A reference to the default Realm module containing all Realm classes in the project (but not dependencies),
can be found using Realm.getDefaultModule(). Combining the schema from the app project and a library
dependency is thus done using the following code:

modules

Replaces the existing module(s) with one or more RealmModules. Using this method will replace the
current schema for this Realm with the schema defined by the provided modules.

A reference to the default Realm module containing all Realm classes in the project (but not dependencies),
can be found using Realm.getDefaultModule(). Combining the schema from the app project and a library
dependency is thus done using the following code:

inMemory

Setting this will create an in-memory Realm instead of saving it to disk. In-memory Realms might still use
disk space if memory is running low, but all files created by an in-memory Realm will be deleted when the
Realm is closed.

Note that because in-memory Realms are not persisted, you must be sure to hold on to at least one non-closed
reference to the in-memory Realm object with the specific name as long as you want the data to last.

trustedRootCA

Provides the trusted root certificate(s) authority (CA) in PEM format, that should be used to
validate the TLS connections to the Realm Object Server.

The file should be stored under assets, it will be copied at runtime into the internal storage.

Note: This is similar to passing the parameter CAfile to SSL_CTX_load_verify_locations,
Therefore it is recommended to include only the root CA you trust, and not the entire list of root CA
as this file will be loaded at runtime.
It is your responsibility to download and verify the correct PEM for the root CA you trust.
An existing list by Mozilla exist that could be used https://mozillacaprogram.secure.force.com/CA/IncludedCACertificateReportPEMCSV

fullSynchronization

Full synchronization, unlike the default query-based synchronization, will transparently
synchronize the entire Realm without needing to query for the data. This option is
useful if the serverside Realm is small and all the data in the Realm should be
available to the user.

compactOnLaunch

Sets this to determine if the Realm file should be compacted before returned to the user. It is passed the
total file size (data + free space) and the bytes used by data in the file.

Parameters:

compactOnLaunch - a callback called when opening a Realm for the first time during the life of a process
to determine if it should be compacted before being returned to the user. It is passed
the total file size (data + free space) and the bytes used by data in the file.