Package io.realm

Class RealmObjectSchema

  • public abstract class RealmObjectSchema
extends Object
    Class for interacting with the schema for a given RealmObject class. This makes it possible to inspect, add, delete or change the fields for given class.

    If this RealmObjectSchema is retrieved from an immutable RealmSchema, this RealmObjectSchema will be immutable as well.

    See Also:
    RealmMigration

    • Method Detail

      • getClassName

        public String getClassName()
        Returns the name of the RealmObject class being represented by this schema.

        • When using a normal Realm this name is the same as the RealmObject class.
        • When using a DynamicRealm this is the name used in all API methods requiring a class name.
        Returns:
        the name of the RealmObject class represented by this schema.
        Throws:
        IllegalStateException - if this schema defintion is no longer part of the Realm.

      • addRealmListField

        public abstract RealmObjectSchema addRealmListField​(String fieldName,
                                                    Class<?> primitiveType)
        Adds a new field that references a RealmList with primitive values. See RealmObject for the list of supported types.

        Nullability of elements are defined by using the correct class e.g., Integer.class instead of int.class. Alternatively setRequired(String, boolean) can be used.

        Example: 

         
 // Defines the list of Strings as being non null.
 RealmObjectSchema schema = schema.create("Person")
     .addRealmListField("children", String.class)
     .setRequired("children", true)
        If the list contains references to other Realm classes, use addRealmListField(String, RealmObjectSchema) instead.
        Parameters:
        fieldName - name of the field to add.
        primitiveType - simple type of elements in the array.
        Returns:
        the updated schema.
        Throws:
        IllegalArgumentException - if the field name is illegal, a field with that name already exists or the element type isn't supported.
        UnsupportedOperationException - if this RealmObjectSchema is immutable.

      • addRealmDictionaryField

        public abstract RealmObjectSchema addRealmDictionaryField​(String fieldName,
                                                          Class<?> primitiveType)
        Adds a new field that references a RealmDictionary with primitive values. See RealmObject for the list of supported types.

        Nullability of elements are defined by using the correct class e.g., Integer.class instead of int.class. Alternatively setRequired(String, boolean) can be used.

        Example: 

         
 // Defines the dictionary of Strings as being non null.
 RealmObjectSchema schema = schema.create("Person")
     .addRealmDictionaryField("parentAndChild", String.class)
     .setRequired("parentAndChild", true)
        If the list contains references to other Realm classes, use addRealmDictionaryField(String, RealmObjectSchema) instead.
        Parameters:
        fieldName - name of the field to add.
        primitiveType - simple type of elements in the array.
        Returns:
        the updated schema.
        Throws:
        IllegalArgumentException - if the field name is illegal, a field with that name already exists or the element type isn't supported.
        UnsupportedOperationException - if this RealmObjectSchema is immutable.

      • addRealmSetField

        public abstract RealmObjectSchema addRealmSetField​(String fieldName,
                                                   Class<?> primitiveType)
        Adds a new field that references a RealmSet with primitive values. See RealmObject for the list of supported types.

        Nullability of elements are defined by using the correct class e.g., Integer.class instead of int.class. Alternatively setRequired(String, boolean) can be used.

        Example: 

         
 // Defines the set of Strings as being non null.
 RealmObjectSchema schema = schema.create("Person")
     .addRealmSetField("children", String.class)
     .setRequired("children", true)
        If the list contains references to other Realm classes, use addRealmSetField(String, RealmObjectSchema) instead.
        Parameters:
        fieldName - name of the field to add.
        primitiveType - simple type of elements in the array.
        Returns:
        the updated schema.
        Throws:
        IllegalArgumentException - if the field name is illegal, a field with that name already exists or the element type isn't supported.
        UnsupportedOperationException - if this RealmObjectSchema is immutable.

      • hasField

        public boolean hasField​(String fieldName)
        Tests if the class has field defined with the given name.
        Parameters:
        fieldName - field name to test.
        Returns:
        true if the field exists, false otherwise.

      • hasIndex

        public boolean hasIndex​(String fieldName)
        Checks if a given field has an index defined.
        Parameters:
        fieldName - existing field name to check.
        Returns:
        true if field is indexed, false otherwise.
        Throws:
        IllegalArgumentException - if field name doesn't exist.
        See Also:
        Index

      • addPrimaryKey

        public abstract RealmObjectSchema addPrimaryKey​(String fieldName)
        Adds a primary key to a given field. This is the same as adding the PrimaryKey annotation on the field. Further, this implicitly adds Index annotation to the field as well.
        Parameters:
        fieldName - field to set as primary key.
        Returns:
        the updated schema.
        Throws:
        IllegalArgumentException - if field name doesn't exist, the field cannot be a primary key or it already has a primary key defined.
        UnsupportedOperationException - if this RealmObjectSchema is immutable or of a synced Realm.

      • setRequired

        public abstract RealmObjectSchema setRequired​(String fieldName,
                                              boolean required)
        Sets a field to be required i.e., it is not allowed to hold null values. This is equivalent to switching between boxed types and their primitive variant e.g., Integer to int.

        If the type of designated field is a list of values (not RealmObjects , specified nullability only affects its elements, not the field itself. Value list itself is always non-nullable.

        Parameters:
        fieldName - name of field in the class.
        required - true if field should be required, false otherwise.
        Returns:
        the updated schema.
        Throws:
        IllegalArgumentException - if the field name doesn't exist, cannot have the Required annotation or the field already have been set as required.
        UnsupportedOperationException - if this RealmObjectSchema is immutable.
        See Also:
        Required

      • setNullable

        public abstract RealmObjectSchema setNullable​(String fieldName,
                                              boolean nullable)
        Sets a field to be nullable i.e., it should be able to hold null values. This is equivalent to switching between primitive types and their boxed variant e.g., int to Integer.

        If the type of designated field is a list of values (not RealmObjects , specified nullability only affects its elements, not the field itself. Value list itself is always non-nullable.

        Parameters:
        fieldName - name of field in the class.
        nullable - true if field should be nullable, false otherwise.
        Returns:
        the updated schema.
        Throws:
        IllegalArgumentException - if the field name doesn't exist, or cannot be set as nullable.
        UnsupportedOperationException - if this RealmObjectSchema is immutable.

      • isRequired

        public boolean isRequired​(String fieldName)
        Checks if a given field is required i.e., it is not allowed to contain null values.
        Parameters:
        fieldName - field to check.
        Returns:
        true if it is required, false otherwise.
        Throws:
        IllegalArgumentException - if field name doesn't exist.
        See Also:
        setRequired(String, boolean)

      • isNullable

        public boolean isNullable​(String fieldName)
        Checks if a given field is nullable i.e., it is allowed to contain null values.
        Parameters:
        fieldName - field to check.
        Returns:
        true if it is required, false otherwise.
        Throws:
        IllegalArgumentException - if field name doesn't exist.
        See Also:
        setNullable(String, boolean)

      • isPrimaryKey

        public boolean isPrimaryKey​(String fieldName)
        Checks if a given field is the primary key field.
        Parameters:
        fieldName - field to check.
        Returns:
        true if it is the primary key field, false otherwise.
        Throws:
        IllegalArgumentException - if field name doesn't exist.
        See Also:
        addPrimaryKey(String)

      • hasPrimaryKey

        public boolean hasPrimaryKey()
        Checks if the class has a primary key defined.
        Returns:
        true if a primary key is defined, false otherwise.
        See Also:
        PrimaryKey

      • getPrimaryKey

        public String getPrimaryKey()
        Returns the name of the primary key field.
        Returns:
        the name of the primary key field.
        Throws:
        IllegalStateException - if the class doesn't have a primary key defined.

      • getFieldNames

        public Set<String> getFieldNames()
        Returns all fields in this class.
        Returns:
        a list of all the fields in this class.

      • getFieldType

        public RealmFieldType getFieldType​(String fieldName)
        Returns the type used by the underlying storage engine to represent this field.
        Parameters:
        fieldName - name of the target field.
        Returns:
        the underlying type used by Realm to represent this field.

      • isEmbedded

        public boolean isEmbedded()
        Returns true if objects of this type are considered "embedded". See RealmClass.embedded() for further details.
        Returns:
        true if objects of this type are embedded. false if not.

      • setEmbedded

        public void setEmbedded​(boolean embedded)
        Converts the class to be embedded or not.

        A class can only be marked as embedded if the following invariants are satisfied:

        • The class is not allowed to have a primary key defined.
        • All existing objects of this type, must have one and exactly one parent object already pointing to it. If 0 or more than 1 object has a reference to an object about to be marked embedded an IllegalStateException will be thrown.
        Parameters:
        embedded - If @{code true}, the class type will be turned into an embedded class, and must satisfy the constraints defined above. If @{code false}, the class will be turn into a normal class. An embeded class can always be turned into a non-embedded one.
        Throws:
        IllegalStateException - if the class could not be converted because it broke some of the Embedded Objects invariants.
        See Also:
        RealmClass.embedded()

      • setEmbedded

        public void setEmbedded​(boolean embedded,
                        boolean resolveEmbeddedClassConstraints)
        Converts the class to be embedded or not, while also providing automatic handling of objects that break some of the constraints for making the class embedded.

        A class can only be marked as embedded if the following invariants are satisfied:

        • The class is not allowed to have a primary key defined.
        • All existing objects of this type, must have one and exactly one parent object already pointing to it. If 0 or more than 1 object has a reference to an object about to be marked embedded an IllegalStateException will be thrown.
        If some of these constraints are broken you can ask Realm to resolve them automatically using the @{code resolveEmbeddedClassConstraints} parameter. Setting this to @{code true} will do the following:
        • An object with 0 parents, i.e. no other objects have a reference to it, will be deleted.
        • An object with more than 1 parent, i.e. 2 or more objects have a reference to it, will be copied so each copy have exactly one parent.
        • Objects with a primary key defined will still throw an IllegalStateException and cannot be converted.
        Parameters:
        embedded - If @{code true}, the class type will be turned into an embedded class, and must satisfy the constraints defined above. If @{code false}, the class will be turn into a normal class. An embeded class can always be turned into a non-embedded one.
        resolveEmbeddedClassConstraints - whether or not to automatically fix broken constraints if @{code embedded} was set to true. See above for a full description of what that entails.
        Throws:
        IllegalStateException - if the class could not be converted because it broke some of the Embedded Objects invariants and these could not be resolved automatically.
        See Also:
        RealmClass.embedded()