feat(integrations): Introduce ctor overloads for SystemEvents and AndroidConnectionStatusProvider that accept a Handler (#4808)

* feat(integrations): Introduce ctor overloads for  and  that accept a Handler to invoke their callbacks on

* Changelog

Author: romtsn

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Features
 
 - Add experimental Sentry Android Distribution module for integrating with Sentry Build Distribution to check for and install updates ([#4804](https://github.com/getsentry/sentry-java/pull/4804))
+- Allow passing a different `Handler` to `SystemEventsBreadcrumbsIntegration` and `AndroidConnectionStatusProvider` so their callbacks are deliver to that handler ([#4808](https://github.com/getsentry/sentry-java/pull/4808))
 
 ### Fixes
 

sentry-android-core/api/sentry-android-core.api

@@ -446,6 +446,7 @@ public class io/sentry/android/core/SpanFrameMetricsCollector : io/sentry/IPerfo
 
 public final class io/sentry/android/core/SystemEventsBreadcrumbsIntegration : io/sentry/Integration, io/sentry/android/core/AppState$AppStateListener, java/io/Closeable {
 	public fun <init> (Landroid/content/Context;)V
+	public fun <init> (Landroid/content/Context;Landroid/os/Handler;)V
 	public fun <init> (Landroid/content/Context;Ljava/util/List;)V
 	public fun close ()V
 	public static fun getDefaultActions ()Ljava/util/List;

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

@@ -232,6 +232,7 @@ private static void deduplicateIntegrations(
 
     final List<Integration> timberIntegrations = new ArrayList<>();
     final List<Integration> fragmentIntegrations = new ArrayList<>();
+    final List<Integration> systemEventsIntegrations = new ArrayList<>();
 
     for (final Integration integration : options.getIntegrations()) {
       if (isFragmentAvailable) {
@@ -244,6 +245,9 @@ private static void deduplicateIntegrations(
           timberIntegrations.add(integration);
         }
       }
+      if (integration instanceof SystemEventsBreadcrumbsIntegration) {
+        systemEventsIntegrations.add(integration);
+      }
     }
 
     if (fragmentIntegrations.size() > 1) {
@@ -259,5 +263,12 @@ private static void deduplicateIntegrations(
         options.getIntegrations().remove(integration);
       }
     }
+
+    if (systemEventsIntegrations.size() > 1) {
+      for (int i = 0; i < systemEventsIntegrations.size() - 1; i++) {
+        final Integration integration = systemEventsIntegrations.get(i);
+        options.getIntegrations().remove(integration);
+      }
+    }
   }
 }

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

@@ -72,15 +72,24 @@ public final class SystemEventsBreadcrumbsIntegration
   private final @NotNull AutoClosableReentrantLock receiverLock = new AutoClosableReentrantLock();
   // Track previous battery state to avoid duplicate breadcrumbs when values haven't changed
   private @Nullable BatteryState previousBatteryState;
+  @TestOnly @Nullable Handler customHandler = null;
 
   public SystemEventsBreadcrumbsIntegration(final @NotNull Context context) {
-    this(context, getDefaultActionsInternal());
+    this(context, getDefaultActionsInternal(), null);
+  }
+
+  public SystemEventsBreadcrumbsIntegration(
+      final @NotNull Context context, final @NotNull Handler handler) {
+    this(context, getDefaultActionsInternal(), handler);
   }
 
   SystemEventsBreadcrumbsIntegration(
-      final @NotNull Context context, final @NotNull String[] actions) {
+      final @NotNull Context context,
+      final @NotNull String[] actions,
+      final @Nullable Handler handler) {
     this.context = ContextUtils.getApplicationContext(context);
     this.actions = actions;
+    this.customHandler = handler;
   }
 
   public SystemEventsBreadcrumbsIntegration(
@@ -143,7 +152,7 @@ private void registerReceiver(
                       filter.addAction(item);
                     }
                   }
-                  if (handlerThread == null) {
+                  if (customHandler == null && handlerThread == null) {
                     handlerThread =
                         new HandlerThread(
                             "SystemEventsReceiver", Process.THREAD_PRIORITY_BACKGROUND);
@@ -154,7 +163,12 @@ private void registerReceiver(
                     // official docs
 
                     // onReceive will be called on this handler thread
-                    final @NotNull Handler handler = new Handler(handlerThread.getLooper());
+                    @NotNull Handler handler;
+                    if (customHandler != null) {
+                      handler = customHandler;
+                    } else {
+                      handler = new Handler(handlerThread.getLooper());
+                    }
                     ContextUtils.registerReceiver(context, options, receiver, filter, handler);
                     if (!isReceiverRegistered.getAndSet(true)) {
                       options

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

@@ -8,6 +8,7 @@
 import android.net.Network;
 import android.net.NetworkCapabilities;
 import android.os.Build;
+import android.os.Handler;
 import androidx.annotation.NonNull;
 import androidx.annotation.RequiresApi;
 import io.sentry.IConnectionStatusProvider;
@@ -42,6 +43,7 @@ public final class AndroidConnectionStatusProvider
   private final @NotNull BuildInfoProvider buildInfoProvider;
   private final @NotNull ICurrentDateProvider timeProvider;
   private final @NotNull List<IConnectionStatusObserver> connectionStatusObservers;
+  private final @Nullable Handler handler;
   private final @NotNull AutoClosableReentrantLock lock = new AutoClosableReentrantLock();
   private volatile @Nullable NetworkCallback networkCallback;
 
@@ -68,16 +70,26 @@ public final class AndroidConnectionStatusProvider
   private static final long CACHE_TTL_MS = 2 * 60 * 1000L; // 2 minutes
   private final @NotNull AtomicBoolean isConnected = new AtomicBoolean(false);
 
-  @SuppressLint("InlinedApi")
   public AndroidConnectionStatusProvider(
       @NotNull Context context,
       @NotNull SentryOptions options,
       @NotNull BuildInfoProvider buildInfoProvider,
       @NotNull ICurrentDateProvider timeProvider) {
+    this(context, options, buildInfoProvider, timeProvider, null);
+  }
+
+  @SuppressLint("InlinedApi")
+  public AndroidConnectionStatusProvider(
+      @NotNull Context context,
+      @NotNull SentryOptions options,
+      @NotNull BuildInfoProvider buildInfoProvider,
+      @NotNull ICurrentDateProvider timeProvider,
+      @Nullable Handler handler) {
     this.context = ContextUtils.getApplicationContext(context);
     this.options = options;
     this.buildInfoProvider = buildInfoProvider;
     this.timeProvider = timeProvider;
+    this.handler = handler;
     this.connectionStatusObservers = new ArrayList<>();
 
     capabilities[0] = NetworkCapabilities.NET_CAPABILITY_INTERNET;
@@ -326,7 +338,8 @@ private boolean hasSignificantTransportChanges(
             }
           };
 
-      if (registerNetworkCallback(context, options.getLogger(), buildInfoProvider, callback)) {
+      if (registerNetworkCallback(
+          context, options.getLogger(), buildInfoProvider, handler, callback)) {
         networkCallback = callback;
         options.getLogger().log(SentryLevel.DEBUG, "Network callback registered successfully");
       } else {
@@ -744,6 +757,7 @@ static boolean registerNetworkCallback(
       final @NotNull Context context,
       final @NotNull ILogger logger,
       final @NotNull BuildInfoProvider buildInfoProvider,
+      final @Nullable Handler handler,
       final @NotNull NetworkCallback networkCallback) {
     if (buildInfoProvider.getSdkInfoVersion() < Build.VERSION_CODES.N) {
       logger.log(SentryLevel.DEBUG, "NetworkCallbacks need Android N+.");
@@ -758,7 +772,11 @@ static boolean registerNetworkCallback(
       return false;
     }
     try {
-      connectivityManager.registerDefaultNetworkCallback(networkCallback);
+      if (handler != null) {
+        connectivityManager.registerDefaultNetworkCallback(networkCallback, handler);
+      } else {
+        connectivityManager.registerDefaultNetworkCallback(networkCallback);
+      }
     } catch (Throwable t) {
       logger.log(SentryLevel.WARNING, "registerDefaultNetworkCallback failed", t);
       return false;

sentry-android-core/src/test/java/io/sentry/android/core/SentryAndroidTest.kt

@@ -6,6 +6,7 @@ import android.app.ApplicationExitInfo
 import android.content.Context
 import android.os.Build
 import android.os.Bundle
+import android.os.Handler
 import android.os.Looper
 import android.os.SystemClock
 import androidx.test.core.app.ApplicationProvider
@@ -237,13 +238,19 @@ class SentryAndroidTest {
   }
 
   @Test
-  fun `deduplicates fragment and timber integrations`() {
+  fun `deduplicates fragment, timber and system events integrations`() {
     var refOptions: SentryAndroidOptions? = null
-
     fixture.initSut(autoInit = true) {
       it.addIntegration(FragmentLifecycleIntegration(ApplicationProvider.getApplicationContext()))
 
       it.addIntegration(SentryTimberIntegration(minEventLevel = FATAL, minBreadcrumbLevel = DEBUG))
+
+      it.addIntegration(
+        SystemEventsBreadcrumbsIntegration(
+          ApplicationProvider.getApplicationContext(),
+          CustomHandler(Looper.getMainLooper()),
+        )
+      )
       refOptions = it
     }
 
@@ -256,6 +263,11 @@ class SentryAndroidTest {
     // fragment integration is not auto-installed in the test, since the context is not Application
     // but we just verify here that the single integration is preserved
     assertEquals(refOptions!!.integrations.filterIsInstance<FragmentLifecycleIntegration>().size, 1)
+
+    val systemEventsIntegrations =
+      refOptions!!.integrations.filterIsInstance<SystemEventsBreadcrumbsIntegration>()
+    assertEquals(systemEventsIntegrations.size, 1)
+    assertTrue(systemEventsIntegrations.first().customHandler is CustomHandler)
   }
 
   @Test
@@ -580,3 +592,5 @@ fun initForTest(context: Context, logger: ILogger) {
 fun initForTest(context: Context) {
   SentryAndroid.init(context)
 }
+
+class CustomHandler(looper: Looper) : Handler(looper)

sentry-android-core/src/test/java/io/sentry/android/core/SystemEventsBreadcrumbsIntegrationTest.kt

@@ -6,6 +6,7 @@ import android.content.Context
 import android.content.Intent
 import android.os.BatteryManager
 import android.os.Build
+import android.os.Handler
 import android.os.Looper
 import androidx.test.core.app.ApplicationProvider
 import androidx.test.ext.junit.runners.AndroidJUnit4
@@ -27,6 +28,7 @@ import kotlin.test.assertTrue
 import org.junit.runner.RunWith
 import org.mockito.kotlin.any
 import org.mockito.kotlin.anyOrNull
+import org.mockito.kotlin.argThat
 import org.mockito.kotlin.check
 import org.mockito.kotlin.mock
 import org.mockito.kotlin.never
@@ -53,6 +55,7 @@ class SystemEventsBreadcrumbsIntegrationTest {
       enableSystemEventBreadcrumbs: Boolean = true,
       enableSystemEventBreadcrumbsExtras: Boolean = false,
       executorService: ISentryExecutorService = ImmediateExecutorService(),
+      handler: Handler? = null,
     ): SystemEventsBreadcrumbsIntegration {
       options =
         SentryAndroidOptions().apply {
@@ -63,6 +66,7 @@ class SystemEventsBreadcrumbsIntegrationTest {
       return SystemEventsBreadcrumbsIntegration(
         context,
         SystemEventsBreadcrumbsIntegration.getDefaultActions().toTypedArray(),
+        handler,
       )
     }
   }
@@ -585,4 +589,16 @@ class SystemEventsBreadcrumbsIntegrationTest {
         anyOrNull(),
       )
   }
+
+  @Test
+  fun `When a custom handler is provided, it is used upon registering the callback`() {
+    val customHandler = object : Handler(Looper.getMainLooper()) {}
+    val sut = fixture.getSut(handler = customHandler)
+
+    sut.register(fixture.scopes, fixture.options)
+
+    verify(fixture.context)
+      .registerReceiver(any(), any(), anyOrNull(), argThat { this == customHandler }, any())
+    assertNotNull(sut.receiver)
+  }
 }

sentry-android-core/src/test/java/io/sentry/android/core/internal/util/AndroidConnectionStatusProviderTest.kt

@@ -15,6 +15,8 @@ import android.net.NetworkCapabilities.TRANSPORT_ETHERNET
 import android.net.NetworkCapabilities.TRANSPORT_WIFI
 import android.net.NetworkInfo
 import android.os.Build
+import android.os.Handler
+import android.os.Looper
 import androidx.test.ext.junit.runners.AndroidJUnit4
 import io.sentry.IConnectionStatusProvider
 import io.sentry.ILogger
@@ -38,6 +40,7 @@ import org.mockito.MockedStatic
 import org.mockito.Mockito.mockStatic
 import org.mockito.kotlin.any
 import org.mockito.kotlin.anyOrNull
+import org.mockito.kotlin.argThat
 import org.mockito.kotlin.argumentCaptor
 import org.mockito.kotlin.clearInvocations
 import org.mockito.kotlin.eq
@@ -274,6 +277,7 @@ class AndroidConnectionStatusProviderTest {
         contextMock,
         logger,
         buildInfo,
+        null,
         mock(),
       )
     )
@@ -841,4 +845,20 @@ class AndroidConnectionStatusProviderTest {
     // Verify no additional unregister calls
     verifyNoInteractions(connectivityManager)
   }
+
+  @Test
+  fun `registerNetworkCallback with a custom handlers calls connectivityManager with it`() {
+    val customHandler = object : Handler(Looper.getMainLooper()) {}
+    whenever(contextMock.getSystemService(any())).thenReturn(connectivityManager)
+    AndroidConnectionStatusProvider.registerNetworkCallback(
+      contextMock,
+      logger,
+      buildInfo,
+      customHandler,
+      mock(),
+    )
+
+    verify(connectivityManager)
+      .registerDefaultNetworkCallback(any<NetworkCallback>(), argThat { this == customHandler })
+  }
 }