readOnly() was added in #4575.

Right now the Schema of a read-only Realm must strictly match the provided schema. If it doesn't a RealmMigrationNeededException is thrown. Which it is impossible to react to since the Realm is read-only.

Cocoa (and Object Store) has slightly different semantics. They will allow classes to be missing and will instead mock them if queried i.e. they will allow queries on non-existing tables (in read-only mode), but just always return the empty set.

This makes sense if the cases where you don't want to force people to re-create the assetFile every time they add new model classes.

However, in Java you could also accomplish the same by creating a RealmModule:

@RealmModule(classes = { MyModel.class })
public class MyModule() {

}

// This schema is restricted to only the classes in the assetFile
RealmConfiguration config = new RealmConfiguration.Builder()
  .modules(new MyModule()) // Restrict schema
  .assetFile("my.realm")
  .readOnly()
  .build();

Considering that mocking a missing class would have major ramifications on our RealmQuery class, I'm not convinced that adopting the same semantics is worthwhile, but it does mean the behavior will be slightly different from Cocoa. Thoughts @realm/java ?