SOA Suite 12c Coherence Adapter

Hello All,

Recently i came up with a use case where how we can implement oracle caching in SOA services, As few of you may know that OSB 11G already provides a facility of cache in OSB level only but in SOA11G there was no such configuration was available.

With the latest SOA version 12C, oracle added a coherence adapter which uses oracle caching management system.

What is SOA 12 C coherence:

The Coherence Adapter provides access to Oracles Coherence Data Grid.  The adapter provides access to the cache capabilities of the grid, it does not currently support the many other features of the grid such as entry processors – more on this at the end of the blog.

Previously if you wanted to use Coherence from within SOA Suite you either used the built in caching capability of OSB or resorted to writing Java code wrapped as a Spring component.  The new adapter significantly simplifies simple cache access operations.

Compatibility:

Note that when using the Coherence adapter in 12.1.3, you would not be able to interact with a remote Coherence cluster other than version 12.1.3. or a newer version.

This is due to a Coherence product limitation on the use of the Coherence extend client with older versions of the extend proxy.

Specifically, regarding compatibility between a Coherence server and an extend client, only forward compatibility is maintained from extend clients to cluster proxy servers. That is, an extend client can connect to cluster servers that have either the same or higher version numbers, but not the lower version numbers.

Oracle Coherence Adapter Features:

You can use the Oracle Coherence Adapter to perform the following activities associated with Oracle Coherence:

• Add a Cache Entry: Create a new entry in the Coherence Cache.
• Remove Cache entries: Identify an item to be removed from the Cache, and the system removes the entry from the Cache. You can also remove multiple entries from the cache by providing a filter or search criteria which match the multiple records in cache.
• Get Cache entry value: After specifying an entry to obtain the associated value, the system returns the value of that entry to you.
• Query Cache: After you identify the Cache, and specify search criteria, the system returns the entries that match the search criteria.

Configuration take place for using it:

When creating a SOA domain the Coherence adapter is shipped with a very basic configuration that you will probably want to enhance to support real requirements.  In this section I look at the configuration required to use Coherence adapter in the real world.

Activate Adapter:

The Coherence Adapter is not targeted at the SOA server by default, so this targeting needs to be performed from within the WebLogic console before the adapter can be used.

Create a cache configuration file:

The Coherence Adapter provides a default connection factory to connect to an out-of-box Coherence cache and also a cache called adapter-local.  This is helpful as an example but it is good practice to only have a single type of object within a Coherence cache, so we will need more than one.  Without having multiple caches then it is hard to clean out all the objects of a particular type.  Having multiple caches also allows us to specify different properties for each cache.  The following is a sample cache configuration file used in the example.

<?xml version="1.0"?>
<!DOCTYPE cache-config SYSTEM "cache-config.dtd">
<cache-config>
  <caching-scheme-mapping>
    <cache-mapping>
      <cache-name>TestCache</cache-name>
      <scheme-name>transactional</scheme-name>
    </cache-mapping>
  </caching-scheme-mapping>
  <caching-schemes>
    <transactional-scheme>
      <scheme-name>transactional</scheme-name>
      <service-name>DistributedCache</service-name>
      <autostart>true</autostart>
    </transactional-scheme>
  </caching-schemes>
</cache-config>

This defines a single cache called TestCache.  This is a distributed cache, meaning that the entries in the cache will distributed across the grid.  This enables you to scale the storage capacity of the grid by adding more servers.  Additional caches can be added to this configuration file by adding additional <cache-mapping> elements.

The cache configuration file is reference by the adapter connection factory and so needs to be on a file system accessed by all servers running the Coherence Adapter.  It is not referenced from the composite.

Create a Coherence Adapter Connection Factory:

We find the correct cache configuration by using a Coherence Adapter connection factory.  The adapter ships with a few sample connection factories but we will create new one.  To create a new connection factory we do the following:

• On the Outbound Connection Pools tab of the Coherence Adapter deployment we select New to create the adapter.

• Choose the javax.resource.cci.ConnectionFactory group.

• Provide a JNDI name, although you can use any name something along the lines of eis/Coherence/Test is a good practice (EIS tells us this an adapter JNDI, Coherence tells us it is the Coherence Adapter, and then we can identify which adapter configuration we are using).

• If requested to create a Plan.xml then make sure that you save it in a location available to all servers.
• From the outbound connection pool tab select your new connection factory so that you can configure it from the properties tab.

• Set the CacheConfigLocation to point to the cache configuration file created in the previous section.
• Set the ClassLoaderMode to CUSTOM.
• Set the ServiceName to the name of the service used by your cache in the cache configuration file created in the previous section.
• Set the WLSExtendProxy to false unless your cache configuration file is using an extend proxy.
• If you plan on using POJOs (Plain Old Java Objects) with the adapter rather than XML then you need to point the PojoJarFile at the location of a jar file containing your POJOs.
• Make sure to press enter in each field after entering your data.  Remember to save your changes when done.

@Note:You may will need to stop and restart the adapter to get it to recognize the new connection factory.

Operations available in SOA 12 C Coherence Adapter:

• put – put an object into the cache with a given key value.
• get – retrieve an object from the cache by key value.
• remove – delete an object from the cache by key value.
• list – retrieve all the objects in the cache.
• listKeys – retrieve all the keys of the objects in the cache.
• removeAll – remove all the objects from the cache.

Put Configuration Steps:

• Cache Type – This is a drop-down combo-box with values – XML, POJO. Use the value that corresponds to the type of item you want to put into the cache.
• Cache Name – Enter a cache name in this text field. This is the name that uniquely identifies the Coherence cache.
• Key – Either enter a key in the text field, or check the auto-generate checkbox to have the key generated. If checked, the key is automatically generated by the Coherence runtime. The key auto-generate process sets the Key Type to String.
• Key Type – Key Type and Key are disabled, if you choose to enter a filter It is enabled if you choose to enter a Key Type and Key. Here Key Type combo-box with list of Java simple types: string, integer, long, float, double.
• Auto-generate Key – Check this box if you want the Coherence Adapter Configuration Wizard to generate a key for you.
• Time to Live – Choose Default, Always, or Custom. If you choose Custom, you can specify a value in milliseconds. This value indicates how long an entry should remain in the Coherence cache. The default is that the message never expires. The Time To Live property is applicable more for Remote Caches than for Local caches. For a Local cache, the entry always remains in the cache until you remove it or the SOA server terminates.

Get Configuration Steps:

• Cache Type - Select XML or POJO from the dropdown list.
• Cache Name -The name of the cache.
• Filter - You can enter a Coherence Query Language filter expression manually. If you do not specify a Filter, the Coherence Adapter Configuration Wizard warns that all items are to be returned.
• Item Count - An integer to specify the limit to the item count returned from the query.
• Index Name - (Optional) A index name to be created in the cache. Select the Sorted checkbox to create a sorted index.
• Return Keys ONLY - Check the box and supply a return key type. If this box is checked, only the keys will be returned whose values match the entries that are returned from the query.
  Index and Ordered field key types are only valid for the POJO Cache Type. For the XML Cache Type, you can only use key() token in the filter expression.
  This means that when you specify a filter expression you can only use the special token key(), which means the cache object key. For example, you could use either of these keys:
  If you are using the POJO cache type, you can create a filter expression that uses both tokens from the POJO object as well as the special built-in key() token.

key() = 1234  

key() = 5678

Use Case:

One example of using the Coherence Adapter is to create a shared memory region that allows SOA composites to share information.  An example of this is provided by Lucas Jellema in his blog entry Coherence Adapter to create cross instance state memory.

However there is a problem in creating global variables that can be updated by multiple instances at the same time.  In this case the get and put operations provided by the Coherence adapter support a last write wins model.  This can be avoided in Coherence by using an Entry Processor to update the entry in the cache, but currently entry processors are not supported by the Coherence Adapter.  In this case it is still necessary to use Java to invoke the entry processor.

Sample Code:

The Sample Code and consists of two JDeveloper projects, one with the cache config file and the other with the Coherence composite.

• CoherenceConfig has the cache config file that must be referenced by the connection factory properties.
• CoherenceSOA has a composite that supports the WSDL introduced at the start of this blog along with the test cases mentioned at the end of the blog.

The Coherence Adapter is a really exciting new addition to the SOA developers toolkit.