Migrator

  • Migrator is an abstract class used to translate GenericDocument objects between different versions of AppSearchSchema.

  • Non-backwards-compatible schema changes without a migrator will delete all old documents.

  • Migration methods onDowngrade or onUpgrade are triggered when the schema version in AppSearch differs from the requested version.

  • Any error in onDowngrade or onUpgrade will reject the setSchema request for non-backwards-compatible changes.

  • The shouldMigrate method determines if a specific schema version update requires migration.
public abstract class Migrator extends Object

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.

Public Constructor Summary

Migrator()

Public Method Summary

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 Method Summary

Public Constructors

public Migrator ()

Public Methods

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 AppSearchClient.setSchema(SetSchemaRequest, String), 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.

Parameters
currentVersion The current version of the document's schema.
finalVersion The final version that documents need to be migrated to.
document The GenericDocument need to be translated to new version.
Returns

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 AppSearchClient.setSchema(SetSchemaRequest, String), 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 AppSearchClient.setSchema(SetSchemaRequest, String).

Parameters
currentVersion The current version of the document's schema.
finalVersion The final version that documents need to be migrated to.
document The GenericDocument need to be translated to new version.
Returns

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;