Package io.realm

Class MutableRealmInteger

  • All Implemented Interfaces:
    io.realm.internal.ManageableObject, Comparable<MutableRealmInteger>

    public abstract class MutableRealmInteger
    extends Object
    implements Comparable<MutableRealmInteger>, io.realm.internal.ManageableObject
    A MutableRealmInteger is a mutable, Long-like numeric quantity. It behaves almost exactly as a reference to a Long. More specifically:

    MutableRealmIntegers are most interesting as members of a managed RealmModel object. When managed, the increment(long) and decrement(long) operators implement a conflict free replicated data type: Simultaneous increments and decrements from multiple distributed clients will be aggregated correctly. For instance, if the value of counter field for the object representing user "Fred" is currently 0, then the following code, executed on two different devices, simultaneously, even if connected by only a slow, unreliable network, will always cause the value of counter to converge, eventually on the value 2.

      MutableRealmInteger counter = realm.where(Users.class)
         .equalTo("name", Fred)
         .findFirst()
         .counter.increment(1);
     
    Note that the set(Long) operator must be used with extreme care. It will quash the effects of any prior calls to increment(long) or decrement(long). Although the value of a MutableRealmInteger will always converge across devices, the specific value on which it converges will depend on the actual order in which operations took place. Mixing set(Long) with increment(long) and decrement(long) is, therefore, not advised, unless fuzzy counting is acceptable.

    MutableRealmIntegers may not be primary keys. Their implementations are not thread safe. Like all managed Realm objects, managed MutableRealmIntegers may not be moved across threads. Unmanaged MutableRealmIntegers may be moved across threads but require safe publication.

    A MutableRealmInteger, in a model class, must always be declared final. For instance:

     public final MutableRealmInteger counter = MutableRealmInteger.ofNull(); 
     
    Although initializing the MutableRealmInteger as null may work very limited circumstances, developers are advised not to do it:
     
      public final MutableRealmInteger counter = null; // DO NOT DO THIS! 
     
    Also note that when a MutableRealmInteger is @Required, it is better, though not required, to initialize it with a non-null value.
     
     @Required
      public final MutableRealmInteger counter = MutableRealmInteger.valueOf(0L);
     

    A reference to a managed MutableRealmInteger is subject to all of the constraints that apply to the model object from which it was obtained: It can only be mutated within a transaction and it becomes invalid if the Realm backing it is closed. Use the isManaged() and isValid() operators to determine whether a MutableRealmInteger is in a consistent state. Note, in particular, that a reference to a managed MutableRealmInteger retains a reference to the model object to which it belongs. For example in this code:

     MutableRealmInteger counter = realm.where(Users.class).findFirst().counter; 
     
    the counter holds a reference to the User model object from which it was obtained. Neither can be GCed until all references to both are unreachable.
    • Method Detail

      • valueOf

        public static MutableRealmInteger valueOf​(Long value)
        Creates a new, unmanaged MutableRealmInteger with the specified initial value.
        Parameters:
        value - initial value.
      • ofNull

        public static MutableRealmInteger ofNull()
        Creates a new, unmanaged MutableRealmInteger whose value is null.
      • valueOf

        public static MutableRealmInteger valueOf​(long value)
        Creates a new, unmanaged MutableRealmInteger with the specified initial value.
        Parameters:
        value - initial value.
      • get

        @Nullable
        public abstract Long get()
        Gets the MutableRealmInteger value. The value may be null.
        Returns:
        the value.
      • set

        public abstract void set​(@Nullable
                                 Long newValue)
        Sets the MutableRealmInteger value. Calling set forcibly sets the MutableRealmInteger to the provided value. Doing this obliterates the effects of any calls to increment(long) and decrement(long) perceived before the call to set.
        Parameters:
        newValue - new value.
      • set

        public final void set​(long newValue)
        Sets the MutableRealmInteger value. Calling set(java.lang.Long) forcibly sets the MutableRealmInteger to the provided value. Doing this obliterates the effects of any calls to increment(long) and decrement(long) perceived before the call to set(java.lang.Long).
        Parameters:
        newValue - new value.
      • increment

        public abstract void increment​(long inc)
        Increments the MutableRealmInteger, adding the value of the argument. Increment/decrement from all devices are reflected in the new value, which is guaranteed to converge.
        Parameters:
        inc - quantity to be added to the MutableRealmInteger.
      • decrement

        public abstract void decrement​(long dec)
        Decrements the MutableRealmInteger, subtracting the value of the argument. Increment/decrement from all devices are reflected in the new value, which is guaranteed to converge.
        Parameters:
        dec - quantity to be subtracted from the MutableRealmInteger.
      • isNull

        public final boolean isNull()
        Returns:
        true if and only if get() will return null.
      • compareTo

        public final int compareTo​(MutableRealmInteger o)
        MutableRealmIntegers compare strictly by their values. Null is a legal value for a MutableRealmInteger and null < any non-null value
        Specified by:
        compareTo in interface Comparable<MutableRealmInteger>
        Parameters:
        o - the compare target
        Returns:
        -1, 0, or 1, depending on whether this object's value is <, =, or > the target's.
      • hashCode

        public final int hashCode()
        A MutableRealmInteger's hash code is, exactly, the hash code of its value.
        Overrides:
        hashCode in class Object
        Returns:
        true if the target has the same value.
      • equals

        public final boolean equals​(Object o)
        Two MutableRealmIntegers are .equals if and only if their longValues are equal.
        Overrides:
        equals in class Object
        Parameters:
        o - compare target
        Returns:
        true if the target has the same value.