public interface

GlobalSearchSession

implements java.io.Closeable

 androidx.appsearch.app.GlobalSearchSession

Gradle dependencies

compile group: 'androidx.appsearch', name: 'appsearch', version: '1.1.0-alpha05'

  • groupId: androidx.appsearch
  • artifactId: appsearch
  • version: 1.1.0-alpha05

Artifact androidx.appsearch:appsearch:1.1.0-alpha05 it located at Google repository (https://maven.google.com/)

Overview

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

All implementations of this interface must be thread safe.

Summary

Methods
public voidclose()

Closes the GlobalSearchSession.

public <any>getByDocumentIdAsync(java.lang.String packageName, java.lang.String databaseName, GetByDocumentIdRequest request)

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.

public FeaturesgetFeatures()

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

public <any>getSchemaAsync(java.lang.String packageName, java.lang.String databaseName)

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

public voidregisterObserverCallback(java.lang.String targetPackageName, ObserverSpec spec, java.util.concurrent.Executor executor, ObserverCallback observer)

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

public <any>reportSystemUsageAsync(ReportSystemUsageRequest request)

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

public SearchResultssearch(java.lang.String queryExpression, SearchSpec searchSpec)

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

public voidunregisterObserverCallback(java.lang.String targetPackageName, ObserverCallback observer)

Removes previously registered ObserverCallback instances from the system.

Methods

public <any> getByDocumentIdAsync(java.lang.String packageName, java.lang.String databaseName, GetByDocumentIdRequest request)

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: the name of the package to get from
databaseName: the name of the database to get from
request: a request containing a namespace and IDs of the documents to retrieve.

public SearchResults search(java.lang.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), or SetSchemaRequest.Builder.setDocumentClassVisibilityForPackage(Class, boolean, PackageIdentifier) when building a schema.

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

See AppSearchSession.search(String, SearchSpec) for a detailed explanation on forming a query string.

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

Parameters:

queryExpression: query string to search.
searchSpec: spec for setting document filters, adding projection, setting term match type, etc.

Returns:

a SearchResults object for retrieved matched documents.

public <any> reportSystemUsageAsync(ReportSystemUsageRequest request)

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

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

Returns:

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

public <any> getSchemaAsync(java.lang.String packageName, java.lang.String databaseName)

Retrieves the collection of schemas most recently successfully provided to AppSearchSession.setSchemaAsync(SetSchemaRequest) 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: the package that owns the requested AppSearchSchema instances.
databaseName: the database that owns the requested AppSearchSchema instances.

Returns:

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.

public Features getFeatures()

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

public void registerObserverCallback(java.lang.String targetPackageName, ObserverSpec spec, java.util.concurrent.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(String, SearchSpec) 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 Features.GLOBAL_SEARCH_SESSION_REGISTER_OBSERVER_CALLBACK before calling this method.

Parameters:

targetPackageName: Package whose changes to monitor
spec: Specification of what types of changes to listen for
executor: Executor on which to call the observer callback methods.
observer: Callback to trigger when a schema or document changes

public void unregisterObserverCallback(java.lang.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 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 Features.GLOBAL_SEARCH_SESSION_REGISTER_OBSERVER_CALLBACK before calling this method.

Parameters:

targetPackageName: Package which the observers to be removed are listening to.
observer: Callback to unregister.

public void close()

Closes the GlobalSearchSession.

Source

/*
 * Copyright 2020 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
// @exportToFramework:skipFile()
package androidx.appsearch.app;

import android.annotation.SuppressLint;

import androidx.annotation.NonNull;
import androidx.annotation.RequiresFeature;
import androidx.appsearch.exceptions.AppSearchException;
import androidx.appsearch.observer.ObserverCallback;
import androidx.appsearch.observer.ObserverSpec;

import com.google.common.util.concurrent.ListenableFuture;

import java.io.Closeable;
import java.util.concurrent.Executor;

/**
 * Provides a connection to all AppSearch databases the querying application has been
 * granted access to.
 *
 * <p>All implementations of this interface must be thread safe.
 *
 * @see AppSearchSession
 */
public interface GlobalSearchSession extends Closeable {
    /**
     * Retrieves {@link GenericDocument} documents, belonging to the specified package name and
     * database name and identified by the namespace and ids in the request, from the
     * {@link GlobalSearchSession} database. When a call is successful, the result will be
     * returned in the successes section of the {@link 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 {@link AppSearchResult} objects with a
     * RESULT_NOT_FOUND status code in the failures section of the {@link AppSearchBatchResult}
     * object.
     *
     * @param packageName the name of the package to get from
     * @param databaseName the name of the database to get from
     * @param request a request containing a namespace and IDs of the documents to retrieve.
     */
    @NonNull
    @RequiresFeature(
            enforcement = "androidx.appsearch.app.Features#isFeatureSupported",
            name = Features.GLOBAL_SEARCH_SESSION_GET_BY_ID)
    ListenableFuture<AppSearchBatchResult<String, GenericDocument>> getByDocumentIdAsync(
            @NonNull String packageName,
            @NonNull String databaseName,
            @NonNull GetByDocumentIdRequest request);

    /**
     * Retrieves documents from all AppSearch databases that the querying application has access to.
     *
     * <p>Applications can be granted access to documents by specifying
     * {@link SetSchemaRequest.Builder#setSchemaTypeVisibilityForPackage}, or
     * {@link SetSchemaRequest.Builder#setDocumentClassVisibilityForPackage} when building a schema.
     *
     * <p>Document access can also be granted to system UIs by specifying
     * {@link SetSchemaRequest.Builder#setSchemaTypeDisplayedBySystem}, or
     * {@link SetSchemaRequest.Builder#setDocumentClassDisplayedBySystem}
     * when building a schema.
     *
     * <p>See {@link AppSearchSession#search} for a detailed explanation on
     * forming a query string.
     *
     * <p>This method is lightweight. The heavy work will be done in
     * {@link SearchResults#getNextPageAsync}.
     *
     * @param queryExpression query string to search.
     * @param searchSpec      spec for setting document filters, adding projection, setting term
     *                        match type, etc.
     * @return a {@link SearchResults} object for retrieved matched documents.
     */
    @NonNull
    SearchResults search(@NonNull String queryExpression, @NonNull SearchSpec searchSpec);

    /**
     * Reports that a particular document has been used from a system surface.
     *
     * <p>See {@link AppSearchSession#reportUsageAsync} for a general description of document usage,
     * as well as an API that can be used by the app itself.
     *
     * <p>Usage reported via this method is accounted separately from usage reported via
     * {@link AppSearchSession#reportUsageAsync} and may be accessed using the constants
     * {@link SearchSpec#RANKING_STRATEGY_SYSTEM_USAGE_COUNT} and
     * {@link SearchSpec#RANKING_STRATEGY_SYSTEM_USAGE_LAST_USED_TIMESTAMP}.
     *
     * @return The pending result of performing this operation which resolves to {@code null} on
     *     success. The pending result will be completed with an
     *     {@link androidx.appsearch.exceptions.AppSearchException} with a code of
     *     {@link AppSearchResult#RESULT_SECURITY_ERROR} if this API is invoked by an app which
     *     is not part of the system.
     */
    @NonNull
    ListenableFuture<Void> reportSystemUsageAsync(@NonNull ReportSystemUsageRequest request);

    /**
     * Retrieves the collection of schemas most recently successfully provided to
     * {@link AppSearchSession#setSchemaAsync} for any types belonging to the requested package and
     * database that the caller has been granted access to.
     *
     * <p> 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.
     *
     *
     * @param packageName the package that owns the requested {@link AppSearchSchema} instances.
     * @param databaseName the database that owns the requested {@link AppSearchSchema} instances.
     * @return The pending {@link 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.
     */
    // This call hits disk; async API prevents us from treating these calls as properties.
    @SuppressLint("KotlinPropertyAccess")
    @NonNull
    @RequiresFeature(
            enforcement = "androidx.appsearch.app.Features#isFeatureSupported",
            name = Features.GLOBAL_SEARCH_SESSION_GET_SCHEMA)
    ListenableFuture<GetSchemaResponse> getSchemaAsync(@NonNull String packageName,
            @NonNull String databaseName);

    /**
     * Returns the {@link Features} to check for the availability of certain features
     * for this session.
     */
    @NonNull
    Features getFeatures();

    /**
     * Adds an {@link ObserverCallback} to monitor changes within the databases owned by
     * {@code targetPackageName} if they match the given
     * {@link androidx.appsearch.observer.ObserverSpec}.
     *
     * <p>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 {@link GlobalSearchSession#search} API.
     *
     * <p>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.
     *
     * <p>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.
     *
     * <p>This feature may not be available in all implementations. Check
     * {@link Features#GLOBAL_SEARCH_SESSION_REGISTER_OBSERVER_CALLBACK} before calling this method.
     *
     * @param targetPackageName Package whose changes to monitor
     * @param spec            Specification of what types of changes to listen for
     * @param executor        Executor on which to call the {@code observer} callback methods.
     * @param observer        Callback to trigger when a schema or document changes
     * @throws AppSearchException            if an error occurs trying to register the observer
     * @throws UnsupportedOperationException if this feature is not available on this
     *                                       AppSearch implementation.
     */
    @RequiresFeature(
            enforcement = "androidx.appsearch.app.Features#isFeatureSupported",
            name = Features.GLOBAL_SEARCH_SESSION_REGISTER_OBSERVER_CALLBACK)
    void registerObserverCallback(
            @NonNull String targetPackageName,
            @NonNull ObserverSpec spec,
            @NonNull Executor executor,
            @NonNull ObserverCallback observer) throws AppSearchException;

    /**
     * Removes previously registered {@link ObserverCallback} instances from the system.
     *
     * <p>All instances of {@link ObserverCallback} which are registered to observe
     * {@code targetPackageName} and compare equal to the provided callback using the provided
     * argument's {@link ObserverCallback#equals} will be removed.
     *
     * <p>If no matching observers have been registered, this method has no effect. If multiple
     * matching observers have been registered, all will be removed.
     *
     * <p>This feature may not be available in all implementations. Check
     * {@link Features#GLOBAL_SEARCH_SESSION_REGISTER_OBSERVER_CALLBACK} before calling this method.
     *
     * @param targetPackageName Package which the observers to be removed are listening to.
     * @param observer          Callback to unregister.
     * @throws 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.
     * @throws UnsupportedOperationException if this feature is not available on this
     *                                       AppSearch implementation.
     */
    @RequiresFeature(
            enforcement = "androidx.appsearch.app.Features#isFeatureSupported",
            name = Features.GLOBAL_SEARCH_SESSION_REGISTER_OBSERVER_CALLBACK)
    void unregisterObserverCallback(
            @NonNull String targetPackageName, @NonNull ObserverCallback observer)
            throws AppSearchException;

    /** Closes the {@link GlobalSearchSession}. */
    @Override
    void close();
}