Docs Menu

Docs Home → Develop Applications → Atlas Device SDKs

Class SyncConfiguration.Builder

On this page

  • io.realm.mongodb.sync
  • Constructors
  • Method Summary
  • Inherited Methods
  • Constructor Detail
  • Method Detail
  • addModule
  • allowQueriesOnUiThread
  • allowWritesOnUiThread
  • assetFile
  • build
  • clientResetHandler
  • compactOnLaunch
  • encryptionKey
  • errorHandler
  • flowFactory
  • inMemory
  • initialData
  • initialSubscriptions
  • maxNumberOfActiveVersions
  • modules
  • name
  • readOnly
  • rxFactory
  • schemaVersion
  • syncClientResetStrategy
  • urlPrefix
  • waitForInitialRemoteData

io.realm.mongodb.sync

java.lang.Object
io.realm.mongodb.sync.SyncConfiguration.Builder

Enclosing class:

SyncConfiguration

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

Constructors

Constructor and Description
Builder (
User user
)

Creates an instance of the builder for a Flexible Sync SyncConfiguration with the given user.

Builder (
User user,
String partitionValue
)

Creates an instance of the builder for a Partition-based Sync SyncConfiguration with the given user and partition value.

Builder (
User user,
ObjectId partitionValue
)

Creates an instance of the builder for a Partition-based Sync SyncConfiguration with the given user and partition value.

Method Summary

Modifier and Type
Method and Description
public SyncConfiguration.Builder
addModule (
Object module
)

Adds a module to the already defined modules.

public SyncConfiguration.Builder
allowQueriesOnUiThread (
boolean allowQueriesOnUiThread
)

Sets whether or not RealmQueries are allowed from the UI thread.

public SyncConfiguration.Builder
allowWritesOnUiThread (
boolean allowWritesOnUiThread
)

Sets whether or not calls to Realm.executeTransaction are allowed from the UI thread.

public SyncConfiguration.Builder
assetFile (
String assetFile
)

When opening the Realm for the first time, instead of creating an empty file, the Realm file will be copied from the provided asset file and used instead.

public SyncConfiguration
build ()

Creates the RealmConfiguration based on the builder parameters.

public SyncConfiguration.Builder
clientResetHandler (
SyncSession.ClientResetHandler handler
)

Sets the handler for when a Client Reset occurs.

public SyncConfiguration.Builder
compactOnLaunch (
CompactOnLaunchCallback compactOnLaunch
)

Sets this to determine if the Realm file should be compacted before returned to the user.

public SyncConfiguration.Builder
compactOnLaunch ()

Setting this will cause Realm to compact the Realm file if the Realm file has grown too large and a significant amount of space can be recovered.

public SyncConfiguration.Builder
encryptionKey (
byte[] key
)

Sets the io.realm.Realm#ENCRYPTION_KEY_LENGTH bytes key used to encrypt and decrypt the Realm file.

public SyncConfiguration.Builder
errorHandler (
SyncSession.ErrorHandler errorHandler
)

Sets the error handler used by this configuration.

public SyncConfiguration.Builder
flowFactory (
FlowFactory factory
)

Sets the FlowFactory used to create coroutines Flows from Realm objects.

public SyncConfiguration.Builder
inMemory ()

Setting this will create an in-memory Realm instead of saving it to disk.

public SyncConfiguration.Builder
initialData (
Realm.Transaction transaction
)

Sets the initial data in io.realm.Realm .

public SyncConfiguration.Builder
initialSubscriptions (
SyncConfiguration.InitialFlexibleSyncSubscriptions action
)

Sets the initial Subscription s for the io.realm.Realm .

public SyncConfiguration.Builder
maxNumberOfActiveVersions (
long number
)

Sets the maximum number of live versions in the Realm file before an IllegalStateException is thrown when attempting to write more data.

public SyncConfiguration.Builder
modules (
java.lang.Iterable<java.lang.Object> modules
)

Replaces the existing module(s) with one or more RealmModule s.

public SyncConfiguration.Builder
modules (
Object baseModule,
java.lang.Object[] additionalModules
)

Replaces the existing module(s) with one or more RealmModule s.

public SyncConfiguration.Builder
name (
String filename
)

Sets the filename for the Realm file on this device.

public SyncConfiguration.Builder
readOnly ()

Setting this will cause the Realm to become read only and all write transactions made against this Realm will fail with an IllegalStateException .

public SyncConfiguration.Builder
rxFactory (
RxObservableFactory factory
)

Sets the RxObservableFactory used to create Rx Observables from Realm objects.

public SyncConfiguration.Builder
schemaVersion (
long schemaVersion
)

Sets the schema version of the Realm.

public SyncConfiguration.Builder
syncClientResetStrategy (
DiscardUnsyncedChangesStrategy handler
)

Sets the handler for when a Client Reset occurs.

public SyncConfiguration.Builder
syncClientResetStrategy (
ManuallyRecoverUnsyncedChangesStrategy handler
)

Sets the handler for when a Client Reset occurs.

public SyncConfiguration.Builder
urlPrefix (
String urlPrefix
)

The prefix that is prepended to the path in the WebSocket request that initiates a sync connection to MongoDB Realm.

public SyncConfiguration.Builder
waitForInitialRemoteData (
long timeout,
TimeUnit unit
)

Setting this will cause the Realm to download all known changes from the server the first time a Realm is opened.

public SyncConfiguration.Builder
waitForInitialRemoteData ()

Setting this will cause the Realm to download all known changes from the server the first time a Realm is opened.

Inherited Methods

  • Methods inherited from class java.lang.Object : getClass , hashCode , equals , clone , toString , notify , notifyAll , wait , wait , wait , finalize

Constructor Detail

public Builder (
User user
)

Creates an instance of the builder for a Flexible Sync SyncConfiguration with the given user.

Parameters

  • user - The user that will be used for accessing the Realm App.

Tip

See also:

  • {@link SubscriptionSet} for more information about Flexible Sync.

public Builder (
User user,
String partitionValue
)

Creates an instance of the builder for a Partition-based Sync SyncConfiguration with the given user and partition value.

Parameters

  • user - The user that will be used for accessing the Realm App.

  • partitionValue - The partition value identifying the remote Realm that will be synchronized.

public Builder (
User user,
ObjectId partitionValue
)

Creates an instance of the builder for a Partition-based Sync SyncConfiguration with the given user and partition value.

Parameters

  • user - The user that will be used for accessing the Realm App.

  • partitionValue - The partition value identifying the remote Realm that will be synchronized.

Method Detail

addModule

public SyncConfiguration.Builder addModule (
Object module
)
Adds a module to the already defined modules.

allowQueriesOnUiThread

public SyncConfiguration.Builder allowQueriesOnUiThread (
boolean allowQueriesOnUiThread
)

Sets whether or not RealmQueries are allowed from the UI thread.

By default Realm allows queries on the main thread. However, by doing so your application may experience a drop of frames or even ANRs. We recommend diverting queries to non-UI threads or, alternatively, using RealmQuery.findAllAsync() or RealmQuery.findFirstAsync() .

allowWritesOnUiThread

public SyncConfiguration.Builder allowWritesOnUiThread (
boolean allowWritesOnUiThread
)

Sets whether or not calls to Realm.executeTransaction are allowed from the UI thread.

WARNING: Realm does not allow synchronous transactions to be run on the main thread unless users explicitly opt in with this method. We recommend diverting calls to executeTransaction to non-UI threads or, alternatively, using Realm.executeTransactionAsync .

assetFile

public SyncConfiguration.Builder assetFile (
String assetFile
)

When opening the Realm for the first time, instead of creating an empty file, the Realm file will be copied from the provided asset file and used instead.This can be used to pre-populate the Realm with data, so it doesn't have to be downloaded from the server.

The provided Realm file must be a valid synced Realm for the given user, and it must have been created using the Realm.writeCopyTo(File) API.

WARNING: This could potentially be a lengthy operation and should ideally be done on a background thread.

Parameters

  • assetFile - path to the asset database file.

Throws

build

public SyncConfiguration build ()

Creates the RealmConfiguration based on the builder parameters.

Returns

the created SyncConfiguration .

Throws

clientResetHandler

public SyncConfiguration.Builder clientResetHandler (
SyncSession.ClientResetHandler handler
)

Sets the handler for when a Client Reset occurs. If no handler is set, and error is logged when a Client Reset occurs.

Parameters

  • handler - custom handler in case of a Client Reset.

compactOnLaunch

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

public SyncConfiguration.Builder compactOnLaunch ()

Setting this will cause Realm to compact the Realm file if the Realm file has grown too large and a significant amount of space can be recovered. See DefaultCompactOnLaunchCallback for details.

encryptionKey

public SyncConfiguration.Builder encryptionKey (
byte[] key
)

Sets the io.realm.Realm#ENCRYPTION_KEY_LENGTH bytes key used to encrypt and decrypt the Realm file.

Parameters

  • key - the encryption key.

Throws

errorHandler

public SyncConfiguration.Builder errorHandler (
SyncSession.ErrorHandler errorHandler
)

Sets the error handler used by this configuration.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

flowFactory

public SyncConfiguration.Builder flowFactory (
FlowFactory factory
)

Sets the FlowFactory used to create coroutines Flows from Realm objects. The default factory is RealmFlowFactory .

Parameters

  • factory - factory to use.

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.

initialData

public SyncConfiguration.Builder initialData (
Realm.Transaction transaction
)

Sets the initial data in io.realm.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.

initialSubscriptions

public SyncConfiguration.Builder initialSubscriptions (
SyncConfiguration.InitialFlexibleSyncSubscriptions action
)

Sets the initial Subscription s for the io.realm.Realm . This will only be executed the first time the Realm file is opened (and the file created). If waitForInitialRemoteData() is configured as well, the realm file isn't fully opened until all subscription data also has been uploaded.

Parameters

maxNumberOfActiveVersions

public SyncConfiguration.Builder maxNumberOfActiveVersions (
long number
)

Sets the maximum number of live versions in the Realm file before an IllegalStateException is thrown when attempting to write more data.

Realm is capable of concurrently handling many different versions of Realm objects. This can happen if you have a Realm open on many different threads or are freezing objects while data is being written to the file.

Under normal circumstances this is not a problem, but if the number of active versions grow too large, it will have a negative effect on the filesize on disk. Setting this parameters can therefore be used to prevent uses of Realm that can result in very large Realms.

Note, the version number will also increase when changes from other devices are integrated on this device, so the number of active versions will also depend on what other devices writing to the same Realm are doing.

Parameters

  • number - the maximum number of active versions before an exception is thrown.

Tip

See also:

modules

public SyncConfiguration.Builder modules (
java.lang.Iterable<java.lang.Object> modules
)

Replaces the existing module(s) with one or more RealmModule s. 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

  • modules - list of modules tthe first Realm module (required).

Throws

Tip

See also:

public SyncConfiguration.Builder modules (
Object baseModule,
java.lang.Object[] additionalModules
)

Replaces the existing module(s) with one or more RealmModule s. 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

Tip

See also:

name

public SyncConfiguration.Builder name (
String filename
)

Sets the filename for the Realm file on this device.

Parameters

  • filename - name for the Realm file.

readOnly

public SyncConfiguration.Builder readOnly ()

Setting this will cause the Realm to become read only and all write transactions made against this Realm will fail with an IllegalStateException .

This in particular mean that initialData(Realm.Transaction) will not work in combination with a read only Realm and setting this will result in a IllegalStateException being thrown.

Marking a Realm as read only only applies to the Realm in this process. Other processes and devices can still write to the Realm.

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.

schemaVersion

public SyncConfiguration.Builder schemaVersion (
long schemaVersion
)

Sets the schema version of the Realm.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 Realm.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.

Parameters

  • schemaVersion - the schema version.

Throws

syncClientResetStrategy

public SyncConfiguration.Builder syncClientResetStrategy (
DiscardUnsyncedChangesStrategy handler
)

Sets the handler for when a Client Reset occurs. If no handler is set, and error is logged when a Client Reset occurs. This strategy is only available for synced realms using partition based sync. Realms using flexible sync currently only support syncClientResetStrategy(ManuallyRecoverUnsyncedChangesStrategy) .

Parameters

  • handler - custom seamless loss handler in case of a Client Reset.

public SyncConfiguration.Builder syncClientResetStrategy (
ManuallyRecoverUnsyncedChangesStrategy handler
)

Sets the handler for when a Client Reset occurs. If no handler is set, and error is logged when a Client Reset occurs.

Parameters

  • handler - custom manual handler in case of a Client Reset.

urlPrefix

public SyncConfiguration.Builder urlPrefix (
String urlPrefix
)

The prefix that is prepended to the path in the WebSocket request that initiates a sync connection to MongoDB Realm. The value specified must match the server’s configuration otherwise the device will not be able to create a connection. This value is optional and should only be set if a specific firewall rule requires it.

Parameters

  • urlPrefix - The prefix to append to the sync connection url.

waitForInitialRemoteData

public SyncConfiguration.Builder waitForInitialRemoteData (
long timeout,
TimeUnit unit
)

Setting this will cause the Realm to download all known changes from the server the first time a Realm is opened. The Realm will not open until all the data has been downloaded. This means that if a device is offline the Realm will not open.Since downloading all changes can be an lengthy operation that might block the UI thread, Realms with this setting enabled should only be opened on background threads or with Realm.getInstanceAsync(RealmConfiguration, Realm.Callback) on the UI thread.

This check is only enforced the first time a Realm is created. If you otherwise want to make sure a Realm has the latest changes, use SyncSession.downloadAllServerChanges() .

Parameters

public SyncConfiguration.Builder waitForInitialRemoteData ()

Setting this will cause the Realm to download all known changes from the server the first time a Realm is opened. The Realm will not open until all the data has been downloaded. This means that if a device is offline the Realm will not open.Since downloading all changes can be an lengthy operation that might block the UI thread, Realms with this setting enabled should only be opened on background threads or with Realm.getInstanceAsync(RealmConfiguration, Realm.Callback) on the UI thread.

This check is only enforced the first time a Realm is created. If you otherwise want to make sure a Realm has the latest changes, use SyncSession.downloadAllServerChanges() .

← Class SyncConfiguration
Interface SyncConfiguration.InitialFlexibleSyncSubscriptions →

On this page