io.realm

Class RealmList<E extends RealmObject>

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractList<E>

io.realm.RealmList<E>

Type Parameters:

E - the class of objects in list.

All Implemented Interfaces:

java.lang.Iterable<E>, java.util.Collection<E>, java.util.List<E>

public class RealmList<E extends RealmObject>
extends java.util.AbstractList<E>

RealmList is used to model one-to-many relationships in a RealmObject. RealmList has two modes: A managed and non-managed mode. In managed mode all objects are persisted inside a Realm, in non-managed 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.

Non-managed RealmLists can be created by the user and can contain both managed and non-managed RealmObjects. This is useful when dealing with JSON deserializers like GSON or other frameworks that inject values into a class. Non-managed 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.

Constructor Summary

Constructors

Constructor and Description
RealmList() Creates a RealmList in non-managed mode, where the elements are not controlled by a Realm.
RealmList(E... objects) Creates a RealmList in non-managed mode with an initial list of elements.

Method Summary

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.
void	clear() Removes all elements from this list, leaving it empty.
boolean	contains(java.lang.Object object) Returns true if the list contains the specified element when attached to a Realm.
void	deleteAllFromRealm() Removes all elements from this list and delete them from the corresponding Realm.
E	first() Finds the first object.
E	get(int location) Returns the element at the specified location in this list.
boolean	isValid() Checks if RealmResults is still valid to use i.e.
E	last() Finds the last object.
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.
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.
java.lang.String	toString()
RealmQuery<E>	where() Returns a RealmQuery, which can be used to query for specific objects of this class.

Methods inherited from class java.util.AbstractList

addAll, equals, hashCode, indexOf, iterator, lastIndexOf, listIterator, listIterator, subList

Methods inherited from class java.util.AbstractCollection

addAll, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.List

addAll, containsAll, isEmpty, remove, removeAll, replaceAll, retainAll, sort, spliterator, toArray, toArray

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream

Methods inherited from interface java.lang.Iterable

forEach

Constructor Detail

RealmList

public RealmList()

Creates a RealmList in non-managed mode, where the elements are not controlled by a Realm. This effectively makes the RealmList function as a ArrayList and it is not possible to query the objects in this state.

Use Realm.copyToRealm(Iterable) to properly persist it's elements in Realm.

RealmList

public RealmList(E... objects)

Creates a RealmList in non-managed mode with an initial list of elements. A RealmList in non-managed mode function as a ArrayList and it is not possible to query the objects in this state. Use Realm.copyToRealm(Iterable) to properly persist all non-managed elements in Realm.

Parameters:

objects - initial objects in the list.

Method Detail

isValid

public boolean isValid()

Checks if RealmResults is still valid to use i.e. the Realm instance hasn't been closed.

Returns:

true if still valid to use, false otherwise or if it is a standalone object.

add

public void add(int location,
                E object)

Inserts the specified object into this List at the specified location. The object is inserted before any previous element at the specified location. If the location is equal to the size of this List, the object is added at the end.

1. Un-managed RealmLists: It is possible to add both managed and un-managed objects. If adding managed objects to a un-managed RealmList they will not be copied to the Realm again if using Realm.copyToRealm(RealmObject) afterwards.
2. Managed RealmLists: It is possible to add un-managed objects to a RealmList that is already managed. In that case the object will transparently be copied to Realm using Realm.copyToRealm(RealmObject) or Realm.copyToRealmOrUpdate(RealmObject) if it has a primary key.

Specified by:

add in interface java.util.List<E extends RealmObject>

Overrides:

add in class java.util.AbstractList<E extends RealmObject>

Parameters:

location - the index at which to insert.

object - the object to add.

Throws:

java.lang.IllegalStateException - if Realm instance has been closed or container object has been removed.

java.lang.IndexOutOfBoundsException - if location < 0 || location > size().

add

public boolean add(E object)

Adds the specified object at the end of this List.

1. Un-managed RealmLists: It is possible to add both managed and un-managed objects. If adding managed objects to a un-managed RealmList they will not be copied to the Realm again if using Realm.copyToRealm(RealmObject) afterwards.
2. Managed RealmLists: It is possible to add un-managed objects to a RealmList that is already managed. In that case the object will transparently be copied to Realm using Realm.copyToRealm(RealmObject) or Realm.copyToRealmOrUpdate(RealmObject) if it has a primary key.

Specified by:

add in interface java.util.Collection<E extends RealmObject>

Specified by:

add in interface java.util.List<E extends RealmObject>

Overrides:

add in class java.util.AbstractList<E extends RealmObject>

Parameters:

object - the object to add.

Returns:

always true

Throws:

java.lang.IllegalStateException - if Realm instance has been closed or parent object has been removed.

set

public E set(int location,
             E object)

Replaces the element at the specified location in this list with the specified object.

1. Un-managed RealmLists: It is possible to add both managed and un-managed objects. If adding managed objects to a un-managed RealmList they will not be copied to the Realm again if using Realm.copyToRealm(RealmObject) afterwards.
2. Managed RealmLists: It is possible to add un-managed objects to a RealmList that is already managed. In that case the object will transparently be copied to Realm using Realm.copyToRealm(RealmObject) or Realm.copyToRealmOrUpdate(RealmObject) if it has a primary key.

Specified by:

set in interface java.util.List<E extends RealmObject>

Overrides:

set in class java.util.AbstractList<E extends RealmObject>

Parameters:

location - the index at which to put the specified object.

object - the object to add.

Returns:

the previous element at the index.

Throws:

java.lang.IllegalStateException - if Realm instance has been closed or parent object has been removed.

java.lang.IndexOutOfBoundsException - if location < 0 || location >= size().

move

public void move(int oldPos,
                 int newPos)

Moves an object from one position to another, while maintaining a fixed sized list. RealmObjects will be shifted so no null values are introduced.

Parameters:

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.

Throws:

java.lang.IllegalStateException - if Realm instance has been closed or parent object has been removed.

java.lang.IndexOutOfBoundsException - if any position is outside [0, size()].

clear

public void clear()

Removes all elements from this list, leaving it empty. This method doesn't remove the objects from the Realm.

Specified by:

clear in interface java.util.Collection<E extends RealmObject>

Specified by:

clear in interface java.util.List<E extends RealmObject>

Overrides:

clear in class java.util.AbstractList<E extends RealmObject>

Throws:

java.lang.IllegalStateException - if Realm instance has been closed or parent object has been removed.

See Also:

List.isEmpty(), List.size(), deleteAllFromRealm()

remove

public E remove(int location)

Removes the object at the specified location from this list.

Specified by:

remove in interface java.util.List<E extends RealmObject>

Overrides:

remove in class java.util.AbstractList<E extends RealmObject>

Parameters:

location - the index of the object to remove.

Returns:

the removed object.

Throws:

java.lang.IllegalStateException - if Realm instance has been closed or parent object has been removed.

java.lang.IndexOutOfBoundsException - if location < 0 || location >= size().

deleteAllFromRealm

public void deleteAllFromRealm()

Removes all elements from this list and delete them from the corresponding Realm. This method can be called on a non-managed RealmList if all of the RealmObjects in the list are managed by Realm.

Throws:

java.lang.IllegalStateException - if the Realm instance has been closed, the parent object has been removed, the method is called in a wrong thread or any RealmObject in the list is not managed by Realm.

See Also:

clear()

get

public E get(int location)

Returns the element at the specified location in this list.

Specified by:

get in interface java.util.List<E extends RealmObject>

Specified by:

get in class java.util.AbstractList<E extends RealmObject>

Parameters:

location - the index of the element to return.

Returns:

the element at the specified index.

Throws:

java.lang.IllegalStateException - if Realm instance has been closed or parent object has been removed.

java.lang.IndexOutOfBoundsException - if location < 0 || location >= size().

first

public E first()

Finds the first object.

Returns:

the first object or null if the list is empty.

Throws:

java.lang.IllegalStateException - if Realm instance has been closed or parent object has been removed.

last

public E last()

Finds the last object.

Returns:

the last object or null if the list is empty.

Throws:

java.lang.IllegalStateException - if Realm instance has been closed or parent object has been removed.

size

public int size()

Returns the number of elements in this List.

Specified by:

size in interface java.util.Collection<E extends RealmObject>

Specified by:

size in interface java.util.List<E extends RealmObject>

Specified by:

size in class java.util.AbstractCollection<E extends RealmObject>

Returns:

the number of elements in this List.

Throws:

java.lang.IllegalStateException - if Realm instance has been closed or parent object has been removed.

where

public RealmQuery<E> where()

Returns a RealmQuery, which can be used to query for specific objects of this class.

Returns:

a RealmQuery object.

Throws:

java.lang.IllegalStateException - if Realm instance has been closed or parent object has been removed.

See Also:

RealmQuery

contains

public boolean contains(java.lang.Object object)

Returns 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 this list is not attached to a Realm the default List.contains(Object) implementation will occur.

Specified by:

contains in interface java.util.Collection<E extends RealmObject>

Specified by:

contains in interface java.util.List<E extends RealmObject>

Overrides:

contains in class java.util.AbstractCollection<E extends RealmObject>

Parameters:

object - the element whose presence in this list is to be tested.

Returns:

true if this list contains the specified element otherwise false.

toString

public java.lang.String toString()

Overrides:

toString in class java.util.AbstractCollection<E extends RealmObject>