@API(value=EXPERIMENTAL) public class MetaDataEvolutionValidator extends Object
Tuple
elements.optional
to required
.Index
es are consistent with the two meta-data versions.FormerIndex
.FormerIndex
es are consistent with the two meta-data versions.This is a relatively strict set of requirements that aims to allow anything written by a record store built with the old meta-data to be readable from record stores built with the new meta-data. Some of the validation rules, however, are stricter than necessary and are instead intended to prevent the user from accidentally changing the meta-data in a way that will require significant work. For example, it is assumed that any change that requires that an existing index be rebuilt is a mistake, but there are legitimate use cases for which this is actually the desired behavior. The user can disable those checks by creating a new validator and allowing laxer standards. For example, one can create a validator that allows format-incompatible changes to existing indexes by calling:
MetaDataEvolutionValidator.newBuilder()
.setAllowIndexRebuilds(true)
.build();
See the Schema Evolution Guidelines in our documentation for more details on what changes may be safely made to the meta-data and why.
Modifier and Type | Class and Description |
---|---|
static class |
MetaDataEvolutionValidator.Builder
A builder class for the
MetaDataEvolutionValidator . |
Modifier and Type | Method and Description |
---|---|
boolean |
allowsIndexRebuilds()
Whether this validator allows new meta-data that require existing indexes to be rebuilt.
|
boolean |
allowsMissingFormerIndexNames()
Whether this validator allows former indexes to drop the name of the index they replace.
|
boolean |
allowsNoSinceVersion()
Whether this validator allows new record types to not declare a "since version".
|
boolean |
allowsNoVersionChange()
Whether this validator allows the evolved meta-data to have the same version as the
old meta-data.
|
boolean |
allowsOlderFormerIndexAddedVersions()
Whether this validator allows former indexes to set their added version to something that is older than
necessary.
|
boolean |
allowsUnsplitToSplit()
Whether this validator allows the meta-data to begin to split long records.
|
MetaDataEvolutionValidator.Builder |
asBuilder()
Convert this validator into a builder.
|
boolean |
disallowsTypeRenames()
Whether this validator disallows record types from being renamed.
|
static MetaDataEvolutionValidator |
getDefaultInstance()
Get the default validator.
|
IndexMaintainerRegistry |
getIndexMaintainerRegistry()
Get the registry of index maintainers used to validate indexes.
|
static MetaDataEvolutionValidator.Builder |
newBuilder()
Create a new builder.
|
void |
validate(RecordMetaData oldMetaData,
RecordMetaData newMetaData)
Validate that the new meta-data has been safely evolved from an older version.
|
void |
validateUnion(Descriptors.Descriptor oldUnionDescriptor,
Descriptors.Descriptor newUnionDescriptor)
Validate that the record types have all been evolved in a legal way.
|
public void validate(@Nonnull RecordMetaData oldMetaData, @Nonnull RecordMetaData newMetaData)
oldMetaData
- the current meta-data for one or more record storesnewMetaData
- the new meta-data for the same record storespublic void validateUnion(@Nonnull Descriptors.Descriptor oldUnionDescriptor, @Nonnull Descriptors.Descriptor newUnionDescriptor)
oldUnionDescriptor
- the union descriptor for the existing meta-data for some record storenewUnionDescriptor
- the new proposed meta-data@Nonnull public IndexMaintainerRegistry getIndexMaintainerRegistry()
IndexMaintainerRegistryImpl
instance.FDBRecordStoreBase.BaseBuilder.setIndexMaintainerRegistry(IndexMaintainerRegistry)
public boolean allowsNoVersionChange()
false
as the assumption is that this validator
is only being called after the meta-data has been updated in some way, and it is good
practice to update the meta-data version in that instance.public boolean allowsNoSinceVersion()
false
.public boolean allowsIndexRebuilds()
false
as index rebuilds are expensive and the index
will not be queryable during the rebuild. The best practice if an index must be updated is to
create a new index with the change and then remove the index once the new index has been built.
This allows the old index to serve queries until such time as the new index is ready.public boolean allowsMissingFormerIndexNames()
FormerIndex
to replace an existing Index
where FormerIndex.getFormerName()
returns null
.
However, this can be a sign that some amount of information is being lost in the upgrade process,
so the default value for this option is false
, but users wanting more lenient validation can
set it to true
.public boolean allowsOlderFormerIndexAddedVersions()
FormerIndex
is used as an optimization at meta-data upgrade
time to decide not to clear the data for a former index if the index was both added and dropped since
the meta-data version was last updated. As a result, it is safe to include older versions than the
actual added version of the associated Index
within a FormerIndex
, but it might result
in extra work and could also be a sign of another problem. As a result, the default value of this option
is false
, but users wanting more lenient validation can set it to true
.public boolean allowsUnsplitToSplit()
SAVE_UNSPLIT_WITH_SUFFIX_FORMAT_VERSION
or newer, this change is safe as the data layout is the same regardless of the value of
RecordMetaData.isSplitLongRecords()
. However, older stores used a different format for if records were
unsplit, and accidentally upgrading the meta-data to split long records is potentially catastrophic as every
record in the store will now appear to be written under the wrong key. The default value of this option
is thus false
, but as the new format version has been the default since prior to version 2.0,
most users should be able set this to true
.public boolean disallowsTypeRenames()
@Nonnull public MetaDataEvolutionValidator.Builder asBuilder()
MetaDataEvoluationValidator.Builder
with the same options as this validator@Nonnull public static MetaDataEvolutionValidator.Builder newBuilder()
MetaDataEvoluationValidator.Builder
with all options set to their defaults@Nonnull public static MetaDataEvolutionValidator getDefaultInstance()