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