From 9e0787f23df1b9604276a3013d81e236468f11aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dominik=20Sch=C3=BCrmann?= Date: Tue, 31 May 2016 17:05:57 +0200 Subject: [PATCH] Add javadoc to installer classes --- .../fdroid/installer/DefaultInstaller.java | 7 +++++ .../installer/DefaultInstallerActivity.java | 2 +- .../fdroid/installer/ExtensionInstaller.java | 4 +++ .../fdroid/fdroid/installer/Installer.java | 28 ++++++++++++++++--- .../fdroid/installer/InstallerFactory.java | 20 +++++++++---- .../fdroid/installer/InstallerService.java | 24 ++++++++++++++++ .../fdroid/installer/PrivilegedInstaller.java | 22 +++++++++------ 7 files changed, 87 insertions(+), 20 deletions(-) diff --git a/app/src/main/java/org/fdroid/fdroid/installer/DefaultInstaller.java b/app/src/main/java/org/fdroid/fdroid/installer/DefaultInstaller.java index 52bf12d49..c6d73654f 100644 --- a/app/src/main/java/org/fdroid/fdroid/installer/DefaultInstaller.java +++ b/app/src/main/java/org/fdroid/fdroid/installer/DefaultInstaller.java @@ -29,6 +29,13 @@ import org.fdroid.fdroid.Utils; import java.io.File; +/** + * The default installer of F-Droid. It uses the normal Intents APIs of Android + * to install apks. Its main inner workings are encapsulated in DefaultInstallerActivity. + *

+ * This is installer requires user interaction and thus install/uninstall directly + * return PendingIntents. + */ public class DefaultInstaller extends Installer { private static final String TAG = "DefaultInstaller"; diff --git a/app/src/main/java/org/fdroid/fdroid/installer/DefaultInstallerActivity.java b/app/src/main/java/org/fdroid/fdroid/installer/DefaultInstallerActivity.java index 0fd2bfa88..6e1e64ff4 100644 --- a/app/src/main/java/org/fdroid/fdroid/installer/DefaultInstallerActivity.java +++ b/app/src/main/java/org/fdroid/fdroid/installer/DefaultInstallerActivity.java @@ -33,7 +33,7 @@ import android.util.Log; import org.fdroid.fdroid.R; /** - * A transparent activity as a wrapper around AOSP's PackageInstaller Intents + * A transparent activity as a wrapper around Android's PackageInstaller Intents */ public class DefaultInstallerActivity extends FragmentActivity { public static final String TAG = "AndroidInstallerAct"; diff --git a/app/src/main/java/org/fdroid/fdroid/installer/ExtensionInstaller.java b/app/src/main/java/org/fdroid/fdroid/installer/ExtensionInstaller.java index a53a205d8..970b8f99f 100644 --- a/app/src/main/java/org/fdroid/fdroid/installer/ExtensionInstaller.java +++ b/app/src/main/java/org/fdroid/fdroid/installer/ExtensionInstaller.java @@ -32,6 +32,10 @@ import java.io.File; /** * Special Installer that is only useful to install the Privileged Extension apk + * as a privileged app into the system partition of Android. + *

+ * This is installer requires user interaction and thus install/uninstall directly + * return PendingIntents. */ public class ExtensionInstaller extends Installer { diff --git a/app/src/main/java/org/fdroid/fdroid/installer/Installer.java b/app/src/main/java/org/fdroid/fdroid/installer/Installer.java index 23276f5cc..b1ed0ff13 100644 --- a/app/src/main/java/org/fdroid/fdroid/installer/Installer.java +++ b/app/src/main/java/org/fdroid/fdroid/installer/Installer.java @@ -45,6 +45,9 @@ import java.io.IOException; import java.security.NoSuchAlgorithmException; import java.util.Map; +/** + * + */ public abstract class Installer { final Context context; final PackageManager pm; @@ -64,10 +67,10 @@ public abstract class Installer { * Same as http://developer.android.com/reference/android/content/Intent.html#EXTRA_ORIGINATING_URI * In InstallManagerService often called urlString */ - public static final String EXTRA_ORIGINATING_URI = "org.fdroid.fdroid.installer.InstallerService.extra.ORIGINATING_URI"; - public static final String EXTRA_PACKAGE_NAME = "org.fdroid.fdroid.installer.InstallerService.extra.PACKAGE_NAME"; - public static final String EXTRA_USER_INTERACTION_PI = "org.fdroid.fdroid.installer.InstallerService.extra.USER_INTERACTION_PI"; - public static final String EXTRA_ERROR_MESSAGE = "org.fdroid.fdroid.net.Downloader.extra.ERROR_MESSAGE"; + public static final String EXTRA_ORIGINATING_URI = "org.fdroid.fdroid.installer.Installer.extra.ORIGINATING_URI"; + public static final String EXTRA_PACKAGE_NAME = "org.fdroid.fdroid.installer.Installer.extra.PACKAGE_NAME"; + public static final String EXTRA_USER_INTERACTION_PI = "org.fdroid.fdroid.installer.Installer.extra.USER_INTERACTION_PI"; + public static final String EXTRA_ERROR_MESSAGE = "org.fdroid.fdroid.net.installer.Installer.extra.ERROR_MESSAGE"; public static class InstallFailedException extends Exception { @@ -155,6 +158,14 @@ public abstract class Installer { return Uri.fromFile(sanitizedApkFile); } + /** + * Returns permission screen for given apk. + * + * @param apk instance of Apk + * @return Intent with Activity to show required permissions. + * Returns null if Installer handles that on itself, e.g., with DefaultInstaller, + * or if no new permissions have been introduced during an update + */ public Intent getPermissionScreen(Apk apk) { if (!isUnattended()) { return null; @@ -195,6 +206,15 @@ public abstract class Installer { return perms.getPermissionCount(AppSecurityPermissions.WHICH_ALL); } + /** + * Returns an Intent to start a dialog wrapped in an activity + * for uninstall confirmation. + * + * @param packageName packageName of app to uninstall + * @return Intent with activity for uninstall confirmation + * Returns null if Installer handles that on itself, e.g., + * with DefaultInstaller. + */ public Intent getUninstallScreen(String packageName) { if (!isUnattended()) { return null; diff --git a/app/src/main/java/org/fdroid/fdroid/installer/InstallerFactory.java b/app/src/main/java/org/fdroid/fdroid/installer/InstallerFactory.java index 3f57b26e4..f2ecd7b6a 100644 --- a/app/src/main/java/org/fdroid/fdroid/installer/InstallerFactory.java +++ b/app/src/main/java/org/fdroid/fdroid/installer/InstallerFactory.java @@ -29,15 +29,23 @@ public class InstallerFactory { private static final String TAG = "InstallerFactory"; - public static Installer create(Context context) { - return create(context, null); - } - + /** + * Returns an instance of an appropriate installer. + * Either DefaultInstaller, PrivilegedInstaller, or in the special + * case to install the "F-Droid Privileged Extension" ExtensionInstaller. + * + * @param context current {@link Context} + * @param packageName package name of apk to be installed. Required to select + * the ExtensionInstaller. + * If this is null, the ExtensionInstaller will never be returned. + * @return instance of an Installer + */ public static Installer create(Context context, String packageName) { Installer installer; - if (packageName != null && packageName.equals(PrivilegedInstaller.PRIVILEGED_EXTENSION_PACKAGE_NAME)) { - // special case: F-Droid Privileged Extension + if (packageName != null + && packageName.equals(PrivilegedInstaller.PRIVILEGED_EXTENSION_PACKAGE_NAME)) { + // special case for "F-Droid Privileged Extension" installer = new ExtensionInstaller(context); } else if (isPrivilegedInstallerEnabled()) { if (PrivilegedInstaller.isExtensionInstalledCorrectly(context) diff --git a/app/src/main/java/org/fdroid/fdroid/installer/InstallerService.java b/app/src/main/java/org/fdroid/fdroid/installer/InstallerService.java index e5784447b..1af566fa3 100644 --- a/app/src/main/java/org/fdroid/fdroid/installer/InstallerService.java +++ b/app/src/main/java/org/fdroid/fdroid/installer/InstallerService.java @@ -24,6 +24,16 @@ import android.content.Context; import android.content.Intent; import android.net.Uri; +/** + * This service handles the install process of apk files and + * uninstall process of apps. + *

+ * This service is based on an IntentService because: + * - no parallel installs/uninstalls should be allowed, + * i.e., runs sequentially + * - no cancel operation is needed. Cancelling an installation + * would be the same as starting uninstall afterwards + */ public class InstallerService extends IntentService { private static final String ACTION_INSTALL = "org.fdroid.fdroid.installer.InstallerService.action.INSTALL"; @@ -48,6 +58,14 @@ public class InstallerService extends IntentService { } } + /** + * Install an apk from {@link Uri} + * + * @param context this app's {@link Context} + * @param uri {@link Uri} pointing to (downloaded) local apk file + * @param originatingUri {@link Uri} where the apk has been downloaded from + * @param packageName package name of the app that should be installed + */ public static void install(Context context, Uri uri, Uri originatingUri, String packageName) { Intent intent = new Intent(context, InstallerService.class); intent.setAction(ACTION_INSTALL); @@ -57,6 +75,12 @@ public class InstallerService extends IntentService { context.startService(intent); } + /** + * Uninstall an app + * + * @param context this app's {@link Context} + * @param packageName package name of the app that will be uninstalled + */ public static void uninstall(Context context, String packageName) { Intent intent = new Intent(context, InstallerService.class); intent.setAction(ACTION_UNINSTALL); diff --git a/app/src/main/java/org/fdroid/fdroid/installer/PrivilegedInstaller.java b/app/src/main/java/org/fdroid/fdroid/installer/PrivilegedInstaller.java index b1a3143d2..9792c9813 100644 --- a/app/src/main/java/org/fdroid/fdroid/installer/PrivilegedInstaller.java +++ b/app/src/main/java/org/fdroid/fdroid/installer/PrivilegedInstaller.java @@ -41,16 +41,21 @@ import org.fdroid.fdroid.privileged.IPrivilegedService; import java.util.HashMap; /** - * Installer based on using internal hidden APIs of the Android OS, which are - * protected by the permissions - *

+ * Installer that only works if the "F-Droid Privileged + * Extension" is installed as a privileged app. *

+ * "F-Droid Privileged Extension" provides a service that exposes + * internal Android APIs for install/uninstall which are protected + * by INSTALL_PACKAGES, DELETE_PACKAGES permissions. * Both permissions are protected by systemOrSignature (in newer versions: - * system|signature). Thus, this installer works only when the "F-Droid Privileged - * Extension" is installed into the system. + * system|signature) and cannot be used directly by F-Droid. + *

+ * Instead, this installer binds to the service of + * "F-Droid Privileged Extension" and then executes the appropriate methods + * inside the privileged context of the privileged extension. + *

+ * This installer makes unattended installs/uninstalls possible. + * Thus no PendingIntents are returned. *

* Sources for Android 4.4 change: * https://groups.google.com/forum/#!msg/android- @@ -268,7 +273,6 @@ public class PrivilegedInstaller extends Installer { } public static int isExtensionInstalledCorrectly(Context context) { - // check if installed if (!isExtensionInstalled(context)) { return IS_EXTENSION_INSTALLED_NO;