ref(android): Deprecate AndroidCurrentDateProvider (JAVA-728) (#6103)

* ref(android): Deprecate AndroidCurrentDateProvider (JAVA-728)

AndroidCurrentDateProvider.getCurrentTimeMillis() is
SystemClock.uptimeMillis(): not a date, and not a clock that counts deep
sleep. Neither the name nor the ICurrentDateProvider type says so, and
CurrentDateProvider implements that same interface with epoch
milliseconds, so a call site declaring the interface accepts either and
the two disagree by however long the device has been suspended.
MonotonicTicker names the guarantee it gives and keeps counting through
deep sleep.

The annotation goes on getInstance() rather than on the type. The
Android modules compile at Java 8, where javac still warns on an import
of a deprecated type, and an import declaration cannot carry a
@SuppressWarnings. Deprecating the sole factory method warns every
caller just the same, and each warning lands somewhere a suppression can
go.

Nothing is migrated and nothing is removed. The five suppressed call
sites are the migration list. AndroidEnvelopeCache cannot move on its
own: it subtracts TimeSpan.getStartUptimeMs(), which is
SystemClock.uptimeMillis() too, so moving one operand alone would
subtract two different clock bases.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* changelog

* ref(android): Deprecate the whole AndroidCurrentDateProvider type (JAVA-728)

Deprecating the type rather than getInstance() says the hazard is the
class itself, and warns on every mention of it, the import included.

That is only affordable because this class has five use sites. An import
of a deprecated type still warns at Java 8 (JEP 211 elides those only
from source 9 on), -Werror turns it into an error, and an import
declaration cannot carry a @SuppressWarnings. Dropping the five imports
for fully-qualified names puts every reference inside a declaration that
a suppression can cover. Verified by re-adding one import: the build
fails with "warning: [deprecation] AndroidCurrentDateProvider in
io.sentry.android.core.internal.util has been deprecated".

The suppression comments now point at JAVA-729, which tracks migrating
the call sites, rather than restating the reasoning at each one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* changelog

* ref(android): Move the deprecation back onto getInstance() (JAVA-728)

Deprecating the type required replacing all five imports with fully
qualified names, since an import of a deprecated type warns at Java 8
and an import cannot carry a @SuppressWarnings. That churn bought
nothing. The constructor is private, so getInstance() is the only way
into this class and deprecating it warns every real caller identically.
Type-level deprecation would only add a warning for declaring a variable
of the concrete type, which nothing does: every holder declares
ICurrentDateProvider.

Measured the alternatives before reverting. Neither a class-level
@SuppressWarnings nor a static import silences the import warning; only
a fully qualified name, or a reference from inside the type's own
package, avoids it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* changelog

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: runningcode

CHANGELOG.md

@@ -34,6 +34,10 @@
 - Sentry can now configure Log4j2 automatically for Spring Boot 3 when `sentry-log4j2` is on the classpath and Log4j2 Core is the active logging backend ([#6072](https://github.com/getsentry/sentry-java/pull/6072))
   - Disabled by default for now; enable it and configure levels the same way as described in the Spring Boot 4 entry above (`sentry.logging.enabled=true`)
 
+### Internal
+
+- Deprecate `AndroidCurrentDateProvider.getInstance()` in favor of `MonotonicTicker`, which counts time spent in deep sleep and cannot be confused with the epoch-based `CurrentDateProvider` ([#6103](https://github.com/getsentry/sentry-java/pull/6103))
+
 ## 8.56.0
 
 ### Behavioral Changes

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

@@ -34,6 +34,8 @@ public final class AppComponentsBreadcrumbsIntegration
   private @Nullable IScopes scopes;
   private @Nullable SentryAndroidOptions options;
 
+  // TODO: JAVA-729
+  @SuppressWarnings("deprecation")
   private final @NotNull Debouncer trimMemoryDebouncer =
       new Debouncer(AndroidCurrentDateProvider.getInstance(), DEBOUNCE_WAIT_TIME_MS, 0);
 

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

@@ -47,6 +47,8 @@ public final class ScreenshotEventProcessor implements EventProcessor {
   private final boolean isReplayAvailable;
   private final AtomicBoolean isReplayModuleAbsenceLogged = new AtomicBoolean(false);
 
+  // TODO: JAVA-729
+  @SuppressWarnings("deprecation")
   public ScreenshotEventProcessor(
       final @NotNull SentryAndroidOptions options,
       final @NotNull BuildInfoProvider buildInfoProvider,

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

@@ -298,6 +298,9 @@ final class SystemEventsBroadcastReceiver extends BroadcastReceiver {
     private static final long DEBOUNCE_WAIT_TIME_MS = 60 * 1000;
     private final @NotNull IScopes scopes;
     private final @NotNull SentryAndroidOptions options;
+
+    // TODO: JAVA-729
+    @SuppressWarnings("deprecation")
     private final @NotNull Debouncer batteryChangedDebouncer =
         new Debouncer(AndroidCurrentDateProvider.getInstance(), DEBOUNCE_WAIT_TIME_MS, 0);
 

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

@@ -46,6 +46,8 @@ public final class ViewHierarchyEventProcessor implements EventProcessor {
   private static final long DEBOUNCE_WAIT_TIME_MS = 2000;
   private static final int DEBOUNCE_MAX_EXECUTIONS = 3;
 
+  // TODO: JAVA-729
+  @SuppressWarnings("deprecation")
   public ViewHierarchyEventProcessor(final @NotNull SentryAndroidOptions options) {
     this.options = Objects.requireNonNull(options, "SentryAndroidOptions is required");
     this.debouncer =

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

@@ -38,6 +38,8 @@ public final class AndroidEnvelopeCache extends EnvelopeCache {
 
   private final @NotNull ICurrentDateProvider currentDateProvider;
 
+  // TODO: JAVA-729
+  @SuppressWarnings("deprecation")
   public AndroidEnvelopeCache(final @NotNull SentryAndroidOptions options) {
     this(options, AndroidCurrentDateProvider.getInstance());
   }

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

@@ -4,11 +4,27 @@
 import io.sentry.transport.ICurrentDateProvider;
 import org.jetbrains.annotations.ApiStatus;
 
+/**
+ * An uptime clock: {@link SystemClock#uptimeMillis()} excludes time the device spent in deep sleep,
+ * which neither the name nor the {@link ICurrentDateProvider} type says. {@link
+ * io.sentry.transport.CurrentDateProvider} implements that same type with epoch milliseconds, so a
+ * call site declaring the interface accepts either, and the two disagree by however long the device
+ * has been suspended.
+ *
+ * <p>Superseded by {@link io.sentry.time.MonotonicTicker}, which counts deep sleep and says in its
+ * name that only differences between its own ticks are meaningful. The annotation sits on {@link
+ * #getInstance()}, the only way in, because a deprecated type warns on every import and an import
+ * cannot carry a {@code @SuppressWarnings}.
+ */
 @ApiStatus.Internal
 public final class AndroidCurrentDateProvider implements ICurrentDateProvider {
 
   private static final ICurrentDateProvider instance = new AndroidCurrentDateProvider();
 
+  /**
+   * @deprecated use {@link io.sentry.time.MonotonicTicker} to measure an interval.
+   */
+  @Deprecated
   public static ICurrentDateProvider getInstance() {
     return instance;
   }