make format optional and create testing case about $dateToString aggregation with timezone outputs invalid ISO8601 string

Author: NathanQingyangXu

driver-core/src/main/com/mongodb/client/model/mql/MqlDate.java

@@ -19,6 +19,7 @@
 import com.mongodb.annotations.Beta;
 import com.mongodb.annotations.Reason;
 import com.mongodb.annotations.Sealed;
+import com.mongodb.lang.Nullable;
 
 import java.util.function.Function;
 
@@ -132,11 +133,19 @@ public interface MqlDate extends MqlValue {
      * The string representation of {@code this} date as determined by the
      * provided {@code timezone}, and formatted according to the {@code format}.
      *
+     * <p>
+     * If {@code format} is unspecified and the {@code timezone} is set to a non UTC timezone, then
+     * {@code "%Y-%m-%dT%H:%M:%S.%L"} will be the default format.
+     *
+     * <p>
+     * If {@code format} is unspecified and the {@code timezone} is UTC, then
+     * {@code "%Y-%m-%dT%H:%M:%S.%LZ"} will be the default format.
+     *
      * @param timezone the UTC Offset or Olson Timezone Identifier.
-     * @param format the format specifier.
+     * @param format the optional format specifier.
      * @return the resulting value.
      */
-    MqlString asString(MqlString timezone, MqlString format);
+    MqlString asString(MqlString timezone, @Nullable MqlString format);
 
     /**
      * The result of passing {@code this} value to the provided function.

driver-core/src/main/com/mongodb/client/model/mql/MqlExpression.java

@@ -17,6 +17,7 @@
 package com.mongodb.client.model.mql;
 
 import com.mongodb.assertions.Assertions;
+import com.mongodb.lang.Nullable;
 import org.bson.BsonArray;
 import org.bson.BsonDocument;
 import org.bson.BsonInt32;
@@ -944,13 +945,15 @@ public MqlInteger millisecond(final MqlString timezone) {
     }
 
     @Override
-    public MqlString asString(final MqlString timezone, final MqlString format) {
-        Assertions.notNull("timezone", timezone);
-        Assertions.notNull("format", format);
-        return newMqlExpression((cr) -> astDoc("$dateToString", new BsonDocument()
-                .append("date", this.toBsonValue(cr))
-                .append("format", toBsonValue(cr, format))
-                .append("timezone", toBsonValue(cr, timezone))));
+    public MqlString asString(final MqlString timezone, @Nullable final MqlString format) {
+        return newMqlExpression((cr) -> {
+            BsonDocument document = new BsonDocument("date", this.toBsonValue(cr));
+            if (format != null) {
+                document.append("format", toBsonValue(cr, format));
+            }
+            document.append("timezone", toBsonValue(cr, timezone));
+            return astDoc("$dateToString", document);
+        });
     }
 
     @Override

driver-core/src/test/functional/com/mongodb/client/model/mql/TypeMqlValuesFunctionalTest.java

@@ -26,6 +26,7 @@
 import java.time.ZoneId;
 import java.time.ZoneOffset;
 import java.time.ZonedDateTime;
+import java.time.format.DateTimeFormatter;
 import java.util.Arrays;
 
 import static com.mongodb.ClusterFixture.serverVersionAtLeast;
@@ -225,6 +226,35 @@ public void dateAsStringTest() {
                 of(instant).asString(of("America/New_York"), of("%Y-%m-%dT%H:%M:%S.%L%z")));
     }
 
+    /**
+     * Tests that with default format and non-UTC timezone, {@code $dateToString} won't output invalid ISO 8601 string ending with 'Z'.
+     * Ticket: JAVA-5044
+     */
+    @Test
+    void dateAsStringWithDefaultFormat() {
+        // the bug was reported on v6.0.3, but was fixed in v7.1 without backporting
+        // due to the concern that it is a breaking change.
+        assumeTrue(serverVersionAtLeast(7, 1));
+
+        final Instant instant = Instant.parse("2025-07-17T18:00:36.052Z");
+        MqlDate date = of(instant);
+        ZonedDateTime utcDateTime = ZonedDateTime.ofInstant(instant, ZoneId.of(ZoneOffset.UTC.getId()));
+
+        // UTC timezone's default format should be "%Y-%m-%dT%H:%M:%S.%LZ"
+        assertExpression(
+                utcDateTime.format(DateTimeFormatter.ISO_INSTANT),
+                date.asString(of("UTC"), null),
+                "{'$dateToString': {'date': {'$date': '2025-07-17T18:00:36.052Z'}, "
+                        + "'timezone': 'UTC'}}");
+
+        // non-UTC timezone's default format should be "%Y-%m-%dT%H:%M:%S.%L"
+        assertExpression(
+                utcDateTime.withZoneSameInstant(ZoneId.of("America/New_York")).format(ISO_LOCAL_DATE_TIME),
+                date.asString(of("America/New_York"), null),
+                "{'$dateToString': {'date': {'$date': '2025-07-17T18:00:36.052Z'}, "
+                        + "'timezone': 'America/New_York'}}");
+    }
+
     // parse string
 
     @Test