Move DocumentId to public space (#571)

* Move DocumentId to public space

* add nest object testing

* add changelog

Author: Hui-Wu

firebase-firestore/CHANGELOG.md

@@ -5,6 +5,9 @@
   if it fails to load SSL Ciphers. To avoid these crashes, you must bundle 
   Conscrypt to support non-GMSCore devices on Android KitKat or JellyBean (see
   https://github.com/grpc/grpc-java/blob/master/SECURITY.md#tls-on-android).
+- [feature] Added a `@DocumentId` annotation which can be used on a
+  `DocumentReference` or `String` property in a POJO to indicate that the SDK
+  should automatically populate it with the document's ID.
 
 # 20.1.0
 - [changed] SSL and gRPC initialization now happens on a separate thread, which

firebase-firestore/src/androidTest/java/com/google/firebase/firestore/POJOTest.java

@@ -201,6 +201,34 @@ public void setShortValue(@Nullable Short shortValue) {
     }
   }
 
+  public static final class POJOWithDocumentIdAnnotation {
+    String str;
+    @DocumentId public DocumentReference autoPopulatedReference;
+    @DocumentId String docReferenceId;
+
+    static class NestedPOJO {
+      @DocumentId public DocumentReference autoPopulatedReference;
+    }
+
+    public NestedPOJO nested = new NestedPOJO();
+
+    public String getDocReferenceId() {
+      return docReferenceId;
+    }
+
+    public void setDocReferenceId(String id) {
+      this.docReferenceId = id;
+    }
+
+    public String getStr() {
+      return str;
+    }
+
+    public void setStr(String str) {
+      this.str = str;
+    }
+  }
+
   @After
   public void tearDown() {
     IntegrationTestUtil.tearDown();
@@ -216,6 +244,20 @@ public void testWriteAndRead() {
     assertEquals(data, otherData);
   }
 
+  @Test
+  public void testDocumentIdAnnotation() {
+    CollectionReference collection = testCollection();
+    POJOWithDocumentIdAnnotation data = new POJOWithDocumentIdAnnotation();
+    data.setStr("name");
+    DocumentReference reference = waitFor(collection.add(data));
+    DocumentSnapshot doc = waitFor(reference.get());
+    POJOWithDocumentIdAnnotation readFromStore = doc.toObject(POJOWithDocumentIdAnnotation.class);
+    assertEquals("name", readFromStore.getStr());
+    assertEquals(reference, readFromStore.autoPopulatedReference);
+    assertEquals(reference, readFromStore.nested.autoPopulatedReference);
+    assertEquals(reference.getId(), readFromStore.getDocReferenceId());
+  }
+
   @Test
   public void testSetMerge() {
     CollectionReference collection = testCollection();

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

@@ -0,0 +1,49 @@
+// 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;
+
+import com.google.firebase.annotations.PublicApi;
+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 property to be automatically populated with the document's ID when
+ * the POJO is created from a Cloud Firestore document (for example, via {@link
+ * DocumentSnapshot#toObject}).
+ *
+ * <ul>
+ *   Any of the following will throw a runtime exception:
+ *   <li>This annotation is applied to a property of a type other than String or {@link
+ *       DocumentReference}.
+ *   <li>This annotation is applied to a property that is not writable (for example, a Java Bean
+ *       getter without a backing field).
+ *   <li>This annotation is applied to a property with a name that conflicts with a read document
+ *       field. For example, if a POJO has a field `firstName` annotated by @DocumentId, and there
+ *       is a property from the document named `firstName` as well, an exception is thrown when you
+ *       try to read the document into the POJO via {@link DocumentSnapshot#toObject} or {@link
+ *       DocumentReference#get}.
+ *   <li>
+ * </ul>
+ *
+ * <p>When using a POJO to write to a document (via {@link DocumentReference#set} or @{@link
+ * WriteBatch#set}), the property annotated by @DocumentId is ignored, which allows writing the POJO
+ * back to any document, even if it's not the origin of the POJO.
+ */
+@PublicApi
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.FIELD, ElementType.METHOD})
+public @interface DocumentId {}

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

@@ -19,6 +19,7 @@
 
 import com.google.firebase.Timestamp;
 import com.google.firebase.firestore.Blob;
+import com.google.firebase.firestore.DocumentId;
 import com.google.firebase.firestore.DocumentReference;
 import com.google.firebase.firestore.Exclude;
 import com.google.firebase.firestore.FieldValue;

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

@@ -21,6 +21,7 @@
 import static org.junit.Assert.assertNull;
 import static org.junit.Assert.fail;
 
+import com.google.firebase.firestore.DocumentId;
 import com.google.firebase.firestore.DocumentReference;
 import com.google.firebase.firestore.Exclude;
 import com.google.firebase.firestore.PropertyName;