coherence

Class AvroSpecificExample

java.lang.Object

coherence.AvroSpecificExample

public class AvroSpecificExample
extends Object

This is a simple Oracle NoSQL Database client application that demonstrates an integration of an Avro Schema-based Oracle NoSQL Database application with Oracle Coherence. This example uses the NoSQLAvroCacheStore module, which is a pre-built implementation of the Oracle Coherence CacheStore interface to manage interaction with an Oracle NoSQL Database instance.

Objects that are manipulated by an Oracle Coherence application need to be serialized when moving them between the application space and the Oracle Coherence cache, as well as between the Oracle Coherence cache and a CacheStore implementation. Oracle Coherence supports a variety of mechanisms for doing this, including multiple native Java Serialization techniques, multiple Oracle Coherence Portable Object Format techniques, and the ability to use user-provided serialization implementations. This example demonstrates the use of the NoSQLAvroSerializer implementation for object serialization. This mechanism uses the fast and compact Avro serialization format to enable applications to be quickly moved to Oracle Coherence.

Because this example assumes that an application is built using Avro schemas, the reader should already be familiar with Avro Schemas. It is suggested that you review the examples in the avro example directory if you are not yet familiar with the use of Avro schemas.

As with the SpecificExample program from the avro example directory, this examples uses an Ant build file to generate application classes from the application's Avro schema. In this case, we use person.avsc to define the content of a Person class.

An Ant build file was used to generate the specific class source file: Person.java. The generate-specific.xml file can be found in the avro example directory, along with directions for use.

Because this example is using the NoSQLAvroCacheStore module to interact with the Oracle NoSQL Database, it does not need to directly use SpecificAvroBinding objects. Instead, the application deals only with the generated Person class. SpecificAvroBinding objects are used under the covers by the NoSQLAvroCacheStore and NoSQLAvroSerializer classes to perform the object serialization on behalf of the user.

The cache-config.xml file in this directory includes a definition for the AvroCache cache. It is assumed that the reader has some level of familiarity with Oracle Coherence cache configuration. The AvroCache has a cache-mapping that references a distributed-scheme named AvroCacheScheme. Note that, although Oracle Coherence allows for a variety of different cache schemes, CacheStore is specifically designed to work within distributed cache schemes.

Please note that this example is structured, for simplicity, to assume that the example program is the only member of the cache cluster. In a real environment it will be necessary to have all cache cluster members using the same cache configuration file.

The distributed scheme contains a serializer definition that tells Oracle Coherence to use the NoSQLAvroSerializer when serializing and de-serializing objects in association with this cache. Its configuration includes init-param definitions for:

• storeName - identifies the Oracle NoSQL Database instance name which which the serializer is interacting.
• helperHosts - contains a comma-separated list of host:port identifiers for hosts to contact in order to set up a connection to the Oracle NoSQL Database instance.
• schemaFiles - contains a comma-separated list of schema file resources that may be needed. This is needed for a cache application that may operate on Json or Generic format object representations. Because this example is using Specific representation, it is not actually needed, but is included here in order to allow conversion to an alternate format.

The distributed-scheme also contains the definition of a cachestore-scheme within a read-write-backing-map-scheme. Here, the definition again specifies store-name and helper-hosts parameters to allow access to the KVStore instance, but also defines an avroFormat parameter with the value SPECIFIC. This setting tells the NoSQLAvroCacheStore module that when an Avro-based object is loaded from the database, it should be rendered in SpecificRecord format. This means that the classpath must contain a compiled class for each such Avro type that will be accessed by the cache application.

In addition to the kvclient.jar file, this application also requires that kvcoherence.jar and coherence.jar be included in the classpath. kvcoherence.jar is included in the same directory as kvclient.jar for Oracle NoSQL Database EE distributions. The kvcoherence.jar file internally references kvclient.jar so it does not need to be explicitly referenced in the classpath. The coherence.jar file should be downloaded and installed separately.

To build this example in the examples/coherence directory:

   cd KVHOME/examples/coherence
   mkdir classes
   javac -cp KVHOME/lib/kvcoherence.jar:COHERENCE_HOME/lib/coherence.jar \
       -d classes *.java
 

The Person.java class in this directory was generated using the generate-specific.xml ant build script found in the avro example directory. 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 kvlite 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 person-schema.avsc
 

After adding the schema, modify the coherence-cache.xml file, if necessary, and update the defintions of the storeName and helperHosts parameters with the appropriate values based on your kvstore instance. For all examples the default instance name is kvstore, the default host name is localhost and the default port number is 5000. Then, run this program, as follows:

 java -cp classes:KVHOME/lib/kvcoherence.jar:COHERENCE_HOME/lib/coherence.jar:.. \
       -Dtangosol.pof.config=pof-config.xml \
       -Dtangosol.coherence.cacheconfig=cache-config.xml \
       coherence.AvroSpecificExample -cache AvroCache
 

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.

Constructor Summary

Constructors

Constructor and Description
AvroSpecificExample(String[] argv) Parses the command line args, opens the cache.

Method Summary

Methods

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

AvroSpecificExample

AvroSpecificExample(String[] argv)

Parses the command line args, opens the cache.

Method Detail

main

public static void main(String[] args)

Runs the AvroSpecificExample command line program.

runExample

void runExample()

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