E - the class of objects in list.public class RealmList<E> extends AbstractList<E> implements OrderedRealmCollection<E>
RealmObject.
RealmList has two modes: A managed and unmanaged mode. In managed mode all objects are persisted inside a Realm, in
unmanaged mode it works as a normal ArrayList.
Only Realm can create managed RealmLists. Managed RealmLists will automatically update the content whenever the
underlying Realm is updated, and can only be accessed using the getter of a RealmObject.
Unmanaged RealmLists can be created by the user and can contain both managed and unmanaged RealmObjects. This is
useful when dealing with JSON deserializers like GSON or other frameworks that inject values into a class.
Unmanaged elements in this list can be added to a Realm using the Realm.copyToRealm(Iterable, ImportFlag...) method.
RealmList can contain more elements than Integer.MAX_VALUE.
In that case, you can access only first Integer.MAX_VALUE elements in it.
| Constructor and Description |
|---|
RealmList()
Creates a RealmList in unmanaged mode, where the elements are not controlled by a Realm.
|
RealmList(E... objects)
Creates a RealmList in unmanaged mode with an initial list of elements.
|
| Modifier and Type | Method and Description |
|---|---|
boolean |
add(E object)
Adds the specified object at the end of this List.
|
void |
add(int location,
E element)
Inserts the specified object into this List at the specified location.
|
void |
addChangeListener(OrderedRealmCollectionChangeListener<RealmList<E>> listener)
Adds a change listener to this
RealmList. |
void |
addChangeListener(RealmChangeListener<RealmList<E>> listener)
Adds a change listener to this
RealmList. |
<any> |
asChangesetObservable()
Returns an Rx Observable that monitors changes to this RealmList.
|
<any> |
asFlowable()
Returns an Rx Flowable that monitors changes to this RealmList.
|
double |
average(String fieldName)
Returns the average of a given field.
|
void |
clear()
Removes all elements from this list, leaving it empty.
|
boolean |
contains(Object object)
Returns
true if the list contains the specified element when attached to a Realm. |
OrderedRealmCollectionSnapshot<E> |
createSnapshot()
Creates a snapshot from this
OrderedRealmCollection. |
boolean |
deleteAllFromRealm()
This deletes all objects in the collection from the underlying Realm as well as from the collection.
|
boolean |
deleteFirstFromRealm()
Deletes the first object from the Realm.
|
void |
deleteFromRealm(int location)
Deletes the object at the given index from the Realm.
|
boolean |
deleteLastFromRealm()
Deletes the last object from the Realm.
|
E |
first()
Gets the first object from the collection.
|
E |
first(E defaultValue)
Gets the first object from the collection.
|
RealmList<E> |
freeze()
Returns a frozen snapshot of this collection.
|
E |
get(int location)
Returns the element at the specified location in this list.
|
Realm |
getRealm()
Returns the
Realm instance to which this collection belongs. |
boolean |
isFrozen() |
boolean |
isLoaded()
Checks if a collection has finished loading its data yet.
|
boolean |
isManaged()
Checks if the collection is managed by Realm.
|
boolean |
isValid()
Checks if the collection is still valid to use, i.e., the
Realm instance hasn't been closed. |
Iterator<E> |
iterator() |
E |
last()
Gets the last object from the collection.
|
E |
last(E defaultValue)
Gets the last object from the collection.
|
ListIterator<E> |
listIterator() |
ListIterator<E> |
listIterator(int location) |
boolean |
load()
Blocks the collection until all data are available.
|
Number |
max(String fieldName)
Finds the maximum value of a field.
|
Date |
maxDate(String fieldName)
Finds the maximum date.
|
Number |
min(String fieldName)
Finds the minimum value of a field.
|
Date |
minDate(String fieldName)
Finds the minimum date.
|
void |
move(int oldPos,
int newPos)
Moves an object from one position to another, while maintaining a fixed sized list.
|
E |
remove(int location)
Removes the object at the specified location from this list.
|
boolean |
remove(Object object)
Removes one instance of the specified object from this
Collection if one
is contained. |
boolean |
removeAll(Collection<?> collection)
Removes all occurrences in this
Collection of each object in the
specified Collection. |
void |
removeAllChangeListeners()
Removes all user-defined change listeners.
|
void |
removeChangeListener(OrderedRealmCollectionChangeListener<RealmList<E>> listener)
Removes the specified change listener.
|
void |
removeChangeListener(RealmChangeListener<RealmList<E>> listener)
Removes the specified change listener.
|
E |
set(int location,
E object)
Replaces the element at the specified location in this list with the specified object.
|
int |
size()
Returns the number of elements in this
List. |
RealmResults<E> |
sort(String fieldName)
Sorts a collection based on the provided field in ascending order.
|
RealmResults<E> |
sort(String[] fieldNames,
Sort[] sortOrders)
Sorts a collection based on the provided fields and sort orders.
|
RealmResults<E> |
sort(String fieldName,
Sort sortOrder)
Sorts a collection based on the provided field and sort order.
|
RealmResults<E> |
sort(String fieldName1,
Sort sortOrder1,
String fieldName2,
Sort sortOrder2)
Sorts a collection based on the provided fields and sort orders.
|
Number |
sum(String fieldName)
Calculates the sum of a given field.
|
String |
toString() |
RealmQuery<E> |
where()
Returns a RealmQuery, which can be used to query for specific objects of this class.
|
addAll, equals, hashCode, indexOf, lastIndexOf, subListaddAll, containsAll, isEmpty, retainAll, toArray, toArrayaddAll, addAll, containsAll, equals, hashCode, indexOf, isEmpty, lastIndexOf, replaceAll, retainAll, sort, spliterator, subList, toArray, toArrayparallelStream, removeIf, streampublic RealmList()
ArrayList and it is not possible to query
the objects in this state.
Use Realm.copyToRealm(Iterable, ImportFlag...) to properly persist its elements in Realm.
public RealmList(E... objects)
ArrayList and it is not possible to query the
objects in this state.
Use Realm.copyToRealm(Iterable, ImportFlag...) to properly persist all unmanaged elements in Realm.
objects - initial objects in the list.public boolean isValid()
Realm instance hasn't been closed. It
will always return true for an unmanaged collection.isValid in interface RealmCollection<E>true if it is still valid to use or an unmanaged collection, false otherwise.public RealmList<E> freeze()
IllegalStateException.
Freezing a collection also creates a Realm which has its own lifecycle, but if the live Realm that spawned the original collection is fully closed (i.e. all instances across all threads are closed), the frozen Realm and this collection will be closed as well.
Frozen collections can be queried as normal, but trying to mutate it in any way or attempting to register a listener will
throw an IllegalStateException.
Note: Keeping a large number of frozen collections with different versions alive can have a negative impact on the filesize
of the Realm. In order to avoid such a situation, it is possible to set RealmConfiguration.Builder.maxNumberOfActiveVersions(long).
freeze in interface RealmCollection<E>public boolean isFrozen()
public boolean isManaged()
If this method returns false, the collection is unmanaged. An unmanaged collection is just a normal java
collection, so it will not be live updated.
isManaged in interface RealmCollection<E>true if this is a managed RealmCollection, false otherwise.public void add(int location,
E element)
Realm.copyToRealm(RealmModel, ImportFlag...) afterwards.Realm.copyToRealm(RealmModel, ImportFlag...)
or Realm.copyToRealmOrUpdate(RealmModel, ImportFlag...) if it has a primary key.add in interface List<E>add in class AbstractList<E>location - the index at which to insert.element - the element to add.IllegalStateException - if Realm instance has been closed or container object has been removed.IndexOutOfBoundsException - if location < 0 || location > size().public boolean add(E object)
Realm.copyToRealm(RealmModel, ImportFlag...) afterwards.Realm.copyToRealm(RealmModel, ImportFlag...)
or Realm.copyToRealmOrUpdate(RealmModel, ImportFlag...) if it has a primary key.add in interface Collection<E>add in interface List<E>add in class AbstractList<E>object - the object to add.true.IllegalStateException - if Realm instance has been closed or parent object has been removed.public E set(int location, E object)
Realm.copyToRealm(RealmModel, ImportFlag...) afterwards.Realm.copyToRealm(RealmModel, ImportFlag...) or
Realm.copyToRealmOrUpdate(RealmModel, ImportFlag...) if it has a primary key.set in interface List<E>set in class AbstractList<E>location - the index at which to put the specified object.object - the object to add.IllegalStateException - if Realm instance has been closed or parent object has been removed.IndexOutOfBoundsException - if location < 0 || location >= size().public void move(int oldPos,
int newPos)
null values are introduced.oldPos - index of RealmObject to move.newPos - target position. If newPos < oldPos the object at the location will be shifted to the right. If
oldPos < newPos, indexes > oldPos will be shifted once to the left.IllegalStateException - if Realm instance has been closed or parent object has been removed.IndexOutOfBoundsException - if any position is outside [0, size()].public void clear()
clear in interface Collection<E>clear in interface List<E>clear in class AbstractList<E>IllegalStateException - if Realm instance has been closed or parent object has been removed.List.isEmpty(),
List.size(),
deleteAllFromRealm()public E remove(int location)
remove in interface List<E>remove in class AbstractList<E>location - the index of the object to remove.IllegalStateException - if Realm instance has been closed or parent object has been removed.IndexOutOfBoundsException - if location < 0 || location >= size().public boolean remove(Object object)
Collection if one
is contained. This implementation iterates over this
Collection and tests each element e returned by the iterator,
whether e is equal to the given object. If object != null
then this test is performed using object.equals(e), otherwise
using object == null. If an element equal to the given object is
found, then the remove method is called on the iterator and
true is returned, false otherwise. If the iterator does
not support removing elements, an UnsupportedOperationException
is thrown.remove in interface Collection<E>remove in interface List<E>remove in class AbstractCollection<E>object - the object to remove.true if this Collection is modified, false otherwise.ClassCastException - if the object passed is not of the correct type.NullPointerException - if object is null.public boolean removeAll(Collection<?> collection)
Collection of each object in the
specified Collection. After this method returns none of the
elements in the passed Collection can be found in this Collection
anymore.
This implementation iterates over the Collection and tests each
element e returned by the iterator, whether it is contained in
the specified Collection. If this test is positive, then the remove method is called on the iterator.
removeAll in interface Collection<E>removeAll in interface List<E>removeAll in class AbstractCollection<E>collection - the collection of objects to remove.true if this Collection is modified, false otherwise.ClassCastException - if one or more elements of collection isn't of the correct type.NullPointerException - if collection is null.public boolean deleteFirstFromRealm()
deleteFirstFromRealm in interface OrderedRealmCollection<E>true if an object was deleted, false otherwise.public boolean deleteLastFromRealm()
deleteLastFromRealm in interface OrderedRealmCollection<E>true if an object was deleted, false otherwise.public E get(int location)
get in interface List<E>get in class AbstractList<E>location - the index of the element to return.IllegalStateException - if Realm instance has been closed or parent object has been removed.IndexOutOfBoundsException - if location < 0 || location >= size().public E first()
first in interface OrderedRealmCollection<E>public E first(E defaultValue)
first in interface OrderedRealmCollection<E>public E last()
last in interface OrderedRealmCollection<E>public E last(E defaultValue)
last in interface OrderedRealmCollection<E>public RealmResults<E> sort(String fieldName)
sort in interface OrderedRealmCollection<E>fieldName - the field name to sort by. Only fields of type boolean, short, int, long, float, double, Date,
and String are supported.RealmResults will be created and returned. The original collection stays unchanged.public RealmResults<E> sort(String fieldName, Sort sortOrder)
sort in interface OrderedRealmCollection<E>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.RealmResults will be created and returned. The original collection stays unchanged.public RealmResults<E> sort(String fieldName1, Sort sortOrder1, String fieldName2, Sort sortOrder2)
sort in interface OrderedRealmCollection<E>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.RealmResults will be created and returned. The original collection stays unchanged.public RealmResults<E> sort(String[] fieldNames, Sort[] sortOrders)
sort in interface OrderedRealmCollection<E>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.RealmResults will be created and returned. The original collection stays unchanged.public void deleteFromRealm(int location)
deleteFromRealm in interface OrderedRealmCollection<E>location - the array index identifying the object to be removed.public int size()
List.size in interface Collection<E>size in interface List<E>size in class AbstractCollection<E>List.IllegalStateException - if Realm instance has been closed or parent object has been removed.public RealmQuery<E> where()
where in interface RealmCollection<E>IllegalStateException - if Realm instance has been closed or parent object has been removed.RealmQuerypublic Number min(String fieldName)
min in interface RealmCollection<E>fieldName - the field to look for a minimum on. Only number fields are supported.null as the value for the given field, null will be
returned. Otherwise the minimum value is returned. When determining the minimum value, objects with null
values are ignored.public Number max(String fieldName)
max in interface RealmCollection<E>fieldName - the field to look for a maximum on. Only number fields are supported.null as the value for the given field, null will be
returned. Otherwise the maximum value is returned. When determining the maximum value, objects with null
values are ignored.public Number sum(String fieldName)
sum in interface RealmCollection<E>fieldName - the field to sum. Only number fields are supported.null as the value for the given field, 0
will be returned. When computing the sum, objects with null values are ignored.public double average(String fieldName)
average in interface RealmCollection<E>fieldName - the field to calculate average on. Only number fields are supported.null as the value for the given field,
0 will be returned. When computing the average, objects with null values are ignored.public Date maxDate(String fieldName)
maxDate in interface RealmCollection<E>fieldName - the field to look for the maximum date. If fieldName is not of Date type, an exception is
thrown.null as the value for the given date field, null
will be returned. Otherwise the maximum date is returned. When determining the maximum date, objects with
null values are ignored.public Date minDate(String fieldName)
minDate in interface RealmCollection<E>fieldName - the field to look for the minimum date. If fieldName is not of Date type, an exception is
thrown.null as the value for the given date field, null
will be returned. Otherwise the minimum date is returned. When determining the minimum date, objects with
null values are ignored.public boolean deleteAllFromRealm()
deleteAllFromRealm in interface RealmCollection<E>true if objects was deleted, false otherwise.public boolean isLoaded()
isLoaded in interface RealmCollection<E>true if data has been loaded and is available, false if data is still being loaded.public boolean load()
load in interface RealmCollection<E>true if the data could be successfully loaded, false otherwise.public boolean contains(Object object)
true if the list contains the specified element when attached to a Realm. This
method will query the native Realm underlying storage engine to quickly find the specified element.
If the list is not attached to a Realm, the default List.contains(Object)
implementation will occur.
contains in interface RealmCollection<E>contains in interface Collection<E>contains in interface List<E>contains in class AbstractCollection<E>object - the element whose presence in this list is to be tested.true if this list contains the specified element otherwise false.public ListIterator<E> listIterator()
listIterator in interface List<E>listIterator in class AbstractList<E>public ListIterator<E> listIterator(int location)
listIterator in interface List<E>listIterator in class AbstractList<E>public OrderedRealmCollectionSnapshot<E> createSnapshot()
OrderedRealmCollection.createSnapshot in interface OrderedRealmCollection<E>OrderedRealmCollectionSnapshotpublic Realm getRealm()
Realm instance to which this collection belongs.
Calling BaseRealm.close() on the returned instance is discouraged as it is the same as
calling it on the original Realm instance which may cause the Realm to fully close invalidating the
list.
Realm instance this collection belongs to or null if the collection is unmanaged.IllegalStateException - if the Realm is an instance of DynamicRealm or the
Realm was already closed.public String toString()
toString in class AbstractCollection<E>public <any> asFlowable()
onComplete will never be called.
Items emitted from Realm Flowables are frozen (See freeze(). This means that they
are immutable and can be read on any thread.
Realm Flowables always emit items from the thread holding the live RealmList. This means that if you need to do further processing, it is recommend to observe the values on a computation scheduler:
list.asFlowable()
.observeOn(Schedulers.computation())
.map(rxResults -> doExpensiveWork(rxResults))
.observeOn(AndroidSchedulers.mainThread())
.subscribe( ... );
If you would like the asFlowable() to stop emitting items you can instruct RxJava to
only emit only the first item by using the first() operator:
list.asFlowable()
.first()
.subscribe( ... ) // You only get the results once
onNext. It will never call onComplete or OnError.UnsupportedOperationException - if the required RxJava framework is not on the classpath or the
corresponding Realm instance doesn't support RxJava.public <any> asChangesetObservable()
OrderedCollectionChangeSet will be sent. The changeset will be null the first
time an RealmList is emitted.
RealmList will continually be emitted as the RealmList is updated - onComplete will never be called.
Items emitted from Realm Observables are frozen (See freeze(). This means that they
are immutable and can be read on any thread.
Realm Observables always emit items from the thread holding the live Realm. This means that if you need to do further processing, it is recommend to observe the values on a computation scheduler:
list.asChangesetObservable()
.observeOn(Schedulers.computation())
.map((rxList, changes) -> doExpensiveWork(rxList, changes))
.observeOn(AndroidSchedulers.mainThread())
.subscribe( ... );
onNext. It will never call onComplete or OnError.UnsupportedOperationException - if the required RxJava framework is not on the classpath or the
corresponding Realm instance doesn't support RxJava.IllegalStateException - if the Realm wasn't opened on a Looper thread.public void addChangeListener(OrderedRealmCollectionChangeListener<RealmList<E>> listener)
RealmList.
Registering a change listener will not prevent the underlying RealmList from being garbage collected. If the RealmList is garbage collected, the change listener will stop being triggered. To avoid this, keep a strong reference for as long as appropriate e.g. in a class variable.
public class MyActivity extends Activity {
private RealmList<Dog> dogs; // Strong reference to keep listeners alive
\@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
dogs = realm.where(Person.class).findFirst().getDogs();
dogs.addChangeListener(new OrderedRealmCollectionChangeListener<RealmList<Dog>>() {
\@Override
public void onChange(RealmList<Dog> dogs, OrderedCollectionChangeSet changeSet) {
// React to change
}
});
}
}
listener - the change listener to be notified.IllegalArgumentException - if the change listener is null.IllegalStateException - if you try to add a listener from a non-Looper or
IntentService thread.public void removeChangeListener(OrderedRealmCollectionChangeListener<RealmList<E>> listener)
listener - the change listener to be removed.IllegalArgumentException - if the change listener is null.IllegalStateException - if you try to remove a listener from a non-Looper Thread.RealmChangeListenerpublic void addChangeListener(RealmChangeListener<RealmList<E>> listener)
RealmList.
Registering a change listener will not prevent the underlying RealmList from being garbage collected. If the RealmList is garbage collected, the change listener will stop being triggered. To avoid this, keep a strong reference for as long as appropriate e.g. in a class variable.
public class MyActivity extends Activity {
private RealmList<Dog> dogs; // Strong reference to keep listeners alive
\@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
dogs = realm.where(Person.class).findFirst().getDogs();
dogs.addChangeListener(new RealmChangeListener<RealmList<Dog>>() {
\@Override
public void onChange(RealmList<Dog> dogs) {
// React to change
}
});
}
}
listener - the change listener to be notified.IllegalArgumentException - if the change listener is null.IllegalStateException - if you try to add a listener from a non-Looper or
IntentService thread.public void removeChangeListener(RealmChangeListener<RealmList<E>> listener)
listener - the change listener to be removed.IllegalArgumentException - if the change listener is null.IllegalStateException - if you try to remove a listener from a non-Looper Thread.RealmChangeListenerpublic void removeAllChangeListeners()
IllegalStateException - if you try to remove listeners from a non-Looper Thread.RealmChangeListener