This chapter describes how to use dependency injection and JNDI to access Coherence caches. Instructions are also provided for packaging Coherence applications as a Grid ARchive (GAR).
This chapter includes the following sections:
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 file must be packaged within an EAR that includes the dependent GAR file.
The following is an example of a Coherence application directory structure, in which myCohApp/
is the staging directory:
A GAR must be packaged in an EAR to be referenced by other JavaEE modules. For details on creating an EAR, see Developing Applications for Oracle WebLogic Server. The following is an example of a Coherence application that is packaged within an EAR:
Example 3-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.5/ 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>
A GAR file must contain a Coherence application deployment descriptor (cohererence-application.xml
) located in the META-INF
directory. The presence of the deployment descriptor indicates a valid GAR. For a detailed reference of all the available elements in the descriptor, see Appendix A, "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>
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 the container.
<?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>
Data caches are defined in a coherence-cache-config.xml
file that is packaged in a GAR file. For details on Coherence caches and their configuration, see Developing Applications with Oracle Coherence.
The following example creates a distributed cache named myCache
. As an alternative, a cache name 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>
Applications use the Coherence NamedCache
API to interact with a Coherence cache. This object 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 3-3 illustrates using dependency injection to get a cache named myCache
. For details on JavaEE annotations and dependency injection, see Developing Applications for Oracle WebLogic Server.
Example 3-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 3-4 illustrates a <resource-ref>
element that identifies myCache
as the NamedCache
. For details on using JNDI in Oracle WebLogic Server, see Developing JNDI Applications for 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 3-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 3-4:
try { Context ctx = new InitialContext(); cache = (NamedCache) ctx.lookup("java:comp/env/coherence/myCache"); cache.put(key, value); } catch (NamingException ne)
Coherence provides a full-featured API for interacting with a cache and for performing data grid operations. For details on using the API to develop applications, see Developing Applications with Oracle Coherence. For a reference of the Coherence API, see Java API Reference for Oracle Coherence.
Some of the features include:
basic get
, put
, and putAll
operations
querying a cache
processing data in a cache using entry processors and aggregators
event notifications
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. For details on using POF in your applications, see Developing Applications with Oracle Coherence.
Coherence applications support the use of an application lifecycle listener. The listener allows custom processing to occur before and after the creation and destruction of Coherence caches and clustered services. The listener class must implement the com.tangosol.application.LifecycleListener
interface. See the Oracle Coherence Java API Reference 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>package.MyAppLifecycleListener</class> </application-lifecycle-listener> </coherence-application>
TopLink Grid is an integration between TopLink and Coherence. Developers use the standard Java Persistence API (JPA) in their applications and take advantage of the scalability of 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. For detailed information on using and configuring TopLink Grid, 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 WegLogic Server system classpath and does not need to be included as part of a GAR or an application (EAR) module.
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 3-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>
...
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 3-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. The Coherence container 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
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. For details on setting up, configuring, and using Coherence*Web in WebLogic Server, see Administering HTTP Session Management with Oracle Coherence*Web.
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. For details on setting up a Coherence proxy server tier in WebLogic Server to allow remote connections, see Administering Clusters for Oracle WebLogic Server. For details on creating Coherence*Extend client applications, see Developing Remote Clients for Oracle Coherence.