API review & cleanup for 1.0

[nhachicha]

The following things should be implemented:

• JSON methods currently wrap all runtime exceptions in a RealmException. Consider removing this as it makes it hard to know exactly what failed -> Remove RealmException where possible. ( Throw the most accurate exception possible in JSON methods #2618 )
• Cleanup sorted* methods. Remove all sort methods accepting 3 fields. Multiarg should be used instead. ( Deprecated 3 field sort in Realm and RealmQuery #2619 )
• Remove allObjects and friends from Realm so all query options are in RealmQuery. ( Move all query methods to RealmQuery #2620 )
• RealmConfiguration setModules() rename to modules() ( Use RealmConfig.modules() instead of RealmConfig.setModules() #2621 )
• All lists methods should automatically do copyToRealm or copyToRealmOrUpdate (mc Checked, all methods which could add/change object in the list, will call copyToRealmIfNeeded)
• RealmChangeListener should provide the changes object/realm/collection as well (#1594 RealmChangeListener should provide the changes object/realm/collection as well #2705)
• realm.createObject(class, primaryKey) should be public ( Make Realm.createObject(Class,PrimaryKey) public #2622 )
• All methods on RealmObject should be final. All public Realm classes should be final (Make all methods on RealmObject and all classes in public API final #2675).
• BaseRealm should be package protected (will most likely require moving some things to io.realm) (BaseRealm should be package protected #2673)
• HandlerController should be package protected. ( Made HandlerController package private. #2632 )
• Constructor of RealmAsyncTask should be package protected (mark constructor of RealmAsyncTask package protected #2676).

---

This issue help track any suggested refactoring, cleanup of the current API to prepare for 1.0 release.
this is not a call for feature, but a take on the existing API to rename/refactor.

please share your suggestions, it would be helpful to include motivation & code snippet/prototype so people can have a quick idea to up/down vote.

[cmelchior]

Some things on my list:

• Get rid of the difference between copyToRealm and copyOrUpdateToRealm. If your model class has primary keys just using copyToRealm doesn't make any sense.
• Consider renaming where to query or filter to get away from the SQL terminology -> Rename to query().
• JSON methods currently wrap all runtime exceptions in a RealmException. Consider removing this as it makes it hard to know exactly what failed -> Remove RealmException where possible.
• Cleanup sorted* methods. At least get rid of those with 3 field sorting. -> gone
• Move BadVersionException to io.realm.exceptions
• Remove allObjects and friends from Realm so all query options are in RealmQuery -> remove
• RealmConfiguration setModules() rename to modules(): Yes
• Determine how/which methods should automatically do copyToRealm behind the users back if adding standalone objects to managed objects. Right now it is a bit inconsistent -> Yes. We just need to verify.

[astigsen]

Consider renaming where to query to get away from the SQL terminology.

In Swift the method is called filter, so it might be an idea to standardize on that?

[nhachicha]

As part of the 1.0 cleanup https://github.com/realm/realm-java-private/issues/21

[cmelchior]

This should also include formalising our Javadoc style and do a cleanup based on that.

[beeender]

• argument for RealmChangeListener.onChange
  • RealmChangeListener.onChange(Realm)
  • RealmChangeListener.onChange(RealmObject)
  • RealmChangeListener.onChange(RealmResults)

👍

public interface RealmChange<T> {
    void onChange(T obj);
}

// RealmResults:
    public void addChange(RealmChange<RealmResults<E>> listener) {

    };
//     
public void test() {
        allObjects(Foo.class).addChange(new RealmChange<RealmResults<Foo>>() {
            @Override
            public void onChange(RealmResults<Foo> obj) {

            }
        });
    }

[cmelchior]

addRealmChangeListener should return the type being observed instead of void for better fluent behavior:

RealmResults<Foo> foos = realm.where(Foo.class).findAllAsync().addChangeListener(() -> {});
foos.clearAllListeners(); // No need for to add listener, and really easy to unregister again to avoid leaks.

[cmelchior]

@Index vs. @Indexed
@Ignore vs. @Ignored

Keep it e.g Java @Override

[cmelchior]

Inheritance hierarchy with regard to DynamicRealmObject/RealmObject, RealmResults<DynamicRealmObject>, RealmResults<RealmObject> etc.

[cmelchior]

SQLite can just do db.insert(...) which is an implicit transaction.
Would it make sense to do the same for copyToRealm or copyToRealmOrUpdate, so you could just do:

Person p = new Person()
realm.copyToRealm(p);

[cmelchior]

Consider replacing @ignore with the transient keyword instead

[cmelchior]

Right now the List interface methods clear()/remove(int)/removeAll(collection) mean different things across RealmList/RealmResults. This adds mental overhead to using Realm.

Also we have the methods RealmObject.removeFromRealm() and RealmList.removeAllFromRealm().
It would be nice we we could somehow express better the difference between "removing from the list" vs. "removing from the list + remove it from Realm", while still being true to the original interfaces.

Done in #1363

[beeender]

Consistency problem with BaseRealm.beginTransaction() BaseRealm.commitTransaction but Realm.executeTransaction().

This could happen in the adapter which only hold a reference to a RealmResults.
User can do:

results.getRealm().beginTransaction();
restults.getRealm().commitTransaction();

but cannot do:

results.getRealm().executeTransaction();

[cmelchior]

Should the findFirst object be live just like a RealmQuery, aka. Should it be able to change completely. Right now once the "first" object has been found we only update that object, we don't replace it, if another object becomes the "first"

[nhachicha]

some output from the API review I did with JP for Cocoa (16/03/2016)

• in Cocoa distinct() will be implemented using NSPredicat (not part of RLMCollection) -> RealmQuery.distinctAsync(), RealmResults.distinctAsync() support #2118
• Cocoa exposes an API to retrieve backlinks.
  we don't have this on Java, Mark is working on it, changes needs to be add to Core then reflected on ObejctStore
  maybe we should wait for ObjectStore integration before implementing this feature. -> Reverse lookup (Backlinks) #607 post 1.0
• in Cocoa commitWrite/ commit maybe recoverable in certain UC depending on Core exception type
  Ex : FileAccessError (out of disk) we can make those checked Exceptions on Java -> Yes, but need list of specific core exceptions to map.
• update objects in bulk (something we don't have in Java) it's using KVC
  the implementation avoid creating Objective-C accessors ==> more cheap
  it also keeps a frozen copy of the table_view -> Batch or bulk updates #762 on roadmap after 1.0
• for-loop​ behaves like frozen table_view (deep copy for accessors only to operate on) -> Fixed in Enable proper iterator behavior #2124
• We don't have IN in Java ==> should be available in ObjectStore -> equalToAny() / equalToAll() / In() — query for list membership #841 is on roadmap
• The async queries impl is different
  two different behavior :
  ~~ 1- first run block the UI thread, then subsequent updates happen in the background ~~

~~ 2- you pass a callback & the user will have the Result when the first run completes
all the subsequent updates happen in the background
no promise/future is returned ~~

[cmelchior]

public realm.createObject(Class, primaryKey)

[bdash]

in Cocoa distinct() will be implemented using NSPredicate (not part of RLMCollection) -> #2118

I don't think this is quite right. NSPredicate's support for "distinct" is quite different than what Java's API provides, and cannot be used to achieve the same results as the Java API.

[jpsim]

in Cocoa commitWrite/ commit maybe recoverable in certain UC depending on Core exception type
Ex : FileAccessError (out of disk) we can make those checked Exceptions on Java -> Yes, but need list of specific core exceptions to map.

See realm/realm-swift#3437

[cmelchior]

All issues fixed. Closing

[iamaniba]

Is that 841 fixed? Do we have any api to get Results based on list.