Skip to content

Commit 845d8a5

Browse files
jyeminjyemin
committed
Improved Javadoc for bulk write operations.
1 parent b08268d commit 845d8a5

4 files changed

Lines changed: 42 additions & 20 deletions

File tree

‎src/main/com/mongodb/BulkUpdateRequestBuilder.java‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -33,16 +33,17 @@ public class BulkUpdateRequestBuilder {
3333
}
3434

3535
/**
36-
* Adds an update request to replace one matching document to the bulk operation.
36+
* Adds a request to replace one document in the collection that matches the query with which this builder was created.
3737
*
38-
* @param document the replacement document
38+
* @param document the replacement document, which must be structured just as a document you would insert. It can not contain any
39+
* update operators.
3940
*/
4041
public void replaceOne(final DBObject document) {
4142
bulkWriteOperation.addRequest(new ReplaceRequest(query, upsert, document));
4243
}
4344

4445
/**
45-
* Adds an update request to update all matching documents to the bulk operation.
46+
* Adds a request to update all documents in the collection that match the query with which this builder was created.
4647
*
4748
* @param update the update criteria
4849
*/
@@ -51,7 +52,7 @@ public void update(final DBObject update) {
5152
}
5253

5354
/**
54-
* Adds an update request to update one matching document to the bulk operation.
55+
* Adds a request to update one document in the collection that matches the query with which this builder was created.
5556
*
5657
* @param update the update criteria
5758
*/

‎src/main/com/mongodb/BulkWriteOperation.java‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,11 @@
2222
import static org.bson.util.Assertions.isTrue;
2323

2424
/**
25-
* A bulk write operation.
25+
* A bulk write operation. A bulk write operation consists of an ordered or unordered collection of write requests,
26+
* which can be any combination of inserts, updates, replaces, or removes.
27+
*
28+
* @see DBCollection#initializeOrderedBulkOperation()
29+
* @see com.mongodb.DBCollection#initializeUnorderedBulkOperation()
2630
*
2731
* @since 2.12
2832
*/
@@ -60,7 +64,8 @@ public void insert(final DBObject document) {
6064
}
6165

6266
/**
63-
* Start building a write request to add to the bulk write operation.
67+
* Start building a write request to add to the bulk write operation. The returned builder can be used to create an update, replace,
68+
* or remove request with the given query.
6469
*
6570
* @param query the query for an update, replace or remove request
6671
* @return a builder for a single write request
@@ -71,7 +76,8 @@ public BulkWriteRequestBuilder find(final DBObject query) {
7176
}
7277

7378
/**
74-
* Execute the bulk write operation.
79+
* Execute the bulk write operation with the default write concern of the collection from which this came. Note that the
80+
* continueOnError property of the write concern is ignored.
7581
*
7682
* @return the result of the bulk write operation.
7783
* @throws com.mongodb.BulkWriteException
@@ -85,9 +91,10 @@ public BulkWriteResult execute() {
8591
}
8692

8793
/**
88-
* Execute the bulk write operation with the given write concern.
94+
* Execute the bulk write operation with the given write concern. Note that the continueOnError property of the write concern is
95+
* ignored.
8996
*
90-
* @param writeConcern the write concern to apply to the bulk operation
97+
* @param writeConcern the write concern to apply to the bulk operation.
9198
*
9299
* @return the result of the bulk write operation.
93100
* @throws com.mongodb.BulkWriteException

‎src/main/com/mongodb/BulkWriteRequestBuilder.java‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -31,30 +31,31 @@ public class BulkWriteRequestBuilder {
3131
}
3232

3333
/**
34-
* Adds a request to remove all matching documents to the bulk operation.
34+
* Adds a request to remove all documents in the collection that match the query with which this builder was created.
3535
*/
3636
public void remove() {
3737
bulkWriteOperation.addRequest(new RemoveRequest(query, true));
3838
}
3939

4040
/**
41-
* Adds a request to remove one matching documents to the bulk operation.
41+
* Adds a request to remove one document in the collection that matches the query with which this builder was created.
4242
*/
4343
public void removeOne() {
4444
bulkWriteOperation.addRequest(new RemoveRequest(query, false));
4545
}
4646

4747
/**
48-
* Adds a request to replace one matching documents to the bulk operation.
48+
* Adds a request to replace one document in the collection that matches the query with which this builder was created.
4949
*
50-
* @param document the replacement document
50+
* @param document the replacement document, which must be structured just as a document you would insert. It can not contain any
51+
* update operators.
5152
*/
5253
public void replaceOne(final DBObject document) {
5354
new BulkUpdateRequestBuilder(bulkWriteOperation, query, false).replaceOne(document);
5455
}
5556

5657
/**
57-
* Adds a request to replace one matching documents to the bulk operation.
58+
* Adds a request to update all documents in the collection that match the query with which this builder was created.
5859
*
5960
* @param update the update criteria
6061
*/
@@ -63,7 +64,7 @@ public void update(final DBObject update) {
6364
}
6465

6566
/**
66-
* Adds a request to update one matching documents to the bulk operation.
67+
* Adds a request to update one document in the collection that matches the query with which this builder was created.
6768
*
6869
* @param update the update criteria
6970
*/

‎src/main/com/mongodb/DBCollection.java‎

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1619,8 +1619,17 @@ public CommandResult explainAggregate(List<DBObject> pipeline, AggregationOption
16191619
public abstract List<Cursor> parallelScan(final ParallelScanOptions options);
16201620

16211621
/**
1622-
* Creates a builder for an ordered bulk operation. Write requests included in the bulk operations will be executed in order,
1623-
* and will halt on the first failure.
1622+
* Creates a builder for an ordered bulk write operation, consisting of an ordered collection of write requests,
1623+
* which can be any combination of inserts, updates, replaces, or removes. Write requests included in the bulk operations will be
1624+
* executed in order, and will halt on the first failure.
1625+
* <p>
1626+
* Note: While this bulk write operation will execute on MongoDB 2.4 servers and below, the writes will be performed one at a time,
1627+
* as that is the only way to preserve the semantics of the value returned from execution or the exception thrown.
1628+
* <p>
1629+
* Note: While a bulk write operation with a mix of inserts, updates, replaces, and removes is supported,
1630+
* the implementation will batch up consecutive requests of the same type and send them to the server one at a time. For example,
1631+
* if a bulk write operation consists of 10 inserts followed by 5 updates, followed by 10 more inserts,
1632+
* it will result in three round trips to the server.
16241633
*
16251634
* @return the builder
16261635
*
@@ -1631,8 +1640,12 @@ public BulkWriteOperation initializeOrderedBulkOperation() {
16311640
}
16321641

16331642
/**
1634-
* Creates a builder for an unordered bulk operation. Write requests included in the bulk operation will be executed in an undefined
1635-
* order, and all requests will be executed even if some fail.
1643+
* Creates a builder for an unordered bulk operation, consisting of an unordered collection of write requests,
1644+
* which can be any combination of inserts, updates, replaces, or removes. Write requests included in the bulk operation will be
1645+
* executed in an undefined order, and all requests will be executed even if some fail.
1646+
* <p>
1647+
* Note: While this bulk write operation will execute on MongoDB 2.4 servers and below, the writes will be performed one at a time,
1648+
* as that is the only way to preserve the semantics of the value returned from execution or the exception thrown.
16361649
*
16371650
* @return the builder
16381651
*
@@ -2014,7 +2027,7 @@ public ReadPreference getReadPreference(){
20142027
*/
20152028
@Deprecated
20162029
public void slaveOk(){
2017-
addOption( Bytes.QUERYOPTION_SLAVEOK );
2030+
addOption(Bytes.QUERYOPTION_SLAVEOK);
20182031
}
20192032

20202033
/**

0 commit comments

Comments
 (0)