Fix tests and docs around RealmAny sorting (#7477)

Author: cmelchior

CHANGELOG.md

@@ -1,3 +1,23 @@
+## 10.6.0-BETA.2 (2021-05-17)
+
+### Breaking Changes
+* None.
+
+### Enhancements
+* None.
+
+### Fixed
+* Removed wrong `@Nullable` annotation on `RealmQuery.maxRealmAny()`.
+
+### Compatibility
+* File format: Generates Realms with format v21. Unsynced Realms will be upgraded from Realm Java 2.0 and later. Synced Realms can only be read and upgraded if created with Realm Java v10.0.0-BETA.1.
+* APIs are backwards compatible with all previous release of realm-java in the 10.6.y series.
+* Realm Studio 11.0.0-alpha.0 or above is required to open Realms created by this version.
+
+### Internal
+* None.
+
+
 ## 10.6.0-BETA.1 (2021-05-17)
 
 ### Breaking Changes

realm/realm-library/src/androidTest/kotlin/io/realm/realmany/RealmAnyQueryTests.kt

@@ -147,8 +147,8 @@ class RealmAnyQueryTests {
     @Test
     fun max() {
         initializeTestData()
-        val value = realm.where<RealmAnyNotIndexed>().maxRealmAny(RealmAnyNotIndexed.FIELD_REALM_ANY)
-        assertEquals(RealmAny.valueOf(UUID.fromString("00000004-aa12-4afa-9219-e20cc3018599")), value)
+        val value = realm.where<RealmAnyNotIndexed>().maxRealmAny(RealmAnyNotIndexed.FIELD_REALM_ANY)!!
+        assertEquals("item 2", value.asRealmModel(PrimaryKeyAsString::class.java).name)
     }
 
     @Test
@@ -157,7 +157,7 @@ class RealmAnyQueryTests {
         val results = realm.where<RealmAnyNotIndexed>().sort(RealmAnyNotIndexed.FIELD_REALM_ANY).findAll()
         assertEquals(112, results.size)
         assertTrue(results.first()!!.realmAny!!.isNull)
-        assertEquals(RealmAny.Type.UUID, results.last()!!.realmAny!!.type)
+        assertEquals(RealmAny.Type.OBJECT, results.last()!!.realmAny!!.type)
     }
 
     @Test

realm/realm-library/src/main/java/io/realm/RealmAny.java

@@ -111,6 +111,23 @@
  * value wrapped by the RealmAny instance. If the resulting class is
  * a realization of {@link io.realm.RealmModel} asRealmModel() can be
  * called to cast the RealmAny value to a Realm object reference.
+ * <p>
+ * RealmAny values can also be sorted. The sorting order used between
+ * different RealmAny types, from lowest to highest, is:
+ * <ol>
+ *     <li>Boolean</li>
+ *     <li>Byte/Short/Integer/Long/Float/Double/Decimal128</li>
+ *     <li>byte[]/String</li>
+ *     <li>Date</li>
+ *     <li>ObjectId</li>
+ *     <li>UUID</li>
+ *     <li>RealmObject</li>
+ * </ol>
+ * This has implications on how {@link RealmQuery#sort(String)},
+ * {@link RealmQuery#minRealmAny(String)} and {@link RealmQuery#maxRealmAny(String)}
+ * work. Especially {@code min()} and {@code max()} will not only take
+ * numeric fields into account, but will use the sorting order to determine
+ * the "largest" or "lowest" value.
  */
 public class RealmAny {
     @Nonnull

realm/realm-library/src/main/java/io/realm/RealmQuery.java

@@ -2193,9 +2193,11 @@ public RealmQuery<E> containsEntry(String fieldName, Map.Entry<String, ?> entry)
      * Calculates the sum of a given field.
      *
      * @param fieldName the field to sum. Only number and RealmAny fields are supported.
-     * @return the sum of fields of the matching objects. If no objects exist or they all have {@code null} as the value
-     * for the given field, {@code 0} will be returned. When computing the sum, objects with {@code null} values
-     * are ignored. When applied to a RealmAny field, the returning type will be {@code Decimal128}.
+     * @return the sum of fields of the matching objects. If no objects exist or they all have
+     * {@code null} as the value for the given field, {@code 0} will be returned. When computing the
+     * sum, objects with {@code null} values are ignored. When applied to a RealmAny field, only
+     * numeric values will be summed up (Byte/Integer/Integer/Long/Float/Double/Decimal128) and the
+     * returning type will be {@code Decimal128}.
      * @throws java.lang.IllegalArgumentException if the field is not a number type.
      * @throws RealmException                     if called from the UI thread after opting out via {@link RealmConfiguration.Builder#allowQueriesOnUiThread(boolean)}.
      */
@@ -2339,12 +2341,12 @@ public Date minimumDate(String fieldName) {
     }
 
     /**
-     * Finds the minimum value of a field.
+     * Finds the minimum value of a {@link RealmAny} field.
      *
-     * @param fieldName the field name
-     * @return if no objects exist or they all have {@code null} as the value for the given RealmAny field, {@code null}
+     * @param fieldName the field containing a RealmAny value.
+     * @return if no objects exist or they all have {@code null} as the value for the given RealmAny field, {@link RealmAny.Type#NULL}
      * will be returned. Otherwise the minimum RealmAny is returned. When determining the minimum RealmAny, objects with
-     * {@code null} values are ignored.
+     * {@code null} values are ignored. See the {@link RealmAny} documentation for more details on how RealmAny values are compared.
      * @throws java.lang.UnsupportedOperationException if the query is not valid ("syntax error").
      * @throws RealmException                          if called from the UI thread after opting out via {@link RealmConfiguration.Builder#allowQueriesOnUiThread(boolean)}.
      */
@@ -2406,15 +2408,14 @@ public Date maximumDate(String fieldName) {
     }
 
     /**
-     * Finds the maximum value of a field.
+     * Finds the maximum value of a {@link RealmAny} field.
      *
-     * @param fieldName the field name.
-     * @return if no objects exist or they all have {@code null} as the value for the given RealmAny field, {@code null}
+     * @param fieldName the field containing a RealmAny value.
+     * @return if no objects exist or they all have {@code null} as the value for the given RealmAny field, {@link RealmAny.Type#NULL}
      * will be returned. Otherwise the maximum RealmAny is returned. When determining the maximum RealmAny, objects with
-     * {@code null} values are ignored.
+     * {@code null} values are ignored. See the {@link RealmAny} documentation for more details on how RealmAny values are compared.
      * @throws java.lang.UnsupportedOperationException if the query is not valid ("syntax error").
      */
-    @Nullable
     public RealmAny maxRealmAny(String fieldName) {
         realm.checkIfValid();
         realm.checkAllowQueriesOnUiThread();