Creating Coherence Applications for WebLogic Server

2 Creating Coherence Applications for WebLogic Server

Coherence caches can be accessed using dependency injection and JNDI. Coherence applications can be packaged as a Grid ARchive (GAR).

This chapter includes the following sections:

Packaging Coherence Applications

Coherence applications use a specific directory structure. You can deploy a Coherence application as a collection of files within this directory structure, known as exploded directory format, or as an archived file called a Grid ARchive (GAR) with a .gar extension.

A GAR module includes the artifacts that comprise a Coherence application. The /META-INF directory contains the deployment descriptor for the Coherence application (cohererence-application.xml). The presence of the deployment descriptor indicates a valid GAR. An additional subdirectory, the /lib directory, is used for storing dependency JAR files. Compiled Java classes that make up a Coherence application (entry processors, aggregators, filters, and so on) are placed in the root directory in the appropriate Java package structure.

A GAR module can also contain a cache configuration file (coherence-cache-config.xml) and a Portable Object Format (POF) serialization configuration file (pof-config.xml). The location of these files is defined within the Coherence application deployment descriptor. Typically, the files are placed in the /META-INF directory; however, they can be located anywhere in the GAR relative to the root or even at a URL-accessible network location.

Note:

If the configuration files are not found at runtime, then the default configuration files that are included in the coherence.jar, which is located in the system classpath, are used.
If the configuration files are located in the root directory of the GAR, then they must not use the default file names; otherwise, the configuration files that are included in the coherence.jar file are found first and the configuration files in the GAR are never loaded.

The entire directory, once staged, is bundled into a GAR file using the jar command. GAR files are deployed as standalone archives to managed Coherence servers that are configured to store cached data.

Client applications that rely on the caches and resources in a GAR module must be packaged within an EAR that includes the dependent GAR. An EAR cannot contain multiple GAR modules. Multiple GAR modules must be merged into a single GAR. That is, a GAR must contain one application deployment descriptor, one cache configuration file, and one POF configuration file.

Directory Structure Example

The following is an example of a Coherence application directory structure, in which myCohApp/ is the staging directory:

Example 2-1 Coherence Application Directory Structure

MyCohApp/
  lib/
  META-INF/
    coherence-application.xml
    coherence-cache-config.xml
    pof-config.xml
  com/myco/
    MyClass.class

Packaging a Grid Archive In an Enterprise Application

A GAR must be packaged in an EAR to be referenced by other JavaEE modules. See Developing Applications for Oracle WebLogic Server for details on creating an EAR. The following is an example of a Coherence application that is packaged within an EAR:

Example 2-2 Coherence Application Packaged in an EAR

MyEAR/
  META-INF/
    application.xml
    weblogic-application.xml
  MyWAR.war
  MyEJB.jar
  MyGAR.gar

Edit the META-INF/weblogic-application.xml descriptor and include a reference to the GAR using the <module> element. The reference is required so that the GAR is deployed when the EAR is deployed. For example:

<?xml version="1.0"?>
<weblogic-application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://xmlns.oracle.com/weblogic/weblogic-application
   http://xmlns.oracle.com/weblogic/weblogic-application/1.6/
   weblogic-application.xsd"
   xmlns="http://xmlns.oracle.com/weblogic/weblogic-application">
   <module>
      <name>MyGAR</name>
      <type>GAR</type>
      <path>MyGAR.gar</path>
   </module>
</weblogic-application>

Creating a Coherence Application Deployment Descriptor

The presence of the deployment descriptor indicates a valid GAR. A GAR file must contain a Coherence application deployment descriptor (cohererence-application.xml) located in the META-INF directory.

For a detailed reference of all the available elements in the descriptor, see coherence-application.xml Deployment Descriptor Elements. The following is an example of a Coherence deployment descriptor that declares a cache configuration file and a POF configuration file that is located in the META-INF directory of the GAR.

<?xml version="1.0"?>
<coherence-application
   xmlns="http://xmlns.oracle.com/coherence/coherence-application">
   <cache-configuration-ref>META-INF/coherence-cache-config.xml
   </cache-configuration-ref>
   <pof-configuration-ref>META-INF/pof-config.xml</pof-configuration-ref>
</coherence-application>

Using JNDI to Override Configuration

Coherence provides the ability to override any XML element value in a configuration file using JNDI properties.

The use of JNDI properties allows a single version of a configuration file to be used for deployment and then altered as required at runtime.

To define a JNDI property, add an override-property attribute to an XML element with a value set to a JNDI context. The following example defines a JNDI property with a cache-config/MyGar context for the <cache-configuration-ref> element in a coherence-application.xml deployment descriptor. The JNDI property is used at runtime to override the cache configuration reference and specify a different cache configuration file. The JNDI context of cache-config is a well known context used and registered by a managed Coherence server.

<?xml version="1.0"?>
<coherence-application
   xmlns="http://xmlns.oracle.com/coherence/coherence-application">
   <cache-configuration-ref override-property="cache-config/MyGar">
      META-INF/coherence-cache-config.xml</cache-configuration-ref>
   <pof-configuration-ref>META-INF/pof-config.xml</pof-configuration-ref>
</coherence-application>

Defining a Data Cache

Data caches are defined in a coherence-cache-config.xml file that is packaged in a GAR file.

See Developing Applications with Oracle Coherence for details on Coherence caches and their configuration.

The following example creates a distributed cache named myCache. As an alternative, a cache mapping may be defined with the asterisk (*) wildcard, which allows an application to use the distributed cache by specifying any name.

<?xml version="1.0" encoding="windows-1252"?>
<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
   coherence-cache-config.xsd">
 
   <caching-scheme-mapping>
      <cache-mapping>
         <cache-name>myCache</cache-name>
         <scheme-name>distributed</scheme-name>
      </cache-mapping>
   </caching-scheme-mapping>
   
   <caching-schemes>
      <distributed-scheme>
         <scheme-name>distributed</scheme-name>
         <service-name>DistributedService</service-name>
         <backing-map-scheme>
           <local-scheme/>
         </backing-map-scheme>
         <autostart>true</autostart>
      </distributed-scheme>
   </caching-schemes>
</cache-config>

Coherence does not support the use of a replicated cache scheme if a GAR module is used in multiple EAR modules (packaged either individually or as a shared GAR) on a managed Coherence server. An alternative is to use a near cache instead of a replicated cache.

Accessing a Data Cache

Applications use the Coherence NamedCache API to interact with a Coherence cache.

The Coherence cache holds resources that are shared among members of a Coherence cluster. An application can obtain a NamedCache object either by dependency injection or by using a JNDI lookup.

To Obtain a Cache by Dependency Injection

An @Resource annotation can be used in a servlet or an EJB to dynamically inject the NamedCache. This annotation cannot be used in a JSP. The name of the cache used in the annotation must be defined in the application's coherence-cache-config.xml file.

Example 2-3 illustrates using dependency injection to get a cache named myCache. See Developing Applications for Oracle WebLogic Server for details on JavaEE annotations and dependency injection.

Example 2-3 Obtaining a Cache Resource by Dependency Injection

...
@Resource(mappedName="MyCache")
com.tangosol.net.NamedCache nc;
...

To Obtain the NamedCache by JNDI Lookup

A component-scoped JNDI tree can be used in EJBs, servlets, or JSPs to get a NamedCache reference.

To use a JNDI lookup, define a resource-ref of type com.tangosol.net.NamedCache in either the web.xml or ejb-jar.xml file. Example 2-4 illustrates a <resource-ref> element that identifies myCache as the NamedCache. See Developing JNDI Applications for Oracle WebLogic Server for details on using JNDI in Oracle WebLogic Server.

Note:

The <res-auth> and <res-sharing-scope> elements do not appear in the example. The <res-auth> element is ignored because currently no resource sign-on is performed to access data caches. The <res-sharing-scope> element is ignored because data caches are sharable by default and this behavior cannot be overridden.

Example 2-4 Defining a NamedCache as resource-ref for JNDI Lookup

...
<resource-ref>
  <res-ref-name>coherence/myCache</res-ref-name>
  <res-type>com.tangosol.net.NamedCache</res-type>
  <mapped-name>MyCache</mapped-name>
</resource-ref>
...

The following example performs a JNDI lookup to get a NamedCache reference that is defined in Example 2-4:

try {
   Context ctx = new InitialContext();
   cache = (NamedCache) ctx.lookup("java:comp/env/coherence/myCache");
   cache.put(key, value);
}
catch (NamingException ne)

Using the Coherence API

Coherence provides a full-featured API for interacting with a cache and for performing data grid operations.

Some of the features of the Coherence API include:

basic get, put, and putAll operations
querying a cache
processing data in a cache using entry processors and aggregators
event notifications

See Developing Applications with Oracle Coherence for details on using the API to develop applications. See Java API Reference for Oracle Coherence for a reference of the Coherence API.

Using POF for Serialization

Objects that are placed in a cache must be serializable. The Portable Object Format (also referred to as POF) is a language agnostic binary format. POF is designed to be efficient in both space and time and is the recommended serialization option in Coherence. See Developing Applications with Oracle Coherence for details on using POF in your applications.

Using a Coherence Application Lifecycle Listener

The Coherence Application Lifecycle listener allows custom processing to occur before and after the creation and destruction of Coherence caches and clustered services.

Coherence applications support the use of an application lifecycle listener. The listener class must implement the com.tangosol.application.LifecycleListener interface. See the Java API Reference for Oracle Coherence for details on the interface.

Override the following methods provided in the LifecycleListener interface and add any required functionality:

preStart(Context) – called before the application is activated
postStart(Context) – called after the application is started
preStop(Context) – called before the application stops its services
postStop(Context) – called after the application is stopped

To use an application lifecycle listener class, declare the fully qualified name of the class within the <application-lifecycle-listener> element in the coherence-application.xml deployment descriptor and include the class in the /lib directory of the GAR. The following is an example of declaring an application lifecycle listener class that is named MyAppLifecycleListener.

<?xml version="1.0"?>
<coherence-application
   xmlns="http://xmlns.oracle.com/coherence/coherence-application">
   <cache-configuration-ref>META-INF/coherence-cache-config.xml
   </cache-configuration-ref>
   <pof-configuration-ref>META-INF/pof-config.xml</pof-configuration-ref>
   <application-lifecycle-listener>
      <class-name>package.MyAppLifecycleListener</class-name>
   </application-lifecycle-listener>
</coherence-application>

Accessing and Retrieving Relational Data

Developers use the standard Java Persistence API (JPA) in their applications and take advantage of the scalability of Coherence to access and retrive relational data.

TopLink Grid is an integration between TopLink and Coherence. TopLink Grid is used to store some or all of a domain model in the Coherence data grid and can also be used as a level 2 cache. See Integrating Oracle Coherence.

The TopLink Grid library (toplink-grid.jar) is located in the INSTALL_HOME\oracle_common\modules\oracle.toplink_version directory. The library is included as part of the WebLogic Server system classpath and does not need to be included as part of a GAR or an application (EAR) module.

Specifying the Eclipse Persistence Provider

The persistence.xml file is the JPA persistence descriptor file. This is where you configure the persistence unit, the persistence provider, and any vendor-specific extensions that this reference describes.

In the file, the provider element specifies the name of the vendor's persistence provider class. When working with Oracle TopLink, enter org.eclipse.persistence.jpa.PersistenceProvider as the value for this element.

Example 2-5 Sample persistence.xml File

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.0" xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">
  <persistence-unit name="JPA" transaction-type="RESOURCE_LOCAL">
    <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
    <class>com.oracle.handson.Employees</class>
   ...

Packaging a Persistence Unit

JPA persistence units (entity classes and resources, including the persistence.xml file) that use TopLink Grid should be packaged as a JAR and included within an EAR module. For example, the JAR can be placed in the APP-INF/lib directory or root of the EAR module that contains the GAR module.

Example 2-6 Coherence and JPA Application Packaged in an EAR

MyEAR/
  APP-INF
    /lib/MyPersistenceUnit.jar
  META-INF/
    application.xml
    weblogic-application.xml
  MyWAR.war
  MyEJB.jar
  MyGAR.gar

Note:

Persistence files cannot be placed in a WAR file. Any persistence files placed in the WAR file will not be found at runtime. Coherence only has access to the application classloader.

Unlike the application tier, the Coherence data tier only requires the deployment of a GAR. For the data tier, include the persistence unit JAR within the /lib directory of the GAR. For example:

MyCohApp/
  lib/
    MyPersistence.jar
  META-INF/
    coherence-application.xml
    coherence-cache-config.xml
    pof-config.xml
  com/myco/
    MyClass.class

Using Coherence for Session Management

Web applications can chose to use Coherence for storing and replicating session state.

The session management features of Coherence are implemented by the Coherence*Web component. See Administering HTTP Session Management with Oracle Coherence*Web for details on setting up, configuring, and using Coherence*Web in WebLogic Server.

Creating Extend Clients in WebLogic Server

Client applications can chose to use Coherence*Extend to interact with Coherence caches without becoming members of a Coherence cluster.

Client applications connect to managed Coherence proxy servers and are unaware that cache and invocation service requests are being executed remotely. Remote clients may be deployed within a WebLogic Server domain or may be external to WebLogic Server. See Administering Clusters for Oracle WebLogic Server for details on setting up a Coherence proxy server tier in WebLogic Server to allow remote connections. See Developing Remote Clients for Oracle Coherence for details on creating Coherence*Extend client applications,.

Using a JCache Cache in WebLogic Server

Applications that are deployed to a managed Coherence container can use the JCache API and JCache provider that is implemented by Coherence.

See Developing Applications with Oracle Coherence for details on using JCache with Coherence.

Add the COHERENCE_HOME/lib/cache-api.jar and COHERENCE_HOME/lib/coherence-jcache.jar libraries to the /lib directory in a GAR file.

Edit the cache configuration file that is referenced in the coherence-application.xml file to include either the JCache namespace or JCacheExtend namespace. For example:

<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
   xmlns:jcache="class://com.tangosol.coherence.jcache.JCacheNamespace"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config 
   coherence-cache-config.xsd">
   ...

Use the JCahe API to create and use a JCache cache. For example within a servlet:

static private Cache<ContactId, Contact> getCache(String cacheName)
   {
   CachingProvider provider = Caching.getCachingProvider();
   CacheManager mgr = Caching.getCachingProvider().getCacheManager();
   
   Cache<ContactId, Contact> cache = null;
   
   try { 
      cache = mgr.getCache(cacheName, ContactId.class, Contact.class); 
   }
 
   catch (IllegalStateException e) {
 
      if (cache == null) {
      PartitionedCacheConfiguration config = new 
         PartitionedCacheConfiguration<ContactId, Contact>();
      config.setTypes(ContactId.class, Contact.class);
      config.setStatisticsEnabled(true); config.setManagementEnabled(true);
      cache = mgr.createCache(cacheName, config); 
      }
   return cache;
}