Class RealmObjectSchema

Realm is now Atlas Device SDK – Learn More

io.realm

java.lang.Object

io.realm.RealmObjectSchema

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.

Tip

Nested Class Summary

Modifier and Type	Class and Description
`public static interface`	RealmObjectSchema.Function

Method Summary

Modifier and Type	Method and Description
public abstract RealmObjectSchema	addField ( String fieldName, java.lang.Class<?> fieldType, io.realm.FieldAttribute[] attributes ) Adds a new simple field to the RealmObject class.
public abstract RealmObjectSchema	addIndex ( String fieldName ) Adds an index to a given field.
public abstract RealmObjectSchema	addPrimaryKey ( String fieldName ) Adds a primary key to a given field.
public abstract RealmObjectSchema	addRealmDictionaryField ( String fieldName, java.lang.Class<?> primitiveType ) Adds a new field that references a RealmDictionary with primitive values.
public abstract RealmObjectSchema	addRealmDictionaryField ( String fieldName, RealmObjectSchema objectSchema ) Adds a new field that contains a RealmDictionary with references to other Realm model classes.
public abstract RealmObjectSchema	addRealmListField ( String fieldName, java.lang.Class<?> primitiveType ) Adds a new field that references a RealmList with primitive values.
public abstract RealmObjectSchema	addRealmListField ( String fieldName, RealmObjectSchema objectSchema ) Adds a new field that contains a RealmList with references to other Realm model classes.
public abstract RealmObjectSchema	addRealmObjectField ( String fieldName, RealmObjectSchema objectSchema ) Adds a new field that references another RealmObject .
public abstract RealmObjectSchema	addRealmSetField ( String fieldName, java.lang.Class<?> primitiveType ) Adds a new field that references a RealmSet with primitive values.
public abstract RealmObjectSchema	addRealmSetField ( String fieldName, RealmObjectSchema objectSchema ) Adds a new field that contains a RealmSet with references to other Realm model classes.
public String	getClassName () Returns the name of the RealmObject class being represented by this schema.
public Set	getFieldNames () Returns all fields in this class.
public RealmFieldType	getFieldType ( String fieldName ) Returns the type used by the underlying storage engine to represent this field.
public String	getPrimaryKey () Returns the name of the primary key field.
public boolean	hasField ( String fieldName ) Tests if the class has field defined with the given name.
public boolean	hasIndex ( String fieldName ) Checks if a given field has an index defined.
public boolean	hasPrimaryKey () Checks if the class has a primary key defined.
public boolean	isEmbedded () Returns `true` if objects of this type are considered "embedded".
public boolean	isNullable ( String fieldName ) Checks if a given field is nullable i.e., it is allowed to contain `null` values.
public boolean	isPrimaryKey ( String fieldName ) Checks if a given field is the primary key field.
public boolean	isRequired ( String fieldName ) Checks if a given field is required i.e., it is not allowed to contain `null` values.
public abstract RealmObjectSchema	removeField ( String fieldName ) Removes a field from the class.
public abstract RealmObjectSchema	removeIndex ( String fieldName ) Removes an index from a given field.
public abstract RealmObjectSchema	removePrimaryKey () Removes the primary key from this class.
public abstract RealmObjectSchema	renameField ( String currentFieldName, String newFieldName ) Renames a field from one name to another.
public abstract RealmObjectSchema	setClassName ( String className ) Sets a new name for this RealmObject class.
public void	setEmbedded ( boolean embedded ) Converts the class to be embedded or not.
public abstract RealmObjectSchema	setNullable ( String fieldName, boolean nullable ) Sets a field to be nullable i.e., it should be able to hold `null` values.
public abstract RealmObjectSchema	setRequired ( String fieldName, boolean required ) Sets a field to be required i.e., it is not allowed to hold `null` values.
public abstract RealmObjectSchema	transform ( RealmObjectSchema.Function function ) Runs a transformation function on each RealmObject instance of the current class.

Inherited Methods

Methods inherited from class java.lang.Object : getClass , hashCode , equals , clone , toString , notify , notifyAll , wait , wait , wait , finalize

Method Detail

addField

public abstract RealmObjectSchema addField ( String fieldName, java.lang.Class<?> fieldType, io.realm.FieldAttribute[] attributes )
Adds a new simple field to the RealmObject class. The type must be one supported by Realm. See RealmObject for the list of supported types. If the field should allow `null` values use the boxed type instead e.g., `Integer.class` instead of `int.class` . To add fields that reference other RealmObjects or RealmLists use addRealmObjectField(String, RealmObjectSchema) or addRealmListField(String, RealmObjectSchema) instead. Parameters `fieldName` - name of the field to add. `fieldType` - type of field to add. See RealmObject for the full list. `attributes` - set of attributes for this field. Returns the updated schema. Throws IllegalArgumentException - if the type isn't supported, field name is illegal or a field with that name already exists. UnsupportedOperationException - if this RealmObjectSchema is immutable or if adding a a field with FieldAttribute.PRIMARY_KEY attribute to a schema of a synced Realm.

public abstract RealmObjectSchema addField (

String  fieldName,
java.lang.Class<?>  fieldType,
io.realm.FieldAttribute[]  attributes

)

Adds a new simple field to the RealmObject class. The type must be one supported by Realm. See RealmObject for the list of supported types. If the field should allow null values use the boxed type instead e.g., Integer.class instead of int.class .

To add fields that reference other RealmObjects or RealmLists use addRealmObjectField(String, RealmObjectSchema) or addRealmListField(String, RealmObjectSchema) instead.

Parameters

fieldName - name of the field to add.
fieldType - type of field to add. See RealmObject for the full list.
attributes - set of attributes for this field.

Returns

the updated schema.

Throws

IllegalArgumentException - if the type isn't supported, field name is illegal or a field with that name already exists.
UnsupportedOperationException - if this RealmObjectSchema is immutable or if adding a a field with FieldAttribute.PRIMARY_KEY attribute to a schema of a synced Realm.

addIndex

public abstract RealmObjectSchema addIndex ( String fieldName )
Adds an index to a given field. This is the equivalent of adding the io.realm.annotations.Index annotation on the field. Parameters `fieldName` - field to add index to. Returns the updated schema. Throws IllegalArgumentException - if field name doesn't exist, the field cannot be indexed or it already has a index defined. UnsupportedOperationException - if this RealmObjectSchema is immutable.

public abstract RealmObjectSchema addIndex (

String fieldName

)

Adds an index to a given field. This is the equivalent of adding the io.realm.annotations.Index annotation on the field.

Parameters

fieldName - field to add index to.

Returns

the updated schema.

Throws

IllegalArgumentException - if field name doesn't exist, the field cannot be indexed or it already has a index defined.
UnsupportedOperationException - if this RealmObjectSchema is immutable.

addPrimaryKey

public abstract RealmObjectSchema addPrimaryKey ( String fieldName )
Adds a primary key to a given field. This is the same as adding the io.realm.annotations.PrimaryKey annotation on the field. Further, this implicitly adds io.realm.annotations.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.

public abstract RealmObjectSchema addPrimaryKey (

String fieldName

)

Adds a primary key to a given field. This is the same as adding the io.realm.annotations.PrimaryKey annotation on the field. Further, this implicitly adds io.realm.annotations.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.

addRealmDictionaryField

public abstract RealmObjectSchema addRealmDictionaryField (

String fieldName,

java.lang.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.

public abstract RealmObjectSchema addRealmDictionaryField ( String fieldName, RealmObjectSchema objectSchema )
Adds a new field that contains a RealmDictionary with references to other Realm model classes. If the dictionary contains primitive types, use addRealmDictionaryField(String, Class) instead. Parameters `fieldName` - name of the field to add. `objectSchema` - schema for the Realm type being referenced. Returns the updated schema. Throws IllegalArgumentException - if the field name is illegal or a field with that name already exists. UnsupportedOperationException - if this RealmObjectSchema is immutable.

public abstract RealmObjectSchema addRealmDictionaryField (

String fieldName,

RealmObjectSchema objectSchema

)

Adds a new field that contains a RealmDictionary with references to other Realm model classes.

If the dictionary contains primitive types, use addRealmDictionaryField(String, Class) instead.

Parameters

fieldName - name of the field to add.
objectSchema - schema for the Realm type being referenced.

Returns

the updated schema.

Throws

IllegalArgumentException - if the field name is illegal or a field with that name already exists.
UnsupportedOperationException - if this RealmObjectSchema is immutable.

addRealmListField

public abstract RealmObjectSchema addRealmListField (

String fieldName,

java.lang.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.

public abstract RealmObjectSchema addRealmListField ( String fieldName, RealmObjectSchema objectSchema )
Adds a new field that contains a RealmList with references to other Realm model classes. If the list contains primitive types, use addRealmListField(String, Class) instead. Parameters `fieldName` - name of the field to add. `objectSchema` - schema for the Realm type being referenced. Returns the updated schema. Throws IllegalArgumentException - if the field name is illegal or a field with that name already exists. UnsupportedOperationException - if this RealmObjectSchema is immutable.

public abstract RealmObjectSchema addRealmListField (

String fieldName,

RealmObjectSchema objectSchema

)

Adds a new field that contains a RealmList with references to other Realm model classes.

If the list contains primitive types, use addRealmListField(String, Class) instead.

Parameters

fieldName - name of the field to add.
objectSchema - schema for the Realm type being referenced.

Returns

the updated schema.

Throws

IllegalArgumentException - if the field name is illegal or a field with that name already exists.
UnsupportedOperationException - if this RealmObjectSchema is immutable.

addRealmObjectField

public abstract RealmObjectSchema addRealmObjectField ( String fieldName, RealmObjectSchema objectSchema )
Adds a new field that references another RealmObject . Parameters `fieldName` - name of the field to add. `objectSchema` - schema for the Realm type being referenced. Returns the updated schema. Throws IllegalArgumentException - if field name is illegal or a field with that name already exists. UnsupportedOperationException - if this RealmObjectSchema is immutable.

addRealmSetField

public abstract RealmObjectSchema addRealmSetField (

String fieldName,

java.lang.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.

public abstract RealmObjectSchema addRealmSetField ( String fieldName, RealmObjectSchema objectSchema )
Adds a new field that contains a RealmSet with references to other Realm model classes. If the set contains primitive types, use addRealmSetField(String, Class) instead. Parameters `fieldName` - name of the field to add. `objectSchema` - schema for the Realm type being referenced. Returns the updated schema. Throws IllegalArgumentException - if the field name is illegal or a field with that name already exists. UnsupportedOperationException - if this RealmObjectSchema is immutable.

public abstract RealmObjectSchema addRealmSetField (

String fieldName,

RealmObjectSchema objectSchema

)

Adds a new field that contains a RealmSet with references to other Realm model classes.

If the set contains primitive types, use addRealmSetField(String, Class) instead.

Parameters

fieldName - name of the field to add.
objectSchema - schema for the Realm type being referenced.

Returns

the updated schema.

Throws

IllegalArgumentException - if the field name is illegal or a field with that name already exists.
UnsupportedOperationException - if this RealmObjectSchema is immutable.

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.

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.

getFieldNames

public Set 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.

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.

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. Tip See also: io.realm.annotations.Index

hasPrimaryKey

public boolean hasPrimaryKey ()
Checks if the class has a primary key defined. Returns `true` if a primary key is defined, `false` otherwise. Tip See also: io.realm.annotations.PrimaryKey

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.

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. Tip 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. Tip See also: addPrimaryKey(String)

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. Tip See also: setRequired(String, boolean)

removeField

public abstract RealmObjectSchema removeField ( String fieldName )
Removes a field from the class. Parameters `fieldName` - field name to remove. Returns the updated schema. Throws IllegalArgumentException - if field name doesn't exist. UnsupportedOperationException - if this RealmObjectSchema is immutable or for a synced Realm.

removeIndex

public abstract RealmObjectSchema removeIndex ( String fieldName )
Removes an index from a given field. This is the same as removing the `@Index` annotation on the field. Parameters `fieldName` - field to remove index from. Returns the updated schema. Throws IllegalArgumentException - if field name doesn't exist or the field doesn't have an index. UnsupportedOperationException - if this RealmObjectSchema is immutable or of a synced Realm.

removePrimaryKey

public abstract RealmObjectSchema removePrimaryKey ()
Removes the primary key from this class. This is the same as removing the io.realm.annotations.PrimaryKey annotation from the class. Further, this implicitly removes io.realm.annotations.Index annotation from the field as well. Returns the updated schema. Throws IllegalArgumentException - if the class doesn't have a primary key defined. UnsupportedOperationException - if this RealmObjectSchema is immutable or of a synced Realm.

public abstract RealmObjectSchema removePrimaryKey ()

Removes the primary key from this class. This is the same as removing the io.realm.annotations.PrimaryKey annotation from the class. Further, this implicitly removes io.realm.annotations.Index annotation from the field as well.

Returns

the updated schema.

Throws

IllegalArgumentException - if the class doesn't have a primary key defined.
UnsupportedOperationException - if this RealmObjectSchema is immutable or of a synced Realm.

renameField

public abstract RealmObjectSchema renameField ( String currentFieldName, String newFieldName )
Renames a field from one name to another. Parameters `currentFieldName` - field name to rename. `newFieldName` - the new field name. Returns the updated schema. Throws IllegalArgumentException - if field name doesn't exist or if the new field name already exists. UnsupportedOperationException - if this RealmObjectSchema is immutable or for a synced Realm.

setClassName

public abstract RealmObjectSchema setClassName ( String className )
Sets a new name for this RealmObject class. This is equivalent to renaming it. Parameters `className` - the new name for this class. Throws IllegalArgumentException - if className is `null` or an empty string, or its length exceeds 56 characters. UnsupportedOperationException - if this RealmObjectSchema is immutable or from a synced Realm. Tip See also: RealmSchema.rename(String, String)

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. Throws IllegalStateException - if the class could not be converted because it broke some of the Embedded Objects invariants. Tip See also: RealmClass.embedded()

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.

Throws

IllegalStateException - if the class could not be converted because it broke some of the Embedded Objects invariants.

Tip

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 RealmObject s , 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.

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 RealmObject s , 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.

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 RealmObject s , 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. Tip See also: Required

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 RealmObject s , 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.

Tip

transform

public abstract RealmObjectSchema transform ( RealmObjectSchema.Function function )
Runs a transformation function on each RealmObject instance of the current class. The object will be represented as a DynamicRealmObject . There is no guarantees in which order the objects are returned. Parameters `function` - transformation function. Returns this schema. Throws UnsupportedOperationException - if this RealmObjectSchema is immutable.

←

→

Class RealmObjectSchema.leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-1l4s55v{margin-top:-175px;position:absolute;padding-bottom:2px;}

io.realm

Tip

See also:

Nested Class Summary

Method Summary

Inherited Methods

Method Detail

addField

addIndex

addPrimaryKey

addRealmDictionaryField

addRealmListField

addRealmObjectField

addRealmSetField

getClassName

getFieldNames

getFieldType

getPrimaryKey

hasField

hasIndex

Tip

See also:

hasPrimaryKey

Tip

See also:

isEmbedded

isNullable

Tip

See also:

isPrimaryKey

Tip

See also:

isRequired

Tip

See also:

removeField

removeIndex

removePrimaryKey

renameField

setClassName

Tip

See also:

setEmbedded

Tip

See also:

setNullable

setRequired

Tip

See also:

transform

Class RealmObjectSchema