T
- is the SpecificRecord
type of the deserialized object
that is passed to toValue
and returned by toObject
. When using a single schema binding, T
is the generated
Avro specific class, which implements SpecificRecord
. When using a
multiple schema binding, T
is the SpecificRecord
interface
itself.public interface SpecificAvroBinding<T extends SpecificRecord> extends AvroBinding<T>
SpecificAvroBinding
interface has the same methods as AvroBinding
, but represents values as instances of a generated Avro
specific class which implements SpecificRecord
. A single schema
binding is created using AvroCatalog.getSpecificBinding(java.lang.Class<T>)
, and a
multiple schema binding is created using AvroCatalog.getSpecificMultiBinding()
.
The trade-offs in using a SpecificAvroBinding
, compared to other
types of bindings, are:
See AvroCatalog
for general information on Avro bindings and
schemas. The schemas used in the examples below are described in the AvroCatalog
javadoc.
When using a SpecificAvroBinding
, an Avro specific Java class, which
implements the Avro SpecificRecord
interface, is used to represent
values. An Avro specific class is a POJO (Plain Old Java Object) having
properties (getter and setter methods) for each field in its associated Avro
schema. The source code for an Avro specific class is generated from an
Avro schema using the Avro compiler tools; see the Avro example in KVHOME/examples/avro
for details.
For example, the generated Avro specific classes for the example schemas are:
package com.example; import org.apache.avro.Schema; import org.apache.avro.specific.SpecificRecord; public class FullName implements SpecificRecord { public FullName() {} public Schema getSchema() { ... } public String getFirst() { ... } public void setFirst(String value) { ... } public String getLast() { ... } public void setLast(String value) { ... } } public class MemberInfo implements SpecificRecord { public MemberInfo() {} public Schema getSchema() { ... } public FullName getName() { ... } public void setName(FullName value) { ... } public Integer getAge() { ... } public void setAge(Integer value) { ... } }In addition to the methods shown, useful
Object.toString()
, Object.equals(java.lang.Object)
and Object.hashCode()
methods are generated. Avro also
generates internal methods for performing serialization and deserialization,
and an internal static field that holds the schema used to compile the
class. Note that the full Avro schema name and full Java class name are
always equal.
The following code fragment demonstrates writing and reading a value using a specific single schema binding. Note that no casting is needed when a single schema binding is used.
AvroBinding<MemberInfo> binding = avroCatalog.getSpecificBinding(MemberInfo.class); // Create object FullName name = new FullName(); name.setFirst(...); name.setLast(...); MemberInfo object = new MemberInfo(); object.setName(name); object.setAge(...); // Serialize and store Value value = binding.toValue(object); kvStore.put(key, value); // Sometime later, retrieve and deserialize ValueVersion vv = kvStore.get(key); MemberInfo object = binding.toObject(vv.getValue()); // Use object FullName name = object.getName(); int age = object.getAge(); ...The following code fragment demonstrates reading values with different schemas (different specific classes) using a multiple schema binding. Note that schema name could also be used to distinguish between classes, instead of using
instanceof
.
SpecificAvroBinding<SpecificRecord> binding = avroCatalog.getSpecificMultiBinding(); Iterator<KeyValueVersion> iter = kvStore.multiGetIterator(...); for (KeyValueVersion kvv : iter) { SpecificRecord object = binding.toObject(kvv.getValue()); if (object instanceof MemberInfo) { MemberInfo member = (MemberInfo) object; ... } else if (object instanceof OtherSpecificClass) { ... } else { ... } }
T toObject(Value value) throws SchemaNotAllowedException, IllegalArgumentException
KVStore
method, the user
calls toObject
with the Value
obtained from the read
operation.
If necessary, this method automatically performs schema evolution, as
described in AvroCatalog
. In the context of schema evolution,
the writer schema is the one associated internally with the value
parameter (this association was normally made earlier when the
value was stored), and the reader schema is the one associated with the
Avro specific class of the caller. The schema of an Avro specific class
is the one from which the class was generated using the Avro compiler
tools.
In other words, this method transforms the serialized data in the value
parameter to conform to the schema of the Avro specific class
that is returned.
toObject
in interface AvroBinding<T extends SpecificRecord>
toObject
in interface ValueBinding<T extends SpecificRecord>
value
- the Value
obtained from a KVStore
read
operation method.. The byte array of the Value
is
serialized Avro data, packaged in an internal format that includes a
reference to the Avro schemaSpecificRecord
instance.SchemaNotAllowedException
- if the schema associated with the
value
parameter is not allowed with this binding.IllegalArgumentException
- if the value format is not Value.Format.AVRO
, the schema identifier embedded in the value
parameter is invalid, or the serialized data cannot be parsed.Value toValue(T object) throws SchemaNotAllowedException, UndefinedSchemaException, IllegalArgumentException
toValue
passing
an object she wishes to store. The resulting Value
is then
passed to the write operation method in KVStore
.
In the context of schema evolution, as described in AvroCatalog
,
the returned value is serialized according to the writer schema. The
writer schema is the one associated with the Avro specific class of the
object
parameter. The schema of an Avro specific class is the
one from which the class was generated using the Avro compiler tools.
In other words, this method returns serialized data that conforms to the schema of the Avro specific class.
toValue
in interface AvroBinding<T extends SpecificRecord>
toValue
in interface ValueBinding<T extends SpecificRecord>
object
- the SpecificRecord
instance the user wishes to
store, or at least serialize.Value
is
serialized Avro data, packaged in an internal format that includes a
reference to the Avro schemaSchemaNotAllowedException
- if the object
parameter's
class is not the class passed to AvroCatalog.getSpecificBinding(java.lang.Class<T>)
;
this can only happen if generic type warnings are ignored or suppressed.
This exception is never thrown by a specific multi-binding
.UndefinedSchemaException
- if the schema associated with the
object
parameter has not been defined using the NoSQL Database
administration interface. Note that when the allowed schemas for a
binding are specified (and validate) at the time the binding is created,
this exception is extremely unlikely and is only possible if a schema is
mistakenly disabled after the binding is created.IllegalArgumentException
- if the object
parameter is
invalid according to its schema, and cannot be serialized.Copyright (c) 2011, 2014 Oracle and/or its affiliates. All rights reserved.