io.realm

Class RealmConfiguration.Builder

java.lang.Object

io.realm.RealmConfiguration.Builder

Enclosing class:

RealmConfiguration

public static final class RealmConfiguration.Builder
extends java.lang.Object

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

Constructor Summary

Constructors

Constructor and Description
Builder(android.content.Context context) Creates an instance of the Builder for the RealmConfiguration.
Builder(android.content.Context context, java.io.File folder) Creates an instance of the Builder for the RealmConfiguration.
Builder(java.io.File folder) Deprecated. Please use #Builder(Context, File) instead.

Method Summary

Modifier and Type	Method and Description
RealmConfiguration.Builder	assetFile(android.content.Context context, java.lang.String assetFile) Copies the Realm file from the given asset file path.
RealmConfiguration	build() Creates the RealmConfiguration based on the builder parameters.
RealmConfiguration.Builder	deleteRealmIfMigrationNeeded() Setting this will change the behavior of how migration exceptions are handled.
RealmConfiguration.Builder	encryptionKey(byte[] key) Sets the 64 bit key used to encrypt and decrypt the Realm file.
RealmConfiguration.Builder	initialData(Realm.Transaction transaction) Sets the initial data in Realm.
RealmConfiguration.Builder	inMemory() Setting this will create an in-memory Realm instead of saving it to disk.
RealmConfiguration.Builder	migration(RealmMigration migration) Sets the RealmMigration to be run if a migration is needed.
RealmConfiguration.Builder	modules(java.lang.Object baseModule, java.lang.Object... additionalModules) Replaces the existing module(s) with one or more RealmModules.
RealmConfiguration.Builder	name(java.lang.String filename) Sets the filename for the Realm.
RealmConfiguration.Builder	rxFactory(RxObservableFactory factory) Sets the RxObservableFactory used to create Rx Observables from Realm objects.
RealmConfiguration.Builder	schemaVersion(long schemaVersion) Sets the schema version of the Realm.

Methods inherited from class java.lang.Object

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

Constructor Detail

Builder

@Deprecated
public Builder(java.io.File folder)

Deprecated. Please use #Builder(Context, File) instead.

Creates an instance of the Builder for the RealmConfiguration. The Realm file will be saved in the provided folder.

Parameters:

folder - the folder to save Realm file in. Folder must be writable.

Throws:

java.lang.IllegalArgumentException - if folder doesn't exist or isn't writable.

Builder

public Builder(android.content.Context context)

Creates an instance of the Builder for the RealmConfiguration.

This will use the app's own internal directory for storing the Realm file. This does not require any additional permissions. The default location is /data/data/<packagename>/files, but can change depending on vendor implementations of Android.

Parameters:

context - the Android application context.

Builder

public Builder(android.content.Context context,
               java.io.File folder)

Creates an instance of the Builder for the RealmConfiguration.

The Realm file will be saved in the provided folder, and it might require additional permissions.

Parameters:

context - the Android application context.

folder - the folder to save Realm file in. Folder must be writable.

Throws:

java.lang.IllegalArgumentException - if folder doesn't exist or isn't writable.

Method Detail

name

public RealmConfiguration.Builder name(java.lang.String filename)

Sets the filename for the Realm.

encryptionKey

public RealmConfiguration.Builder encryptionKey(byte[] key)

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

schemaVersion

public RealmConfiguration.Builder schemaVersion(long schemaVersion)

Sets the schema version of the Realm. This must be equal to or higher than the schema version of the existing Realm file, if any. If the schema version is higher than the already existing Realm, a migration is needed.

If no migration code is provided, Realm will throw a RealmMigrationNeededException.

See Also:

migration(RealmMigration)

migration

public RealmConfiguration.Builder migration(RealmMigration migration)

Sets the RealmMigration to be run if a migration is needed. If this migration fails to upgrade the on-disc schema to the runtime schema, a RealmMigrationNeededException will be thrown.

deleteRealmIfMigrationNeeded

public RealmConfiguration.Builder deleteRealmIfMigrationNeeded()

Setting this will change the behavior of how migration exceptions are handled. Instead of throwing a RealmMigrationNeededException the on-disc Realm will be cleared and recreated with the new Realm schema.

This cannot be configured to have an asset file at the same time by calling assetFile(Context, String) as the provided asset file will be deleted in migrations.

WARNING! This will result in loss of data.

Throws:

java.lang.IllegalStateException - if configured to use an asset file by calling assetFile(Context, String) previously.

inMemory

public RealmConfiguration.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.

modules

public RealmConfiguration.Builder modules(java.lang.Object baseModule,
                                          java.lang.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:

java.lang.IllegalArgumentException - if any of the modules doesn't have the RealmModule annotation.

See Also:

Realm.getDefaultModule()

rxFactory

public RealmConfiguration.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 RealmConfiguration.Builder initialData(Realm.Transaction transaction)

Sets the initial data in Realm. This transaction will be executed only for the first time when database file is created or while migrating the data when deleteRealmIfMigrationNeeded() is set.

Parameters:

transaction - transaction to execute.

assetFile

public RealmConfiguration.Builder assetFile(android.content.Context context,
                                            java.lang.String assetFile)

Copies the Realm file from the given asset file path.

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 cannot be configured to clear and recreate schema by calling deleteRealmIfMigrationNeeded() at the same time as doing so will delete the copied asset schema.

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

Parameters:

context - Android application context.

assetFile - path to the asset database file.

Throws:

java.lang.IllegalStateException - if this is configured to clear its schema by calling deleteRealmIfMigrationNeeded().

build

public RealmConfiguration build()

Creates the RealmConfiguration based on the builder parameters.

Returns:

the created RealmConfiguration.