Migrator


public abstract class Migrator
extends Object

java.lang.Object
   ↳ android.app.appsearch.Migrator


A migrator class to translate GenericDocument from different version of AppSearchSchema

Make non-backwards-compatible changes will delete all stored documents in old schema. You can save your documents by setting Migrator via the SetSchemaRequest.Builder.setMigrator(String, Migrator) for each type and target version you want to save.

onDowngrade(int, int, GenericDocument) or onUpgrade(int, int, GenericDocument) 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 onDowngrade(int, int, GenericDocument) or onUpgrade(int, int, GenericDocument), all the setSchema request will be rejected unless the schema changes are backwards-compatible, and stored documents won't have any observable changes.

Summary

Public constructors

Migrator()

Public methods

abstract GenericDocument onDowngrade(int currentVersion, int finalVersion, GenericDocument document)

Migrates GenericDocument to an older version of AppSearchSchema.

abstract GenericDocument onUpgrade(int currentVersion, int finalVersion, GenericDocument document)

Migrates GenericDocument to a newer version of AppSearchSchema.

abstract boolean shouldMigrate(int currentVersion, int finalVersion)

Returns true if this migrator's source type needs to be migrated to update from currentVersion to finalVersion.

Inherited methods

Object clone()

Creates and returns a copy of this object.

boolean equals(Object obj)

Indicates whether some other object is "equal to" this one.

void finalize()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

final Class<?> getClass()

Returns the runtime class of this Object.

int hashCode()

Returns a hash code value for the object.

final void notify()

Wakes up a single thread that is waiting on this object's monitor.

final void notifyAll()

Wakes up all threads that are waiting on this object's monitor.

String toString()

Returns a string representation of the object.

final void wait(long timeoutMillis, int nanos)

Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

final void wait(long timeoutMillis)

Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

final void wait()

Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Public constructors

Migrator

Added in API level 31
public Migrator ()

Public methods

onDowngrade

Added in API level 31
public abstract GenericDocument onDowngrade (int currentVersion, 
                int finalVersion, 
                GenericDocument document)

Migrates GenericDocument to an older version of AppSearchSchema.

This method will be invoked only if the SetSchemaRequest is setting a lower version number than the current AppSearchSchema saved in AppSearch.

If this Migrator is provided to cover a compatible schema change via AppSearchSession.setSchema(SetSchemaRequest, Executor, Executor, Consumer), 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.
This method may take several seconds to complete, so it should only be called from a worker thread.

Parameters
currentVersion int: The current version of the document's schema.

finalVersion int: The final version that documents need to be migrated to.

document GenericDocument: The GenericDocument need to be translated to new version. This value cannot be null.

Returns
GenericDocument A GenericDocument in new version. This value cannot be null.

onUpgrade

Added in API level 31
public abstract GenericDocument onUpgrade (int currentVersion, 
                int finalVersion, 
                GenericDocument document)

Migrates GenericDocument to a newer version of AppSearchSchema.

This method will be invoked only if the SetSchemaRequest is setting a higher version number than the current AppSearchSchema saved in AppSearch.

If this Migrator is provided to cover a compatible schema change via AppSearchSession.setSchema(SetSchemaRequest, Executor, Executor, Consumer), 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 AppSearchSession.setSchema(SetSchemaRequest, Executor, Executor, Consumer).
This method may take several seconds to complete, so it should only be called from a worker thread.

Parameters
currentVersion int: The current version of the document's schema.

finalVersion int: The final version that documents need to be migrated to.

document GenericDocument: The GenericDocument need to be translated to new version. This value cannot be null.

Returns
GenericDocument A GenericDocument in new version. This value cannot be null.

shouldMigrate

Added in API level 31
public abstract boolean shouldMigrate (int currentVersion, 
                int finalVersion)

Returns 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 shouldMigrate(int, int) return true;

Parameters
currentVersion int

finalVersion int

Returns
boolean