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.

Public Method Summary

ListenerRegistration	addSnapshotListener(Activity activity, MetadataChanges metadataChanges, EventListener<DocumentSnapshot> listener) Starts listening to the document referenced by this DocumentReference with the given options using an Activity-scoped listener.
ListenerRegistration	addSnapshotListener(Executor executor, MetadataChanges metadataChanges, EventListener<DocumentSnapshot> listener) Starts listening to the document referenced by this DocumentReference with the given options.
ListenerRegistration	addSnapshotListener(MetadataChanges metadataChanges, EventListener<DocumentSnapshot> listener) Starts listening to the document referenced by this DocumentReference with the given options.
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.
ListenerRegistration	addSnapshotListener(Activity activity, EventListener<DocumentSnapshot> listener) Starts listening to the document referenced by this DocumentReference using an Activity-scoped listener.
CollectionReference	collection(String collectionPath) Gets a CollectionReference instance that refers to the subcollection at the specified path relative to this document.
Task<Void>	delete() Deletes the document referred to by this DocumentReference.
boolean	equals(Object o)
Task<DocumentSnapshot>	get() Reads the document referenced by this DocumentReference.
Task<DocumentSnapshot>	get(Source source) Reads the document referenced by this DocumentReference.
FirebaseFirestore	getFirestore() Gets the Firestore instance associated with this document reference.
String	getId()
CollectionReference	getParent() Gets a CollectionReference to the collection that contains this document.
String	getPath() Gets the path of this document (relative to the root of the database) as a slash-separated string.
int	hashCode()
Task<Void>	set(Object data) Overwrites the document referred to by this DocumentReference.
Task<Void>	set(Object data, SetOptions options) Writes to the document referred to by this DocumentReference.
Task<Void>	update(Map<String, Object> data) Updates fields in the document referred to by this DocumentReference.
Task<Void>	update(String field, Object value, Object... moreFieldsAndValues) Updates fields in the document referred to by this DocumentReference.
Task<Void>	update(FieldPath fieldPath, Object value, Object... moreFieldsAndValues) Updates fields in the document referred to by this DocumentReference.

Inherited Method Summary

From class java.lang.Object

Object	clone()
boolean	equals(Object arg0)
void	finalize()
final Class<?>	getClass()
int	hashCode()
final void	notify()
final void	notifyAll()
String	toString()
final void	wait(long arg0, int arg1)
final void	wait(long arg0)
final void	wait()

Public Methods

public ListenerRegistration addSnapshotListener (Activity activity, MetadataChanges metadataChanges, EventListener<DocumentSnapshot> listener)

Starts listening to the document referenced by this DocumentReference with the given options using an Activity-scoped listener.

The listener will be automatically removed during onStop().

Parameters

activity	The activity to scope the listener to.
metadataChanges	Indicates whether metadata-only changes (i.e. only DocumentSnapshot.getMetadata() changed) should trigger snapshot events.
listener	The event listener that will be called with the snapshots.

Returns

• A registration object that can be used to remove the listener.

public ListenerRegistration addSnapshotListener (Executor executor, MetadataChanges metadataChanges, EventListener<DocumentSnapshot> listener)

Starts listening to the document referenced by this DocumentReference with the given options.

Parameters

executor	The executor to use to call the listener.
metadataChanges	Indicates whether metadata-only changes (i.e. only DocumentSnapshot.getMetadata() changed) should trigger snapshot events.
listener	The event listener that will be called with the snapshots.

Returns

• A registration object that can be used to remove the listener.

public ListenerRegistration addSnapshotListener (MetadataChanges metadataChanges, EventListener<DocumentSnapshot> listener)

Starts listening to the document referenced by this DocumentReference with the given options.

Parameters

metadataChanges	Indicates whether metadata-only changes (i.e. only DocumentSnapshot.getMetadata() changed) should trigger snapshot events.
listener	The event listener that will be called with the snapshots.

Returns

• A registration object that can be used to remove the listener.

public ListenerRegistration addSnapshotListener (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.

public ListenerRegistration addSnapshotListener (Executor executor, 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.

public ListenerRegistration addSnapshotListener (Activity activity, EventListener<DocumentSnapshot> listener)

Starts listening to the document referenced by this DocumentReference using an Activity-scoped listener.

The listener will be automatically removed during onStop().

Parameters

activity	The activity to scope the listener to.
listener	The event listener that will be called with the snapshots.

Returns

• A registration object that can be used to remove the listener.

public CollectionReference collection (String collectionPath)

Gets a CollectionReference instance that refers to the subcollection at the specified path relative to this document.

Parameters

collectionPath	A slash-separated relative path to a subcollection.

Returns

• The CollectionReference instance.

public Task<Void> delete ()

Deletes the document referred to by this DocumentReference.

Returns

• A Task that will be resolved when the delete completes.

public boolean equals (Object o)

public Task<DocumentSnapshot> get ()

Reads the document referenced by this DocumentReference.

Returns

• A Task that will be resolved with the contents of the Document at this DocumentReference.

public Task<DocumentSnapshot> get (Source source)

Reads the document referenced by this DocumentReference.

By default, get() attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. This behavior can be altered via the Source parameter.

Parameters

source	A value to configure the get behavior.

Returns

• A Task that will be resolved with the contents of the Document at this DocumentReference.

public FirebaseFirestore getFirestore ()

Gets the Firestore instance associated with this document reference.

public String getId ()

public CollectionReference getParent ()

Gets a CollectionReference to the collection that contains this document.

Returns

• The CollectionReference that contains this document.

public String getPath ()

Gets the path of this document (relative to the root of the database) as a slash-separated string.

Returns

• The path of this document.

public int hashCode ()

public Task<Void> set (Object data)

Overwrites the document referred to by this DocumentReference. If the document does not yet exist, it will be created. If a document already exists, it will be overwritten.

Parameters

data	The data to write to the document (e.g. a Map or a POJO containing the desired document contents).

Returns

• A Task that will be resolved when the write finishes.

public Task<Void> set (Object data, 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

data	The data to write to the document (e.g. a Map or a POJO containing the desired document contents).
options	An object to configure the set behavior.

Returns

• A Task that will be resolved when the write finishes.

public Task<Void> update (Map<String, Object> data)

Updates fields in the document referred to by this DocumentReference. If no document exists yet, the update will fail.

Parameters

data	A map of field / value pairs to update. Fields can contain dots to reference nested fields within the document.

Returns

• A Task that will be resolved when the write finishes.

public Task<Void> update (String field, Object value, Object... moreFieldsAndValues)

Updates fields in the document referred to by this DocumentReference. If no document exists yet, the update will fail.

Parameters

field	The first field to update. Fields can contain dots to reference a nested field within the document.
value	The first value
moreFieldsAndValues	Additional field/value pairs.

Returns

• A Task that will be resolved when the write finishes.

public Task<Void> update (FieldPath fieldPath, Object value, Object... moreFieldsAndValues)

Updates fields in the document referred to by this DocumentReference. If no document exists yet, the update will fail.

Parameters

fieldPath	The first field to update.
value	The first value
moreFieldsAndValues	Additional field/value pairs.

Returns

• A Task that will be resolved when the write finishes.