com.apple.foundationdb.record

Class RecordMetaDataBuilder

java.lang.Object

com.apple.foundationdb.record.RecordMetaDataBuilder

All Implemented Interfaces:

RecordMetaDataProvider

@API(value=MAINTAINED)
public class RecordMetaDataBuilder
extends Object
implements RecordMetaDataProvider

A builder for RecordMetaData. Meta-data can be built in two ways.

From compiled .proto
Simple single field indexes and single field primary keys can be specified in the Protobuf source file using option extensions. Additional indexes or more complicated primary keys need to be specified with code using this builder. The setRecords(Descriptors.FileDescriptor, boolean) method loads the meta-data information from the Protobuf source file. Indexes and other properties such as version are not accessible before calling setRecords.

From a RecordMetaDataProto.MetaData Protobuf message
The Protobuf form can store the complete meta-data. The setRecords(RecordMetaDataProto.MetaData, boolean) method loads the Protobuf message. Similar to loading the meta-data directly from a Protobuf file descriptor, indexes and other properties are not accessible before calling setRecords. The Protobuf message may contain all of the dependencies required for resolving the record types and indexes. If some of the dependencies are missing (e.g., when a list of excluded dependencies is passed to RecordMetaData.toProto()), before calling setRecords, callers must first add the missing dependencies using addDependency(Descriptors.FileDescriptor) or addDependencies(Descriptors.FileDescriptor[]). The addDependency or addDependencies methods can also be used to override the embedded dependencies.

See Also:

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RecordMetaDataBuilder.MetaDataProtoDeserializationException Exception thrown when meta-data cannot be loaded from serialized form.

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_UNION_NAME

Constructor Summary

Constructors

Constructor and Description
RecordMetaDataBuilder(Descriptors.FileDescriptor fileDescriptor) Deprecated. use RecordMetaData.newBuilder() instead
RecordMetaDataBuilder(Descriptors.FileDescriptor fileDescriptor, boolean processExtensionOptions) Deprecated. use RecordMetaData.newBuilder() instead
RecordMetaDataBuilder(RecordMetaDataProto.MetaData metaDataProto) Deprecated. use RecordMetaData.newBuilder() instead
RecordMetaDataBuilder(RecordMetaDataProto.MetaData metaDataProto, boolean processExtensionOptions) Deprecated. use RecordMetaData.newBuilder() instead
RecordMetaDataBuilder(RecordMetaDataProto.MetaData metaDataProto, Descriptors.FileDescriptor[] dependencies) Deprecated. use RecordMetaData.newBuilder() instead
RecordMetaDataBuilder(RecordMetaDataProto.MetaData metaDataProto, Descriptors.FileDescriptor[] dependencies, boolean processExtensionOptions) Deprecated. use RecordMetaData.newBuilder() instead

Method Summary

Modifier and Type	Method and Description
RecordMetaDataBuilder	addDependencies(Descriptors.FileDescriptor[] fileDescriptors) Adds dependencies to be used for loading the RecordMetaData from a meta-data proto.
RecordMetaDataBuilder	addDependency(Descriptors.FileDescriptor fileDescriptor) Adds a dependency to the list of dependencies.
void	addFormerIndex(FormerIndex formerIndex)
void	addIndex(RecordTypeBuilder recordType, Index index) Adds a new index.
void	addIndex(String recordType, Index index) Adds a new index.
void	addIndex(String recordType, String fieldName) Adds a new index on a single field.
void	addIndex(String recordType, String indexName, KeyExpression indexExpression) Adds a new index.
void	addIndex(String recordType, String indexName, String fieldName) Adds a new index.
void	addMultiTypeIndex(List<RecordTypeBuilder> recordTypes, Index index) Adds a new index that contains multiple record types.
void	addUniversalIndex(Index index) Adds a new index on all record types.
RecordMetaData	build() Build and validate meta-data.
RecordMetaData	build(boolean validate) Build and validate meta-data with specific index registry.
static int[]	buildPrimaryKeyComponentPositions(KeyExpression indexKey, KeyExpression primaryKey)
RecordMetaDataBuilder	enableCounterBasedSubspaceKeys() Enable counter-based subspace keys assignment.
MetaDataEvolutionValidator	getEvolutionValidator() Get the validator used to compare the local file descriptor to the descriptor included in the meta-data proto.
Index	getIndex(String indexName)
IndexMaintainerRegistry	getIndexMaintainerRegistry() Get the index registry used for validation.
RecordTypeBuilder	getOnlyRecordType() If there is only one record type, get it.
KeyExpression	getRecordCountKey() Deprecated. use COUNT type indexes instead
RecordMetaData	getRecordMetaData() Provide an instance of RecordMetaData.
RecordTypeBuilder	getRecordType(String name)
long	getSubspaceKeyCounter() Get the current value of the index subspace key counter.
Descriptors.Descriptor	getUnionDescriptor()
Descriptors.FieldDescriptor	getUnionFieldForRecordType(RecordType recordType)
int	getVersion()
boolean	isSplitLongRecords()
boolean	isStoreRecordVersions()
void	removeIndex(String name)
RecordMetaDataBuilder	setEvolutionValidator(MetaDataEvolutionValidator evolutionValidator) Set the validator used to compare the local file descriptor to the descriptor included in the meta-data proto.
void	setIndexMaintainerRegistry(IndexMaintainerRegistry indexMaintainerRegistry) Set the index registry used for validation.
RecordMetaDataBuilder	setLocalFileDescriptor(Descriptors.FileDescriptor localFileDescriptor) Sets the local file descriptor.
void	setRecordCountKey(KeyExpression recordCountKey) Deprecated. use COUNT type indexes instead
RecordMetaDataBuilder	setRecords(Descriptors.FileDescriptor fileDescriptor) Adds the root file descriptor of the RecordMetaData and processes the extension options.
RecordMetaDataBuilder	setRecords(Descriptors.FileDescriptor fileDescriptor, boolean processExtensionOptions) Adds the root file descriptor of the RecordMetaData.
RecordMetaDataBuilder	setRecords(RecordMetaDataProto.MetaData metaDataProto) Deserializes the meta-data proto into the builder.
RecordMetaDataBuilder	setRecords(RecordMetaDataProto.MetaData metaDataProto, boolean processExtensionOptions) Deserializes the meta-data proto into the builder.
void	setSplitLongRecords(boolean splitLongRecords)
void	setStoreRecordVersions(boolean storeRecordVersions)
RecordMetaDataBuilder	setSubspaceKeyCounter(long subspaceKeyCounter) Set the initial value of the subspace key counter.
void	setVersion(int version)
void	updateRecords(Descriptors.FileDescriptor recordsDescriptor) Update the records descriptor of the record meta-data.
void	updateRecords(Descriptors.FileDescriptor recordsDescriptor, boolean processExtensionOptions) Update the records descriptor of the record meta-data.
boolean	usesSubspaceKeyCounter() Checks if counter-based subspace key assignment is used.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_UNION_NAME

public static final String DEFAULT_UNION_NAME

See Also:

Constant Field Values

Constructor Detail

RecordMetaDataBuilder

@Deprecated
public RecordMetaDataBuilder(@Nonnull
                                         Descriptors.FileDescriptor fileDescriptor)

Deprecated. use RecordMetaData.newBuilder() instead

Creates a new builder from the provided record types protobuf.

Parameters:

fileDescriptor - a file descriptor containing all the record types in the metadata

RecordMetaDataBuilder

@Deprecated
public RecordMetaDataBuilder(@Nonnull
                                         Descriptors.FileDescriptor fileDescriptor,
                                         boolean processExtensionOptions)

Deprecated. use RecordMetaData.newBuilder() instead

Creates a new builder from the provided record types protobuf.

Parameters:

fileDescriptor - a file descriptor containing all the record types in the metadata

processExtensionOptions - whether to add primary keys and indexes based on extensions in the protobuf

RecordMetaDataBuilder

@Deprecated
public RecordMetaDataBuilder(@Nonnull
                                         RecordMetaDataProto.MetaData metaDataProto)

Deprecated. use RecordMetaData.newBuilder() instead

Creates a new builder from the provided meta-data protobuf. This constructor assumes that metaDataProto is not the result of RecordMetaData.toProto() and will not already include all the indexes defined by any original extension options, so that they still need to be processed. If metaDataProto is the result of toProto and indexes also appear in extension options, a duplicate index error will result. In that case, RecordMetaDataBuilder(RecordMetaDataProto.MetaData, boolean) will be needed instead.

Parameters:

metaDataProto - the protobuf form of the meta-data

RecordMetaDataBuilder

@Deprecated
public RecordMetaDataBuilder(@Nonnull
                                         RecordMetaDataProto.MetaData metaDataProto,
                                         boolean processExtensionOptions)

Deprecated. use RecordMetaData.newBuilder() instead

Creates a new builder from the provided meta-data protobuf. If metaDataProto is the result of RecordMetaData.toProto(), it will already include all the indexes defined by any original extension options, so processExtensionOptions should be false.

Parameters:

metaDataProto - the protobuf form of the meta-data

processExtensionOptions - whether to add primary keys and indexes based on extensions in the protobuf

RecordMetaDataBuilder

@Deprecated
public RecordMetaDataBuilder(@Nonnull
                                         RecordMetaDataProto.MetaData metaDataProto,
                                         @Nonnull
                                         Descriptors.FileDescriptor[] dependencies)

Deprecated. use RecordMetaData.newBuilder() instead

Creates a new builder from the provided meta-data protobuf. This constructor assumes that metaDataProto is not the result of RecordMetaData.toProto() and will not already include all the indexes defined by any original extension options, so that they still need to be processed. If metaDataProto is the result of toProto and indexes also appear in extension options, a duplicate index error will result. In that case, RecordMetaDataBuilder(RecordMetaDataProto.MetaData, Descriptors.FileDescriptor[], boolean) will be needed instead.

Parameters:

metaDataProto - the protobuf form of the meta-data

dependencies - other files imported by the record types protobuf

RecordMetaDataBuilder

@Deprecated
public RecordMetaDataBuilder(@Nonnull
                                         RecordMetaDataProto.MetaData metaDataProto,
                                         @Nonnull
                                         Descriptors.FileDescriptor[] dependencies,
                                         boolean processExtensionOptions)

Deprecated. use RecordMetaData.newBuilder() instead

Creates a new builder from the provided meta-data protobuf. If metaDataProto is the result of RecordMetaData.toProto(), it will already include all the indexes defined by any original extension options, so processExtensionOptions should be false.

Parameters:

metaDataProto - the protobuf form of the meta-data

dependencies - other files imported by the record types protobuf

processExtensionOptions - whether to add primary keys and indexes based on extensions in the protobuf

Method Detail

setRecords

@Nonnull
public RecordMetaDataBuilder setRecords(@Nonnull
                                                 RecordMetaDataProto.MetaData metaDataProto)

Deserializes the meta-data proto into the builder. The extension options are not processed.

Parameters:

metaDataProto - the proto of the RecordMetaData

Returns:

this builder

setRecords

@Nonnull
public RecordMetaDataBuilder setRecords(@Nonnull
                                                 RecordMetaDataProto.MetaData metaDataProto,
                                                 boolean processExtensionOptions)

Deserializes the meta-data proto into the builder.

Parameters:

metaDataProto - the proto of the RecordMetaData

processExtensionOptions - whether to add primary keys and indexes based on extensions in the protobuf

Returns:

this builder

setRecords

@Nonnull
public RecordMetaDataBuilder setRecords(@Nonnull
                                                 Descriptors.FileDescriptor fileDescriptor)

Adds the root file descriptor of the RecordMetaData and processes the extension options.

Parameters:

fileDescriptor - the file descriptor of the record meta-data

Returns:

this builder

setRecords

@Nonnull
public RecordMetaDataBuilder setRecords(@Nonnull
                                                 Descriptors.FileDescriptor fileDescriptor,
                                                 boolean processExtensionOptions)

Adds the root file descriptor of the RecordMetaData.

Parameters:

fileDescriptor - the file descriptor of the record meta-data

processExtensionOptions - whether to add primary keys and indexes based on extensions in the protobuf

Returns:

this builder

updateRecords

public void updateRecords(@Nonnull
                          Descriptors.FileDescriptor recordsDescriptor)

Update the records descriptor of the record meta-data.

This involves adding new record types and updating descriptors for the existing record types and union fields. By contract, the extension options will be processed for all of the new record types and will not be processed for any of the old record types. Also, it is not allowed to call this method when the local file descriptor is set.

See updateRecords(Descriptors.FileDescriptor, boolean) for more information.

Parameters:

recordsDescriptor - the new record descriptor

updateRecords

public void updateRecords(@Nonnull
                          Descriptors.FileDescriptor recordsDescriptor,
                          boolean processExtensionOptions)

Update the records descriptor of the record meta-data.

This adds any new record types and updates the descriptors for existing record types. By contract, the extension options will not be processed for the old record types. If processExtensionOptions is set, extension options will be processed only for the new record types. Also, this method may not be called when localFileDescriptor is set. This method bumps the meta-data version and sets the since version for the new record types (and their indexes).

To avoid accidental changes, this method only updates the record types (i.e., updates the message descriptors of the old record types and adds new record types with their primary keys and indexes). This method does not process schema options. To update the schema options, use setSplitLongRecords(boolean) and setStoreRecordVersions(boolean).

Parameters:

recordsDescriptor - the new record descriptor

processExtensionOptions - whether to add primary keys and indexes using the extensions in the protobuf (only for the new record types)

setLocalFileDescriptor

@Nonnull
public RecordMetaDataBuilder setLocalFileDescriptor(@Nonnull
                                                             Descriptors.FileDescriptor localFileDescriptor)

Sets the local file descriptor. A local meta-data file descriptor may contain newer versions of record types or indexes.

This method is handy when two versions of the record meta-data are compatible (i.e., they follow the Record Layer guidelines on schema evolution), but their descriptors are not equal, e.g., a statically-generated proto and its serialized version stored in a meta-data store (i.e., FDBMetaDataStore). A record store created using the meta-data store may not be able to store a record created by the statically-generated proto file because the meta-data and record have mismatched descriptors. Using this method, the meta-data can use the same version of the descriptor as the record.

This should only be used when the records descriptor is set through a meta-data proto (i.e, it is followed by a call to setRecords(RecordMetaDataProto.MetaData) or setRecords(RecordMetaDataProto.MetaData, boolean)). This will not work if the records are set using a file descriptor.

To verify that the file descriptor supplied here and the file descriptor included in the meta-data proto are compatible, the two descriptors are compared using a MetaDataEvolutionValidator. The user may provide their own validator by calling setEvolutionValidator(MetaDataEvolutionValidator). By default, this will use that class's default instance.

Parameters:

localFileDescriptor - a file descriptor that contains updated record types

Returns:

this builder

addDependency

@Nonnull
public RecordMetaDataBuilder addDependency(@Nonnull
                                                    Descriptors.FileDescriptor fileDescriptor)

Adds a dependency to the list of dependencies. It will be used for loading the RecordMetaData from a meta-data proto.

Parameters:

fileDescriptor - the file descriptor of the dependency

Returns:

this builder

addDependencies

@Nonnull
public RecordMetaDataBuilder addDependencies(@Nonnull
                                                      Descriptors.FileDescriptor[] fileDescriptors)

Adds dependencies to be used for loading the RecordMetaData from a meta-data proto.

Parameters:

fileDescriptors - a list of dependencies

Returns:

this builder

getUnionDescriptor

@Nonnull
public Descriptors.Descriptor getUnionDescriptor()

getUnionFieldForRecordType

@Nonnull
public Descriptors.FieldDescriptor getUnionFieldForRecordType(@Nonnull
                                                                       RecordType recordType)

getRecordType

@Nonnull
public RecordTypeBuilder getRecordType(@Nonnull
                                                String name)

getIndex

@Nonnull
public Index getIndex(@Nonnull
                               String indexName)

addIndex

public void addIndex(@Nullable
                     RecordTypeBuilder recordType,
                     @Nonnull
                     Index index)

Adds a new index. This index can either be a universal index or an index for a single record type.

Parameters:

recordType - if null this index will exist for all record types

index - the index to be added

addIndex

public void addIndex(@Nonnull
                     String recordType,
                     @Nonnull
                     Index index)

Adds a new index.

Parameters:

recordType - name of the record type

index - the index to be added

addIndex

public void addIndex(@Nonnull
                     String recordType,
                     @Nonnull
                     String indexName,
                     @Nonnull
                     KeyExpression indexExpression)

Adds a new index.

Parameters:

recordType - name of the record type

indexName - the name of the new index

indexExpression - the root expression of the new index

addIndex

public void addIndex(@Nonnull
                     String recordType,
                     @Nonnull
                     String indexName,
                     @Nonnull
                     String fieldName)

Adds a new index.

Parameters:

recordType - name of the record type

indexName - the name of the new index

fieldName - the record field to be indexed

addIndex

public void addIndex(@Nonnull
                     String recordType,
                     @Nonnull
                     String fieldName)

Adds a new index on a single field.

Parameters:

recordType - name of the record type

fieldName - the record field to be indexed

addMultiTypeIndex

public void addMultiTypeIndex(@Nullable
                              List<RecordTypeBuilder> recordTypes,
                              @Nonnull
                              Index index)

Adds a new index that contains multiple record types. If the list is null or empty, the resulting index will include all record types. If the list has one element it will just be a normal single record type index.

Parameters:

recordTypes - a list of record types that the index will include

index - the index to be added

addUniversalIndex

public void addUniversalIndex(@Nonnull
                              Index index)

Adds a new index on all record types.

Parameters:

index - the index to be added

removeIndex

public void removeIndex(@Nonnull
                        String name)

addFormerIndex

public void addFormerIndex(@Nonnull
                           FormerIndex formerIndex)

isSplitLongRecords

public boolean isSplitLongRecords()

setSplitLongRecords

public void setSplitLongRecords(boolean splitLongRecords)

isStoreRecordVersions

public boolean isStoreRecordVersions()

setStoreRecordVersions

public void setStoreRecordVersions(boolean storeRecordVersions)

getRecordCountKey

@Nullable
 @Deprecated
 @API(value=DEPRECATED)
public KeyExpression getRecordCountKey()

Deprecated. use COUNT type indexes instead

Get the record count key, if any.

Returns:

the record count key of null

setRecordCountKey

@Deprecated
 @API(value=DEPRECATED)
public void setRecordCountKey(KeyExpression recordCountKey)

Deprecated. use COUNT type indexes instead

Set the key used for maintaining record counts.

Parameters:

recordCountKey - grouping key for counting

getVersion

public int getVersion()

setVersion

public void setVersion(int version)

enableCounterBasedSubspaceKeys

@Nonnull
public RecordMetaDataBuilder enableCounterBasedSubspaceKeys()

Enable counter-based subspace keys assignment.

If enabled, index subspace keys will be set using a counter instead of defaulting to the indexes' names. This must be called prior to setting the records descriptor (for example setRecords(Descriptors.FileDescriptor)).

Existing clients should be careful about enabling this feature. The name of an index is the default value of its subspace key when counter-based subspace keys are disabled. If a subspace key was not set explicitly before, enabling the counter-based scheme will change the index's subspace key. Note that it is important that the subspace key of an index that has data does not change. See Index.setSubspaceKey(Object) for more details.

Returns:

this builder

usesSubspaceKeyCounter

public boolean usesSubspaceKeyCounter()

Checks if counter-based subspace key assignment is used.

Returns:

true if the subspace key counter is used

getSubspaceKeyCounter

public long getSubspaceKeyCounter()

Get the current value of the index subspace key counter. If it is not enabled, the value will be 0.

Returns:

the current value of the index subspace key counter

See Also:

enableCounterBasedSubspaceKeys()

setSubspaceKeyCounter

@Nonnull
public RecordMetaDataBuilder setSubspaceKeyCounter(long subspaceKeyCounter)

Set the initial value of the subspace key counter. This method can be handy when users want to assign subspace keys using a counter, but their indexes already have subspace keys that may conflict with the counter-based assignment.

Note that the new counter must be greater than the current value. Also, users must first enable this feature by calling enableCounterBasedSubspaceKeys() before updating the counter value.

Parameters:

subspaceKeyCounter - the new value

Returns:

this builder

See Also:

enableCounterBasedSubspaceKeys()

getOnlyRecordType

@Nonnull
public RecordTypeBuilder getOnlyRecordType()

If there is only one record type, get it.

Returns:

the only type defined for this store.

getIndexMaintainerRegistry

@Nonnull
public IndexMaintainerRegistry getIndexMaintainerRegistry()

Get the index registry used for validation.

Returns:

the index maintainer registry

setIndexMaintainerRegistry

public void setIndexMaintainerRegistry(@Nonnull
                                       IndexMaintainerRegistry indexMaintainerRegistry)

Set the index registry used for validation. If a record store has a custom index maintainer registry, that same registry may need to be used to properly validate the meta-data.

Parameters:

indexMaintainerRegistry - the index maintainer registry

See Also:

FDBRecordStoreBase.BaseBuilder.setIndexMaintainerRegistry(com.apple.foundationdb.record.provider.foundationdb.IndexMaintainerRegistry)

getEvolutionValidator

@Nonnull
public MetaDataEvolutionValidator getEvolutionValidator()

Get the validator used to compare the local file descriptor to the descriptor included in the meta-data proto. By default, this instance is set to the MetaDataEvolutionValidator's default instance, but the user may provide their own through setEvolutionValidator(MetaDataEvolutionValidator) if they want to tweak certain validator options.

Returns:

the validator used to check the local file descriptor against the one in the meta-data proto

See Also:

setLocalFileDescriptor(Descriptors.FileDescriptor), MetaDataEvolutionValidator

setEvolutionValidator

@Nonnull
public RecordMetaDataBuilder setEvolutionValidator(@Nonnull
                                                            MetaDataEvolutionValidator evolutionValidator)

Set the validator used to compare the local file descriptor to the descriptor included in the meta-data proto. As this validator is used only to check whether the local file descriptor is compatible with the records descriptor set in setRecords() through the meta-data proto, this method must be called before setRecords().

Parameters:

evolutionValidator - the validator used to check the local file descriptor against the one in the meta-data proto

Returns:

this builder

See Also:

setLocalFileDescriptor(Descriptors.FileDescriptor), MetaDataEvolutionValidator

getRecordMetaData

@Nonnull
public RecordMetaData getRecordMetaData()

Description copied from interface: RecordMetaDataProvider

Provide an instance of RecordMetaData. Implementors should assume that this method will be called frequently, so it may be necessary to cache the result if generating the RecordMetaData is expensive.

Specified by:

getRecordMetaData in interface RecordMetaDataProvider

Returns:

an instance of RecordMetaData

build

@Nonnull
public RecordMetaData build()

Build and validate meta-data.

Returns:

new validated meta-data

build

@Nonnull
public RecordMetaData build(boolean validate)

Build and validate meta-data with specific index registry.

Parameters:

validate - true to validate the new meta-data

Returns:

new meta-data

buildPrimaryKeyComponentPositions

@Nullable
public static int[] buildPrimaryKeyComponentPositions(@Nonnull
                                                                KeyExpression indexKey,
                                                                @Nonnull
                                                                KeyExpression primaryKey)