Backport OffsetDateTime changes from 4.0 (#3090)

Backport OffsetDateTime changes from Java/Python on 4.0 where OffsetDateTime is now the default Date type in Gremlin, while retained Date as accepted input for steps. Added OffsetDateTime serializers to Go/JS/.NET. Made OffsetDateTime the default serializer for date types in GLVs (Date type will only deserialize).

Author: xiazcy

CHANGELOG.asciidoc

@@ -49,6 +49,8 @@ This release also includes changes from <<release-3-7-XXX, 3.7.XXX>>.
 * Fixed bug in `group()` value traversal of the second `by()` where a `CollectingBarrierStep` could produce an unexpected filtering effect when `ReducingBarrierStep` or `SupplyingBarrierStep` instances were not taken into account.
 * Changed `DetachedFactory` to special case the handling of `ComputerAdjacentVertex` which doesn't carry properties but still needs to be detachable for OLAP cases.
 * Deprecated `ProfilingAware.prepareForProfiling` method preferring to simply `resetBarrierFromValueTraversal` from the `Grouping` interface after strategy application.
+* Deprecated `Date` in favor of `OffsetDateTime` as the default date type in core, `Date` is still supported as input to date steps for compatibility.
+* Added and made `OffsetDateTime` serializers the default for existing date types in Python, Go, JavaScript, and .NET. `Date` is only used to deserialize from server.
 * Added missing strategies in `gremlin-go`, updated certain strategies to take varargs and updated `GoTranslatorVisitor` for corresponding translations.
 * Fixed `BigInt` and `BigDecimal` parsing in `gremlin-go` cucumber test suite, fixed `UnscaledValue` type in `BigDecimal` struct and added `ParseBigDecimal` method.
 * Added validation to `groupCount()` to prevent an invalid usage of multiple `by()` modulators.

docs/src/reference/the-traversal.asciidoc

@@ -812,7 +812,7 @@ The `asDate()`-step (*map*) converts string or numeric input to Date.
 For string input only ISO-8601 format is supported. For numbers, the value is considered as the number of the
 milliseconds since "the epoch" (January 1, 1970, 00:00:00 GMT). Date input is passed without changes.
 
-If the incoming traverser is not a string, number or Date then an `IllegalArgumentException` will be thrown.
+If the incoming traverser is not a string, number, Date or OffsetDateTime then an `IllegalArgumentException` will be thrown.
 
 [gremlin-groovy,modern]
 ----
@@ -1354,7 +1354,7 @@ link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gre
 === DateAdd Step
 
 The `dateAdd()`-step (*map*) returns the value with the addition of the value number of units as specified by the DateToken. 
-If the incoming traverser is not a Date, then an `IllegalArgumentException` will be thrown.
+If the incoming traverser is not a Date or OffsetDateTime, then an `IllegalArgumentException` will be thrown.
 
 [gremlin-groovy,modern]
 ----
@@ -1373,7 +1373,7 @@ link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gre
 === DateDiff Step
 
 The `dateDiff()`-step (*map*) returns the difference between two Dates in epoch time. 
-If the incoming traverser is not a Date, then an `IllegalArgumentException` will be thrown.
+If the incoming traverser is not a Date or OffsetDateTime, then an `IllegalArgumentException` will be thrown.
 
 [gremlin-groovy,modern]
 ----
@@ -1385,6 +1385,7 @@ g.inject("2023-08-02T00:00:00Z").asDate().dateDiff(constant("2023-08-03T00:00:00
 *Additional References*
 
 link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#dateDiff(java.util.Date)++[`dateDiff(Date)`],
+link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#dateDiff(java.util.Date)++[`dateDiff(OffsetDateTime)`],
 link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#dateDiff(org.apache.tinkerpop.gremlin.process.traversal.Traversal)++[`dateDiff(Traversal)`]
 
 [[dedup-step]]

docs/src/upgrade/release-3.8.x.asciidoc

@@ -30,6 +30,17 @@ complete list of all the modifications that are part of this release.
 
 === Upgrading for Users
 
+==== The Switch from Date to OffsetDateTime
+The default implementation for date type in Gremlin is now changed from the `java.util.Date` to the more encompassing `java.time.OffsetDateTime`. This means the reference implementation for all date manipulation steps, `asDate()`, `dateAdd()`, and `dateDiff()`, as well as helper methods `datetime()`, will return `OffsetDateTime`, whose string representation will be in ISO 8601 format.
+
+`Date` is still supported as incoming traverser results for these steps, as well as input into `dateDiff()` for compatibility purposes. All dates are assumed to be in `UTC` (given epoch time).
+
+If one is using a persisted TinkerGraph that stored `Date` objects inside properties, one may notice `OffsetDateTime` being returned after traversal manipulation. The recommended solution is to update all existing `Date` objects into `OffsetDateTime`. This can be done by querying for the properties and transforming them using `asDate()`. Do note that all dates are assumed to be in `UTC` (given epoch time).
+
+For Python, Go, JavaScript, and .NET GLVs, the existing date types are retained. The change is at the serialization level, where the exiting date type will be serialized as `OffsetDateTime` to the server, and both `Date` and `OffsetDateTime` from the server will be deserialized into the existing date types in the host language. As such, users of these GLVs should not notice impact to the application code. The caution remains in cases when client is accessing a database with `Date` object stored, the `Date` to `OffsetDateTime` transformations on the server assumes `UTC` timezone.
+
+For Java GLV, this change would impact users who are expecting the old `Date` object from a traversal in their application, in this case the recommendation is to update code to expect `OffsetDateTime` as part of the version upgrade.
+
 ==== Simplification to g creation
 The creation of "g" is the start point to writing Gremlin. There are a number of ways to create it, but TinkerPop has
 long recommended the use of the anonymous `traversal()` function for this creation.
@@ -284,4 +295,16 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-3121[TINKERPOP-3121]
 
 ==== Graph System Providers
 
+==== The Switch from Date to OffsetDateTime
+The default implementation for date type in Gremlin is now changed from the deprecated `java.util.Date` to the more encompassing `java.time.OffsetDateTime`. This means the reference implementation for all date manipulation steps, `asDate()`, `dateAdd()`, and `dateDiff()`, as well as helper methods `datetime()`, will return `OffsetDateTime`, whose string representation will be in ISO 8601 format.
+
+`Date` is still supported as incoming traverser results for these steps, as well as input into `dateDiff()` for compatibility purposes. All dates are assumed to be in `UTC` (given epoch time).
+
+This may impact providers who use TinkerGraph or whose implementation store dates as `java.util.Date`. While steps will support `Date`, all date manipulations will output `OffsetDateTime`. If a user had persisted `Date` objects in the database, upgrading to 3.8 may lead to the database having both types stored. It is recommended for users to perform transformation of `Date` to `OffsetDateTime` to retain consistency.
+
 ==== Graph Driver Providers
+
+==== The Switch from Date to OffsetDateTime
+The default implementation for date type in Gremlin is now changed from the deprecated `java.util.Date` to the more encompassing `java.time.OffsetDateTime`. This means the reference implementation for all date manipulation steps, `asDate()`, `dateAdd()`, and `dateDiff()`, as well as helper methods `datetime()`, will return `OffsetDateTime`, whose string representation will be in ISO 8601 format.
+
+This means that drivers should use the extended `OffsetDateTime` type in the IO specs to serialize and deserialize native date objects.

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/jsr223/CoreImports.java

@@ -330,6 +330,7 @@ public final class CoreImports {
         CLASS_IMPORTS.add(TimeUtil.class);
         CLASS_IMPORTS.add(Lambda.class);
         CLASS_IMPORTS.add(java.util.Date.class);
+        CLASS_IMPORTS.add(java.time.OffsetDateTime.class);
         CLASS_IMPORTS.add(java.sql.Timestamp.class);
         CLASS_IMPORTS.add(java.util.UUID.class);
 

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/language/grammar/ArgumentVisitor.java

@@ -22,7 +22,8 @@
 import org.apache.tinkerpop.gremlin.util.iterator.IteratorUtils;
 
 import java.lang.reflect.Array;
-import java.util.Date;
+import java.time.OffsetDateTime;
+import java.util.Comparator;
 import java.util.Map;
 import java.util.Objects;
 
@@ -68,8 +69,8 @@ public String parseString(final GremlinParser.StringArgumentContext ctx) {
     /**
      * Wrapper to visit function for Date type.
      */
-    public Date parseDate(final GremlinParser.DateArgumentContext ctx) {
-        return (Date) visitDateArgument(ctx);
+    public OffsetDateTime parseDate(final GremlinParser.DateArgumentContext ctx) {
+        return (OffsetDateTime) visitDateArgument(ctx);
     }
 
     /**

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/language/grammar/GenericLiteralVisitor.java

@@ -31,8 +31,8 @@
 
 import java.math.BigDecimal;
 import java.math.BigInteger;
+import java.time.OffsetDateTime;
 import java.util.ArrayList;
-import java.util.Date;
 import java.util.HashSet;
 import java.util.LinkedHashMap;
 import java.util.List;
@@ -86,8 +86,8 @@ public String parseString(final GremlinParser.StringNullableLiteralContext strin
     /**
      * Parse a Date based literal context and return the Date.
      */
-    public Date parseDate(final GremlinParser.DateLiteralContext dateLiteral) {
-        return (Date) visitDateLiteral(dateLiteral);
+    public OffsetDateTime parseDate(final GremlinParser.DateLiteralContext dateLiteral) {
+        return (OffsetDateTime) visitDateLiteral(dateLiteral);
     }
 
     /**

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/language/translator/AnonymizedTranslatorVisitor.java

@@ -23,7 +23,7 @@
 
 import java.math.BigDecimal;
 import java.math.BigInteger;
-import java.util.Date;
+import java.time.OffsetDateTime;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -167,7 +167,7 @@ public Void visitBooleanLiteral(final GremlinParser.BooleanLiteralContext ctx) {
 
     @Override
     public Void visitDateLiteral(final GremlinParser.DateLiteralContext ctx) {
-        return anonymize(ctx, Date.class);
+        return anonymize(ctx, OffsetDateTime.class);
     }
 
     @Override

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/language/translator/DotNetTranslateVisitor.java

@@ -27,7 +27,7 @@
 import org.apache.tinkerpop.gremlin.structure.VertexProperty;
 import org.apache.tinkerpop.gremlin.util.DatetimeHelper;
 
-import java.util.Date;
+import java.time.OffsetDateTime;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -158,10 +158,10 @@ public Void visitFloatLiteral(final GremlinParser.FloatLiteralContext ctx) {
     public Void visitDateLiteral(final GremlinParser.DateLiteralContext ctx) {
         // child at 2 is the date argument to datetime() and comes enclosed in quotes
         final String dtString = ctx.getChild(2).getText();
-        final Date dt = DatetimeHelper.parse(removeFirstAndLastCharacters(dtString));
-        sb.append("DateTimeOffset.FromUnixTimeMilliseconds(");
-        sb.append(dt.getTime());
-        sb.append(")");
+        final OffsetDateTime dt = DatetimeHelper.parse(removeFirstAndLastCharacters(dtString));
+        sb.append("DateTimeOffset.Parse(\"");
+        sb.append(dt);
+        sb.append("\")");
         return null;
     }
 

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/language/translator/GoTranslateVisitor.java

@@ -27,9 +27,9 @@
 import org.apache.tinkerpop.gremlin.structure.VertexProperty;
 import org.apache.tinkerpop.gremlin.util.DatetimeHelper;
 
+import java.time.OffsetDateTime;
 import java.util.Arrays;
 import java.util.Collections;
-import java.util.Date;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -57,8 +57,17 @@ public GoTranslateVisitor(final String graphTraversalSourceName) {
     public Void visitDateLiteral(final GremlinParser.DateLiteralContext ctx) {
         // child at 2 is the date argument to datetime() and comes enclosed in quotes
         final String dtString = ctx.getChild(2).getText();
-        final Date dt = DatetimeHelper.parse(removeFirstAndLastCharacters(dtString));
-        sb.append("time.UnixMilli(" + dt.getTime() + ")");
+        final OffsetDateTime dt = DatetimeHelper.parse(removeFirstAndLastCharacters(dtString));
+        final String zoneInfo = dt.getOffset().getId().equals("Z") ? "UTC+00:00" : "UTC" + dt.getOffset().getId();
+        sb.append("time.Date(").append(dt.getYear()).
+                append(", ").append(dt.getMonthValue()).
+                append(", ").append(dt.getDayOfMonth()).
+                append(", ").append(dt.getHour()).
+                append(", ").append(dt.getMinute()).
+                append(", ").append(dt.getSecond()).
+                append(", ").append(dt.getNano()).
+                append(", time.FixedZone(\"").append(zoneInfo).append("\", ").append(dt.getOffset().getTotalSeconds()).append(")").
+                append(")");
         return null;
     }
 

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/language/translator/JavaTranslateVisitor.java

@@ -25,7 +25,7 @@
 import org.apache.tinkerpop.gremlin.structure.util.reference.ReferenceVertex;
 import org.apache.tinkerpop.gremlin.util.DatetimeHelper;
 
-import java.util.Date;
+import java.time.OffsetDateTime;
 import java.util.List;
 import java.util.stream.Collectors;
 
@@ -152,10 +152,10 @@ public Void visitMapKey(final GremlinParser.MapKeyContext ctx) {
     public Void visitDateLiteral(final GremlinParser.DateLiteralContext ctx) {
         // child at 2 is the date argument to datetime() and comes enclosed in quotes
         final String dtString = ctx.getChild(2).getText();
-        final Date dt = DatetimeHelper.parse(removeFirstAndLastCharacters(dtString));
-        sb.append("new Date(");
-        sb.append(dt.getTime());
-        sb.append(")");
+        final OffsetDateTime dt = DatetimeHelper.parse(removeFirstAndLastCharacters(dtString));
+        sb.append("OffsetDateTime.parse(\"");
+        sb.append(dt);
+        sb.append("\")");
         return null;
     }