src.android.app.appsearch.Migrator Maven / Gradle / Ivy
Show all versions of android-all Show documentation
/*
* 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;
/**
* A migrator class to translate {@link GenericDocument} from different version of {@link
* AppSearchSchema}
*
* 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.
*
*
{@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.
*
*
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 {
/**
* Returns {@code true} if this migrator's source type needs to be migrated to update from
* currentVersion to finalVersion.
*
*
Migration won't be triggered if currentVersion is equal to finalVersion even if {@link
* #shouldMigrate} return true;
*/
public abstract boolean shouldMigrate(int currentVersion, int finalVersion);
/**
* Migrates {@link GenericDocument} to a newer version of {@link AppSearchSchema}.
*
*
This method will be invoked only if the {@link SetSchemaRequest} is setting a higher
* version number than the current {@link AppSearchSchema} saved in AppSearch.
*
*
If this {@link Migrator} is provided to cover a compatible schema change via {@link
* AppSearchSession#setSchema}, documents under the old version won't be removed unless you use
* the same document ID.
*
*
This method will be invoked on the background worker thread provided via {@link
* AppSearchSession#setSchema}.
*
* @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.
*/
@WorkerThread
@NonNull
public abstract GenericDocument onUpgrade(
int currentVersion, int finalVersion, @NonNull GenericDocument document);
/**
* Migrates {@link GenericDocument} to an older version of {@link AppSearchSchema}.
*
*
This method will be invoked only if the {@link SetSchemaRequest} is setting a lower
* version number than the current {@link AppSearchSchema} saved in AppSearch.
*
*
If this {@link Migrator} is provided to cover a compatible schema change via {@link
* AppSearchSession#setSchema}, documents under the old version won't be removed unless you use
* the same document ID.
*
*
This method will be invoked on the background worker thread.
*
* @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.
*/
@WorkerThread
@NonNull
public abstract GenericDocument onDowngrade(
int currentVersion, int finalVersion, @NonNull GenericDocument document);
}