Move DocumentId to public space

.gitignore

@@ -7,3 +7,9 @@ local.properties
 google-services.json
 /build.gradle
 _artifacts
+# VS code/extension files
+.project
+.classpath
+org.eclipse.buildship.core.prefs
+bin/
+.vscode/

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

@@ -201,6 +201,28 @@ public void setShortValue(@Nullable Short shortValue) {
     }
   }
 
+  public static final class POJOWithDocumentIdAnnotation {
+    String str;
+    @DocumentId public DocumentReference autoPopulatedReference;
+    @DocumentId String docReferenceId;
+
+    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 +238,19 @@ 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.getPath().endsWith(readFromStore.getDocReferenceId()), true);
+  }
+
   @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 properties of a type other than String or {@link
+ *       DocumentReference}.
+ *   <li>This annotation is applied to a property that is not writeable (for example, a Java Bean
+ *       getter without a backing field).
+ *   <li>There are conflicts between this annotation and property name matches. 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 writes to any
+ * documents that are 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/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.DocumentId;
 import com.google.firebase.firestore.DocumentReference;
 import com.google.firebase.firestore.Exclude;
 import com.google.firebase.firestore.PropertyName;