io.realm

Class SyncConfiguration.Builder

java.lang.Object

io.realm.SyncConfiguration.Builder

Enclosing class:

SyncConfiguration

public static final class SyncConfiguration.Builder
extends Object

Builder used to construct instances of a SyncConfiguration in a fluent manner.

Constructor Summary

Constructors

Constructor and Description
Builder(SyncUser user, String uri) Creates an instance of the Builder for the SyncConfiguration.

Method Summary

Modifier and Type	Method and Description
SyncConfiguration	build() Creates the RealmConfiguration based on the builder parameters.
SyncConfiguration.Builder	directory(File directory) Sets the local root directory where synchronized Realm files can be saved.
SyncConfiguration.Builder	encryptionKey(byte[] key) Sets the 64 bytes key used to encrypt and decrypt the Realm file.
SyncConfiguration.Builder	errorHandler(SyncSession.ErrorHandler errorHandler) Sets the error handler used by this configuration.
SyncConfiguration.Builder	initialData(Realm.Transaction transaction) Sets the initial data in Realm.
SyncConfiguration.Builder	inMemory() Setting this will create an in-memory Realm instead of saving it to disk.
SyncConfiguration.Builder	modules(Object baseModule, Object... additionalModules) Replaces the existing module(s) with one or more RealmModules.
SyncConfiguration.Builder	name(String filename) Sets the local file name for the Realm.
SyncConfiguration.Builder	rxFactory(RxObservableFactory factory) Sets the RxObservableFactory used to create Rx Observables from Realm objects.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Builder

public Builder(SyncUser user,
               String uri)

Creates an instance of the Builder for the SyncConfiguration.

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.

See Also:

SyncUser.isValid()

Method Detail

name

public SyncConfiguration.Builder name(String filename)

Sets the local file name for the Realm. This will override the default name defined by the Realm URL.

Parameters:

filename - name of the local file on disk.

Throws:

IllegalArgumentException - if file name is null or empty.

directory

public SyncConfiguration.Builder directory(File 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.

The default location is context.getFilesDir().

Parameters:

directory - directory on disk where the Realm file can be saved.

Throws:

IllegalArgumentException - if the directory is not valid.

encryptionKey

public SyncConfiguration.Builder encryptionKey(byte[] key)

Sets the 64 bytes key used to encrypt and decrypt the Realm file.

Parameters:

key - the encryption key.

Throws:

IllegalArgumentException - if key is invalid.

modules

public SyncConfiguration.Builder modules(Object baseModule,
                                         Object... additionalModules)

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:

builder.modules(Realm.getDefaultMode(), new MyLibraryModule());

Parameters:

baseModule - the first Realm module (required).

additionalModules - the additional Realm modules

Throws:

IllegalArgumentException - if any of the modules don't have the RealmModule annotation.

See Also:

Realm.getDefaultModule()

rxFactory

public SyncConfiguration.Builder rxFactory(RxObservableFactory factory)

Sets the RxObservableFactory used to create Rx Observables from Realm objects. The default factory is RealmObservableFactory.

Parameters:

factory - factory to use.

initialData

public SyncConfiguration.Builder initialData(Realm.Transaction transaction)

Sets the initial data in Realm. This transaction will be executed only the first time the Realm file is opened (created) or while migrating the data if RealmConfiguration.Builder.deleteRealmIfMigrationNeeded() is set.

Parameters:

transaction - transaction to execute.

inMemory

public SyncConfiguration.Builder 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.

errorHandler

public SyncConfiguration.Builder errorHandler(SyncSession.ErrorHandler errorHandler)

Sets the error handler used by this configuration. This will override any handler set by calling SyncManager.setDefaultSessionErrorHandler(SyncSession.ErrorHandler).

Only errors not handled by the defined SyncPolicy will be reported to this error handler.

Parameters:

errorHandler - error handler used to report back errors when communicating with the Realm Object Server.

Throws:

IllegalArgumentException - if null is given as an error handler.

build

public SyncConfiguration build()

Creates the RealmConfiguration based on the builder parameters.

Returns:

the created SyncConfiguration.

Throws:

IllegalStateException - if the configuration parameters are invalid or inconsistent.