BenWhitehead commented on a change in pull request #14261: URL: https://github.com/apache/beam/pull/14261#discussion_r597968767
########## File path: sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/firestore/FirestoreV1.java ########## @@ -0,0 +1,610 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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 org.apache.beam.sdk.io.gcp.firestore; + +import static java.util.Objects.requireNonNull; + +import com.google.firestore.v1.BatchWriteRequest; +import com.google.firestore.v1.WriteResult; +import com.google.rpc.Status; +import java.io.Serializable; +import java.util.List; +import java.util.Objects; +import javax.annotation.concurrent.Immutable; +import org.apache.beam.sdk.io.gcp.firestore.FirestoreV1WriteFn.BatchWriteFnWithDeadLetterQueue; +import org.apache.beam.sdk.io.gcp.firestore.FirestoreV1WriteFn.DefaultBatchWriteFn; +import org.apache.beam.sdk.transforms.PTransform; +import org.apache.beam.sdk.transforms.ParDo; +import org.apache.beam.sdk.transforms.Reshuffle; +import org.apache.beam.sdk.transforms.display.DisplayData; +import org.apache.beam.sdk.transforms.display.HasDisplayData; +import org.apache.beam.sdk.values.PCollection; +import org.apache.beam.sdk.values.PDone; +import org.apache.beam.sdk.values.PInput; +import org.apache.beam.sdk.values.POutput; +import org.checkerframework.checker.nullness.qual.Nullable; + +/** + * {@link FirestoreV1} provides an API which provides lifecycle managed {@link PTransform}s for + * <a href="https://cloud.google.com/firestore/docs/reference/rpc/google.firestore.v1";>Cloud + * Firestore v1 API</a>. + * <p/> + * This class is part of the Firestore Connector DSL and should be accessed via {@link + * FirestoreIO#v1()}. + * <p/> + * All {@link PTransform}s provided by this API use {@link org.apache.beam.sdk.extensions.gcp.options.GcpOptions + * GcpOptions} on {@link org.apache.beam.sdk.options.PipelineOptions PipelineOptions} for + * credentials access and projectId resolution. As such, the lifecycle of gRPC clients and project + * information is scoped to the bundle level, not the worker level. + * <p/> + * + * <h3>Permissions</h3> + * + * Permission requirements depend on the {@code PipelineRunner} that is used to execute the + * pipeline. Please refer to the documentation of corresponding {@code PipelineRunner}s for more + * details. + * + * <p>Please see <a href="https://cloud.google.com/firestore/docs/quickstart-servers#create_a_in_native_mode_database";>Create + * a Firestore in Native mode database + * </a>for security and permission related information specific to Cloud Firestore. + * + * <p>Optionally, Cloud Firestore V1 Emulator, running locally, could be used for testing purposes + * by providing the host port information vi {@link FirestoreIOOptions#setEmulatorHostPort(String)}. + * In such a case, all the Cloud Firestore API calls are directed to the Emulator. + * + * @see FirestoreIO#v1() + * @see org.apache.beam.sdk.PipelineRunner + * @see org.apache.beam.sdk.options.PipelineOptions + * @see org.apache.beam.sdk.extensions.gcp.options.GcpOptions + * @see <a href="https://cloud.google.com/firestore/docs/reference/rpc/google.firestore.v1";>Cloud + * Firestore v1 API</a> + */ +@Immutable +public final class FirestoreV1 { + static final FirestoreV1 INSTANCE = new FirestoreV1(); + + private FirestoreV1() {} + + /** + * The class returned by this method provides the ability to create {@link PTransform PTransforms} + * for write operations available in the Firestore V1 API provided by {@link + * com.google.cloud.firestore.spi.v1.FirestoreRpc FirestoreRpc}. + * <p/> + * This method is part of the Firestore Connector DSL and should be accessed via {@link + * FirestoreIO#v1()}. + * <p/> + * + * @return Type safe builder factory for write operations. + * @see FirestoreIO#v1() + */ + public final Write write() { + return Write.INSTANCE; + } + + /** + * Type safe builder factory for write operations. + * <p/> + * This class is part of the Firestore Connector DSL and should be accessed via {@link #write() + * FirestoreIO.v1().write()}. + * <p/> + * <p/> + * This class provides access to a set of type safe builders for supported write operations + * available in the Firestore V1 API accessed through {@link com.google.cloud.firestore.spi.v1.FirestoreRpc + * FirestoreRpc}. Each builder allows configuration before creating an immutable instance which + * can be used in your pipeline. + * + * @see FirestoreIO#v1() + * @see #write() + */ + @Immutable + public static final class Write { + private static final Write INSTANCE = new Write(); + + private Write() {} + + /** + * Factory method to create a new type safe builder for {@link com.google.firestore.v1.Write} + * operations. + * <p/> + * By default, when an error is encountered while trying to write to Cloud Firestore a {@link + * FailedWritesException} will be thrown. If you would like a failed write to not result in a + * {@link FailedWritesException}, you can instead use {@link BatchWriteWithDeadLetterQueue} which + * will output any failed write. {@link BatchWriteWithDeadLetterQueue} can be used by + * including {@link BatchWrite.Builder#withDeadLetterQueue()} when constructing the write handler. + * <p/> + * This method is part of the Firestore Connector DSL and should be accessed via {@link + * FirestoreIO#v1()}. + * <p/> + * + * <b>Example Usage</b> Review comment: Done -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected]
