1 /* 2 * Copyright 2021 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 package androidx.appsearch.app; 17 18 import androidx.annotation.RestrictTo; 19 20 import org.jspecify.annotations.NonNull; 21 22 import java.util.Set; 23 24 /** 25 * A class that encapsulates all features that are only supported in certain cases (e.g. only on 26 * certain implementations or only at a certain Android API Level). 27 * 28 * <p>Features do not depend on any runtime state, and features will never be removed. Once 29 * {@link #isFeatureSupported} returns {@code true} for a certain feature, it is safe to assume that 30 * the feature will be available forever on that AppSearch storage implementation, at that 31 * Android API level, on that device. 32 */ 33 34 // @exportToFramework:copyToPath(../../../cts/tests/appsearch/testutils/src/android/app/appsearch/testutil/external/Features.java) 35 // Note: When adding new fields, The @RequiresFeature is needed in setters but could be skipped in 36 // getters if call the getter won't send unsupported requests to the AppSearch-framework-impl. 37 public interface Features { 38 39 /** 40 * Feature for {@link #isFeatureSupported(String)}. This feature covers 41 * {@link SearchResult.MatchInfo#getSubmatchRange} and 42 * {@link SearchResult.MatchInfo#getSubmatch}. 43 */ 44 String SEARCH_RESULT_MATCH_INFO_SUBMATCH = "SEARCH_RESULT_MATCH_INFO_SUBMATCH"; 45 46 /** 47 * Feature for {@link #isFeatureSupported(String)}. This feature covers 48 * {@link GlobalSearchSession#registerObserverCallback} and 49 * {@link GlobalSearchSession#unregisterObserverCallback}. 50 */ 51 String GLOBAL_SEARCH_SESSION_REGISTER_OBSERVER_CALLBACK = 52 "GLOBAL_SEARCH_SESSION_REGISTER_OBSERVER_CALLBACK"; 53 54 /** 55 * Feature for {@link #isFeatureSupported(String)}. This feature covers 56 * {@link GlobalSearchSession#getSchemaAsync}. 57 */ 58 String GLOBAL_SEARCH_SESSION_GET_SCHEMA = "GLOBAL_SEARCH_SESSION_GET_SCHEMA"; 59 60 /** 61 * Feature for {@link #isFeatureSupported(String)}. This feature covers 62 * {@link GlobalSearchSession#getByDocumentIdAsync}. 63 */ 64 String GLOBAL_SEARCH_SESSION_GET_BY_ID = "GLOBAL_SEARCH_SESSION_GET_BY_ID"; 65 66 /** 67 * Feature for {@link #isFeatureSupported(String)}. This feature covers 68 * {@link SetSchemaRequest.Builder#addRequiredPermissionsForSchemaTypeVisibility(String, Set)}, 69 * {@link SetSchemaRequest.Builder#clearRequiredPermissionsForSchemaTypeVisibility(String)}, 70 * {@link GetSchemaResponse#getSchemaTypesNotDisplayedBySystem()}, 71 * {@link GetSchemaResponse#getSchemaTypesVisibleToPackages()}, 72 * {@link GetSchemaResponse#getRequiredPermissionsForSchemaTypeVisibility()}, 73 * {@link SetSchemaRequest.Builder#addRequiredPermissionsForSchemaTypeVisibility} and 74 * {@link SetSchemaRequest.Builder#clearRequiredPermissionsForSchemaTypeVisibility} 75 */ 76 String ADD_PERMISSIONS_AND_GET_VISIBILITY = "ADD_PERMISSIONS_AND_GET_VISIBILITY"; 77 78 /** 79 * Feature for {@link #isFeatureSupported(String)}. This feature covers 80 * {@link AppSearchSchema.StringPropertyConfig#TOKENIZER_TYPE_RFC822}. 81 */ 82 String TOKENIZER_TYPE_RFC822 = "TOKENIZER_TYPE_RFC822"; 83 84 /** 85 * Feature for {@link #isFeatureSupported(String)}. This feature covers 86 * {@link AppSearchSchema.LongPropertyConfig#INDEXING_TYPE_RANGE} and all other numeric search 87 * features. 88 * 89 * <p>For details on the numeric search expressions in the query language, see 90 * {@link AppSearchSession#search}. 91 */ 92 // Note: The preferred name of this feature should have been LIST_FILTER_NUMERIC_SEARCH. 93 String NUMERIC_SEARCH = FeatureConstants.NUMERIC_SEARCH; 94 95 /** 96 * Feature for {@link #isFeatureSupported(String)}. This feature covers 97 * {@link AppSearchSchema.StringPropertyConfig#TOKENIZER_TYPE_VERBATIM} and all other 98 * verbatim search features within the query language that allows clients to search using the 99 * verbatim string operator. 100 * 101 * <p>For details on the verbatim string operator, see {@link AppSearchSession#search}. 102 */ 103 // Note: The preferred name of this feature should have been LIST_FILTER_VERBATIM_SEARCH. 104 String VERBATIM_SEARCH = FeatureConstants.VERBATIM_SEARCH; 105 106 /** 107 * Feature for {@link #isFeatureSupported(String)}. This feature covers the expansion of the 108 * query language to conform to the definition of the list filters language 109 * (https://aip.dev/160). 110 * 111 * <p>For more details, see {@link AppSearchSession#search}. 112 */ 113 String LIST_FILTER_QUERY_LANGUAGE = FeatureConstants.LIST_FILTER_QUERY_LANGUAGE; 114 115 /** 116 * Feature for {@link #isFeatureSupported(String)}. This feature covers the use of the 117 * "hasProperty" function in query expressions. 118 * 119 * <p>For details on the "hasProperty" function in the query language, see 120 * {@link AppSearchSession#search}. 121 */ 122 String LIST_FILTER_HAS_PROPERTY_FUNCTION = FeatureConstants.LIST_FILTER_HAS_PROPERTY_FUNCTION; 123 124 /** 125 * Feature for {@link #isFeatureSupported(String)}. This feature covers the use of the 126 * "matchScoreExpression" function in query expressions. 127 * 128 * <p>For details on the "matchScoreExpression" function in the query language, see 129 * {@link AppSearchSession#search}. 130 */ 131 @ExperimentalAppSearchApi 132 String LIST_FILTER_MATCH_SCORE_EXPRESSION_FUNCTION = 133 FeatureConstants.LIST_FILTER_MATCH_SCORE_EXPRESSION_FUNCTION; 134 135 /** 136 * Feature for {@link #isFeatureSupported(String)}. This feature covers whether or not the 137 * AppSearch backend can store the descriptions returned by 138 * {@link AppSearchSchema#getDescription} and 139 * {@link AppSearchSchema.PropertyConfig#getDescription}. 140 */ 141 @ExperimentalAppSearchApi 142 String SCHEMA_SET_DESCRIPTION = "SCHEMA_SET_DESCRIPTION"; 143 144 /** 145 * Feature for {@link #isFeatureSupported(String)}. This feature covers 146 * {@link AppSearchSchema.EmbeddingPropertyConfig}. 147 * 148 * <p>For details on the embedding search expressions, see {@link AppSearchSession#search} for 149 * the query language and {@link SearchSpec.Builder#setRankingStrategy(String)} for the ranking 150 * language. 151 */ 152 String SCHEMA_EMBEDDING_PROPERTY_CONFIG = "SCHEMA_EMBEDDING_PROPERTY_CONFIG"; 153 154 /** 155 * Feature for {@link #isFeatureSupported(String)}. This feature covers 156 * {@link AppSearchSchema.EmbeddingPropertyConfig.Builder#setQuantizationType(int)}. 157 */ 158 @ExperimentalAppSearchApi 159 String SCHEMA_EMBEDDING_QUANTIZATION = "SCHEMA_EMBEDDING_QUANTIZATION"; 160 161 /** 162 * Feature for {@link #isFeatureSupported(String)}. This feature covers 163 * {@link SearchSpec#GROUPING_TYPE_PER_SCHEMA} 164 */ 165 String SEARCH_SPEC_GROUPING_TYPE_PER_SCHEMA = "SEARCH_SPEC_GROUPING_TYPE_PER_SCHEMA"; 166 167 /** 168 * Feature for {@link #isFeatureSupported(String)}. This feature covers 169 * {@link SearchSpec.Builder#setPropertyWeights}. 170 */ 171 String SEARCH_SPEC_PROPERTY_WEIGHTS = "SEARCH_SPEC_PROPERTY_WEIGHTS"; 172 173 /** 174 * Feature for {@link #isFeatureSupported(String)}. This feature covers 175 * {@link SearchSpec.Builder#addFilterProperties} and 176 * {@link SearchSuggestionSpec.Builder#addFilterProperties}. 177 */ 178 String SEARCH_SPEC_ADD_FILTER_PROPERTIES = "SEARCH_SPEC_ADD_FILTER_PROPERTIES"; 179 180 /** 181 * Feature for {@link #isFeatureSupported(String)}. This feature covers 182 * {@link SearchSpec.Builder#setRankingStrategy(String)}. 183 */ 184 String SEARCH_SPEC_ADVANCED_RANKING_EXPRESSION = "SEARCH_SPEC_ADVANCED_RANKING_EXPRESSION"; 185 186 /** 187 * Feature for {@link #isFeatureSupported(String)}. This feature covers the support of the 188 * {@link SearchSpec.Builder#addSearchStringParameters} and 189 * {@link SearchSuggestionSpec.Builder#addSearchStringParameters} apis. 190 */ 191 String SEARCH_SPEC_SEARCH_STRING_PARAMETERS = "SEARCH_SPEC_SEARCH_STRING_PARAMETERS"; 192 193 /** 194 * Feature for {@link #isFeatureSupported(String)}. This feature covers 195 * {@link SearchSpec.Builder#addFilterDocumentIds}. 196 */ 197 @ExperimentalAppSearchApi 198 String SEARCH_SPEC_ADD_FILTER_DOCUMENT_IDS = "SEARCH_SPEC_ADD_FILTER_DOCUMENT_IDS"; 199 200 /** 201 * Feature for {@link #isFeatureSupported(String)}. This feature covers 202 * {@link AppSearchSchema.StringPropertyConfig#JOINABLE_VALUE_TYPE_QUALIFIED_ID}, 203 * {@link SearchSpec.Builder#setJoinSpec}, and all other join features. 204 */ 205 String JOIN_SPEC_AND_QUALIFIED_ID = "JOIN_SPEC_AND_QUALIFIED_ID"; 206 207 /** 208 * Feature for {@link #isFeatureSupported(String)}. This feature covers 209 * {@link AppSearchSession#searchSuggestionAsync}. 210 */ 211 String SEARCH_SUGGESTION = "SEARCH_SUGGESTION"; 212 213 /** 214 * Feature for {@link #isFeatureSupported(String)}. This feature covers setting schemas with 215 * circular references for {@link AppSearchSession#setSchemaAsync}. 216 */ 217 String SET_SCHEMA_CIRCULAR_REFERENCES = "SET_SCHEMA_CIRCULAR_REFERENCES"; 218 219 /** 220 * Feature for {@link #isFeatureSupported(String)}. This feature covers 221 * {@link AppSearchSchema.Builder#addParentType}. 222 */ 223 String SCHEMA_ADD_PARENT_TYPE = "SCHEMA_ADD_PARENT_TYPE"; 224 225 /** 226 * Feature for {@link #isFeatureSupported(String)}. This feature covers 227 * {@link 228 * AppSearchSchema.DocumentPropertyConfig.Builder#addIndexableNestedProperties(String...)} 229 */ 230 String SCHEMA_ADD_INDEXABLE_NESTED_PROPERTIES = "SCHEMA_ADD_INDEXABLE_NESTED_PROPERTIES"; 231 232 /** 233 * Feature for {@link #isFeatureSupported(String)}. This feature covers 234 * {@link AppSearchSchema.LongPropertyConfig.Builder#setScoringEnabled(boolean)}, 235 * {@link AppSearchSchema.DoublePropertyConfig.Builder#setScoringEnabled(boolean)}, 236 * {@link AppSearchSchema.BooleanPropertyConfig.Builder#setScoringEnabled(boolean)}. 237 * {@link SearchSpec.Builder#setScorablePropertyRankingEnabled(boolean)}. 238 */ 239 @ExperimentalAppSearchApi 240 String SCHEMA_SCORABLE_PROPERTY_CONFIG = FeatureConstants.SCHEMA_SCORABLE_PROPERTY_CONFIG; 241 242 /** 243 * Feature for {@link #isFeatureSupported(String)}. This feature covers 244 * {@link SearchSpec.Builder#setSearchSourceLogTag(String)}. 245 */ 246 String SEARCH_SPEC_SET_SEARCH_SOURCE_LOG_TAG = "SEARCH_SPEC_SET_SEARCH_SOURCE_LOG_TAG"; 247 248 /** 249 * Feature for {@link #isFeatureSupported(String)}. This feature covers 250 * {@link SetSchemaRequest.Builder#setPubliclyVisibleSchema(String, PackageIdentifier)}. 251 */ 252 String SET_SCHEMA_REQUEST_SET_PUBLICLY_VISIBLE = "SET_SCHEMA_REQUEST_SET_PUBLICLY_VISIBLE"; 253 254 /** 255 * Feature for {@link #isFeatureSupported(String)}. This feature covers 256 * {@link SetSchemaRequest.Builder#addSchemaTypeVisibleToConfig}. 257 */ 258 String SET_SCHEMA_REQUEST_ADD_SCHEMA_TYPE_VISIBLE_TO_CONFIG = 259 "SET_SCHEMA_REQUEST_ADD_SCHEMA_TYPE_VISIBLE_TO_CONFIG"; 260 261 /** 262 * Feature for {@link #isFeatureSupported(String)}. This feature covers 263 * {@link EnterpriseGlobalSearchSession} 264 */ 265 String ENTERPRISE_GLOBAL_SEARCH_SESSION = "ENTERPRISE_GLOBAL_SEARCH_SESSION"; 266 267 /** 268 * Feature for {@link #isFeatureSupported(String)}. This feature covers 269 * {@link SearchSpec.Builder#addInformationalRankingExpressions}. 270 */ 271 String SEARCH_SPEC_ADD_INFORMATIONAL_RANKING_EXPRESSIONS = 272 "SEARCH_SPEC_ADD_INFORMATIONAL_RANKING_EXPRESSIONS"; 273 274 /** 275 * Feature for {@link #isFeatureSupported(String)}. This feature covers 276 * {@link AppSearchBlobHandle}. 277 */ 278 // TODO(b/273591938) improve the java doc when we support set blob property in GenericDocument 279 // TODO(b/273591938) unhide the API once it read for API review. 280 @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP) 281 @ExperimentalAppSearchApi 282 String BLOB_STORAGE = "BLOB_STORAGE"; 283 284 /** 285 * Feature for {@link #isFeatureSupported(String)}. This feature indicates whether or not the 286 * MobileApplication corpus is being indexed. 287 * 288 * <p>This corpus contains documents representing applications installed on the device, and each 289 * document includes an icon uri, a package id, a display name, and nicknames of the app. This 290 * corpus may be queried by applications interested in querying for and launching applications, 291 * such as a search app. {@link androidx.appsearch.builtintypes.MobileApplication} can be used 292 * to parse documents returned from this corpus. 293 * 294 * <p>This corpus can be queried with a {@link GlobalSearchSession}, by filtering on the 295 * "android" package and the "apps" namespace, for example: 296 * <code> 297 * globalSession.query("", 298 * new SearchSpec.Builder().addFilterPackageNames("android").addFilterNamespace("apps").build()) 299 * </code> 300 * 301 * @see androidx.appsearch.builtintypes.MobileApplication 302 */ 303 @ExperimentalAppSearchApi 304 String INDEXER_MOBILE_APPLICATIONS = "INDEXER_MOBILE_APPLICATIONS"; 305 306 /** 307 * Feature for {@link #isFeatureSupported(String)}. This feature covers whether to wrap the 308 * parent types of a document in the corresponding 309 * {@link androidx.appsearch.app.SearchResult}, instead of in 310 * {@link androidx.appsearch.app.GenericDocument}. 311 */ 312 @ExperimentalAppSearchApi 313 String SEARCH_RESULT_PARENT_TYPES = "SEARCH_RESULT_PARENT_TYPES"; 314 315 /** 316 * Feature for {@link #isFeatureSupported(String)}. This feature covers 317 * {@link AppSearchSchema.StringPropertyConfig#DELETE_PROPAGATION_TYPE_PROPAGATE_FROM} and 318 * {@link AppSearchSchema.StringPropertyConfig.Builder#setDeletePropagationType}. 319 */ 320 // TODO(b/384947619) unhide the API once it is ready. 321 @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP) 322 @ExperimentalAppSearchApi 323 String SCHEMA_STRING_PROPERTY_CONFIG_DELETE_PROPAGATION_TYPE_PROPAGATE_FROM = 324 "SCHEMA_STRING_PROPERTY_CONFIG_DELETE_PROPAGATION_TYPE_PROPAGATE_FROM"; 325 326 /** 327 * Feature for {@link #isFeatureSupported(String)}. This feature covers whether to use isolated 328 * storage for user data. 329 */ 330 @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP) 331 String ISOLATED_STORAGE = "ISOLATED_STORAGE"; 332 333 /** 334 * Feature for {@link #isFeatureSupported(String)}. This feature covers the use of the 335 * "minOrDefault" and "maxOrDefault" functions in ranking expressions. 336 * 337 * <p>For details on the functions in the ranking language, see 338 * {@link SearchSpec.Builder#setRankingStrategy(String)}. 339 */ 340 @ExperimentalAppSearchApi 341 String SEARCH_SPEC_RANKING_FUNCTION_MAX_MIN_OR_DEFAULT = 342 "SEARCH_SPEC_RANKING_FUNCTION_MAX_MIN_OR_DEFAULT"; 343 344 /** 345 * Feature for {@link #isFeatureSupported(String)}. This feature covers the use of the 346 * "filterByRange" function in ranking expressions. 347 * 348 * <p>For details on the function in the ranking language, see 349 * {@link SearchSpec.Builder#setRankingStrategy(String)}. 350 */ 351 @ExperimentalAppSearchApi 352 String SEARCH_SPEC_RANKING_FUNCTION_FILTER_BY_RANGE = 353 "SEARCH_SPEC_RANKING_FUNCTION_FILTER_BY_RANGE"; 354 355 /** 356 * Feature for {@link #isFeatureSupported(String)}. This feature covers 357 * {@link SearchSpec.Builder#setRetrieveEmbeddingMatchInfos(boolean)}. 358 */ 359 @ExperimentalAppSearchApi 360 String SEARCH_EMBEDDING_MATCH_INFO = "SEARCH_EMBEDDING_MATCH_INFO"; 361 362 /** 363 * Feature for {@link #isFeatureSupported(String)}. This feature covers {@link 364 * ActionAccumulator#create}. 365 */ 366 // TODO(b/395157195): Update Javadoc and imports once ActionAccumulator class is available 367 // Due to lint checks, we cannot include the word "ACTION" in this value 368 @ExperimentalAppSearchApi 369 String SEARCH_AND_CLICK_ACCUMULATOR = "SEARCH_AND_CLICK_ACCUMULATOR"; 370 371 /** 372 * Returns whether a feature is supported at run-time. Feature support depends on the 373 * feature in question, the AppSearch backend being used and the Android version of the 374 * device. 375 * 376 * <p class="note"><b>Note:</b> If this method returns {@code false}, it is not safe to invoke 377 * the methods requiring the desired feature. 378 * 379 * @param feature the feature to be checked 380 * @return whether the capability is supported given the Android API level and AppSearch 381 * backend. 382 */ isFeatureSupported(@onNull String feature)383 boolean isFeatureSupported(@NonNull String feature); 384 385 /** 386 * Returns the maximum amount of properties that can be indexed in a Document 387 * given the Android API level and AppSearch backend. 388 * 389 * <p>A property is defined as all values that are present at a particular path. 390 */ getMaxIndexedProperties()391 int getMaxIndexedProperties(); 392 } 393