avro

Class SpecificExample

java.lang.Object

avro.SpecificExample

public class SpecificExample
extends Object

A simple KVStore client application that represents a Value as a a POJO (or Plain Old Java Object) class that is generated by the Avro compiler tools and serializes values using a SpecificAvroBinding.

An Ant build file, generate-specific.xml, is included with this example to generate the specific class source files: MemberInfo.java, FullName.java and Address.java. When running "ant -f generate-specific.xml" (part of the build instructions below), Ivy will be used to download the Avro jars that are needed from the central Maven repository. These jar files are placed in the generate-specific-libs directory. In a real application, the contents of generate-specific.xml could be included in the application's Ant build file, and the libraries in generate-specific-libs could be obtained differently.

When using an Avro binding, the Avro and Jackson jars must be in the classpath, as well as the kvclient jar. The Avro and Jackson jars are included in the KVHOME/lib directory along with the kvclient jar:

    kvclient.jar avro.jar jackson-core-asl.jar jackson-mapper-asl.jar
 

As long as all four jars are in the same directory, only the kvclient jar needs to be specified in the classpath, because the kvclient jar references the other three jars. If they are not in the same directory, all four jars must be explicitly specified in the classpath.

To build this example in the examples/avro directory:

   cd KVHOME/examples/avro
   ant -f generate-specific.xml
   mkdir classes
   javac -cp KVHOME/lib/kvclient.jar -d classes *.java
 

You'll noticed that the ant -f generate-specific.xml command generates three source files in this directory: Address.java, MemberInfo.java and FullName.java. It is useful to look at these files to understand how they are used, but they should not be modified directly.

Before running this example program, start a KVStore instance. The simplest way to do that is to run KV Lite as described in the Quickstart document.

After starting the KVStore instance, the Avro schema used by the example must be added to the store using the administration command line interface (CLI). First start the admin CLI as described in the Oracle NoSQL Database Administrator's Guide. Then enter the following command to add the example schema:

ddl add-schema -file member-schemas.avsc

After adding the schema, use the KVStore instance name, host and port for running this program, as follows:

 java -cp classes:KVHOME/lib/kvclient.jar avro.SpecificExample \
                       -store <instance name> \
                       -host  <host name>     \
                       -port  <port number>
 

For all examples the default instance name is kvstore, the default host name is localhost and the default port number is 5000. These defaults match the defaults for running kvlite, so the simplest way to run the examples along with kvlite is to omit all parameters.

In this example a single key is used for storing a kv pair, where the value is an object serialized as Avro binary data. The first time the example is run it inserts the kv pair, and subsequent times that it is run it reads and updates the kv pair, incrementing the "age" field.

This example may also be used to demonstrate simple schema evolution by performing the following steps:

1. Build and run the example as described above.
2. Change the FullName schema in member-schemas.avsc to add the "middle" field, including a default value:

         "fields": [
             {"name": "first", "type": "string", "default": ""},
             {"name": "middle", "type": "string", "default": ""},
             {"name": "last", "type": "string", "default": ""}
         ]
      

3. Uncomment the two lines in the example that set the middle name field. In other words, change:

             //final FullName name = member.getName();
             //name.setMiddle("Lawrence");
      

   to:

             final FullName name = member.getName();
             name.setMiddle("Lawrence");
      

4. Build and run the modified example as before. Be sure to re-run the ant -f generate-specific.xml command to re-generate the three source files and re-compile all source files with javac.

   The -evolve option must be used with the add-schema command as follows:

   ddl add-schema -file member-schemas.avsc -evolve

   Finally, run the example as before.

When the example is run after being changed, the initial value that is read (which was stored with the old version of the schema) will be displayed with a middle name field with an empty string value. This is because, when Avro deserializes a stored value that has no middle name field, it adds the middle name field because it is present in the reader schema, and it assigns it the default value for that field. A default value is required whenever a new field is added.

The updated example will also set the middle name to "Lawrence" when it increments the age field and stores the updated value. So the final value displayed will include this updated value for the middle name.

You can also reverse this process to demonstrate what happens when a client using the old schema reads and writes a kv pair that was written earlier using the new schema. To try this, undo the two changes above -- remove the middle name field from the schema and comment out the two lines that set the middle name value -- and then build and run the program.

When the example is run after undoing these changes, the initial value that is read (which was stored with the new version of the schema) will be displayed without a middle name field. This is because, when Avro deserializes a stored value that has a middle name, it ignores it because no middle name field is present in the reader schema.

Note that when this version of the example program updates the age field and writes the modified record, no middle name is included in the stored data. In other words, the middle name that was stored earlier is lost.

Also note that the same rules apply when a field is intentionally deleted in a new version of the schema because it is no longer needed. From the Avro perspective, there is no difference between the two scenarios.

Constructor Summary

Constructors

Constructor and Description
SpecificExample(String[] argv) Parses the command line args, opens the KVStore and creates the Avro binding.

Method Summary

Methods

Modifier and Type	Method and Description
static void	main(String[] args) Runs the SpecificExample command line program.
(package private) void	runExample() Insert a kv pair if it doesn't exist, or read/update it if it does.

Methods inherited from class java.lang.Object

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

Constructor Detail

SpecificExample

SpecificExample(String[] argv)

Parses the command line args, opens the KVStore and creates the Avro binding.

Method Detail

main

public static void main(String[] args)

Runs the SpecificExample command line program.

runExample

void runExample()

Insert a kv pair if it doesn't exist, or read/update it if it does.