feat: Introduce java.time to Gax-Java

[diegomarquezp]

This introduces the use of java.time in replacement of org.threeten backport classes.

Message to library users (release note)

We have made the following backwards-compatible changes in this library:

• We have changed the method return type and argument type in internal classes from org.threeten.bp to java.time. This has no effect in the API surface.
• We have added java.time versions for each of the abstract methods involving org.threeten.bp. The affected classes are BatchingSettings, RetrySettings, TimedAttemptSettings and ClientContext, all of which are AutoValue classes, not meant to be extended by our users.
• All getters and setters using org.threeten.bp will be marked final because we will force their behavior to be the same one as the java.time counterpart, which has the actual implementation. The affected classes are BatchingSettings, RetrySettings, TimedAttemptSettings and ClientContext, all of which are AutoValue classes, not meant to be extended by our users.
• In three interfaces, we have added java.time versions for each of the methods involving org.threeten.bp. The affected interfaces are WatchdogProvider (public interface), ApiTracer (internal) and ApiCallContext (internal). The new method in WatchdogProvider has a default behavior, which is to call the threeten counterpart, in order to make this a backwards-compatible change.

Implementation

It preserves method signatures using threeten. The cases are:

@AutoValue clases and classes with public interface involving time objects

Autovalues will have an internal threeten variable with a convenience java.time wrapper method. For example:

sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java

Lines 78 to 89 in 667f2da

	/** Backport of {@link #getTotalTimeoutDuration()} */
	@ObsoleteApi("Use getTotalTimeoutDuration() instead")
	public abstract org.threeten.bp.Duration getTotalTimeout();
	/**
	* TotalTimeout has ultimate control over how long the logic should keep trying the remote call
	* until it gives up completely. The higher the total timeout, the more retries can be attempted.
	* The default value is {@code Duration.ZERO}.
	*/
	public final java.time.Duration getTotalTimeoutDuration() {
	return toJavaTimeDuration(getTotalTimeout());
	}

and

sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java

Lines 243 to 262 in a99d3c1

	/** Backport of {@link #setTotalTimeoutDuration(java.time.Duration)} */
	@ObsoleteApi("Use setTotalTimeoutDuration(java.time.Duration) instead")
	public abstract Builder setTotalTimeout(org.threeten.bp.Duration totalTimeout);
	/**
	* TotalTimeout has ultimate control over how long the logic should keep trying the remote call
	* until it gives up completely. The higher the total timeout, the more retries and polls can be
	* attempted. If this value is {@code Duration.ZERO}, then the logic will instead use the number
	* of attempts to determine retries. In the event that both maxAttempts and totalTimeout values
	* are both 0, the logic will not retry. If this value is non-{@code Duration.ZERO}, and the
	* retry duration has reaches the timeout value, the logic will give up retrying even the number
	* of attempts is lower than the maxAttempts value.
	*
	* <p>If there are no configurations, Retries have the default timeout value of {@code
	* Duration.ZERO} and LROs have a default total timeout value of {@code
	* Duration.ofMillis(300000)} (5 minutes).
	*/
	public final Builder setTotalTimeoutDuration(java.time.Duration totalTimeout) {
	return setTotalTimeout(toThreetenDuration(totalTimeout));
	}

Internal variables

Duration or Instant private variables are switched to java.time. In this case, the wrappers are of threeten clasess. For example

sdk-platform-java/gax-java/gax-httpjson/src/main/java/com/google/api/gax/httpjson/HttpJsonCallContext.java

Lines 237 to 247 in 667f2da

	/** Overload of {@link #withTimeout(java.time.Duration)} using {@link org.threeten.bp.Duration} */
	@Override
	@ObsoleteApi("Use withTimeout(java.time.Duration) instead")
	public HttpJsonCallContext withTimeout(org.threeten.bp.Duration timeout) {
	return withTimeout(toJavaTimeDuration(timeout));
	}
	@Override
	public HttpJsonCallContext withTimeout(java.time.Duration timeout) {
	// Default RetrySettings use 0 for RPC timeout. Treat that as disabled timeouts.
	if (timeout != null && (timeout.isZero() || timeout.isNegative())) {

Deprecation warning

threeten methods will now have an @ObsoleteApi annotation. For example:

sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/batching/BatchingSettings.java

Line 106 in 667f2da

@ObsoleteApi("Use getDelayThresholdDuration() instead")

CLIRR checks

gax-java/gax

[ERROR] 7013: com.google.api.gax.batching.BatchingSettings: Abstract method 'public java.time.Duration getDelayThresholdDuration()' has been added
[ERROR] 7014: com.google.api.gax.batching.BatchingSettings$Builder: Method 'public com.google.api.gax.batching.BatchingSettings$Builder setDelayThreshold(org.threeten.bp.Duration)' is now final
[ERROR] 7013: com.google.api.gax.batching.BatchingSettings$Builder: Abstract method 'public com.google.api.gax.batching.BatchingSettings$Builder setDelayThresholdDuration(java.time.Duration)' has been added
[ERROR] 7005: com.google.api.gax.retrying.DirectRetryingExecutor: Parameter 1 of 'protected void sleep(org.threeten.bp.Duration)' has changed its type to java.time.Duration
[ERROR] 7013: com.google.api.gax.retrying.RetrySettings: Abstract method 'public java.time.Duration getInitialRetryDelayDuration()' has been added
[ERROR] 7014: com.google.api.gax.retrying.RetrySettings: Method 'public org.threeten.bp.Duration getInitialRpcTimeout()' is now final
[ERROR] 7013: com.google.api.gax.retrying.RetrySettings: Abstract method 'public java.time.Duration getInitialRpcTimeoutDuration()' has been added
[ERROR] 7013: com.google.api.gax.retrying.RetrySettings: Abstract method 'public java.time.Duration getMaxRetryDelayDuration()' has been added
[ERROR] 7014: com.google.api.gax.retrying.RetrySettings: Method 'public org.threeten.bp.Duration getMaxRpcTimeout()' is now final
[ERROR] 7013: com.google.api.gax.retrying.RetrySettings: Abstract method 'public java.time.Duration getMaxRpcTimeoutDuration()' has been added
[ERROR] 7013: com.google.api.gax.retrying.RetrySettings: Abstract method 'public java.time.Duration getTotalTimeoutDuration()' has been added
[ERROR] 7014: com.google.api.gax.retrying.RetrySettings$Builder: Method 'public org.threeten.bp.Duration getInitialRetryDelay()' is now final
[ERROR] 7013: com.google.api.gax.retrying.RetrySettings$Builder: Abstract method 'public java.time.Duration getInitialRetryDelayDuration()' has been added
[ERROR] 7014: com.google.api.gax.retrying.RetrySettings$Builder: Method 'public org.threeten.bp.Duration getInitialRpcTimeout()' is now final
[ERROR] 7013: com.google.api.gax.retrying.RetrySettings$Builder: Abstract method 'public java.time.Duration getInitialRpcTimeoutDuration()' has been added
[ERROR] 7014: com.google.api.gax.retrying.RetrySettings$Builder: Method 'public org.threeten.bp.Duration getMaxRetryDelay()' is now final
[ERROR] 7013: com.google.api.gax.retrying.RetrySettings$Builder: Abstract method 'public java.time.Duration getMaxRetryDelayDuration()' has been added
[ERROR] 7014: com.google.api.gax.retrying.RetrySettings$Builder: Method 'public org.threeten.bp.Duration getMaxRpcTimeout()' is now final
[ERROR] 7013: com.google.api.gax.retrying.RetrySettings$Builder: Abstract method 'public java.time.Duration getMaxRpcTimeoutDuration()' has been added
[ERROR] 7014: com.google.api.gax.retrying.RetrySettings$Builder: Method 'public org.threeten.bp.Duration getTotalTimeout()' is now final
[ERROR] 7013: com.google.api.gax.retrying.RetrySettings$Builder: Abstract method 'public java.time.Duration getTotalTimeoutDuration()' has been added
[ERROR] 7014: com.google.api.gax.retrying.RetrySettings$Builder: Method 'public com.google.api.gax.retrying.RetrySettings$Builder setInitialRetryDelay(org.threeten.bp.Duration)' is now final
[ERROR] 7013: com.google.api.gax.retrying.RetrySettings$Builder: Abstract method 'public com.google.api.gax.retrying.RetrySettings$Builder setInitialRetryDelayDuration(java.time.Duration)' has been added
[ERROR] 7014: com.google.api.gax.retrying.RetrySettings$Builder: Method 'public com.google.api.gax.retrying.RetrySettings$Builder setInitialRpcTimeout(org.threeten.bp.Duration)' is now final
[ERROR] 7013: com.google.api.gax.retrying.RetrySettings$Builder: Abstract method 'public com.google.api.gax.retrying.RetrySettings$Builder setInitialRpcTimeoutDuration(java.time.Duration)' has been added
[ERROR] 7014: com.google.api.gax.retrying.RetrySettings$Builder: Method 'public com.google.api.gax.retrying.RetrySettings$Builder setMaxRetryDelay(org.threeten.bp.Duration)' is now final
[ERROR] 7013: com.google.api.gax.retrying.RetrySettings$Builder: Abstract method 'public com.google.api.gax.retrying.RetrySettings$Builder setMaxRetryDelayDuration(java.time.Duration)' has been added
[ERROR] 7014: com.google.api.gax.retrying.RetrySettings$Builder: Method 'public com.google.api.gax.retrying.RetrySettings$Builder setMaxRpcTimeout(org.threeten.bp.Duration)' is now final
[ERROR] 7013: com.google.api.gax.retrying.RetrySettings$Builder: Abstract method 'public com.google.api.gax.retrying.RetrySettings$Builder setMaxRpcTimeoutDuration(java.time.Duration)' has been added
[ERROR] 7014: com.google.api.gax.retrying.RetrySettings$Builder: Method 'public com.google.api.gax.retrying.RetrySettings$Builder setTotalTimeout(org.threeten.bp.Duration)' is now final
[ERROR] 7013: com.google.api.gax.retrying.RetrySettings$Builder: Abstract method 'public com.google.api.gax.retrying.RetrySettings$Builder setTotalTimeoutDuration(java.time.Duration)' has been added
[ERROR] 7014: com.google.api.gax.retrying.TimedAttemptSettings: Method 'public org.threeten.bp.Duration getRandomizedRetryDelay()' is now final
[ERROR] 7013: com.google.api.gax.retrying.TimedAttemptSettings: Abstract method 'public java.time.Duration getRandomizedRetryDelayDuration()' has been added
[ERROR] 7014: com.google.api.gax.retrying.TimedAttemptSettings: Method 'public org.threeten.bp.Duration getRetryDelay()' is now final
[ERROR] 7013: com.google.api.gax.retrying.TimedAttemptSettings: Abstract method 'public java.time.Duration getRetryDelayDuration()' has been added
[ERROR] 7014: com.google.api.gax.retrying.TimedAttemptSettings: Method 'public org.threeten.bp.Duration getRpcTimeout()' is now final
[ERROR] 7013: com.google.api.gax.retrying.TimedAttemptSettings: Abstract method 'public java.time.Duration getRpcTimeoutDuration()' has been added
[ERROR] 7014: com.google.api.gax.retrying.TimedAttemptSettings$Builder: Method 'public com.google.api.gax.retrying.TimedAttemptSettings$Builder setRandomizedRetryDelay(org.threeten.bp.Duration)' is now final
[ERROR] 7013: com.google.api.gax.retrying.TimedAttemptSettings$Builder: Abstract method 'public com.google.api.gax.retrying.TimedAttemptSettings$Builder setRandomizedRetryDelayDuration(java.time.Duration)' has been added
[ERROR] 7014: com.google.api.gax.retrying.TimedAttemptSettings$Builder: Method 'public com.google.api.gax.retrying.TimedAttemptSettings$Builder setRetryDelay(org.threeten.bp.Duration)' is now final
[ERROR] 7013: com.google.api.gax.retrying.TimedAttemptSettings$Builder: Abstract method 'public com.google.api.gax.retrying.TimedAttemptSettings$Builder setRetryDelayDuration(java.time.Duration)' has been added
[ERROR] 7014: com.google.api.gax.retrying.TimedAttemptSettings$Builder: Method 'public com.google.api.gax.retrying.TimedAttemptSettings$Builder setRpcTimeout(org.threeten.bp.Duration)' is now final
[ERROR] 7013: com.google.api.gax.retrying.TimedAttemptSettings$Builder: Abstract method 'public com.google.api.gax.retrying.TimedAttemptSettings$Builder setRpcTimeoutDuration(java.time.Duration)' has been added
[ERROR] 7012: com.google.api.gax.rpc.ApiCallContext: Method 'public java.time.Duration getStreamIdleTimeoutDuration()' has been added to an interface
[ERROR] 7012: com.google.api.gax.rpc.ApiCallContext: Method 'public java.time.Duration getStreamWaitTimeoutDuration()' has been added to an interface
[ERROR] 7012: com.google.api.gax.rpc.ApiCallContext: Method 'public java.time.Duration getTimeoutDuration()' has been added to an interface
[ERROR] 7012: com.google.api.gax.rpc.ApiCallContext: Method 'public com.google.api.gax.rpc.ApiCallContext withStreamIdleTimeoutDuration(java.time.Duration)' has been added to an interface
[ERROR] 7012: com.google.api.gax.rpc.ApiCallContext: Method 'public com.google.api.gax.rpc.ApiCallContext withStreamWaitTimeoutDuration(java.time.Duration)' has been added to an interface
[ERROR] 7012: com.google.api.gax.rpc.ApiCallContext: Method 'public com.google.api.gax.rpc.ApiCallContext withTimeoutDuration(java.time.Duration)' has been added to an interface
[ERROR] 7014: com.google.api.gax.rpc.ClientContext: Method 'public org.threeten.bp.Duration getStreamWatchdogCheckInterval()' is now final
[ERROR] 7013: com.google.api.gax.rpc.ClientContext: Abstract method 'public java.time.Duration getStreamWatchdogCheckIntervalDuration()' has been added
[ERROR] 7014: com.google.api.gax.rpc.ClientContext$Builder: Method 'public com.google.api.gax.rpc.ClientContext$Builder setStreamWatchdogCheckInterval(org.threeten.bp.Duration)' is now final
[ERROR] 7013: com.google.api.gax.rpc.ClientContext$Builder: Abstract method 'public com.google.api.gax.rpc.ClientContext$Builder setStreamWatchdogCheckIntervalDuration(java.time.Duration)' has been added
[ERROR] 7012: com.google.api.gax.rpc.WatchdogProvider: Method 'public com.google.api.gax.rpc.WatchdogProvider withCheckIntervalDuration(java.time.Duration)' has been added to an interface
[ERROR] 7012: com.google.api.gax.tracing.ApiTracer: Method 'public void attemptFailedDuration(java.lang.Throwable, java.time.Duration)' has been added to an interface

We have decided to ignore a these CLIRR messages due to the following reasons

• 7005 (method type change): This has only been implemented in internal classes, not exposed to our customers
• 7013 (new abstract method added): We have added several java.time versions for each of the methods involving org.threeten.bp. This affects AutoValue classes only.
• 7014 (convert to final): All getters and setters using org.threeten.bp will be marked final because we will force their behavior to be the same one as the java.time counterpart, which has the actual implementation. This affects AutoValue classes only.
• 7012 (new method in interface): We have added several java.time versions for each of the methods involving org.threeten.bp. For the only public interface WatchdogProvider, we added a default behavior.

[sonarqubecloud]

Quality Gate failed for 'gapic-generator-java-root'

Failed conditions
B Reliability Rating on New Code (required ≥ A)

See analysis details on SonarCloud

Catch issues before they fail your Quality Gate with our IDE extension SonarLint

[sonarqubecloud]

Quality Gate failed for 'java_showcase_integration_tests'

Failed conditions
49.8% Coverage on New Code (required ≥ 80%)
B Reliability Rating on New Code (required ≥ A)

See analysis details on SonarCloud

Catch issues before they fail your Quality Gate with our IDE extension SonarLint

[diegomarquezp]

The java-spanner downstream check is failing because a new method attemptFailedDuration was added to BaseApiTracer.

Error:  Failures: 
Error:    CompositeTracerTest.testMethodsOverrideMetricsTracer:238 Method not found in compositeTracerMethods: public void com.google.api.gax.tracing.MetricsTracer.attemptFailedDuration(java.lang.Throwable,java.time.Duration)

The test CompositeTracerTest.testMethodsOverrideMetricsTracer verifies that the class CompositeTracer has an overridden declaration of each method of BaseApiTracer, which is not true as of July 4th.

cc: @rahul2393

[kluever]

FWIW, this truncates sub-millisecond precision. I think what you probably want to do is instead:

return java.time.Instant.ofEpochSecond(source.getEpochSecond(), source.getNano());

Ditto on the other methods in this file (including converting via nanoseconds for the Duration method --- that will overflow for values > 292 years --- instead, use Duration.ofSeconds(duration.getSeconds(), duration.getNano());

[lqiu96]

CC: @diegomarquezp Can you take a look at this?

[diegomarquezp]

I confirmed this causes trouble:

  @Test
  void testToThreeteenTimeInstant_bigInput_doesNotTruncate() {
    java.time.Instant jtInstant = java.time.Instant.MAX;
    org.threeten.bp.Instant ttInstant = TimeConversionUtils.toThreetenInstant(jtInstant);
    assertEquals(jtInstant.toEpochMilli(), ttInstant.toEpochMilli());
  }

It did not truncate, though. It failed with an overflow exception:

java.lang.ArithmeticException: long overflow

	at java.base/java.lang.Math.multiplyExact(Math.java:1033)
	at java.base/java.lang.Math.multiplyExact(Math.java:1009)
	at java.base/java.time.Instant.toEpochMilli(Instant.java:1262)
	at com.google.api.gax.util.TimeConversionUtils.toThreetenInstant(TimeConversionUtils.java:59)

I'll leave this test as a standard for a coming PR.