Package io.realm

Class RealmMap<K,​V>

  • Type Parameters:
    K - the type of the keys stored in this map
    V - the type of the values stored in this map
    All Implemented Interfaces:
    io.realm.internal.Freezable<RealmMap<K,​V>>, io.realm.internal.ManageableObject, Map<K,​V>
    Direct Known Subclasses:
    RealmDictionary
    public abstract class RealmMap<K,​V>
extends Object
implements Map<K,​V>, io.realm.internal.ManageableObject, io.realm.internal.Freezable<RealmMap<K,​V>>
    RealmMap is used to map keys to values. A RealmMap cannot contain duplicate keys and each key can map to at most one value. A RealmMap cannot have null keys but can have null values.

    Similarly to RealmLists, a RealmDictionary can operate in managed and unmanaged modes. In managed mode a RealmDictionary persists all its contents inside a Realm whereas in unmanaged mode it functions like a HashMap.

    Managed RealmDictionaries can only be created by Realm and will automatically update its content whenever the underlying Realm is updated. Managed RealmDictionaries can only be accessed using the getter that points to a RealmDictionary field of a RealmObject.

    Unmanaged RealmDictionaries 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 RealmMaps can be added to a Realm using the Realm.copyToRealm(Iterable, ImportFlag...) method.

    • Method Detail

      • isManaged

        public boolean isManaged()
        Specified by:
        isManaged in interface io.realm.internal.ManageableObject

      • isValid

        public boolean isValid()
        Specified by:
        isValid in interface io.realm.internal.ManageableObject

      • isFrozen

        public boolean isFrozen()
        Specified by:
        isFrozen in interface io.realm.internal.ManageableObject

      • size

        public int size()
        Specified by:
        size in interface Map<K,​V>

      • isEmpty

        public boolean isEmpty()
        Specified by:
        isEmpty in interface Map<K,​V>

      • get

        public V get​(Object key)
        Specified by:
        get in interface Map<K,​V>

      • remove

        public V remove​(Object key)
        Specified by:
        remove in interface Map<K,​V>

      • putAll

        public void putAll​(Map<? extends K,​? extends V> m)
        Specified by:
        putAll in interface Map<K,​V>

      • clear

        public void clear()
        Specified by:
        clear in interface Map<K,​V>

      • keySet

        public Set<K> keySet()
        Specified by:
        keySet in interface Map<K,​V>

      • freeze

        public RealmMap<K,​V> freeze()
        Specified by:
        freeze in interface io.realm.internal.Freezable<K>

      • addChangeListener

        public void addChangeListener​(MapChangeListener<K,​V> listener)
        Adds a change listener to this RealmMap.

        Registering a change listener will not prevent the underlying RealmMap from being garbage collected. If the RealmMap 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 RealmMap<String, 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 MapChangeListener<String, Dog>() {
           \@Override
           public void onChange(RealmMap<String, Dog> map, MapChangeSet<String> changeSet) {
               // React to change
           }
       });
     }
 }
        Parameters:
        listener - the change listener to be notified.
        Throws:
        IllegalArgumentException - if the change listener is null.
        IllegalStateException - if you try to add a listener from a non-Looper or IntentService thread.

      • addChangeListener

        public void addChangeListener​(RealmChangeListener<RealmMap<K,​V>> listener)
        Adds a change listener to this RealmMap.

        Registering a change listener will not prevent the underlying RealmMap from being garbage collected. If the RealmMap 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 RealmMap<String, 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<RealmMap<String, Dog>>() {
           \@Override
           public void onChange(RealmMap<String, Dog> map) {
               // React to change
           }
       });
     }
 }
        Parameters:
        listener - the change listener to be notified.
        Throws:
        IllegalArgumentException - if the change listener is null.
        IllegalStateException - if you try to add a listener from a non-Looper or IntentService thread.
        See Also:
        RealmChangeListener

      • removeChangeListener

        public void removeChangeListener​(MapChangeListener<K,​V> listener)
        Removes the specified change listener.
        Parameters:
        listener - the change listener to be removed.
        Throws:
        IllegalArgumentException - if the change listener is null.
        IllegalStateException - if you try to remove a listener from a non-Looper Thread.

      • removeAllChangeListeners

        public void removeAllChangeListeners()
        Removes all user-defined change listeners.
        Throws:
        IllegalStateException - if you try to remove listeners from a non-Looper Thread.
        See Also:
        RealmChangeListener