Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: Introduce java.time to Gax-Java (#1872)
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 `interface`s, 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: https://github.com/googleapis/sdk-platform-java/blob/667f2da15d0800d87d0866e36627ac23955c0b01/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java#L78-L89 and https://github.com/googleapis/sdk-platform-java/blob/a99d3c1acd4b25a28bd571c8c6f7f7f5d74e1365/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java#L243-L262 ### Internal variables `Duration` or `Instant` private variables are switched to `java.time`. In this case, the wrappers are of `threeten` clasess. For example https://github.com/googleapis/sdk-platform-java/blob/667f2da15d0800d87d0866e36627ac23955c0b01/gax-java/gax-httpjson/src/main/java/com/google/api/gax/httpjson/HttpJsonCallContext.java#L237-L247 ## Deprecation warning `threeten` methods will now have an `@ObsoleteApi` annotation. For example: https://github.com/googleapis/sdk-platform-java/blob/667f2da15d0800d87d0866e36627ac23955c0b01/gax-java/gax/src/main/java/com/google/api/gax/batching/BatchingSettings.java#L106 ## 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. --------- Co-authored-by: Blake Li <[email protected]> Co-authored-by: Mike Eltsufin <[email protected]> Co-authored-by: Lawrence Qiu <[email protected]>
- Loading branch information