Add DocumentId annotation, mark planned interface changes and call site updates. (#456)

This change adds a DocumentId annotation class, under util/ for now, that can be used to automatically populate document id values into user defined custom objects.

The actual implementation of the population will be in a subsequent PR.

Author: Hui-Wu

firebase-firestore/src/main/java/com/google/firebase/firestore/DocumentSnapshot.java

@@ -200,7 +200,9 @@ public <T> T toObject(
     checkNotNull(
         serverTimestampBehavior, "Provided serverTimestampBehavior value must not be null.");
     Map<String, Object> data = getData(serverTimestampBehavior);
-    return data == null ? null : CustomClassMapper.convertToCustomClass(data, valueType);
+    return data == null
+        ? null
+        : CustomClassMapper.convertToCustomClass(data, valueType, getReference());
   }
 
   /**
@@ -353,7 +355,9 @@ public <T> T get(
       @NonNull Class<T> valueType,
       @NonNull ServerTimestampBehavior serverTimestampBehavior) {
     Object data = get(fieldPath, serverTimestampBehavior);
-    return data == null ? null : CustomClassMapper.convertToCustomClass(data, valueType);
+    return data == null
+        ? null
+        : CustomClassMapper.convertToCustomClass(data, valueType, getReference());
   }
 
   /**

firebase-firestore/src/main/java/com/google/firebase/firestore/UserDataConverter.java

@@ -73,14 +73,23 @@ public UserDataConverter(DatabaseId databaseId) {
     this.databaseId = databaseId;
   }
 
-  /** Parse document data from a non-merge set() call. */
+  /**
+   * Parse document data from a non-merge set() call.
+   *
+   * @param input A map or POJO object representing document data.
+   */
   public ParsedSetData parseSetData(Object input) {
     ParseAccumulator accumulator = new ParseAccumulator(UserData.Source.Set);
     ObjectValue updateData = convertAndParseDocumentData(input, accumulator.rootContext());
     return accumulator.toSetData(updateData);
   }
 
-  /** Parse document data from a set() call with SetOptions.merge() set. */
+  /**
+   * Parse document data from a set() call with SetOptions.merge() set.
+   *
+   * @param input A map or POJO object representing document data.
+   * @param fieldMask A {@link FieldMask} object representing the fields to be merged.
+   */
   public ParsedSetData parseMergeData(Object input, @Nullable FieldMask fieldMask) {
     ParseAccumulator accumulator = new ParseAccumulator(UserData.Source.MergeSet);
     ObjectValue updateData = convertAndParseDocumentData(input, accumulator.rootContext());

firebase-firestore/src/main/java/com/google/firebase/firestore/util/CustomClassMapper.java

@@ -91,9 +91,12 @@ public static Map<String, Object> convertToPlainJavaTypes(Map<?, Object> update)
    *
    * @param object The representation of the JSON data
    * @param clazz The class of the object to convert to
+   * @param docRef The value to set to {@link DocumentId} annotated fields in the custom class.
    * @return The POJO object.
    */
-  public static <T> T convertToCustomClass(Object object, Class<T> clazz) {
+  public static <T> T convertToCustomClass(
+      Object object, Class<T> clazz, DocumentReference docRef) {
+    // TODO(wuandy): Use DeserializeContext to encapsulate ErrorPath and docRef.
     return deserializeToClass(object, clazz, ErrorPath.EMPTY);
   }
 
@@ -754,6 +757,7 @@ private Type resolveType(Type type, Map<TypeVariable<Class<T>>, Type> types) {
     }
 
     Map<String, Object> serialize(T object, ErrorPath path) {
+      // TODO(wuandy): Add logic to skip @DocumentId annotated fields in serialization.
       if (!clazz.isAssignableFrom(object.getClass())) {
         throw new IllegalArgumentException(
             "Can't serialize object of class "

firebase-firestore/src/main/java/com/google/firebase/firestore/util/DocumentId.java

@@ -0,0 +1,38 @@
+// Copyright 2019 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package com.google.firebase.firestore.util;
+
+import com.google.firebase.annotations.PublicApi;
+import com.google.firebase.firestore.DocumentReference;
+import com.google.firebase.firestore.DocumentSnapshot;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation used to mark a POJO field to be automatically populated with the document's ID when
+ * the POJO is created from a Firestore document (e.g. via {@link DocumentSnapshot#toObject}).
+ *
+ * <p>This annotation can only be applied to fields of String or {@link DocumentReference},
+ * otherwise a runtime exception will be thrown.
+ *
+ * <p>When writing a POJO to Firestore, the @DocumentId-annotated field will be ignored, to allow
+ * writing to any documents that are not the origin of the POJO.
+ */
+@PublicApi
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.FIELD})
+@interface DocumentId {}

firebase-firestore/src/test/java/com/google/firebase/firestore/util/MapperTest.java

@@ -21,6 +21,7 @@
 import static org.junit.Assert.assertNull;
 import static org.junit.Assert.fail;
 
+import com.google.firebase.firestore.DocumentReference;
 import com.google.firebase.firestore.Exclude;
 import com.google.firebase.firestore.PropertyName;
 import com.google.firebase.firestore.ThrowOnExtraProperties;
@@ -899,7 +900,7 @@ public void setValue(String value) {
 
   private static <T> T deserialize(String jsonString, Class<T> clazz) {
     Map<String, Object> json = fromSingleQuotedString(jsonString);
-    return CustomClassMapper.convertToCustomClass(json, clazz);
+    return CustomClassMapper.convertToCustomClass(json, clazz, null);
   }
 
   private static Object serialize(Object object) {
@@ -919,6 +920,15 @@ private static void assertExceptionContains(String partialMessage, Runnable run)
     }
   }
 
+  private static <T> T convertToCustomClass(
+      Object object, Class<T> clazz, DocumentReference docRef) {
+    return CustomClassMapper.convertToCustomClass(object, clazz, docRef);
+  }
+
+  private static <T> T convertToCustomClass(Object object, Class<T> clazz) {
+    return CustomClassMapper.convertToCustomClass(object, clazz, null);
+  }
+
   @Test
   public void primitiveDeserializeString() {
     StringBean bean = deserialize("{'value': 'foo'}", StringBean.class);
@@ -1339,8 +1349,7 @@ public void beansCanContainMaps() {
   public void beansCanContainUpperBoundedMaps() {
     Date date = new Date(1491847082123L);
     Map<String, Object> source = map("values", map("foo", date));
-    UpperBoundedMapBean bean =
-        CustomClassMapper.convertToCustomClass(source, UpperBoundedMapBean.class);
+    UpperBoundedMapBean bean = convertToCustomClass(source, UpperBoundedMapBean.class);
     Map<String, Object> expected = map("foo", date);
     assertEquals(expected, bean.values);
   }
@@ -1349,8 +1358,7 @@ public void beansCanContainUpperBoundedMaps() {
   public void beansCanContainMultiBoundedMaps() {
     Date date = new Date(1491847082123L);
     Map<String, Object> source = map("map", map("values", map("foo", date)));
-    MultiBoundedMapHolderBean bean =
-        CustomClassMapper.convertToCustomClass(source, MultiBoundedMapHolderBean.class);
+    MultiBoundedMapHolderBean bean = convertToCustomClass(source, MultiBoundedMapHolderBean.class);
 
     Map<String, Object> expected = map("foo", date);
     assertEquals(expected, bean.map.values);
@@ -1367,7 +1375,7 @@ public void beansCanContainUnboundedMaps() {
   public void beansCanContainUnboundedTypeVariableMaps() {
     Map<String, Object> source = map("map", map("values", map("foo", "bar")));
     UnboundedTypeVariableMapHolderBean bean =
-        CustomClassMapper.convertToCustomClass(source, UnboundedTypeVariableMapHolderBean.class);
+        convertToCustomClass(source, UnboundedTypeVariableMapHolderBean.class);
 
     Map<String, Object> expected = map("foo", "bar");
     assertEquals(expected, bean.map.values);
@@ -1823,63 +1831,60 @@ public void objectAcceptsAnyObject() {
 
   @Test
   public void objectClassCanBePassedInAtTopLevel() {
-    assertEquals("foo", CustomClassMapper.convertToCustomClass("foo", Object.class));
-    assertEquals(1, CustomClassMapper.convertToCustomClass(1, Object.class));
-    assertEquals(1L, CustomClassMapper.convertToCustomClass(1L, Object.class));
-    assertEquals(true, CustomClassMapper.convertToCustomClass(true, Object.class));
-    assertEquals(1.1, CustomClassMapper.convertToCustomClass(1.1, Object.class));
+    assertEquals("foo", convertToCustomClass("foo", Object.class));
+    assertEquals(1, convertToCustomClass(1, Object.class));
+    assertEquals(1L, convertToCustomClass(1L, Object.class));
+    assertEquals(true, convertToCustomClass(true, Object.class));
+    assertEquals(1.1, convertToCustomClass(1.1, Object.class));
     List<String> fooList = Collections.singletonList("foo");
-    assertEquals(fooList, CustomClassMapper.convertToCustomClass(fooList, Object.class));
+    assertEquals(fooList, convertToCustomClass(fooList, Object.class));
     Map<String, String> fooMap = Collections.singletonMap("foo", "bar");
-    assertEquals(fooMap, CustomClassMapper.convertToCustomClass(fooMap, Object.class));
+    assertEquals(fooMap, convertToCustomClass(fooMap, Object.class));
   }
 
   @Test
   public void primitiveClassesCanBePassedInTopLevel() {
-    assertEquals("foo", CustomClassMapper.convertToCustomClass("foo", String.class));
-    assertEquals((Integer) 1, CustomClassMapper.convertToCustomClass(1, Integer.class));
-    assertEquals((Long) 1L, CustomClassMapper.convertToCustomClass(1L, Long.class));
-    assertEquals(true, CustomClassMapper.convertToCustomClass(true, Boolean.class));
-    assertEquals((Double) 1.1, CustomClassMapper.convertToCustomClass(1.1, Double.class));
+    assertEquals("foo", convertToCustomClass("foo", String.class));
+    assertEquals((Integer) 1, convertToCustomClass(1, Integer.class));
+    assertEquals((Long) 1L, convertToCustomClass(1L, Long.class));
+    assertEquals(true, convertToCustomClass(true, Boolean.class));
+    assertEquals((Double) 1.1, convertToCustomClass(1.1, Double.class));
   }
 
   @Test
   public void passingInListTopLevelThrows() {
     assertExceptionContains(
         "Class java.util.List has generic type parameters, please use GenericTypeIndicator "
             + "instead",
-        () -> CustomClassMapper.convertToCustomClass(Collections.singletonList("foo"), List.class));
+        () -> convertToCustomClass(Collections.singletonList("foo"), List.class));
   }
 
   @Test
   public void passingInMapTopLevelThrows() {
     assertExceptionContains(
         "Class java.util.Map has generic type parameters, please use GenericTypeIndicator "
             + "instead",
-        () ->
-            CustomClassMapper.convertToCustomClass(
-                Collections.singletonMap("foo", "bar"), Map.class));
+        () -> convertToCustomClass(Collections.singletonMap("foo", "bar"), Map.class));
   }
 
   @Test
   public void passingInCharacterTopLevelThrows() {
     assertExceptionContains(
         "Deserializing values to Character is not supported",
-        () -> CustomClassMapper.convertToCustomClass('1', Character.class));
+        () -> convertToCustomClass('1', Character.class));
   }
 
   @Test
   public void passingInShortTopLevelThrows() {
     assertExceptionContains(
         "Deserializing values to Short is not supported",
-        () -> CustomClassMapper.convertToCustomClass(1, Short.class));
+        () -> convertToCustomClass(1, Short.class));
   }
 
   @Test
   public void passingInByteTopLevelThrows() {
     assertExceptionContains(
-        "Deserializing values to Byte is not supported",
-        () -> CustomClassMapper.convertToCustomClass(1, Byte.class));
+        "Deserializing values to Byte is not supported", () -> convertToCustomClass(1, Byte.class));
   }
 
   @Test
@@ -1916,13 +1921,13 @@ public void collectionsCantBeDeserialized() {
 
   @Test
   public void allowNullEverywhere() {
-    assertNull(CustomClassMapper.convertToCustomClass(null, Integer.class));
-    assertNull(CustomClassMapper.convertToCustomClass(null, String.class));
-    assertNull(CustomClassMapper.convertToCustomClass(null, Double.class));
-    assertNull(CustomClassMapper.convertToCustomClass(null, Long.class));
-    assertNull(CustomClassMapper.convertToCustomClass(null, Boolean.class));
-    assertNull(CustomClassMapper.convertToCustomClass(null, StringBean.class));
-    assertNull(CustomClassMapper.convertToCustomClass(null, Object.class));
+    assertNull(convertToCustomClass(null, Integer.class));
+    assertNull(convertToCustomClass(null, String.class));
+    assertNull(convertToCustomClass(null, Double.class));
+    assertNull(convertToCustomClass(null, Long.class));
+    assertNull(convertToCustomClass(null, Boolean.class));
+    assertNull(convertToCustomClass(null, StringBean.class));
+    assertNull(convertToCustomClass(null, Object.class));
   }
 
   @Test
@@ -2233,7 +2238,7 @@ public void deserializationFailureIncludesPath() {
     Object serialized = Collections.singletonMap("value", (short) 1);
 
     try {
-      CustomClassMapper.convertToCustomClass(serialized, ShortBean.class);
+      convertToCustomClass(serialized, ShortBean.class);
       fail("should have thrown");
     } catch (RuntimeException e) {
       assertEquals(