DOCSP-22293: Records and Codec Provider (#280)

* DOCSP-22293: Records and Codec Provider

Author: Chris Cho

source/fundamentals/data-formats.txt

@@ -8,6 +8,7 @@ Data Formats
 - :doc:`/fundamentals/data-formats/document-data-format-extended-json`
 - :doc:`/fundamentals/data-formats/documents`
 - :doc:`/fundamentals/data-formats/document-data-format-pojo`
+- :doc:`/fundamentals/data-formats/document-data-format-record`
 - :doc:`/fundamentals/data-formats/pojo-customization`
 - :doc:`/fundamentals/data-formats/codecs`
 
@@ -18,6 +19,7 @@ Data Formats
    /fundamentals/data-formats/document-data-format-extended-json
    /fundamentals/data-formats/documents
    /fundamentals/data-formats/document-data-format-pojo
+   /fundamentals/data-formats/document-data-format-record
    /fundamentals/data-formats/pojo-customization
    /fundamentals/data-formats/codecs
 

source/fundamentals/data-formats/codecs.txt

@@ -1,3 +1,5 @@
+.. _fundamentals-codecs:
+
 ======
 Codecs
 ======
@@ -32,7 +34,7 @@ sections:
 - :ref:`CodecProvider <codecs-codecprovider>`
 - :ref:`Custom Codec Example <codecs-custom-example>`
 
-If you are customizing encoding and decoding logic for Plain old Java objects
+If you are customizing encoding and decoding logic for plain old Java objects
 (POJOs), read our guide on :doc:`POJO Customization </fundamentals/data-formats/pojo-customization>`.
 
 .. _codecs-codec:

source/fundamentals/data-formats/document-data-format-pojo.txt

@@ -1,3 +1,5 @@
+.. _fundamentals-pojos:
+
 ===========================
 Document Data Format: POJOs
 ===========================
@@ -21,7 +23,7 @@ data representation.
 The example in this guide shows how to perform the following:
 
 - Configure the driver to serialize and deserialize POJOs
-- How to read and write to documents using POJOs 
+- How to read and write to documents using POJOs
 
 .. _fundamentals-example-pojo:
 
@@ -120,8 +122,8 @@ To set up the driver to store and retrieve POJOs, we need to specify:
   encode/decode the data between the POJO and MongoDB document, and which
   POJO classes or packages that the codecs should apply to.
 - A ``CodecRegistry`` instance that contains the codecs and other related information.
-- A ``MongoClient``, ``MongoDatabase``, or ``MongoCollection`` instance
-  configured to use the ``CodecRegistry``.
+- A ``MongoDatabase`` or ``MongoCollection`` instance configured to use the
+  ``CodecRegistry``.
 - A ``MongoCollection`` instance created with the POJO document class
   bound to the ``TDocument`` generic type.
 
@@ -130,7 +132,7 @@ requirements:
 
 1. Configure the ``PojoCodecProvider``. In this example, we use the ``automatic(true)``
    setting of the ``PojoCodecProvider.Builder`` to apply the Codecs to
-   any class and its properties. 
+   any class and its properties.
 
    .. code-block:: java
 
@@ -140,7 +142,7 @@ requirements:
 
       Codec providers also contain other objects such as ``ClassModel`` and
       ``Convention`` instances that further define serialization behavior.
-      For more information on codec providers and customization, see our guide
+      For more information on codec providers and customization, see the guide
       on :doc:`POJO Customization </fundamentals/data-formats/pojo-customization>`.
 
 #. Add the ``PojoCodecProvider`` instance to a ``CodecRegistry``. The
@@ -166,11 +168,10 @@ requirements:
 
       CodecRegistry pojoCodecRegistry = fromRegistries(getDefaultCodecRegistry(), fromProviders(pojoCodecProvider));
 
-#. Configure our ``MongoClient``, ``MongoDatabase``, or ``MongoCollection``
-   instance to use the Codecs in the ``CodecRegistry``. You only need to
-   configure one of these. In this example, we set the ``CodecRegistry`` on a
-   ``MongoDatabase`` called ``sample_pojos`` using the ``withCodecRegistry()``
-   method.
+#. Configure the ``MongoDatabase`` or ``MongoCollection`` instance to use the
+   Codecs in the ``CodecRegistry``. You only need to configure one of these.
+   In this example, we set the ``CodecRegistry`` on a ``MongoDatabase`` called
+   ``sample_pojos`` using the ``withCodecRegistry()`` method.
 
    .. code-block:: java
 
@@ -220,10 +221,10 @@ When you run this code, your output should look something like this:
 
    By default, the ``PojoCodecProvider`` omits fields in your POJO that are
    set to ``null``. For more information on how to specify this behavior, see
-   our guide on :doc:`POJO Customization </fundamentals/data-formats/pojo-customization>`.
+   the guide on :doc:`POJO Customization </fundamentals/data-formats/pojo-customization>`.
 
 For more information about the methods and classes mentioned in this section,
-see the following API Documentation:
+see the following API documentation:
 
 - `CodecRegistry <{+api+}/apidocs/bson/org/bson/codecs/configuration/CodecRegistry.html>`__
 - `TDocument <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html>`__
@@ -245,5 +246,4 @@ by performing the following:
 - Specify the **automatic** conversion behavior for the ``PojoCodecProvider``
   to apply the ``Codecs`` to any class and its properties.
 - Add the ``PojoCodecProvider`` to a ``CodecRegistry``, and specify the
-  registry on an instance of a ``MongoClient``, ``MongoDatabase``, or
-  ``MongoCollection``.
+  registry on an instance of a ``MongoDatabase`` or ``MongoCollection``.

source/fundamentals/data-formats/document-data-format-record.txt

@@ -0,0 +1,88 @@
+.. _fundamentals-records:
+
+=============================
+Document Data Format: Records
+=============================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to store and retrieve data in the {+driver-long+}
+using **Java records**. Java records are a type of Java class often used to
+model data and separate business logic from data representation.
+
+.. tip::
+
+   You can declare Java records in Java 16 or later. Learn more about the
+   functionality and restrictions of records from `Java 17 Language Updates: Record Classes <https://docs.oracle.com/en/java/javase/17/language/records.html>`__.
+
+   If you are using an earlier version of Java, you can use plain old Java
+   objects instead. See the :ref:`<fundamentals-pojos>` guide for
+   implementation details.
+
+.. _fundamentals-example-record:
+
+Serialize and Deserialize a Record
+----------------------------------
+
+The driver natively supports encoding and decoding Java records for
+MongoDB read and write operations using the **default codec registry**. The
+default codec registry is a collection of classes called **codecs** that
+define how to convert encode and decode Java types.  Learn more about
+codecs and the default codec registry in the guide on :ref:`<fundamentals-codecs>`.
+
+Example Record
+~~~~~~~~~~~~~~
+
+The code examples in this guide reference the following sample record, which
+describes a data storage device:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/records/DataStorageRecord.java
+   :language: java
+   :start-after: start dataStorageRecord
+   :end-before: end dataStorageRecord
+
+Insert a Record
+~~~~~~~~~~~~~~~
+
+You can insert a ``DataStorageRecord`` instance as shown in the following code:
+
+.. code-block:: java
+
+   MongoCollection<DataStorageRecord> collection = database.getCollection("data_storage_devices", DataStorageRecord.class);
+
+   // insert the record
+   collection.insertOne(new DataStorageRecord("2TB SSD", 1.71));
+
+Retrieve a Record
+~~~~~~~~~~~~~~~~~
+
+You can retrieve documents as ``DataStorageRecord`` instances and print them
+as shown in the following code:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input::
+      :language: java
+
+      MongoCollection<DataStorageRecord> collection = database.getCollection("data_storage_devices", DataStorageRecord.class);
+
+      // retrieve and print the records
+      List<DataStorageRecord> records = new ArrayList<DataStorageRecord>();
+      collection.find().into(records);
+      records.forEach(System.out::println);
+
+   .. output::
+      :language: none
+
+      DataStorageRecord[productName=1TB SSD, capacity=1.71]
+

source/fundamentals/data-formats/pojo-customization.txt

@@ -1,3 +1,5 @@
+.. _fundamentals-pojo-customization:
+
 ==================
 POJO Customization
 ==================

source/includes/fundamentals/code-snippets/records/CodecRecordExample.java

@@ -0,0 +1,30 @@
+package fundamentals.codecs.records;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import com.mongodb.client.MongoClient;
+import com.mongodb.client.MongoClients;
+import com.mongodb.client.MongoCollection;
+import com.mongodb.client.MongoDatabase;
+
+
+public class CodecRecordExample {
+    public static void main(String args[]) {
+        // Replace the uri string with your MongoDB deployment's connection string
+        String uri = "<connection uri>";
+        try (MongoClient mongoClient = MongoClients.create(uri)) {
+
+            MongoDatabase database = mongoClient.getDatabase("sample_data");
+            MongoCollection<DataStorageRecord> collection = database.getCollection("data_storage_devices", DataStorageRecord.class);
+
+            // insert the document
+            collection.insertOne(new DataStorageRecord("2TB SSD", 1.71));
+
+            // return all documents in the collection as records
+            List<DataStorageRecord> records = new ArrayList<DataStorageRecord>();
+            collection.find().into(records);
+            records.forEach(System.out::println);
+        }
+    }
+}

source/includes/fundamentals/code-snippets/records/DataStorageRecord.java

@@ -0,0 +1,8 @@
+package fundamentals.codecs.records;
+
+// start dataStorageRecord
+public record DataStorageRecord(
+        String productName,
+        double capacity
+) {}
+// end dataStorageRecord

source/whats-new.txt

@@ -32,7 +32,7 @@ Client-Side Field Level Encryption and Queryable Encryption.
 The bug can cause data corruption when rotating :ref:`Data Encryption Keys <csfle-key-architecture>`
 (DEKs) encrypted with a :ref:`Customer Master Key <csfle-key-architecture>`
 hosted on Google Cloud Key Management Service or Azure
-Key Vault. The bug was present in version 4.7.0 of the driver 
+Key Vault. The bug was present in version 4.7.0 of the driver
 in the ``RewrapManyDataKey`` method and causes the
 loss of your DEKs.
 
@@ -117,7 +117,8 @@ New features of the 4.6 Java driver release include:
   and the `DnsClientProvider <https://mongodb.github.io/mongo-java-driver/4.6/apidocs/mongodb-driver-core/com/mongodb/spi/dns/DnsClientProvider.html>`__
   interface API documentation for more information.
 - Added driver support for encoding and decoding between `Java records <https://docs.oracle.com/en/java/javase/17/language/records.html>`__
-  and BSON documents, which is enabled by default.
+  and BSON documents, which is enabled by default. See :ref:`<fundamentals-records>`
+  for more information.
 
 .. _version-4.5: