SetSchemaRequest.Builder

public static final class SetSchemaRequest.Builder
extends Object

java.lang.Object
   ↳ androidx.appsearch.app.SetSchemaRequest.Builder


Builder for SetSchemaRequest objects.

Once build() is called, the instance can no longer be used.

Summary

Public constructors

Builder()

Public methods

SetSchemaRequest.Builder addDocumentClasses(Class...<?> documentClasses)

Adds one or more Document annotated classes to the schema.

SetSchemaRequest.Builder addDocumentClasses(Collection<? extends Class<?>> documentClasses)

Adds a collection of Document annotated classes to the schema.

SetSchemaRequest.Builder addSchemas(AppSearchSchema... schemas)

Adds one or more AppSearchSchema types to the schema.

SetSchemaRequest.Builder addSchemas(Collection<AppSearchSchema> schemas)

Adds a collection of AppSearchSchema objects to the schema.

SetSchemaRequest build()

Builds a new SetSchemaRequest object.

SetSchemaRequest.Builder setDocumentClassDisplayedBySystem(Class<?> documentClass, boolean displayed)

Sets whether or not documents from the provided Document annotated class will be displayed and visible on any system UI surface.

SetSchemaRequest.Builder setDocumentClassVisibilityForPackage(Class<?> documentClass, boolean visible, PackageIdentifier packageIdentifier)

Sets whether or not documents from the provided Document annotated class can be read by the specified package.

SetSchemaRequest.Builder setForceOverride(boolean forceOverride)

Sets whether or not to override the current schema in the AppSearchSession database.

SetSchemaRequest.Builder setMigrator(String schemaType, Migrator migrator)

Sets the Migrator associated with the given SchemaType.

SetSchemaRequest.Builder setMigrators(Map<String, Migrator> migrators)

Sets a Map of Migrators.

SetSchemaRequest.Builder setSchemaTypeDisplayedBySystem(String schemaType, boolean displayed)

Sets whether or not documents from the provided schemaType will be displayed and visible on any system UI surface.

SetSchemaRequest.Builder setSchemaTypeVisibilityForPackage(String schemaType, boolean visible, PackageIdentifier packageIdentifier)

Sets whether or not documents from the provided schemaType can be read by the specified package.

SetSchemaRequest.Builder setVersion(int version)

Sets the version number of the overall AppSearchSchema in the database.

Inherited methods

Public constructors

Builder

public Builder ()

Public methods

addDocumentClasses

public SetSchemaRequest.Builder addDocumentClasses (Class...<?> documentClasses)

Adds one or more Document annotated classes to the schema.

Parameters
documentClasses Class: classes annotated with Document.

Returns
SetSchemaRequest.Builder

Throws
AppSearchException if androidx.appsearch.compiler.AppSearchCompiler has not generated a schema for the given document classes.
IllegalStateException if the builder has already been used.

addDocumentClasses

public SetSchemaRequest.Builder addDocumentClasses (Collection<? extends Class<?>> documentClasses)

Adds a collection of Document annotated classes to the schema.

Parameters
documentClasses Collection: classes annotated with Document.

Returns
SetSchemaRequest.Builder

Throws
AppSearchException if androidx.appsearch.compiler.AppSearchCompiler has not generated a schema for the given document classes.
IllegalStateException if the builder has already been used.

addSchemas

public SetSchemaRequest.Builder addSchemas (AppSearchSchema... schemas)

Adds one or more AppSearchSchema types to the schema.

An AppSearchSchema object represents one type of structured data.

Any documents of these types will be displayed on system UI surfaces by default.

Parameters
schemas AppSearchSchema

Returns
SetSchemaRequest.Builder

Throws
IllegalStateException if the builder has already been used.

addSchemas

public SetSchemaRequest.Builder addSchemas (Collection<AppSearchSchema> schemas)

Adds a collection of AppSearchSchema objects to the schema.

An AppSearchSchema object represents one type of structured data.

Parameters
schemas Collection

Returns
SetSchemaRequest.Builder

Throws
IllegalStateException if the builder has already been used.

build

public SetSchemaRequest build ()

Builds a new SetSchemaRequest object.

Returns
SetSchemaRequest

Throws
IllegalArgumentException if schema types were referenced, but the corresponding AppSearchSchema type was never added.
IllegalStateException if the builder has already been used.

setDocumentClassDisplayedBySystem

public SetSchemaRequest.Builder setDocumentClassDisplayedBySystem (Class<?> documentClass, 
                boolean displayed)

Sets whether or not documents from the provided Document annotated class will be displayed and visible on any system UI surface.

This setting applies to the provided Document annotated class only, and does not persist across AppSearchSession.setSchema(SetSchemaRequest) calls.

The default behavior, if this method is not called, is to allow types to be displayed on system UI surfaces.

Parameters
documentClass Class: A class annotated with Document, the visibility of which will be configured

displayed boolean: Whether documents of this type will be displayed on system UI surfaces.

Returns
SetSchemaRequest.Builder

Throws
AppSearchException if androidx.appsearch.compiler.AppSearchCompiler has not generated a schema for the given document class.

setDocumentClassVisibilityForPackage

public SetSchemaRequest.Builder setDocumentClassVisibilityForPackage (Class<?> documentClass, 
                boolean visible, 
                PackageIdentifier packageIdentifier)

Sets whether or not documents from the provided Document annotated class can be read by the specified package.

Each package is represented by a PackageIdentifier, containing a package name and a byte array of type PackageManager.CERT_INPUT_SHA256.

To opt into one-way data sharing with another application, the developer will need to explicitly grant the other application’s package name and certificate Read access to its data.

For two-way data sharing, both applications need to explicitly grant Read access to one another.

By default, app data sharing between applications is disabled.

Parameters
documentClass Class: The Document class to set visibility on.

visible boolean: Whether the documentClass will be visible or not.

packageIdentifier PackageIdentifier: Represents the package that will be granted visibility.

Returns
SetSchemaRequest.Builder

Throws
AppSearchException if androidx.appsearch.compiler.AppSearchCompiler has not generated a schema for the given document class.

setForceOverride

public SetSchemaRequest.Builder setForceOverride (boolean forceOverride)

Sets whether or not to override the current schema in the AppSearchSession database.

Call this method whenever backward incompatible changes need to be made by setting forceOverride to true. As a result, during execution of the setSchema operation, all documents that are incompatible with the new schema will be deleted and the new schema will be saved and persisted.

By default, this is false.

Parameters
forceOverride boolean

Returns
SetSchemaRequest.Builder

setMigrator

public SetSchemaRequest.Builder setMigrator (String schemaType, 
                Migrator migrator)

Sets the Migrator associated with the given SchemaType.

The Migrator migrates all GenericDocuments under given schema type from the current version number stored in AppSearch to the final version set via setVersion(int).

A Migrator will be invoked if the current version number stored in AppSearch is different from the final version set via setVersion(int) and Migrator.shouldMigrate(int, int) returns true.

The target schema type of the output GenericDocument of Migrator.onUpgrade(int, int, GenericDocument) or Migrator.onDowngrade(int, int, GenericDocument) must exist in this SetSchemaRequest.

Parameters
schemaType String: The schema type to set migrator on.

migrator Migrator: The migrator translates a document from its current version to the final version set via setVersion(int).

Returns
SetSchemaRequest.Builder

setMigrators

public SetSchemaRequest.Builder setMigrators (Map<String, Migrator> migrators)

Sets a Map of Migrators.

The Migrator migrates all GenericDocuments under given schema type from the current version number stored in AppSearch to the final version set via setVersion(int).

A Migrator will be invoked if the current version number stored in AppSearch is different from the final version set via setVersion(int) and Migrator.shouldMigrate(int, int) returns true.

The target schema type of the output GenericDocument of Migrator.onUpgrade(int, int, GenericDocument) or Migrator.onDowngrade(int, int, GenericDocument) must exist in this SetSchemaRequest.

Parameters
migrators Map: A Map of migrators that translate a document from it's current version to the final version set via setVersion(int).

Returns
SetSchemaRequest.Builder

setSchemaTypeDisplayedBySystem

public SetSchemaRequest.Builder setSchemaTypeDisplayedBySystem (String schemaType, 
                boolean displayed)

Sets whether or not documents from the provided schemaType will be displayed and visible on any system UI surface.

This setting applies to the provided schemaType only, and does not persist across AppSearchSession.setSchema(SetSchemaRequest) calls.

The default behavior, if this method is not called, is to allow types to be displayed on system UI surfaces.

Parameters
schemaType String: The name of an AppSearchSchema within the same SetSchemaRequest, which will be configured.

displayed boolean: Whether documents of this type will be displayed on system UI surfaces.

Returns
SetSchemaRequest.Builder

Throws
IllegalStateException if the builder has already been used.

setSchemaTypeVisibilityForPackage

public SetSchemaRequest.Builder setSchemaTypeVisibilityForPackage (String schemaType, 
                boolean visible, 
                PackageIdentifier packageIdentifier)

Sets whether or not documents from the provided schemaType can be read by the specified package.

Each package is represented by a PackageIdentifier, containing a package name and a byte array of type PackageManager.CERT_INPUT_SHA256.

To opt into one-way data sharing with another application, the developer will need to explicitly grant the other application’s package name and certificate Read access to its data.

For two-way data sharing, both applications need to explicitly grant Read access to one another.

By default, data sharing between applications is disabled.

Parameters
schemaType String: The schema type to set visibility on.

visible boolean: Whether the schemaType will be visible or not.

packageIdentifier PackageIdentifier: Represents the package that will be granted visibility.

Returns
SetSchemaRequest.Builder

Throws
IllegalStateException if the builder has already been used.

setVersion

public SetSchemaRequest.Builder setVersion (int version)

Sets the version number of the overall AppSearchSchema in the database.

The AppSearchSession database can only ever hold documents for one version at a time.

Setting a version number that is different from the version number currently stored in AppSearch will result in AppSearch calling the Migrators provided to AppSearchSession.setSchema(SetSchemaRequest) to migrate the documents already in AppSearch from the previous version to the one set in this request. The version number can be updated without any other changes to the set of schemas.

The version number can stay the same, increase, or decrease relative to the current version number that is already stored in the AppSearchSession database.

Parameters
version int: A positive integer representing the version of the entire set of schemas represents the version of the whole schema in the AppSearchSession database, default version is 1.

Value is 1 or greater.

Returns
SetSchemaRequest.Builder

Throws
IllegalStateException if the version is negative or the builder has already been used.