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 17 package android.app.appsearch; 18 19 import android.annotation.WorkerThread; 20 21 import org.jspecify.annotations.NonNull; 22 23 /** 24 * A migrator class to translate {@link GenericDocument} from different version of {@link 25 * AppSearchSchema} 26 * 27 * <p>Make non-backwards-compatible changes will delete all stored documents in old schema. You can 28 * save your documents by setting {@link Migrator} via the {@link 29 * SetSchemaRequest.Builder#setMigrator} for each type and target version you want to save. 30 * 31 * <p>{@link #onDowngrade} or {@link #onUpgrade} will be triggered if the version number of the 32 * schema stored in AppSearch is different with the version in the request. 33 * 34 * <p>If any error or Exception occurred in the {@link #onDowngrade} or {@link #onUpgrade}, all the 35 * setSchema request will be rejected unless the schema changes are backwards-compatible, and stored 36 * documents won't have any observable changes. 37 */ 38 public abstract class Migrator { 39 /** 40 * Returns {@code true} if this migrator's source type needs to be migrated to update from 41 * currentVersion to finalVersion. 42 * 43 * <p>Migration won't be triggered if currentVersion is equal to finalVersion even if {@link 44 * #shouldMigrate} return true; 45 */ shouldMigrate(int currentVersion, int finalVersion)46 public abstract boolean shouldMigrate(int currentVersion, int finalVersion); 47 48 /** 49 * Migrates {@link GenericDocument} to a newer version of {@link AppSearchSchema}. 50 * 51 * <p>This method will be invoked only if the {@link SetSchemaRequest} is setting a higher 52 * version number than the current {@link AppSearchSchema} saved in AppSearch. 53 * 54 * <p>If this {@link Migrator} is provided to cover a compatible schema change via {@link 55 * AppSearchSession#setSchema}, documents under the old version won't be removed unless you use 56 * the same document ID. 57 * 58 * <p>This method will be invoked on the background worker thread provided via {@link 59 * AppSearchSession#setSchema}. 60 * 61 * @param currentVersion The current version of the document's schema. 62 * @param finalVersion The final version that documents need to be migrated to. 63 * @param document The {@link GenericDocument} need to be translated to new version. 64 * @return A {@link GenericDocument} in new version. 65 */ 66 @WorkerThread onUpgrade( int currentVersion, int finalVersion, @NonNull GenericDocument document)67 public abstract @NonNull GenericDocument onUpgrade( 68 int currentVersion, int finalVersion, @NonNull GenericDocument document); 69 70 /** 71 * Migrates {@link GenericDocument} to an older version of {@link AppSearchSchema}. 72 * 73 * <p>This method will be invoked only if the {@link SetSchemaRequest} is setting a lower 74 * version number than the current {@link AppSearchSchema} saved in AppSearch. 75 * 76 * <p>If this {@link Migrator} is provided to cover a compatible schema change via {@link 77 * AppSearchSession#setSchema}, documents under the old version won't be removed unless you use 78 * the same document ID. 79 * 80 * <p>This method will be invoked on the background worker thread. 81 * 82 * @param currentVersion The current version of the document's schema. 83 * @param finalVersion The final version that documents need to be migrated to. 84 * @param document The {@link GenericDocument} need to be translated to new version. 85 * @return A {@link GenericDocument} in new version. 86 */ 87 @WorkerThread onDowngrade( int currentVersion, int finalVersion, @NonNull GenericDocument document)88 public abstract @NonNull GenericDocument onDowngrade( 89 int currentVersion, int finalVersion, @NonNull GenericDocument document); 90 } 91