oracle.kv.coherence

## Class NoSQLBinaryStore

- oracle.kv.coherence.NoSQLBinaryStore

- All Implemented Interfaces:
    BinaryEntryStore, XmlConfigurable

      public class NoSQLBinaryStore
      implements BinaryEntryStore, XmlConfigurable

  Oracle NoSQL Database implementation of the `BinaryEntryStore` interface. This implementation uses a single Oracle NoSQL Database handler to deal with single operation and bulk operations that have been requested by the Oracle Coherence layer.

  Users are not generally expected to directly interact with instances of this class. It is expected that the class is managed by Oracle Coherence as the result of XML configuration supplied to Coherence at program startup. The documentation contained in this class is intended primarily to explain the XML configuration options. However, this class does define two static functions, which provide access to the key encode/decode logic, if needed.

  ### Usage

  In order to use the `NoSQLBinaryStore` module, you must configure an Oracle Coherence cache to use it. `NoSQLBinaryStore` is a `BinaryEntryStore`, which implies that the cache must be defined as part of a `distributed-scheme`.

  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.

  A BinaryEntryStore relies on the Coherence application for serialization and deserialization of data. * In the default mode of operation, where no `keyMapper` has been specified, the cache key objects can be any object type, but the keys are handled differently, depending on the the type. For key objects of type `Key`, the objects are used directly as the Oracle NoSQL Database `Key` for the operation. For all other object types, the serialized form of the object is encoded using the `encodeBinaryKey(byte[])` method, and the result is treated as a single path component relative to the components in the `keyPrefix` option, if specified, or as the single top-level major path component if `keyPrefix` was not specified.

  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 can be of any type, provided they can be serialized by Oracle Coherence. The binary data as serialized by Oracle Coherence is used to construct a `Value`.

  The `NoSQLBinaryStore` also needs to access a 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 Oracle NoSQL Database 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 key passed to the cache store that is not of type `Key`. See `Key.toString()` for a of the format of the key strings.

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

  #### 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

  Here is an example for the configuration of an Oracle Coherence cache using the `NoSQLBinaryStore` module.

       <distributed-scheme>
          <scheme-name>MyBinaryScheme</scheme-name>
          <service-name>MyBinaryService</service-name>
          <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.NoSQLBinaryStore</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-params>
                </class-scheme>
              </cachestore-scheme>
            </read-write-backing-map-scheme>
          </backing-map-scheme>
          <autostart>true</autostart>
        </distributed-scheme>

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static byte[]` | `decodeBinaryKey(String strKey)` Decode a binary key from ascii form.
    `static String` | `encodeBinaryKey(byte[] bKey)` Encode a binary key in ascii form so that it is suitable for use as a NoSQL key.

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

      `erase, eraseAll, load, loadAll, store, storeAll`

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

      `getConfig, setConfig`

- - ### Method Detail

    - #### encodeBinaryKey

          public static String encodeBinaryKey(byte[] bKey)

      Encode a binary key in ascii form so that it is suitable for use as a NoSQL key.
      Parameters:
        `bKey` - the binary key value to be encoded
      Returns:
        the binary key in string from

    - #### decodeBinaryKey

          public static byte[] decodeBinaryKey(String strKey)

      Decode a binary key from ascii form.
      Parameters:
        `strKey` - the encoded binary key value to be decoded
      Returns:
        the binary key value

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