Package io.realm

Class RealmAny

  • public class RealmAny
extends Object
    RealmAny is used to represent a polymorphic Realm value.

    At any particular moment an instance of this class stores a definite value of a definite type. If, for instance, that is an double value, you may call asDouble() to extract that value. You may call getType() to discover what type of value is currently stored. Calling asDouble() on an instance that does not store an double would raise a ClassCastException.

    RealmAny behaves like a value type on all the supported types except on Realm objects. It means that Realm will not persist any change to the RealmAny value except when the type is Realm object. When a RealmAny holds a Realm object, it just holds the reference to it, not a copy of the object. So modifications to the Realm object are reflected in the RealmAny value, including if the object is deleted. Because RealmAny instances are immutable, a new instance is needed to update a RealmAny attribute. 

     
      anObject.realmAnyAttribute = RealmAny.valueOf(5);
      anObject.realmAnyAttribute = RealmAny.valueOf(10.f);
    It is crucial to understand that the act of extracting a value of a particular type requires definite knowledge about the stored type. Calling a getter method for any particular type, that is not the same type as the stored value, would raise an exception.

    Our recommendation to handle the RealmAny polymorphism is to write a switch case around the RealmAny type and its inner value class. 

     
      RealmAny realmAny = aRealmObject.realmAnyAttribute;

      switch (realmAny.getType()) {
          case OBJECT:
              if (realmAny.getValueClass().equals(DogRealmModel.class)) {
                  DogRealmModel value = realmAny.asRealmModel(DogRealmModel.class);
              }
          case INTEGER:
              performAction(realmAny.asInteger());
              break;
          case BOOLEAN:
              performAction(realmAny.asBoolean());
              break;
          case STRING:
              performAction(realmAny.asString());
              break;
          case BINARY:
              performAction(realmAny.asBinary());
              break;
          case DATE:
              performAction(realmAny.asDate());
              break;
          case FLOAT:
              performAction(realmAny.asFloat());
              break;
          case DOUBLE:
              performAction(realmAny.asDouble());
              break;
          case DECIMAL128:
              performAction(realmAny.asDecimal128());
              break;
          case OBJECT_ID:
              performAction(realmAny.asObjectId());
              break;
          case UUID:
              performAction(realmAny.asUUID());
              break;
          case NULL:
              performNullAction();
              break;
      }

    getValueClass() returns the Java class that represents the inner value wrapped by the RealmAny instance. If the resulting class is a realization of RealmModel asRealmModel() can be called to cast the RealmAny value to a Realm object reference.

    RealmAny values can also be sorted. The sorting order used between different RealmAny types, from lowest to highest, is:

    1. Boolean
    2. Byte/Short/Integer/Long/Float/Double/Decimal128
    3. byte[]/String
    4. Date
    5. ObjectId
    6. UUID
    7. RealmObject
    This has implications on how RealmQuery.sort(String), RealmQuery.minRealmAny(String) and RealmQuery.maxRealmAny(String) work. Especially min() and max() will not only take numeric fields into account, but will use the sorting order to determine the "largest" or "lowest" value.

    • Method Detail

      • getType

        public RealmAny.Type getType()
        Gets the inner type of this RealmAny object.
        Returns:
        the inner RealmAny.Type

      • getValueClass

        @Nullable
public Class<?> getValueClass()
        Returns the Java class that represents the inner value wrapped by this RealmAny value.
        Returns:
        the class that represents the inner value wrapped by this RealmAny value.

      • valueOf

        public static RealmAny valueOf​(@Nullable
                               Byte value)
        Creates a new RealmAny with the specified value. If the value is not null the type will be RealmAny.Type.INTEGER, RealmAny.Type.NULL otherwise.
        Parameters:
        value - the RealmAny value.
        Returns:
        a new RealmAny containing a Byte value.

      • valueOf

        public static RealmAny valueOf​(@Nullable
                               byte[] value)
        Creates a new RealmAny with the specified value. If the value is not null the type will be RealmAny.Type.BINARY, RealmAny.Type.NULL otherwise.
        Parameters:
        value - the RealmAny value.
        Returns:
        a new RealmAny of a byte[].

      • valueOf

        public static RealmAny valueOf​(@Nullable
                               UUID value)
        Creates a new RealmAny with the specified value. If the value is not null the type will be RealmAny.Type.UUID, RealmAny.Type.NULL otherwise.
        Parameters:
        value - the RealmAny value.
        Returns:
        a new RealmAny of an UUID.

      • nullValue

        public static RealmAny nullValue()
        Creates a new RealmAny of a null value.
        Returns:
        a new RealmAny instance of a null value.

      • valueOf

        public static RealmAny valueOf​(@Nullable
                               RealmModel value)
        Creates a new RealmAny with the specified value.
        Parameters:
        value - the RealmAny value.
        Returns:
        a new RealmAny of a RealmModel.

      • isNull

        public boolean isNull()
        Returns true if the inner value is null, false otherwise.
        Returns:
        true if the inner value is null, false otherwise.

      • asByte

        public Byte asByte()
        Gets this value as a Byte if it is one, otherwise throws exception.
        Returns:
        a Byte.
        Throws:
        ClassCastException - if this value is not of the expected type.

      • asShort

        public Short asShort()
        Gets this value as a Short if it is one, otherwise throws exception.
        Returns:
        a Short.
        Throws:
        ClassCastException - if this value is not of the expected type.

      • asInteger

        public Integer asInteger()
        Gets this value as a Integer if it is one, otherwise throws exception.
        Returns:
        an Integer.
        Throws:
        ClassCastException - if this value is not of the expected type.

      • asLong

        public Long asLong()
        Gets this value as a Long if it is one, otherwise throws exception.
        Returns:
        a Long.
        Throws:
        ClassCastException - if this value is not of the expected type.

      • asBoolean

        public Boolean asBoolean()
        Gets this value as a Boolean if it is one, otherwise throws exception.
        Returns:
        a Boolean.
        Throws:
        ClassCastException - if this value is not of the expected type.

      • asFloat

        public Float asFloat()
        Gets this value as a Float if it is one, otherwise throws exception.
        Returns:
        a Float.
        Throws:
        ClassCastException - if this value is not of the expected type.

      • asDouble

        public Double asDouble()
        Gets this value as a Double if it is one, otherwise throws exception.
        Returns:
        a Double.
        Throws:
        ClassCastException - if this value is not of the expected type.

      • asString

        public String asString()
        Gets this value as a String if it is one, otherwise throws exception.
        Returns:
        a String.
        Throws:
        ClassCastException - if this value is not of the expected type.

      • asBinary

        public byte[] asBinary()
        Gets this value as a byte[] if it is one, otherwise throws exception.
        Returns:
        a byte[].
        Throws:
        ClassCastException - if this value is not of the expected type.

      • asDate

        public Date asDate()
        Gets this value as a Date if it is one, otherwise throws exception.
        Returns:
        a Date.
        Throws:
        ClassCastException - if this value is not of the expected type.

      • asObjectId

        public ObjectId asObjectId()
        Gets this value as a ObjectId if it is one, otherwise throws exception.
        Returns:
        an ObjectId.
        Throws:
        ClassCastException - if this value is not of the expected type.

      • asUUID

        public UUID asUUID()
        Gets this value as a UUID if it is one, otherwise throws exception.
        Returns:
        an UUID.
        Throws:
        ClassCastException - if this value is not of the expected type.

      • asDecimal128

        public Decimal128 asDecimal128()
        Gets this value as a Decimal128 if it is one, otherwise throws exception.
        Returns:
        a Decimal128.
        Throws:
        ClassCastException - if this value is not of the expected type.

      • asRealmModel

        public <T extends RealmModel> T asRealmModel​(Class<T> clazz)
        Gets this value as a RealmModel if it is one, otherwise throws exception.
        Type Parameters:
        T - the RealmModel type to cast the inner value to.
        Returns:
        a RealmModel of the T type.
        Throws:
        ClassCastException - if this value is not of the expected type.

      • hashCode

        public final int hashCode()
        A RealmAny'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
        Throws:
        NullPointerException - if the inner value is null

      • equals

        public final boolean equals​(@Nullable
                            Object other)
        Two RealmAnys are .equals if and only if their contents are equal.
        Overrides:
        equals in class Object
        Parameters:
        other - compare target
        Returns:
        true if the target has the same value