RealmConfiguration + new constructors #929

cmelchior · 2015-03-06T08:07:35Z

This fixes #511
This PR is part of #880

This PR changes how Realms are created. Our current approach with telescoping constructor arguments are not scalable especially as Migrations introduce new arguments and we have in-memory/read-only realms coming as well. It also allows us to move the Android Context away from Realm.java.

API Overview

This PR replaces the current constructors with a RealmConfiguration that are constructed using the Builder pattern:

// Creating a configuration, using a Builder. This makes it very scalable without having to add new constructors in Realm.java

// Full set of options are in this PR are:
RealmConfiguration config = new RealmConfiguration.Builder(getContext())
                        .name("default.realm")
                        .encryptionKey(getKey())
                        .schemaVersion(42)
                        .migration(new MyMigration())
                        .addModule(new MyModule())  // Add 1 module to already set modules
                        .setModules(new MyModule(),  new MyLibraryModule()) // Replace current modules
                        .deleteRealmIfMigrationNeeded()
                        .schema(Foo.class, Bar.class) // package protected method, only used for internal testing.
                        .build()

// Constructors are:
RealmConfiguration.Builder builder = new RealmConfiguration.Builder(Context ctx);
RealmConfiguration.Builder builder = new RealmConfiguration.Builder(File realmDir);

I don't think a directory is needed for in-memory Realms, but requiring a folder in the constructor makes it a lot less error prone.

// Introduce the concept of a default Realm (This is also the same on Cocoa where you can configure a default Realm)
Realm.setDefaultConfiguration(config); // A default configuration must be set first
Realm.getDefaultInstance(); // Making it even easier to get a default instance
Realm.getInstance(config); // Getting the instance for any given configuration

// These two are similar
Realm.getInstance(getContext())
Realm.getInstance(new RealmConfiguration.Builder(getContext()).build())

// Deprecated methods
Realm.getInstance(Context context, String fileName)
Realm.getInstance(Context context, byte[] key)
Realm.getInstance(Context context, String fileName, byte[] key)
Realm.getInstance(File writeableFolder)
Realm.getInstance(File writeableFolder, String fileName)
Realm.getInstance(File writeableFolder, byte[] key)
Realm.getInstance(File writeableFolder, String fileName, byte[] key)
Realm.deleteRealmFile(Context context, String fileName)
Realm.deleteRealmFile(Context context)
Realm.migrateRealmAtPath(String realmPath, RealmMigration migration)
Realm.migrateRealmAtPath(String realmPath, byte[] key, RealmMigration migration)
Realm.migrateRealmAtPath(String realmPath, RealmMigration migration, boolean autoRefresh)
Realm.migrateRealmAtPath(String realmPath, byte[] key, RealmMigration migration, boolean autoUpdate)
Realm.compactRealmFile(Context context, String fileName)
Realm.compactRealmFile(Context context)

// Note that the following constructor is kept to make it easier for Realm beginners? Is this just API bloat?
Realm.getInstance(Context context)

// New methods replacing them
Realm.getDefaultInstance();
Realm.getInstance(RealmConfiguration realmConfig)
Realm.deleteRealm(RealmConfiguration realmConfig);
Realm.migrateRealm(RealmConfiguration realmConfig);
Realm.migrateRealm(RealmConfiguration realmConfig, RealmMigration migration);
Realm.compactRealm(RealmConfiguration realmConfig);

SchemaVersion and Migration

The current interaction between using .schemaVersion() and .migration() is the following:

If only schemaVersion is set we make a no-op migration behind the scenes that try to upgrade the version number. Schema is validated afterwards and throw an exception if there is mismatch.
If newSchemaVersion > currentSchemaVersion and a migration block is set. This migration will be called when first opening the Realm. We also have a method on the Realm for manually triggering this migration. Useful if you want to upgrade on a background thread: Realm.migrateRealm(RealmConfiguration)
Setting a migration block without a schemaVersion is a no-op, ie. migration code is never called. We might want to log a warning or throw an exception for this.
Setting a newSchemaVersion < currentSchemaVersion will throw an exception when opening the Realm.
Setting newSchemaVersion == currentSchemaVersion and a schema mismatch is detected will throw an exception when opening the Realm.
The current RealmMigration interface will be kept until we introduce the new Migration API as it will introduce breaking changes.

Discussion

Some implementation details that could be discussed:

A RealmConfiguration is immutable once created.
How to handle multiple configurations pointing to the same Realm. Currently it is allowed (eg. needed for ReadOnly realms).

This PR will also potentially deprecate a lot of methods (all constructors + all migrateRealmAtPath() + deleteRealmFile) , so I would rather introduce it all at once, and then having the option of extending RealmConfiguration afterwards.

Missing:

Determine policy for when migrations are needed and interaction with schemaVersion. Check Cocoa: Add RLMConfiguration realm-swift#1584
Determine policy for multiple configurations pointing to the same Realm file. See RealmConfiguration used as cache key #1156
Update examples (separate PR)
Add example for using library projects with Realm (separate PR)
Update website/documentation (separate PR)

…ead of telescoping constructors.

emanuelez · 2015-03-06T18:51:10Z

I like the direction, but we're breaking the API drastically. I think we should maintain the old constructors while deprecating them until the following big release.

cmelchior · 2015-03-06T18:58:15Z

Yeah that was my plan as well, this commit might have cleaned up a bit to drastically

timanglade · 2015-03-08T16:20:49Z

@alazier Would love to get your thoughts on this. See also #java on slack for additional conversation about this PR.

emanuelez · 2015-03-09T12:57:44Z

Also, we might want to keep static constructor for the most common case:

Context or File
Context of File + Migration + Version

alazier · 2015-03-09T16:31:52Z

@timanglade this is something I have proposed for the cocoa apis multiple times (and think I have mentioned it to @cmelchior). As the number of global configuration parameters grows this will likely be a necessity.

My concerns with this proposal would be:

version should be schemaVersion to remove any ambiguity
In cocoa we will also need parameters for readOnly, inMemoryIdentifier - not sure if you support these in java
We might also want to consider support notifications so that all realm configuration can be done in one place. We would still want register/unregister methods though for users who want to change notifications after realm initialization
Is name the same thing as path? Do we just use different terminologies on java vs cocoa?

cmelchior · 2015-03-09T18:46:01Z

@alazier
We have actually been talking about trying to move away from SQL terminology on the Android side, ie.
version instead of schemaVersion, Modules/ClassCollection instead of schema etc. to avoid people associating Realm with SQL too much. However it has not been decided yet and should probably be agreeded on for both platforms. What is your stance on that?

We don't support ReadOnly and InMemory yet, but it is coming.

I don't think the configuration is a good place for adding notification setup as they are added/removed a lot more while the Realm is used. I would prefer to keep the setup methods to initialisation properties.

Name is filename, on android path is split into 2 methods, one for folder and one for filename as getting a default document folder is a bit more complicated.

…ility methods that now uses RealmConfiguration.

…changes.

Conflicts: realm/src/main/java/io/realm/Realm.java

…ed my in memory realm.

cmelchior · 2015-05-06T07:14:58Z

I have updated the top note with current API design. Feedback welcome. We still miss support for custom schemas but that will be included ons #938 has been merged.

@segiddins @bmunkholm @emanuelez @kneth

kneth · 2015-05-06T08:38:39Z

realm/src/androidTest/java/io/realm/RealmConfigurationTest.java

+                    .schemaVersion(42)
+                    .schema(AllTypesPrimaryKey.class)
+                    .build());
+            fail("A migration should be required");


It seems to be an inconsistency how you use try/catch and fail() in this unit test and other unit tests.

kneth · 2015-05-06T08:47:41Z

Will you add an option to compact the Realm file before opening?

cmelchior · 2015-05-06T08:57:09Z

I didn't consider that. It would be fairly easy adding an option like:

config.compactRealmWhenClosing() or config.compactRealmWhenOpening()

However I am a bit worried it would introduce a unpredictable slowdown as compaction could potentially take a lot of time + plus it require additional space on the disc ?

kneth · 2015-05-06T09:33:59Z

Realm Core might be able to provide information about how much space is saved before actually calling compact.

kneth · 2015-05-29T13:27:30Z

realm/src/androidTest/java/io/realm/RealmConfigurationTest.java

+
+    public void testWrongKeyLengthThrows() {
+        try {
+            new RealmConfiguration.Builder(getContext()).encryptionKey(new byte[63]).build();


What about 65?

kneth · 2015-05-29T13:54:08Z

I believe it is ready to be merged (when my few last comments are addressed).

emanuelez · 2015-06-02T09:06:06Z

Please make this merge-able and address @kneth 's comments. I think this is ready for prime time.

Conflicts: changelog.txt realm/src/main/java/io/realm/Realm.java realm/src/main/java/io/realm/internal/Util.java

cmelchior · 2015-06-02T12:55:51Z

Any final comments @kneth @emanuelez @nhachicha @bmunkholm before I merge this?

emanuelez · 2015-06-02T13:00:48Z

realm-annotations-processor/src/test/java/io/realm/processor/RealmProcessorTest.java

@@ -29,7 +32,6 @@
    private JavaFileObject simpleModel = JavaFileObjects.forResource("some/test/Simple.java");
    private JavaFileObject simpleProxy = JavaFileObjects.forResource("io/realm/SimpleRealmProxy.java");
    private JavaFileObject allTypesModel = JavaFileObjects.forResource("some/test/AllTypes.java");
-    private JavaFileObject allTypesProxy = JavaFileObjects.forResource("io/realm/AllTypesRealmProxy.java");


we should still check that we produce the expected model class proxy! This is a problem introduced in the Modules PR

cmelchior · 2015-06-03T09:31:35Z

RealmConfiguration.addModule() removed and Realm.getDefaultModule() introduced instead.

@emanuelez @nhachicha @kneth

emanuelez · 2015-06-04T08:59:04Z

RealmConfiguration + new constructors

cmelchior added 2 commits March 6, 2015 08:15

Added RealmConfiguration + Builder. Refactored Realm to use this inst…

5b29976

…ead of telescoping constructors.

Removing test code

632e487

bmunkholm mentioned this pull request Mar 9, 2015

Add RLMConfiguration realm/realm-swift#1584

Closed

cmelchior mentioned this pull request Mar 10, 2015

java.lang.IllegalStateException: Objects cannot be changed outside a transaction on findAll() call #941

Closed

cmelchior added 3 commits March 16, 2015 19:16

Streamline new constructors and deprecate old constructors + other ut…

a39ca18

…ility methods that now uses RealmConfiguration.

Merge branch 'master' into cm-configuration-builder

3c70bab

Added test cases for RealmConfiguration + minor refactoring.

fdbe368

cmelchior added the PR label Mar 20, 2015

cmelchior added 3 commits March 22, 2015 10:28

Merge branch 'master' into cm-configuration-builder

083fd7f

Fixed unit tests. Renamed version to SchemaVersion

6393086

Cleanup unit tests. Removed automatic version upgrade with no schema …

1fa0ddb

…changes.

cmelchior mentioned this pull request Apr 2, 2015

In-Memory Realms android #1007

Closed

cmelchior mentioned this pull request Apr 22, 2015

Realm IDs are now its absolute path instead of its hashcode #1054

Merged

cmelchior mentioned this pull request Apr 29, 2015

New migration + dynamic API #1046

Closed

bmunkholm added P1 and removed PR labels Apr 30, 2015

cmelchior added 3 commits May 5, 2015 17:06

Merge branch 'master' into cm-configuration-builder

1a4ec73

Conflicts: realm/src/main/java/io/realm/Realm.java

Cleaned up naming. Removed deleteRealmBeforeOpening, should be replac…

7463741

…ed my in memory realm.

Removed option of deleting Realm on start

07dee9f

kneth reviewed May 6, 2015
View reviewed changes

kneth reviewed May 29, 2015
View reviewed changes

Merge branch 'master' into cm-configuration-builder

7e667fc

cmelchior added 2 commits June 2, 2015 13:44

Merge branch 'master' into cm-configuration-builder

9828737

Conflicts: changelog.txt realm/src/main/java/io/realm/Realm.java realm/src/main/java/io/realm/internal/Util.java

Cleanup test + language. Encryption key length is now a constant.

b454011

emanuelez reviewed Jun 2, 2015
View reviewed changes

cmelchior added 3 commits June 2, 2015 15:13

Readdded AllTypesRealmProxy unit test.

8e1dd5b

Merge branch 'master' into cm-configuration-builder

153a79e

Removed addModule and exposed Realm.getDefaultModule().

da2637b

cmelchior added a commit that referenced this pull request Jun 4, 2015

Merge pull request #929 from realm/cm-configuration-builder

4160757

RealmConfiguration + new constructors

cmelchior merged commit 4160757 into master Jun 4, 2015

cmelchior removed the PR label Jun 4, 2015

cmelchior deleted the cm-configuration-builder branch June 4, 2015 09:03

This was referenced Jun 6, 2015

java.lang.ClassNotFoundException: Didn't find class "io.realm.DefaultRealmModuleMediator" #1189

Closed

Realm crashes when there is no model classes #860

Closed

Fixed migration example #1191

Merged

Migrations API v2 #880

Closed

github-actions bot locked as resolved and limited conversation to collaborators Mar 17, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

RealmConfiguration + new constructors #929

RealmConfiguration + new constructors #929

cmelchior commented Mar 6, 2015

emanuelez commented Mar 6, 2015

cmelchior commented Mar 6, 2015

timanglade commented Mar 8, 2015

emanuelez commented Mar 9, 2015

alazier commented Mar 9, 2015

cmelchior commented Mar 9, 2015

cmelchior commented May 6, 2015

kneth May 6, 2015

kneth commented May 6, 2015

cmelchior commented May 6, 2015

kneth commented May 6, 2015

kneth May 29, 2015

kneth commented May 29, 2015

emanuelez commented Jun 2, 2015

cmelchior commented Jun 2, 2015

emanuelez Jun 2, 2015

cmelchior commented Jun 3, 2015

emanuelez commented Jun 4, 2015

RealmConfiguration + new constructors #929

RealmConfiguration + new constructors #929

Conversation

cmelchior commented Mar 6, 2015

API Overview

SchemaVersion and Migration

Discussion

emanuelez commented Mar 6, 2015

cmelchior commented Mar 6, 2015

timanglade commented Mar 8, 2015

emanuelez commented Mar 9, 2015

alazier commented Mar 9, 2015

cmelchior commented Mar 9, 2015

cmelchior commented May 6, 2015

kneth May 6, 2015

Choose a reason for hiding this comment

kneth commented May 6, 2015

cmelchior commented May 6, 2015

kneth commented May 6, 2015

kneth May 29, 2015

Choose a reason for hiding this comment

kneth commented May 29, 2015

emanuelez commented Jun 2, 2015

cmelchior commented Jun 2, 2015

emanuelez Jun 2, 2015

Choose a reason for hiding this comment

cmelchior commented Jun 3, 2015

emanuelez commented Jun 4, 2015