Oracle Coherence is an in-memory clustered data management technology that provides data caching for the applications running in the cluster. In effect, Oracle Coherence is a data service that provides fast access, availability guarantees, and real-time access to frequently used data. Some of the benefits of Oracle Coherence are a fully coherent data, read and write scalability, fast & transparent failover and failback, no single point of failure, and cluster wide transactions. Coherence caches value objects, which represent data from some source such as Oracle NoSQL Database, and the objects must be serializable. Serialization involves the conversion of the data to a binary format for transfer across the network and storage in the cache. When data is read from the cache data is deserialized. Various options are available for serialization/deserialization. The recommended serialzier for Coherence is com.tangosol.io.pof.PofSerializer . Portable Object Format (POF) is an efficient, language independent binary format. Oracle NoSQL Database provides a Java API to interact with Oracle Coherence. For the cache store the following interfaces are provided. Class Description · oracle.kv.coherence.NoSQLBinaryStore Operates on com.tangosol.util.BinaryEntry objects to cache key/value pairs in binary format making use of a Serializer to convert to and from an Object representation. Managed by Oracle Coherence using XML configuration. · oracle.kv.coherence.NoSQLAvroCacheStore · Used to cache key/value pairs in which the value objects are one of the following Avro formats: SpecificRecord , GenericRecord , JsonRecord , RawRecord . Also used for value objects of type Binary (non-Avro) and Value(Avro or non-Avro). Managed by Oracle Coherence using XML configuration. A Serializer must be configured for serializing/deserializing between the Object representation and the cache store representation. Oracle NoSQL Database provides the following classes as serializers. Class Description oracle.kv.coherence.PofKeySerializer Provides Coherence Portable Object Format (POF) serialization of the Key class. Used in conjunction with a NoSQLBinaryStore cache to provide Coherence POF serialization. May also be used for value objects as we shall to serialize a Plain Old Java Object (POJO) entity. Managed by Oracle Coherence using XML configuration. oracle.kv.coherence.NoSQLAvroSerializer Used for serialization of Avro-schema based formats: SpecificRecord , GenericRecord , JsonRecord , RawRecord . Also used with Key and Value types. Primarily designed to be used in conjunction with a oracle.kv.coherence.NoSQLAvroCacheStore cache . Managed by Oracle Coherence using XML configuration. In this article we shall make use of Oracle Coherence to cache Oracle NoSQL Database (Community Edition) data using a NoSQLBinaryStore in conjunction with a PofKeySerializer . Though Oracle Coherence is designed for access to frequently used data by multiple applications in a cluster, we shall use Oracle Coherence with a single node Oracle NoSQL Database in a single client application. This article has the following sections. Setting the Environment Download the following software. Oracle NoSQL Database Community Edition 3.05 from http://www.oracle.com/technetwork/products/nosqldb/downloads/default-495311.html . Oracle NoSQL Database Enterprise Edition 3.05 from http://www.oracle.com/technetwork/products/nosqldb/downloads/default-495311.html . Oracle Coherence for Java Version 3.7.1 http://www.oracle.com/technetwork/middleware/coherence/downloads/coherence-archive-165749.html . Oracle JDeveloper 11g or 12c from http://www.oracle.com/technetwork/developer-tools/jdev/downloads/index.html . The Oracle NoSQL Database Enterprise Edition (EE) is required to be downloaded as the KV Coherence Jar is included only in the Oracle NoSQL Database EE. Create a lightweight version of Oracle NoSQL Database, the kvlite store with the following command. java -jar C:/OracleNoSQLDatabase/kv-ce-3.0.5/kv-3.0.5/lib/kvstore.jar kvlite As indicated in the output the kvlite store gets created. Creating a Java Project We shall be using a Java client application for caching Oracle NoSQL Database data with Oracle Coherence. In this section we shall create the Java application in Oracle JDeveloper. Start Oracle JDeveloper and select File>New>From Gallery. In New Gallery select General>Applications in Categories and Java Desktop Application in Items. Click on OK. The Create Java Desktop Application wizard gets started. In Name your application specify an Application Name ( OracleNoSQLCoherence ) and click on Next. In Name your project specify a Project name ( Coherence ) and click on Next. In Configure Java Settings select the default settings and click on Finish. A Java application Coherence gets created. We need to add some coherence related JAR files to the application. Right-click on Coherence in the Application Navigator and select Project Properties. In Project Properties select Libraries and Classpath. Click on Add Jar/Directory to add the coherence JARs coherence.jar from C:\Coherence\coherence-java-3.7.1.0b27797\coherence\lib directory and kvcoherence.jar from C:\Coherence\kv-ee-3.0.5\kv-3.0.5\lib directory. Click on OK. We also need to set the Coherence Cache configuration file and the POF configuration file as Java options to the application. Select Run/Debug/Profile in Project Properties. Click on Edit. Select Launch Settings. In Java Options specify the following options. -Dtangosol.pof.config=pof-config.xml -Dtangosol.coherence.cacheconfig=cache-config.xml The Launch Settings Java Options are shown in the Edit Run Configuration ‘Default’. Click on OK. Click on OK in the Run/Edit/Profile. Creating a Persistence Entity Class We shall be persisting a POJO entity to Oracle NoSQL Database. In this section we shall create the Java class for the POJO entity. Select File>New>From Gallery. In New Gallery select General in Categories and Java Class in Items. Click on OK. In Create Java Class specify a class Name ( Catalog ) and Package ( coherence ) and click on OK. The coherence.Catalog class gets created. Specify fields journal , publisher , edition , title and author for a Catalog . Add get/set methods for the fields. The Catalog class is listed below. package coherence; public class Catalog { public java.lang.String journal; public java.lang.String publisher; public java.lang.String edition; public java.lang.String title; public java.lang.String author; /** * Gets the value of the 'journal' field. */ public java.lang.String getJournal() { return journal; } /** * Sets the value of the 'journal' field. * @param value the value to set. */ public void setJournal(java.lang.String value) { this.journal = value; } /** * Gets the value of the 'publisher' field. */ public java.lang.String getPublisher() { return publisher; } /** * Sets the value of the 'publisher' field. * @param value the value to set. */ public void setPublisher(java.lang.String value) { this.publisher = value; } /** * Gets the value of the 'edition' field. */ public java.lang.String getEdition() { return edition; } /** * Sets the value of the 'edition' field. * @param value the value to set. */ public void setEdition(java.lang.String value) { this.edition = value; } /** * Gets the value of the 'title' field. */ public java.lang.String getTitle() { return title; } /** * Sets the value of the 'title' field. * @param value the value to set. */ public void setTitle(java.lang.String value) { this.title = value; } /** * Gets the value of the 'author' field. */ public java.lang.String getAuthor() { return author; } /** * Sets the value of the 'author' field. * @param value the value to set. */ public void setAuthor(java.lang.String value) { this.author = value; } } Creating a Serializer Class We shall use the Coherence Portable Object Format (POF) for serializing/deserializing Java objects to the Coherence cache. Non-intrinisic types of objects that are used for serializing/deserialzing are called User Types. The com.tangosol.io.pof.PofSerializer interface provides the following methods for serializing/deserializing Java objects to a POF stream. Method Description deserialize(PofReader in) Deserializes a user type from a POF stream using the specified PofReader . A PofReader reads user types from a POF stream as an ordered sequence of indexed properties. serialize(PofWriter out, java.lang.Object o) Serializes a user type object to a POF stream using the supplied PofWriter . PofWriter interface serializes a user type as an ordered sequence of indexed properties. Create a class that implements the com.tangosol.io.pof.PofSerializer interface. Select File>New>From Gallery. In New Gallery select Java Class. In Create Java Class specify a class Name ( CatalogSerializer ), a Package ( coherence ) and click on OK. In the CatalogSerializer class declare index constants for the VERSION_ID and the Catalog object properties to be indexed. final private static int VERSION_ID = 1; final private static int JOURNAL = 1; final private static int PUBLISHER = 2; final private static int EDITION = 3; final private static int TITLE = 4; final private static int AUTHOR = 5; Override the serialize(PofWriter out, Object o) method to serialize a Catalog object. The PofWriter argument “out” is used to serialize the Object “o” cast to Catalog . Catalog object properties are obtained using the get methods for the properties. Override the deserialize(PofReader in) method to deserialize a user type from the POF stream. The PofReader interface provides various methods for deserializing different types of properties from a POF stream. For the String type property the readString(int iProp) method is used. After all properties have been read the readRemainder() method must be invoked to read all the remaining indexed properties of the current user type from the POF stream. After the readRemainder() method has been invoked all subsequent calls to a read method fail. After obtaining all the indexed properties for the user types create an instance of the user type Catalog . Invoke the set methods to set the properties of the user type. The CatalogSerializer class is listed below. package coherence; import com.tangosol.io.pof.PofSerializer; import com.tangosol.io.pof.PofReader; import com.tangosol.io.pof.PofWriter; import java.io.IOException; /** * This class provides POF serialization of Catalog */ public class CatalogSerializer implements PofSerializer { final private static int VERSION_ID = 1; final private static int JOURNAL = 1; final private static int PUBLISHER = 2; final private static int EDITION = 3; final private static int TITLE = 4; final private static int AUTHOR = 5; /** * Default constructor */ public CatalogSerializer() { } /** * Serialize a Catalog object. * * @param out The PofWriter to write to * @param o The Catalog object to write * @throws IOException if the object o is not a Catalog */ @Override public void serialize(PofWriter out, Object o) throws IOException { if (o.getClass() == Catalog.class) { out.setVersionId(VERSION_ID); out.writeString(JOURNAL, ((Catalog)o).getJournal()); out.writeString(PUBLISHER, ((Catalog)o).getPublisher()); out.writeString(EDITION, ((Catalog)o).getEdition()); out.writeString(TITLE, ((Catalog)o).getTitle()); out.writeString(AUTHOR, ((Catalog)o).getAuthor()); out.writeRemainder(null); } else { throw new IOException("Invalid type presented to Catalog Serializer: " + o.getClass()); } } /** * Deserialize a Catalog object. * * @param in The PofReader to read from * @return The Catalog object read from the input stream * @throws IOException if the stream does not contain the serialization * of a Catalog object in an expected version. */ @Override public Object deserialize(PofReader in) throws IOException { if (in.getVersionId() != VERSION_ID) { throw new IOException("CatalogSerializer encountered unexpected " + "version id: " + in.getVersionId()); } final String journal = in.readString(JOURNAL); final String publisher = in.readString(PUBLISHER); final String edition = in.readString(EDITION); final String title = in.readString(TITLE); final String author = in.readString(AUTHOR); in.readRemainder(); final Catalog catalog = new Catalog(); catalog.setJournal(journal); catalog.setPublisher(publisher); catalog.setEdition(edition); catalog.setTitle(title); catalog.setAuthor(author); return catalog; } } Configuring Coherence Cache The Coherence cache is configured in the cache-config.xml configuration file. Create the cache-config.xml file in the Coherence application in JDeveloper. Select File>New>From Gallery and in New Gallery select General>XML in Categories and XML Document in Items and click on OK. In Create XML File specify a File Name ( cache-config.xml ) and click on OK. The root element of cache-config .xml is cache-config . Coherence provides several coherence cache implementations or schemes. Cache Schema Discription Local Cache Local on heap cache for non-clustered cache. While thread-safe and concurrent a local cache is size limited. Replicated Cache Data is fully replicated to each node in the cluster. Provide fast data access. Suitable for small read-heavy caches. Adding cluster nodes does not increase the aggregate capacity as the same data is replicated to all the nodes, but provides faster data access as more cluster nodes are available. Provides concurrency control. Optimistic Cache Same as replicated cache but without the concurrency control. Provides higher write throughput than replicated cache but two different nodes could have different data. Distributed Cache Data is automatically, dynamically and transparently (location transparency) distributed/partitioned and load-balanced across the nodes on a Oracle NoSQL Database cluster. Data is not replicated. Failover and failback without data loss is provided using backups. The size of the cache grows linearly with the size of the cluster. Network data traffic and latency are the two main considerations for the data distribution algorithm. Both are minimized. Remote Cache A remote cache accessed by a Coherence*Extend client. All cache requests are sent to a proxy and delegated to a cache (Replicated, Optimistic, and Distributed) Near Cache A hybrid cache consisting of a “front cache” and a “back cache”. The front cache is typically Local cache and the back cache is typically distributed cache or remote cache. The caching schemes used are configured in the element. The element defines the mapping between cache names and caching schemes. Each cache mapping is specified in the element. Add element within a element and within the element specify the element for the cache name and the element for the schema name. The NoSQLBinaryStore cache store is designed to be used with the distributed-scheme named BinaryCacheScheme . Add a element within the element and define the BinaryCacheScheme . The element specifies the name of the service that manages the service. The serializer is configured in the element. A Java serializer and a POF serializer are predefined in the tangasol-coherence.xml operational deployment descriptor in the coherence.jar file. com.tangosol.io.pof.ConfigurablePofContext String pof-config.xml The configuration file for the pof serializer pof-config.xml is discussed in the next section. The actual storage schema used for storage within the cache is defined with the element. Add a element within the element to specify a backing map that provides a size limited cache of the persistent store. The element specifies the cache scheme used to cache entries. Specify an in-memory local cache using the element. Add a element within the element to define a mechanism for connecting a cache to the backend data store. To use the oracle.kv.coherence.NoSQLBinaryStore cache implementation the is added within the element. Within the element specify the class name as oracle.kv.coherence.NoSQLBinaryStore using the element. The init parameters storeName and helperHosts are specified within the element for the Oracle NoSQL Database store name and host:port . storeName kvstore helperHosts localhost:5000 To start the cache services associated with a cache scheme automatically at a cluster node set to true . The cache-config.xml configuration file is listed below. BinaryCache BinaryCacheScheme BinaryCacheScheme BinaryCacheService pof oracle.kv.coherence.NoSQLBinaryStore storeName kvstore helperHosts localhost:5000 true Configuring POF Serialization Earlier we defined user types as types to be serialized/deserialized to a cache. The user types are configured in the pof-config.xml configuration file by default as specified in the pof serializer in the tangasol-coherence.xml operational deployment descriptor. Create a pof-config.xml configuration file similar to the cache-config.xml file. The directory structure of the Coherence application is shown in the Application Navigator. The root element of pof-config.xml is . The user types are configured within the element. Coherence specific user types are specified in the coherence-pof-config.xml and the file must be included using element. The POF user types are specified in the element. The coherence.Catalog user type defined earlier is configured as follows. The type-id is a unique id and the specifies a serializer class. Specify the coherence.CatalogSerializer class in the element within the element. 9001 coherence.Catalog coherence.CatalogSerializer Add another user type for the oracle.kv.Key class . with class as oracle.kv.coherence.PofKeySerializer . The oracle.kv.coherence.PofKeySerializer type is actually an interface and the is required to be set to true for an interface type to be a serializer class name. For a subclass to be serializer class set to true . The pof-config.xml is listed below. coherence-pof-config.xml 9001 coherence.Catalog coherence.CatalogSerializer 9002 oracle.kv.Key oracle.kv.coherence.PofKeySerializer true true Creating a Binary Store In this section we shall create a Oracle Coherence cache for data stored in Oracle NoSQL Database. Create a Java class coherence.CatalogBinaryStore . The resources in a cache to be shared among the cluster nodes are defined by the com.tangosol.net.NamedCache interface. An instance of a NamedCache is obtained from the com.tangosol.net.CacheFactory using the static method getCache(java.lang.String sName) . First, initialize the cluster caching services using the ensureCluster() method in CacheFactory in the class constructor. Caching services are initialized by default but invoking the ensureCluster() method makes the process faster. Obtain a NamedCache object using the getCache(java.lang.String sName) method in the class constructor also. NamedCache cache = CacheFactory.getCache(cacheName); Add the following methods to the CatalogBinaryStore class. Method Description create() An instance of Catalog user type is persisted in the method. createCatalog() Creates an instance of Catalog. get() Gets a Catalog user type instance from the cache. In the create() method create a Key instance using the static Key.createKey(List majorPath) method. Specify the major path as /p/pof/catalog1 . final Key key = Key.createKey(Arrays.asList("p", "pof", "catalog1")); Create a Catalog instance to persist using the createCatalog() method. Catalog catalog = createCatalog(); Persist the Catalog instance using the put(java.lang.Object oKey, java.lang.Object oValue) method. cache.put(key, catalog); In the get() method create a Key instance for the key to get from the cache. final Key key = Key.createKey(Arrays.asList("p", "pof", "catalog1")); Get the value associated with the Key instance using the get(java.lang.Object key) method in NamedCache . final Object value = cache.get(key); If the value is not null cast the Object to Catalog and get the properties using the get methods. In the main method create an instance of CatalogBinaryStore and invoke the create() and get() methods. The CatalogBinaryStore class is listed below. package coherence; import com.tangosol.net.CacheFactory; import com.tangosol.net.NamedCache; import com.tangosol.net.cache.BinaryEntryStore; import java.util.Arrays; import oracle.kv.Key; import oracle.kv.coherence.NoSQLBinaryStore; public class CatalogBinaryStore { private final NamedCache cache; public static void main(String args[]) { CatalogBinaryStore catalogBinaryStore = new CatalogBinaryStore(); catalogBinaryStore.create(); catalogBinaryStore.get(); } /** * Parses the command line args, opens the cache. */ CatalogBinaryStore() { String cacheName = "BinaryCache"; CacheFactory.ensureCluster(); cache = CacheFactory.getCache(cacheName); } /** * Insert a kv pair if it doesn't exist, or read/update it if it does. */ void create() { /* Use key "/p/pof/catalog1" to store the person object. */ final Key key = Key.createKey(Arrays.asList("p", "pof", "catalog1")); /* Create a fresh Catalog object. */ Catalog catalog = createCatalog(); /* insert/update the Catalog object in the cache */ cache.put(key, catalog); // CacheFactory.releaseCache(cache); } private Catalog createCatalog() { final Catalog catalog = new Catalog(); catalog.setJournal("Oracle Magazine"); catalog.setPublisher("Oracle Publishing"); catalog.setEdition("November-December 2004"); catalog.setTitle("From ADF UIX to JSF"); catalog.setAuthor("Jonas Jacobi"); return catalog; } void get() { final Key key = Key.createKey(Arrays.asList("p", "pof", "catalog1")); final Object value = cache.get(key); final Catalog catalog; if (value != null) { catalog = (Catalog)value; /* Print Catalog as a JSON string. */ System.out.println("Journal: " + catalog.getJournal()); System.out.println("Publisher: " + catalog.getPublisher()); System.out.println("Edition: " + catalog.getEdition()); System.out.println("Title: " + catalog.getTitle()); System.out.println("Author: " + catalog.getAuthor()); } } } Right-click on CatalogBinaryStore.java in Application Navigator and select Run. A Catalog user type instance gets created and persisted to the Oracle Coherence cache and subsequently the Catalog instance is retrieved from the cache and the properties output. In this article we configured Oracle Coherence caches to be used with Oracle NoSQL Database. We stored a Catalog user type instance in a single node cluster cache and subsequently fetched and output the Catalog instance.
↧