Package io.realm.annotations

Enum RealmNamingPolicy

  • All Implemented Interfaces:
    Serializable, Comparable<RealmNamingPolicy>
    public enum RealmNamingPolicy
extends Enum<RealmNamingPolicy>
    This enum defines the possible ways class and field names can be mapped from what is used in Java to the name used internally in the Realm file.

    Examples where this is useful:

    • To support two model classes with the same simple name but in different packages.
    • To make it easier to work with cross platform schemas as naming conventions are different.
    • To use a Java class name that is longer than the 57 character limit enforced by Realm.
    • To change a field name in Java without forcing app users through a migration process.
    Depending on where the policy is applied, it will have slightly different semantics:
    • If applied to RealmModule.classNamingPolicy() all classes part of that module will be affected. If a class is part of multiple modules, the same naming policy must be applied to both modules, otherwise an error will be thrown.
    • If applied to RealmModule.fieldNamingPolicy() all persistable fields in all classes part of this module will be affected.
    • If applied to RealmClass.fieldNamingPolicy() all fields in that class will be affected. This will override any field naming policy specified on a module.

    An example of this: 

     
 \@RealmClass(name = "__person", fieldNamingPolicy = RealmNamingPolicy.LOWER_CASE_WITH_UNDERSCORES)
 public class Person implements RealmModel { // is converted to "__person" internally
     public string firstName; // Is converted to "first_name" internally
 }

    Choosing an internal name that differs from the name used in the Java model classes has the following implications:

    • Queries on DynamicRealm must use the internal name. Queries on normal Realm instances must continue to use the name as it is defined in the Java class.
    • Migrations must use the internal name when creating classes and fields.
    • Schema errors reported will use the internal names.

    When automatically converting Java variable names, each variable name is normalized by splitting it into a list of words that are then joined using the rules of the target format. The following heuristics are used for determining what constitutes a "word".

    1. Anytime a _ or $ is encountered. Examples are "_FirstName", "_First_Name" and "$First$Name" which all becomes "First" and "Name".
    2. Anytime you switch from a lower case character to an upper case character as identified by Character.isUpperCase(int) and Character.isLowerCase(int). Example is "FirstName" which becomes "First" and "Name".
    3. Anytime you switch from more than one uppercase character to a lower case one. The last upper case letter is assumed to be part of the next word. This is identified by using Character.isUpperCase(int) and Character.isLowerCase(int). Example is "FIRSTName" which becomes "FIRST" and "Name.
    4. Some characters like emojiis are neither uppercase nor lowercase characters, so they will be part of the current word. Examples are "my😁" and "MY😁" which are both treated as one word.
    5. Hungarian notation, i.e. variable names starting with lowercase "m" followed by uppercase letter is stripped and not considered part of any word. Example is "mFirstName" and "mFIRSTName" which becomes "First" and "Name.

    Note that changing the internal name does NOT affect importing data from JSON. The JSON data must still follow the names as defined in the Realm Java class.

    When it comes to parsing JSON using standard libraries like Moshi, GSON or Jackson it is important to keep in mind that these libraries define the transformation from JSON to Java while setting internal Realm names define the transformation from Java to the Realm file.

    This means that if you want to import data into Realm from JSON using these libraries you still need to provide the annotations from both the JSON parser library and Realm.

    Using Moshi, it would look something like this: 

     
 public class Person extends RealmObject {
     \@Json(name = "first_name") // Name used in JSON input.
     \@RealmField(name = "first_name") // Name used internally in the Realm file.
     public string firstName; // name used in Java
 }
    See Also:
    RealmModule, RealmClass, RealmField

    • Enum Constant Detail

      • NO_POLICY

        public static final RealmNamingPolicy NO_POLICY
        No policy is applied. This policy will not override any policy set on a parent element, e.g. if set in RealmClass.fieldNamingPolicy(), the module policy will still apply to field names.

        If two modules disagree on the policy and one of them is NO_POLICY, the other will be chosen without an error being thrown.

        This policy is the default.

      • IDENTITY

        public static final RealmNamingPolicy IDENTITY
        The name in the Java model class is used as is internally.

      • CAMEL_CASE

        public static final RealmNamingPolicy CAMEL_CASE
        The name in the Java model class is converted to camelCase, i.e. all words are joined together with the first letter in the first word lower cased, and the first letter of all subsequent words upper cased. This is the standard naming schema in Java, Kotlin, Swift and JavaScript.

        Examples: "firstName", "FirstName", "mFirstName", "FIRST_NAME", "First$Name" all becomes "firstName".

      • PASCAL_CASE

        public static final RealmNamingPolicy PASCAL_CASE
        The name in the Java model class is converted to PascalCase, i.e. all words are joined together with the first letter of all words upper cased. This is the default naming scheme in .NET.

        Examples: "firstName", "FirstName", "mFirstName", "FIRST_NAME", "First$Name" all becomes "FirstName".

      • LOWER_CASE_WITH_UNDERSCORES

        public static final RealmNamingPolicy LOWER_CASE_WITH_UNDERSCORES
        The name in the Java model class is converted lowercase with each word separated by _. This is the default naming scheme in C++.

        Examples: "firstName", "FirstName", "mFirstName", "FIRST_NAME", "First$Name" all becomes "first_name".

    • Method Detail

      • values

        public static RealmNamingPolicy[] values()
        Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows: 
        for (RealmNamingPolicy c : RealmNamingPolicy.values())
    System.out.println(c);
        Returns:
        an array containing the constants of this enum type, in the order they are declared

      • valueOf

        public static RealmNamingPolicy valueOf​(String name)
        Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
        Parameters:
        name - the name of the enum constant to be returned.
        Returns:
        the enum constant with the specified name
        Throws:
        IllegalArgumentException - if this enum type has no constant with the specified name
        NullPointerException - if the argument is null