coherence

## Class BinaryStoreExample

- java.lang.Object
- - coherence.BinaryStoreExample

-     public class BinaryStoreExample
      extends Object

  This is a simple Oracle NoSQL Database client application that demonstrates an integration of an existing Oracle Coherence application with Oracle NoSQL Database. This example uses the `NoSQLBinaryStore` module, which is a pre-built implementation of the Oracle Coherence `BinaryEntryStore` 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 `BinaryEntryStore` implementation. Oracle Coherence supports a variety of mechanisms for doing this, including multiple native Java Serialization techniques, multiple Oacle Coherence Portable Object Format (POF) techniques, and the ability to use user-provided serialization implementations. This example assumes that an application exists with a working Serialization scheme in place. This example provides POF serialization for the `Person` implementation. Although we encourage users to migrate to an Avro schema for object storage format, the BinaryEntryStore implementation will leverage the existing application object serialization to allow for the integration to be implemented with minimal impact to the Oracle Coherence application code.

  Because this example is using the `NoSQLBinaryStore` module to interact with the Oracle NoSQL Database, instance it does not need to directly use Oracle NoSQL Database classes in order allow the Oracle NoSQL Database to provide persistent backing for an Oracle Coherence cache. The `NoSQLBinaryStore` module relies on application-controlled serialization.

  The cache-config.xml file in this directory includes a definition for the `BinaryCache` cache. It is assumed that the reader has some level of familiarity with Oracle Coherence cache configuration. The `BinaryCache` has a `cache-mapping` that references a `distributed-scheme` named `BinaryCacheScheme`. Note that although Oracle Coherence allows for a variety of different cache schemes, `BinaryEntryStore` 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 Oracle Coherence Portable Object Format when serializing and de-serializing objects in association with this cache. Its configuration relies on a POF configuration file to control the type mapping for the application.

  The `distributed-scheme` also contains the definition of a `cachestore-scheme` within a `read-write-backing-map-scheme`. Here, the definition specifies `storeName` and `helperHosts` parameters to allow access to the Oracle NoSQL Database instance, in association with this cache. Its configuration includes init-param definitions for:

  - `storeName` - identifies the Oracle NoSQL Database instance name that will be backing the cache.
  - `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.

  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
         javac -cp KVHOME/lib/kvcoherence.jar:COHERENCE_HOME/lib/coherence.jar \
               -d classes *.java

  Before running this example program, start an Oracle NoSQL Database instance. The simplest way to do that is to run kvlite as described in the Quickstart document.

  Before running the example, modify the coherence-cache.xml file, if necessary, and update the definitions 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.BinaryStoreExample -cache BinaryCache

  In this example a single key is used for storing a kv pair, where the value is an object serialized using Portable Object Format encoding. The first time the example is run it inserts the kv pair, and for subsequent executions, it reads and updates the kv pair, incrementing the "age" field.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `BinaryStoreExample(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 BinaryStoreExample 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

    - #### BinaryStoreExample

          BinaryStoreExample(String[] argv)

      Parses the command line args, opens the cache.

  - ### Method Detail

    - #### main

          public static void main(String[] args)

      Runs the BinaryStoreExample 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.