DOCSP-14391: dynamic collection naming settings (#85)

* DOCSP-14391: dynamic collection naming settings

Author: Chris Cho

source/kafka-sink-properties.txt

@@ -85,6 +85,21 @@ data to sink to MongoDB. For an example configuration file, see
        | *Required*
        | **Accepted Values**: A MongoDB collection name
 
+   * - namespace.mapper
+     - string
+     - | The class name of the class that specifies which database or
+         collection in which to sink the data. The
+         ``DefaultNamespaceMapper`` uses the ``database`` and ``collection``
+         settings.
+
+         .. seealso::
+
+            - :ref:`FieldPathNamespaceMapper settings <fieldpathnamespacemapper-settings>`
+
+       | **Default**: ``com.mongodb.kafka.connect.sink.namespace.mapping.DefaultNamespaceMapper``
+       | **Accepted Values**: A fully qualified Java class name of a class
+         that implements the ``NamespaceMapper`` interface.
+
    * - document.id.strategy
      - string
      - | The class name of the class that generates a unique document ``_id`` field.
@@ -308,6 +323,75 @@ the following behavior for data consumed from ``topicA``:
   ``BlockList`` projection type.
 
 
+.. _fieldpathnamespacemapper-settings:
+
+FieldPathNamespaceMapper Settings
+---------------------------------
+
+You can specify which namespace (database and/or collection) to sink
+a document based on its field values using the
+``FieldPathNamespaceMapper``. To enable this mapper, set the
+``namespace.mapper`` configuration setting to the class name as shown
+below:
+
+.. code-block:: properties
+
+   namespace.mapper=com.mongodb.kafka.connect.sink.topic.mapping.FieldPathNamespaceMapper
+
+The ``FieldPathNamespaceMapper`` requires the following:
+
+- at least one of the mapping configurations to a database or collection is set
+- only one of the ``key`` or ``value`` mapping configurations is set for a
+  mapping to a database
+- only one of the ``key`` or ``value`` mapping configurations is set for a
+  mapping to a collection
+
+You can use the following settings to customize the behavior of the
+``FieldPathNamespaceMapper``:
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+   :widths: 2 1 4
+
+   * - Name
+     - Type
+     - Description
+
+   * - namespace.mapper.key.database.field
+     - string
+     - | The name of the key document field that specifies the name of the
+         database to write to.
+
+   * - namespace.mapper.key.collection.field
+     - string
+     - | The name of the key document field that specifies the name of the
+         collection to write to.
+
+   * - namespace.mapper.value.database.field
+     - string
+     - | The name of the value document field that specifies the name of
+         the database to write to.
+
+   * - namespace.mapper.value.collection.field
+     - string
+     - | The name of the value document field that specifies the name of
+         the collection to write to.
+
+   * - namespace.mapper.error.if.invalid
+     - boolean
+     - | Whether to throw an exception if the document is missing the
+         mapped field or if it contains an invalid BSON type.
+       | When set to ``true``, the connector does not process the record
+         and may halt or skip processing depending on the related settings.
+       | When set to ``false`` and a document is missing the mapped field
+         or if it contains an invalid BSON type, the connector defaults to
+         writing to the specified ``database`` and ``collection`` settings.
+       |
+       | **Default**: ``false``
+       | **Accepted Values**: ``true`` or ``false``
+
+
 Dead Letter Queue Configuration Settings
 ----------------------------------------