Package com.google.cloud.firestore

Class DocumentReference

java.lang.Object
com.google.cloud.firestore.DocumentReference
@InternalExtensionOnly public class DocumentReference extends Object
A DocumentReference refers to a document location in a Firestore database and can be used to write, read, or listen to the location. There may or may not exist a document at the referenced location. A DocumentReference can also be used to create a CollectionReference to a subcollection.

Subclassing Note: Firestore classes are not meant to be subclassed except for use in test mocks. Subclassing is not supported in production code and new SDK releases may break code that does so.

  • Method Details

    • getFirestore

      @Nonnull public Firestore getFirestore()

    • getId

      @Nonnull public String getId()
      The id of a document refers to the last component of path pointing to a document, for example "document-id" in "projects/project-id/databases/database-id/document-id".
      Returns:
      The ID of the document.

    • getPath

      @Nonnull public String getPath()
      A string representing the path of the referenced document (relative to the root of the database).
      Returns:
      The slash-separated path relative to the root of the database.

    • getParent

      @Nonnull public CollectionReference getParent()
      A reference to the Collection to which this DocumentReference belongs to.
      Returns:
      The parent Collection.

    • collection

      @Nonnull public CollectionReference collection(@Nonnull String collectionPath)
      Gets a CollectionReference instance that refers to the collection that is a child of this document.
      Parameters:
      collectionPath - A relative and slash-separated path to a collection.
      Returns:
      The CollectionReference instance.

    • create

      @Nonnull public com.google.api.core.ApiFuture<WriteResult> create(@Nonnull Map<String,Object> fields)
      Creates a new Document at the DocumentReference's Location. It fails the write if the document exists.
      Parameters:
      fields - A map of the fields and values for the document.
      Returns:
      An ApiFuture that will be resolved when the write finishes.

    • create

      @Nonnull public com.google.api.core.ApiFuture<WriteResult> create(@Nonnull Object pojo)
      Creates a new Document at the DocumentReference location. It fails the write if the document exists.
      Parameters:
      pojo - The POJO that will be used to populate the document contents.
      Returns:
      An ApiFuture that will be resolved when the write finishes.

    • set

      @Nonnull public com.google.api.core.ApiFuture<WriteResult> set(@Nonnull Map<String,Object> fields)
      Overwrites the document referred to by this DocumentReference. If no document exists yet, it will be created. If a document already exists, it will be overwritten.
      Parameters:
      fields - A map of the fields and values for the document.
      Returns:
      An ApiFuture that will be resolved when the write finishes.

    • set

      @Nonnull public com.google.api.core.ApiFuture<WriteResult> set(@Nonnull Map<String,Object> fields, @Nonnull SetOptions options)
      Writes to the document referred to by this DocumentReference. If the document does not yet exist, it will be created. If you pass SetOptions, the provided data can be merged into an existing document.
      Parameters:
      fields - A map of the fields and values for the document.
      options - An object to configure the set behavior.
      Returns:
      An ApiFuture that will be resolved when the write finishes.

    • set

      @Nonnull public com.google.api.core.ApiFuture<WriteResult> set(@Nonnull Object pojo)
      Overwrites the document referred to by this DocumentReference. If no document exists yet, it will be created. If a document already exists, it will be overwritten.
      Parameters:
      pojo - The POJO that will be used to populate the document contents.
      Returns:
      An ApiFuture that will be resolved when the write finishes.

    • set

      @Nonnull public com.google.api.core.ApiFuture<WriteResult> set(@Nonnull Object pojo, @Nonnull SetOptions options)
      Writes to the document referred to by this DocumentReference. If the document does not yet exist, it will be created. If you pass SetOptions, the provided data can be merged into an existing document.
      Parameters:
      pojo - The POJO that will be used to populate the document contents.
      options - An object to configure the set behavior.
      Returns:
      An ApiFuture that will be resolved when the write finishes.

    • update

      @Nonnull public com.google.api.core.ApiFuture<WriteResult> update(@Nonnull Map<String,Object> fields)
      Updates fields in the document referred to by this DocumentReference. If the document doesn't exist yet, the update will fail.
      Parameters:
      fields - A Map containing the fields and values with which to update the document.
      Returns:
      An ApiFuture that will be resolved when the write finishes.

    • update

      @Nonnull public com.google.api.core.ApiFuture<WriteResult> update(@Nonnull Map<String,Object> fields, Precondition options)
      Updates fields in the document referred to by this DocumentReference. If the document doesn't exist yet, the update will fail.
      Parameters:
      fields - A map containing the fields and values with which to update the document.
      options - Preconditions to enforce on this update.
      Returns:
      An ApiFuture that will be resolved when the write finishes.

    • update

      @Nonnull public com.google.api.core.ApiFuture<WriteResult> update(@Nonnull String field, @Nullable Object value, Object... moreFieldsAndValues)
      Updates the fields in the document referred to by this DocumentReference. If the document doesn't exist yet, the update will fail.
      Parameters:
      field - The first field to set
      value - The first value to set
      moreFieldsAndValues - String and Object pairs with more fields to be set.
      Returns:
      An ApiFuture that will be resolved when the write finishes.

    • update

      @Nonnull public com.google.api.core.ApiFuture<WriteResult> update(@Nonnull FieldPath fieldPath, @Nullable Object value, Object... moreFieldsAndValues)
      Updates the fields in the document referred to by this DocumentReference. If the document doesn't exist yet, the update will fail.
      Parameters:
      fieldPath - The first field to set
      value - The first value to set
      moreFieldsAndValues - String and Object pairs with more fields to be set.
      Returns:
      A ApiFuture that will be resolved when the write finishes.

    • update

      @Nonnull public com.google.api.core.ApiFuture<WriteResult> update(@Nonnull Precondition options, @Nonnull String field, @Nullable Object value, Object... moreFieldsAndValues)
      Updates the fields in the document referred to by this DocumentReference. If the document doesn't exist yet, the update will fail.
      Parameters:
      options - Preconditions to enforce on this update.
      field - The first field to set
      value - The first value to set
      moreFieldsAndValues - String and Object pairs with more fields to be set.
      Returns:
      A ApiFuture that will be resolved when the write finishes.

    • update

      @Nonnull public com.google.api.core.ApiFuture<WriteResult> update(@Nonnull Precondition options, @Nonnull FieldPath fieldPath, @Nullable Object value, Object... moreFieldsAndValues)
      Updates the fields in the document referred to by this DocumentReference. If the document doesn't exist yet, the update will fail.
      Parameters:
      options - Preconditions to enforce on this update.
      fieldPath - The first field to set
      value - The first value to set
      moreFieldsAndValues - String and Object pairs with more fields to be set.
      Returns:
      A ApiFuture that will be resolved when the write finishes.

    • delete

      @Nonnull public com.google.api.core.ApiFuture<WriteResult> delete(@Nonnull Precondition options)
      Deletes the document referred to by this DocumentReference.
      Parameters:
      options - Preconditions to enforce for this delete.
      Returns:
      An ApiFuture that will be resolved when the delete completes.

    • delete

      @Nonnull public com.google.api.core.ApiFuture<WriteResult> delete()
      Deletes the document referred to by this DocumentReference.
      Returns:
      An ApiFuture that will be resolved when the delete completes.

    • get

      @Nonnull public com.google.api.core.ApiFuture<DocumentSnapshot> get()
      Reads the document referenced by this DocumentReference. If the document doesn't exist, the get() will return an an empty DocumentSnapshot.
      Returns:
      An ApiFuture that will be resolved with the contents of the Document at this DocumentReference, or a failure if the document does not exist.

    • get

      @Nonnull public com.google.api.core.ApiFuture<DocumentSnapshot> get(FieldMask fieldMask)
      Reads the document referenced by this DocumentReference. If the document doesn't exist, the get(FieldMask fieldMask) will return an empty DocumentSnapshot.
      Parameters:
      fieldMask - A FieldMask object to retrieve the field value
      Returns:
      An ApiFuture that will be resolved with the contents of the Document at this DocumentReference, or a failure if the document does not exist

    • listCollections

      @Nonnull public Iterable<CollectionReference> listCollections()
      Fetches the subcollections that are direct children of this document.
      Returns:
      An Iterable that can be used to fetch all subcollections.
      Throws:
      FirestoreException - if the Iterable could not be initialized.

    • addSnapshotListener

      @Nonnull public ListenerRegistration addSnapshotListener(@Nonnull Executor executor, @Nonnull EventListener<DocumentSnapshot> listener)
      Starts listening to the document referenced by this DocumentReference.
      Parameters:
      executor - The executor to use to call the listener.
      listener - The event listener that will be called with the snapshots.
      Returns:
      A registration object that can be used to remove the listener.

    • addSnapshotListener

      @Nonnull public ListenerRegistration addSnapshotListener(@Nonnull EventListener<DocumentSnapshot> listener)
      Starts listening to the document referenced by this DocumentReference.
      Parameters:
      listener - The event listener that will be called with the snapshots.
      Returns:
      A registration object that can be used to remove the listener.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object obj)
      Returns true if this DocumentReference is equal to the provided object.
      Overrides:
      equals in class Object
      Parameters:
      obj - The object to compare against.
      Returns:
      Whether this DocumentReference is equal to the provided object.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object