Skip to content

Commit ce34eee

Browse files
stIncMalevbabanin
stIncMale
and
vbabanin
authored
Create and document Java sync improved bulk write API (#1458)
JAVA-5527 DRIVERS-2975 --------- Co-authored-by: Viacheslav Babanin <[email protected]>
1 parent c717171 commit ce34eee

File tree

55 files changed

+3262
-10
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

55 files changed

+3262
-10
lines changed

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

+138
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
/*
2+
* Copyright 2008-present MongoDB, Inc.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package com.mongodb;
17+
18+
import com.mongodb.bulk.WriteConcernError;
19+
import com.mongodb.client.model.bulk.ClientBulkWriteResult;
20+
import com.mongodb.client.model.bulk.ClientNamespacedWriteModel;
21+
import com.mongodb.lang.Nullable;
22+
23+
import java.util.List;
24+
import java.util.Map;
25+
import java.util.Optional;
26+
27+
import static com.mongodb.assertions.Assertions.isTrueArgument;
28+
import static java.util.Collections.emptyList;
29+
import static java.util.Collections.emptyMap;
30+
import static java.util.Collections.unmodifiableList;
31+
import static java.util.Collections.unmodifiableMap;
32+
import static java.util.Optional.ofNullable;
33+
34+
/**
35+
* The result of an unsuccessful or partially unsuccessful client-level bulk write operation.
36+
* Note that the {@linkplain #getCode() code} and {@linkplain #getErrorLabels() labels} from this exception are not useful.
37+
* An application should use those from the {@linkplain #getError() top-level error}.
38+
*
39+
* @see ClientBulkWriteResult
40+
* @since 5.3
41+
* @serial exclude
42+
*/
43+
public final class ClientBulkWriteException extends MongoServerException {
44+
private static final long serialVersionUID = 1;
45+
46+
@Nullable
47+
private final MongoException error;
48+
private final List<WriteConcernError> writeConcernErrors;
49+
private final Map<Integer, WriteError> writeErrors;
50+
@Nullable
51+
private final ClientBulkWriteResult partialResult;
52+
53+
/**
54+
* Constructs a new instance.
55+
*
56+
* @param error The {@linkplain #getError() top-level error}.
57+
* @param writeConcernErrors The {@linkplain #getWriteConcernErrors() write concern errors}.
58+
* @param writeErrors The {@linkplain #getWriteErrors() write errors}.
59+
* @param partialResult The {@linkplain #getPartialResult() partial result}.
60+
* @param serverAddress The {@linkplain MongoServerException#getServerAddress() server address}.
61+
*/
62+
public ClientBulkWriteException(
63+
@Nullable final MongoException error,
64+
@Nullable final List<WriteConcernError> writeConcernErrors,
65+
@Nullable final Map<Integer, WriteError> writeErrors,
66+
@Nullable final ClientBulkWriteResult partialResult,
67+
final ServerAddress serverAddress) {
68+
super(message(error, writeConcernErrors, writeErrors, partialResult, serverAddress), serverAddress);
69+
isTrueArgument("At least one of `writeConcernErrors`, `writeErrors`, `partialResult` must be non-null or non-empty",
70+
!(writeConcernErrors == null || writeConcernErrors.isEmpty())
71+
|| !(writeErrors == null || writeErrors.isEmpty())
72+
|| partialResult != null);
73+
this.error = error;
74+
this.writeConcernErrors = writeConcernErrors == null ? emptyList() : unmodifiableList(writeConcernErrors);
75+
this.writeErrors = writeErrors == null ? emptyMap() : unmodifiableMap(writeErrors);
76+
this.partialResult = partialResult;
77+
}
78+
79+
private static String message(
80+
@Nullable final MongoException error,
81+
@Nullable final List<WriteConcernError> writeConcernErrors,
82+
@Nullable final Map<Integer, WriteError> writeErrors,
83+
@Nullable final ClientBulkWriteResult partialResult,
84+
final ServerAddress serverAddress) {
85+
return "Client-level bulk write operation error on server " + serverAddress + "."
86+
+ (error == null ? "" : " Top-level error: " + error + ".")
87+
+ (writeErrors == null || writeErrors.isEmpty() ? "" : " Write errors: " + writeErrors + ".")
88+
+ (writeConcernErrors == null || writeConcernErrors.isEmpty() ? "" : " Write concern errors: " + writeConcernErrors + ".")
89+
+ (partialResult == null ? "" : " Partial result: " + partialResult + ".");
90+
}
91+
92+
/**
93+
* The top-level error. That is an error that is neither a {@linkplain #getWriteConcernErrors() write concern error},
94+
* nor is an {@linkplain #getWriteErrors() error of an individual write operation}.
95+
*
96+
* @return The top-level error. {@linkplain Optional#isPresent() Present} only if a top-level error occurred.
97+
*/
98+
public Optional<MongoException> getError() {
99+
return ofNullable(error);
100+
}
101+
102+
/**
103+
* The {@link WriteConcernError}s that occurred while executing the client-level bulk write operation.
104+
* <p>
105+
* There are no guarantees on mutability of the {@link List} returned.</p>
106+
*
107+
* @return The {@link WriteConcernError}s.
108+
*/
109+
public List<WriteConcernError> getWriteConcernErrors() {
110+
return writeConcernErrors;
111+
}
112+
113+
/**
114+
* The indexed {@link WriteError}s.
115+
* The {@linkplain Map#keySet() keys} are the indexes of the corresponding {@link ClientNamespacedWriteModel}s
116+
* in the corresponding client-level bulk write operation.
117+
* <p>
118+
* There are no guarantees on mutability or iteration order of the {@link Map} returned.</p>
119+
*
120+
* @return The indexed {@link WriteError}s.
121+
* @see ClientBulkWriteResult.VerboseResults#getInsertResults()
122+
* @see ClientBulkWriteResult.VerboseResults#getUpdateResults()
123+
* @see ClientBulkWriteResult.VerboseResults#getDeleteResults()
124+
*/
125+
public Map<Integer, WriteError> getWriteErrors() {
126+
return writeErrors;
127+
}
128+
129+
/**
130+
* The result of the part of a client-level bulk write operation that is known to be successful.
131+
*
132+
* @return The successful partial result. {@linkplain Optional#isPresent() Present} only if the client received a response indicating success
133+
* of at least one {@linkplain ClientNamespacedWriteModel individual write operation}.
134+
*/
135+
public Optional<ClientBulkWriteResult> getPartialResult() {
136+
return ofNullable(partialResult);
137+
}
138+
}

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

+90
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
/*
2+
* Copyright 2008-present MongoDB, Inc.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package com.mongodb.client.model.bulk;
17+
18+
import com.mongodb.annotations.Sealed;
19+
import com.mongodb.client.model.Filters;
20+
import com.mongodb.internal.client.model.bulk.ConcreteClientBulkWriteOptions;
21+
import com.mongodb.lang.Nullable;
22+
import org.bson.BsonValue;
23+
import org.bson.conversions.Bson;
24+
25+
/**
26+
* The options to apply when executing a client-level bulk write operation.
27+
*
28+
* @since 5.3
29+
*/
30+
@Sealed
31+
public interface ClientBulkWriteOptions {
32+
/**
33+
* Creates the default options.
34+
*
35+
* @return The default options.
36+
*/
37+
static ClientBulkWriteOptions clientBulkWriteOptions() {
38+
return new ConcreteClientBulkWriteOptions();
39+
}
40+
41+
/**
42+
* Enables or disables ordered execution of {@linkplain ClientNamespacedWriteModel individual write operations}.
43+
* In an ordered execution a failure of an individual operation prevents the rest of them
44+
* from being executed.
45+
* In an unordered execution failures of individual operations do not prevent the rest of them
46+
* from being executed.
47+
*
48+
* @param ordered The ordered flag. If {@code null}, the client defaults to {@code true}.
49+
* @return {@code this}.
50+
*/
51+
ClientBulkWriteOptions ordered(@Nullable Boolean ordered);
52+
53+
/**
54+
* Disables or enables checking against document validation rules, a.k.a., schema validation.
55+
*
56+
* @param bypassDocumentValidation The flag specifying whether to bypass the document validation rules.
57+
* {@code null} represents the server default.
58+
* @return {@code this}.
59+
*/
60+
ClientBulkWriteOptions bypassDocumentValidation(@Nullable Boolean bypassDocumentValidation);
61+
62+
/**
63+
* Sets variables that can be referenced from {@linkplain ClientNamespacedWriteModel individual write operations}
64+
* with the {@code "$$"} syntax, which in turn requires using {@link Filters#expr(Object)} when specifying filters.
65+
* Values must be constants or expressions that do not reference fields.
66+
*
67+
* @param let The variables. {@code null} represents the server default.
68+
* @return {@code this}.
69+
* @mongodb.driver.manual reference/aggregation-variables/ Variables in Aggregation Expressions
70+
*/
71+
ClientBulkWriteOptions let(@Nullable Bson let);
72+
73+
/**
74+
* Sets the comment to attach to the {@code bulkWrite} administration command.
75+
*
76+
* @param comment The comment. {@code null} represents the server default.
77+
* @return {@code this}.
78+
*/
79+
ClientBulkWriteOptions comment(@Nullable BsonValue comment);
80+
81+
/**
82+
* Enables or disables requesting {@linkplain ClientBulkWriteResult#getVerboseResults() verbose results}.
83+
*
84+
* @param verboseResults The flag specifying whether to request verbose results.
85+
* If {@code null}, the client defaults to {@code false}.
86+
* This value corresponds inversely to the {@code errorsOnly} field of the {@code bulkWrite} administration command.
87+
* @return {@code this}.
88+
*/
89+
ClientBulkWriteOptions verboseResults(@Nullable Boolean verboseResults);
90+
}

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

+136
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
/*
2+
* Copyright 2008-present MongoDB, Inc.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package com.mongodb.client.model.bulk;
17+
18+
import com.mongodb.ClientBulkWriteException;
19+
import com.mongodb.WriteConcern;
20+
import com.mongodb.annotations.Evolving;
21+
22+
import java.util.Map;
23+
import java.util.Optional;
24+
25+
/**
26+
* The result of a successful or partially successful client-level bulk write operation.
27+
* Note that if a client-level bulk write operation fails while some of the
28+
* {@linkplain ClientNamespacedWriteModel individual write operations} are known to be successful,
29+
* then the successful partial result is still accessible via {@link ClientBulkWriteException#getPartialResult()}.
30+
*
31+
* @see ClientBulkWriteException
32+
* @since 5.3
33+
*/
34+
@Evolving
35+
public interface ClientBulkWriteResult {
36+
/**
37+
* Indicates whether this result was {@linkplain WriteConcern#isAcknowledged() acknowledged}.
38+
* If not, then all other methods throw {@link UnsupportedOperationException}.
39+
*
40+
* @return Whether this result was acknowledged.
41+
*/
42+
boolean isAcknowledged();
43+
44+
/**
45+
* The number of documents that were inserted across all insert operations.
46+
*
47+
* @return The number of documents that were inserted.
48+
* @throws UnsupportedOperationException If this result is not {@linkplain #isAcknowledged() acknowledged}.
49+
*/
50+
long getInsertedCount();
51+
52+
/**
53+
* The number of documents that were upserted across all update and replace operations.
54+
*
55+
* @return The number of documents that were upserted.
56+
* @throws UnsupportedOperationException If this result is not {@linkplain #isAcknowledged() acknowledged}.
57+
*/
58+
long getUpsertedCount();
59+
60+
/**
61+
* The number of documents that matched the filters across all operations with filters.
62+
*
63+
* @return The number of documents that were matched.
64+
* @throws UnsupportedOperationException If this result is not {@linkplain #isAcknowledged() acknowledged}.
65+
*/
66+
long getMatchedCount();
67+
68+
/**
69+
* The number of documents that were modified across all update and replace operations.
70+
*
71+
* @return The number of documents that were modified.
72+
* @throws UnsupportedOperationException If this result is not {@linkplain #isAcknowledged() acknowledged}.
73+
*/
74+
long getModifiedCount();
75+
76+
/**
77+
* The number of documents that were deleted across all delete operations.
78+
*
79+
* @return The number of documents that were deleted.
80+
* @throws UnsupportedOperationException If this result is not {@linkplain #isAcknowledged() acknowledged}.
81+
*/
82+
long getDeletedCount();
83+
84+
/**
85+
* The verbose results of individual operations.
86+
*
87+
* @return {@link Optional} verbose results of individual operations.
88+
* @throws UnsupportedOperationException If this result is not {@linkplain #isAcknowledged() acknowledged}.
89+
* @see ClientBulkWriteOptions#verboseResults(Boolean)
90+
*/
91+
Optional<ClientBulkWriteResult.VerboseResults> getVerboseResults();
92+
93+
/**
94+
* The {@linkplain ClientBulkWriteResult#getVerboseResults() verbose results} of individual operations.
95+
*
96+
* @since 5.3
97+
*/
98+
@Evolving
99+
interface VerboseResults {
100+
/**
101+
* The indexed {@link ClientInsertOneResult}s.
102+
* The {@linkplain Map#keySet() keys} are the indexes of the corresponding {@link ClientNamespacedWriteModel}s
103+
* in the client-level bulk write operation.
104+
* <p>
105+
* There are no guarantees on mutability or iteration order of the {@link Map} returned.</p>
106+
*
107+
* @return The indexed {@link ClientInsertOneResult}s.
108+
* @see ClientBulkWriteException#getWriteErrors()
109+
*/
110+
Map<Integer, ClientInsertOneResult> getInsertResults();
111+
112+
/**
113+
* The indexed {@link ClientUpdateResult}s.
114+
* The {@linkplain Map#keySet() keys} are the indexes of the corresponding {@link ClientNamespacedWriteModel}s
115+
* in the client-level bulk write operation.
116+
* <p>
117+
* There are no guarantees on mutability or iteration order of the {@link Map} returned.</p>
118+
*
119+
* @return The indexed {@link ClientUpdateResult}s.
120+
* @see ClientBulkWriteException#getWriteErrors()
121+
*/
122+
Map<Integer, ClientUpdateResult> getUpdateResults();
123+
124+
/**
125+
* The indexed {@link ClientDeleteResult}s.
126+
* The {@linkplain Map#keySet() keys} are the indexes of the corresponding {@link ClientNamespacedWriteModel}s
127+
* in the client-level bulk write operation.
128+
* <p>
129+
* There are no guarantees on mutability or iteration order of the {@link Map} returned.</p>
130+
*
131+
* @return The indexed {@link ClientDeleteResult}s.
132+
* @see ClientBulkWriteException#getWriteErrors()
133+
*/
134+
Map<Integer, ClientDeleteResult> getDeleteResults();
135+
}
136+
}

0 commit comments

Comments
 (0)