Package io.realm

Interface OrderedRealmCollection<E>

  • All Superinterfaces:
    Collection<E>, io.realm.internal.Freezable<RealmCollection<E>>, Iterable<E>, List<E>, io.realm.internal.ManageableObject, RealmCollection<E>
    All Known Implementing Classes:
    OrderedRealmCollectionSnapshot, RealmList, RealmResults
    public interface OrderedRealmCollection<E>
extends List<E>, RealmCollection<E>
    An OrderedRealmCollection is a collection which maintains an ordering for its elements. Every element in the OrderedRealmCollection has an index. Each element can thus be accessed by its index, with the first index being zero. Normally, OrderedRealmCollections allow duplicate elements, as compared to Sets, where elements have to be unique.

    There are three types of OrderedRealmCollection. RealmResults and RealmList are live collections. They are up-to-date all the time and they will never contain an invalid RealmObject. OrderedRealmCollectionSnapshot is different. An OrderedRealmCollectionSnapshot can be created from another OrderedRealmCollection. Its size and elements order stay the same as the original collection's when it was created. OrderedRealmCollectionSnapshot may contain invalid RealmObjects if the objects get deleted.

    Using iterators to iterate on OrderedRealmCollection will always work. You can delete or modify the elements without impacting the iterator. See below example: 

     
 RealmResults<Dog> dogs = realm.where(Dog.class).findAll();
 int s = dogs.size(); // 10
 realm.beginTransaction();
 for (Dog dog : dogs) {
     dog.deleteFromRealm();
     s = dogs.size(); // This will be decreased by 1 every time after a dog is removed.
 }
 realm.commitTransaction();
 s = dogs.size(); // 0

    An iterator created from a live collection will create a stable view when the iterator is created, allowing you to delete and modify elements while iterating without impacting the iterator. However, the RealmResults backing the iterator will still be live updated meaning that size and order of elements can change when iterating. RealmList has the same behaviour as RealmResults since they are both live collections.

    A simple for-loop is different. See below example: 

     
 RealmResults<Dog> dogs = realm.where(Dog.class).findAll();
 realm.beginTransaction();
 for (int i = 0; i < dogs.size(); i++) {
     dogs.get(i).deleteFromRealm();
 }
 realm.commitTransaction();
 s = dogs.size(); // 5

    The above example only deletes half of elements in the RealmResults. This is because of dogs.size() decreased by 1 for every loop. The deletion happens in the loop will immediately impact the size of RealmResults. To solve this problem, you can create a OrderedRealmCollectionSnapshot from the RealmResults or RealmList and do simple for-loop on that instead: 

     
 RealmResults<Dog> dogs = realm.where(Dog.class).findAll();
 OrderedRealmCollectionSnapshot snapshot = dogs.createSnapshot();
 // dogs.size() == 10 && snapshot.size() == 10
 realm.beginTransaction();
 for (int i = 0; i < snapshot.size(); i++) {
     snapshot.get(0).deleteFromRealm();
     // snapshot.get(0).isValid() == false
 }
 realm.commitTransaction();
 // dogs.size() == 0 && snapshot.size() == 10

    As you can see, after deletion, the size and elements order of snapshot stay the same as before. But the element at the position becomes invalid.

    • Method Detail

      • first

        @Nullable
E first​(@Nullable
        E defaultValue)
        Gets the first object from the collection. If the collection is empty, the provided default will be used instead.
        Returns:
        the first object or the provided default.

      • last

        @Nullable
E last​(@Nullable
       E defaultValue)
        Gets the last object from the collection. If the collection is empty, the provided default will be used instead.
        Returns:
        the last object or the provided default.

      • sort

        RealmResults<E> sort​(String fieldName)
        Sorts a collection based on the provided field in ascending order.
        Parameters:
        fieldName - the field name to sort by. Only fields of type boolean, short, int, long, float, double, Date, and String are supported.
        Returns:
        a new sorted RealmResults will be created and returned. The original collection stays unchanged.
        Throws:
        IllegalArgumentException - if field name does not exist or it has an invalid type.
        IllegalStateException - if the Realm is closed, called on the wrong thread or the collection is an unmanaged collection.

      • sort

        RealmResults<E> sort​(String fieldName,
                     Sort sortOrder)
        Sorts a collection based on the provided field and sort order.
        Parameters:
        fieldName - the field name to sort by. Only fields of type boolean, short, int, long, float, double, Date, and String are supported.
        sortOrder - the direction to sort by.
        Returns:
        a new sorted RealmResults will be created and returned. The original collection stays unchanged.
        Throws:
        IllegalArgumentException - if field name does not exist or has an invalid type.
        IllegalStateException - if the Realm is closed, called on the wrong thread or the collection is an unmanaged collection.

      • sort

        RealmResults<E> sort​(String fieldName1,
                     Sort sortOrder1,
                     String fieldName2,
                     Sort sortOrder2)
        Sorts a collection based on the provided fields and sort orders.
        Parameters:
        fieldName1 - first field name. Only fields of type boolean, short, int, long, float, double, Date, and String are supported.
        sortOrder1 - sort order for first field.
        fieldName2 - second field name. Only fields of type boolean, short, int, long, float, double, Date, and String are supported.
        sortOrder2 - sort order for second field.
        Returns:
        a new sorted RealmResults will be created and returned. The original collection stays unchanged.
        Throws:
        IllegalArgumentException - if a field name does not exist or has an invalid type.
        IllegalStateException - if the Realm is closed, called on the wrong thread or the collection is an unmanaged collection.

      • sort

        RealmResults<E> sort​(String[] fieldNames,
                     Sort[] sortOrders)
        Sorts a collection based on the provided fields and sort orders.
        Parameters:
        fieldNames - an array of field names to sort by. Only fields of type boolean, short, int, long, float, double, Date, and String are supported.
        sortOrders - the directions to sort by.
        Returns:
        a new sorted RealmResults will be created and returned. The original collection stays unchanged.
        Throws:
        IllegalArgumentException - if a field name does not exist or has an invalid type.
        IllegalStateException - if the Realm is closed, called on the wrong thread or the collection is an unmanaged collection.

      • deleteFromRealm

        void deleteFromRealm​(int location)
        Deletes the object at the given index from the Realm. This also removes it from the collection.
        Parameters:
        location - the array index identifying the object to be removed.
        Throws:
        IndexOutOfBoundsException - if location < 0 || location >= size().
        IllegalStateException - if the Realm is closed or the method is called from the wrong thread.
        UnsupportedOperationException - if the collection is unmanaged.

      • deleteFirstFromRealm

        boolean deleteFirstFromRealm()
        Deletes the first object from the Realm. This also removes it from this collection.
        Returns:
        true if an object was deleted, false otherwise.
        Throws:
        IllegalStateException - if the Realm is closed or the method is called on the wrong thread.
        UnsupportedOperationException - if the collection is unmanaged.

      • deleteLastFromRealm

        boolean deleteLastFromRealm()
        Deletes the last object from the Realm. This also removes it from this collection.
        Returns:
        true if an object was deleted, false otherwise.
        Throws:
        IllegalStateException - if the Realm is closed or the method is called from the wrong thread.
        UnsupportedOperationException - if the collection is unmanaged.