feat: introduce java.time (#2415)

This PR introduces `java.time` alternatives to existing `org.threeten.bp.*` methods, as well as switching internal variables (if any) to `java.time`

The main constraint is to keep the changes backwards compatible, so for each existing threeten method "`method1(org.threeten.bp.Duration)`" we will add an alternative with a _Duration_ (or _Timestamp_ when applicable) suffix: "`method1Duration(java.time.Duration)`".

For most cases, the implementation will be held in the `java.time` method and the old threeten method will just delegate the call to it. However, for the case of abstract classes, the implementation will be kept in the threeten method to avoid breaking changes (i.e. users that already overloaded the method in their user code).

Note: https://cloud.google.com/bigtable/docs/reference/sql/data-types#timestamp_type implies that nanosecond precision will be ignored.

Author: diegomarquezp

google-cloud-bigtable/clirr-ignored-differences.xml

@@ -275,4 +275,37 @@
         <className>com/google/cloud/bigtable/data/v2/stub/metrics/DefaultMetricsProvider</className>
         <method>*</method>
     </difference>
+    <difference>
+        <!-- InternalApi was updated -->
+        <differenceType>7006</differenceType>
+        <className>com/google/cloud/bigtable/data/v2/internal/*</className>
+        <method>*getTimestamp(*)</method>
+        <to>java.time.Instant</to>
+    </difference>
+    <difference>
+        <!-- BetaApi was updated -->
+        <differenceType>7006</differenceType>
+        <className>com/google/cloud/bigtable/data/v2/models/sql/StructReader</className>
+        <method>*getTimestamp(*)</method>
+        <to>java.time.Instant</to>
+    </difference>
+    <difference>
+        <!-- BetaApi was updated -->
+        <differenceType>7005</differenceType>
+        <className>com/google/cloud/bigtable/data/v2/models/sql/Statement$Builder</className>
+        <method>*setTimestampParam(java.lang.String, org.threeten.bp.Instant)</method>
+        <to>*setTimestampParam(java.lang.String, java.time.Instant)</to>
+    </difference>
+    <difference>
+        <!-- ChangeStream api is internal, only used by apache/beam-->
+        <differenceType>7013</differenceType>
+        <className>com/google/cloud/bigtable/data/v2/models/ChangeStreamMutation</className>
+        <method>*get*Time()</method>
+    </difference>
+    <difference>
+        <!-- Heartbeat is part of the ChangeStream api, which is internal and only used by apache/beam-->
+        <differenceType>7013</differenceType>
+        <className>com/google/cloud/bigtable/data/v2/models/Heartbeat</className>
+        <method>*getEstimatedLowWatermarkTime()</method>
+    </difference>
 </differences>

google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/common/Type.java

@@ -23,8 +23,8 @@
 import com.google.common.base.Objects;
 import com.google.common.collect.ImmutableList;
 import com.google.protobuf.ByteString;
+import java.time.Instant;
 import java.util.List;
-import org.threeten.bp.Instant;
 
 /**
  * Shared type implementations. Right now this is only used by SqlType but this will become a shared

google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/data/v2/BigtableDataSettings.java

@@ -39,7 +39,6 @@
 import java.util.logging.Logger;
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
-import org.threeten.bp.Duration;
 
 /**
  * Settings class to configure an instance of {@link BigtableDataClient}.
@@ -134,9 +133,11 @@ public static Builder newBuilderForEmulator(String hostname, int port) {
                 .setMaxInboundMessageSize(256 * 1024 * 1024)
                 .setChannelPoolSettings(ChannelPoolSettings.staticallySized(1))
                 .setChannelConfigurator(ManagedChannelBuilder::usePlaintext)
-                .setKeepAliveTime(Duration.ofSeconds(61)) // sends ping in this interval
-                .setKeepAliveTimeout(
-                    Duration.ofSeconds(10)) // wait this long before considering the connection dead
+                .setKeepAliveTimeDuration(
+                    java.time.Duration.ofSeconds(61)) // sends ping in this interval
+                .setKeepAliveTimeoutDuration(
+                    java.time.Duration.ofSeconds(
+                        10)) // wait this long before considering the connection dead
                 .build());
 
     LOGGER.info("Connecting to the Bigtable emulator at " + hostname + ":" + port);

google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/data/v2/internal/AbstractProtoStructReader.java

@@ -25,12 +25,12 @@
 import com.google.common.base.Preconditions;
 import com.google.protobuf.ByteString;
 import com.google.protobuf.Timestamp;
+import java.time.Instant;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
-import org.threeten.bp.Instant;
 
 @InternalApi
 public abstract class AbstractProtoStructReader implements StructReader {

google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/data/v2/internal/ResultSetImpl.java

@@ -28,10 +28,10 @@
 import com.google.cloud.bigtable.data.v2.stub.sql.SqlServerStream;
 import com.google.common.base.Preconditions;
 import com.google.protobuf.ByteString;
+import java.time.Instant;
 import java.util.Iterator;
 import java.util.List;
 import java.util.Map;
-import org.threeten.bp.Instant;
 
 /**
  * The primary implementation of a ResultSet.

google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/data/v2/models/ChangeStreamMutation.java

@@ -15,15 +15,17 @@
  */
 package com.google.cloud.bigtable.data.v2.models;
 
+import static com.google.api.gax.util.TimeConversionUtils.toThreetenInstant;
+
 import com.google.api.core.InternalApi;
+import com.google.api.core.ObsoleteApi;
 import com.google.auto.value.AutoValue;
 import com.google.cloud.bigtable.data.v2.models.Range.TimestampRange;
 import com.google.cloud.bigtable.data.v2.stub.changestream.ChangeStreamRecordMerger;
 import com.google.common.collect.ImmutableList;
 import com.google.protobuf.ByteString;
 import java.io.Serializable;
 import javax.annotation.Nonnull;
-import org.threeten.bp.Instant;
 
 /**
  * A ChangeStreamMutation represents a list of mods(represented by List<{@link Entry}>) targeted at
@@ -73,13 +75,13 @@ public enum MutationType {
   static Builder createUserMutation(
       @Nonnull ByteString rowKey,
       @Nonnull String sourceClusterId,
-      Instant commitTimestamp,
+      java.time.Instant commitTimestamp,
       int tieBreaker) {
     return builder()
         .setRowKey(rowKey)
         .setType(MutationType.USER)
         .setSourceClusterId(sourceClusterId)
-        .setCommitTimestamp(commitTimestamp)
+        .setCommitTime(commitTimestamp)
         .setTieBreaker(tieBreaker);
   }
 
@@ -89,12 +91,12 @@ static Builder createUserMutation(
    * mutation.
    */
   static Builder createGcMutation(
-      @Nonnull ByteString rowKey, Instant commitTimestamp, int tieBreaker) {
+      @Nonnull ByteString rowKey, java.time.Instant commitTimestamp, int tieBreaker) {
     return builder()
         .setRowKey(rowKey)
         .setType(MutationType.GARBAGE_COLLECTION)
         .setSourceClusterId("")
-        .setCommitTimestamp(commitTimestamp)
+        .setCommitTime(commitTimestamp)
         .setTieBreaker(tieBreaker);
   }
 
@@ -110,8 +112,14 @@ static Builder createGcMutation(
   @Nonnull
   public abstract String getSourceClusterId();
 
+  /** This method is obsolete. Use {@link #getCommitTime()} instead. */
+  @ObsoleteApi("Use getCommitTime() instead")
+  public org.threeten.bp.Instant getCommitTimestamp() {
+    return toThreetenInstant(getCommitTime());
+  }
+
   /** Get the commit timestamp of the current mutation. */
-  public abstract Instant getCommitTimestamp();
+  public abstract java.time.Instant getCommitTime();
 
   /**
    * Get the tie breaker of the current mutation. This is used to resolve conflicts when multiple
@@ -123,8 +131,14 @@ static Builder createGcMutation(
   @Nonnull
   public abstract String getToken();
 
+  /** This method is obsolete. Use {@link #getEstimatedLowWatermarkTime()} instead. */
+  @ObsoleteApi("Use getEstimatedLowWatermarkTime() instead")
+  public org.threeten.bp.Instant getEstimatedLowWatermark() {
+    return toThreetenInstant(getEstimatedLowWatermarkTime());
+  }
+
   /** Get the low watermark of the current mutation. */
-  public abstract Instant getEstimatedLowWatermark();
+  public abstract java.time.Instant getEstimatedLowWatermarkTime();
 
   /** Get the list of mods of the current mutation. */
   @Nonnull
@@ -145,15 +159,15 @@ abstract static class Builder {
 
     abstract Builder setSourceClusterId(@Nonnull String sourceClusterId);
 
-    abstract Builder setCommitTimestamp(Instant commitTimestamp);
+    abstract Builder setCommitTime(java.time.Instant commitTimestamp);
 
     abstract Builder setTieBreaker(int tieBreaker);
 
     abstract ImmutableList.Builder<Entry> entriesBuilder();
 
     abstract Builder setToken(@Nonnull String token);
 
-    abstract Builder setEstimatedLowWatermark(Instant estimatedLowWatermark);
+    abstract Builder setEstimatedLowWatermarkTime(java.time.Instant estimatedLowWatermark);
 
     Builder setCell(
         @Nonnull String familyName,

google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/data/v2/models/ChangeStreamRecordAdapter.java

@@ -19,8 +19,8 @@
 import com.google.bigtable.v2.ReadChangeStreamResponse;
 import com.google.cloud.bigtable.data.v2.models.Range.TimestampRange;
 import com.google.protobuf.ByteString;
+import java.time.Instant;
 import javax.annotation.Nonnull;
-import org.threeten.bp.Instant;
 
 /**
  * An extension point that allows end users to plug in a custom implementation of logical change

google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/data/v2/models/DefaultChangeStreamRecordAdapter.java

@@ -20,9 +20,9 @@
 import com.google.cloud.bigtable.data.v2.models.Range.TimestampRange;
 import com.google.common.base.Preconditions;
 import com.google.protobuf.ByteString;
+import java.time.Instant;
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
-import org.threeten.bp.Instant;
 
 /**
  * Default implementation of a {@link ChangeStreamRecordAdapter} that uses {@link
@@ -112,8 +112,7 @@ public void startUserMutation(
 
     /** {@inheritDoc} */
     @Override
-    public void startGcMutation(
-        @Nonnull ByteString rowKey, Instant commitTimestamp, int tieBreaker) {
+    public void startGcMutation(ByteString rowKey, Instant commitTimestamp, int tieBreaker) {
       this.changeStreamMutationBuilder =
           ChangeStreamMutation.createGcMutation(rowKey, commitTimestamp, tieBreaker);
     }
@@ -176,9 +175,9 @@ public void finishCell() {
     /** {@inheritDoc} */
     @Override
     public ChangeStreamRecord finishChangeStreamMutation(
-        @Nonnull String token, Instant estimatedLowWatermark) {
+        String token, Instant estimatedLowWatermark) {
       this.changeStreamMutationBuilder.setToken(token);
-      this.changeStreamMutationBuilder.setEstimatedLowWatermark(estimatedLowWatermark);
+      this.changeStreamMutationBuilder.setEstimatedLowWatermarkTime(estimatedLowWatermark);
       return this.changeStreamMutationBuilder.build();
     }
 

google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/data/v2/models/Heartbeat.java

@@ -15,12 +15,14 @@
  */
 package com.google.cloud.bigtable.data.v2.models;
 
+import static com.google.api.gax.util.TimeConversionUtils.toThreetenInstant;
+
 import com.google.api.core.InternalApi;
+import com.google.api.core.ObsoleteApi;
 import com.google.auto.value.AutoValue;
 import com.google.bigtable.v2.ReadChangeStreamResponse;
 import java.io.Serializable;
 import javax.annotation.Nonnull;
-import org.threeten.bp.Instant;
 
 /** A simple wrapper for {@link ReadChangeStreamResponse.Heartbeat}. */
 @InternalApi("Intended for use by the BigtableIO in apache/beam only.")
@@ -29,22 +31,29 @@ public abstract class Heartbeat implements ChangeStreamRecord, Serializable {
   private static final long serialVersionUID = 7316215828353608504L;
 
   private static Heartbeat create(
-      ChangeStreamContinuationToken changeStreamContinuationToken, Instant estimatedLowWatermark) {
+      ChangeStreamContinuationToken changeStreamContinuationToken,
+      java.time.Instant estimatedLowWatermark) {
     return new AutoValue_Heartbeat(changeStreamContinuationToken, estimatedLowWatermark);
   }
 
   /** Wraps the protobuf {@link ReadChangeStreamResponse.Heartbeat}. */
   static Heartbeat fromProto(@Nonnull ReadChangeStreamResponse.Heartbeat heartbeat) {
     return create(
         ChangeStreamContinuationToken.fromProto(heartbeat.getContinuationToken()),
-        Instant.ofEpochSecond(
+        java.time.Instant.ofEpochSecond(
             heartbeat.getEstimatedLowWatermark().getSeconds(),
             heartbeat.getEstimatedLowWatermark().getNanos()));
   }
 
   @InternalApi("Intended for use by the BigtableIO in apache/beam only.")
   public abstract ChangeStreamContinuationToken getChangeStreamContinuationToken();
 
+  /** This method is obsolete. Use {@link #getEstimatedLowWatermarkTime()} instead. */
+  @ObsoleteApi("Use getEstimatedLowWatermarkTime() instead")
+  public org.threeten.bp.Instant getEstimatedLowWatermark() {
+    return toThreetenInstant(getEstimatedLowWatermarkTime());
+  }
+
   @InternalApi("Intended for use by the BigtableIO in apache/beam only.")
-  public abstract Instant getEstimatedLowWatermark();
+  public abstract java.time.Instant getEstimatedLowWatermarkTime();
 }

google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/data/v2/models/ReadChangeStreamQuery.java

@@ -15,7 +15,11 @@
  */
 package com.google.cloud.bigtable.data.v2.models;
 
+import static com.google.api.gax.util.TimeConversionUtils.toJavaTimeDuration;
+import static com.google.api.gax.util.TimeConversionUtils.toJavaTimeInstant;
+
 import com.google.api.core.InternalApi;
+import com.google.api.core.ObsoleteApi;
 import com.google.bigtable.v2.ReadChangeStreamRequest;
 import com.google.bigtable.v2.RowRange;
 import com.google.bigtable.v2.StreamContinuationTokens;
@@ -36,7 +40,6 @@
 import java.util.List;
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
-import org.threeten.bp.Instant;
 
 /** A simple wrapper to construct a query for the ReadChangeStream RPC. */
 @InternalApi("Intended for use by the BigtableIO in apache/beam only.")
@@ -143,8 +146,14 @@ public ReadChangeStreamQuery streamPartition(ByteStringRange range) {
     return streamPartition(rangeBuilder.build());
   }
 
+  /** This method is obsolete. Use {@link #startTime(java.time.Instant)} instead. */
+  @ObsoleteApi("Use startTime(java.time.Instant) instead")
+  public ReadChangeStreamQuery startTime(org.threeten.bp.Instant value) {
+    return startTime(toJavaTimeInstant(value));
+  }
+
   /** Sets the startTime to read the change stream. */
-  public ReadChangeStreamQuery startTime(Instant value) {
+  public ReadChangeStreamQuery startTime(java.time.Instant value) {
     Preconditions.checkState(
         !builder.hasContinuationTokens(),
         "startTime and continuationTokens can't be specified together");
@@ -156,8 +165,14 @@ public ReadChangeStreamQuery startTime(Instant value) {
     return this;
   }
 
+  /** This method is obsolete. Use {@link #endTime(java.time.Instant)} instead. */
+  @ObsoleteApi("Use endTime(java.time.Instant) instead")
+  public ReadChangeStreamQuery endTime(org.threeten.bp.Instant value) {
+    return endTime(toJavaTimeInstant(value));
+  }
+
   /** Sets the endTime to read the change stream. */
-  public ReadChangeStreamQuery endTime(Instant value) {
+  public ReadChangeStreamQuery endTime(java.time.Instant value) {
     builder.setEndTime(
         Timestamp.newBuilder()
             .setSeconds(value.getEpochSecond())
@@ -181,8 +196,14 @@ public ReadChangeStreamQuery continuationTokens(
     return this;
   }
 
-  /** Sets the heartbeat duration for the change stream. */
+  /** This method is obsolete. Use {@link #heartbeatDuration(java.time.Duration)} instead. */
+  @ObsoleteApi("Use heartbeatDuration(java.time.Duration) instead")
   public ReadChangeStreamQuery heartbeatDuration(org.threeten.bp.Duration duration) {
+    return heartbeatDuration(toJavaTimeDuration(duration));
+  }
+
+  /** Sets the heartbeat duration for the change stream. */
+  public ReadChangeStreamQuery heartbeatDuration(java.time.Duration duration) {
     builder.setHeartbeatDuration(
         Duration.newBuilder()
             .setSeconds(duration.getSeconds())