4 Accessing and Retrieving Relational Data

TopLink Grid marries the standardization and simplicity of application development using the Java Persistence API (JPA) with the scalability and distributed processing power of Oracle's Coherence Data Grid. Developers can use their investment in JPA and take advantage of the scalability of Coherence. Standard JPA applications interact directly with their primary data store, typically a relational database, but with ActiveCache, TopLink Grid developers can choose to store some or all of their domain model in the Coherence data grid.

For detailed information about configuring TopLink Grid for a Coherence environment, see Integration Guide for Oracle TopLink with Coherence Grid.

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 4-1 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>

...

Adding TopLink Grid Functionality to a Coherence Cluster

As described in Package Applications and Configure Coherence Cluster Scope, Coherence clusters are classloader-scoped according to where you place the coherence.jar file in the classloader hierarchy. The Coherence cluster can be either application server-, EAR-, or WAR-scoped. To make TopLink Grid functionality available to applications running in the cluster, the TopLink Grid JAR file must also be added to the classpath.

TopLink Grid JAR file, toplink-grid-1.0.jar, contains the classes that allow TopLink to interact with Oracle Coherence. You can find the file in the common\deployable-libraries folder of your WebLogic Server distribution.

The following sections describe how to add the JAR for application server-, EAR- and WAR-scoped cluster environments.

Adding TopLink Grid to Application Server-Scoped Coherence Clusters

If you are using TopLink Grid to store JPA Entities in Coherence caches, follow these steps:

Follow the instructions in Configuring Application Server-Scoped Coherence Clusters to include coherence.jar and active-cache.jar in the system classpath.
Edit your WebLogic Server system classpath to include toplink-grid-1.0.jar in the system classpath.

Adding TopLink Grid to EAR-Scoped Coherence Clusters

If you are using TopLink Grid to store JPA Entities in Coherence caches, follow these steps:

Follow the instructions in Configuring EAR-Scoped Coherence Clusters to deploy the coherence.jar and active-cache.jar files as shared libraries.
Use either of the following methods to deploy toplink-grid-1.0.jar as a shared library.
- Use the WebLogic Server Administration Console or the command line to deploy toplink-grid-1.0.jar as a shared library.
```
java weblogic.Deployer -username <> -password <> -adminurl <> -deploy toplink-grid-1.0.jar -name toplink-grid -library -targets <>
```
  If you deploy toplink-grid-1.0.jar as a shared library, refer to it in the weblogic-application.xml file as a library-ref. Example 4-2 illustrates the toplink-grid-1.0.jar referenced in the weblogic-application.xml file.
  Example 4-2 Reference to TopLink Grid JAR File in the weblogic-application.xml File
```
<weblogic-application>
...
  <library-ref>
    <library-name>coherence</library-name>
  </library-ref>
   ...
  <library-ref>
    <library-name>active-cache</library-name>
  </library-ref>
  <library-ref>
    <library-name>toplink-grid</library-name>
  </library-ref>
...
</weblogic-application>
```
- Copy toplink-grid-1.0.jar to the application EAR's APP-INF/lib folder. However, the preferred way is to deploy it as a shared library.

Adding TopLink Grid to WAR-Scoped Coherence Clusters

If you are using TopLink Grid to store JPA Entities in Coherence caches, follow these steps:

Follow the instructions in Configuring WAR-Scoped Coherence Clusters to deploy the coherence.jar and active-cache.jar files.
Use the WebLogic Server Administration Console or the command line to deploy toplink-grid-1.0.jar. The following is a sample command line:
```
java weblogic.Deployer -username <> -password <> -adminurl <> -deploy toplink-grid-1.0.jar -name toplink-grid -library -targets <>
```
Import toplink-grid-1.0.jar as an optional package in the manifest.mf file of each module that will be using Coherence. As an alternative, you can copy it to each of the application WAR's WEB-INF/lib directories.

Example 4-3 illustrates a sample manifest file.
Example 4-3 Manifest File with coherence, active-cache, and toplink-grid
```
Manifest-Version: 1.0
Extension-List: coherence active-cache toplink-grid
coherence-Extension-Name: coherence
active-cache-Extension-Name: active-cache
toplink-grid-Extension-Name: toplink-grid
```