public class SpecificExample extends Object
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.jarAs 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.avscAfter 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:
"fields": [ {"name": "first", "type": "string", "default": ""}, {"name": "middle", "type": "string", "default": ""}, {"name": "last", "type": "string", "default": ""} ]
//final FullName name = member.getName(); //name.setMiddle("Lawrence");to:
final FullName name = member.getName(); name.setMiddle("Lawrence");
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 -evolveFinally, 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 and Description |
---|
SpecificExample(String[] argv)
Parses the command line args, opens the KVStore and creates the Avro
binding.
|
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.
|
SpecificExample(String[] argv)
public static void main(String[] args)
void runExample()
Copyright (c) 2011, 2015 Oracle and/or its affiliates. All rights reserved.