Top Description Inners Constructors Methods
org.apache.avro

public Class Resolver

extends Object
Class Inheritance
Imports
java.util.HashMap, .List, .Map, org.apache.avro.generic.GenericData, org.apache.avro.Schema.Field, .Schema.SeenPair, .Resolver.ErrorAction.ErrorType

Encapsulate schema-resolution logic in an easy-to-consume representation. See resolve and also the separate document entitled refactoring-resolution for more information. It might also be helpful to study org.apache.avro.io.parsing.ResolvingGrammarGenerator as an example of how to use this class.

Nested and Inner Type Summary

Modifier and TypeClass and Description
public abstract static class
Resolver.Action

An abstract class for an action to be taken to resolve a writer's schema (found in public instance variable writer) against a reader's schema (in reader).

public static class
Resolver.Container

Used for array and map schemas: the public instance variable elementAction contains the resolving action needed for the element type of an array or value top of a map.

public static class
Resolver.DoNothing

In this case, there's nothing to be done for resolution: the two schemas are effectively the same.

public static class
Resolver.EnumAdjust

Contains information needed to resolve enumerations.

public static class
Resolver.ErrorAction

In this case there is an error.

public static class
Resolver.Promote

In this case, the writer's type needs to be promoted to the reader's.

public static class
Resolver.ReaderUnion

In this case, the reader is a union and the writer is not.

public static class
Resolver.RecordAdjust

Instructions for resolving two record schemas.

public static class
Resolver.Skip

This only appears inside RecordAdjust#fieldActions, i.e., the actions for adjusting the fields of a record.

public static class
Resolver.WriterUnion

In this case, the writer was a union.

Constructor Summary

AccessConstructor and Description
public

Method Summary

Modifier and TypeMethod and Description
public static Resolver.Action

Returns:

Nested actions for resolving the two
resolve
(Schema
The schema used by the writer
writer
,
Schema
The schema used by the reader
reader
,
GenericData
Used for getDefaultValue and getting conversions
data
)

Returns a Resolver.Action tree for resolving the writer schema writer and the reader schema reader.

public static Resolver.Action
resolve(Schema writer, Schema reader)

Uses GenericData.get() for the data param.

private static Resolver.Action
private static boolean
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

Resolverback to summary
public Resolver()

Method Detail

resolveback to summary
public static Resolver.Action resolve(Schema writer, Schema reader, GenericData data)

Returns a Resolver.Action tree for resolving the writer schema writer and the reader schema reader. This method walks the reader's and writer's schemas together, generating an appropriate subclass of Action to encapsulate the information needed to resolve the corresponding parts of each schema tree. For convenience, every Action object has a pointer to the corresponding parts of the reader's and writer's trees being resolved by the action. Each subclass of Action has additional information needed for different types of schema, e.g., the EnumAdjust subclass has information about re-ordering and deletion of enumeration symbols, while RecordAdjust has information about re-ordering and deletion of record fields. Note that aliases are applied to the writer's schema before resolution actually takes place. This means that the writer field of the resulting Action objects will not be the same schema as provided to this method. However, the reader field will be.

Parameters
writer:Schema

The schema used by the writer

reader:Schema

The schema used by the reader

data:GenericData

Used for getDefaultValue and getting conversions

Returns:Resolver.Action

Nested actions for resolving the two

resolveback to summary
public static Resolver.Action resolve(Schema writer, Schema reader)

Uses GenericData.get() for the data param.

resolveback to summary
private static Resolver.Action resolve(Schema w, Schema r, GenericData d, Map<Schema.SeenPair, Resolver.Action> seen)
unionEquivback to summary
private static boolean unionEquiv(Schema write, Schema read, Map<Schema.SeenPair, Boolean> seen)
org.apache.avro back to summary

public abstract Class Resolver.Action

extends Object
Class Inheritance
Known Direct Subclasses
org.apache.avro.Resolver.DoNothing, org.apache.avro.Resolver.ErrorAction, org.apache.avro.Resolver.Promote, org.apache.avro.Resolver.Container, org.apache.avro.Resolver.EnumAdjust, org.apache.avro.Resolver.Skip, org.apache.avro.Resolver.RecordAdjust, org.apache.avro.Resolver.WriterUnion, org.apache.avro.Resolver.ReaderUnion

An abstract class for an action to be taken to resolve a writer's schema (found in public instance variable writer) against a reader's schema (in reader). Ordinarily, neither field can be null, except that the reader field can be null in a Skip, which is used to skip a field in a writer's record that doesn't exist in the reader's (and thus there is no reader schema to resolve to).

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static enum
Resolver.Action.Type

Helps us traverse faster.

Field Summary

Modifier and TypeField and Description
public final Conversion<?>
conversion

If the reader has a conversion that needs to be applied, it's stored here for fast access, otherwise this will be null.

public final LogicalType
logicalType

If the reader has a logical type, it's stored here for fast access, otherwise this will be null.

public final Schema
public final Resolver.Action.Type
public final Schema

Constructor Summary

AccessConstructor and Description
protected

Method Summary

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

conversionback to summary
public final Conversion<?> conversion

If the reader has a conversion that needs to be applied, it's stored here for fast access, otherwise this will be null.

logicalTypeback to summary
public final LogicalType logicalType

If the reader has a logical type, it's stored here for fast access, otherwise this will be null.

readerback to summary
public final Schema reader
typeback to summary
public final Resolver.Action.Type type
writerback to summary
public final Schema writer

Constructor Detail

Actionback to summary
protected Action(Schema w, Schema r, GenericData data, Resolver.Action.Type t)
org.apache.avro back to summary

public final Enum Resolver.Action.Type

extends Enum<Resolver.Action.Type>
Class Inheritance

Helps us traverse faster.

Field Summary

Modifier and TypeField and Description
public static final Resolver.Action.Type
public static final Resolver.Action.Type
public static final Resolver.Action.Type
public static final Resolver.Action.Type
public static final Resolver.Action.Type
public static final Resolver.Action.Type
public static final Resolver.Action.Type
public static final Resolver.Action.Type
public static final Resolver.Action.Type

Constructor Summary

AccessConstructor and Description
private
Type()

Method Summary

Modifier and TypeMethod and Description
public static Resolver.Action.Type
public static Resolver.Action.Type[]
Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

CONTAINERback to summary
public static final Resolver.Action.Type CONTAINER
DO_NOTHINGback to summary
public static final Resolver.Action.Type DO_NOTHING
ENUMback to summary
public static final Resolver.Action.Type ENUM
ERRORback to summary
public static final Resolver.Action.Type ERROR
PROMOTEback to summary
public static final Resolver.Action.Type PROMOTE
READER_UNIONback to summary
public static final Resolver.Action.Type READER_UNION
RECORDback to summary
public static final Resolver.Action.Type RECORD
SKIPback to summary
public static final Resolver.Action.Type SKIP
WRITER_UNIONback to summary
public static final Resolver.Action.Type WRITER_UNION

Constructor Detail

Typeback to summary
private Type()

Method Detail

valueOfback to summary
public static Resolver.Action.Type valueOf(String name)
valuesback to summary
public static Resolver.Action.Type[] values()
org.apache.avro back to summary

public Class Resolver.Container

extends Action
Class Inheritance

Used for array and map schemas: the public instance variable elementAction contains the resolving action needed for the element type of an array or value top of a map.

Field Summary

Modifier and TypeField and Description
public final Resolver.Action
Inherited from org.apache.avro.Resolver.Action:
conversionlogicalTypereadertypewriter

Constructor Summary

AccessConstructor and Description
public

Field Detail

elementActionback to summary
public final Resolver.Action elementAction

Constructor Detail

Containerback to summary
public Container(Schema w, Schema r, GenericData d, Resolver.Action e)
org.apache.avro back to summary

public Class Resolver.DoNothing

extends Action
Class Inheritance

In this case, there's nothing to be done for resolution: the two schemas are effectively the same. This action will be generated only for primitive types and fixed types, and not for any other kind of schema.

Field Summary

Inherited from org.apache.avro.Resolver.Action:
conversionlogicalTypereadertypewriter

Constructor Summary

AccessConstructor and Description
public

Constructor Detail

DoNothingback to summary
public DoNothing(Schema w, Schema r, GenericData d)
org.apache.avro back to summary

public Class Resolver.EnumAdjust

extends Action
Class Inheritance

Contains information needed to resolve enumerations. When resolving enums, adjustments need to be made in two scenarios: the index for an enum symbol might be different in the reader or writer, or the reader might not have a symbol that was written out for the writer (which is an error, but one we can only detect when decoding data). These adjustments are reflected in the instance variable adjustments. For the symbol with index i in the writer's enum definition, adjustments[i] -- and integer -- contains the adjustment for that symbol. If the integer is positive, then reader also has the symbol and the integer is its index in the reader's schema. If adjustment[i] is negative, then the reader does not have the corresponding symbol (which is the error case). Sometimes there's no adjustments needed: all symbols in the reader have the same index in the reader's and writer's schema. This is a common case, and it allows for some optimization. To signal that this is the case, noAdjustmentsNeeded is set to true.

Field Summary

Modifier and TypeField and Description
public final int[]
public final boolean
public final Object[]
Inherited from org.apache.avro.Resolver.Action:
conversionlogicalTypereadertypewriter

Constructor Summary

AccessConstructor and Description
private
EnumAdjust(Schema w, Schema r, GenericData d, int[] adj, Object[] values)

Method Summary

Modifier and TypeMethod and Description
public static Resolver.Action
resolve(Schema w, Schema r, GenericData d)

If writer and reader don't have same name, a ErrorAction.ErrorType#NAMES_DONT_MATCH is returned, otherwise an appropriate EnumAdjust is.

Field Detail

adjustmentsback to summary
public final int[] adjustments
noAdjustmentsNeededback to summary
public final boolean noAdjustmentsNeeded
valuesback to summary
public final Object[] values

Constructor Detail

EnumAdjustback to summary
private EnumAdjust(Schema w, Schema r, GenericData d, int[] adj, Object[] values)

Method Detail

resolveback to summary
public static Resolver.Action resolve(Schema w, Schema r, GenericData d)

If writer and reader don't have same name, a ErrorAction.ErrorType#NAMES_DONT_MATCH is returned, otherwise an appropriate EnumAdjust is.

org.apache.avro back to summary

public Class Resolver.ErrorAction

extends Action
Class Inheritance

In this case there is an error. We put error Actions into trees because Avro reports these errors in a lazy fashion: if a particular input doesn't "tickle" the error (typically because it's in a branch of a union that isn't found in the data being read), then it's safe to ignore it.

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static enum

Field Summary

Modifier and TypeField and Description
public final Resolver.ErrorAction.ErrorType
Inherited from org.apache.avro.Resolver.Action:
conversionlogicalTypereadertypewriter

Constructor Summary

AccessConstructor and Description
public

Method Summary

Modifier and TypeMethod and Description
public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.

Field Detail

errorback to summary
public final Resolver.ErrorAction.ErrorType error

Constructor Detail

ErrorActionback to summary
public ErrorAction(Schema w, Schema r, GenericData d, Resolver.ErrorAction.ErrorType e)

Method Detail

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object.

Annotations
@Override
org.apache.avro back to summary

public final Enum Resolver.ErrorAction.ErrorType

extends Enum<Resolver.ErrorAction.ErrorType>
Class Inheritance

Field Summary

Modifier and TypeField and Description
public static final Resolver.ErrorAction.ErrorType
INCOMPATIBLE_SCHEMA_TYPES

Use when Schema types don't match and can't be converted.

public static final Resolver.ErrorAction.ErrorType
MISSING_REQUIRED_FIELD

Use when matching two records and the reader has a field with no default value and that field is missing in the writer..

public static final Resolver.ErrorAction.ErrorType
NAMES_DONT_MATCH

Use when Schema types match but, in the case of record, enum, or fixed, the names don't match.

public static final Resolver.ErrorAction.ErrorType
NO_MATCHING_BRANCH

Use when matching a reader's union against a non-union and can't find a branch that matches.

public static final Resolver.ErrorAction.ErrorType
SIZES_DONT_MATCH

Use when two fixed types match and their names match by their sizes don't.

Constructor Summary

AccessConstructor and Description
private

Field Detail

INCOMPATIBLE_SCHEMA_TYPESback to summary
public static final Resolver.ErrorAction.ErrorType INCOMPATIBLE_SCHEMA_TYPES

Use when Schema types don't match and can't be converted. For example, resolving "int" and "enum".

MISSING_REQUIRED_FIELDback to summary
public static final Resolver.ErrorAction.ErrorType MISSING_REQUIRED_FIELD

Use when matching two records and the reader has a field with no default value and that field is missing in the writer..

NAMES_DONT_MATCHback to summary
public static final Resolver.ErrorAction.ErrorType NAMES_DONT_MATCH

Use when Schema types match but, in the case of record, enum, or fixed, the names don't match.

NO_MATCHING_BRANCHback to summary
public static final Resolver.ErrorAction.ErrorType NO_MATCHING_BRANCH

Use when matching a reader's union against a non-union and can't find a branch that matches.

SIZES_DONT_MATCHback to summary
public static final Resolver.ErrorAction.ErrorType SIZES_DONT_MATCH

Use when two fixed types match and their names match by their sizes don't.

Constructor Detail

ErrorTypeback to summary
private ErrorType()

Method Detail

valueOfback to summary
public static Resolver.ErrorAction.ErrorType valueOf(String name)
valuesback to summary
public static Resolver.ErrorAction.ErrorType[] values()
org.apache.avro back to summary

public Class Resolver.Promote

extends Action
Class Inheritance

In this case, the writer's type needs to be promoted to the reader's. These are constructed by Promote#resolve, which will only construct one when the writer's and reader's schemas are different (ie, no "self promotion"), and whent the promotion is one allowed by the Avro spec.

Field Summary

Inherited from org.apache.avro.Resolver.Action:
conversionlogicalTypereadertypewriter

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public static boolean
isValid(Schema w, Schema r)

Returns true iff w and r are both primitive types and either they are the same type or w is promotable to r.

public static Resolver.Action

Returns:

a Promote schema if the two schemas are compatible, or ErrorType#INCOMPATIBLE_SCHEMA_TYPES if they are not.
resolve
(Schema
Writer's schema
w
,
Schema
Rearder's schema
r
,
GenericData d)

Return a promotion.

Constructor Detail

Promoteback to summary
private Promote(Schema w, Schema r, GenericData d)

Method Detail

isValidback to summary
public static boolean isValid(Schema w, Schema r)

Returns true iff w and r are both primitive types and either they are the same type or w is promotable to r. Should

resolveback to summary
public static Resolver.Action resolve(Schema w, Schema r, GenericData d)

Return a promotion.

Parameters
w:Schema

Writer's schema

r:Schema

Rearder's schema

Returns:Resolver.Action

a Promote schema if the two schemas are compatible, or ErrorType#INCOMPATIBLE_SCHEMA_TYPES if they are not.

Exceptions
IllegalArgumentException:
if getType() of the two schemas are not different.
org.apache.avro back to summary

public Class Resolver.ReaderUnion

extends Action
Class Inheritance

In this case, the reader is a union and the writer is not. For this case, we need to pick the first branch of the reader that matches the writer and pretend to the reader that the index of this branch was found in the writer's data stream. To support this case, the ReaderUnion object has two (public) fields: firstMatch gives the index of the first matching branch in the reader's schema, and actualResolution is the Action that resolves the writer's schema with the schema found in the firstMatch branch of the reader's schema.

Field Summary

Modifier and TypeField and Description
public final Resolver.Action
public final int
Inherited from org.apache.avro.Resolver.Action:
conversionlogicalTypereadertypewriter

Constructor Summary

AccessConstructor and Description
public
ReaderUnion(Schema w, Schema r, GenericData d, int firstMatch, Resolver.Action actual)

Method Summary

Modifier and TypeMethod and Description
private static int
private static boolean
public static Resolver.Action
resolve(Schema w, Schema r, GenericData d, Map<Schema.SeenPair, Resolver.Action> seen)

Returns a ReaderUnion action for resolving w and r, or an ErrorAction if there is no branch in the reader that matches the writer.

Field Detail

actualActionback to summary
public final Resolver.Action actualAction
firstMatchback to summary
public final int firstMatch

Constructor Detail

ReaderUnionback to summary
public ReaderUnion(Schema w, Schema r, GenericData d, int firstMatch, Resolver.Action actual)

Method Detail

firstMatchingBranchback to summary
private static int firstMatchingBranch(Schema w, Schema r, GenericData d, Map<Schema.SeenPair, Resolver.Action> seen)
hasMatchErrorback to summary
private static boolean hasMatchError(Resolver.Action action)
resolveback to summary
public static Resolver.Action resolve(Schema w, Schema r, GenericData d, Map<Schema.SeenPair, Resolver.Action> seen)

Returns a ReaderUnion action for resolving w and r, or an ErrorAction if there is no branch in the reader that matches the writer.

Exceptions
RuntimeException:
if r is not a union schema or w is a union schema
org.apache.avro back to summary

public Class Resolver.RecordAdjust

extends Action
Class Inheritance

Instructions for resolving two record schemas. Includes instructions on how to recursively resolve each field, an indication of when to skip (writer fields), plus information about which reader fields should be populated by defaults (because the writer doesn't have corresponding fields).

Field Summary

Modifier and TypeField and Description
public final Object[]
defaults

Contains the default values to be used for the last readerOrder.length-firstDefault fields in rearderOrder.

public final Resolver.Action[]
fieldActions

An action for each field of the writer.

public final int
firstDefault

Pointer into RecordAdjust#readerOrder of the first reader field whose value comes from a default value.

public final GenericData.InstanceSupplier
instanceSupplier

Supplier that offers an optimized alternative to data.newRecord()

public final Schema.Field[]
readerOrder

Contains (all of) the reader's fields.

Inherited from org.apache.avro.Resolver.Action:
conversionlogicalTypereadertypewriter

Constructor Summary

AccessConstructor and Description
private
RecordAdjust(Schema w, Schema r, GenericData d, Resolver.Action[] fa, Schema.Field[] ro, int firstD, Object[] defaults)

Method Summary

Modifier and TypeMethod and Description
public boolean
noReorder()

Returns true iff i == readerOrder[i].pos() for all indices i.

pack-priv static Resolver.Action
resolve(Schema writeSchema, Schema readSchema, GenericData data, Map<Schema.SeenPair, Resolver.Action> seen)

Returns a RecordAdjust for the two schemas, or an ErrorAction if there was a problem resolving.

Field Detail

defaultsback to summary
public final Object[] defaults

Contains the default values to be used for the last readerOrder.length-firstDefault fields in rearderOrder. The ith element of defaults is the default value for the i+firstDefault member of readerOrder.

fieldActionsback to summary
public final Resolver.Action[] fieldActions

An action for each field of the writer. If the corresponding field is to be skipped during reading, then this will contain a Skip. For fields to be read into the reading datum, will contain a regular action for resolving the writer/reader schemas of the matching fields.

firstDefaultback to summary
public final int firstDefault

Pointer into RecordAdjust#readerOrder of the first reader field whose value comes from a default value. Set to length of RecordAdjust#readerOrder if there are none.

instanceSupplierback to summary
public final GenericData.InstanceSupplier instanceSupplier

Supplier that offers an optimized alternative to data.newRecord()

readerOrderback to summary
public final Schema.Field[] readerOrder

Contains (all of) the reader's fields. The first n of these are the fields that will be read from the writer: these n are in the order dictated by writer's schema. The remaining m fields will be read from default values (actions for these default values are found in RecordAdjust#defaults.

Constructor Detail

RecordAdjustback to summary
private RecordAdjust(Schema w, Schema r, GenericData d, Resolver.Action[] fa, Schema.Field[] ro, int firstD, Object[] defaults)

Method Detail

noReorderback to summary
public boolean noReorder()

Returns true iff i == readerOrder[i].pos() for all indices i. Which is to say: the order of the reader's fields is the same in both the reader's and writer's schema.

resolveback to summary
pack-priv static Resolver.Action resolve(Schema writeSchema, Schema readSchema, GenericData data, Map<Schema.SeenPair, Resolver.Action> seen)

Returns a RecordAdjust for the two schemas, or an ErrorAction if there was a problem resolving. An ErrorAction is returned when either the two record-schemas don't have the same name, or if the writer is missing a field for which the reader does not have a default value.

Exceptions
RuntimeException:
if writer and reader schemas are not both records
org.apache.avro back to summary

public Class Resolver.WriterUnion

extends Action
Class Inheritance

In this case, the writer was a union. There are two subcases here: If the reader and writer are the same union, then the unionEquiv variable is set to true and the actions list holds the resolutions of each branch of the writer against the corresponding branch of the reader (which will result in no material resolution work, because the branches will be equivalent). If they reader is not a union or is a different union, then unionEquiv is false and the actions list holds the resolution of each of the writer's branches against the entire schema of the reader (if the reader is a union, that will result in ReaderUnion actions).

Field Summary

Modifier and TypeField and Description
public final Resolver.Action[]
public final boolean
Inherited from org.apache.avro.Resolver.Action:
conversionlogicalTypereadertypewriter

Constructor Summary

AccessConstructor and Description
private
WriterUnion(Schema w, Schema r, GenericData d, boolean ue, Resolver.Action[] a)

Method Summary

Modifier and TypeMethod and Description
public static Resolver.Action
resolve(Schema writeSchema, Schema readSchema, GenericData data, Map<Schema.SeenPair, Resolver.Action> seen)

Field Detail

actionsback to summary
public final Resolver.Action[] actions
unionEquivback to summary
public final boolean unionEquiv

Constructor Detail

WriterUnionback to summary
private WriterUnion(Schema w, Schema r, GenericData d, boolean ue, Resolver.Action[] a)

Method Detail

resolveback to summary
public static Resolver.Action resolve(Schema writeSchema, Schema readSchema, GenericData data, Map<Schema.SeenPair, Resolver.Action> seen)