DOCSP-30481: replace date with LocalDateTime (#108)

rustagir · web-flow · commit baabb3cbd414 · 2023-06-30T09:28:54.000-04:00
# Pull Request Info [PR Reviewing Guidelines](https://github.com/mongodb/docs-java/blob/master/REVIEWING.md) JIRA - https://jira.mongodb.org/browse/DOCSP-30481 Staging: - [Documents](https://docs-mongodbcom-staging.corp.mongodb.com/kotlin/docsworker-xlarge/DOCSP-30481-localdatetime/fundamentals/data-formats/documents/) - [Extended JSON](https://docs-mongodbcom-staging.corp.mongodb.com/kotlin/docsworker-xlarge/DOCSP-30481-localdatetime/fundamentals/data-formats/document-data-format-extended-json/) ## Self-Review Checklist - [ ] Is this free of any warnings or errors in the RST? - [ ] Did you run a spell-check? - [ ] Did you run a grammar-check? - [ ] Are all the links working?
diff --git a/examples/src/test/kotlin/DocumentsTest.kt b/examples/src/test/kotlin/DocumentsTest.kt
@@ -11,8 +11,10 @@ import org.bson.types.ObjectId
 import org.junit.jupiter.api.AfterAll
 import org.junit.jupiter.api.Assertions.*
 import org.junit.jupiter.api.TestInstance
-import java.time.LocalDate
+import java.time.Instant
+import java.time.LocalDateTime
 import java.time.ZoneId
+import java.time.ZoneOffset
 import java.util.*
 import kotlin.test.*
 
@@ -40,10 +42,7 @@ internal class DocumentsTest {
             .append("name", "Gabriel García Márquez")
             .append(
                 "dateOfDeath",
-                Date.from(
-                    LocalDate.of(2014, 4, 17)
-                        .atStartOfDay(ZoneId.systemDefault()).toInstant()
-                )
+                LocalDateTime.of(2014, 4, 17, 4, 0)
             )
             .append(
                 "novels", listOf(
@@ -96,8 +95,7 @@ internal class DocumentsTest {
             .append(
                 "dateOfDeath",
                 BsonDateTime(
-                    LocalDate.of(2014, 4, 17)
-                        .atStartOfDay(ZoneId.systemDefault()).toInstant().toEpochMilli()
+                    LocalDateTime.of(2014, 4, 17, 0, 0).atZone(ZoneId.of("America/New_York")).toInstant().toEpochMilli()
                 )
             )
             .append(
@@ -135,7 +133,7 @@ internal class DocumentsTest {
 
         val doc = collection.find(Filters.eq("name", "Gabriel García Márquez")).firstOrNull()
         doc?.let {
-            println("_id: ${it.getObjectId("_id").value}, name: ${it.getString("name").value}, dateOfDeath: ${Date(it.getDateTime("dateOfDeath").value)}")
+            println("_id: ${it.getObjectId("_id").value}, name: ${it.getString("name").value}, dateOfDeath: ${Instant.ofEpochMilli(it.getDateTime("dateOfDeath").value).atZone(ZoneId.of("America/New_York")).toLocalDateTime()}")
 
             it.getArray("novels").forEach { novel ->
                 val novelDocument = novel.asDocument()
diff --git a/examples/src/test/kotlin/EjsonTest.kt b/examples/src/test/kotlin/EjsonTest.kt
@@ -9,12 +9,12 @@ import org.junit.jupiter.api.Assertions.*
 import org.junit.jupiter.api.TestInstance
 import java.io.BufferedWriter
 import java.io.OutputStreamWriter
-import java.time.Instant
-import java.time.ZoneOffset
+import java.time.*
 import java.time.format.DateTimeFormatter
 import java.util.*
 import kotlin.test.*
 
+
 @TestInstance(TestInstance.Lifecycle.PER_CLASS)
 internal class EjsonTest {
 
@@ -94,15 +94,15 @@ internal class EjsonTest {
         val settings = JsonWriterSettings.builder()
             .outputMode(JsonMode.RELAXED)
             .objectIdConverter { value, writer -> writer.writeString(value.toHexString()) }
-            .dateTimeConverter { value, writer ->
-                val zonedDateTime = Instant.ofEpochMilli(value).atZone(ZoneOffset.UTC)
-                writer.writeString(DateTimeFormatter.ISO_DATE_TIME.format(zonedDateTime))
+            .timestampConverter { value, writer ->
+                val ldt = LocalDateTime.ofInstant(Instant.ofEpochSecond(value.time.toLong()), ZoneOffset.UTC)
+                writer.writeString(ldt.format(DateTimeFormatter.ISO_DATE_TIME))
             }
             .build()
 
         val doc = Document()
             .append("_id", ObjectId("507f1f77bcf86cd799439012"))
-            .append("createdAt", Date.from(Instant.ofEpochMilli(1601499609000L)))
+            .append("createdAt", BsonTimestamp(1601516589,1))
             .append("myNumber", 4794261)
 
         println(doc.toJson(settings))
diff --git a/examples/src/test/kotlin/UpdatesBuildersTest.kt b/examples/src/test/kotlin/UpdatesBuildersTest.kt
@@ -166,7 +166,7 @@ class UpdatesBuildersTest {
         // :snippet-start: current-timestamp-update
         // Create a new instance of the collection with the flexible `Document` type
         // to allow for the changing of the `lastModified` field to a `BsonTimestamp`
-        // from a `Date`.
+        // from a `LocalDateTime`.
         val collection = database.getCollection<Document>("paint_orders")
 
         val filter = Filters.eq("_id", 1)
diff --git a/source/examples/generated/DocumentsTest.snippet.create-bson-document.kt b/source/examples/generated/DocumentsTest.snippet.create-bson-document.kt
@@ -4,8 +4,7 @@ val author = BsonDocument()
     .append(
         "dateOfDeath",
         BsonDateTime(
-            LocalDate.of(2014, 4, 17)
-                .atStartOfDay(ZoneId.systemDefault()).toInstant().toEpochMilli()
+            LocalDateTime.of(2014, 4, 17, 0, 0).atZone(ZoneId.of("America/New_York")).toInstant().toEpochMilli()
         )
     )
     .append(
diff --git a/source/examples/generated/DocumentsTest.snippet.create-document.kt b/source/examples/generated/DocumentsTest.snippet.create-document.kt
@@ -2,10 +2,7 @@ val author = Document("_id", ObjectId())
     .append("name", "Gabriel García Márquez")
     .append(
         "dateOfDeath",
-        Date.from(
-            LocalDate.of(2014, 4, 17)
-                .atStartOfDay(ZoneId.systemDefault()).toInstant()
-        )
+        LocalDateTime.of(2014, 4, 17, 4, 0)
     )
     .append(
         "novels", listOf(
diff --git a/source/examples/generated/DocumentsTest.snippet.retrieve-bson-document.kt b/source/examples/generated/DocumentsTest.snippet.retrieve-bson-document.kt
@@ -2,7 +2,7 @@
 
 val doc = collection.find(Filters.eq("name", "Gabriel García Márquez")).firstOrNull()
 doc?.let {
-    println("_id: ${it.getObjectId("_id").value}, name: ${it.getString("name").value}, dateOfDeath: ${Date(it.getDateTime("dateOfDeath").value)}")
+    println("_id: ${it.getObjectId("_id").value}, name: ${it.getString("name").value}, dateOfDeath: ${Instant.ofEpochMilli(it.getDateTime("dateOfDeath").value).atZone(ZoneId.of("America/New_York")).toLocalDateTime()}")
 
     it.getArray("novels").forEach { novel ->
         val novelDocument = novel.asDocument()
diff --git a/source/examples/generated/EjsonTest.snippet.custom-bson-type-conversion.kt b/source/examples/generated/EjsonTest.snippet.custom-bson-type-conversion.kt
@@ -1,15 +1,15 @@
 val settings = JsonWriterSettings.builder()
     .outputMode(JsonMode.RELAXED)
     .objectIdConverter { value, writer -> writer.writeString(value.toHexString()) }
-    .dateTimeConverter { value, writer ->
-        val zonedDateTime = Instant.ofEpochMilli(value).atZone(ZoneOffset.UTC)
-        writer.writeString(DateTimeFormatter.ISO_DATE_TIME.format(zonedDateTime))
+    .timestampConverter { value, writer ->
+        val ldt = LocalDateTime.ofInstant(Instant.ofEpochSecond(value.time.toLong()), ZoneOffset.UTC)
+        writer.writeString(ldt.format(DateTimeFormatter.ISO_DATE_TIME))
     }
     .build()
 
 val doc = Document()
     .append("_id", ObjectId("507f1f77bcf86cd799439012"))
-    .append("createdAt", Date.from(Instant.ofEpochMilli(1601499609000L)))
+    .append("createdAt", BsonTimestamp(1601516589,1))
     .append("myNumber", 4794261)
 
 println(doc.toJson(settings))
diff --git a/source/examples/generated/UpdatesBuildersTest.snippet.current-timestamp-update.kt b/source/examples/generated/UpdatesBuildersTest.snippet.current-timestamp-update.kt
@@ -1,6 +1,6 @@
 // Create a new instance of the collection with the flexible `Document` type
 // to allow for the changing of the `lastModified` field to a `BsonTimestamp`
-// from a `Date`.
+// from a `LocalDateTime`.
 val collection = database.getCollection<Document>("paint_orders")
 
 val filter = Filters.eq("_id", 1)
diff --git a/source/fundamentals/data-formats/document-data-format-extended-json.txt b/source/fundamentals/data-formats/document-data-format-extended-json.txt
@@ -271,14 +271,14 @@ expressions, to simplify the Relaxed mode JSON output.
    .. output::
       :language: javascript
 
-      {"_id": "507f1f77bcf86cd799439012", "createdAt": "2020-09-30T21:00:09Z", "myNumber": 4794261}
+      {"_id": "507f1f77bcf86cd799439012", "createdAt": "2020-10-01T01:43:09", "myNumber": 4794261}
 
       // Without specifying the converters, the Relaxed mode JSON output
       // should look something like this:
-      {"_id": {"$oid": "507f1f77bcf86cd799439012"}, "createdAt": {"$date": "2020-09-30T21:00:09Z"}, "myNumber": 4794261}
+      {"_id": {"$oid": "507f1f77bcf86cd799439012"}, "createdAt": {"$timestamp": {"t": 1601516589, "i": 1}}, "myNumber": 4794261}
 
 For more information about the methods and classes mentioned in this section,
 see the following API Documentation:
 
 - `Converter <{+api+}/apidocs/bson/org/bson/json/Converter.html>`__
-- `JsonWriterSettings.Builder <{+api+}/apidocs/bson/org/bson/json/JsonWriterSettings.Builder.html>`__
+- `JsonWriterSettings.Builder <{+api+}/apidocs/bson/org/bson/json/JsonWriterSettings.Builder.html>`__
diff --git a/source/fundamentals/data-formats/documents.txt b/source/fundamentals/data-formats/documents.txt
@@ -81,7 +81,7 @@ frequently-used BSON and Kotlin types:
    * - Boolean
      - ``kotlin.Boolean``
    * - Date
-     - ``java.util.Date``
+     - ``java.time.LocalDateTime``
    * - Document
      - ``org.bson.Document``
    * - Double
@@ -209,7 +209,7 @@ data from the collection using the following code:
    .. output::
       :language: none
 
-      _id: 5fb5fad05f734e3794741a35, name: Gabriel García Márquez, dateOfDeath: Thu Apr 17 00:00:00 EDT 2014
+      _id: 5fb5fad05f734e3794741a35, name: Gabriel García Márquez, dateOfDeath: 2014-04-17T00:00
       title: One Hundred Years of Solitude, yearPublished: 1967
       title: Chronicle of a Death Foretold, yearPublished: 1981
       title: Love in the Time of Cholera, yearPublished: 1985

Original file line number	Diff line number	Diff line change
`@@ -4,8 +4,7 @@ val author = BsonDocument()`
`4`	`4`	`.append(`
`5`	`5`	`"dateOfDeath",`
`6`	`6`	`BsonDateTime(`
`7`		`- LocalDate.of(2014, 4, 17)`
`8`		`- .atStartOfDay(ZoneId.systemDefault()).toInstant().toEpochMilli()`
	`7`	`+ LocalDateTime.of(2014, 4, 17, 0, 0).atZone(ZoneId.of("America/New_York")).toInstant().toEpochMilli()`
`9`	`8`	`)`
`10`	`9`	`)`
`11`	`10`	`.append(`