E
- the class of objects in list.public final class RealmList<E extends RealmModel> 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)
method.
RealmList
can contain more elements than Integer.MAX_VALUE
.
In that case, you can access only first Integer.MAX_VALUE
elements in it.
Modifier and Type | Field and Description |
---|---|
static String |
REMOVE_OUTSIDE_TRANSACTION_ERROR |
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 object)
Inserts the specified object into this List at the specified location.
|
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. |
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.
|
E |
get(int location)
Returns the element at the specified location in this list.
|
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 . |
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, subList
addAll, containsAll, isEmpty, retainAll, toArray, toArray
addAll, addAll, containsAll, equals, hashCode, indexOf, isEmpty, lastIndexOf, replaceAll, retainAll, sort, spliterator, subList, toArray, toArray
parallelStream, removeIf, stream
public static final String REMOVE_OUTSIDE_TRANSACTION_ERROR
public RealmList()
ArrayList
and it is not possible to query
the objects in this state.
Use Realm.copyToRealm(Iterable)
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)
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 extends RealmModel>
true
if it is still valid to use or an unmanaged collection, false
otherwise.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 extends RealmModel>
true
if this is a managed RealmCollection
, false
otherwise.public void add(int location, E object)
Realm.copyToRealm(RealmModel)
afterwards.Realm.copyToRealm(RealmModel)
or Realm.copyToRealmOrUpdate(RealmModel)
if it has a primary key.add
in interface List<E extends RealmModel>
add
in class AbstractList<E extends RealmModel>
location
- the index at which to insert.object
- the object 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)
afterwards.Realm.copyToRealm(RealmModel)
or Realm.copyToRealmOrUpdate(RealmModel)
if it has a primary key.add
in interface Collection<E extends RealmModel>
add
in interface List<E extends RealmModel>
add
in class AbstractList<E extends RealmModel>
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)
afterwards.Realm.copyToRealm(RealmModel)
or
Realm.copyToRealmOrUpdate(RealmModel)
if it has a primary key.set
in interface List<E extends RealmModel>
set
in class AbstractList<E extends RealmModel>
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 extends RealmModel>
clear
in interface List<E extends RealmModel>
clear
in class AbstractList<E extends RealmModel>
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 extends RealmModel>
remove
in class AbstractList<E extends RealmModel>
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 extends RealmModel>
remove
in interface List<E extends RealmModel>
remove
in class AbstractCollection<E extends RealmModel>
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 extends RealmModel>
removeAll
in interface List<E extends RealmModel>
removeAll
in class AbstractCollection<E extends RealmModel>
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 extends RealmModel>
true
if an object was deleted, false
otherwise.public boolean deleteLastFromRealm()
deleteLastFromRealm
in interface OrderedRealmCollection<E extends RealmModel>
true
if an object was deleted, false
otherwise.public E get(int location)
get
in interface List<E extends RealmModel>
get
in class AbstractList<E extends RealmModel>
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 extends RealmModel>
public E first(E defaultValue)
first
in interface OrderedRealmCollection<E extends RealmModel>
public E last()
last
in interface OrderedRealmCollection<E extends RealmModel>
public E last(E defaultValue)
last
in interface OrderedRealmCollection<E extends RealmModel>
public RealmResults<E> sort(String fieldName)
sort
in interface OrderedRealmCollection<E extends RealmModel>
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 extends RealmModel>
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 extends RealmModel>
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 extends RealmModel>
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 extends RealmModel>
location
- the array index identifying the object to be removed.public int size()
List
.size
in interface Collection<E extends RealmModel>
size
in interface List<E extends RealmModel>
size
in class AbstractCollection<E extends RealmModel>
List
.IllegalStateException
- if Realm instance has been closed or parent object has been removed.public RealmQuery<E> where()
where
in interface RealmCollection<E extends RealmModel>
IllegalStateException
- if Realm instance has been closed or parent object has been removed.RealmQuery
public Number min(String fieldName)
min
in interface RealmCollection<E extends RealmModel>
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 extends RealmModel>
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 extends RealmModel>
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 extends RealmModel>
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 extends RealmModel>
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 extends RealmModel>
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 extends RealmModel>
true
if objects was deleted, false
otherwise.public boolean isLoaded()
isLoaded
in interface RealmCollection<E extends RealmModel>
true
if data has been loaded and is available, false
if data is still being loaded.public boolean load()
load
in interface RealmCollection<E extends RealmModel>
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 extends RealmModel>
contains
in interface Collection<E extends RealmModel>
contains
in interface List<E extends RealmModel>
contains
in class AbstractCollection<E extends RealmModel>
object
- the element whose presence in this list is to be tested.true
if this list contains the specified element otherwise false
.public Iterator<E> iterator()
iterator
in interface Iterable<E extends RealmModel>
iterator
in interface Collection<E extends RealmModel>
iterator
in interface List<E extends RealmModel>
iterator
in class AbstractList<E extends RealmModel>
public ListIterator<E> listIterator()
listIterator
in interface List<E extends RealmModel>
listIterator
in class AbstractList<E extends RealmModel>
public ListIterator<E> listIterator(int location)
listIterator
in interface List<E extends RealmModel>
listIterator
in class AbstractList<E extends RealmModel>
public String toString()
toString
in class AbstractCollection<E extends RealmModel>