/
Firestore.java
178 lines (162 loc) · 7.35 KB
/
Firestore.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
/*
* Copyright 2017 Google LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.google.cloud.firestore;
import com.google.api.core.ApiFuture;
import com.google.api.core.InternalExtensionOnly;
import com.google.api.gax.rpc.ApiStreamObserver;
import com.google.cloud.Service;
import java.util.List;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
/** Represents a Firestore Database and is the entry point for all Firestore operations */
@InternalExtensionOnly
public interface Firestore extends Service<FirestoreOptions>, AutoCloseable {
/**
* Gets a {@link CollectionReference} that refers to the collection at the specified path.
*
* @param path A slash-separated path to a collection.
* @return The CollectionReference instance.
*/
@Nonnull
CollectionReference collection(@Nonnull String path);
/**
* Gets a {@link DocumentReference} that refers to the document at the specified path.
*
* @param path A slash-separated path to a document.
* @return The DocumentReference instance.
*/
@Nonnull
DocumentReference document(@Nonnull String path);
/**
* Fetches the root collections that are associated with this Firestore database.
*
* @throws FirestoreException if the Iterable could not be initialized.
* @return An Iterable that can be used to fetch all collections.
*/
@Nonnull
Iterable<CollectionReference> listCollections();
/**
* Creates and returns a new @link{Query} that includes all documents in the database that are
* contained in a collection or subcollection with the given @code{collectionId}.
*
* @param 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.
* @return The created Query.
*/
Query collectionGroup(@Nonnull String collectionId);
/**
* 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.
*
* @param updateFunction The function to execute within the transaction context.
* @return An ApiFuture that will be resolved with the result from updateFunction.
*/
@Nonnull
<T> ApiFuture<T> runTransaction(@Nonnull final Transaction.Function<T> 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 the maxmimum number of attemps specified in
* transactionOptions, the transaction will fail.
*
* @param updateFunction The function to execute within the transaction context.
* @return An ApiFuture that will be resolved with the result from updateFunction.
*/
@Nonnull
<T> ApiFuture<T> runTransaction(
@Nonnull final Transaction.Function<T> updateFunction,
@Nonnull TransactionOptions transactionOptions);
/**
* 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. <br>
* <br>
* Running a transaction places locks all consumed documents. To unblock other clients, the
* Firestore backend automatically releases all locks after 60 seconds of inactivity and fails all
* transactions that last longer than 270 seconds (see <a
* href="https://firebase.google.com/docs/firestore/quotas#writes_and_transactions">Firestore
* Quotas</a>).
*
* @param updateFunction The function to execute within the transaction context.
* @return An ApiFuture that will be resolved with the result from updateFunction.
*/
@Nonnull
<T> ApiFuture<T> runAsyncTransaction(@Nonnull final Transaction.AsyncFunction<T> 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 the maxmimum number of attemps specified in
* transactionOptions, the transaction will fail. <br>
* <br>
* Running a transaction places locks all consumed documents. To unblock other clients, the
* Firestore backend automatically releases all locks after 60 seconds of inactivity and fails all
* transactions that last longer than 270 seconds (see <a
* href="https://firebase.google.com/docs/firestore/quotas#writes_and_transactions">Firestore
* Quotas</a>).
*
* @param updateFunction The function to execute within the transaction context.
* @return An ApiFuture that will be resolved with the result from updateFunction.
*/
@Nonnull
<T> ApiFuture<T> runAsyncTransaction(
@Nonnull final Transaction.AsyncFunction<T> updateFunction,
@Nonnull TransactionOptions transactionOptions);
/**
* Retrieves multiple documents from Firestore.
*
* @param documentReferences List of Document References to fetch.
*/
@Nonnull
ApiFuture<List<DocumentSnapshot>> getAll(@Nonnull DocumentReference... documentReferences);
/**
* Retrieves multiple documents from Firestore, while optionally applying a field mask to reduce
* the amount of data transmitted.
*
* @param documentReferences Array with Document References to fetch.
* @param fieldMask If set, specifies the subset of fields to return.
*/
@Nonnull
ApiFuture<List<DocumentSnapshot>> getAll(
@Nonnull DocumentReference[] documentReferences, @Nullable FieldMask fieldMask);
/**
* Retrieves multiple documents from Firestore while optionally applying a field mask to reduce
* the amount of data transmitted. Returned documents will be out of order.
*
* @param documentReferences Array with Document References to fetch.
* @param fieldMask If not null, specifies the subset of fields to return.
* @param responseObserver The observer to be notified when {@link DocumentSnapshot} details
* arrive.
*/
void getAll(
@Nonnull DocumentReference[] documentReferences,
@Nullable FieldMask fieldMask,
final ApiStreamObserver<DocumentSnapshot> responseObserver);
/**
* Gets a Firestore {@link WriteBatch} instance that can be used to combine multiple writes.
*
* @return A WriteBatch that operates on this Firestore client.
*/
@Nonnull
WriteBatch batch();
/**
* Closes the gRPC channels associated with this instance and frees up their resources. This
* method blocks until all channels are closed. Once this method is called, this Firestore client
* is no longer usable.
*/
@Override
void close() throws Exception;
}