Added in API level 31

GlobalSearchSession

public class GlobalSearchSession
extends Object implements Closeable

java.lang.Object
   ↳ android.app.appsearch.GlobalSearchSession


Provides a connection to all AppSearch databases the querying application has been granted access to.

This class is thread safe.

See also:

Summary

Public methods

void close()

Closes the GlobalSearchSession.

void getByDocumentId(String packageName, String databaseName, GetByDocumentIdRequest request, Executor executor, BatchResultCallback<StringGenericDocument> callback)

Retrieves GenericDocument documents, belonging to the specified package name and database name and identified by the namespace and ids in the request, from the GlobalSearchSession database.

void getSchema(String packageName, String databaseName, Executor executor, Consumer<AppSearchResult<GetSchemaResponse>> callback)

Retrieves the collection of schemas most recently successfully provided to AppSearchSession.setSchema(SetSchemaRequest, Executor, Executor, Consumer) for any types belonging to the requested package and database that the caller has been granted access to.

void registerObserverCallback(String targetPackageName, ObserverSpec spec, Executor executor, ObserverCallback observer)

Adds an ObserverCallback to monitor changes within the databases owned by targetPackageName if they match the given ObserverSpec.

void reportSystemUsage(ReportSystemUsageRequest request, Executor executor, Consumer<AppSearchResult<Void>> callback)

Reports that a particular document has been used from a system surface.

SearchResults search(String queryExpression, SearchSpec searchSpec)

Retrieves documents from all AppSearch databases that the querying application has access to.

void unregisterObserverCallback(String targetPackageName, ObserverCallback observer)

Removes previously registered ObserverCallback instances from the system.

Inherited methods

Public methods

close

Added in API level 31
public void close ()

Closes the GlobalSearchSession. Persists all mutations, including usage reports, to disk.

getByDocumentId

Added in API level 33
public void getByDocumentId (String packageName, 
                String databaseName, 
                GetByDocumentIdRequest request, 
                Executor executor, 
                BatchResultCallback<StringGenericDocument> callback)

Retrieves GenericDocument documents, belonging to the specified package name and database name and identified by the namespace and ids in the request, from the GlobalSearchSession database.

If the package or database doesn't exist or if the calling package doesn't have access, the gets will be handled as failures in an AppSearchBatchResult object in the callback.

Parameters
packageName String: the name of the package to get from This value cannot be null.

databaseName String: the name of the database to get from This value cannot be null.

request GetByDocumentIdRequest: a request containing a namespace and IDs to get documents for. This value cannot be null.

executor Executor: Executor on which to invoke the callback. This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.

callback BatchResultCallback: Callback to receive the pending result of performing this operation. The keys of the returned AppSearchBatchResult are the input IDs. The values are the returned GenericDocuments on success, or a failed AppSearchResult otherwise. IDs that are not found will return a failed AppSearchResult with a result code of AppSearchResult#RESULT_NOT_FOUND. If an unexpected internal error occurs in the AppSearch service, BatchResultCallback#onSystemError will be invoked with a Throwable. This value cannot be null.

getSchema

Added in API level 33
public void getSchema (String packageName, 
                String databaseName, 
                Executor executor, 
                Consumer<AppSearchResult<GetSchemaResponse>> callback)

Retrieves the collection of schemas most recently successfully provided to AppSearchSession.setSchema(SetSchemaRequest, Executor, Executor, Consumer) for any types belonging to the requested package and database that the caller has been granted access to.

If the requested package/database combination does not exist or the caller has not been granted access to it, then an empty GetSchemaResponse will be returned.

Parameters
packageName String: the package that owns the requested AppSearchSchema instances. This value cannot be null.

databaseName String: the database that owns the requested AppSearchSchema instances. This value cannot be null.

executor Executor: This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.

callback Consumer: This value cannot be null.

Returns
void The pending GetSchemaResponse containing the schemas that the caller has access to or an empty GetSchemaResponse if the request package and database does not exist, has not set a schema or contains no schemas that are accessible to the caller.

registerObserverCallback

Added in API level 33
public void registerObserverCallback (String targetPackageName, 
                ObserverSpec spec, 
                Executor executor, 
                ObserverCallback observer)

Adds an ObserverCallback to monitor changes within the databases owned by targetPackageName if they match the given ObserverSpec.

The observer callback is only triggered for data that changes after it is registered. No notification about existing data is sent as a result of registering an observer. To find out about existing data, you must use the GlobalSearchSession#search API.

If the data owned by targetPackageName is not visible to you, the registration call will succeed but no notifications will be dispatched. Notifications could start flowing later if targetPackageName changes its schema visibility settings.

If no package matching targetPackageName exists on the system, the registration call will succeed but no notifications will be dispatched. Notifications could start flowing later if targetPackageName is installed and starts indexing data.

Parameters
targetPackageName String: Package whose changes to monitor This value cannot be null.

spec ObserverSpec: Specification of what types of changes to listen for This value cannot be null.

executor Executor: Executor on which to call the observer callback methods. This value cannot be null.

observer ObserverCallback: Callback to trigger when a schema or document changes This value cannot be null.

Throws
AppSearchException If an unexpected error occurs when trying to register an observer.

reportSystemUsage

Added in API level 31
public void reportSystemUsage (ReportSystemUsageRequest request, 
                Executor executor, 
                Consumer<AppSearchResult<Void>> callback)

Reports that a particular document has been used from a system surface.

See AppSearchSession#reportUsage for a general description of document usage, as well as an API that can be used by the app itself.

Usage reported via this method is accounted separately from usage reported via AppSearchSession#reportUsage and may be accessed using the constants SearchSpec#RANKING_STRATEGY_SYSTEM_USAGE_COUNT and SearchSpec#RANKING_STRATEGY_SYSTEM_USAGE_LAST_USED_TIMESTAMP.

Parameters
request ReportSystemUsageRequest: The usage reporting request. This value cannot be null.

executor Executor: Executor on which to invoke the callback. This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.

callback Consumer: Callback to receive errors. If the operation succeeds, the callback will be invoked with an AppSearchResult whose value is null. The callback will be invoked with an AppSearchResult of AppSearchResult#RESULT_SECURITY_ERROR if this API is invoked by an app which is not part of the system.

search

Added in API level 31
public SearchResults search (String queryExpression, 
                SearchSpec searchSpec)

Retrieves documents from all AppSearch databases that the querying application has access to.

Applications can be granted access to documents by specifying SetSchemaRequest.Builder.setSchemaTypeVisibilityForPackage(String, boolean, PackageIdentifier) when building a schema.

Document access can also be granted to system UIs by specifying SetSchemaRequest.Builder.setSchemaTypeDisplayedBySystem(String, boolean) when building a schema.

See AppSearchSession#search for a detailed explanation on forming a query string.

This method is lightweight. The heavy work will be done in SearchResults.getNextPage(Executor, Consumer).

Parameters
queryExpression String: query string to search. This value cannot be null.

searchSpec SearchSpec: spec for setting document filters, adding projection, setting term match type, etc. This value cannot be null.

Returns
SearchResults a SearchResults object for retrieved matched documents. This value cannot be null.

unregisterObserverCallback

Added in API level 33
public void unregisterObserverCallback (String targetPackageName, 
                ObserverCallback observer)

Removes previously registered ObserverCallback instances from the system.

All instances of ObserverCallback which are registered to observe targetPackageName and compare equal to the provided callback using the provided argument's ObserverCallback#equals will be removed.

If no matching observers have been registered, this method has no effect. If multiple matching observers have been registered, all will be removed.

Parameters
targetPackageName String: Package which the observers to be removed are listening to. This value cannot be null.

observer ObserverCallback: Callback to unregister. This value cannot be null.

Throws
AppSearchException if an error occurs trying to remove the observer, such as a failure to communicate with the system service. Note that no error will be thrown if the provided observer doesn't match any registered observer.