com.google.cloud.firestore

Class DocumentReference

java.lang.Object

com.google.cloud.firestore.DocumentReference

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.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DocumentReference(com.google.cloud.firestore.FirestoreImpl firestore, com.google.cloud.firestore.ResourcePath path)

Method Summary

Modifier and Type	Method and Description
ListenerRegistration	addSnapshotListener(EventListener<DocumentSnapshot> listener) Starts listening to the document referenced by this DocumentReference.
ListenerRegistration	addSnapshotListener(Executor executor, EventListener<DocumentSnapshot> listener) Starts listening to the document referenced by this DocumentReference.
CollectionReference	collection(String collectionPath) Gets a CollectionReference instance that refers to the collection that is a child of this document.
ApiFuture<WriteResult>	create(Map<String,Object> fields) Creates a new Document at the DocumentReference's Location.
ApiFuture<WriteResult>	create(Object pojo) Creates a new Document at the DocumentReference location.
ApiFuture<WriteResult>	delete() Deletes the document referred to by this DocumentReference.
ApiFuture<WriteResult>	delete(Precondition options) Deletes the document referred to by this DocumentReference.
boolean	equals(Object obj) Returns true if this DocumentReference is equal to the provided object.
ApiFuture<DocumentSnapshot>	get() Reads the document referenced by this DocumentReference.
Iterable<CollectionReference>	getCollections() Deprecated. Use `listCollections()`.
Firestore	getFirestore()
String	getId() The id of a document refers to the last component of path pointing to a document, e.g.
CollectionReference	getParent() A reference to the Collection to which this DocumentReference belongs to.
String	getPath() A string representing the path of the referenced document (relative to the root of the database).
int	hashCode()
Iterable<CollectionReference>	listCollections() Fetches the subcollections that are direct children of this document.
ApiFuture<WriteResult>	set(Map<String,Object> fields) Overwrites the document referred to by this DocumentReference.
ApiFuture<WriteResult>	set(Map<String,Object> fields, SetOptions options) Writes to the document referred to by this DocumentReference.
ApiFuture<WriteResult>	set(Object pojo) Overwrites the document referred to by this DocumentReference.
ApiFuture<WriteResult>	set(Object pojo, SetOptions options) Writes to the document referred to by this DocumentReference.
String	toString()
ApiFuture<WriteResult>	update(FieldPath fieldPath, Object value, Object... moreFieldsAndValues) Updates the fields in the document referred to by this DocumentReference.
ApiFuture<WriteResult>	update(Map<String,Object> fields) Updates fields in the document referred to by this DocumentReference.
ApiFuture<WriteResult>	update(Map<String,Object> fields, Precondition options) Updates fields in the document referred to by this DocumentReference.
ApiFuture<WriteResult>	update(Precondition options, FieldPath fieldPath, Object value, Object... moreFieldsAndValues) Updates the fields in the document referred to by this DocumentReference.
ApiFuture<WriteResult>	update(Precondition options, String field, Object value, Object... moreFieldsAndValues) Updates the fields in the document referred to by this DocumentReference.
ApiFuture<WriteResult>	update(String field, Object value, Object... moreFieldsAndValues) Updates the fields in the document referred to by this DocumentReference.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

DocumentReference

protected DocumentReference(com.google.cloud.firestore.FirestoreImpl firestore,
                            com.google.cloud.firestore.ResourcePath path)

Method Detail

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, e.g. "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 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 ApiFuture<WriteResult> create(@Nonnull
                                              Object pojo)

Creates a new Document at the DocumentReference location. It fails the write if the document exists.

Parameters:

pojo - A map of the fields and values for the document.

Returns:

An ApiFuture that will be resolved when the write finishes.

set

@Nonnull
public 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 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 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 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 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 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 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 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 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 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 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 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 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.

listCollections

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.

getCollections

public Iterable<CollectionReference> getCollections()

Deprecated. Use `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