avro

Class JsonExample

java.lang.Object

avro.JsonExample

public class JsonExample
extends Object

A simple KVStore client application that represents a Value as a JsonNode object using the Jackson API, and serializes values using a JsonAvroBinding.

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
   mkdir classes
   javac -cp KVHOME/lib/kvclient.jar -d classes *.java
 

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.JsonExample \
                       -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 ObjectNode name = (ObjectNode) member.get("name");
             //name.put("middle", "Lawrence");
      

   to:

             final ObjectNode name = (ObjectNode) member.get("name");
             name.put("middle", "Lawrence");
      

4. Build and run the modified example as before. The -evolve option must be used with the add-schema command as follows:

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

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
JsonExample(String[] argv) Parses the command line args, opens the KVStore, parses the Avro schemas and creates the Avro binding.

Method Summary

Methods

Modifier and Type	Method and Description
static void	main(String[] args) Runs the JsonExample 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

JsonExample

JsonExample(String[] argv)
      throws IOException

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

Throws:

IOException

Method Detail

main

public static void main(String[] args)

Runs the JsonExample command line program.

runExample

void runExample()

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