/// <summary> /// Fetches document snapshots from the server, based on an optional transaction ID. /// </summary> /// <param name="documents">The document references to fetch. Must not be null, or contain null references.</param> /// <param name="transactionId">A transaction ID, or null to not include any transaction ID.</param> /// <param name="fieldMask">The field mask to use to restrict which fields are retrieved. May be null, in which /// case no field mask is applied, and the complete documents are retrieved.</param> /// <param name="cancellationToken">A cancellation token for the operation.</param> /// <returns>The document snapshots, in the order they are provided in the response. (This may not be the order of <paramref name="documents"/>.)</returns> internal async Task <IList <DocumentSnapshot> > GetDocumentSnapshotsAsync(IEnumerable <DocumentReference> documents, ByteString transactionId, FieldMask fieldMask, CancellationToken cancellationToken) { GaxPreconditions.CheckNotNull(documents, nameof(documents)); var request = new BatchGetDocumentsRequest { Database = RootPath, Documents = { documents.Select(ExtractPath) }, Mask = fieldMask?.ToProto() }; if (transactionId != null) { request.Transaction = transactionId; } var stream = Client.BatchGetDocuments(request, CallSettings.FromCancellationToken(cancellationToken)); using (var responseStream = stream.ResponseStream) { List <DocumentSnapshot> snapshots = new List <DocumentSnapshot>(); // Note: no need to worry about passing the cancellation token in here, as we've passed it into the overall call. // If the token is cancelled, the call will be aborted. while (await responseStream.MoveNext().ConfigureAwait(false)) { var response = responseStream.Current; var readTime = Timestamp.FromProto(response.ReadTime); switch (response.ResultCase) { case BatchGetDocumentsResponse.ResultOneofCase.Found: snapshots.Add(DocumentSnapshot.ForDocument(this, response.Found, readTime)); break; case BatchGetDocumentsResponse.ResultOneofCase.Missing: snapshots.Add(DocumentSnapshot.ForMissingDocument(this, response.Missing, readTime)); break; default: throw new InvalidOperationException($"Unknown response type: {response.ResultCase}"); } } return(snapshots); } string ExtractPath(DocumentReference documentReference) { GaxPreconditions.CheckArgument(documentReference != null, nameof(documents), "DocumentReference sequence must not contain null elements."); return(documentReference.Path); } }
/// <summary> /// Watch this document for changes. /// </summary> /// <param name="callback">The callback to invoke each time the document changes. Must not be null.</param> /// <param name="cancellationToken">Optional cancellation token which may be used to cancel the listening operation.</param> /// <returns>A <see cref="FirestoreChangeListener"/> which may be used to monitor the listening operation and stop it gracefully.</returns> public FirestoreChangeListener Listen(Func <DocumentSnapshot, CancellationToken, Task> callback, CancellationToken cancellationToken = default) { GaxPreconditions.CheckNotNull(callback, nameof(callback)); var target = WatchStream.CreateTarget(this); Func <QuerySnapshot, CancellationToken, Task> queryCallback = async(querySnapshot, localCancellationToken) => { foreach (var doc in querySnapshot) { if (doc.Reference.Equals(this)) { await callback(doc, localCancellationToken).ConfigureAwait(false); return; } } // TODO: This will mean parsing the path back to a DocumentReference. Maybe we should accept "this". var missingDoc = DocumentSnapshot.ForMissingDocument(Database, Path, querySnapshot.ReadTime); await callback(missingDoc, cancellationToken).ConfigureAwait(false); }; var stream = new WatchStream(new WatchState(Parent, queryCallback), target, Database, cancellationToken); return(FirestoreChangeListener.Start(stream)); }
/// <summary> /// Fetches document snapshots from the server, based on an optional transaction ID. /// </summary> /// <param name="documents">The document references to fetch. Must not be null, or contain null references.</param> /// <param name="transactionId">A transaction ID, or null to not include any transaction ID.</param> /// <param name="fieldMask">The field mask to use to restrict which fields are retrieved. May be null, in which /// case no field mask is applied, and the complete documents are retrieved.</param> /// <param name="cancellationToken">A cancellation token for the operation.</param> /// <returns>The document snapshots, in the order they are provided in the response. (This may not be the order of <paramref name="documents"/>.)</returns> internal async Task <IList <DocumentSnapshot> > GetDocumentSnapshotsAsync(IEnumerable <DocumentReference> documents, ByteString transactionId, FieldMask fieldMask, CancellationToken cancellationToken) { GaxPreconditions.CheckNotNull(documents, nameof(documents)); var request = new BatchGetDocumentsRequest { Database = RootPath, Documents = { documents.Select(ExtractPath) }, Mask = fieldMask?.ToProto() }; if (transactionId != null) { request.Transaction = transactionId; } var clock = Client.Settings.Clock ?? SystemClock.Instance; var scheduler = Client.Settings.Scheduler ?? SystemScheduler.Instance; var callSettings = _batchGetCallSettings.WithCancellationToken(cancellationToken); // This is the function that we'll retry. We can't use the built-in retry functionality, because it's not a unary gRPC call. // (We could potentially simulate a unary call, but it would be a little odd to do so.) // Note that we perform a "whole request" retry. In theory we could collect some documents, then see an error, and only // request the remaining documents. Given how rarely we retry anyway in practice, that's probably not worth doing. Func <BatchGetDocumentsRequest, CallSettings, Task <List <DocumentSnapshot> > > function = async(req, settings) => { var stream = Client.BatchGetDocuments(req, settings); using (var responseStream = stream.ResponseStream) { List <DocumentSnapshot> snapshots = new List <DocumentSnapshot>(); // Note: no need to worry about passing the cancellation token in here, as we've passed it into the overall call. // If the token is cancelled, the call will be aborted. while (await responseStream.MoveNext().ConfigureAwait(false)) { var response = responseStream.Current; var readTime = Timestamp.FromProto(response.ReadTime); switch (response.ResultCase) { case BatchGetDocumentsResponse.ResultOneofCase.Found: snapshots.Add(DocumentSnapshot.ForDocument(this, response.Found, readTime)); break; case BatchGetDocumentsResponse.ResultOneofCase.Missing: snapshots.Add(DocumentSnapshot.ForMissingDocument(this, response.Missing, readTime)); break; default: throw new InvalidOperationException($"Unknown response type: {response.ResultCase}"); } } return(snapshots); } }; var retryingTask = RetryHelper.Retry(function, request, callSettings, clock, scheduler); return(await retryingTask.ConfigureAwait(false)); string ExtractPath(DocumentReference documentReference) { GaxPreconditions.CheckArgument(documentReference != null, nameof(documents), "DocumentReference sequence must not contain null elements."); return(documentReference.Path); } }