feat(android-distribution): Run checkForUpdate on background thread (EME-413) (#4811)

* feat(android-distribution): Run checkForUpdate on background thread (EME-413)

Implement async version of checkForUpdate that runs on a background thread
instead of blocking the calling thread. The callback is invoked on the
background thread, allowing callers to dispatch to main thread if needed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* refactor(android-distribution): Use Future instead of callback for async checkForUpdate (EME-413)

Replace callback-based API with Future-based API to avoid confusion and improve consistency with SDK patterns. Use SentryExecutorService instead of spawning new threads to better manage resources.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* refactor(sentry): Use custom CompletedFuture for API 21+ compatibility (EME-413)

Replace CompletableFuture.completedFuture() with a custom CompletedFuture
implementation in NoOpDistributionApi to maintain Android API 21+ compatibility.
CompletableFuture was only added in Android API 24.

The new CompletedFuture follows the same pattern as existing CancelledFuture
implementations in the codebase and returns an immediately completed Future
with a result.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* refactor(android-distribution): Import Future type for cleaner code (EME-413)

Add explicit import for java.util.concurrent.Future and use short form
instead of fully qualified name in method signature.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* fix(samples): Update MainActivity to use Future-based checkForUpdate API (EME-413)

Update sample app to use the new Future-based checkForUpdate() method
instead of the old callback-based API. The Future is processed on a
background thread and results are posted back to the UI thread.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* refactor(samples): Add Future import and async library comment (EME-413)

Improves code readability by importing Future instead of using fully qualified name.
Adds guidance comment suggesting developers convert the sample to their preferred
async library (RxJava, Coroutines, etc.) in production code.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* style(samples): Reflow comment for proper line length (EME-413)

Applied spotlessApply formatting to wrap long comment line.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* release: 8.24.0-alpha.2

---------

Co-authored-by: Claude <[email protected]>
Co-authored-by: getsentry-bot <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## Unreleased
+## 8.24.0-alpha.2
 
 ### Features
 

gradle.properties

@@ -11,7 +11,7 @@ org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
 android.useAndroidX=true
 
 # Release information
-versionName=8.23.0
+versionName=8.24.0-alpha.2
 
 # Override the SDK name on native crashes on Android
 sentryAndroidSdkName=sentry.native.android

sentry-android-distribution/api/sentry-android-distribution.api

@@ -1,6 +1,6 @@
 public final class io/sentry/android/distribution/DistributionIntegration : io/sentry/IDistributionApi, io/sentry/Integration {
 	public fun <init> (Landroid/content/Context;)V
-	public fun checkForUpdate (Lio/sentry/IDistributionApi$UpdateCallback;)V
+	public fun checkForUpdate ()Ljava/util/concurrent/Future;
 	public fun checkForUpdateBlocking ()Lio/sentry/UpdateStatus;
 	public fun downloadUpdate (Lio/sentry/UpdateInfo;)V
 	public fun isEnabled ()Z

sentry-android-distribution/src/main/java/io/sentry/android/distribution/DistributionIntegration.kt

@@ -14,6 +14,7 @@ import io.sentry.UpdateInfo
 import io.sentry.UpdateStatus
 import java.net.SocketTimeoutException
 import java.net.UnknownHostException
+import java.util.concurrent.Future
 import org.jetbrains.annotations.ApiStatus
 
 /**
@@ -84,14 +85,12 @@ public class DistributionIntegration(context: Context) : Integration, IDistribut
   }
 
   /**
-   * Check for available updates asynchronously using a callback.
+   * Check for available updates asynchronously.
    *
-   * @param onResult Callback that will be called with the UpdateStatus result
+   * @return Future that will resolve to an UpdateStatus result
    */
-  public override fun checkForUpdate(onResult: IDistributionApi.UpdateCallback) {
-    // TODO implement this in a async way
-    val result = checkForUpdateBlocking()
-    onResult.onResult(result)
+  public override fun checkForUpdate(): Future<UpdateStatus> {
+    return sentryOptions.executorService.submit<UpdateStatus> { checkForUpdateBlocking() }
   }
 
   /**

sentry-samples/sentry-samples-android/src/main/java/io/sentry/samples/android/MainActivity.java

@@ -29,6 +29,7 @@
 import java.util.Collections;
 import java.util.List;
 import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.Future;
 import timber.log.Timber;
 
 public class MainActivity extends AppCompatActivity {
@@ -315,35 +316,51 @@ public void run() {
     binding.checkForUpdate.setOnClickListener(
         view -> {
           Toast.makeText(this, "Checking for updates...", Toast.LENGTH_SHORT).show();
-          Sentry.distribution()
-              .checkForUpdate(
-                  result -> {
-                    runOnUiThread(
-                        () -> {
-                          String message;
-                          if (result instanceof UpdateStatus.NewRelease) {
-                            UpdateStatus.NewRelease newRelease = (UpdateStatus.NewRelease) result;
-                            message =
-                                "Update available: "
-                                    + newRelease.getInfo().getBuildVersion()
-                                    + " (Build "
-                                    + newRelease.getInfo().getBuildNumber()
-                                    + ")\nDownload URL: "
-                                    + newRelease.getInfo().getDownloadUrl();
-                          } else if (result instanceof UpdateStatus.UpToDate) {
-                            message = "App is up to date!";
-                          } else if (result instanceof UpdateStatus.NoNetwork) {
-                            UpdateStatus.NoNetwork noNetwork = (UpdateStatus.NoNetwork) result;
-                            message = "No network connection: " + noNetwork.getMessage();
-                          } else if (result instanceof UpdateStatus.UpdateError) {
-                            UpdateStatus.UpdateError error = (UpdateStatus.UpdateError) result;
-                            message = "Error checking for updates: " + error.getMessage();
-                          } else {
-                            message = "Unknown status";
-                          }
-                          Toast.makeText(this, message, Toast.LENGTH_LONG).show();
-                        });
-                  });
+          Future<UpdateStatus> future = Sentry.distribution().checkForUpdate();
+          // In production, convert this to use your preferred async library (RxJava, Coroutines,
+          // etc.)
+          // This sample uses raw threads and Future.get() for simplicity
+          // Process result on background thread, then update UI
+          new Thread(
+                  () -> {
+                    try {
+                      UpdateStatus result = future.get();
+                      runOnUiThread(
+                          () -> {
+                            String message;
+                            if (result instanceof UpdateStatus.NewRelease) {
+                              UpdateStatus.NewRelease newRelease = (UpdateStatus.NewRelease) result;
+                              message =
+                                  "Update available: "
+                                      + newRelease.getInfo().getBuildVersion()
+                                      + " (Build "
+                                      + newRelease.getInfo().getBuildNumber()
+                                      + ")\nDownload URL: "
+                                      + newRelease.getInfo().getDownloadUrl();
+                            } else if (result instanceof UpdateStatus.UpToDate) {
+                              message = "App is up to date!";
+                            } else if (result instanceof UpdateStatus.NoNetwork) {
+                              UpdateStatus.NoNetwork noNetwork = (UpdateStatus.NoNetwork) result;
+                              message = "No network connection: " + noNetwork.getMessage();
+                            } else if (result instanceof UpdateStatus.UpdateError) {
+                              UpdateStatus.UpdateError error = (UpdateStatus.UpdateError) result;
+                              message = "Error checking for updates: " + error.getMessage();
+                            } else {
+                              message = "Unknown status";
+                            }
+                            Toast.makeText(this, message, Toast.LENGTH_LONG).show();
+                          });
+                    } catch (Exception e) {
+                      runOnUiThread(
+                          () ->
+                              Toast.makeText(
+                                      this,
+                                      "Error checking for updates: " + e.getMessage(),
+                                      Toast.LENGTH_LONG)
+                                  .show());
+                    }
+                  })
+              .start();
         });
 
     binding.openCameraActivity.setOnClickListener(

sentry/api/sentry.api

@@ -776,16 +776,12 @@ public abstract interface class io/sentry/IContinuousProfiler {
 }
 
 public abstract interface class io/sentry/IDistributionApi {
-	public abstract fun checkForUpdate (Lio/sentry/IDistributionApi$UpdateCallback;)V
+	public abstract fun checkForUpdate ()Ljava/util/concurrent/Future;
 	public abstract fun checkForUpdateBlocking ()Lio/sentry/UpdateStatus;
 	public abstract fun downloadUpdate (Lio/sentry/UpdateInfo;)V
 	public abstract fun isEnabled ()Z
 }
 
-public abstract interface class io/sentry/IDistributionApi$UpdateCallback {
-	public abstract fun onResult (Lio/sentry/UpdateStatus;)V
-}
-
 public abstract interface class io/sentry/IEnvelopeReader {
 	public abstract fun read (Ljava/io/InputStream;)Lio/sentry/SentryEnvelope;
 }
@@ -1494,7 +1490,7 @@ public final class io/sentry/NoOpContinuousProfiler : io/sentry/IContinuousProfi
 }
 
 public final class io/sentry/NoOpDistributionApi : io/sentry/IDistributionApi {
-	public fun checkForUpdate (Lio/sentry/IDistributionApi$UpdateCallback;)V
+	public fun checkForUpdate ()Ljava/util/concurrent/Future;
 	public fun checkForUpdateBlocking ()Lio/sentry/UpdateStatus;
 	public fun downloadUpdate (Lio/sentry/UpdateInfo;)V
 	public static fun getInstance ()Lio/sentry/NoOpDistributionApi;

sentry/src/main/java/io/sentry/IDistributionApi.java

@@ -1,5 +1,6 @@
 package io.sentry;
 
+import java.util.concurrent.Future;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
@@ -14,20 +15,21 @@ public interface IDistributionApi {
 
   /**
    * Check for available updates synchronously (blocking call). This method will block the calling
-   * thread while making the network request. Consider using checkForUpdate with callback for
-   * non-blocking behavior.
+   * thread while making the network request. Consider using checkForUpdate for non-blocking
+   * behavior.
    *
    * @return UpdateStatus indicating if an update is available, up to date, or error
    */
   @NotNull
   UpdateStatus checkForUpdateBlocking();
 
   /**
-   * Check for available updates asynchronously using a callback.
+   * Check for available updates asynchronously.
    *
-   * @param onResult Callback that will be called with the UpdateStatus result
+   * @return Future that will resolve to an UpdateStatus result
    */
-  void checkForUpdate(@NotNull UpdateCallback onResult);
+  @NotNull
+  Future<UpdateStatus> checkForUpdate();
 
   /**
    * Download and install the provided update by opening the download URL in the default browser or
@@ -43,9 +45,4 @@ public interface IDistributionApi {
    * @return true if the distribution integration is enabled, false otherwise
    */
   boolean isEnabled();
-
-  /** Callback interface for receiving async update check results. */
-  interface UpdateCallback {
-    void onResult(@NotNull UpdateStatus status);
-  }
 }

sentry/src/main/java/io/sentry/NoOpDistributionApi.java

@@ -1,5 +1,9 @@
 package io.sentry;
 
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
@@ -21,8 +25,8 @@ public static NoOpDistributionApi getInstance() {
   }
 
   @Override
-  public void checkForUpdate(@NotNull UpdateCallback onResult) {
-    // No-op implementation - do nothing
+  public @NotNull Future<UpdateStatus> checkForUpdate() {
+    return new CompletedFuture<>(UpdateStatus.UpToDate.getInstance());
   }
 
   @Override
@@ -34,4 +38,42 @@ public void downloadUpdate(@NotNull UpdateInfo info) {
   public boolean isEnabled() {
     return false;
   }
+
+  /**
+   * A Future implementation that is already completed with a result. This is used instead of
+   * CompletableFuture.completedFuture() to maintain compatibility with Android API 21+.
+   */
+  private static final class CompletedFuture<T> implements Future<T> {
+    private final T result;
+
+    CompletedFuture(T result) {
+      this.result = result;
+    }
+
+    @Override
+    public boolean cancel(final boolean mayInterruptIfRunning) {
+      return false;
+    }
+
+    @Override
+    public boolean isCancelled() {
+      return false;
+    }
+
+    @Override
+    public boolean isDone() {
+      return true;
+    }
+
+    @Override
+    public T get() throws ExecutionException {
+      return result;
+    }
+
+    @Override
+    public T get(final long timeout, final @NotNull TimeUnit unit)
+        throws ExecutionException, TimeoutException {
+      return result;
+    }
+  }
 }