Merge "Update framework from jetpack." into sc-dev am: b97100acaa (612f4f93) · Commits · e / os / android_frameworks_base

apex/appsearch/framework/java/android/app/appsearch/AppSearchBatchResult.java

+37 −15

Original line number	Diff line number	Diff line
		@@ -28,11 +28,19 @@ import java.util.Collections;
		import java.util.Map;

		/**
		* Provides access to multiple {@link AppSearchResult}s from a batch operation accepting multiple
		* inputs.
		* Provides results for AppSearch batch operations which encompass multiple documents.
		*
		* @param <KeyType> The type of the keys for {@link #getSuccesses} and {@link #getFailures}.
		* @param <ValueType> The type of result objects associated with the keys.
		* <p>Individual results of a batch operation are separated into two maps: one for successes and one
		* for failures. For successes, {@link #getSuccesses()} will return a map of keys to instances of
		* the value type. For failures, {@link #getFailures()} will return a map of keys to {@link
		* AppSearchResult} objects.
		*
		* <p>Alternatively, {@link #getAll()} returns a map of keys to {@link AppSearchResult} objects for
		* both successes and failures.
		*
		* @see AppSearchSession#put
		* @see AppSearchSession#getByUri
		* @see AppSearchSession#remove
		*/
		public final class AppSearchBatchResult<KeyType, ValueType> implements Parcelable {
		@NonNull private final Map<KeyType, ValueType> mSuccesses;
		@@ -75,8 +83,11 @@ public final class AppSearchBatchResult<KeyType, ValueType> implements Parcelabl
		}

		/**
		* Returns a {@link Map} of all successful keys mapped to the successful {@link
		* AppSearchResult}s they produced.
		* Returns a {@link Map} of keys mapped to instances of the value type for all successful
		* individual results.
		*
		* <p>Example: {@link AppSearchSession#getByUri} returns an {@link AppSearchBatchResult}. Each
		* key (a URI of {@code String} type) will map to a {@link GenericDocument} object.
		*
		* <p>The values of the {@link Map} will not be {@code null}.
		*/
		@@ -86,8 +97,8 @@ public final class AppSearchBatchResult<KeyType, ValueType> implements Parcelabl
		}

		/**
		* Returns a {@link Map} of all failed keys mapped to the failed {@link AppSearchResult}s they
		* produced.
		* Returns a {@link Map} of keys mapped to instances of {@link AppSearchResult} for all failed
		* individual results.
		*
		* <p>The values of the {@link Map} will not be {@code null}.
		*/
		@@ -97,7 +108,8 @@ public final class AppSearchBatchResult<KeyType, ValueType> implements Parcelabl
		}

		/**
		* Returns a {@link Map} of all keys mapped to the {@link AppSearchResult}s they produced.
		* Returns a {@link Map} of keys mapped to instances of {@link AppSearchResult} for all
		* individual results.
		*
		* <p>The values of the {@link Map} will not be {@code null}.
		*/
		@@ -149,8 +161,8 @@ public final class AppSearchBatchResult<KeyType, ValueType> implements Parcelabl
		/**
		* Builder for {@link AppSearchBatchResult} objects.
		*
		* @param <KeyType> The type of keys.
		* @param <ValueType> The type of result objects associated with the keys.
		* <p>Once {@link #build} is called, the instance can no longer be used.
		*
		* @hide
		*/
		public static final class Builder<KeyType, ValueType> {
		@@ -160,9 +172,11 @@ public final class AppSearchBatchResult<KeyType, ValueType> implements Parcelabl
		private boolean mBuilt = false;

		/**
		* Associates the {@code key} with the given successful return value.
		* Associates the {@code key} with the provided successful return value.
		*
		* <p>Any previous mapping for a key, whether success or failure, is deleted.
		*
		* @throws IllegalStateException if the builder has already been used.
		*/
		@NonNull
		public Builder<KeyType, ValueType> setSuccess(
		@@ -173,9 +187,11 @@ public final class AppSearchBatchResult<KeyType, ValueType> implements Parcelabl
		}

		/**
		* Associates the {@code key} with the given failure code and error message.
		* Associates the {@code key} with the provided failure code and error message.
		*
		* <p>Any previous mapping for a key, whether success or failure, is deleted.
		*
		* @throws IllegalStateException if the builder has already been used.
		*/
		@NonNull
		public Builder<KeyType, ValueType> setFailure(
		@@ -188,9 +204,11 @@ public final class AppSearchBatchResult<KeyType, ValueType> implements Parcelabl
		}

		/**
		* Associates the {@code key} with the given {@code result}.
		* Associates the {@code key} with the provided {@code result}.
		*
		* <p>Any previous mapping for a key, whether success or failure, is deleted.
		*
		* @throws IllegalStateException if the builder has already been used.
		*/
		@NonNull
		public Builder<KeyType, ValueType> setResult(
		@@ -209,7 +227,11 @@ public final class AppSearchBatchResult<KeyType, ValueType> implements Parcelabl
		return this;
		}

		/** Builds an {@link AppSearchBatchResult} from the contents of this {@link Builder}. */
		/**
		* Builds an {@link AppSearchBatchResult} object from the contents of this {@link Builder}.
		*
		* @throws IllegalStateException if the builder has already been used.
		*/
		@NonNull
		public AppSearchBatchResult<KeyType, ValueType> build() {
		Preconditions.checkState(!mBuilt, "Builder has already been used");

apex/appsearch/framework/java/android/app/appsearch/AppSearchSession.java

+15 −83

Original line number	Diff line number	Diff line
		@@ -41,7 +41,7 @@ import java.util.function.Consumer;
		* Represents a connection to an AppSearch storage system where {@link GenericDocument}s can be
		* placed and queried.
		*
		* This class is thread safe.
		* <p>This class is thread safe.
		*/
		public final class AppSearchSession implements Closeable {
		private static final String TAG = "AppSearchSession";
		@@ -102,92 +102,23 @@ public final class AppSearchSession implements Closeable {
		}

		/**
		* Sets the schema that will be used by documents provided to the {@link #put} method.
		*
		* <p>The schema provided here is compared to the stored copy of the schema previously supplied
		* to {@link #setSchema}, if any, to determine how to treat existing documents. The following
		* types of schema modifications are always safe and are made without deleting any existing
		* documents:
		*
		* <ul>
		* <li>Addition of new types
		* <li>Addition of new {@link AppSearchSchema.PropertyConfig#CARDINALITY_OPTIONAL OPTIONAL} or
		* {@link AppSearchSchema.PropertyConfig#CARDINALITY_REPEATED REPEATED} properties to a
		* type
		* <li>Changing the cardinality of a data type to be less restrictive (e.g. changing an {@link
		* AppSearchSchema.PropertyConfig#CARDINALITY_OPTIONAL OPTIONAL} property into a {@link
		* AppSearchSchema.PropertyConfig#CARDINALITY_REPEATED REPEATED} property.
		* </ul>
		*
		* <p>The following types of schema changes are not backwards-compatible:
		*
		* <ul>
		* <li>Removal of an existing type
		* <li>Removal of a property from a type
		* <li>Changing the data type ({@code boolean}, {@code long}, etc.) of an existing property
		* <li>For properties of {@code Document} type, changing the schema type of {@code Document}s
		* of that property
		* <li>Changing the cardinality of a data type to be more restrictive (e.g. changing an {@link
		* AppSearchSchema.PropertyConfig#CARDINALITY_OPTIONAL OPTIONAL} property into a {@link
		* AppSearchSchema.PropertyConfig#CARDINALITY_REQUIRED REQUIRED} property).
		* <li>Adding a {@link AppSearchSchema.PropertyConfig#CARDINALITY_REQUIRED REQUIRED} property.
		* </ul>
		*
		* <p>Supplying a schema with such changes will, by default, result in this call completing its
		* future with an {@link android.app.appsearch.exceptions.AppSearchException} with a code of
		* {@link AppSearchResult#RESULT_INVALID_SCHEMA} and a message describing the incompatibility.
		* In this case the previously set schema will remain active.
		*
		* <p>If you need to make non-backwards-compatible changes as described above, you can either:
		*
		* <ul>
		* <li>Set the {@link SetSchemaRequest.Builder#setForceOverride} method to {@code true}. In
		* this case, instead of completing its future with an {@link
		* android.app.appsearch.exceptions.AppSearchException} with the {@link
		* AppSearchResult#RESULT_INVALID_SCHEMA} error code, all documents which are not
		* compatible with the new schema will be deleted and the incompatible schema will be
		* applied. Incompatible types and deleted types will be set into {@link
		* SetSchemaResponse#getIncompatibleTypes()} and {@link
		* SetSchemaResponse#getDeletedTypes()}, respectively.
		* <li>Add a {@link android.app.appsearch.AppSearchSchema.Migrator} for each incompatible type
		* and make no deletion. The migrator will migrate documents from it's old schema version
		* to the new version. Migrated types will be set into both {@link
		* SetSchemaResponse#getIncompatibleTypes()} and {@link
		* SetSchemaResponse#getMigratedTypes()}. See the migration section below.
		* </ul>
		*
		* <p>It is a no-op to set the same schema as has been previously set; this is handled
		* efficiently.
		*
		* <p>By default, documents are visible on platform surfaces. To opt out, call {@code
		* SetSchemaRequest.Builder#setPlatformSurfaceable} with {@code surfaceable} as false. Any
		* visibility settings apply only to the schemas that are included in the {@code request}.
		* Visibility settings for a schema type do not apply or persist across {@link
		* SetSchemaRequest}s.
		*
		* <p>Migration: make non-backwards-compatible changes will delete all stored documents in old
		* schema. You can save your documents by setting {@link
		* android.app.appsearch.AppSearchSchema.Migrator} via the {@link
		* SetSchemaRequest.Builder#setMigrator} for each type you want to save.
		*
		* <p>{@link android.app.appsearch.AppSearchSchema.Migrator#onDowngrade} or {@link
		* android.app.appsearch.AppSearchSchema.Migrator#onUpgrade} will be triggered if the version
		* number of the schema stored in AppSearch is different with the version in the request.
		* Sets the schema that represents the organizational structure of data within the AppSearch
		* database.
		*
		* <p>If any error or Exception occurred in the {@link
		* android.app.appsearch.AppSearchSchema.Migrator#onDowngrade}, {@link
		* android.app.appsearch.AppSearchSchema.Migrator#onUpgrade} or {@link
		* android.app.appsearch.AppSearchMigrationHelper.Transformer#transform}, the migration will be
		* terminated, the setSchema request will be rejected unless the schema changes are
		* backwards-compatible, and stored documents won't have any observable changes.
		* <p>Upon creating an {@link AppSearchSession}, {@link #setSchema} should be called. If the
		* schema needs to be updated, or it has not been previously set, then the provided schema will
		* be saved and persisted to disk. Otherwise, {@link #setSchema} is handled efficiently as a
		* no-op call.
		*
		* @param request The schema update request.
		* @param request the schema to set or update the AppSearch database to.
		* @param executor Executor on which to invoke the callback.
		* @param callback Callback to receive errors resulting from setting the schema. If the
		* operation succeeds, the callback will be invoked with {@code null}.
		* @see android.app.appsearch.AppSearchSchema.Migrator
		* @see android.app.appsearch.AppSearchMigrationHelper.Transformer
		*/
		// TODO(b/169883602): Change @code references to @link when setPlatformSurfaceable APIs are
		// exposed.
		public void setSchema(
		@NonNull SetSchemaRequest request,
		@NonNull @CallbackExecutor Executor executor,
		@@ -280,12 +211,13 @@ public final class AppSearchSession implements Closeable {
		}

		/**
		* Indexes documents into AppSearch.
		* Indexes documents into the {@link AppSearchSession} database.
		*
		* <p>Each {@link GenericDocument}'s {@code schemaType} field must be set to the name of a
		* schema type previously registered via the {@link #setSchema} method.
		* <p>Each {@link GenericDocument} object must have a {@code schemaType} field set to an {@link
		* AppSearchSchema} type that has been previously registered by calling the {@link #setSchema}
		* method.
		*
		* @param request {@link PutDocumentsRequest} containing documents to be indexed
		* @param request containing documents to be indexed.
		* @param executor Executor on which to invoke the callback.
		* @param callback Callback to receive pending result of performing this operation. The keys
		* of the returned {@link AppSearchBatchResult} are the URIs of the input

apex/appsearch/framework/java/android/app/appsearch/GlobalSearchSession.java

+1 −2

Original line number	Diff line number	Diff line
		@@ -98,8 +98,7 @@ public class GlobalSearchSession implements Closeable {
		* <p>Document access can also be granted to system UIs by specifying {@link
		* SetSchemaRequest.Builder#setSchemaTypeVisibilityForSystemUi} when building a schema.
		*
		* <p>See {@link AppSearchSession#search} for a detailed explanation on
		* forming a query string.
		* <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#getNextPage}.

apex/appsearch/framework/java/android/app/appsearch/SearchResults.java

+12 −8

Original line number	Diff line number	Diff line
		@@ -33,12 +33,16 @@ import java.util.concurrent.Executor;
		import java.util.function.Consumer;

		/**
		* SearchResults are a returned object from a query API.
		* Encapsulates results of a search operation.
		*
		* <p>Each {@link SearchResult} contains a document and may contain other fields like snippets based
		* on request.
		* <p>Each {@link AppSearchSession#search} operation returns a list of {@link SearchResult} objects,
		* referred to as a "page", limited by the size configured by {@link
		* SearchSpec.Builder#setResultCountPerPage}.
		*
		* <p>Should close this object after finish fetching results.
		* <p>To fetch a page of results, call {@link #getNextPage}.
		*
		* <p>All instances of {@link SearchResults} must call {@link SearchResults#close()} after the
		* results are fetched.
		*
		* <p>This class is not thread safe.
		*/
		@@ -87,12 +91,12 @@ public class SearchResults implements Closeable {
		}

		/**
		* Gets a whole page of {@link SearchResult}s.
		* Retrieves the next page of {@link SearchResult} objects.
		*
		* <p>Re-call this method to get next page of {@link SearchResult}, until it returns an empty
		* list.
		* <p>The page size is configured by {@link SearchSpec.Builder#setResultCountPerPage}.
		*
		* <p>The page size is set by {@link SearchSpec.Builder#setResultCountPerPage}.
		* <p>Continue calling this method to access results until it returns an empty list, signifying
		* there are no more results.
		*
		* @param callback Callback to receive the pending result of performing this operation.
		*/

apex/appsearch/framework/java/external/android/app/appsearch/PutDocumentsRequest.java

+0 −2

Original line number	Diff line number	Diff line
		@@ -30,8 +30,6 @@ import java.util.List;
		/**
		* Encapsulates a request to index documents into an {@link AppSearchSession} database.
		*
		* <p>@see AppSearchSession#putDocuments
		*
		* @see AppSearchSession#put
		*/
		public final class PutDocumentsRequest {