1 /* 2 * Copyright 2024 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 // @exportToFramework:skipFile() 17 package androidx.appsearch.app; 18 19 import android.annotation.SuppressLint; 20 21 import androidx.annotation.RequiresFeature; 22 23 import com.google.common.util.concurrent.ListenableFuture; 24 25 import org.jspecify.annotations.NonNull; 26 27 /** 28 * Provides a connection to all enterprise (work profile) AppSearch databases the querying 29 * application has been granted access to. 30 * 31 * <p>This session can be created from any user profile but will only properly return results when 32 * created from the main profile. If the user is not the main profile or an associated work profile 33 * does not exist, queries will still successfully complete but with empty results. 34 * 35 * <p>Schemas must be explicitly tagged enterprise and may require additional permissions to be 36 * visible from an enterprise session. Retrieved documents may also have certain fields restricted 37 * or modified unlike if they were retrieved directly from {@link GlobalSearchSession} on the work 38 * profile. 39 * 40 * <p>All implementations of this interface must be thread safe. 41 * 42 * @see GlobalSearchSession 43 */ 44 @RequiresFeature( 45 enforcement = "androidx.appsearch.app.Features#isFeatureSupported", 46 name = Features.ENTERPRISE_GLOBAL_SEARCH_SESSION) 47 public interface EnterpriseGlobalSearchSession { 48 /** 49 * Retrieves {@link GenericDocument} documents, belonging to the specified package name and 50 * database name and identified by the namespace and ids in the request, from the 51 * {@link EnterpriseGlobalSearchSession} database. When a call is successful, the result will be 52 * returned in the successes section of the {@link AppSearchBatchResult} object in the callback. 53 * If the package doesn't exist, database doesn't exist, or if the calling package doesn't have 54 * access, these failures will be reflected as {@link AppSearchResult} objects with a 55 * RESULT_NOT_FOUND status code in the failures section of the {@link AppSearchBatchResult} 56 * object. 57 * 58 * @param packageName the name of the package to get from 59 * @param databaseName the name of the database to get from 60 * @param request a request containing a namespace and IDs of the documents to retrieve. 61 */ getByDocumentIdAsync( @onNull String packageName, @NonNull String databaseName, @NonNull GetByDocumentIdRequest request)62 @NonNull ListenableFuture<AppSearchBatchResult<String, GenericDocument>> getByDocumentIdAsync( 63 @NonNull String packageName, 64 @NonNull String databaseName, 65 @NonNull GetByDocumentIdRequest request); 66 67 /** 68 * Retrieves documents from all enterprise (work profile) AppSearch databases that the querying 69 * application has access to. 70 * 71 * <p>Applications can be granted access to documents by specifying 72 * {@link SetSchemaRequest.Builder#setSchemaTypeVisibilityForPackage}, or 73 * {@link SetSchemaRequest.Builder#setDocumentClassVisibilityForPackage} when building a schema. 74 * 75 * <p>Document access can also be granted to system UIs by specifying 76 * {@link SetSchemaRequest.Builder#setSchemaTypeDisplayedBySystem}, or 77 * {@link SetSchemaRequest.Builder#setDocumentClassDisplayedBySystem} 78 * when building a schema. 79 * 80 * <p>See {@link AppSearchSession#search} for a detailed explanation on 81 * forming a query string. 82 * 83 * <p>This method is lightweight. The heavy work will be done in 84 * {@link SearchResults#getNextPageAsync}. 85 * 86 * @param queryExpression query string to search. 87 * @param searchSpec spec for setting document filters, adding projection, setting term 88 * match type, etc. 89 * @return a {@link SearchResults} object for retrieved matched documents. 90 */ search(@onNull String queryExpression, @NonNull SearchSpec searchSpec)91 @NonNull SearchResults search(@NonNull String queryExpression, @NonNull SearchSpec searchSpec); 92 93 /** 94 * Retrieves the collection of schemas most recently successfully provided to 95 * {@link AppSearchSession#setSchemaAsync} for any types belonging to the requested package and 96 * database that the caller has been granted access to. 97 * 98 * <p> If the requested package/database combination does not exist or the caller has not been 99 * granted access to it, then an empty GetSchemaResponse will be returned. 100 * 101 * 102 * @param packageName the package that owns the requested {@link AppSearchSchema} instances. 103 * @param databaseName the database that owns the requested {@link AppSearchSchema} instances. 104 * @return The pending {@link GetSchemaResponse} containing the schemas that the caller has 105 * access to or an empty GetSchemaResponse if the request package and database does not 106 * exist, has not set a schema or contains no schemas that are accessible to the caller. 107 */ 108 // This call hits disk; async API prevents us from treating these calls as properties. 109 @SuppressLint("KotlinPropertyAccess") getSchemaAsync(@onNull String packageName, @NonNull String databaseName)110 @NonNull ListenableFuture<GetSchemaResponse> getSchemaAsync(@NonNull String packageName, 111 @NonNull String databaseName); 112 113 /** 114 * Returns the {@link Features} to check for the availability of certain features 115 * for this session. 116 */ getFeatures()117 @NonNull Features getFeatures(); 118 } 119