A DocumentReference
refers to a document location in a Cloud 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: Cloud 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 | |
Task<DocumentSnapshot> |
get()
Reads the document referenced by this
DocumentReference .
|
Task<DocumentSnapshot> | |
FirebaseFirestore |
getFirestore()
Gets the Cloud 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> | |
Task<Void> | |
Task<Void> | |
Task<Void> | |
Task<Void> |
Inherited Method Summary
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 Cloud 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.