Create and document Java sync improved bulk write API

driver-core/src/main/com/mongodb/ClientBulkWriteException.java

@@ -0,0 +1,143 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * 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.mongodb;
+
+import com.mongodb.bulk.WriteConcernError;
+import com.mongodb.client.model.bulk.ClientWriteModel;
+import com.mongodb.client.result.bulk.ClientBulkWriteResult;
+import com.mongodb.lang.Nullable;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+import static com.mongodb.assertions.Assertions.isTrueArgument;
+import static java.util.Collections.emptyList;
+import static java.util.Collections.emptyMap;
+import static java.util.Collections.unmodifiableList;
+import static java.util.Collections.unmodifiableMap;
+import static java.util.Optional.ofNullable;
+
+/**
+ * The result of an unsuccessful or partially unsuccessful client-level bulk write operation.
+ *
+ * @see ClientBulkWriteResult
+ * @since 5.3
+ * @serial exclude
+ */
+public final class ClientBulkWriteException extends MongoServerException {
+    private static final long serialVersionUID = 1;
+
+    @Nullable
+    private final MongoException error;
+    private final List<WriteConcernError> writeConcernErrors;
+    private final Map<Long, WriteError> writeErrors;
+    @Nullable
+    private final ClientBulkWriteResult partialResult;
+
+    private ClientBulkWriteException(
+            final String message,
+            @Nullable final MongoException error,
+            @Nullable final List<WriteConcernError> writeConcernErrors,
+            @Nullable final Map<Long, WriteError> writeErrors,
+            @Nullable final ClientBulkWriteResult partialResult,
+            final ServerAddress serverAddress) {
+        super(message, serverAddress);
+        // BULK-TODO Should ClientBulkWriteException.getCode be the same as error.getCode,
+        // and getErrorLabels/hasErrorLabel contain the same labels as error.getErrorLabels?
+        this.error = error;
+        this.writeConcernErrors = writeConcernErrors == null ? emptyList() : unmodifiableList(writeConcernErrors);
+        this.writeErrors = writeErrors == null ? emptyMap() : unmodifiableMap(writeErrors);
+        this.partialResult = partialResult;
+    }
+
+    /**
+     * Creates a {@link ClientBulkWriteException}.
+     * At least one of {@code error}, {@code writeConcernErrors}, {@code writeErrors}, {@code partialResult}
+     * must be non-{@code null} or non-empty.
+     *
+     * @param error The {@linkplain #getError() top-level error}.
+     * @param writeConcernErrors The {@linkplain #getWriteConcernErrors() write concern errors}.
+     * @param writeErrors The {@linkplain #getWriteErrors() write errors}.
+     * @param partialResult The {@linkplain #getPartialResult() partial result}.
+     * @param serverAddress The {@linkplain MongoServerException#getServerAddress() server address}.
+     * @return The requested {@link ClientBulkWriteException}.
+     */
+    public static ClientBulkWriteException create(
+            @Nullable final MongoException error,
+            @Nullable final List<WriteConcernError> writeConcernErrors,
+            @Nullable final Map<Long, WriteError> writeErrors,
+            @Nullable final ClientBulkWriteResult partialResult,
+            final ServerAddress serverAddress) {
+        isTrueArgument("At least one of `writeConcernErrors`, `writeErrors`, `partialResult` must be non-null or non-empty",
+                !(writeConcernErrors == null || writeConcernErrors.isEmpty())
+                || !(writeErrors == null || writeErrors.isEmpty())
+                || partialResult != null);
+        String message = "Client-level bulk write operation error on server " + serverAddress + "."
+                + (error == null ? "" : " Top-level error: " + error + ".")
+                + (writeErrors == null || writeErrors.isEmpty() ? "" : " Write errors: " + writeErrors + ".")
+                + (writeConcernErrors == null || writeConcernErrors.isEmpty() ? "" : " Write concern errors: " + writeConcernErrors + ".")
+                + (partialResult == null ? "" : " Partial result: " + partialResult + ".");
+        return new ClientBulkWriteException(message, error, writeConcernErrors, writeErrors, partialResult, serverAddress);
+    }
+
+    /**
+     * The top-level error. That is an error that is neither a {@linkplain #getWriteConcernErrors() write concern error},
+     * nor is an {@linkplain #getWriteErrors() error of an individual write operation}.
+     *
+     * @return The top-level error. {@linkplain Optional#isPresent() Present} only if a top-level error occurred.
+     */
+    public Optional<MongoException> getError() {
+        return ofNullable(error);
+    }
+
+    /**
+     * The {@link WriteConcernError}s that occurred while executing the client-level bulk write operation.
+     * <p>
+     * There are no guarantees on mutability of the {@link List} returned.</p>
+     *
+     * @return The {@link WriteConcernError}s.
+     */
+    public List<WriteConcernError> getWriteConcernErrors() {
+        return writeConcernErrors;
+    }
+
+    /**
+     * The indexed {@link WriteError}s.
+     * The {@linkplain Map#keySet() keys} are the indexes of the corresponding {@link ClientWriteModel}s
+     * in the corresponding client-level bulk write operation.
+     * <p>
+     * There are no guarantees on mutability or iteration order of the {@link Map} returned.</p>
+     *
+     * @return The indexed {@link WriteError}s.
+     * @see ClientBulkWriteResult#getInsertResults()
+     * @see ClientBulkWriteResult#getUpdateResults()
+     * @see ClientBulkWriteResult#getDeleteResults()
+     */
+    public Map<Long, WriteError> getWriteErrors() {
+        return writeErrors;
+    }
+
+    /**
+     * The result of the successful part of a client-level bulk write operation.
+     *
+     * @return The successful partial result. {@linkplain Optional#isPresent() Present} only if at least one
+     * {@linkplain ClientWriteModel individual write operation} succeed.
+     */
+    public Optional<ClientBulkWriteResult> getPartialResult() {
+        return ofNullable(partialResult);
+    }
+}

driver-core/src/main/com/mongodb/client/model/bulk/ClientBulkWriteOptions.java

@@ -0,0 +1,91 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * 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.mongodb.client.model.bulk;
+
+import com.mongodb.annotations.Sealed;
+import com.mongodb.client.model.Filters;
+import com.mongodb.client.result.bulk.ClientBulkWriteResult;
+import com.mongodb.internal.client.model.bulk.ConcreteClientBulkWriteOptions;
+import com.mongodb.lang.Nullable;
+import org.bson.BsonValue;
+import org.bson.conversions.Bson;
+
+/**
+ * The options to apply when executing a client-level bulk write operation.
+ *
+ * @since 5.3
+ */
+@Sealed
+public interface ClientBulkWriteOptions {
+    /**
+     * Creates the default options.
+     *
+     * @return The default options.
+     */
+    static ClientBulkWriteOptions clientBulkWriteOptions() {
+        return new ConcreteClientBulkWriteOptions();
+    }
+
+    /**
+     * Enables or disables ordered execution of {@linkplain ClientWriteModel individual write operations}.
+     * In an ordered execution a failure of an individual operation prevents the rest of them
+     * from being executed.
+     * In an unordered execution failures of individual operations do not prevent the rest of them
+     * from being executed.
+     *
+     * @param ordered The ordered flag. If {@code null}, the client defaults to {@code true}.
+     * @return {@code this}.
+     */
+    ClientBulkWriteOptions ordered(@Nullable Boolean ordered);
+
+    /**
+     * Disables or enables checking against document validation rules, a.k.a., schema validation.
+     *
+     * @param bypassDocumentValidation The flag specifying whether to bypass the document validation rules.
+     * {@code null} represents the server default.
+     * @return {@code this}.
+     */
+    ClientBulkWriteOptions bypassDocumentValidation(@Nullable Boolean bypassDocumentValidation);
+
+    /**
+     * Sets variables that can be referenced from {@linkplain ClientWriteModel individual write operations}
+     * with the {@code "$$"} syntax, which in turn requires using {@link Filters#expr(Object)} when specifying filters.
+     * Values must be constants or expressions that do not reference fields.
+     *
+     * @param let The variables. {@code null} represents the server default.
+     * @return {@code this}.
+     * @mongodb.driver.manual reference/aggregation-variables/ Variables in Aggregation Expressions
+     */
+    ClientBulkWriteOptions let(@Nullable Bson let);
+
+    /**
+     * Sets the comment to attach to the {@code bulkWrite} administration command.
+     *
+     * @param comment The comment. {@code null} represents the server default.
+     * @return {@code this}.
+     */
+    ClientBulkWriteOptions comment(@Nullable BsonValue comment);
+
+    /**
+     * Enables or disables requesting {@linkplain ClientBulkWriteResult#hasVerboseResults() verbose results}.
+     *
+     * @param verboseResults The flag specifying whether to request verbose results.
+     * If {@code null}, the client defaults to {@code false}.
+     * This value corresponds inversely to the {@code errorsOnly} field of the {@code bulkWrite} administration command.
+     * @return {@code this}.
+     */
+    ClientBulkWriteOptions verboseResults(@Nullable Boolean verboseResults);
+}

driver-core/src/main/com/mongodb/client/model/bulk/ClientDeleteOptions.java

@@ -0,0 +1,65 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * 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.mongodb.client.model.bulk;
+
+import com.mongodb.annotations.Sealed;
+import com.mongodb.client.model.Collation;
+import com.mongodb.internal.client.model.bulk.ConcreteClientDeleteOptions;
+import com.mongodb.lang.Nullable;
+import org.bson.conversions.Bson;
+
+/**
+ * The options to apply when deleting documents.
+ *
+ * @since 5.3
+ */
+@Sealed
+public interface ClientDeleteOptions {
+    /**
+     * Creates the default options.
+     *
+     * @return The default options.
+     */
+    static ClientDeleteOptions clientDeleteOptions() {
+        return new ConcreteClientDeleteOptions();
+    }
+
+    /**
+     * Sets the collation.
+     *
+     * @param collation The collation. {@code null} represents the server default.
+     * @return {@code this}.
+     */
+    ClientDeleteOptions collation(@Nullable Collation collation);
+
+    /**
+     * Sets the index specification,
+     * {@code null}-ifies {@linkplain #hintString(String) hint string}.
+     *
+     * @param hint The index specification. {@code null} represents the server default.
+     * @return {@code this}.
+     */
+    ClientDeleteOptions hint(@Nullable Bson hint);
+
+    /**
+     * Sets the index name,
+     * {@code null}-ifies {@linkplain #hint(Bson) hint}.
+     *
+     * @param hintString The index name. {@code null} represents the server default.
+     * @return {@code this}.
+     */
+    ClientDeleteOptions hintString(@Nullable String hintString);
+}

driver-core/src/main/com/mongodb/client/model/bulk/ClientReplaceOptions.java

@@ -0,0 +1,73 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * 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.mongodb.client.model.bulk;
+
+import com.mongodb.annotations.Sealed;
+import com.mongodb.client.model.Collation;
+import com.mongodb.internal.client.model.bulk.ConcreteClientReplaceOptions;
+import com.mongodb.lang.Nullable;
+import org.bson.conversions.Bson;
+
+/**
+ * The options to apply when replacing documents.
+ *
+ * @since 5.3
+ */
+@Sealed
+public interface ClientReplaceOptions {
+    /**
+     * Creates the default options.
+     *
+     * @return The default options.
+     */
+    static ClientReplaceOptions clientReplaceOptions() {
+        return new ConcreteClientReplaceOptions();
+    }
+
+    /**
+     * Sets the collation.
+     *
+     * @param collation The collation. {@code null} represents the server default.
+     * @return {@code this}.
+     */
+    ClientReplaceOptions collation(@Nullable Collation collation);
+
+    /**
+     * Sets the index specification,
+     * {@code null}-ifies {@linkplain #hintString(String) hint string}.
+     *
+     * @param hint The index specification. {@code null} represents the server default.
+     * @return {@code this}.
+     */
+    ClientReplaceOptions hint(@Nullable Bson hint);
+
+    /**
+     * Sets the index name,
+     * {@code null}-ifies {@linkplain #hint(Bson) hint}.
+     *
+     * @param hintString The index name. {@code null} represents the server default.
+     * @return {@code this}.
+     */
+    ClientReplaceOptions hintString(@Nullable String hintString);
+
+    /**
+     * Enables or disables creation of a document if no documents match the filter.
+     *
+     * @param upsert The upsert flag. {@code null} represents the server default.
+     * @return {@code this}.
+     */
+    ClientReplaceOptions upsert(@Nullable Boolean upsert);
+}