Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit bda2ada6 authored by Alexander Dorokhine's avatar Alexander Dorokhine
Browse files

Update Framework from Jetpack. 

Changes included:
* 517c1ee: Schema Migration API updates to match API council recommendations.
* 407144d: Refactor some migration helper methods to Utils class.
* 2297b3a: Add a test for migrate to a nonexistent schema.
* 16a38d0: Log the PutDocumentStats in AppSearchImpl

Bug: 178060626
Bug: 179804862
Bug: 173532925
Test: Presubmit
Change-Id: I8b879bc9a5f30f9be3ce08d07dc60f4b177fb11b
parent 61897f07

apex/appsearch/framework/api/current.txt

+9 −15
Original line number Diff line number Diff line
@@ -24,14 +24,6 @@ package android.app.appsearch { 
    method @Deprecated @NonNull public android.app.appsearch.AppSearchManager.SearchContext.Builder setDatabaseName(@NonNull String);

  }



  public interface AppSearchMigrationHelper {

    method public void queryAndTransform(@NonNull String, @NonNull android.app.appsearch.AppSearchMigrationHelper.Transformer) throws java.lang.Exception;

  }



  public static interface AppSearchMigrationHelper.Transformer {

    method @NonNull public android.app.appsearch.GenericDocument transform(int, int, @NonNull android.app.appsearch.GenericDocument) throws java.lang.Exception;

  }



  public final class AppSearchResult<ValueType> {

    method @Nullable public String getErrorMessage();

    method public int getResultCode();
@@ -109,11 +101,6 @@ package android.app.appsearch { 
    method @NonNull public android.app.appsearch.AppSearchSchema.Int64PropertyConfig.Builder setCardinality(int);

  }



  public static interface AppSearchSchema.Migrator {

    method public default void onDowngrade(int, int, @NonNull android.app.appsearch.AppSearchMigrationHelper) throws java.lang.Exception;

    method public default void onUpgrade(int, int, @NonNull android.app.appsearch.AppSearchMigrationHelper) throws java.lang.Exception;

  }



  public abstract static class AppSearchSchema.PropertyConfig {

    method public int getCardinality();

    method @NonNull public String getName();
@@ -221,6 +208,13 @@ package android.app.appsearch { 
    method @NonNull public android.app.appsearch.SearchResults search(@NonNull String, @NonNull android.app.appsearch.SearchSpec);

  }



  public abstract class Migrator {

    ctor public Migrator();

    ctor public Migrator(int);

    method @NonNull @WorkerThread public abstract android.app.appsearch.GenericDocument onDowngrade(int, int, @NonNull android.app.appsearch.GenericDocument);

    method @NonNull @WorkerThread public abstract android.app.appsearch.GenericDocument onUpgrade(int, int, @NonNull android.app.appsearch.GenericDocument);

  }



  public class PackageIdentifier {

    ctor public PackageIdentifier(@NonNull String, @NonNull byte[]);

    method @NonNull public String getPackageName();
@@ -357,7 +351,7 @@ package android.app.appsearch { 
  }



  public final class SetSchemaRequest {

    method @NonNull public java.util.Map<java.lang.String,android.app.appsearch.AppSearchSchema.Migrator> getMigrators();

    method @NonNull public java.util.Map<java.lang.String,android.app.appsearch.Migrator> getMigrators();

    method @NonNull public java.util.Set<android.app.appsearch.AppSearchSchema> getSchemas();

    method @NonNull public java.util.Set<java.lang.String> getSchemasNotDisplayedBySystem();

    method @Deprecated @NonNull public java.util.Set<java.lang.String> getSchemasNotVisibleToSystemUi();
@@ -371,7 +365,7 @@ package android.app.appsearch { 
    method @NonNull public android.app.appsearch.SetSchemaRequest.Builder addSchemas(@NonNull java.util.Collection<android.app.appsearch.AppSearchSchema>);

    method @NonNull public android.app.appsearch.SetSchemaRequest build();

    method @NonNull public android.app.appsearch.SetSchemaRequest.Builder setForceOverride(boolean);

    method @NonNull public android.app.appsearch.SetSchemaRequest.Builder setMigrator(@NonNull String, @NonNull android.app.appsearch.AppSearchSchema.Migrator);

    method @NonNull public android.app.appsearch.SetSchemaRequest.Builder setMigrator(@NonNull String, @NonNull android.app.appsearch.Migrator);

    method @NonNull public android.app.appsearch.SetSchemaRequest.Builder setSchemaTypeDisplayedBySystem(@NonNull String, boolean);

    method @NonNull public android.app.appsearch.SetSchemaRequest.Builder setSchemaTypeVisibilityForPackage(@NonNull String, boolean, @NonNull android.app.appsearch.PackageIdentifier);

    method @Deprecated @NonNull public android.app.appsearch.SetSchemaRequest.Builder setSchemaTypeVisibilityForSystemUi(@NonNull String, boolean);

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

+0 −2
Original line number Diff line number Diff line
@@ -114,8 +114,6 @@ public final class AppSearchSession implements Closeable { 
     * @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.

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

deleted100644 → 0
+0 −65
Original line number Diff line number Diff line 
/*

 * Copyright 2021 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.

 */



package android.app.appsearch;



import android.annotation.NonNull;

import android.annotation.SuppressLint;



/**

 * The helper class for {@link AppSearchSchema} migration.

 *

 * <p>It will query and migrate {@link GenericDocument} in given type to a new version.

 */

public interface AppSearchMigrationHelper {



    /**

     * Queries all documents that need to be migrated to the different version, and transform

     * documents to that version by passing them to the provided {@link Transformer}.

     *

     * @param schemaType The schema that need be updated and migrated {@link GenericDocument} under

     *     this type.

     * @param transformer The {@link Transformer} that will upgrade or downgrade a {@link

     *     GenericDocument} to new version.

     * @see Transformer#transform

     */

    // Rethrow the Generic Exception thrown from the Transformer.

    @SuppressLint("GenericException")

    void queryAndTransform(@NonNull String schemaType, @NonNull Transformer transformer)

            throws Exception;



    /** The class to migrate {@link GenericDocument} between different version. */

    interface Transformer {



        /**

         * Translates a {@link GenericDocument} from a version to a different version.

         *

         * <p>If the uri, schema type or namespace is changed via the transform, it will apply to

         * the new {@link GenericDocument}.

         *

         * @param currentVersion The current version of the document's schema.

         * @param finalVersion The final version that documents need to be migrated to.

         * @param document The {@link GenericDocument} need to be translated to new version.

         * @return A {@link GenericDocument} in new version.

         */

        @NonNull

        // This method will be overridden by users, allow them to throw any customer Exceptions.

        @SuppressLint("GenericException")

        GenericDocument transform(

                int currentVersion, int finalVersion, @NonNull GenericDocument document)

                throws Exception;

    }

}

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

+1 −41
Original line number Diff line number Diff line
@@ -20,7 +20,6 @@ import android.annotation.IntDef; 
import android.annotation.IntRange;

import android.annotation.NonNull;

import android.annotation.Nullable;

import android.annotation.SuppressLint;

import android.app.appsearch.exceptions.IllegalSchemaException;

import android.app.appsearch.util.BundleUtil;

import android.os.Bundle;
@@ -179,7 +178,7 @@ public final class AppSearchSchema { 
         * @throws IllegalStateException if the version is negative or the builder has already been

         *     used.

         * @see AppSearchSession#setSchema

         * @see AppSearchSchema.Migrator

         * @see Migrator

         * @see SetSchemaRequest.Builder#setMigrator

         */

        @NonNull
@@ -861,43 +860,4 @@ public final class AppSearchSchema { 
            }

        }

    }



    /**

     * A migrator class to translate {@link GenericDocument} from different version of {@link

     * AppSearchSchema}

     */

    public interface Migrator {



        /**

         * Migrates {@link GenericDocument} to a newer version of {@link AppSearchSchema}.

         *

         * <p>This methods will be invoked only if the {@link SetSchemaRequest} is setting a higher

         * version number than the current {@link AppSearchSchema} saved in AppSearch.

         *

         * @param currentVersion The current version of the document's schema.

         * @param targetVersion The final version that documents need to be migrated to.

         * @param helper The helper class could help to query all documents need to be migrated.

         */

        // This method will be overridden by users, allow them to throw any customer Exceptions.

        @SuppressLint("GenericException")

        default void onUpgrade(

                int currentVersion, int targetVersion, @NonNull AppSearchMigrationHelper helper)

                throws Exception {}



        /**

         * Migrates {@link GenericDocument} to an older version of {@link AppSearchSchema}.

         *

         * <p>The methods will be invoked only if the {@link SetSchemaRequest} is setting a higher

         * version number than the current {@link AppSearchSchema} saved in AppSearch.

         *

         * @param currentVersion The current version of the document's schema.

         * @param targetVersion The final version that documents need to be migrated to.

         * @param helper The helper class could help to query all documents need to be migrated.

         */

        // This method will be overridden by users, allow them to throw any customer Exceptions.

        @SuppressLint("GenericException")

        default void onDowngrade(

                int currentVersion, int targetVersion, @NonNull AppSearchMigrationHelper helper)

                throws Exception {}

    }

}

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

0 → 100644
+107 −0
Original line number Diff line number Diff line 
/*

 * Copyright 2021 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.

 */



package android.app.appsearch;



import android.annotation.NonNull;

import android.annotation.WorkerThread;



import com.android.internal.util.Preconditions;



/**

 * A migrator class to translate {@link GenericDocument} from different version of {@link

 * AppSearchSchema}

 *

 * <p>Make non-backwards-compatible changes will delete all stored documents in old schema. You can

 * save your documents by setting {@link Migrator} via the {@link

 * SetSchemaRequest.Builder#setMigrator} for each type and target version you want to save.

 *

 * <p>{@link #onDowngrade} or {@link #onUpgrade} will be triggered if the version number of the

 * schema stored in AppSearch is different with the version in the request.

 *

 * <p>If any error or Exception occurred in the {@link #onDowngrade} or {@link #onUpgrade}, all the

 * setSchema request will be rejected unless the schema changes are backwards-compatible, and stored

 * documents won't have any observable changes.

 */

public abstract class Migrator {

    private final int mStartVersion;



    /**

     * Creates a {@link Migrator} will trigger migration for any version less than the final version

     * in the new schema.

     */

    public Migrator() {

        this(/*startVersion=*/ 0);

    }



    /**

     * Creates a {@link Migrator} with a non-negative start version.

     *

     * <p>Providing 0 will trigger migration for any version less than the final version in the new

     * schema.

     *

     * @param startVersion The migration will be only triggered for those versions greater or equal

     *     to the given startVersion.

     */

    public Migrator(int startVersion) {

        Preconditions.checkArgumentNonnegative(startVersion);

        mStartVersion = startVersion;

    }



    /**

     * @return {@code True} if the current version need to be migrated.

     * @hide

     */

    public boolean shouldMigrateToFinalVersion(int currentVersion, int finalVersion) {

        return currentVersion >= mStartVersion && currentVersion != finalVersion;

    }



    /**

     * Migrates {@link GenericDocument} to a newer version of {@link AppSearchSchema}.

     *

     * <p>This method will be invoked only if the {@link SetSchemaRequest} is setting a higher

     * version number than the current {@link AppSearchSchema} saved in AppSearch.

     *

     * <p>This method will be invoked on the background worker thread.

     *

     * @param currentVersion The current version of the document's schema.

     * @param targetVersion The final version that documents need to be migrated to.

     * @param document The {@link GenericDocument} need to be translated to new version.

     * @return A {@link GenericDocument} in new version.

     */

    @WorkerThread

    @NonNull

    public abstract GenericDocument onUpgrade(

            int currentVersion, int targetVersion, @NonNull GenericDocument document);



    /**

     * Migrates {@link GenericDocument} to an older version of {@link AppSearchSchema}.

     *

     * <p>This method will be invoked only if the {@link SetSchemaRequest} is setting a lower

     * version number than the current {@link AppSearchSchema} saved in AppSearch.

     *

     * <p>This method will be invoked on the background worker thread.

     *

     * @param currentVersion The current version of the document's schema.

     * @param targetVersion The final version that documents need to be migrated to.

     * @param document The {@link GenericDocument} need to be translated to new version.

     * @return A {@link GenericDocument} in new version.

     */

    @WorkerThread

    @NonNull

    public abstract GenericDocument onDowngrade(

            int currentVersion, int targetVersion, @NonNull GenericDocument document);

}