It is an immutable value class implemented by AutoValue. - * - * @see https://github.com/google/auto/tree/master/value + * The release information returned by {@link FirebaseAppDistribution#checkForNewRelease} when a new + * version is available for the signed in tester. */ @AutoValue public abstract class AppDistributionRelease { @@ -35,19 +30,19 @@ static Builder builder() { return new com.google.firebase.appdistribution.AutoValue_AppDistributionRelease.Builder(); } - /** The short bundle version of this build (example 1.0.0) */ + /** The short bundle version of this build (example 1.0.0). */ @NonNull public abstract String getDisplayVersion(); - /** The version code of this build (example: 123) */ + /** The version code of this build (example: 123). */ @NonNull public abstract long getVersionCode(); - /** The release notes for this build */ + /** The release notes for this build. */ @Nullable public abstract String getReleaseNotes(); - /** The binary type for this build */ + /** The binary type for this build. */ @NonNull public abstract BinaryType getBinaryType(); diff --git a/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/BinaryType.java b/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/BinaryType.java index efe5719f915..b2ac653d407 100644 --- a/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/BinaryType.java +++ b/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/BinaryType.java @@ -14,8 +14,11 @@ package com.google.firebase.appdistribution; -/** Enum of Android App Binary types, used in AppDistributionRelease */ +/** Enum of Android app binary types, used in {@link AppDistributionRelease} */ public enum BinaryType { + /** Android App Bundle. */ AAB, + + /** Android Application Package. */ APK } diff --git a/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/FirebaseAppDistribution.java b/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/FirebaseAppDistribution.java index 17110e54351..f2196dd83e2 100644 --- a/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/FirebaseAppDistribution.java +++ b/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/FirebaseAppDistribution.java @@ -39,6 +39,15 @@ import com.google.firebase.inject.Provider; import com.google.firebase.installations.FirebaseInstallationsApi; +/** + * The Firebase App Distribution API provides methods to update the app to the most recent + * pre-release build. + * + *
By default, Firebase App Distribution is automatically initialized. + * + *
Call {@link FirebaseAppDistribution#getInstance()} to get the singleton instance of + * FirebaseAppDistribution. + */ public class FirebaseAppDistribution { private static final int UNKNOWN_RELEASE_FILE_SIZE = -1; @@ -124,19 +133,25 @@ public class FirebaseAppDistribution { FirebaseAppDistributionLifecycleNotifier.getInstance()); } - /** @return a FirebaseAppDistribution instance */ + /** Gets the singleton {@link FirebaseAppDistribution} instance. */ @NonNull public static FirebaseAppDistribution getInstance() { return FirebaseApp.getInstance().get(FirebaseAppDistribution.class); } /** - * Updates the app to the newest release, if one is available. Returns the release information or - * null if no update is found. Performs the following actions: 1. If tester is not signed in, - * presents the tester with a Google sign in UI 2. Checks if a newer release is available. If so, - * presents the tester with a confirmation dialog to begin the download. 3. For APKs, downloads - * the binary and starts an installation intent. 4. For AABs, directs the tester to the Play app - * to complete the download and installation. + * Updates the app to the newest release, if one is available. + * + *
Returns the release information or null if no update is found. Performs the following + * actions: + * + *
If the newest release is an APK, downloads the binary and starts an installation. If the + * newest release is an AAB, directs the tester to the Play app to complete the download and + * installation. * - *
cancels task with FirebaseAppDistributionException with UPDATE_NOT_AVAILABLE exception if no - * new release is cached from checkForNewRelease + *
Cancels task with {@link Status#UPDATE_NOT_AVAILABLE} if no new release is cached from + * {@link #checkForNewRelease}. */ @NonNull public UpdateTask updateApp() { @@ -324,7 +340,7 @@ private UpdateTask updateApp(boolean showDownloadInNotificationManager) { } } - /** Returns true if the App Distribution tester is signed in */ + /** Returns {@code true} if the App Distribution tester is signed in. */ public boolean isTesterSignedIn() { return this.signInStorage.getSignInStatus(); } diff --git a/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/FirebaseAppDistributionException.java b/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/FirebaseAppDistributionException.java index 86c43b3d790..e48e7dcb74c 100644 --- a/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/FirebaseAppDistributionException.java +++ b/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/FirebaseAppDistributionException.java @@ -19,37 +19,38 @@ import com.google.firebase.FirebaseException; import com.google.firebase.appdistribution.Constants.ErrorMessages; -/** Possible exceptions thrown in FirebaseAppDistribution */ +/** The class for all Exceptions thrown by {@link FirebaseAppDistribution}. */ public class FirebaseAppDistributionException extends FirebaseException { + /** Enum for potential error statuses that caused the {@link FirebaseAppDistributionException}. */ public enum Status { /** Unknown error. */ UNKNOWN, - /** Authentication failed */ + /** The authentication process failed. */ AUTHENTICATION_FAILURE, - /** Authentication canceled */ + /** The authentication process was canceled. */ AUTHENTICATION_CANCELED, - /** No Network available to make requests or the request timed out */ + /** No network is available to make requests or the request timed out. */ NETWORK_FAILURE, - /** Download failed */ + /** The new release failed to download. */ DOWNLOAD_FAILURE, - /** Installation failed */ + /** The new release failed to install. */ INSTALLATION_FAILURE, - /** Installation canceled */ + /** The installation was canceled. */ INSTALLATION_CANCELED, - /** Update not available for the current tester and app */ + /** An update is not available for the current tester and app. */ UPDATE_NOT_AVAILABLE, - /** App is in production */ + /** The app is running in production. */ APP_RUNNING_IN_PRODUCTION, - /** Host activity for confirmation dialog destroyed or pushed to the backstack */ + /** The host activity for a confirmation dialog was destroyed or pushed to the backstack. */ HOST_ACTIVITY_INTERRUPTED, } @@ -86,12 +87,13 @@ public enum Status { this.release = release; } - /** Get cached release when error was thrown */ + /** Returns the release that was ready to be installed when the error was thrown. */ @Nullable public AppDistributionRelease getRelease() { return release; } + /** Returns the {@link FirebaseAppDistributionException.Status} that caused the exception. */ @NonNull public Status getErrorCode() { return status; diff --git a/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/OnProgressListener.java b/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/OnProgressListener.java index c651eb6a362..8f8f3ac8e72 100644 --- a/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/OnProgressListener.java +++ b/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/OnProgressListener.java @@ -18,5 +18,6 @@ /** A listener that is called periodically during execution of the {@link UpdateTask}. */ public interface OnProgressListener { + /** Called periodically for progress update and state changes of the {@link UpdateTask}. */ void onProgressUpdate(@NonNull UpdateProgress updateState); } diff --git a/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/UpdateProgress.java b/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/UpdateProgress.java index 840a04154af..a0a77719dbf 100644 --- a/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/UpdateProgress.java +++ b/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/UpdateProgress.java @@ -18,7 +18,7 @@ import androidx.annotation.Nullable; import com.google.auto.value.AutoValue; -/** Data class to get download progress for APKs and the status of the update. Used in updateApp. */ +/** Represents a progress update or a final state from updating an app. */ @AutoValue public abstract class UpdateProgress { @@ -28,21 +28,25 @@ static UpdateProgress.Builder builder() { } /** - * The number of bytes downloaded so far for the APK. Returns -1 if called on an AAB or if no new - * release is available. + * The number of bytes downloaded so far for an APK. + * + * @returns the number of bytes downloaded, or -1 if called when updating to an AAB or if no new + * release is available. */ @NonNull public abstract long getApkBytesDownloaded(); /** - * The file size of the APK file to download in bytes. Returns -1 if called on an AAB or if no new - * release is available. + * The file size of the APK file to download in bytes. + * + * @returns the file size in bytes, or -1 if called when updating to an AAB or if no new release + * is available. */ @NonNull public abstract long getApkFileTotalBytes(); + /** Returns the current {@link UpdateStatus} of the update. */ @NonNull - /** returns the current state of the update */ public abstract UpdateStatus getUpdateStatus(); /** Builder for {@link UpdateProgress}. */ diff --git a/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/UpdateStatus.java b/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/UpdateStatus.java index d7d4aa3f1f1..a90e0354c50 100644 --- a/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/UpdateStatus.java +++ b/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/UpdateStatus.java @@ -14,35 +14,35 @@ package com.google.firebase.appdistribution; -/** Enum for possible states during Update, used in UpdateProgress. */ +/** Enum for possible states during Update, used in {@link UpdateProgress}. */ public enum UpdateStatus { - /** Update queued but not started */ + /** The update is queued but not started. */ PENDING, - /** Download in progress */ + /** The new release download is in progress. */ DOWNLOADING, - /** Download completed */ + /** The new release was downloaded successfully. */ DOWNLOADED, - /** Download failed */ + /** The new release failed to download. */ DOWNLOAD_FAILED, - /** Installation canceled */ + /** The new release installation was canceled. */ INSTALL_CANCELED, - /** Installation failed */ + /** The new release installation failed. */ INSTALL_FAILED, - /** AAB flow (directed to Play) */ + /** The tester was redirected to Play to download an {@link BinaryType#AAB} file. */ REDIRECTED_TO_PLAY, - /** Currently on the latest release */ + /** The tester is currently on the latest release they have access to for the current app. */ NEW_RELEASE_NOT_AVAILABLE, - /** Release check failed before download started */ + /** The call to {@link FirebaseAppDistribution#checkForNewRelease} failed. */ NEW_RELEASE_CHECK_FAILED, - /** Customer canceled the update */ + /** The tester canceled the update. */ UPDATE_CANCELED, } diff --git a/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/UpdateTask.java b/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/UpdateTask.java index 642ba8dbf33..a14ca7a45e3 100644 --- a/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/UpdateTask.java +++ b/firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/UpdateTask.java @@ -19,15 +19,26 @@ import com.google.android.gms.tasks.Task; import java.util.concurrent.Executor; +/** + * Represents an asynchronous operation to update an app. + * + *
This task also receives progress and other state change notifications.
+ */
public abstract class UpdateTask extends Task