Class NoSQLBinaryStore
- java.lang.Object
-
- com.tangosol.util.Base
-
- oracle.kv.coherence.NoSQLBinaryStore
-
- All Implemented Interfaces:
BinaryEntryStore
,XmlConfigurable
public class NoSQLBinaryStore extends Base implements BinaryEntryStore
Oracle NoSQL Database implementation of theBinaryEntryStore
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 theNoSQLBinaryStore
module, you must configure an Oracle Coherence cache to use it.NoSQLBinaryStore
is aBinaryEntryStore
, which implies that the cache must be defined as part of adistributed-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
key-mapper
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 typeKey
, the objects are used directly as the Oracle NoSQL DatabaseKey
for the operation. For all other object types, the serialized form of the object is encoded using theencodeBinaryKey(byte[])
method, and the result is treated as a single path component relative to the components in thekey-prefix
option, if specified, or as the single top-level major path component ifkey-prefix
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 akey-mapper
, which can provide arbitrary translation of key types. Thiskey-mapper
must implement theCacheKeyMapper
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 addition 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<kv:XXX>
style elements, whereXXX
are:store-name
- (Required) The Oracle NoSQL Database instance name that is used to provide persistence for your Oracle Coherence cache.helper-hosts
- (Required) A comma-separated list of helperHost:port values that serve as the gateway to the Oracle NoSQL Database instance.key-prefix
- (Optional) A prefix to apply to relative keys. Not valid in conjunction with thekeyMapper
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 typeKey
. SeeKey.toString()
for a of the format of the key strings.key-mapper
- (Optional) Names a class with a no-arg constructor and which implements theCacheKeyMapper
interface. Provides application rules for mapping Coherence cache keys to Oracle NoSQL Database keys. This is not valid in conjunction withkeyPrefix
.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
consistency-time-lag
- (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)consistency-timeout
- (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
durability-master-sync
- (Optional) Specifies the Durability completeness for writes at the master replication node. Valid values are:- SYNC
- NO_SYNC
- WRITE_NO_SYNC
durability-replica-sync
- (Optional) Specifies the Durability completeness for writes at replica nodes. Valid values are as shown for thedurabilityMasterSync
parameter.durability-replica-ack
- (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 theNoSQLBinaryStore
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> <kv:binary-cache-store> <kv:store-name>kvstore</kv:store-name> <kv:helper-hosts>myhost:5000</kv:helper-hosts> </kv:binary-cache-store> </cachestore-scheme> </read-write-backing-map-scheme> </backing-map-scheme> <autostart>true</autostart> </distributed-scheme>
Coherence 3.7.1 Support
You may use this module with Coherence version 3.7.1, however it's highly recommended for you to upgrade to the latest version of Coherence. You may visit the package summary of the oracle.kv.coherence package for how to configure a NoSQL backed cache with Coherence 3.7.1.
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from class com.tangosol.util.Base
Base.CommonMonitor, Base.LoggingWriter, Base.StackFrame
-
-
Field Summary
Fields Modifier and Type Field Description protected CacheKeyMapper
cacheKeyMapper
A configured key mapping object.protected oracle.kv.coherence.XmlConfigParser.ConfigSettings
configSettings
The configuration as parsedprotected String
keyPrefix
The prefix for relative KV keysprotected KVStore
kvstore
A reference to the key/value storeprotected KVStoreConfig
kvstoreConfig
Configuration to be used for KVStore acquisition.protected XmlElement
xmlConfig
The configuration of this CacheStore.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description protected void
connectNoSQL()
Obtain the NoSQL database handler being used to connect.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.XmlElement
getConfig()
Returns the configuration of this Storeprotected void
instantiateKeyMapper(String mapperClassName)
Given a class name, create an instance of the class and assign it to the cacheKeyMapper variable.protected Key
resolveStringKey(String keyString)
Given a String key, turn it into a NoSQL Key object, but applying prefix if needed.void
setConfig(XmlElement config)
Set the cache configuration based on XML configuration specified by the user.-
Methods inherited from class com.tangosol.util.Base
azzert, azzert, azzert, azzertFailed, breakLines, breakLines, capitalize, checkNotEmpty, checkNotNull, checkRange, computeSafeWaitTime, decimalValue, dup, dup, ensureClassLoader, ensureRuntimeException, ensureRuntimeException, equals, equalsDeep, err, err, err, err, err, escape, formatDateTime, getCallerStackFrame, getCommonMonitor, getCommonMonitor, getCommonMonitor, getContextClassLoader, getContextClassLoader, getDeepMessage, getErr, getLastSafeTimeMillis, getLog, getMaxDecDigits, getMaxHexDigits, getOriginalException, getOut, getRandom, getRandomBinary, getRandomString, getSafeTimeMillis, getStackFrame, getStackFrames, getStackTrace, getStackTrace, getThreadFactory, getUpTimeMillis, hashCode, hexValue, indentString, indentString, isDecimal, isHex, isLogEcho, isOctal, log, log, log, log, log, makeInteger, makeLong, makeThread, octalValue, out, out, out, out, out, pad, parseBandwidth, parseBandwidth, parseDelimitedString, parseHex, parseHex, parseMemorySize, parseMemorySize, parseTime, parseTime, parseTimeNanos, parseTimeNanos, printStackTrace, randomize, randomize, randomize, read, read, read, read, read, read, read, replace, setErr, setLog, setLogEcho, setOut, sleep, toBandwidthString, toBandwidthString, toCharEscape, toCrc, toCrc, toCrc, toCrc, toCrc, toDecString, toDelimitedString, toDelimitedString, toDelimitedString, toDelimitedString, toHex, toHex, toHexDump, toHexEscape, toHexEscape, toHexEscape, toHexEscape, toHexString, toMemorySizeString, toMemorySizeString, toQuotedCharEscape, toQuotedStringEscape, toSqlString, toString, toString, toStringEscape, toUnicodeEscape, trace, trace, trace, trace, trace, trace, trace, trace, trace, truncateString, wait
-
-
-
-
Field Detail
-
kvstoreConfig
protected KVStoreConfig kvstoreConfig
Configuration to be used for KVStore acquisition.
-
xmlConfig
protected XmlElement xmlConfig
The configuration of this CacheStore. Configuration can only be performed once.
-
configSettings
protected oracle.kv.coherence.XmlConfigParser.ConfigSettings configSettings
The configuration as parsed
-
kvstore
protected KVStore kvstore
A reference to the key/value store
-
keyPrefix
protected String keyPrefix
The prefix for relative KV keys
-
cacheKeyMapper
protected CacheKeyMapper cacheKeyMapper
A configured key mapping object. When specified, the keyPrefix is not used.
-
-
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
-
setConfig
public void setConfig(XmlElement config)
Set the cache configuration based on XML configuration specified by the user.- Specified by:
setConfig
in interfaceXmlConfigurable
- Throws:
IllegalStateException
- if this is not the first call to setConfig
-
getConfig
public XmlElement getConfig()
Returns the configuration of this Store- Specified by:
getConfig
in interfaceXmlConfigurable
- Returns:
- The XML configuration specified for this module. This may be null if no call to setConfig has previously been made.
-
instantiateKeyMapper
protected void instantiateKeyMapper(String mapperClassName)
Given a class name, create an instance of the class and assign it to the cacheKeyMapper variable.- Parameters:
mapperClassName
- The name of a class, which must implement the CacheKeyMapper interface, and have a no-args constructor.
-
resolveStringKey
protected Key resolveStringKey(String keyString)
Given a String key, turn it into a NoSQL Key object, but applying prefix if needed.
-
connectNoSQL
protected void connectNoSQL()
Obtain the NoSQL database handler being used to connect.
-
-