From f33024a144daf5a717029e38f7968bd77f799d99 Mon Sep 17 00:00:00 2001 From: Sudheer Shanka Date: Wed, 22 Jan 2020 15:26:15 -0800 Subject: Expand BlobStoreManager javadocs. Bug: 143559646 Test: make -j offline-sdk-docs Change-Id: Ia5c3f3143efdfd4c99fd184f63f481792ef2085c --- .../java/android/app/blob/BlobStoreManager.java | 96 +++++++++++++++++++++- 1 file changed, 92 insertions(+), 4 deletions(-) diff --git a/apex/blobstore/framework/java/android/app/blob/BlobStoreManager.java b/apex/blobstore/framework/java/android/app/blob/BlobStoreManager.java index 47af7c0a5ed9..6d0644da099a 100644 --- a/apex/blobstore/framework/java/android/app/blob/BlobStoreManager.java +++ b/apex/blobstore/framework/java/android/app/blob/BlobStoreManager.java @@ -37,11 +37,99 @@ import java.util.function.Consumer; /** * This class provides access to the blob store managed by the system. * - * Apps can publish data blobs which might be useful for other apps on the device to be - * managed by the system and apps that would like to access these data blobs can do so - * by addressing them via their cryptographically secure hashes. + *

Apps can publish and access a data blob using a {@link BlobHandle} object which can + * be created with {@link BlobHandle#createWithSha256(byte[], CharSequence, long, String)}. + * This {@link BlobHandle} object encapsulates the following pieces of information used for + * identifying the blobs: + *

+ * For two {@link BlobHandle} objects to be considered identical, all these pieces of information + * must be equal. * - * TODO: More documentation. + *

For contributing a new data blob, an app needs to create a session using + * {@link BlobStoreManager#createSession(BlobHandle)} and then open this session for writing using + * {@link BlobStoreManager#openSession(long)}. + * + *

The following code snippet shows how to create and open a session for writing: + * 

+ *     final long sessionId = blobStoreManager.createSession(blobHandle);
+ *     try (BlobStoreManager.Session session = blobStoreManager.openSession(sessionId)) {
+ *         try (ParcelFileDescriptor pfd = new ParcelFileDescriptor.AutoCloseOutputStream(
+ *                 session.openWrite(offsetBytes, lengthBytes))) {
+ *             writeData(pfd);
+ *         }
+ *     }
+ *
+ * + *

If all the data could not be written in a single attempt, apps can close this session + * and re-open it again using the session id obtained via + * {@link BlobStoreManager#createSession(BlobHandle)}. Note that the session data is persisted + * and can be re-opened for completing the data contribution, even across device reboots. + * + *

After the data is written to the session, it can be committed using + * {@link Session#commit(Executor, Consumer)}. Until the session is committed, data written + * to the session will not be shared with any app. + * + *

Once a session is committed using {@link Session#commit(Executor, Consumer)}, + * any data written as part of this session is sealed and cannot be modified anymore. + * + *

Before committing the session, apps can indicate which apps are allowed to access the + * contributed data using one or more of the following access modes: + *

+ * + *

The following code snippet shows how to specify the access mode and commit the session: + * 

+ *     try (BlobStoreManager.Session session = blobStoreManager.openSession(sessionId)) {
+ *         try (ParcelFileDescriptor pfd = new ParcelFileDescriptor.AutoCloseOutputStream(
+ *                 session.openWrite(offsetBytes, lengthBytes))) {
+ *             writeData(pfd);
+ *         }
+ *         session.allowSameSignatureAccess();
+ *         session.allowPackageAccess(packageName, certificate);
+ *         session.commit(executor, callback);
+ *     }
+ *
+ * + *

Apps that satisfy at least one of the access mode constraints specified by the publisher + * of the data blob will be able to access it. + * + *

A data blob published without specifying any of + * these access modes will be considered private and only the app that contributed the data + * blob will be allowed to access it. This is still useful for overall device system health as + * the System can try to keep one copy of data blob on disk when multiple apps contribute the + * same data. + * + *

It is strongly recommended that apps use one of + * {@link Session#allowPackageAccess(String, byte[])} or {@link Session#allowSameSignatureAccess()} + * when they know, ahead of time, the set of apps they would like to share the blobs with. + * {@link Session#allowPublicAccess()} is meant for publicly available data committed from + * libraries and SDKs. + * + *

Once a data blob is committed with {@link Session#commit(Executor, Consumer)}, it + * can be accessed using {@link BlobStoreManager#openBlob(BlobHandle)}, assuming the caller + * satisfies constraints of any of the access modes associated with that data blob. An app may + * acquire a lease on a blob with {@link BlobStoreManager#acquireLease(BlobHandle, int)} and + * release the lease with {@link BlobStoreManager#releaseLease(BlobHandle)}. A blob will not be + * deleted from the system while there is at least one app leasing it. + * + *

The following code snippet shows how to access the data blob: + * 

+ *     try (ParcelFileDescriptor pfd = new ParcelFileDescriptor.AutoCloseInputStream(
+ *             blobStoreManager.openBlob(blobHandle)) {
+ *         useData(pfd);
+ *     }
+ *
*/ @SystemService(Context.BLOB_STORE_SERVICE) public class BlobStoreManager { -- cgit v1.2.3-59-g8ed1b