Represents a Cloud Firestore database and is the entry point for all Cloud Firestore operations.
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 | |
ListenerRegistration |
addSnapshotsInSyncListener(Executor
executor, Runnable
runnable)
Attaches a listener for a snapshots-in-sync event.
|
ListenerRegistration |
addSnapshotsInSyncListener(Activity
activity, Runnable
runnable)
Attaches a listener for a snapshots-in-sync event.
|
WriteBatch |
batch()
Creates a write batch, used for performing multiple writes as a single atomic
operation.
|
Task<Void> |
clearPersistence()
Clears the persistent storage, including pending writes and cached documents.
|
CollectionReference |
collection(String
collectionPath)
Gets a
CollectionReference instance that refers to the collection
at the specified path within the database.
|
Query |
collectionGroup(String
collectionId)
Creates and returns a new
Query that includes all documents in the
database that are contained in a collection or subcollection with the given
collectionId .
|
Task<Void> |
disableNetwork()
Disables network access for this instance.
|
DocumentReference | |
Task<Void> |
enableNetwork()
Re-enables network usage for this instance after a prior call to
disableNetwork() .
|
FirebaseApp |
getApp()
Returns the FirebaseApp instance to which this
FirebaseFirestore
belongs.
|
FirebaseFirestoreSettings |
getFirestoreSettings()
Returns the settings used by this
FirebaseFirestore object.
|
static FirebaseFirestore | |
static FirebaseFirestore |
getInstance(FirebaseApp app)
|
Task<Void> |
runBatch(WriteBatch.Function
batchFunction)
Executes a batchFunction on a newly created
WriteBatch
and then commits all of the writes made by the batchFunction as a single atomic
unit.
|
<TResult> Task<TResult> |
runTransaction(Function<TResult>
updateFunction)
Executes the given updateFunction and then attempts to commit the changes
applied within the transaction.
|
void |
setFirestoreSettings(FirebaseFirestoreSettings
settings)
Sets any custom settings used to configure this
FirebaseFirestore
object.
|
static void |
setLoggingEnabled(boolean loggingEnabled)
Globally enables / disables Cloud Firestore logging for the SDK.
|
Task<Void> |
terminate()
Terminates this
FirebaseFirestore instance.
|
void |
useEmulator(String host, int
port)
Modifies this FirebaseDatabase instance to communicate with the Cloud Firestore
emulator.
|
Task<Void> |
waitForPendingWrites()
Waits until all currently pending writes for the active user have been
acknowledged by the backend.
|
Inherited Method Summary
Public Methods
public ListenerRegistration addSnapshotsInSyncListener (Runnable runnable)
Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners.
NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server.
Parameters
runnable | A callback to be called every time all snapshot listeners are in sync with each other. |
---|
Returns
- A registration object that can be used to remove the listener.
public ListenerRegistration addSnapshotsInSyncListener (Executor executor, Runnable runnable)
Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners.
NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server.
Parameters
executor | The executor to use to call the listener. |
---|---|
runnable | A callback to be called every time all snapshot listeners are in sync with each other. |
Returns
- A registration object that can be used to remove the listener.
public ListenerRegistration addSnapshotsInSyncListener (Activity activity, Runnable runnable)
Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners.
NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server.
Parameters
activity | The activity to scope the listener to. |
---|---|
runnable | A callback to be called every time all snapshot listeners are in sync with each other. |
Returns
- A registration object that can be used to remove the listener.
public WriteBatch batch ()
Creates a write batch, used for performing multiple writes as a single atomic operation.
The maximum number of writes allowed in a single batch is 500, but note that each
usage of serverTimestamp()
,
arrayUnion(Object)
,
arrayRemove(Object)
, or increment(long)
inside a transaction counts as an additional write.
Returns
- The created WriteBatch object.
public Task<Void> clearPersistence ()
Clears the persistent storage, including pending writes and cached documents.
Must be called while the FirebaseFirestore
instance is not started
(after the app is shutdown or when the app is first initialized). On startup, this
method must be called before other methods (other than
setFirestoreSettings(FirebaseFirestoreSettings)
). If the
FirebaseFirestore
instance is still running, the Task
will
fail with an error code of FAILED_PRECONDITION
.
Note: clearPersistence()
is primarily intended to help write reliable
tests that use Cloud Firestore. It uses an efficient mechanism for dropping existing
data but does not attempt to securely overwrite or otherwise make cached data
unrecoverable. For applications that are sensitive to the disclosure of cached data in
between user sessions, we strongly recommend not enabling persistence at all.
Returns
- A
Task
that is resolved when the persistent storage is cleared. Otherwise, theTask
is rejected with an error.
public CollectionReference collection (String collectionPath)
Gets a CollectionReference
instance that refers to the collection at
the specified path within the database.
Parameters
collectionPath | A slash-separated path to a collection. |
---|
Returns
- The
CollectionReference
instance.
public Query collectionGroup (String collectionId)
Creates and returns a new Query
that includes all documents in the
database that are contained in a collection or subcollection with the given
collectionId
.
Parameters
collectionId | Identifies the collections to query over. Every collection or subcollection with this ID as the last segment of its path will be included. Cannot contain a slash. |
---|
Returns
- The created Query.
public Task<Void> disableNetwork ()
Disables network access for this instance. While the network is disabled, any
snapshot listeners or get()
calls will return results from cache, and any
write operations will be queued until network usage is re-enabled via a call to
enableNetwork()
.
Returns
- A Task that will be completed once networking is disabled.
public DocumentReference document (String documentPath)
Gets a `DocumentReference` instance that refers to the document at the specified path within the database.
Parameters
documentPath | A slash-separated path to a document. |
---|
Returns
- The DocumentReference instance.
public Task<Void> enableNetwork ()
Re-enables network usage for this instance after a prior call to
disableNetwork()
.
Returns
- A Task that will be completed once networking is enabled.
public FirebaseApp getApp ()
Returns the FirebaseApp instance to which this FirebaseFirestore
belongs.
public FirebaseFirestoreSettings getFirestoreSettings ()
Returns the settings used by this FirebaseFirestore
object.
public static FirebaseFirestore getInstance ()
public static FirebaseFirestore getInstance (FirebaseApp app)
public Task<Void> runBatch (WriteBatch.Function batchFunction)
Executes a batchFunction on a newly created WriteBatch
and then commits all of the writes made by the batchFunction as a single atomic
unit.
Parameters
batchFunction | The function to execute within the batch context. |
---|
Returns
- A Task that will be resolved when the batch has been committed.
public Task<TResult> runTransaction (Function<TResult> updateFunction)
Executes the given updateFunction and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, the updateFunction will be retried. If it fails to commit after 5 attempts, the transaction will fail.
Parameters
updateFunction | The function to execute within the transaction context. |
---|
Returns
- The task returned from the updateFunction.
public void setFirestoreSettings (FirebaseFirestoreSettings settings)
Sets any custom settings used to configure this FirebaseFirestore
object. This method can only be called before calling any other methods on this
object.
public static void setLoggingEnabled (boolean loggingEnabled)
Globally enables / disables Cloud Firestore logging for the SDK.
public Task<Void> terminate ()
Terminates this FirebaseFirestore
instance.
After calling terminate()
only the
clearPersistence()
method may be used. Any other method will throw an
IllegalStateException
.
To restart after termination, simply create a new instance of
FirebaseFirestore
with
getInstance()
or
getInstance(FirebaseApp)
.
terminate()
does not cancel any pending writes and any tasks that are
awaiting a response from the server will not be resolved. The next time you start this
instance, it will resume attempting to send these writes to the server.
Note: Under normal circumstances, calling terminate()
is not required.
This method is useful only when you want to force this instance to release all of its
resources or in combination with
clearPersistence()
to ensure that all local state is destroyed between test
runs.
Returns
- A
Task
that is resolved when the instance has been successfully terminated.
public void useEmulator (String host, int port)
Modifies this FirebaseDatabase instance to communicate with the Cloud Firestore emulator.
Note: Call this method before using the instance to do any database operations.
Parameters
host | the emulator host (for example, 10.0.2.2) |
---|---|
port | the emulator port (for example, 8080) |
public Task<Void> waitForPendingWrites ()
Waits until all currently pending writes for the active user have been acknowledged by the backend.
The returned Task completes immediately if there are no outstanding writes.
Otherwise, the Task waits for all previously issued writes (including those written in
a previous app session), but it does not wait for writes that were added after the
method is called. If you wish to wait for additional writes, you have to call
waitForPendingWrites()
again.
Any outstanding waitForPendingWrites()
Tasks are cancelled during user
changes.
Returns
- A
Task
which resolves when all currently pending writes have been acknowledged by the backend.