-
Notifications
You must be signed in to change notification settings - Fork 1.5k
Create and document Java sync improved bulk write API #1458
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 28 commits
48b9614
af854ed
1eb7466
5567324
644d561
f566303
3d13ffd
cf46b46
e049234
0e16427
0d518d8
6b77f78
fdb90d2
39386fe
f67af3f
395af7a
a11e5f6
f41ed59
4846e0b
dbf9a26
21bb22e
f026ee3
3584de5
5a17ea0
8e1d770
e973615
e33f592
301a2ba
6f01e61
c3224e9
c057390
dbb6ec8
f781bca
3fc86bb
86e5234
fb134f8
a4bf4d0
2837235
b6702a6
24ce6db
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,138 @@ | ||
/* | ||
* 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.ClientBulkWriteResult; | ||
import com.mongodb.client.model.bulk.ClientNamespacedWriteModel; | ||
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. | ||
* Note that the {@linkplain #getCode() code} and {@linkplain #getErrorLabels() labels} from this exception are not useful. | ||
* An application should use those from the {@linkplain #getError() top-level error}. | ||
* | ||
* @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<Integer, WriteError> writeErrors; | ||
@Nullable | ||
private final ClientBulkWriteResult partialResult; | ||
|
||
/** | ||
* Constructs a new instance. | ||
* | ||
* @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}. | ||
*/ | ||
public ClientBulkWriteException( | ||
@Nullable final MongoException error, | ||
@Nullable final List<WriteConcernError> writeConcernErrors, | ||
@Nullable final Map<Integer, WriteError> writeErrors, | ||
@Nullable final ClientBulkWriteResult partialResult, | ||
final ServerAddress serverAddress) { | ||
super(message(error, writeConcernErrors, writeErrors, partialResult, 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); | ||
this.error = error; | ||
this.writeConcernErrors = writeConcernErrors == null ? emptyList() : unmodifiableList(writeConcernErrors); | ||
this.writeErrors = writeErrors == null ? emptyMap() : unmodifiableMap(writeErrors); | ||
this.partialResult = partialResult; | ||
} | ||
|
||
private static String message( | ||
@Nullable final MongoException error, | ||
@Nullable final List<WriteConcernError> writeConcernErrors, | ||
@Nullable final Map<Integer, WriteError> writeErrors, | ||
@Nullable final ClientBulkWriteResult partialResult, | ||
final ServerAddress serverAddress) { | ||
return "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 + "."); | ||
} | ||
|
||
/** | ||
* 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. | ||
*/ | ||
vbabanin marked this conversation as resolved.
Show resolved
Hide resolved
|
||
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 ClientNamespacedWriteModel}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.Verbose#getInsertResults() | ||
* @see ClientBulkWriteResult.Verbose#getUpdateResults() | ||
* @see ClientBulkWriteResult.Verbose#getDeleteResults() | ||
*/ | ||
public Map<Integer, 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 ClientNamespacedWriteModel individual write operation} succeed. | ||
*/ | ||
public Optional<ClientBulkWriteResult> getPartialResult() { | ||
stIncMale marked this conversation as resolved.
Show resolved
Hide resolved
|
||
return ofNullable(partialResult); | ||
} | ||
} |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,90 @@ | ||
/* | ||
* 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.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 { | ||
jyemin marked this conversation as resolved.
Show resolved
Hide resolved
|
||
/** | ||
* Creates the default options. | ||
* | ||
* @return The default options. | ||
*/ | ||
static ClientBulkWriteOptions clientBulkWriteOptions() { | ||
return new ConcreteClientBulkWriteOptions(); | ||
} | ||
|
||
/** | ||
* Enables or disables ordered execution of {@linkplain ClientNamespacedWriteModel 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 ClientNamespacedWriteModel 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#getVerbose() 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); | ||
} |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,137 @@ | ||
/* | ||
* 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.ClientBulkWriteException; | ||
import com.mongodb.WriteConcern; | ||
import com.mongodb.annotations.Evolving; | ||
import com.mongodb.bulk.WriteConcernError; | ||
|
||
import java.util.Map; | ||
import java.util.Optional; | ||
|
||
/** | ||
* The result of a successful or partially successful client-level bulk write operation. | ||
* Note that if only some of the {@linkplain ClientNamespacedWriteModel individual write operations} succeed, | ||
* or if there are {@link WriteConcernError}s, then the successful partial result | ||
* is still accessible via {@link ClientBulkWriteException#getPartialResult()}. | ||
* | ||
* @see ClientBulkWriteException | ||
* @since 5.3 | ||
*/ | ||
@Evolving | ||
public interface ClientBulkWriteResult { | ||
/** | ||
* Indicated whether this result was {@linkplain WriteConcern#isAcknowledged() acknowledged}. | ||
stIncMale marked this conversation as resolved.
Show resolved
Hide resolved
|
||
* If not, then all other methods throw {@link UnsupportedOperationException}. | ||
* | ||
* @return Whether this result was acknowledged. | ||
*/ | ||
boolean isAcknowledged(); | ||
|
||
/** | ||
* The number of documents that were inserted across all insert operations. | ||
* | ||
* @return The number of documents that were inserted. | ||
* @throws UnsupportedOperationException If this result is not {@linkplain #isAcknowledged() acknowledged}. | ||
*/ | ||
long getInsertedCount(); | ||
|
||
/** | ||
* The number of documents that were upserted across all update and replace operations. | ||
* | ||
* @return The number of documents that were upserted. | ||
* @throws UnsupportedOperationException If this result is not {@linkplain #isAcknowledged() acknowledged}. | ||
*/ | ||
long getUpsertedCount(); | ||
|
||
/** | ||
* The number of documents that matched the filters across all operations with filters. | ||
* | ||
* @return The number of documents that were matched. | ||
* @throws UnsupportedOperationException If this result is not {@linkplain #isAcknowledged() acknowledged}. | ||
*/ | ||
long getMatchedCount(); | ||
|
||
/** | ||
* The number of documents that were modified across all update and replace operations. | ||
* | ||
* @return The number of documents that were modified. | ||
* @throws UnsupportedOperationException If this result is not {@linkplain #isAcknowledged() acknowledged}. | ||
*/ | ||
long getModifiedCount(); | ||
|
||
/** | ||
* The number of documents that were deleted across all delete operations. | ||
* | ||
* @return The number of documents that were deleted. | ||
* @throws UnsupportedOperationException If this result is not {@linkplain #isAcknowledged() acknowledged}. | ||
*/ | ||
long getDeletedCount(); | ||
|
||
/** | ||
* The verbose results of individual operations. | ||
* | ||
* @return {@link Optional} verbose results of individual operations. | ||
* @throws UnsupportedOperationException If this result is not {@linkplain #isAcknowledged() acknowledged}. | ||
* @see ClientBulkWriteOptions#verboseResults(Boolean) | ||
*/ | ||
Optional<Verbose> getVerbose(); | ||
|
||
/** | ||
* The {@linkplain ClientBulkWriteResult#getVerbose() verbose results} of individual operations. | ||
* | ||
* @since 5.3 | ||
*/ | ||
@Evolving | ||
interface Verbose { | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. While I would suggest noun-based naming, just couple of examples: There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Done in b6702a6. |
||
/** | ||
* The indexed {@link ClientInsertOneResult}s. | ||
* The {@linkplain Map#keySet() keys} are the indexes of the corresponding {@link ClientNamespacedWriteModel}s | ||
* in the 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 ClientInsertOneResult}s. | ||
* @see ClientBulkWriteException#getWriteErrors() | ||
*/ | ||
Map<Integer, ClientInsertOneResult> getInsertResults(); | ||
|
||
/** | ||
* The indexed {@link ClientUpdateResult}s. | ||
* The {@linkplain Map#keySet() keys} are the indexes of the corresponding {@link ClientNamespacedWriteModel}s | ||
* in the 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 ClientUpdateResult}s. | ||
* @see ClientBulkWriteException#getWriteErrors() | ||
*/ | ||
Map<Integer, ClientUpdateResult> getUpdateResults(); | ||
|
||
/** | ||
* The indexed {@link ClientDeleteResult}s. | ||
* The {@linkplain Map#keySet() keys} are the indexes of the corresponding {@link ClientNamespacedWriteModel}s | ||
* in the 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 ClientDeleteResult}s. | ||
* @see ClientBulkWriteException#getWriteErrors() | ||
*/ | ||
Map<Integer, ClientDeleteResult> getDeleteResults(); | ||
} | ||
} |
Uh oh!
There was an error while loading. Please reload this page.