[backport v5.5] #710 Java Write Exception

source/crud/bulk.txt

@@ -623,6 +623,54 @@ Even though the write operation inserting a document with a duplicate key result
 in an error, the other operations are executed because the write operation is
 unordered.
 
+.. _java-bulk-insert-troubleshooting:
+
+Troubleshooting
+---------------
+
+Bulk Write Exception
+~~~~~~~~~~~~~~~~~~~~
+
+If the driver encounters an error during a bulk write operation, the driver
+throws a `MongoBulkWriteException.
+<{+core-api+}/MongoBulkWriteException.html>`__ A ``MongoBulkWriteException``
+contains a ``writeErrors`` field consisting of a list of one or more
+``WriteError`` objects associated with the same bulk write operation. 
+
+Consider a collection that has a schema validation rule where the value of the
+``quantity`` field must be an ``int`` type. In the following example, the driver
+throws a ``MongoBulkWriteException`` when you attempt to insert a document with
+a ``quantity`` field value of ``"three"`` and another with a ``quantity`` field
+value of ``"ten"``.
+
+.. code-block:: none
+   :copyable: false
+   :emphasize-lines: 1-2, 6-9, 13-16
+
+   Exception in thread "main" com.mongodb.MongoBulkWriteException: Bulk write
+   operation result had errors at
+   com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:258)
+   ... at
+   BulkWriteMultipleValidationErrorsExample.main(BulkWriteMultipleValidationErrorsExample.java:30)
+   Caused by: com.mongodb.MongoWriteException: WriteError{code=121,
+   message='Document failed validation', details={ operator: "$jsonSchema",
+   schemaRules: { bsonType: "int", description: "must be an integer" },
+   offendingDocument: {"name":"Apple","quantity":"three"} }} at
+   com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50)
+   at com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:254)
+   ... 19 more 
+   Caused by: com.mongodb.MongoWriteException: WriteError{code=121,
+   message='Document failed validation', details={ operator: "$jsonSchema",
+   schemaRules: { bsonType: "int", description: "must be an integer" },
+   offendingDocument: {"name":"Banana","quantity":"ten"} }} at
+   com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50)
+   at
+   com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:254)
+   ... 19 more    
+
+To learn more about schema validation, see Schema Validation in the Server
+Manual Entries section.
+
 Additional Information
 ----------------------
 
@@ -637,6 +685,7 @@ MongoCollection
 
 - `bulkWrite() <{+driver-api+}/MongoCollection.html#bulkWrite(com.mongodb.client.ClientSession,java.util.List)>`__
 - `BulkWriteOptions <{+core-api+}/client/model/BulkWriteOptions.html>`__
+- `WriteError <{+core-api+}/WriteError.html>`__
 - `MongoBulkWriteException <{+core-api+}/MongoBulkWriteException.html>`__
 
 MongoClient
@@ -651,3 +700,4 @@ Server Manual Entries
 
 - :manual:`MongoCollection.bulkWrite() </reference/method/db.collection.bulkWrite/>`
 - :manual:`MongoClient.bulkWrite() </reference/command/bulkWrite/>`
+- :manual:`Schema Validation </core/schema-validation/>`

source/crud/insert.txt

@@ -15,7 +15,7 @@ Insert Operations
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 1
+   :depth: 2
    :class: singlecol
 
 Overview
@@ -189,6 +189,40 @@ operation and an insert many operation:
       insertOne() document id: BsonObjectId{value=...}
       insertMany() document ids: {0=BsonObjectId{value=...}, 1=BsonObjectId{value=...}}
 
+.. _java-insert-troubleshooting:
+
+Troubleshooting
+---------------
+
+Write Exception
+~~~~~~~~~~~~~~~
+
+The driver throws a `MongoWriteException
+<{+core-api+}/MongoWriteException.html>`__ for any write errors that occur when
+performing single write operations. A ``MongoWriteException`` object has an
+``error`` field containing the ``WriteError`` object that caused it.
+
+Consider a collection that has a schema validation rule where the value of the
+``quantity`` field must be an ``int`` type. In the following example, the driver
+throws a ``MongoWriteException`` if you attempt to insert a document where the
+value of ``quantity`` is ``"three"``.
+
+.. code-block:: none
+   :copyable: false
+   :emphasize-lines: 1, 4-7
+
+   Exception in thread "main" com.mongodb.MongoWriteException: Document failed validation at
+   com.mongodb.internal.connection.ProtocolHelper.getWriteException(ProtocolHelper.java:228)
+   ... 
+   Caused by: com.mongodb.MongoWriteException: WriteError{code=121,
+   message='Document failed validation', details={ operator: "$jsonSchema",
+   schemaRules: { bsonType: "int", description: "must be an integer" },
+   offendingDocument: {"name":"Apple","quantity":"three"} } } at
+   com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50)
+
+To learn more about schema validation, see Schema Validation in the Server
+Manual Entries section.
+
 Additional Information
 ----------------------
 
@@ -202,8 +236,14 @@ For more information about the methods and classes used to insert documents, see
 - `insertMany() <{+driver-api+}/MongoCollection.html#insertMany(java.util.List)>`__
 - `InsertManyResult <{+core-api+}/client/result/InsertManyResult.html>`__ 
 
+For more information about the error types discussed in the Troubleshooting section, see the following API documentation: 
+
+- `WriteError <{+core-api+}/WriteError.html>`__
+- `MongoWriteException <{+core-api+}/MongoWriteException.html>`__
+
 Server Manual Entries
 ~~~~~~~~~~~~~~~~~~~~~
 
 - :manual:`db.collection.insertOne() </reference/method/db.collection.insertOne/>`
 - :manual:`db.collection.insertMany() </reference/method/db.collection.insertMany/>`
+- :manual:`Schema Validation </core/schema-validation/>`