oracle.kv.coherence

## Class NoSQLAvroCacheStore

- oracle.kv.coherence.NoSQLAvroCacheStore

- All Implemented Interfaces:
    CacheLoader, CacheStore, XmlConfigurable

      public class NoSQLAvroCacheStore
      implements CacheStore, XmlConfigurable

  This is an Oracle NoSQL Database-based implementation of the `CacheStore` interface. This implementation is Avro-aware and will convert database values which are stored in Avro format to Object format using Avro binding objects.

  Users are not expected to directly interact with this class. It is expected that the class is managed by Oracle Coherence as the result of XML configuration supplied to Oracle Coherence at program startup. The documentation contained in this class is intended primarily to explain the XML configuration options.

  ### Usage

  In order to use the `NoSQLAvroCacheStore` module, you must configure an Oracle Coherence cache to use it. `NoSQLAvroCacheStore` is a `CacheStore`, which implies that the cache must be defined as part of a `distributed-scheme`. In addition, you would typically want to pair the `NoSQLAvroCacheStore` with `NoSQLAvroSerializer` as shown in the example below.

  This implementation handles requests to load data into the cache when a key is not present, to store data when changes are made to the cache, and to delete a KV entry when a remove is performed on the cache. These operations require converting the Oracle Coherence application's representation of a cache key and a cache value into a form that meets the needs of Oracle NoSQL Database.

  In the default mode of operation, the cache key objects can be specified as `String` objects or as `Key` objects. When specified in `String` form, the key may either be in the form documented in `Key.toString()`, or may omit the leading '/'. If specified in relative form (no leading '/', a key string passed to the cache will be prefixed by the major components indicated by the `keyPrefix` option, if specified. The resulting concatenation must follow the formatting rules dictated by the `Key` class.

  If an application needs greater control over the way in which Oracle Coherence keys are mapped to Oracle NoSQL Database `Key` objects, the cache can be configured with a `keyMapper`, which can provide abitrary translation of key types. This `keyMapper` must implement the `CacheKeyMapper` interface.

  The Oracle Coherence value objects are required to be one of the following types:

  - `SpecificRecord`
  - `GenericRecord`
  - `JsonRecord`
  - `RawRecord`
  - `Binary`
  - `Value`
  The `SpecificRecord`, `GenericRecord`, `JsonRecord`, and `RawRecord` types are Avro schema-based types. `Binary` represents a non-Avro type that has been serialized by the application. `Value` can represent either an Avro or non-Avro type.

  In order to simplify application development, we provide a companion `NoSQLAvroSerializer`, which understands how to serialize the object types listed above without the need to write additional serialization code.

  The `NoSQLAvroCacheStore` also needs to access an Oracle NoSQL database instance. In addtion to the basic information needed to connect to the database, a number of additional store interaction properties are also configurable, allowing the developer to set Durability, Consistency in the cache configuration.

  ### XML Configuration Options

  The various configuration parameters to adjust the behavior to your application's specific requirements are set within the cache definition XML using `<init-param>` elements:

  `storeName` - (Required) The KVStore instance name that is used to provide persistence for your Oracle Coherence cache.

  `helperHosts` - (Required) A comma-separated list of helperHost:port values that serve as the gateway to the Oracle NoSQL Database instance.

  `keyPrefix` - (Optional) A prefix to apply to relative keys. Not valid in conjunction with the `keyMapper` option. The value specified must begin with a '/' character and indicates zero or more major key path components to prepend to any String key passed to the cache store that is in relative form (i.e. not starting with a '/').

  `keyMapper` - (Optional) Names a class with a no-arg constructor and which implements the `CacheKeyMapper` interface. Provides application rules for mapping Oracle Coherence cache keys to Oracle NoSQL Database keys. This is not valid in conjunction with `keyPrefix`.

  `avroFormat` - (Optional) Specifies the preferred object representation for Avro schema-based objects. Valid values (case insensitive) are:

  - `SPECIFIC`
  - `GENERIC`
  - `JSON`
  - `RAW`
  If not specified, this defaults to `SPECIFIC`.

  `schemaFiles` - (Optional) When Generic or Json format is selected, The application needs to identify the specific version of the schema that it expects. It does this by providing a comma separated list of schema definition files. Each file is located as a system resource and should be named in resource form (e.g. /my/path/to/schema.avsc).

  #### Consistency parameters

  `consistency` - (Optional) Specifies the type of consistency to use during lookups. Valid values are:
  - ABSOLUTE
  - NONE_REQUIRED
  - NONE_REQUIRED_NO_MASTER
  - TIME - requires consistencyTimeLag and consistencyTimeout

  `consistencyTimeLag` - (Optional) Specifies the maximum time lag for valid consistency. Time durations can be specified using standard Oracle Coherence time unit suffixes (e.g. 1ns, 1us, 1ms, 1s)

  `consistencyTimeout` - (Optional) Specifies the timeout for waiting for consistency. Time durations can be specified using standard Oracle Coherence time unit suffixes (e.g. 1ns, 1us, 1ms, 1s)

  #### Durability parameters

  `durabilityMasterSync` - (Optional) Specifies the Durability completeness for writes at the master replication node. Valid values are:

  - SYNC
  - NO_sync
  - WRITE_NO_SYNC

  `durabilityReplicaSync` - (Optional) Specifies the Durability completeness for writes at replica nodes. Valid values are as shown for the `durabilityMasterSync` parameter.

  `durabilityReplicaAck` - (Optional) Specifies the Durability completeness for replica nodes. Valid values are:

  - ALL
  - NONE
  - SIMPLE_MAJORITY

  ### Example

  Here is an example for the configuration of an Oracle Coherence cache using the `NoSQLAvroCacheStore` module in conjunction with the `NoSQLAvroSerializer` module.

       <distributed-scheme>
          <scheme-name>MyAvroCacheScheme</scheme-name>
          <service-name>MyAvroCacheService</service-name>
          <serializer>
             <instance>
                <class-name>oracle.kv.coherence.NoSQLAvroSerializer</class-name>
                <init-params>
                   <init-param>
                     <param-name>storeName</param-name>
                     <param-value>kvstore</param-value>
                   </init-param>
                   <init-param>
                     <param-name>helperHosts</param-name>
                     <param-value>myhost:5000</param-value>
                   </init-param>
                   <init-param>
                     <param-name>schemaFiles</param-name>
                     <param-value>my/app/datatype.avsc,my/app/othertype.avsc</param-value>
                  </init-param>
                 </init-params>
             </instance>
          </serializer>
          <backing-map-scheme>
            <read-write-backing-map-scheme>
              <internal-cache-scheme>
                <local-scheme />
              </internal-cache-scheme>
              <cachestore-scheme>
                <class-scheme>
                  <class-name>oracle.kv.coherence.NoSQLAvroCacheStore</class-name>
                  <init-params>
                    <init-param>
                      <param-name>storeName</param-name>
                      <param-value>kvstore</param-value>
                    </init-param>
                    <init-param>
                      <param-name>helperHosts</param-name>
                      <param-value>myhost:5000</param-value>
                    </init-param>
                    <init-param>
                      <param-name>avroFormat</param-name>
                      <param-value>SPECIFIC</param-value>
                    </init-param>
                    <init-param>
                      <param-name>schemaFiles</param-name>
                      <param-value>my/app/datatype.avsc,my/app/othertype.avsc</param-value>
                    </init-param>
                  </init-params>
                </class-scheme>
              </cachestore-scheme>
            </read-write-backing-map-scheme>
          </backing-map-scheme>
          <autostart>true</autostart>
        </distributed-scheme>

- - ### Method Summary

    - ### Methods inherited from interface com.tangosol.net.cache.CacheStore

      `erase, eraseAll, store, storeAll`

    - ### Methods inherited from interface com.tangosol.net.cache.CacheLoader

      `load, loadAll`

    - ### Methods inherited from interface com.tangosol.run.xml.XmlConfigurable

      `getConfig, setConfig`

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