DOCSP-23027: BsonExtraElements Annotation (#242)

* DOCSP-23027: BsonExtraElements Annotation

Author: Chris Cho

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

@@ -300,10 +300,20 @@ package:
        nested within the field.
 
    * - ``BsonExtraElements``
-     - Specifies any extra elements that aren't already mapped to a field.
+     - Specifies the POJO field on which to deserialize all elements that are
+       not mapped to a field. The POJO field must be one of the following
+       types:
+
+       - `Document <{+api+}/apidocs/bson/org/bson/Document.html>`__
+       - `BsonDocument <{+api+}/apidocs/bson/org/bson/BsonDocument.html>`__
+       - ``Map<String, Object>``
+
+       .. seealso::
+
+          :ref:`BsonExtraElements Annotation Example <bsonextraelements-annotation-code-example>`
 
 The following code snippet shows a sample POJO called ``Product`` that uses
-the preceding annotations.
+several of the preceding annotations.
 
 .. _bson-annotation-code-example:
 
@@ -364,6 +374,73 @@ The annotations in the example POJO specify the following behavior:
 - Omit the ``relatedItems`` field and value when converting data
 - Use the ``Product(String name)`` constructor when instantiating the POJO
 
+
+.. _bsonextraelements-annotation-code-example:
+
+BsonExtraElements Example
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``@BsonExtraElements`` annotation allows you to specify a field to
+deserialize data from a MongoDB document that lacks a corresponding POJO
+field mapping. This is useful when your application needs to work with data in
+a partially-defined schema. You can use this annotation to access data from
+any fields that do not correspond to the fields on your POJO.
+
+Consider a situation in which you store and retrieve data for an online store
+using the :ref:`Product POJO <bson-annotation-code-example>` from the previous
+example. As you offer a greater variety of products for the store, you
+discover that you need additional fields to describe them. Instead of
+mapping each additional field to the POJO, you can access them from a
+single field annotated with ``@BsonExtraElements`` as shown in the following
+code example:
+
+.. code-block:: java
+   :emphasize-lines: 12-13
+
+   public class Product {
+       @BsonProperty("modelName")
+       private String name;
+
+       @BsonId()
+       @BsonRepresentation(BsonType.OBJECT_ID)
+       private String serialNumber;
+
+       @BsonIgnore
+       private List<Product> relatedItems;
+
+       @BsonExtraElements
+       private Document additionalInfo;
+
+       // ...
+
+Suppose someone added additional fields for ``dimensions`` and ``weight`` to
+the product data such that the documents contained the following information:
+
+.. code-block:: json
+   :copyable: false
+   :emphasize-lines: 4-5
+
+   {
+     "name": "MDB0123",
+     "serialNumber": "62e2...",
+     "dimensions": "3x4x5",
+     "weight": "256g"
+   }
+
+The preceding document retrieved using the ``Product`` POJO contains the
+following data:
+
+.. code-block::
+   :copyable: false
+   :emphasize-lines: 5
+
+   ProductWithBsonExtraElements [
+     name=MDB0123,
+     serialNumber=62eb...,
+     relatedItems=null,
+     additionalInfo=Document{{dimensions=3x4x5, weight=256g}}
+   ]
+
 .. _pojo-discriminators:
 
 Discriminators

source/includes/fundamentals/code-snippets/bson-extra-elements/BsonExtraElementsExample.java

@@ -0,0 +1,68 @@
+package fundamentals;
+
+import static com.mongodb.MongoClientSettings.getDefaultCodecRegistry;
+import static org.bson.codecs.configuration.CodecRegistries.fromProviders;
+import static org.bson.codecs.configuration.CodecRegistries.fromRegistries;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import org.bson.Document;
+import org.bson.codecs.configuration.CodecRegistry;
+import org.bson.codecs.pojo.PojoCodecProvider;
+
+import com.mongodb.client.MongoClient;
+import com.mongodb.client.MongoClients;
+import com.mongodb.client.MongoCollection;
+import com.mongodb.client.MongoDatabase;
+import com.mongodb.client.model.Filters;
+import com.mongodb.client.model.Updates;
+import com.mongodb.client.result.UpdateResult;
+
+public class BsonExtraElementsExample {
+
+    private static final String DOC_NAME_VALUE = "MDB0123";
+
+    private static CodecRegistry getCodecRegistry() {
+        PojoCodecProvider pojoCodecProvider = PojoCodecProvider.builder().automatic(true).build();
+        return fromRegistries(getDefaultCodecRegistry(), pojoCodecProvider);
+    }
+
+    private static void setup(MongoCollection<ProductWithBsonExtraElements> collection) {
+        collection.drop();
+
+        ProductWithBsonExtraElements doc = new ProductWithBsonExtraElements(DOC_NAME_VALUE);
+        collection.insertOne(doc);
+    }
+
+    // Update without the POJO; match the annotations for field names
+    private static void addOtherFields(MongoClient client) {
+        MongoCollection<Document> collection = client.getDatabase("sample_pojo").getCollection("ProductsWithMoreInfo");
+
+        UpdateResult result = collection.updateOne(
+                Filters.eq("modelName", DOC_NAME_VALUE),
+                Updates.combine(
+                        Updates.set("dimensions", "3x4x5"),
+                        Updates.set("weight", "256g")));
+        System.out.println(result);
+    }
+
+    private static <T> void printDocuments(MongoCollection<T> collection) {
+        List<T> products = new ArrayList<T>();
+        collection.find().into(products);
+        products.forEach(doc -> System.out.println(doc));
+    }
+
+    public static void main(String[] args) {
+        String uri = "mongodb://localhost:27017";
+
+        try (MongoClient mongoClient = MongoClients.create(uri)) {
+            MongoDatabase database = mongoClient.getDatabase("sample_pojo").withCodecRegistry(getCodecRegistry());
+            MongoCollection<ProductWithBsonExtraElements> collection = database.getCollection("ProductsWithMoreInfo", ProductWithBsonExtraElements.class);
+
+            setup(collection);
+            addOtherFields(mongoClient);
+            printDocuments(collection);
+        }
+    }
+}

source/includes/fundamentals/code-snippets/bson-extra-elements/ProductWithBsonExtraElements.java

@@ -0,0 +1,75 @@
+package fundamentals;
+
+import java.util.List;
+
+import org.bson.BsonType;
+import org.bson.Document;
+import org.bson.codecs.pojo.annotations.BsonCreator;
+import org.bson.codecs.pojo.annotations.BsonDiscriminator;
+import org.bson.codecs.pojo.annotations.BsonExtraElements;
+import org.bson.codecs.pojo.annotations.BsonId;
+import org.bson.codecs.pojo.annotations.BsonIgnore;
+import org.bson.codecs.pojo.annotations.BsonProperty;
+import org.bson.codecs.pojo.annotations.BsonRepresentation;
+
+@BsonDiscriminator(value="ProductWithBsonExtraElements", key="_cls")
+public class ProductWithBsonExtraElements {
+
+    @BsonProperty("modelName")
+    private String name;
+
+    @BsonId()
+    @BsonRepresentation(BsonType.OBJECT_ID)
+    private String serialNumber;
+
+    @BsonIgnore
+    private List<ProductPojo> relatedItems;
+
+    @BsonExtraElements
+    private Document additionalInfo;
+
+    @BsonCreator
+    public ProductWithBsonExtraElements(
+            @BsonProperty("modelName") String name) {
+        this.name = name;
+    }
+
+    public String getName() {
+        return name;
+    }
+
+    public void setName(String name) {
+        this.name = name;
+    }
+
+    public String getSerialNumber() {
+        return serialNumber;
+    }
+
+    public void setSerialNumber(String serialNumber) {
+        this.serialNumber = serialNumber;
+    }
+
+    public List<ProductPojo> getRelatedItems() {
+        return relatedItems;
+    }
+
+    public void setRelatedItems(List<ProductPojo> relatedItems) {
+        this.relatedItems = relatedItems;
+    }
+
+    public Document getAdditionalInfo() {
+        return additionalInfo;
+    }
+
+    public void setAdditionalInfo(Document additionalInfo) {
+        this.additionalInfo = additionalInfo;
+    }
+
+    @Override
+    public String toString() {
+        return "ProductWithBsonExtraElements [name=" + name + ", serialNumber=" + serialNumber + ", relatedItems="
+                + relatedItems + ", additionalInfo=" + additionalInfo + "]";
+    }
+
+}