* See the individual types documentation for details. * @@ -359,7 +358,9 @@ public class PackageInstaller { * Streaming installation using Incremental FileSystem. * * @see #EXTRA_DATA_LOADER_TYPE + * @hide */ + @SystemApi public static final int DATA_LOADER_TYPE_INCREMENTAL = DataLoaderType.INCREMENTAL; /** @@ -1165,7 +1166,7 @@ public class PackageInstaller { } /** - * Adds a file to session. On commit this file will be pulled from dataLoader {@code + * Adds a file to session. On commit this file will be pulled from DataLoader {@code * android.service.dataloader.DataLoaderService.DataLoader}. * * @param location target location for the file. Possible values: @@ -1180,7 +1181,7 @@ public class PackageInstaller { * @param lengthBytes total size of the file being written. * The system may clear various caches as needed to allocate * this space. - * @param metadata additional info use by dataLoader to pull data for the file. + * @param metadata additional info use by DataLoader to pull data for the file. * @param signature additional file signature, e.g. * APK Signature Scheme v4 * @throws SecurityException if called after the session has been @@ -2021,7 +2022,7 @@ public class PackageInstaller { /** * Set the data loader params for the session. - * This also switches installation into data provider mode and disallow direct writes into + * This also switches installation into data loading mode and disallow direct writes into * staging folder. * * @see android.service.dataloader.DataLoaderService.DataLoader diff --git a/core/java/android/service/dataloader/DataLoaderService.java b/core/java/android/service/dataloader/DataLoaderService.java index 3ad80d3e97fac..63ec252c2fa80 100644 --- a/core/java/android/service/dataloader/DataLoaderService.java +++ b/core/java/android/service/dataloader/DataLoaderService.java @@ -39,24 +39,35 @@ import java.io.IOException; import java.util.Collection; /** - * The base class for implementing data loader service to control data loaders. Expecting - * Installation Session to bind to a children class of this. + * The base class for implementing a data loader service. + *
+ * After calling commit() on the install session, the DataLoaderService is started and bound to
+ * provide the actual data bytes for the streaming session.
+ * The service will automatically be rebound until the streaming session has enough data to
+ * proceed with the installation.
+ *
+ * @see android.content.pm.DataLoaderParams
+ * @see android.content.pm.PackageInstaller.SessionParams#setDataLoaderParams
*/
public abstract class DataLoaderService extends Service {
private static final String TAG = "DataLoaderService";
private final DataLoaderBinderService mBinder = new DataLoaderBinderService();
/**
- * Managed DataLoader interface. Each instance corresponds to a single installation session.
+ * DataLoader interface. Each instance corresponds to a single installation session.
*/
public interface DataLoader {
/**
* A virtual constructor.
*
* @param dataLoaderParams parameters set in the installation session
- * @param connector FS API wrapper
- * @return True if initialization of a Data Loader was successful. False will be reported to
- * PackageManager and fail the installation
+ * {@link android.content.pm.PackageInstaller.SessionParams#setDataLoaderParams}
+ * @param connector Wrapper providing access to the installation image.
+ * @return true if initialization of a DataLoader was successful. False will notify the
+ * Installer {@link android.content.pm.PackageInstaller#STATUS_PENDING_STREAMING} and
+ * interrupt the session commit. The Installer is supposed to make sure DataLoader can
+ * proceed and then commit the session
+ * {@link android.content.pm.PackageInstaller.Session#commit}.
*/
boolean onCreate(@NonNull DataLoaderParams dataLoaderParams,
@NonNull FileSystemConnector connector);
@@ -64,10 +75,35 @@ public abstract class DataLoaderService extends Service {
/**
* Prepare installation image. After this method succeeds installer will validate the files
* and continue installation.
+ * The method should block until the files are prepared for installation.
+ * This can take up to session lifetime (~day). If the session lifetime is exceeded then
+ * any attempts to write new data will fail.
*
- * @param addedFiles list of files created in this installation session.
- * @param removedFiles list of files removed in this installation session.
- * @return false if unable to create and populate all addedFiles.
+ * Example implementation:
+ *
+ * String localPath = "/data/local/tmp/base.apk";
+ * session.addFile(LOCATION_DATA_APP, "base", 123456, localPath.getBytes(UTF_8), null);
+ * ...
+ * // onPrepareImage
+ * for (InstallationFile file : addedFiles) {
+ * String localPath = new String(file.getMetadata(), UTF_8);
+ * File source = new File(localPath);
+ * ParcelFileDescriptor fd = ParcelFileDescriptor.open(source, MODE_READ_ONLY);
+ * try {
+ * mConnector.writeData(file.getName(), 0, fd.getStatSize(), fd);
+ * } finally {
+ * IoUtils.closeQuietly(fd);
+ * }
+ * }
+ *
+ * It is recommended to stream data into installation session directly from source, e.g.
+ * cloud data storage, to save local disk space.
+ *
+ * @param addedFiles list of files created in this installation session
+ * {@link android.content.pm.PackageInstaller.Session#addFile}
+ * @param removedFiles list of files removed in this installation session
+ * {@link android.content.pm.PackageInstaller.Session#removeFile}
+ * @return false if unable to create and populate all addedFiles. Installation will fail.
*/
boolean onPrepareImage(@NonNull Collection