Skip to content

Commit 95555aa

Browse files
author
Chris Cho
authored
DOCSP-22977: Java record annotations (#284)
* DOCSP-22977: Java record annotations
1 parent 3bda6b1 commit 95555aa

File tree

3 files changed

+153
-7
lines changed

3 files changed

+153
-7
lines changed

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

Lines changed: 104 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,9 @@ Document Data Format: Records
1515
Overview
1616
--------
1717

18-
In this guide, you can learn how to store and retrieve data in the {+driver-long+}
19-
using **Java records**. Java records are a type of Java class often used to
20-
model data and separate business logic from data representation.
18+
In this guide, you can learn how to store and retrieve data in the
19+
{+driver-long+} using **Java records**. Java records are a type of Java class
20+
often used to model data and separate business logic from data representation.
2121

2222
.. tip::
2323

@@ -28,21 +28,21 @@ model data and separate business logic from data representation.
2828
objects instead. See the :ref:`<fundamentals-pojos>` guide for
2929
implementation details.
3030

31-
.. _fundamentals-example-record:
32-
3331
Serialize and Deserialize a Record
3432
----------------------------------
3533

3634
The driver natively supports encoding and decoding Java records for
3735
MongoDB read and write operations using the **default codec registry**. The
3836
default codec registry is a collection of classes called **codecs** that
39-
define how to convert encode and decode Java types. Learn more about
37+
define how to convert encode and decode Java types. Learn more about
4038
codecs and the default codec registry in the guide on :ref:`<fundamentals-codecs>`.
4139

40+
.. _fundamentals-example-record:
41+
4242
Example Record
4343
~~~~~~~~~~~~~~
4444

45-
The code examples in this guide reference the following sample record, which
45+
The code examples in this section reference the following sample record, which
4646
describes a data storage device:
4747

4848
.. literalinclude:: /includes/fundamentals/code-snippets/records/DataStorageRecord.java
@@ -86,3 +86,100 @@ as shown in the following code:
8686

8787
DataStorageRecord[productName=1TB SSD, capacity=1.71]
8888

89+
90+
.. _fundamentals-records-annotations:
91+
92+
Specify Component Conversion Using Annotations
93+
----------------------------------------------
94+
95+
This section describes the annotations you can use to configure the
96+
serialization behavior of record components and provides an example to
97+
demonstrate the annotation behavior.
98+
99+
.. tip::
100+
101+
The ``org.bson.codecs.records.annotations`` package is deprecated. Use the
102+
equivalent ones from the `org.bson.codecs.pojo.annotations <{+api+}/apidocs/bson/org/bson/codecs/pojo/annotations/package-summary.html>`__
103+
package instead.
104+
105+
You can use the following annotations on record components:
106+
107+
.. list-table::
108+
:header-rows: 1
109+
:stub-columns: 1
110+
:widths: 10 10
111+
112+
* - Annotation Name
113+
- Description
114+
115+
* - ``BsonId``
116+
- Specifies the component to serialize as the _id property.
117+
118+
* - ``BsonProperty``
119+
- Specifies a custom document field name when converting the record
120+
component to BSON. Accepts the field name as the parameter.
121+
122+
* - ``BsonRepresentation``
123+
- Specifies a BSON type to store when different from the record component
124+
type. Accepts the BSON type as the parameter.
125+
126+
Example Annotated Record
127+
~~~~~~~~~~~~~~~~~~~~~~~~
128+
129+
The code examples in this section reference the following sample record, which
130+
describes a network device:
131+
132+
.. literalinclude:: /includes/fundamentals/code-snippets/records/NetworkDeviceRecord.java
133+
:language: java
134+
:start-after: start networkDeviceRecord
135+
:end-before: end networkDeviceRecord
136+
137+
Insert an Annotated Record
138+
~~~~~~~~~~~~~~~~~~~~~~~~~~
139+
140+
You can insert a ``DataStorageRecord`` instance as shown in the following code:
141+
142+
.. code-block:: java
143+
144+
MongoCollection<NetworkDeviceRecord> collection = database.getCollection("network_devices", NetworkDeviceRecord.class);
145+
146+
// insert the record
147+
String deviceId = new ObjectId().toHexString();
148+
collection.insertOne(new NetworkDeviceRecord(deviceId, "Enterprise Wi-fi", "router"));
149+
150+
The inserted document in MongoDB should resemble the following:
151+
152+
.. code-block:: json
153+
:copyable: false
154+
155+
{
156+
_id: ObjectId("fedc..."),
157+
name: 'Enterprise Wi-fi',
158+
type: 'router'
159+
}
160+
161+
162+
Retrieve an Annotated Record
163+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
164+
165+
You can retrieve documents as ``NetworkDeviceRecord`` instances and print them
166+
as shown in the following code:
167+
168+
.. io-code-block::
169+
:copyable: true
170+
171+
.. input::
172+
:language: java
173+
174+
MongoCollection<NetworkDeviceRecord> collection = database.getCollection("network_devices", NetworkDeviceRecord.class);
175+
176+
// return all documents in the collection as records
177+
List<NetworkDeviceRecord> records = new ArrayList<NetworkDeviceRecord>();
178+
collection.find().into(records);
179+
records.forEach(System.out::println);
180+
181+
.. output::
182+
:language: none
183+
184+
NetworkDeviceRecord[deviceId=fedc..., name=Enterprise Wi-fi, deviceType=router]
185+

‎source/includes/fundamentals/code-snippets/records/NetworkDeviceRecord.java‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
package fundamentals.codecs.records;
2+
3+
// start networkDeviceRecord
4+
import org.bson.BsonType;
5+
import org.bson.codecs.pojo.annotations.BsonProperty;
6+
import org.bson.codecs.pojo.annotations.BsonId;
7+
import org.bson.codecs.pojo.annotations.BsonRepresentation;
8+
9+
public record NetworkDeviceRecord(
10+
@BsonId()
11+
@BsonRepresentation(BsonType.OBJECT_ID)
12+
String deviceId,
13+
String name,
14+
@BsonProperty("type")
15+
String deviceType
16+
)
17+
{}
18+
// end networkDeviceRecord

‎source/includes/fundamentals/code-snippets/records/RecordAnnotationExample.java‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
package fundamentals.codecs.records;
2+
3+
import com.mongodb.client.MongoClient;
4+
import com.mongodb.client.MongoClients;
5+
import com.mongodb.client.MongoCollection;
6+
import com.mongodb.client.MongoDatabase;
7+
import com.mongodb.client.result.InsertOneResult;
8+
9+
import java.util.ArrayList;
10+
import java.util.List;
11+
12+
public class RecordAnnotationExample {
13+
public static void main(String[] args) {
14+
// Replace the uri string with your MongoDB deployment's connection string
15+
String uri = "<your connection uri>";
16+
try (MongoClient mongoClient = MongoClients.create(uri)) {
17+
18+
MongoDatabase database = mongoClient.getDatabase("sample_data");
19+
MongoCollection<NetworkDeviceRecord> collection = database.getCollection("network_devices", NetworkDeviceRecord.class);
20+
21+
// insert the document
22+
String deviceId = new ObjectId().toHexString();
23+
collection.insertOne(new NetworkDeviceRecord(deviceId, "Enterprise Wi-fi", "router"));
24+
25+
// return all documents in the collection as records
26+
List<NetworkDeviceRecord> records = new ArrayList<NetworkDeviceRecord>();
27+
collection.find().into(records);
28+
records.forEach(System.out::println);
29+
}
30+
}
31+
}

0 commit comments

Comments
 (0)