GlobalSearchSession

interface GlobalSearchSession : Closeable

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

All implementations of this interface must be thread safe.

See also
AppSearchSession

Summary

Public functions
Unit

Closes the GlobalSearchSession.
ListenableFuture<AppSearchBatchResult<String!, GenericDocument!>!>
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.GLOBAL_SEARCH_SESSION_GET_BY_ID)
getByDocumentIdAsync(
    packageName: String,
    databaseName: String,
    request: GetByDocumentIdRequest
)

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.
Features

Returns the Features to check for the availability of certain features for this session.
ListenableFuture<GetSchemaResponse!>
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.GLOBAL_SEARCH_SESSION_GET_SCHEMA)
getSchemaAsync(packageName: String, databaseName: String)

Retrieves the collection of schemas most recently successfully provided to setSchemaAsync for any types belonging to the requested package and database that the caller has been granted access to.
ListenableFuture<OpenBlobForReadResponse!>
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.BLOB_STORAGE)
@ExperimentalAppSearchApi
openBlobForReadAsync(handles: (Mutable)Set<AppSearchBlobHandle!>)

Opens a batch of AppSearch Blobs for reading.
Unit
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.GLOBAL_SEARCH_SESSION_REGISTER_OBSERVER_CALLBACK)
registerObserverCallback(
    targetPackageName: String,
    spec: ObserverSpec,
    executor: Executor,
    observer: ObserverCallback
)

Adds an ObserverCallback to monitor changes within the databases owned by targetPackageName if they match the given androidx.appsearch.observer.ObserverSpec.
ListenableFuture<Void!>

Reports that a particular document has been used from a system surface.
SearchResults
search(queryExpression: String, searchSpec: SearchSpec)

Retrieves documents from all AppSearch databases that the querying application has access to.
Unit
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.GLOBAL_SEARCH_SESSION_REGISTER_OBSERVER_CALLBACK)
unregisterObserverCallback(
    targetPackageName: String,
    observer: ObserverCallback
)

Removes previously registered ObserverCallback instances from the system.

Public functions

close

Added in 1.1.0-alpha07
fun close(): Unit

Closes the GlobalSearchSession.

getByDocumentIdAsync

Added in 1.1.0-alpha07
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.GLOBAL_SEARCH_SESSION_GET_BY_ID)
fun getByDocumentIdAsync(
    packageName: String,
    databaseName: String,
    request: GetByDocumentIdRequest
): ListenableFuture<AppSearchBatchResult<String!, GenericDocument!>!>

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. When a call is successful, the result will be returned in the successes section of the AppSearchBatchResult object in the callback. If the package doesn't exist, database doesn't exist, or if the calling package doesn't have access, these failures will be reflected as AppSearchResult objects with a RESULT_NOT_FOUND status code in the failures section of the AppSearchBatchResult object.

Parameters
packageName: String

the name of the package to get from
databaseName: String

the name of the database to get from
request: GetByDocumentIdRequest

a request containing a namespace and IDs of the documents to retrieve.

getFeatures

Added in 1.1.0-alpha07
fun getFeatures(): Features

Returns the Features to check for the availability of certain features for this session.

getSchemaAsync

Added in 1.1.0-alpha07
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.GLOBAL_SEARCH_SESSION_GET_SCHEMA)
fun getSchemaAsync(packageName: String, databaseName: String): ListenableFuture<GetSchemaResponse!>

Retrieves the collection of schemas most recently successfully provided to setSchemaAsync 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.
databaseName: String

the database that owns the requested AppSearchSchema instances.
Returns
ListenableFuture<GetSchemaResponse!>

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.

openBlobForReadAsync

Added in 1.1.0-alpha07
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.BLOB_STORAGE)
@ExperimentalAppSearchApi
fun openBlobForReadAsync(handles: (Mutable)Set<AppSearchBlobHandle!>): ListenableFuture<OpenBlobForReadResponse!>

Opens a batch of AppSearch Blobs for reading.

See openBlobForReadAsync for a general description when a blob is open for read.

The returned OpenBlobForReadResponse must be closed after use to avoid resource leaks. Failing to close it will result in system file descriptor exhaustion.

Parameters
handles: (Mutable)Set<AppSearchBlobHandle!>

The AppSearchBlobHandles that identifies the blobs.
Returns
ListenableFuture<OpenBlobForReadResponse!>

a response containing the readable file descriptors.
See also
setPropertyBlobHandle

registerObserverCallback

Added in 1.1.0-alpha07
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.GLOBAL_SEARCH_SESSION_REGISTER_OBSERVER_CALLBACK)
fun registerObserverCallback(
    targetPackageName: String,
    spec: ObserverSpec,
    executor: Executor,
    observer: ObserverCallback
): Unit

Adds an ObserverCallback to monitor changes within the databases owned by targetPackageName if they match the given androidx.appsearch.observer.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 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.

This feature may not be available in all implementations. Check GLOBAL_SEARCH_SESSION_REGISTER_OBSERVER_CALLBACK before calling this method.

Parameters
targetPackageName: String

Package whose changes to monitor
spec: ObserverSpec

Specification of what types of changes to listen for
executor: Executor

Executor on which to call the observer callback methods.
observer: ObserverCallback

Callback to trigger when a schema or document changes
Throws
androidx.appsearch.exceptions.AppSearchException

if an error occurs trying to register the observer
java.lang.UnsupportedOperationException

if this feature is not available on this AppSearch implementation.

reportSystemUsageAsync

Added in 1.1.0-alpha07
fun reportSystemUsageAsync(request: ReportSystemUsageRequest): ListenableFuture<Void!>

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

See reportUsageAsync 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 reportUsageAsync and may be accessed using the constants RANKING_STRATEGY_SYSTEM_USAGE_COUNT and RANKING_STRATEGY_SYSTEM_USAGE_LAST_USED_TIMESTAMP.

Returns
ListenableFuture<Void!>

The pending result of performing this operation which resolves to null on success. The pending result will be completed with an androidx.appsearch.exceptions.AppSearchException with a code of RESULT_SECURITY_ERROR if this API is invoked by an app which is not part of the system.

search

Added in 1.1.0-alpha07
fun search(queryExpression: String, searchSpec: SearchSpec): SearchResults

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

Applications can be granted access to documents by specifying setSchemaTypeVisibilityForPackage, or setDocumentClassVisibilityForPackage when building a schema.

Document access can also be granted to system UIs by specifying setSchemaTypeDisplayedBySystem, or setDocumentClassDisplayedBySystem when building a schema.

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

This method is lightweight. The heavy work will be done in getNextPageAsync.

Parameters
queryExpression: String

query string to search.
searchSpec: SearchSpec

spec for setting document filters, adding projection, setting term match type, etc.
Returns
SearchResults

a SearchResults object for retrieved matched documents.

unregisterObserverCallback

Added in 1.1.0-alpha07
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.GLOBAL_SEARCH_SESSION_REGISTER_OBSERVER_CALLBACK)
fun unregisterObserverCallback(
    targetPackageName: String,
    observer: ObserverCallback
): Unit

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 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.

This feature may not be available in all implementations. Check GLOBAL_SEARCH_SESSION_REGISTER_OBSERVER_CALLBACK before calling this method.

Parameters
targetPackageName: String

Package which the observers to be removed are listening to.
observer: ObserverCallback

Callback to unregister.
Throws
androidx.appsearch.exceptions.AppSearchException

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

if this feature is not available on this AppSearch implementation.