Never create two instances using the same folder. * *
A single instance of {@link AppSearchImpl} can support all packages and databases. This is * done by combining the package and database name into a unique prefix and prefixing the schemas * and documents stored under that owner. Schemas and documents are physically saved together in * {@link IcingSearchEngine}, but logically isolated: * *
Methods in this class belong to two groups, the query group and the mutate group. * *
This class is thread safe.
*
* @hide
*/
@WorkerThread
public final class AppSearchImpl implements Closeable {
private static final String TAG = "AppSearchImpl";
/** A value 0 means that there're no more pages in the search results. */
private static final long EMPTY_PAGE_TOKEN = 0;
@VisibleForTesting static final int CHECK_OPTIMIZE_INTERVAL = 100;
/** A GetResultSpec that uses projection to skip all properties. */
private static final GetResultSpecProto GET_RESULT_SPEC_NO_PROPERTIES =
GetResultSpecProto.newBuilder()
.addTypePropertyMasks(
TypePropertyMask.newBuilder()
.setSchemaType(
GetByDocumentIdRequest.PROJECTION_SCHEMA_TYPE_WILDCARD))
.build();
private final ReadWriteLock mReadWriteLock = new ReentrantReadWriteLock();
private final OptimizeStrategy mOptimizeStrategy;
private final AppSearchConfig mConfig;
@GuardedBy("mReadWriteLock")
@VisibleForTesting
final IcingSearchEngine mIcingSearchEngineLocked;
@GuardedBy("mReadWriteLock")
private final SchemaCache mSchemaCacheLocked = new SchemaCache();
// This map contains namespaces for all package-database prefixes. All values in the map are
// prefixed with the package-database prefix.
// TODO(b/172360376): Check if this can be replaced with an ArrayMap
@GuardedBy("mReadWriteLock")
private final Map Clients can pass a {@link AppSearchLogger} here through their AppSearchSession, but it
* can't be saved inside {@link AppSearchImpl}, because the impl will be shared by all the
* sessions for the same package in JetPack.
*
* Instead, logger instance needs to be passed to each individual method, like create, query
* and putDocument.
*
* @param initStatsBuilder collects stats for initialization if provided.
* @param visibilityChecker The {@link VisibilityChecker} that check whether the caller has
* access to aa specific schema. Pass null will lost that ability and global querier could
* only get their own data.
*/
@NonNull
public static AppSearchImpl create(
@NonNull File icingDir,
@NonNull AppSearchConfig config,
@Nullable InitializeStats.Builder initStatsBuilder,
@Nullable VisibilityChecker visibilityChecker,
@NonNull OptimizeStrategy optimizeStrategy)
throws AppSearchException {
return new AppSearchImpl(
icingDir, config, initStatsBuilder, optimizeStrategy, visibilityChecker);
}
/**
* @param initStatsBuilder collects stats for initialization if provided.
*/
private AppSearchImpl(
@NonNull File icingDir,
@NonNull AppSearchConfig config,
@Nullable InitializeStats.Builder initStatsBuilder,
@NonNull OptimizeStrategy optimizeStrategy,
@Nullable VisibilityChecker visibilityChecker)
throws AppSearchException {
Objects.requireNonNull(icingDir);
mConfig = Objects.requireNonNull(config);
mOptimizeStrategy = Objects.requireNonNull(optimizeStrategy);
mVisibilityCheckerLocked = visibilityChecker;
mReadWriteLock.writeLock().lock();
try {
// We synchronize here because we don't want to call IcingSearchEngine.initialize() more
// than once. It's unnecessary and can be a costly operation.
IcingSearchEngineOptions options =
IcingSearchEngineOptions.newBuilder()
.setBaseDir(icingDir.getAbsolutePath())
.setMaxTokenLength(mConfig.getMaxTokenLength())
.setIndexMergeSize(mConfig.getIndexMergeSize())
.setDocumentStoreNamespaceIdFingerprint(
mConfig.getDocumentStoreNamespaceIdFingerprint())
.setOptimizeRebuildIndexThreshold(
mConfig.getOptimizeRebuildIndexThreshold())
.setCompressionLevel(mConfig.getCompressionLevel())
.setAllowCircularSchemaDefinitions(
mConfig.getAllowCircularSchemaDefinitions())
.setPreMappingFbv(mConfig.getUsePreMappingWithFileBackedVector())
.setUsePersistentHashMap(mConfig.getUsePersistentHashMap())
.setIntegerIndexBucketSplitThreshold(
mConfig.getIntegerIndexBucketSplitThreshold())
.setLiteIndexSortAtIndexing(mConfig.getLiteIndexSortAtIndexing())
.setLiteIndexSortSize(mConfig.getLiteIndexSortSize())
.setUseNewQualifiedIdJoinIndex(mConfig.getUseNewQualifiedIdJoinIndex())
.setBuildPropertyExistenceMetadataHits(
mConfig.getBuildPropertyExistenceMetadataHits())
.build();
LogUtil.piiTrace(TAG, "Constructing IcingSearchEngine, request", options);
mIcingSearchEngineLocked = new IcingSearchEngine(options);
LogUtil.piiTrace(
TAG,
"Constructing IcingSearchEngine, response",
Objects.hashCode(mIcingSearchEngineLocked));
// The core initialization procedure. If any part of this fails, we bail into
// resetLocked(), deleting all data (but hopefully allowing AppSearchImpl to come up).
try {
LogUtil.piiTrace(TAG, "icingSearchEngine.initialize, request");
InitializeResultProto initializeResultProto = mIcingSearchEngineLocked.initialize();
LogUtil.piiTrace(
TAG,
"icingSearchEngine.initialize, response",
initializeResultProto.getStatus(),
initializeResultProto);
if (initStatsBuilder != null) {
initStatsBuilder
.setStatusCode(
statusProtoToResultCode(initializeResultProto.getStatus()))
// TODO(b/173532925) how to get DeSyncs value
.setHasDeSync(false);
AppSearchLoggerHelper.copyNativeStats(
initializeResultProto.getInitializeStats(), initStatsBuilder);
}
checkSuccess(initializeResultProto.getStatus());
// Read all protos we need to construct AppSearchImpl's cache maps
long prepareSchemaAndNamespacesLatencyStartMillis = SystemClock.elapsedRealtime();
SchemaProto schemaProto = getSchemaProtoLocked();
LogUtil.piiTrace(TAG, "init:getAllNamespaces, request");
GetAllNamespacesResultProto getAllNamespacesResultProto =
mIcingSearchEngineLocked.getAllNamespaces();
LogUtil.piiTrace(
TAG,
"init:getAllNamespaces, response",
getAllNamespacesResultProto.getNamespacesCount(),
getAllNamespacesResultProto);
StorageInfoProto storageInfoProto = getRawStorageInfoProto();
// Log the time it took to read the data that goes into the cache maps
if (initStatsBuilder != null) {
// In case there is some error for getAllNamespaces, we can still
// set the latency for preparation.
// If there is no error, the value will be overridden by the actual one later.
initStatsBuilder
.setStatusCode(
statusProtoToResultCode(
getAllNamespacesResultProto.getStatus()))
.setPrepareSchemaAndNamespacesLatencyMillis(
(int)
(SystemClock.elapsedRealtime()
- prepareSchemaAndNamespacesLatencyStartMillis));
}
checkSuccess(getAllNamespacesResultProto.getStatus());
// Populate schema map
List This instance is no longer usable after it's been closed. Call {@link #create} to create a
* new, usable instance.
*/
@Override
public void close() {
mReadWriteLock.writeLock().lock();
try {
if (mClosedLocked) {
return;
}
persistToDisk(PersistType.Code.FULL);
LogUtil.piiTrace(TAG, "icingSearchEngine.close, request");
mIcingSearchEngineLocked.close();
LogUtil.piiTrace(TAG, "icingSearchEngine.close, response");
mClosedLocked = true;
} catch (AppSearchException e) {
Log.w(TAG, "Error when closing AppSearchImpl.", e);
} finally {
mReadWriteLock.writeLock().unlock();
}
}
/**
* Updates the AppSearch schema for this app.
*
* This method belongs to mutate group.
*
* @param packageName The package name that owns the schemas.
* @param databaseName The name of the database where this schema lives.
* @param schemas Schemas to set for this app.
* @param visibilityConfigs {@link InternalVisibilityConfig}s that contain all visibility
* setting information for those schemas has user custom settings. Other schemas in the list
* that don't has a {@link InternalVisibilityConfig} will be treated as having the default
* visibility, which is accessible by the system and no other packages.
* @param forceOverride Whether to force-apply the schema even if it is incompatible. Documents
* which do not comply with the new schema will be deleted.
* @param version The overall version number of the request.
* @param setSchemaStatsBuilder Builder for {@link SetSchemaStats} to hold stats for setSchema
* @return A success {@link InternalSetSchemaResponse} with a {@link SetSchemaResponse}. Or a
* failed {@link InternalSetSchemaResponse} if this call contains incompatible change. The
* {@link SetSchemaResponse} in the failed {@link InternalSetSchemaResponse} contains which
* type is incompatible. You need to check the status by {@link
* InternalSetSchemaResponse#isSuccess()}.
* @throws AppSearchException On IcingSearchEngine error. If the status code is
* FAILED_PRECONDITION for the incompatible change, the exception will be converted to the
* SetSchemaResponse.
*/
@NonNull
public InternalSetSchemaResponse setSchema(
@NonNull String packageName,
@NonNull String databaseName,
@NonNull List This method can be used only when no one is observing {@code packageName}.
*
* @see #setSchema
* @see #doSetSchemaWithChangeNotificationLocked
*/
@GuardedBy("mReadWriteLock")
@NonNull
private InternalSetSchemaResponse doSetSchemaNoChangeNotificationLocked(
@NonNull String packageName,
@NonNull String databaseName,
@NonNull List This method belongs to query group.
*
* @param packageName Package that owns the requested {@link AppSearchSchema} instances.
* @param databaseName Database that owns the requested {@link AppSearchSchema} instances.
* @param callerAccess Visibility access info of the calling app
* @throws AppSearchException on IcingSearchEngine error.
*/
@NonNull
public GetSchemaResponse getSchema(
@NonNull String packageName,
@NonNull String databaseName,
@NonNull CallerAccess callerAccess)
throws AppSearchException {
mReadWriteLock.readLock().lock();
try {
throwIfClosedLocked();
SchemaProto fullSchema = getSchemaProtoLocked();
String prefix = createPrefix(packageName, databaseName);
GetSchemaResponse.Builder responseBuilder = new GetSchemaResponse.Builder();
for (int i = 0; i < fullSchema.getTypesCount(); i++) {
// Check that this type belongs to the requested app and that the caller has
// access to it.
SchemaTypeConfigProto typeConfig = fullSchema.getTypes(i);
String prefixedSchemaType = typeConfig.getSchemaType();
String typePrefix = getPrefix(prefixedSchemaType);
if (!prefix.equals(typePrefix)) {
// This schema type doesn't belong to the database we're querying for.
continue;
}
if (!VisibilityUtil.isSchemaSearchableByCaller(
callerAccess,
packageName,
prefixedSchemaType,
mVisibilityStoreLocked,
mVisibilityCheckerLocked)) {
// Caller doesn't have access to this type.
continue;
}
// Rewrite SchemaProto.types.schema_type
SchemaTypeConfigProto.Builder typeConfigBuilder = typeConfig.toBuilder();
PrefixUtil.removePrefixesFromSchemaType(typeConfigBuilder);
AppSearchSchema schema =
SchemaToProtoConverter.toAppSearchSchema(typeConfigBuilder);
responseBuilder.setVersion(typeConfig.getVersion());
responseBuilder.addSchema(schema);
// Populate visibility info. Since the constructor of VisibilityStore will get
// schema. Avoid call visibility store before we have already created it.
if (mVisibilityStoreLocked != null) {
String typeName = typeConfig.getSchemaType().substring(typePrefix.length());
InternalVisibilityConfig visibilityConfig =
mVisibilityStoreLocked.getVisibility(prefixedSchemaType);
if (visibilityConfig != null) {
if (visibilityConfig.isNotDisplayedBySystem()) {
responseBuilder.addSchemaTypeNotDisplayedBySystem(typeName);
}
List This method belongs to query group.
*
* @param packageName Package name that owns this schema
* @param databaseName The name of the database where this schema lives.
* @throws AppSearchException on IcingSearchEngine error.
*/
@NonNull
public List This method belongs to mutate group.
*
* @param packageName The package name that owns this document.
* @param databaseName The databaseName this document resides in.
* @param document The document to index.
* @param sendChangeNotifications Whether to dispatch {@link
* android.app.appsearch.observer.DocumentChangeInfo} messages to observers for this change.
* @throws AppSearchException on IcingSearchEngine error.
*/
public void putDocument(
@NonNull String packageName,
@NonNull String databaseName,
@NonNull GenericDocument document,
boolean sendChangeNotifications,
@Nullable AppSearchLogger logger)
throws AppSearchException {
PutDocumentStats.Builder pStatsBuilder = null;
if (logger != null) {
pStatsBuilder = new PutDocumentStats.Builder(packageName, databaseName);
}
long totalStartTimeMillis = SystemClock.elapsedRealtime();
mReadWriteLock.writeLock().lock();
try {
throwIfClosedLocked();
// Generate Document Proto
long generateDocumentProtoStartTimeMillis = SystemClock.elapsedRealtime();
DocumentProto.Builder documentBuilder =
GenericDocumentToProtoConverter.toDocumentProto(document).toBuilder();
long generateDocumentProtoEndTimeMillis = SystemClock.elapsedRealtime();
// Rewrite Document Type
long rewriteDocumentTypeStartTimeMillis = SystemClock.elapsedRealtime();
String prefix = createPrefix(packageName, databaseName);
addPrefixToDocument(documentBuilder, prefix);
long rewriteDocumentTypeEndTimeMillis = SystemClock.elapsedRealtime();
DocumentProto finalDocument = documentBuilder.build();
// Check limits
int newDocumentCount =
enforceLimitConfigLocked(
packageName, finalDocument.getUri(), finalDocument.getSerializedSize());
// Insert document
LogUtil.piiTrace(TAG, "putDocument, request", finalDocument.getUri(), finalDocument);
PutResultProto putResultProto = mIcingSearchEngineLocked.put(finalDocument);
LogUtil.piiTrace(
TAG, "putDocument, response", putResultProto.getStatus(), putResultProto);
// Logging stats
if (pStatsBuilder != null) {
pStatsBuilder
.setStatusCode(statusProtoToResultCode(putResultProto.getStatus()))
.setGenerateDocumentProtoLatencyMillis(
(int)
(generateDocumentProtoEndTimeMillis
- generateDocumentProtoStartTimeMillis))
.setRewriteDocumentTypesLatencyMillis(
(int)
(rewriteDocumentTypeEndTimeMillis
- rewriteDocumentTypeStartTimeMillis));
AppSearchLoggerHelper.copyNativeStats(
putResultProto.getPutDocumentStats(), pStatsBuilder);
}
checkSuccess(putResultProto.getStatus());
// Only update caches if the document is successfully put to Icing.
addToMap(mNamespaceMapLocked, prefix, finalDocument.getNamespace());
mDocumentCountMapLocked.put(packageName, newDocumentCount);
// Prepare notifications
if (sendChangeNotifications) {
mObserverManager.onDocumentChange(
packageName,
databaseName,
document.getNamespace(),
document.getSchemaType(),
document.getId(),
mVisibilityStoreLocked,
mVisibilityCheckerLocked);
}
} finally {
mReadWriteLock.writeLock().unlock();
if (pStatsBuilder != null && logger != null) {
long totalEndTimeMillis = SystemClock.elapsedRealtime();
pStatsBuilder.setTotalLatencyMillis(
(int) (totalEndTimeMillis - totalStartTimeMillis));
logger.logStats(pStatsBuilder.build());
}
}
}
/**
* Checks that a new document can be added to the given packageName with the given serialized
* size without violating our {@link LimitConfig}.
*
* @return the new count of documents for the given package, including the new document.
* @throws AppSearchException with a code of {@link AppSearchResult#RESULT_OUT_OF_SPACE} if the
* limits are violated by the new document.
*/
@GuardedBy("mReadWriteLock")
private int enforceLimitConfigLocked(String packageName, String newDocUri, int newDocSize)
throws AppSearchException {
// Limits check: size of document
if (newDocSize > mConfig.getMaxDocumentSizeBytes()) {
throw new AppSearchException(
AppSearchResult.RESULT_OUT_OF_SPACE,
"Document \""
+ newDocUri
+ "\" for package \""
+ packageName
+ "\" serialized to "
+ newDocSize
+ " bytes, which exceeds "
+ "limit of "
+ mConfig.getMaxDocumentSizeBytes()
+ " bytes");
}
// Limits check: number of documents
Integer oldDocumentCount = mDocumentCountMapLocked.get(packageName);
int newDocumentCount;
if (oldDocumentCount == null) {
newDocumentCount = 1;
} else {
newDocumentCount = oldDocumentCount + 1;
}
if (newDocumentCount > mConfig.getMaxDocumentCount()) {
// Our management of mDocumentCountMapLocked doesn't account for document
// replacements, so our counter might have overcounted if the app has replaced docs.
// Rebuild the counter from StorageInfo in case this is so.
// TODO(b/170371356): If Icing lib exposes something in the result which says
// whether the document was a replacement, we could subtract 1 again after the put
// to keep the count accurate. That would allow us to remove this code.
rebuildDocumentCountMapLocked(getRawStorageInfoProto());
oldDocumentCount = mDocumentCountMapLocked.get(packageName);
if (oldDocumentCount == null) {
newDocumentCount = 1;
} else {
newDocumentCount = oldDocumentCount + 1;
}
}
if (newDocumentCount > mConfig.getMaxDocumentCount()) {
// Now we really can't fit it in, even accounting for replacements.
throw new AppSearchException(
AppSearchResult.RESULT_OUT_OF_SPACE,
"Package \""
+ packageName
+ "\" exceeded limit of "
+ mConfig.getMaxDocumentCount()
+ " documents. Some documents "
+ "must be removed to index additional ones.");
}
return newDocumentCount;
}
/**
* Retrieves a document from the AppSearch index by namespace and document ID from any
* application the caller is allowed to view
*
* This method will handle both Icing engine errors as well as permission errors by throwing
* an obfuscated RESULT_NOT_FOUND exception. This is done so the caller doesn't receive
* information on whether or not a file they are not allowed to access exists or not. This is
* different from the behavior of {@link #getDocument}.
*
* @param packageName The package that owns this document.
* @param databaseName The databaseName this document resides in.
* @param namespace The namespace this document resides in.
* @param id The ID of the document to get.
* @param typePropertyPaths A map of schema type to a list of property paths to return in the
* result.
* @param callerAccess Visibility access info of the calling app
* @return The Document contents
* @throws AppSearchException on IcingSearchEngine error or invalid permissions
*/
@NonNull
public GenericDocument globalGetDocument(
@NonNull String packageName,
@NonNull String databaseName,
@NonNull String namespace,
@NonNull String id,
@NonNull Map This method belongs to query group.
*
* @param packageName The package that owns this document.
* @param databaseName The databaseName this document resides in.
* @param namespace The namespace this document resides in.
* @param id The ID of the document to get.
* @param typePropertyPaths A map of schema type to a list of property paths to return in the
* result.
* @return The Document contents
* @throws AppSearchException on IcingSearchEngine error.
*/
@NonNull
public GenericDocument getDocument(
@NonNull String packageName,
@NonNull String databaseName,
@NonNull String namespace,
@NonNull String id,
@NonNull Map This method belongs to query group.
*
* @param packageName The package name that is performing the query.
* @param databaseName The databaseName this query for.
* @param queryExpression Query String to search.
* @param searchSpec Spec for setting filters, raw query etc.
* @param logger logger to collect query stats
* @return The results of performing this search. It may contain an empty list of results if no
* documents matched the query.
* @throws AppSearchException on IcingSearchEngine error.
*/
@NonNull
public SearchResultPage query(
@NonNull String packageName,
@NonNull String databaseName,
@NonNull String queryExpression,
@NonNull SearchSpec searchSpec,
@Nullable AppSearchLogger logger)
throws AppSearchException {
long totalLatencyStartMillis = SystemClock.elapsedRealtime();
SearchStats.Builder sStatsBuilder = null;
if (logger != null) {
sStatsBuilder =
new SearchStats.Builder(SearchStats.VISIBILITY_SCOPE_LOCAL, packageName)
.setDatabase(databaseName)
.setSearchSourceLogTag(searchSpec.getSearchSourceLogTag());
}
long javaLockAcquisitionLatencyStartMillis = SystemClock.elapsedRealtime();
mReadWriteLock.readLock().lock();
try {
if (sStatsBuilder != null) {
sStatsBuilder.setJavaLockAcquisitionLatencyMillis(
(int)
(SystemClock.elapsedRealtime()
- javaLockAcquisitionLatencyStartMillis));
}
throwIfClosedLocked();
List This method belongs to query group.
*
* @param queryExpression Query String to search.
* @param searchSpec Spec for setting filters, raw query etc.
* @param callerAccess Visibility access info of the calling app
* @param logger logger to collect globalQuery stats
* @return The results of performing this search. It may contain an empty list of results if no
* documents matched the query.
* @throws AppSearchException on IcingSearchEngine error.
*/
@NonNull
public SearchResultPage globalQuery(
@NonNull String queryExpression,
@NonNull SearchSpec searchSpec,
@NonNull CallerAccess callerAccess,
@Nullable AppSearchLogger logger)
throws AppSearchException {
long totalLatencyStartMillis = SystemClock.elapsedRealtime();
SearchStats.Builder sStatsBuilder = null;
if (logger != null) {
sStatsBuilder =
new SearchStats.Builder(
SearchStats.VISIBILITY_SCOPE_GLOBAL,
callerAccess.getCallingPackageName())
.setSearchSourceLogTag(searchSpec.getSearchSourceLogTag());
}
long javaLockAcquisitionLatencyStartMillis = SystemClock.elapsedRealtime();
mReadWriteLock.readLock().lock();
try {
if (sStatsBuilder != null) {
sStatsBuilder.setJavaLockAcquisitionLatencyMillis(
(int)
(SystemClock.elapsedRealtime()
- javaLockAcquisitionLatencyStartMillis));
}
throwIfClosedLocked();
long aclLatencyStartMillis = SystemClock.elapsedRealtime();
// The two scenarios where we want to limit package filters are if the outer
// SearchSpec has package filters and there is no JoinSpec, or if both outer and
// nested SearchSpecs have package filters. If outer SearchSpec has no package
// filters or the nested SearchSpec has no package filters, then we pass the key set of
// mNamespaceMapLocked to the SearchSpecToProtoConverter, signifying that there is a
// SearchSpec that wants to query every visible package.
Set This method belongs to query group.
*
* @param packageName The package name that is performing the query.
* @param databaseName The databaseName this query for.
* @param suggestionQueryExpression The non-empty query expression used to be completed.
* @param searchSuggestionSpec Spec for setting filters.
* @return a List of {@link SearchSuggestionResult}. The returned {@link SearchSuggestionResult}
* are order by the number of {@link android.app.appsearch.SearchResult} you could get by
* using that suggestion in {@link #query}.
* @throws AppSearchException if the suggestionQueryExpression is empty.
*/
@NonNull
public List This method is inefficient to call repeatedly.
*/
@NonNull
public Map This method belongs to query group.
*
* @param packageName Package name of the caller.
* @param nextPageToken The token of pre-loaded results of previously executed query.
* @return The next page of results of previously executed query.
* @throws AppSearchException on IcingSearchEngine error or if can't advance on nextPageToken.
*/
@NonNull
public SearchResultPage getNextPage(
@NonNull String packageName,
long nextPageToken,
@Nullable SearchStats.Builder sStatsBuilder)
throws AppSearchException {
long totalLatencyStartMillis = SystemClock.elapsedRealtime();
long javaLockAcquisitionLatencyStartMillis = SystemClock.elapsedRealtime();
mReadWriteLock.readLock().lock();
try {
if (sStatsBuilder != null) {
sStatsBuilder.setJavaLockAcquisitionLatencyMillis(
(int)
(SystemClock.elapsedRealtime()
- javaLockAcquisitionLatencyStartMillis));
}
throwIfClosedLocked();
LogUtil.piiTrace(TAG, "getNextPage, request", nextPageToken);
checkNextPageToken(packageName, nextPageToken);
SearchResultProto searchResultProto =
mIcingSearchEngineLocked.getNextPage(nextPageToken);
if (sStatsBuilder != null) {
sStatsBuilder.setStatusCode(statusProtoToResultCode(searchResultProto.getStatus()));
// Join query stats are handled by SearchResultsImpl, which has access to the
// original SearchSpec.
AppSearchLoggerHelper.copyNativeStats(
searchResultProto.getQueryStats(), sStatsBuilder);
}
LogUtil.piiTrace(
TAG,
"getNextPage, response",
searchResultProto.getResultsCount(),
searchResultProto);
checkSuccess(searchResultProto.getStatus());
if (nextPageToken != EMPTY_PAGE_TOKEN
&& searchResultProto.getNextPageToken() == EMPTY_PAGE_TOKEN) {
// At this point, we're guaranteed that this nextPageToken exists for this package,
// otherwise checkNextPageToken would've thrown an exception.
// Since the new token is 0, this is the last page. We should remove the old token
// from our cache since it no longer refers to this query.
synchronized (mNextPageTokensLocked) {
Set This method belongs to query group.
*
* @param packageName Package name of the caller.
* @param nextPageToken The token of pre-loaded results of previously executed query to be
* Invalidated.
* @throws AppSearchException if nextPageToken is unusable.
*/
public void invalidateNextPageToken(@NonNull String packageName, long nextPageToken)
throws AppSearchException {
if (nextPageToken == EMPTY_PAGE_TOKEN) {
// (b/208305352) Directly return here since we are no longer caching EMPTY_PAGE_TOKEN
// in the cached token set. So no need to remove it anymore.
return;
}
mReadWriteLock.readLock().lock();
try {
throwIfClosedLocked();
LogUtil.piiTrace(TAG, "invalidateNextPageToken, request", nextPageToken);
checkNextPageToken(packageName, nextPageToken);
mIcingSearchEngineLocked.invalidateNextPageToken(nextPageToken);
synchronized (mNextPageTokensLocked) {
Set This method belongs to mutate group.
*
* @param packageName The package name that owns the document.
* @param databaseName The databaseName the document is in.
* @param namespace Namespace of the document to remove.
* @param documentId ID of the document to remove.
* @param removeStatsBuilder builder for {@link RemoveStats} to hold stats for remove
* @throws AppSearchException on IcingSearchEngine error.
*/
public void remove(
@NonNull String packageName,
@NonNull String databaseName,
@NonNull String namespace,
@NonNull String documentId,
@Nullable RemoveStats.Builder removeStatsBuilder)
throws AppSearchException {
long totalLatencyStartTimeMillis = SystemClock.elapsedRealtime();
mReadWriteLock.writeLock().lock();
try {
throwIfClosedLocked();
String prefixedNamespace = createPrefix(packageName, databaseName) + namespace;
String schemaType = null;
if (mObserverManager.isPackageObserved(packageName)) {
// Someone might be observing the type this document is under, but we have no way to
// know its type without retrieving it. Do so now.
// TODO(b/193494000): If Icing Lib can return information about the deleted
// document's type we can remove this code.
if (LogUtil.isPiiTraceEnabled()) {
LogUtil.piiTrace(
TAG, "removeById, getRequest", prefixedNamespace + ", " + documentId);
}
GetResultProto getResult =
mIcingSearchEngineLocked.get(
prefixedNamespace, documentId, GET_RESULT_SPEC_NO_PROPERTIES);
LogUtil.piiTrace(TAG, "removeById, getResponse", getResult.getStatus(), getResult);
checkSuccess(getResult.getStatus());
schemaType = PrefixUtil.removePrefix(getResult.getDocument().getSchema());
}
if (LogUtil.isPiiTraceEnabled()) {
LogUtil.piiTrace(TAG, "removeById, request", prefixedNamespace + ", " + documentId);
}
DeleteResultProto deleteResultProto =
mIcingSearchEngineLocked.delete(prefixedNamespace, documentId);
LogUtil.piiTrace(
TAG, "removeById, response", deleteResultProto.getStatus(), deleteResultProto);
if (removeStatsBuilder != null) {
removeStatsBuilder.setStatusCode(
statusProtoToResultCode(deleteResultProto.getStatus()));
AppSearchLoggerHelper.copyNativeStats(
deleteResultProto.getDeleteStats(), removeStatsBuilder);
}
checkSuccess(deleteResultProto.getStatus());
// Update derived maps
updateDocumentCountAfterRemovalLocked(packageName, /* numDocumentsDeleted= */ 1);
// Prepare notifications
if (schemaType != null) {
mObserverManager.onDocumentChange(
packageName,
databaseName,
namespace,
schemaType,
documentId,
mVisibilityStoreLocked,
mVisibilityCheckerLocked);
}
} finally {
mReadWriteLock.writeLock().unlock();
if (removeStatsBuilder != null) {
removeStatsBuilder.setTotalLatencyMillis(
(int) (SystemClock.elapsedRealtime() - totalLatencyStartTimeMillis));
}
}
}
/**
* Removes documents by given query.
*
* This method belongs to mutate group.
*
* {@link SearchSpec} objects containing a {@link JoinSpec} are not allowed here.
*
* @param packageName The package name that owns the documents.
* @param databaseName The databaseName the document is in.
* @param queryExpression Query String to search.
* @param searchSpec Defines what and how to remove
* @param removeStatsBuilder builder for {@link RemoveStats} to hold stats for remove
* @throws AppSearchException on IcingSearchEngine error.
* @throws IllegalArgumentException if the {@link SearchSpec} contains a {@link JoinSpec}.
*/
public void removeByQuery(
@NonNull String packageName,
@NonNull String databaseName,
@NonNull String queryExpression,
@NonNull SearchSpec searchSpec,
@Nullable RemoveStats.Builder removeStatsBuilder)
throws AppSearchException {
if (searchSpec.getJoinSpec() != null) {
throw new IllegalArgumentException(
"JoinSpec not allowed in removeByQuery, but " + "JoinSpec was provided");
}
long totalLatencyStartTimeMillis = SystemClock.elapsedRealtime();
mReadWriteLock.writeLock().lock();
try {
throwIfClosedLocked();
List Change notifications will be created if prefixedObservedSchemas is not null.
*
* @param packageName The package name that owns the documents.
* @param finalSearchSpec The final search spec that has been written through {@link
* SearchSpecToProtoConverter}.
* @param prefixedObservedSchemas The set of prefixed schemas that have valid registered
* observers. Only changes to schemas in this set will be queued.
*/
@GuardedBy("mReadWriteLock")
private void doRemoveByQueryLocked(
@NonNull String packageName,
@NonNull SearchSpecProto finalSearchSpec,
@Nullable Set If the app crashes after a call to PersistToDisk with {@link PersistType.Code#FULL}, Icing
* would be able to fully recover all data written up to this point without a costly recovery
* process.
*
* If the app crashes after a call to PersistToDisk with {@link PersistType.Code#LITE}, Icing
* would trigger a costly recovery process in next initialization. After that, Icing would still
* be able to recover all written data - excepting Usage data. Usage data is only guaranteed to
* be safe after a call to PersistToDisk with {@link PersistType.Code#FULL}
*
* If the app crashes after an update/delete request has been made, but before any call to
* PersistToDisk, then all data in Icing will be lost.
*
* @param persistType the amount of data to persist. {@link PersistType.Code#LITE} will only
* persist the minimal amount of data to ensure all data can be recovered. {@link
* PersistType.Code#FULL} will persist all data necessary to prevent data loss without
* needing data recovery.
* @throws AppSearchException on any error that AppSearch persist data to disk.
*/
public void persistToDisk(@NonNull PersistType.Code persistType) throws AppSearchException {
mReadWriteLock.writeLock().lock();
try {
throwIfClosedLocked();
LogUtil.piiTrace(TAG, "persistToDisk, request", persistType);
PersistToDiskResultProto persistToDiskResultProto =
mIcingSearchEngineLocked.persistToDisk(persistType);
LogUtil.piiTrace(
TAG,
"persistToDisk, response",
persistToDiskResultProto.getStatus(),
persistToDiskResultProto);
checkSuccess(persistToDiskResultProto.getStatus());
} finally {
mReadWriteLock.writeLock().unlock();
}
}
/**
* Remove all {@link AppSearchSchema}s and {@link GenericDocument}s under the given package.
*
* @param packageName The name of package to be removed.
* @throws AppSearchException if we cannot remove the data.
*/
public void clearPackageData(@NonNull String packageName) throws AppSearchException {
mReadWriteLock.writeLock().lock();
try {
throwIfClosedLocked();
if (LogUtil.DEBUG) {
Log.d(TAG, "Clear data for package: " + packageName);
}
// TODO(b/193494000): We are calling getPackageToDatabases here and in several other
// places within AppSearchImpl. This method is not efficient and does a lot of string
// manipulation. We should find a way to cache the package to database map so it can
// just be obtained from a local variable instead of being parsed out of the prefixed
// map.
Set This method belongs to mutate group.
*
* @throws AppSearchException on IcingSearchEngine error.
*/
@GuardedBy("mReadWriteLock")
private void resetLocked(@Nullable InitializeStats.Builder initStatsBuilder)
throws AppSearchException {
LogUtil.piiTrace(TAG, "icingSearchEngine.reset, request");
ResetResultProto resetResultProto = mIcingSearchEngineLocked.reset();
LogUtil.piiTrace(
TAG,
"icingSearchEngine.reset, response",
resetResultProto.getStatus(),
resetResultProto);
mOptimizeIntervalCountLocked = 0;
mSchemaCacheLocked.clear();
mNamespaceMapLocked.clear();
mDocumentCountMapLocked.clear();
synchronized (mNextPageTokensLocked) {
mNextPageTokensLocked.clear();
}
if (initStatsBuilder != null) {
initStatsBuilder
.setHasReset(true)
.setResetStatusCode(statusProtoToResultCode(resetResultProto.getStatus()));
}
checkSuccess(resetResultProto.getStatus());
}
@GuardedBy("mReadWriteLock")
private void rebuildDocumentCountMapLocked(@NonNull StorageInfoProto storageInfoProto) {
mDocumentCountMapLocked.clear();
List If the data owned by {@code targetPackageName} is not visible to you, the registration
* call will succeed but no notifications will be dispatched. Notifications could start flowing
* later if {@code targetPackageName} changes its schema visibility settings.
*
* If no package matching {@code targetPackageName} exists on the system, the registration
* call will succeed but no notifications will be dispatched. Notifications could start flowing
* later if {@code targetPackageName} is installed and starts indexing data.
*
* Note that this method does not take the standard read/write lock that guards I/O, so it
* will not queue behind I/O. Therefore it is safe to call from any thread including UI or
* binder threads.
*
* @param listeningPackageAccess Visibility information about the app that wants to receive
* notifications.
* @param targetPackageName The package that owns the data the observer wants to be notified
* for.
* @param spec Describes the kind of data changes the observer should trigger for.
* @param executor The executor on which to trigger the observer callback to deliver
* notifications.
* @param observer The callback to trigger on notifications.
*/
public void registerObserverCallback(
@NonNull CallerAccess listeningPackageAccess,
@NonNull String targetPackageName,
@NonNull ObserverSpec spec,
@NonNull Executor executor,
@NonNull ObserverCallback observer) {
// This method doesn't consult mSchemaMap or mNamespaceMap, and it will register
// observers for types that don't exist. This is intentional because we notify for types
// being created or removed. If we only registered observer for existing types, it would
// be impossible to ever dispatch a notification of a type being added.
mObserverManager.registerObserverCallback(
listeningPackageAccess, targetPackageName, spec, executor, observer);
}
/**
* Removes an {@link ObserverCallback} from watching the databases owned by {@code
* targetPackageName}.
*
* All observers which compare equal to the given observer via {@link
* ObserverCallback#equals} are removed. This may be 0, 1, or many observers.
*
* Note that this method does not take the standard read/write lock that guards I/O, so it
* will not queue behind I/O. Therefore it is safe to call from any thread including UI or
* binder threads.
*/
public void unregisterObserverCallback(
@NonNull String targetPackageName, @NonNull ObserverCallback observer) {
mObserverManager.unregisterObserverCallback(targetPackageName, observer);
}
/**
* Dispatches the pending change notifications one at a time.
*
* The notifications are dispatched on the respective executors that were provided at the
* time of observer registration. This method does not take the standard read/write lock that
* guards I/O, so it is safe to call from any thread including UI or binder threads.
*
* Exceptions thrown from notification dispatch are logged but otherwise suppressed.
*/
public void dispatchAndClearChangeNotifications() {
mObserverManager.dispatchAndClearPendingNotifications();
}
private static void addToMap(
Map This method should be only called after a mutation to local storage backend which deletes
* a mass of data and could release lots resources after {@link IcingSearchEngine#optimize()}.
*
* This method will trigger {@link IcingSearchEngine#getOptimizeInfo()} to check resources
* that could be released for every {@link #CHECK_OPTIMIZE_INTERVAL} mutations.
*
* {@link IcingSearchEngine#optimize()} should be called only if {@link
* GetOptimizeInfoResultProto} shows there is enough resources could be released.
*
* @param mutationSize The number of how many mutations have been executed for current request.
* An inside counter will accumulates it. Once the counter reaches {@link
* #CHECK_OPTIMIZE_INTERVAL}, {@link IcingSearchEngine#getOptimizeInfo()} will be triggered
* and the counter will be reset.
*/
public void checkForOptimize(int mutationSize, @Nullable OptimizeStats.Builder builder)
throws AppSearchException {
mReadWriteLock.writeLock().lock();
try {
mOptimizeIntervalCountLocked += mutationSize;
if (mOptimizeIntervalCountLocked >= CHECK_OPTIMIZE_INTERVAL) {
checkForOptimize(builder);
}
} finally {
mReadWriteLock.writeLock().unlock();
}
}
/**
* Checks whether {@link IcingSearchEngine#optimize()} should be called to release resources.
*
* This method will directly trigger {@link IcingSearchEngine#getOptimizeInfo()} to check
* resources that could be released.
*
* {@link IcingSearchEngine#optimize()} should be called only if {@link
* OptimizeStrategy#shouldOptimize(GetOptimizeInfoResultProto)} return true.
*/
public void checkForOptimize(@Nullable OptimizeStats.Builder builder)
throws AppSearchException {
mReadWriteLock.writeLock().lock();
try {
GetOptimizeInfoResultProto optimizeInfo = getOptimizeInfoResultLocked();
checkSuccess(optimizeInfo.getStatus());
mOptimizeIntervalCountLocked = 0;
if (mOptimizeStrategy.shouldOptimize(optimizeInfo)) {
optimize(builder);
}
} finally {
mReadWriteLock.writeLock().unlock();
}
// TODO(b/147699081): Return OptimizeResultProto & log lost data detail once we add
// a field to indicate lost_schema and lost_documents in OptimizeResultProto.
// go/icing-library-apis.
}
/** Triggers {@link IcingSearchEngine#optimize()} directly. */
public void optimize(@Nullable OptimizeStats.Builder builder) throws AppSearchException {
mReadWriteLock.writeLock().lock();
try {
LogUtil.piiTrace(TAG, "optimize, request");
OptimizeResultProto optimizeResultProto = mIcingSearchEngineLocked.optimize();
LogUtil.piiTrace(
TAG,
"optimize, response",
optimizeResultProto.getStatus(),
optimizeResultProto);
if (builder != null) {
builder.setStatusCode(statusProtoToResultCode(optimizeResultProto.getStatus()));
AppSearchLoggerHelper.copyNativeStats(
optimizeResultProto.getOptimizeStats(), builder);
}
checkSuccess(optimizeResultProto.getStatus());
} finally {
mReadWriteLock.writeLock().unlock();
}
}
/** Sync the current Android logging level to Icing for the entire process. No lock required. */
public static void syncLoggingLevelToIcing() {
String icingTag = IcingSearchEngine.getLoggingTag();
if (icingTag == null) {
Log.e(TAG, "Received null logging tag from Icing");
return;
}
if (LogUtil.DEBUG) {
if (Log.isLoggable(icingTag, Log.VERBOSE)) {
boolean unused =
IcingSearchEngine.setLoggingLevel(
LogSeverity.Code.VERBOSE, /* verbosity= */ (short) 1);
return;
} else if (Log.isLoggable(icingTag, Log.DEBUG)) {
boolean unused = IcingSearchEngine.setLoggingLevel(LogSeverity.Code.DBG);
return;
}
}
if (LogUtil.INFO) {
if (Log.isLoggable(icingTag, Log.INFO)) {
boolean unused = IcingSearchEngine.setLoggingLevel(LogSeverity.Code.INFO);
return;
}
}
if (Log.isLoggable(icingTag, Log.WARN)) {
boolean unused = IcingSearchEngine.setLoggingLevel(LogSeverity.Code.WARNING);
} else if (Log.isLoggable(icingTag, Log.ERROR)) {
boolean unused = IcingSearchEngine.setLoggingLevel(LogSeverity.Code.ERROR);
} else {
boolean unused = IcingSearchEngine.setLoggingLevel(LogSeverity.Code.FATAL);
}
}
@GuardedBy("mReadWriteLock")
@VisibleForTesting
GetOptimizeInfoResultProto getOptimizeInfoResultLocked() {
LogUtil.piiTrace(TAG, "getOptimizeInfo, request");
GetOptimizeInfoResultProto result = mIcingSearchEngineLocked.getOptimizeInfo();
LogUtil.piiTrace(TAG, "getOptimizeInfo, response", result.getStatus(), result);
return result;
}
/**
* Returns all prefixed schema types saved in AppSearch.
*
* This method is inefficient to call repeatedly.
*/
@NonNull
public List Callers should ensure that the status code is not OK or WARNING_DATA_LOSS.
*
* @param statusProto StatusProto with error code to translate into an {@link AppSearchResult}
* code.
* @return {@link AppSearchResult} error code
*/
@AppSearchResult.ResultCode
private static int statusProtoToResultCode(@NonNull StatusProto statusProto) {
return ResultCodeToProtoConverter.toResultCode(statusProto.getCode());
}
}