ref(time): Deprecate the legacy date and clock providers (JAVA-571)

CHANGELOG.md

@@ -18,12 +18,17 @@
 - Gradle builds now resolve all Sentry SDK modules to the same version, the highest one present, because every module depends on `sentry-bom` as a platform ([#6466](https://github.com/getsentry/sentry-java/pull/6466))
   - Before, a build could mix module versions, for example a newer `sentry-android-core` with an older `sentry-android-fragment`, which failed at runtime. Maven builds resolve as before.
   - `sentry-bom` now also includes `sentry-android-distribution`.
+- Deprecate `DateUtils.getCurrentDateTime()` in favor of `options.getDateProvider().now()`, which is configurable and resolves finer than a millisecond ([#6043](https://github.com/getsentry/sentry-java/pull/6043))
 
 ### Fixes
 
 - Session Replay: Fix `SentryOkHttpInterceptor` hanging forever on responses whose body has no known length, such as Server-Sent Events or a gzipped response, when network details are enabled for the URL ([#6231](https://github.com/getsentry/sentry-java/pull/6231))
 - Stop marking an OkHttp call span as failed when a connection attempt to one of the host's addresses fails but OkHttp connects on another ([#6472](https://github.com/getsentry/sentry-java/pull/6472))
 
+### Internal
+
+- Deprecate `ICurrentDateProvider.getCurrentTimeMillis()`, `CurrentDateProvider.getInstance()` and `AndroidDateUtils.getCurrentSentryDateTime()` in favor of `MonotonicTicker` and `SentryDateProvider` ([#6043](https://github.com/getsentry/sentry-java/pull/6043))
+
 ### Dependencies
 
 - Bump OkHttp from 4.9.2 to 5.5.1 ([#6472](https://github.com/getsentry/sentry-java/pull/6472))

sentry-android-core/src/main/java/io/sentry/android/core/ANRWatchDog.java

@@ -123,6 +123,7 @@ final class ANRWatchDog extends Thread {
     }
   }
 
+  @SuppressWarnings("deprecation")
   @Override
   public void run() {
     // right when the watchdog gets started, let's assume there's no ANR

sentry-android-core/src/main/java/io/sentry/android/core/ActivityLifecycleIntegration.java

@@ -549,6 +549,9 @@ private void finishTransaction(
     }
   }
 
+  // TODO [MAJOR]: replace AndroidDateUtils.getCurrentSentryDateTime() with
+  // options.getDateProvider().now()
+  @SuppressWarnings("deprecation")
   @Override
   public void onActivityPreCreated(
       final @NotNull Activity activity, final @Nullable Bundle savedInstanceState) {
@@ -604,6 +607,9 @@ public void onActivityPostCreated(
     }
   }
 
+  // TODO [MAJOR]: replace AndroidDateUtils.getCurrentSentryDateTime() with
+  // options.getDateProvider().now()
+  @SuppressWarnings("deprecation")
   @Override
   public void onActivityPreStarted(final @NotNull Activity activity) {
     final ActivityLifecycleSpanHelper helper = activitySpanHelpers.get(activity);
@@ -672,6 +678,9 @@ public void onActivityPostResumed(@NotNull Activity activity) {
     // empty override, required to avoid a api-level breaking super.onActivityPostResumed() calls
   }
 
+  // TODO [MAJOR]: replace AndroidDateUtils.getCurrentSentryDateTime() with
+  // options.getDateProvider().now()
+  @SuppressWarnings("deprecation")
   @Override
   public void onActivityPrePaused(@NotNull Activity activity) {
     // only executed if API >= 29 otherwise it happens on onActivityPaused
@@ -1094,6 +1103,9 @@ private void onHeadlessAppStart() {
    * Standalone-only: this is only registered as a listener when standalone app start tracing is
    * enabled.
    */
+  // TODO [MAJOR]: replace AndroidDateUtils.getCurrentSentryDateTime() with
+  // options.getDateProvider().now()
+  @SuppressWarnings("deprecation")
   private @Nullable AppStartExtension.ExtendedAppStart onExtendAppStartRequested() {
     if (scopes == null
         || options == null

sentry-android-core/src/main/java/io/sentry/android/core/AndroidDateUtils.java

@@ -17,7 +17,10 @@ public final class AndroidDateUtils {
    * invocations.
    *
    * @return the UTC SentryDate
+   * @deprecated use {@code options.getDateProvider()}. This static holder cannot be configured or
+   *     stubbed, which is why the note above already asked callers to prefer the options.
    */
+  @Deprecated
   public static @NotNull SentryDate getCurrentSentryDateTime() {
     return dateProvider.now();
   }

sentry-android-core/src/main/java/io/sentry/android/core/AndroidOptionsInitializer.java

@@ -412,6 +412,9 @@ private static void setupProfiler(
     }
   }
 
+  // TODO [MAJOR]: replace CurrentDateProvider (wall clock) with SentryDateProvider or
+  // MonotonicTicker
+  @SuppressWarnings("deprecation")
   static void installDefaultIntegrations(
       final @NotNull Context context,
       final @NotNull SentryAndroidOptions options,

sentry-android-core/src/main/java/io/sentry/android/core/AndroidProfiler.java

@@ -117,6 +117,8 @@ public AndroidProfiler(
   }
 
   @SuppressLint("NewApi")
+  // TODO [MAJOR]: replace DateUtils.getCurrentDateTime() with options.getDateProvider().now()
+  @SuppressWarnings("deprecation")
   public @Nullable ProfileStartData start() {
     try (final @NotNull ISentryLifecycleToken ignored = lock.acquire()) {
       // intervalUs is 0 only if there was a problem in the init

sentry-android-core/src/main/java/io/sentry/android/core/AndroidTransactionProfiler.java

@@ -89,6 +89,8 @@ public AndroidTransactionProfiler(
         () -> executorService);
   }
 
+  // TODO [MAJOR]: replace DateUtils.getCurrentDateTime() with options.getDateProvider().now()
+  @SuppressWarnings("deprecation")
   public AndroidTransactionProfiler(
       final @NotNull Context context,
       final @NotNull BuildInfoProvider buildInfoProvider,

sentry-android-core/src/main/java/io/sentry/android/core/AnrV2Integration.java

@@ -50,6 +50,9 @@ public class AnrV2Integration implements Integration, Closeable {
   private final @NotNull ICurrentDateProvider dateProvider;
   private @Nullable SentryAndroidOptions options;
 
+  // TODO [MAJOR]: replace CurrentDateProvider (wall clock) with SentryDateProvider; the epoch
+  // comparison it feeds must stay wall time
+  @SuppressWarnings("deprecation")
   public AnrV2Integration(final @NotNull Context context) {
     // using CurrentDateProvider instead of AndroidCurrentDateProvider as AppExitInfo uses
     // System.currentTimeMillis

sentry-android-core/src/main/java/io/sentry/android/core/ApplicationExitInfoHistoryDispatcher.java

@@ -53,6 +53,9 @@ final class ApplicationExitInfoHistoryDispatcher implements Runnable {
   private final @NotNull ApplicationExitInfoPolicy policy;
   private final long threshold;
 
+  // TODO [MAJOR]: replace CurrentDateProvider (wall clock) with SentryDateProvider; the epoch
+  // comparison it feeds must stay wall time
+  @SuppressWarnings("deprecation")
   ApplicationExitInfoHistoryDispatcher(
       final @NotNull Context context,
       final @NotNull IScopes scopes,

sentry-android-core/src/main/java/io/sentry/android/core/LifecycleWatcher.java

@@ -28,6 +28,9 @@ final class LifecycleWatcher implements AppState.AppStateListener {
 
   private final @NotNull ICurrentDateProvider currentDateProvider;
 
+  // TODO [MAJOR]: replace CurrentDateProvider (wall clock) with SentryDateProvider; the epoch
+  // comparison it feeds must stay wall time
+  @SuppressWarnings("deprecation")
   LifecycleWatcher(
       final @NotNull IScopes scopes,
       final long sessionIntervalMillis,
@@ -60,6 +63,9 @@ public void onForeground() {
     addAppBreadcrumb("foreground");
   }
 
+  // TODO [MAJOR]: replace CurrentDateProvider (wall clock) with SentryDateProvider; the epoch
+  // comparison it feeds must stay wall time
+  @SuppressWarnings("deprecation")
   private void startSession() {
     cancelTask();
 
@@ -90,6 +96,9 @@ private void startSession() {
 
   // App went to background and triggered this callback after 700ms
   // as no new screen was shown
+  // TODO [MAJOR]: replace CurrentDateProvider (wall clock) with SentryDateProvider; the epoch
+  // comparison it feeds must stay wall time
+  @SuppressWarnings("deprecation")
   @Override
   public void onBackground() {
     final long currentTimeMillis = currentDateProvider.getCurrentTimeMillis();

sentry-android-core/src/main/java/io/sentry/android/core/MemoryLimiterIntegration.java

@@ -89,6 +89,9 @@ public final class MemoryLimiterIntegration implements Integration, Closeable {
   private final @NotNull BuildInfoProvider buildInfoProvider;
   private @Nullable SentryAndroidOptions androidOptions;
 
+  // TODO [MAJOR]: replace CurrentDateProvider (wall clock) with SentryDateProvider; the epoch
+  // comparison it feeds must stay wall time
+  @SuppressWarnings("deprecation")
   public MemoryLimiterIntegration(
       final @NotNull Context context, final @NotNull BuildInfoProvider buildInfoProvider) {
     // Use CurrentDateProvider instead of AndroidCurrentDateProvider as ApplicationExitInfo uses

sentry-android-core/src/main/java/io/sentry/android/core/TombstoneIntegration.java

@@ -54,6 +54,9 @@ public class TombstoneIntegration implements Integration, Closeable {
   private final @NotNull ICurrentDateProvider dateProvider;
   private @Nullable SentryAndroidOptions options;
 
+  // TODO [MAJOR]: replace CurrentDateProvider (wall clock) with SentryDateProvider; the epoch
+  // comparison it feeds must stay wall time
+  @SuppressWarnings("deprecation")
   public TombstoneIntegration(final @NotNull Context context) {
     // using CurrentDateProvider instead of AndroidCurrentDateProvider as AppExitInfo uses
     // System.currentTimeMillis

sentry-android-core/src/main/java/io/sentry/android/core/cache/AndroidEnvelopeCache.java

@@ -67,6 +67,9 @@ public boolean storeEnvelope(@NotNull SentryEnvelope envelope, @NotNull Hint hin
     return storeInternalAndroid(envelope, hint);
   }
 
+  // TODO [MAJOR]: this reading must stay paired with AppStartMetrics.getStartUptimeMs(),
+  // which is SystemClock.uptimeMillis(), so MonotonicTicker is not a drop-in replacement
+  @SuppressWarnings("deprecation")
   private boolean storeInternalAndroid(@NotNull SentryEnvelope envelope, @NotNull Hint hint) {
     final boolean didStore = super.storeEnvelope(envelope, hint);
 

sentry-android-core/src/main/java/io/sentry/android/core/internal/util/AndroidCurrentDateProvider.java

@@ -19,6 +19,7 @@
 @ApiStatus.Internal
 public final class AndroidCurrentDateProvider implements ICurrentDateProvider {
 
+  @SuppressWarnings("deprecation")
   private static final ICurrentDateProvider instance = new AndroidCurrentDateProvider();
 
   /**
@@ -32,6 +33,7 @@ public static ICurrentDateProvider getInstance() {
   private AndroidCurrentDateProvider() {}
 
   @Override
+  @SuppressWarnings("deprecation")
   public long getCurrentTimeMillis() {
     return SystemClock.uptimeMillis();
   }

sentry-android-core/src/main/java/io/sentry/android/core/internal/util/Debouncer.java

@@ -30,6 +30,8 @@ public Debouncer(
    * @return true if the execution should be debounced due to maxExecutions executions being made
    *     within waitTimeMs, otherwise false.
    */
+  // TODO [MAJOR]: replace AndroidCurrentDateProvider with MonotonicTicker
+  @SuppressWarnings("deprecation")
   public boolean checkForDebounce() {
     final long now = timeProvider.getCurrentTimeMillis();
     if (lastExecutionTime.get() == 0 || (lastExecutionTime.get() + waitTimeMs) <= now) {

sentry-android-core/src/main/java/io/sentry/android/core/performance/ActivityLifecycleSpanHelper.java

@@ -69,6 +69,9 @@ public void createAndStopOnStartSpan(final @Nullable ISpan parentSpan) {
     return onStartStartTimestamp;
   }
 
+  // TODO [MAJOR]: replace AndroidDateUtils.getCurrentSentryDateTime() with
+  // options.getDateProvider().now()
+  @SuppressWarnings("deprecation")
   public void saveSpanToAppStartMetrics() {
     if (onCreateSpan == null || onStartSpan == null) {
       return;

sentry/src/main/java/io/sentry/Breadcrumb.java

@@ -99,7 +99,8 @@ public Breadcrumb(final long timestamp) {
    * @param options - the sentry options
    * @return the breadcrumb
    */
-  @SuppressWarnings("unchecked")
+  // TODO [MAJOR]: replace DateUtils.getCurrentDateTime() with options.getDateProvider().now()
+  @SuppressWarnings({"unchecked", "deprecation"})
   public static Breadcrumb fromMap(
       @NotNull Map<String, Object> map, @NotNull SentryOptions options) {
 
@@ -915,7 +916,8 @@ public void serialize(final @NotNull ObjectWriter writer, final @NotNull ILogger
   }
 
   public static final class Deserializer implements JsonDeserializer<Breadcrumb> {
-    @SuppressWarnings("unchecked")
+    // TODO [MAJOR]: replace DateUtils.getCurrentDateTime() with options.getDateProvider().now()
+    @SuppressWarnings({"unchecked", "deprecation"})
     @Override
     public @NotNull Breadcrumb deserialize(@NotNull ObjectReader reader, @NotNull ILogger logger)
         throws Exception {

sentry/src/main/java/io/sentry/DateUtils.java

@@ -19,8 +19,12 @@ private DateUtils() {}
    * Get the current Date (UTC)
    *
    * @return the UTC Date
+   * @deprecated use {@code options.getDateProvider().now()}, which is configurable and resolves
+   *     finer than a millisecond.
    */
-  @SuppressWarnings("JavaUtilDate")
+  @Deprecated
+  // not @InlineMe: the replacement is options.getDateProvider().now(), not this method's body
+  @SuppressWarnings({"JavaUtilDate", "InlineMeSuggester"})
   public static @NotNull Date getCurrentDateTime() {
     return new Date();
   }

sentry/src/main/java/io/sentry/ProfilingTraceData.java

@@ -75,6 +75,8 @@ private ProfilingTraceData() {
     this(new File("dummy"), NoOpTransaction.getInstance());
   }
 
+  // TODO [MAJOR]: replace DateUtils.getCurrentDateTime() with options.getDateProvider().now()
+  @SuppressWarnings("deprecation")
   public ProfilingTraceData(
       final @NotNull File traceFile, final @NotNull ITransaction transaction) {
     this(

sentry/src/main/java/io/sentry/SentryEvent.java

@@ -103,6 +103,8 @@ public SentryEvent(final @Nullable Throwable throwable) {
     this.throwable = throwable;
   }
 
+  // TODO [MAJOR]: replace DateUtils.getCurrentDateTime() with options.getDateProvider().now()
+  @SuppressWarnings("deprecation")
   public SentryEvent() {
     this(new SentryId(), DateUtils.getCurrentDateTime());
   }

sentry/src/main/java/io/sentry/SentryReplayEvent.java

@@ -52,6 +52,8 @@ public static final class Deserializer implements JsonDeserializer<ReplayType> {
   private @Nullable List<String> segmentNames;
   private @Nullable Map<String, Object> unknown;
 
+  // TODO [MAJOR]: replace DateUtils.getCurrentDateTime() with options.getDateProvider().now()
+  @SuppressWarnings("deprecation")
   public SentryReplayEvent() {
     super();
     this.replayId = new SentryId();

sentry/src/main/java/io/sentry/Session.java

@@ -112,6 +112,8 @@ public Session(
     this.abnormalMechanism = abnormalMechanism;
   }
 
+  // TODO [MAJOR]: replace DateUtils.getCurrentDateTime() with options.getDateProvider().now()
+  @SuppressWarnings("deprecation")
   public Session(
       @Nullable String distinctId,
       final @Nullable User user,
@@ -221,6 +223,8 @@ public boolean hasNonTerminatingUnhandledError() {
    *
    * @return whether the session was updated, i.e. false if it had already reached a terminal state
    */
+  // TODO [MAJOR]: replace DateUtils.getCurrentDateTime() with options.getDateProvider().now()
+  @SuppressWarnings("deprecation")
   @ApiStatus.Internal
   public boolean recordNonTerminatingUnhandledError() {
     try (final @NotNull ISentryLifecycleToken ignored = sessionLock.acquire()) {
@@ -242,6 +246,8 @@ public boolean recordNonTerminatingUnhandledError() {
   }
 
   /** Ends a session and update its values */
+  // TODO [MAJOR]: replace DateUtils.getCurrentDateTime() with options.getDateProvider().now()
+  @SuppressWarnings("deprecation")
   public void end() {
     end(DateUtils.getCurrentDateTime());
   }
@@ -251,6 +257,8 @@ public void end() {
    *
    * @param timestamp the timestamp or null
    */
+  // TODO [MAJOR]: replace DateUtils.getCurrentDateTime() with options.getDateProvider().now()
+  @SuppressWarnings("deprecation")
   public void end(final @Nullable Date timestamp) {
     try (final @NotNull ISentryLifecycleToken ignored = sessionLock.acquire()) {
       init = null;
@@ -301,6 +309,8 @@ public boolean update(
    * @param abnormalMechanism the mechanism which caused the session to be abnormal
    * @return if the session has been updated
    */
+  // TODO [MAJOR]: replace DateUtils.getCurrentDateTime() with options.getDateProvider().now()
+  @SuppressWarnings("deprecation")
   public boolean update(
       final @Nullable State status,
       final @Nullable String userAgent,

sentry/src/main/java/io/sentry/cache/EnvelopeCache.java

@@ -279,6 +279,8 @@ private void tryEndPreviousSession(final @NotNull Hint hint) {
     }
   }
 
+  // TODO [MAJOR]: replace DateUtils.getCurrentDateTime() with options.getDateProvider().now()
+  @SuppressWarnings("deprecation")
   private void writeCrashMarkerFile() {
     final File crashMarkerFile = new File(options.getCacheDirPath(), CRASH_MARKER_FILE);
     try (final OutputStream outputStream = new FileOutputStream(crashMarkerFile)) {

sentry/src/main/java/io/sentry/clientreport/ClientReportRecorder.java

@@ -170,6 +170,8 @@ private long itemCountFromHeader(final @NotNull SentryEnvelopeItem envelopeItem)
     return itemCount != null ? itemCount : 1L;
   }
 
+  // TODO [MAJOR]: replace DateUtils.getCurrentDateTime() with options.getDateProvider().now()
+  @SuppressWarnings("deprecation")
   @Nullable
   ClientReport resetCountsAndGenerateClientReport() {
     final Date currentDate = DateUtils.getCurrentDateTime();

sentry/src/main/java/io/sentry/transport/CurrentDateProvider.java

@@ -2,18 +2,32 @@
 
 import org.jetbrains.annotations.ApiStatus;
 
+/**
+ * The wall clock, which jumps when the device time changes.
+ *
+ * <p>Superseded by {@link io.sentry.SentryDateProvider} for timestamps and {@link
+ * io.sentry.time.MonotonicTicker} for intervals.
+ */
 @ApiStatus.Internal
 public final class CurrentDateProvider implements ICurrentDateProvider {
 
+  @SuppressWarnings("deprecation")
   private static final ICurrentDateProvider instance = new CurrentDateProvider();
 
+  /**
+   * @deprecated use {@link io.sentry.SentryDateProvider} for a timestamp, or {@link
+   *     io.sentry.time.MonotonicTicker} to measure an interval.
+   */
+  @Deprecated
+  @SuppressWarnings("deprecation")
   public static ICurrentDateProvider getInstance() {
     return instance;
   }
 
   private CurrentDateProvider() {}
 
   @Override
+  @SuppressWarnings("deprecation")
   public final long getCurrentTimeMillis() {
     return System.currentTimeMillis();
   }