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 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 storeName and helperHosts 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.

Copyright (c) 2011, 2014 Oracle and/or its affiliates. All rights reserved.