A "blob" is a large binary object. It is used to store a significant amount of data that is * not searchable, such as images, videos, audio files, or other binary data. Unlike other fields in * AppSearch, blobs are stored as blob files on disk rather than in memory, and use {@link * android.os.ParcelFileDescriptor} to read and write. This allows for efficient handling of large, * non-searchable content. * *
{@link AppSearchBlobHandle} is a light-weight {@code Property} of {@link GenericDocument}, * which is a pointer to the heavy-weight blob data. * *
The blob data could be written via {@link AppSearchSession#openBlobForWrite} and read via * {@link AppSearchSession#openBlobForRead}. * *
A {@link GenericDocument} with {@link AppSearchBlobHandle} {@code Property} could be put and
* read without the large blob data. This offers lazy retrieval to blob data when searching {@link
* GenericDocument} in AppSearch.
*
* @see GenericDocument.Builder#setPropertyBlobHandle
*/
@FlaggedApi(Flags.FLAG_ENABLE_BLOB_STORE)
// TODO(b/384721898): Switch to JSpecify annotations
@SuppressWarnings({"HiddenSuperclass", "JSpecifyNullness"})
@SafeParcelable.Class(creator = "AppSearchBlobHandleCreator")
public final class AppSearchBlobHandle extends AbstractSafeParcelable {
/** The length of the SHA-256 digest in bytes. SHA-256 produces a 256-bit (32-byte) digest. */
private static final int SHA_256_DIGEST_BYTE_LENGTH = 32;
@NonNull
public static final Parcelable.Creator For two objects of {@link AppSearchBlobHandle} to be considered equal, the {@code
* packageName}, {@code database}, {@code namespace} and {@code digest} must be equal.
*/
public @NonNull byte[] getSha256Digest() {
return mSha256Digest;
}
/**
* Returns the package name indicating the owner app of the blob that this object is
* representing.
*
* For two objects of {@link AppSearchBlobHandle} to be considered equal, the {@code
* packageName}, {@code database}, {@code namespace} and {@code digest} must be equal.
*/
public @NonNull String getPackageName() {
return mPackageName;
}
/**
* Returns the name of database stored the blob that this object is representing.
*
* For two objects of {@link AppSearchBlobHandle} to be considered equal, the {@code
* packageName}, {@code database}, {@code namespace} and {@code digest} must be equal.
*/
public @NonNull String getDatabaseName() {
return mDatabaseName;
}
/**
* Returns the app-defined namespace this blob resides in.
*
* For two objects of {@link AppSearchBlobHandle} to be considered equal, the {@code
* packageName}, {@code database}, {@code namespace} and {@code digest} must be equal.
*/
public @NonNull String getNamespace() {
return mNamespace;
}
@Override
public boolean equals(@Nullable Object o) {
if (this == o) {
return true;
}
if (!(o instanceof AppSearchBlobHandle)) {
return false;
}
AppSearchBlobHandle that = (AppSearchBlobHandle) o;
if (!Arrays.equals(mSha256Digest, that.mSha256Digest)) {
return false;
}
return mPackageName.equals(that.mPackageName)
&& mDatabaseName.equals(that.mDatabaseName)
&& mNamespace.equals(that.mNamespace);
}
@Override
public int hashCode() {
if (mHashCode == null) {
mHashCode =
Objects.hash(
Arrays.hashCode(mSha256Digest),
mPackageName,
mDatabaseName,
mNamespace);
}
return mHashCode;
}
@Override
public @NonNull String toString() {
IndentingStringBuilder builder = new IndentingStringBuilder();
builder.append("{\n");
builder.increaseIndentLevel();
builder.append("packageName: \"").append(mPackageName).append("\",\n");
builder.append("databaseName: \"").append(mDatabaseName).append("\",\n");
builder.append("namespace: \"").append(mNamespace).append("\",\n");
builder.append("digest: \"");
for (byte b : mSha256Digest) {
String hex = Integer.toHexString(0xFF & b);
if (hex.length() == 1) {
builder.append('0');
}
builder.append(hex);
}
builder.append("\",\n").decreaseIndentLevel();
builder.append("}");
return builder.toString();
}
/**
* Create a new AppSearch blob identifier with given digest, package, database and namespace.
*
* The package name and database name indicated where this blob will be stored. To write,
* commit or read this blob via {@link AppSearchSession}, it must match the package name and
* database name of {@link AppSearchSession}.
*
* For two objects of {@link AppSearchBlobHandle} to be considered equal, the {@code
* packageName}, {@code database}, {@code namespace} and {@code digest} must be equal.
*
* @param digest The SHA-256 hash of the blob this is representing.
* @param packageName The package name of the owner of this Blob.
* @param databaseName The database name of this blob to stored into.
* @param namespace The namespace of this blob resides in.
* @return a new instance of {@link AppSearchBlobHandle} object.
*/
public static @NonNull AppSearchBlobHandle createWithSha256(
@NonNull byte[] digest,
@NonNull String packageName,
@NonNull String databaseName,
@NonNull String namespace) {
Objects.requireNonNull(digest);
Preconditions.checkArgument(
digest.length == SHA_256_DIGEST_BYTE_LENGTH, "The digest is not a SHA-256 digest");
Objects.requireNonNull(packageName);
Objects.requireNonNull(databaseName);
Objects.requireNonNull(namespace);
return new AppSearchBlobHandle(digest, packageName, databaseName, namespace);
}
@Override
public void writeToParcel(@NonNull Parcel dest, int flags) {
AppSearchBlobHandleCreator.writeToParcel(this, dest, flags);
}
}