1 /* 2 * Copyright 2020 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.app.appsearch; 18 19 import android.annotation.NonNull; 20 import android.annotation.SuppressLint; 21 import android.app.appsearch.exceptions.AppSearchException; 22 import android.app.appsearch.observer.ObserverCallback; 23 import android.app.appsearch.observer.ObserverSpec; 24 25 import com.google.common.util.concurrent.ListenableFuture; 26 27 import java.io.Closeable; 28 import java.util.concurrent.Executor; 29 30 /** 31 * Provides a connection to all AppSearch databases the querying application has been granted access 32 * to. 33 * 34 * <p>All implementations of this interface must be thread safe. 35 * 36 * @see AppSearchSessionShim 37 */ 38 public interface GlobalSearchSessionShim extends Closeable { 39 /** 40 * Retrieves {@link GenericDocument} documents, belonging to the specified package name and 41 * database name and identified by the namespace and ids in the request, from the {@link 42 * GlobalSearchSessionShim} database. When a call is successful, the result will be returned in 43 * the successes section of the {@link AppSearchBatchResult} object in the callback. If the 44 * package doesn't exist, database doesn't exist, or if the calling package doesn't have access, 45 * these failures will be reflected as {@link AppSearchResult} objects with a RESULT_NOT_FOUND 46 * status code in the failures section of the {@link AppSearchBatchResult} object. 47 * 48 * @param packageName the name of the package to get from 49 * @param databaseName the name of the database to get from 50 * @param request a request containing a namespace and IDs of the documents to retrieve. 51 */ 52 @NonNull getByDocumentIdAsync( @onNull String packageName, @NonNull String databaseName, @NonNull GetByDocumentIdRequest request)53 ListenableFuture<AppSearchBatchResult<String, GenericDocument>> getByDocumentIdAsync( 54 @NonNull String packageName, 55 @NonNull String databaseName, 56 @NonNull GetByDocumentIdRequest request); 57 58 /** 59 * Retrieves documents from all AppSearch databases that the querying application has access to. 60 * 61 * <p>Applications can be granted access to documents by specifying {@link 62 * SetSchemaRequest.Builder#setSchemaTypeVisibilityForPackage}, or {@link 63 * SetSchemaRequest.Builder#setDocumentClassVisibilityForPackage} when building a schema. 64 * 65 * <p>Document access can also be granted to system UIs by specifying {@link 66 * SetSchemaRequest.Builder#setSchemaTypeDisplayedBySystem}, or {@link 67 * SetSchemaRequest.Builder#setDocumentClassDisplayedBySystem} when building a schema. 68 * 69 * <p>See {@link AppSearchSessionShim#search} for a detailed explanation on forming a query 70 * string. 71 * 72 * <p>This method is lightweight. The heavy work will be done in {@link 73 * SearchResultsShim#getNextPage}. 74 * 75 * @param queryExpression query string to search. 76 * @param searchSpec spec for setting document filters, adding projection, setting term match 77 * type, etc. 78 * @return a {@link SearchResultsShim} object for retrieved matched documents. 79 */ 80 @NonNull search(@onNull String queryExpression, @NonNull SearchSpec searchSpec)81 SearchResultsShim search(@NonNull String queryExpression, @NonNull SearchSpec searchSpec); 82 83 /** 84 * Reports that a particular document has been used from a system surface. 85 * 86 * <p>See {@link AppSearchSessionShim#reportUsage} for a general description of document usage, 87 * as well as an API that can be used by the app itself. 88 * 89 * <p>Usage reported via this method is accounted separately from usage reported via {@link 90 * AppSearchSessionShim#reportUsage} and may be accessed using the constants {@link 91 * SearchSpec#RANKING_STRATEGY_SYSTEM_USAGE_COUNT} and {@link 92 * SearchSpec#RANKING_STRATEGY_SYSTEM_USAGE_LAST_USED_TIMESTAMP}. 93 * 94 * @return The pending result of performing this operation which resolves to {@code null} on 95 * success. The pending result will be completed with an {@link 96 * android.app.appsearch.exceptions.AppSearchException} with a code of {@link 97 * AppSearchResult#RESULT_SECURITY_ERROR} if this API is invoked by an app which is not part 98 * of the system. 99 */ 100 @NonNull reportSystemUsageAsync(@onNull ReportSystemUsageRequest request)101 ListenableFuture<Void> reportSystemUsageAsync(@NonNull ReportSystemUsageRequest request); 102 103 /** 104 * Retrieves the collection of schemas most recently successfully provided to {@link 105 * AppSearchSessionShim#setSchema} for any types belonging to the requested package and database 106 * that the caller has been granted access to. 107 * 108 * <p>If the requested package/database combination does not exist or the caller has not been 109 * granted access to it, then an empty GetSchemaResponse will be returned. 110 * 111 * @param packageName the package that owns the requested {@link AppSearchSchema} instances. 112 * @param databaseName the database that owns the requested {@link AppSearchSchema} instances. 113 * @return The pending {@link GetSchemaResponse} containing the schemas that the caller has 114 * access to or an empty GetSchemaResponse if the request package and database does not 115 * exist, has not set a schema or contains no schemas that are accessible to the caller. 116 */ 117 // This call hits disk; async API prevents us from treating these calls as properties. 118 @SuppressLint("KotlinPropertyAccess") 119 @NonNull getSchemaAsync( @onNull String packageName, @NonNull String databaseName)120 ListenableFuture<GetSchemaResponse> getSchemaAsync( 121 @NonNull String packageName, @NonNull String databaseName); 122 123 /** 124 * Returns the {@link Features} to check for the availability of certain features for this 125 * session. 126 */ 127 @NonNull getFeatures()128 Features getFeatures(); 129 130 /** 131 * Adds an {@link ObserverCallback} to monitor changes within the databases owned by {@code 132 * targetPackageName} if they match the given {@link 133 * android.app.appsearch.observer.ObserverSpec}. 134 * 135 * <p>The observer callback is only triggered for data that changes after it is registered. No 136 * notification about existing data is sent as a result of registering an observer. To find out 137 * about existing data, you must use the {@link GlobalSearchSessionShim#search} API. 138 * 139 * <p>If the data owned by {@code targetPackageName} is not visible to you, the registration 140 * call will succeed but no notifications will be dispatched. Notifications could start flowing 141 * later if {@code targetPackageName} changes its schema visibility settings. 142 * 143 * <p>If no package matching {@code targetPackageName} exists on the system, the registration 144 * call will succeed but no notifications will be dispatched. Notifications could start flowing 145 * later if {@code targetPackageName} is installed and starts indexing data. 146 * 147 * <p>This feature may not be available in all implementations. Check {@link 148 * Features#GLOBAL_SEARCH_SESSION_REGISTER_OBSERVER_CALLBACK} before calling this method. 149 * 150 * @param targetPackageName Package whose changes to monitor 151 * @param spec Specification of what types of changes to listen for 152 * @param executor Executor on which to call the {@code observer} callback methods. 153 * @param observer Callback to trigger when a schema or document changes 154 * @throws AppSearchException if an error occurs trying to register the observer 155 * @throws UnsupportedOperationException if this feature is not available on this AppSearch 156 * implementation. 157 */ registerObserverCallback( @onNull String targetPackageName, @NonNull ObserverSpec spec, @NonNull Executor executor, @NonNull ObserverCallback observer)158 void registerObserverCallback( 159 @NonNull String targetPackageName, 160 @NonNull ObserverSpec spec, 161 @NonNull Executor executor, 162 @NonNull ObserverCallback observer) 163 throws AppSearchException; 164 165 /** 166 * Removes previously registered {@link ObserverCallback} instances from the system. 167 * 168 * <p>All instances of {@link ObserverCallback} which are registered to observe {@code 169 * targetPackageName} and compare equal to the provided callback using the provided argument's 170 * {@link ObserverCallback#equals} will be removed. 171 * 172 * <p>If no matching observers have been registered, this method has no effect. If multiple 173 * matching observers have been registered, all will be removed. 174 * 175 * <p>This feature may not be available in all implementations. Check {@link 176 * Features#GLOBAL_SEARCH_SESSION_REGISTER_OBSERVER_CALLBACK} before calling this method. 177 * 178 * @param targetPackageName Package which the observers to be removed are listening to. 179 * @param observer Callback to unregister. 180 * @throws AppSearchException if an error occurs trying to remove the observer, such as a 181 * failure to communicate with the system service in the platform backend. Note that no 182 * error will be thrown if the provided observer doesn't match any registered observer. 183 * @throws UnsupportedOperationException if this feature is not available on this AppSearch 184 * implementation. 185 */ unregisterObserverCallback( @onNull String targetPackageName, @NonNull ObserverCallback observer)186 void unregisterObserverCallback( 187 @NonNull String targetPackageName, @NonNull ObserverCallback observer) 188 throws AppSearchException; 189 190 /** Closes the {@link GlobalSearchSessionShim}. */ 191 @Override close()192 void close(); 193 } 194