oracle.kv.avro
Interface GenericAvroBinding

All Superinterfaces:

AvroBinding<GenericRecord>, ValueBinding<GenericRecord>

public interface GenericAvroBinding
extends AvroBinding<GenericRecord>

The GenericAvroBinding interface has the same methods as AvroBinding, but represents values as instances of GenericRecord. A single schema binding is created using AvroCatalog.getGenericBinding(org.apache.avro.Schema), and a multiple schema binding is created using AvroCatalog.getGenericMultiBinding(java.util.Map).

The trade-offs in using a GenericAvroBinding, compared to other types of bindings, are:

• The obvious advantage of using a generic binding is that values may be treated generically. Also, if schemas are treated dynamically, then the set of schemas used in an application need not be fixed at build time.

• Because GenericRecord is part of the Avro API, it conveniently represents all data types defined by Avro. This is in contrast to a JsonAvroBinding.

• GenericRecord does not provide type safety because field values must be cast to the type defined in the schema. It can also be error prone, because fields are accessed by string name.

• To support class evolution, with generic bindings (unlike Avro specific bindings) the application must supply the Avro Schema objects at runtime. In other words, the application must maintain a set of known schemas for use at runtime.

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 GenericAvroBinding, a GenericRecord is used to represent values. A GenericRecord represents an Avro object roughly as a map of string field names to field values, as follows:

  public interface GenericRecord {
    public Schema getSchema();
    public Object get(String key);
    public void put(String key, Object value);
  }

Note that field values in this API are type Object and must be cast to the appropriate type, as defined by the schema. The mapping from Avro schema data types to Java data types is described at the bottom of the org.apache.avro.generic package description.

The following code fragment demonstrates writing and reading a value using a generic single schema binding.

 Schema.Parser parser = new Schema.Parser();
 Schema nameSchema = parser.parse(nameSchemaText);
 Schema memberSchema = parser.parse(memberSchemaText);

 GenericAvroBinding binding = avroCatalog.getGenericBinding(memberSchema);

 // Create object
 GenericRecord name = new GenericData.Record(nameSchema)
 name.put("first", ...);
 name.put("last", ...);
 GenericRecord object = new GenericData.Record(memberSchema)
 object.put("name", name);
 object.put("age", new Integer(...));

 // Serialize and store
 Value value = binding.toValue(object);
 kvStore.put(key, value);

 // Sometime later, retrieve and deserialize
 ValueVersion vv = kvStore.get(key);
 GenericRecord object = binding.toObject(vv.getValue());

 // Use object
 GenericRecord name = (GenericRecord) object.get("name");
 Integer age = (Integer) object.get("age");
 ...

The following code fragment demonstrates reading values with different schemas using a generic multiple schema binding.

 Schema.Parser parser = new Schema.Parser();
 Schema nameSchema = parser.parse(nameSchemaText);
 Schema memberSchema = parser.parse(memberSchemaText);
 Schema anotherSchema = parser.parse(anotherSchemaText);

 Map<String, Schema> schemas = new HashMap<String, Schema>()
 schemas.put(memberSchema.getFullName(), memberSchema);
 schemas.put(anotherSchema.getFullName(), anotherSchema);

 GenericAvroBinding binding = avroCatalog.getGenericMultiBinding(schemas);

 Iterator<KeyValueVersion> iter = kvStore.multiGetIterator(...);
 for (KeyValueVersion kvv : iter) {
     GenericRecord object = binding.toObject(kvv.getValue());
     String schemaName = object.getSchema().getFullName();
     if (schemaName.equals(memberSchema.getFullName())) {
         ...
     } else if (schemaName.equals(anotherSchema.getFullName())) {
         ...
     } else {
         ...
     }
 }

A special use case for a generic multiple schema binding is when the application treats values dynamically based on their schema, rather than using a fixed set of known schemas. The AvroCatalog.getCurrentSchemas() method can be used to obtain a map of the most current schemas, which can be passed to AvroCatalog.getGenericMultiBinding(java.util.Map).

For example, the following code fragment demonstrates reading values with different schemas using a generic multiple schema binding. Note that in a long running application, it is possible that a schema may be added and used to store a key-value pair, after the binding has been created. The application may handle this possibility by catching SchemaNotAllowedException.

 GenericAvroBinding binding =
     avroCatalog.getGenericMultiBinding(avroCatalog.getCurrentSchemas());

 Iterator<KeyValueVersion> iter = kvStore.storeIterator(...);
 while (iter.hasNext()) {
     KeyValueVersion kvv = iter.next();
     GenericRecord object;
     try {
         object = binding.toObject(kvv.getValue());
     } catch (SchemaNotAllowedException e) {
         // In this example, ignore values with a schema that was not
         // known at the time the binding was created.
         continue;
     }
     String schemaName = object.getSchema().getFullName();
     if (schemaName.equals(memberSchema.getFullName())) {
         ...
     } else if (schemaName.equals(anotherSchema.getFullName())) {
         ...
     } else {
         ...
     }
 }

Since:

2.0

Method Summary

GenericRecord	toObject(Value value) After doing a read operation using a KVStore method, the user calls toObject with the Value obtained from the read operation.
Value	toValue(GenericRecord object) Before doing a write operation, the user calls toValue passing an object she wishes to store.

Method Detail

toObject

GenericRecord toObject(Value value)
                       throws SchemaNotAllowedException,
                              IllegalArgumentException

After doing a read operation using a 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 this binding (and was specified when the binding was created).

In other words, this method transforms the serialized data in the value parameter to conform to the schema of the GenericRecord that is returned.

Specified by:

toObject in interface AvroBinding<GenericRecord>

Specified by:

toObject in interface ValueBinding<GenericRecord>

Parameters:

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 schema

Returns:

the deserialized GenericRecord instance. The GenericContainer.getSchema() method will return the reader schema, which is the schema that was specified when this binding was created.

Throws:

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.

toValue

Value toValue(GenericRecord object)
              throws SchemaNotAllowedException,
                     UndefinedSchemaException,
                     IllegalArgumentException

Before doing a write operation, the user calls 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 GenericRecord object parameter; it is returned by GenericContainer.getSchema() and normally specified when creating a GenericData.Record object. The writer schema must be one of the schemas specified when this binding was created.

In other words, this method returns serialized data that conforms to the schema of the given GenericRecord.

Specified by:

toValue in interface AvroBinding<GenericRecord>

Specified by:

toValue in interface ValueBinding<GenericRecord>

Parameters:

object - the GenericRecord instance the user wishes to store, or at least serialize.

Returns:

the serialized object.. The byte array of the Value is serialized Avro data, packaged in an internal format that includes a reference to the Avro schema

Throws:

SchemaNotAllowedException - if the schema associated with the object parameter is not allowed with this 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.