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, DocumentListenOptions options, 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, DocumentListenOptions options, 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(DocumentListenOptions options, EventListener<DocumentSnapshot> listener)
Starts listening to the document referenced by this DocumentReference with the given options.
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.
Task<DocumentSnapshot>
get()
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.
Task<Void>
set(Object pojo)
Overwrites the document referred to by this DocumentReference.
Task<Void>
set(Map<StringObject> data, SetOptions options)
Writes to the document referred to by this DocumentReference.
Task<Void>
set(Object pojo, SetOptions options)
Writes to the document referred to by this DocumentReference.
Task<Void>
set(Map<StringObject> data)
Overwrites the document referred to by this DocumentReference.
Task<Void>
update(Map<StringObject> 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

Public Methods

public ListenerRegistration addSnapshotListener (Activity activity, DocumentListenOptions options, 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.
options The options to use for this listen.
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, DocumentListenOptions options, 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.
options The options to use for this listen.
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 (DocumentListenOptions options, EventListener<DocumentSnapshot> listener)

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

Parameters
options The options to use for this listen.
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 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 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 Task<Void> set (Object pojo)

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
pojo The POJO that will be used to populate the document contents
Returns
  • A Task that will be resolved when the write finishes.

public Task<Void> set (Map<StringObject> 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 A map of the fields and values for the document.
options An object to configure the set behavior.
Returns
  • A Task that will be resolved when the write finishes.

public Task<Void> set (Object pojo, 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
  • A Task that will be resolved when the write finishes.

public Task<Void> set (Map<StringObject> 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 A map of the fields and values for the document.
Returns
  • A Task that will be resolved when the write finishes.

public Task<Void> update (Map<StringObject> 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.

Send feedback about...

Need help? Visit our support page.