Dictionary data type (#7397)

Author: edualonso

CHANGELOG.md

@@ -11,6 +11,7 @@
 * Added support for `java.util.UUID` as supported field in model classes.
 * Added support for `java.util.UUID` as a primary key.
 * Added support for `RealmAny` as supported field in model classes. A `RealmAny` is used to represent a polymorphic Realm value or Realm Object, is indexable but cannot be used as a primary key. See [Javadoc for RealmAny](https://docs.mongodb.com/realm-sdks/java/latest/io/realm/RealmAny.html).
+* Added support for `RealmDictionary` as supported field in model classes. A `RealmDictionary` is a `Map` of strings to values - all types under the `RealmAny` umbrella can be used as values. See [Javadoc for RealmDictionary](https://docs.mongodb.com/realm-sdks/java/latest/io/realm/RealmDictionary.html) and [Javadoc for RealmMap](https://docs.mongodb.com/realm-sdks/java/latest/io/realm/RealmMap.html). `RealmDictionary` is not yet supported by any of the `Realm.insert` and `Realm.createFromJson` methods - This support will be added in a future release.
 * Allow UTF8 encoded characters in property names in string-based queries ([#4467](https://github.com/realm/realm-core/issues/4467))
 * The error message when the initial steps of opening a Realm file fails is now more descriptive.
 * Make conversion of Decimal128 to/from string work for numbers with more than 19 significant digits. ([#4548](https://github.com/realm/realm-core/issues/4548))

dependencies.list

@@ -4,7 +4,7 @@ REALM_CORE=10.3.3
 
 # Version of MongoDB Realm used by integration tests
 # See https://github.com/realm/ci/packages/147854 for available versions
-MONGODB_REALM_SERVER=2021-03-29
+MONGODB_REALM_SERVER=2021-04-19
 
 # Common Android settings across projects
 GRADLE_BUILD_TOOLS=4.0.0

realm/realm-annotations-processor/src/main/java/io/realm/processor/ClassMetaData.kt

@@ -40,6 +40,7 @@ class ClassMetaData(env: ProcessingEnvironment, typeMirrors: TypeMirrors, privat
     private val backlinks = LinkedHashSet<Backlink>()
     private val nullableFields = LinkedHashSet<RealmFieldElement>() // Set of fields which can be nullable
     private val nullableValueListFields = LinkedHashSet<RealmFieldElement>() // Set of fields whose elements can be nullable
+    private val nullableValueMapFields = LinkedHashSet<RealmFieldElement>() // Set of fields whose elements can be nullable
 
     // package name for model class.
     private lateinit var packageName: String
@@ -59,7 +60,7 @@ class ClassMetaData(env: ProcessingEnvironment, typeMirrors: TypeMirrors, privat
     lateinit var internalClassName: String
         private set
 
-    private val validPrimaryKeyTypes: List<TypeMirror> = Arrays.asList(
+    private val validPrimaryKeyTypes: List<TypeMirror> = listOf(
             typeMirrors.STRING_MIRROR,
             typeMirrors.PRIMITIVE_LONG_MIRROR,
             typeMirrors.PRIMITIVE_INT_MIRROR,
@@ -68,7 +69,7 @@ class ClassMetaData(env: ProcessingEnvironment, typeMirrors: TypeMirrors, privat
             typeMirrors.OBJECT_ID_MIRROR,
             typeMirrors.UUID_MIRROR
     )
-    private val validListValueTypes: List<TypeMirror> = Arrays.asList(
+    private val validListValueTypes: List<TypeMirror> = listOf(
             typeMirrors.STRING_MIRROR,
             typeMirrors.BINARY_MIRROR,
             typeMirrors.BOOLEAN_MIRROR,
@@ -84,6 +85,23 @@ class ClassMetaData(env: ProcessingEnvironment, typeMirrors: TypeMirrors, privat
             typeMirrors.UUID_MIRROR,
             typeMirrors.MIXED_MIRROR
     )
+    private val validDictionaryTypes: List<TypeMirror>  = listOf(
+            typeMirrors.STRING_MIRROR,
+            typeMirrors.BINARY_MIRROR,
+            typeMirrors.BINARY_NON_PRIMITIVE_MIRROR,
+            typeMirrors.BOOLEAN_MIRROR,
+            typeMirrors.LONG_MIRROR,
+            typeMirrors.INTEGER_MIRROR,
+            typeMirrors.SHORT_MIRROR,
+            typeMirrors.BYTE_MIRROR,
+            typeMirrors.DOUBLE_MIRROR,
+            typeMirrors.FLOAT_MIRROR,
+            typeMirrors.DATE_MIRROR,
+            typeMirrors.DECIMAL128_MIRROR,
+            typeMirrors.OBJECT_ID_MIRROR,
+            typeMirrors.UUID_MIRROR,
+            typeMirrors.MIXED_MIRROR
+    )
     private val stringType = typeMirrors.STRING_MIRROR
 
     private val typeUtils: Types = env.typeUtils
@@ -205,6 +223,15 @@ class ClassMetaData(env: ProcessingEnvironment, typeMirrors: TypeMirrors, privat
         return nullableValueListFields.contains(realmListVariableElement)
     }
 
+    /**
+     * Checks if the value of a `RealmDictionary` entry designated by `realmDictionaryVariableElement` is nullable.
+     *
+     * @return `true` if the element is nullable type, `false` otherwise.
+     */
+    fun isDictionaryValueNullable(realmDictionaryVariableElement: VariableElement): Boolean {
+        return nullableValueMapFields.contains(realmDictionaryVariableElement)
+    }
+
     /**
      * Checks if a VariableElement is indexed.
      *
@@ -303,6 +330,9 @@ class ClassMetaData(env: ProcessingEnvironment, typeMirrors: TypeMirrors, privat
         if (!checkCollectionTypes()) {
             return false
         }
+        if (!checkDictionaryTypes()) {
+            return false
+        }
         if (!checkReferenceTypes()) {
             return false
         }
@@ -361,44 +391,88 @@ class ClassMetaData(env: ProcessingEnvironment, typeMirrors: TypeMirrors, privat
         return true
     }
 
-    private fun checkRealmListType(field: VariableElement): Boolean {
+    private fun checkDictionaryTypes(): Boolean {
+        for (field in fields) {
+            if (Utils.isRealmDictionary(field)) {
+                if (!checkDictionaryValuesType(field)) {
+                    return false
+                }
+            }
+        }
+
+        return true
+    }
+
+    private fun checkDictionaryValuesType(field: VariableElement): Boolean {
         // Check for missing generic (default back to Object)
         if (Utils.getGenericTypeQualifiedName(field) == null) {
             Utils.error(getFieldErrorSuffix(field) + "No generic type supplied for field", field)
             return false
         }
 
-        // Check that the referenced type is a concrete class and not an interface
-        val fieldType = field.asType()
-        val elementTypeMirror = (fieldType as DeclaredType).typeArguments[0]
-        if (elementTypeMirror.kind == TypeKind.DECLARED /* class of interface*/) {
-            val elementTypeElement = (elementTypeMirror as DeclaredType).asElement() as TypeElement
-            if (elementTypeElement.superclass.kind == TypeKind.NONE) {
-                Utils.error(
-                        getFieldErrorSuffix(field) + "Only concrete Realm classes are allowed in RealmLists. "
-                                + "Neither interfaces nor abstract classes are allowed.",
-                        field)
-                return false
-            }
+        val elementTypeMirror = checkReferenceIsNotInterface(field) ?: return false
+        return checkAcceptableClass(
+                field,
+                elementTypeMirror,
+                validDictionaryTypes,
+                "Element type of RealmDictionary must be of type 'RealmAny' or any type that can be boxed inside 'RealmAny': "
+        )
+    }
+
+    private fun checkRealmListType(field: VariableElement): Boolean {
+        // Check for missing generic (default back to Object)
+        if (Utils.getGenericTypeQualifiedName(field) == null) {
+            Utils.error(getFieldErrorSuffix(field) + "No generic type supplied for field", field)
+            return false
         }
 
+        val elementTypeMirror = checkReferenceIsNotInterface(field) ?: return false
+        return checkAcceptableClass(
+                field,
+                elementTypeMirror,
+                validListValueTypes,
+                "Element type of RealmList must be a class implementing 'RealmModel' or one of "
+        )
+    }
+
+    private fun checkAcceptableClass(
+            field: VariableElement,
+            elementTypeMirror: TypeMirror,
+            validTypes: List<TypeMirror>,
+            specificFieldTypeMessage: String
+    ): Boolean {
         // Check if the actual value class is acceptable
-        if (!containsType(validListValueTypes, elementTypeMirror) && !Utils.isRealmModel(elementTypeMirror)) {
-            val messageBuilder = StringBuilder(
-                    getFieldErrorSuffix(field) + "Element type of RealmList must be a class implementing 'RealmModel' or one of ")
+        if (!containsType(validTypes, elementTypeMirror) && !Utils.isRealmModel(elementTypeMirror)) {
+            val messageBuilder = StringBuilder(getFieldErrorSuffix(field) + "Type was '$elementTypeMirror'. $specificFieldTypeMessage")
             val separator = ", "
-            for (type in validListValueTypes) {
+            for (type in validTypes) {
                 messageBuilder.append('\'').append(type.toString()).append('\'').append(separator)
             }
             messageBuilder.setLength(messageBuilder.length - separator.length)
             messageBuilder.append('.')
             Utils.error(messageBuilder.toString(), field)
             return false
         }
-
         return true
     }
 
+    private fun checkReferenceIsNotInterface(field: VariableElement): TypeMirror? {
+        // Check that the referenced type is a concrete class and not an interface
+        val fieldType = field.asType()
+        val elementTypeMirror: TypeMirror = (fieldType as DeclaredType).typeArguments[0]
+        if (elementTypeMirror.kind == TypeKind.DECLARED /* class of interface*/) {
+            val elementTypeElement = (elementTypeMirror as DeclaredType).asElement() as TypeElement
+            if (elementTypeElement.superclass.kind == TypeKind.NONE) {
+                Utils.error(
+                        getFieldErrorSuffix(field) + "Only concrete Realm classes are allowed in field '$field'. "
+                                + "Neither interfaces nor abstract classes are allowed.",
+                        field)
+                return null
+            }
+        }
+        return elementTypeMirror
+    }
+
     private fun checkRealmResultsType(field: VariableElement): Boolean {
         // Only classes implementing RealmModel are allowed since RealmResults field is used only for backlinks.
 
@@ -467,11 +541,12 @@ class ClassMetaData(env: ProcessingEnvironment, typeMirrors: TypeMirrors, privat
             if (!field.modifiers.contains(Modifier.FINAL)) {
                 continue
             }
-            if (Utils.isRealmList(field) || Utils.isMutableRealmInteger(field)) {
+            if (Utils.isRealmList(field) || Utils.isMutableRealmInteger(field) ||
+                    Utils.isRealmDictionary(field)) {
                 continue
             }
 
-            Utils.error(String.format(Locale.US, "Class \"%s\" contains illegal final field \"%s\".", simpleJavaClassName,
+            Utils.error(String.format(Locale.US, "Class \"%s\" contains illegal final/immutable field \"%s\".", simpleJavaClassName,
                     field.simpleName.toString()))
 
             return false
@@ -515,7 +590,7 @@ class ClassMetaData(env: ProcessingEnvironment, typeMirrors: TypeMirrors, privat
             }
         }
 
-        // @Required annotation of RealmList field only affects its value type, not field itself.
+        // @Required annotation of RealmList and RealmDictionary field only affects its value type, not field itself.
         if (Utils.isRealmList(field)) {
             val hasRequiredAnnotation = hasRequiredAnnotation(field)
             val listGenericType = (field.asType() as DeclaredType).typeArguments
@@ -535,6 +610,26 @@ class ClassMetaData(env: ProcessingEnvironment, typeMirrors: TypeMirrors, privat
                     nullableValueListFields.add(field)
                 }
             }
+        } else if (Utils.isRealmDictionary(field)) {
+            // Same as RealmList
+            val hasRequiredAnnotation = hasRequiredAnnotation(field)
+            val listGenericType = (field.asType() as DeclaredType).typeArguments
+            val containsRealmModelClasses = (listGenericType.isNotEmpty() && Utils.isRealmModel(listGenericType[0]))
+            val containsRealmAny = (listGenericType.isNotEmpty() && Utils.isRealmAny(listGenericType[0]))
+
+            // @Required not allowed if the dictionary contains Realm model classes
+            if (hasRequiredAnnotation && (containsRealmModelClasses || containsRealmAny)) {
+                Utils.error("@Required not allowed on RealmDictionaries that contain other Realm model classes and RealmAny.")
+                return false
+            }
+
+            // @Required thus only makes sense for RealmDictionaries with primitive types
+            // We only check @Required annotation. @org.jetbrains.annotations.NotNull annotation should not affect nullability of the list values.
+            if (!hasRequiredAnnotation) {
+                if (!containsRealmModelClasses) {
+                    nullableValueMapFields.add(field)
+                }
+            }
         } else if (isRequiredField(field)) {
             if (!checkBasicRequiredAnnotationUsage(field)) {
                 return false
@@ -570,7 +665,12 @@ class ClassMetaData(env: ProcessingEnvironment, typeMirrors: TypeMirrors, privat
 
         // Standard field that appears to be valid (more fine grained checks might fail later).
         fields.add(field)
-        if (Utils.isRealmModel(field) || Utils.isRealmModelList(field) || Utils.isRealmAnyList(field) || Utils.isRealmAny(field)) {
+        if (Utils.isRealmModel(field) ||
+                Utils.isRealmModelList(field) ||
+                Utils.isRealmAnyList(field) ||
+                Utils.isRealmAny(field) ||
+                Utils.isRealmModelDictionary(field) ||
+                Utils.isRealmAnyDictionary(field)) {
             _objectReferenceFields.add(field)
         } else {
             basicTypeFields.add(field)

realm/realm-annotations-processor/src/main/java/io/realm/processor/Constants.kt

@@ -70,6 +70,23 @@ object Constants {
             "io.realm.RealmAny" to RealmFieldType.MIXED_LIST
     )
 
+    val DICTIONARY_ELEMENT_TYPE_TO_REALM_TYPES = mapOf(
+            "java.lang.Byte" to RealmFieldType.STRING_TO_INTEGER_MAP,
+            "java.lang.Short" to RealmFieldType.STRING_TO_INTEGER_MAP,
+            "java.lang.Integer" to RealmFieldType.STRING_TO_INTEGER_MAP,
+            "java.lang.Long" to RealmFieldType.STRING_TO_INTEGER_MAP,
+            "java.lang.Float" to RealmFieldType.STRING_TO_FLOAT_MAP,
+            "java.lang.Double" to RealmFieldType.STRING_TO_DOUBLE_MAP,
+            "java.lang.Boolean" to RealmFieldType.STRING_TO_BOOLEAN_MAP,
+            "java.lang.String" to RealmFieldType.STRING_TO_STRING_MAP,
+            "java.util.Date" to RealmFieldType.STRING_TO_DATE_MAP,
+            "byte[]" to RealmFieldType.STRING_TO_BINARY_MAP,
+            "org.bson.types.Decimal128" to RealmFieldType.STRING_TO_DECIMAL128_MAP,
+            "org.bson.types.ObjectId" to RealmFieldType.STRING_TO_OBJECT_ID_MAP,
+            "java.util.UUID" to RealmFieldType.STRING_TO_UUID_MAP,
+            "io.realm.RealmAny" to RealmFieldType.STRING_TO_MIXED_MAP
+    )
+
     /**
      * Realm types and their corresponding Java types.
      *
@@ -105,7 +122,21 @@ object Constants {
         DECIMAL128_LIST("DECIMAL128_LIST", "List"),
         OBJECT_ID_LIST("OBJECT_ID_LIST", "List"),
         UUID_LIST("UUID_LIST", "List"),
-        MIXED_LIST("MIXED_LIST", "List");
+        MIXED_LIST("MIXED_LIST", "List"),
+
+        STRING_TO_LINK_MAP("STRING_TO_LINK_MAP", "Map"),
+        STRING_TO_INTEGER_MAP("STRING_TO_INTEGER_MAP", "Map"),
+        STRING_TO_BOOLEAN_MAP("STRING_TO_BOOLEAN_MAP", "Map"),
+        STRING_TO_STRING_MAP("STRING_TO_STRING_MAP", "Map"),
+        STRING_TO_BINARY_MAP("STRING_TO_BINARY_MAP", "Map"),
+        STRING_TO_DATE_MAP("STRING_TO_DATE_MAP", "Map"),
+        STRING_TO_FLOAT_MAP("STRING_TO_FLOAT_MAP", "Map"),
+        STRING_TO_DOUBLE_MAP("STRING_TO_DOUBLE_MAP", "Map"),
+        STRING_TO_DECIMAL128_MAP("STRING_TO_DECIMAL128_MAP", "Map"),
+        STRING_TO_OBJECT_ID_MAP("STRING_TO_OBJECT_ID_MAP", "Map"),
+        STRING_TO_UUID_MAP("STRING_TO_UUID_MAP", "Map"),
+        STRING_TO_MIXED_MAP("STRING_TO_MIXED_MAP", "Map");
+
 
         /**
          * The name of the enum, used in the Java bindings, used to represent the corresponding type.

realm/realm-annotations-processor/src/main/java/io/realm/processor/OsObjectBuilderTypeHelper.kt

@@ -25,11 +25,27 @@ object OsObjectBuilderTypeHelper {
 
     private val QUALIFIED_TYPE_TO_BUILDER: Map<QualifiedClassName, String>
     private val QUALIFIED_LIST_TYPE_TO_BUILDER: Map<QualifiedClassName, String>
+    private val QUALIFIED_MAP_VALUES: Map<QualifiedClassName, String> = mapOf(
+            QualifiedClassName("io.realm.RealmAny") to "RealmAnyValueDictionary",
+            QualifiedClassName("java.lang.Boolean") to "BooleanValueDictionary",
+            QualifiedClassName("java.lang.String") to "StringValueDictionary",
+            QualifiedClassName("java.lang.Integer") to "IntegerValueDictionary",
+            QualifiedClassName("java.lang.Float") to "FloatValueDictionary",
+            QualifiedClassName("java.lang.Long") to "LongValueDictionary",
+            QualifiedClassName("java.lang.Short") to "ShortValueDictionary",
+            QualifiedClassName("java.lang.Byte") to "ByteValueDictionary",
+            QualifiedClassName("java.lang.Double") to "DoubleValueDictionary",
+            QualifiedClassName("java.util.Date") to "DateValueDictionary",
+            QualifiedClassName("byte[]") to "BinaryValueDictionary",
+            QualifiedClassName("org.bson.types.ObjectId") to "ObjectIdValueDictionary",
+            QualifiedClassName("org.bson.types.Decimal128") to "Decimal128ValueDictionary",
+            QualifiedClassName("java.util.UUID") to "UUIDValueDictionary"
+    )
 
     init {
         // Map of qualified types to their OsObjectBuilder Type
         val fieldTypes = HashMap<QualifiedClassName, String>()
-        fieldTypes.apply { 
+        fieldTypes.apply {
             this[QualifiedClassName("byte")] = "Integer"
             this[QualifiedClassName("byte")] = "Integer"
             this[QualifiedClassName("short")] = "Integer"
@@ -89,6 +105,8 @@ object OsObjectBuilderTypeHelper {
             "addObjectList"
         } else if (Utils.isRealmValueList(field)) {
             "add" + getListTypeName(Utils.getRealmListType(field))
+        } else if (Utils.isRealmDictionary(field)) {
+            "add" + getDictionaryValueTypeName(Utils.getDictionaryType(field))
         } else if (Utils.isRealmResults(field)) {
             throw IllegalStateException("RealmResults are not supported by OsObjectBuilder: $field")
         } else {
@@ -112,4 +130,9 @@ object OsObjectBuilderTypeHelper {
         throw IllegalArgumentException("Unsupported list type: $type")
     }
 
+    private fun getDictionaryValueTypeName(typeName: QualifiedClassName?): String {
+        return requireNotNull(QUALIFIED_MAP_VALUES[typeName]) {
+            "Unsupported dictionary value type: '$typeName'"
+        }
+    }
 }