DOCSP-30350 put troubleshooting into main pages, not separate

Author: mballard-mdb

source/crud.txt

@@ -19,7 +19,6 @@ CRUD Operations
    Collations </crud/collations>
    Large File Storage with GridFS </crud/gridfs>
    Configure Custom CRUD Settings </crud/crud-settings>
-   Troubleshooting Write Exceptions </crud/operation-error-handling>
 
 - :ref:`Insert Documents <java-fundamentals-insert>`
 - :ref:`Query Documents <java-read-operations>`
@@ -33,4 +32,3 @@ CRUD Operations
 - :ref:`Collations <java-crud-collations>`
 - :ref:`Large File Storage with GridFS <java-crud-gridfs>`
 - :ref:`Configure Custom CRUD Settings <java-configure-custom-crud>`
-- :ref:`Troubleshooting Write Exceptions <java-operation-errors>`

source/crud/bulk.txt

@@ -623,6 +623,63 @@ 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.
 
+Troubleshooting
+---------------
+
+.. include:: /includes/crud/write-error.rst
+
+Bulk Write Exception
+~~~~~~~~~~~~~~~~~~~~
+
+The driver creates write exceptions when a ``WriteError`` object is created. If an
+error is detected during a bulk write operation, a `MongoBulkWriteException
+<{+core-api+}/MongoBulkWriteException.html>`__ is thrown.
+
+A ``MongoBulkWriteException`` contains a ``writeErrors`` field containing a list
+of one or more ``WriteError`` objects associated with the same bulk write
+operation. 
+
+Example
+'''''''
+
+For example, the driver raises a ``MongoBulkWriteException`` if your bulk insert
+contains two documents into a collection that violate the collection's schema
+validation rules. Suppose the collection has a rule where the value of the
+``quantity`` field must be an ``int`` type. If your bulk insert contains a
+document with a ``quantity`` of ``"three"`` and another with a ``quantity`` of
+``"ten"`, the driver prints the following error message:
+
+.. 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    
+
+This exception message contains a list of the two ``WriteError`` objects. The
+description in the ``MongoBulkWriteException`` object is vague as
+documents associated with the same bulk operation could produce different error
+types. Refer to the individual ``WriteError`` objects' ``message`` fields to
+determine the cause of each error.
+
 Additional Information
 ----------------------
 

source/crud/insert.txt

@@ -189,6 +189,52 @@ operation and an insert many operation:
       insertOne() document id: BsonObjectId{value=...}
       insertMany() document ids: {0=BsonObjectId{value=...}, 1=BsonObjectId{value=...}}
 
+Troubleshooting
+---------------
+
+.. include:: /includes/crud/write-error.rst
+
+Write Exception
+~~~~~~~~~~~~~~~
+
+The driver creates write exceptions when a ``WriteError`` object is created. The
+driver raises a `MongoWriteException <{+core-api+}/MongoWriteException.html>`__
+for any write errors that occur when performing single write operations.
+
+A ``MongoWriteException`` object contains an ``error`` field containing the
+``WriteError`` object that caused it.
+
+Example
+'''''''
+
+For example, the driver raises a ``MongoWriteException`` if you
+attempt to insert a document into a collection that violates the collection's
+schema validation rules. Suppose the collection has a rule where the value of
+the ``quantity`` field must be an ``int`` type. If you attempt to insert a
+document where the value of ``quantity`` is ``"three"``, the driver prints the
+following error message:
+
+.. 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)
+
+In the preceding error message, the ``MongoWriteException`` object provides a
+high-level description of the error. The ``WriteError`` object provides details
+on the failed operation, such as the schema rules and the offending document. To
+address this error, you must either revise the document to adhere to the schema
+validation rules or bypass validation.
+
+To learn more about schema validation, see :manual:`Schema Validation </core/schema-validation/>` in the Server Manual.
+
 Additional Information
 ----------------------
 

source/crud/operation-error-handling.txt

@@ -0,0 +1,31 @@
+.. _java_write_error:
+
+This section describes write exceptions you might encounter when
+using the {+driver-long+} to perform MongoDB write operations. Once you
+understand the types of write exceptions that the driver raises, you can take
+appropriate actions to either handle them or correct the error-causing code.
+
+.. note::
+
+   This page addresses only write exception handling. If you encounter
+   any other issues with MongoDB or the driver, visit the following
+   resources:
+ 
+    - :ref:`java-connection-troubleshooting` for potential solutions to issues
+      you might encounter when connecting to a MongoDB deployment
+    - :ref:`java-issues-and-help` page for information about reporting bugs,
+      contributing to the driver, and finding more resources
+    - :community-forum:`MongoDB Community Forums </tag/java>` for questions,
+      discussions, or general technical support
+
+Write Error
+~~~~~~~~~~~
+
+If the driver encounters an error while performing a write operation, it
+creates an error of the `WriteError <{+core-api+}/WriteError.html>`__ type.
+
+The ``WriteError`` type contains the following fields: 
+
+    - ``code``: the code associated with the error
+    - ``message``: a message explaining the error
+    - ``details``: an optional field containing details associated with the error