Difference between revisions of "EclipseLink/Examples/JPA/CacheCoordination"

Revision as of 10:12, 21 September 2010

Overview

EclipseLink supports a shared (L2) object cache that avoids database access for objects and their relationships. This cache is enabled by default which is normally not a problem, unless the database is modified directly by other applications, or by the same application on other servers in a clustered environment.

There are many solutions to caching in a clustered environment, including:

• disable the shared cache
• only cache read-only objects
• set a cache invalidation timeout
• use refreshing on objects/queries when fresh data is required
• use optimistic locking (writes on stale data will fail, and will automatically invalidate the cache)
• using a distributed cache (such as Oracle TopLink Grid with Oracle Coherence)
• using cache coordination (synchronizing the caches, as discussed in this example)

This example gives an overview of the cache coordination option.

EclipseLink provides a cache coordination feature that enables a set of EclipseLink sessions to synchronize their changes in a distributed network such as an application server cluster. Cache coordination works by each EclipseLink session (ServerSession/persistence unit) on each server in the cluster being able to broadcast notification of transactional object changes to the other EclipseLink sessions in the cluster. EclipseLink supports cache coordination over RMI and JMS. The cache coordination framework is also extensible so other options could be developed.

This example demonstrates enabling cache coordination using JMS or RMI for a JEE EJB 3.0 SessionBean application using JPA deployed to an Oracle Weblogic cluster. The example could be ported to other JEE application servers or environments. EclipseLink supports cache coordination in any Java environment, including Java SE, or Tomcat.

If you encounter any issues in running this example, or are running in another app server or version please discuss, here

Prerequisites

The following software is required to run this example:

• Oracle Weblogic Server (10.3.3 was used, but any WLS version supporting EJB 3 should work, or any JEE application server with some work) - download link
• ant (1.7 was used, but other versions should also work) - download link
• Oracle database (or any other client/server database (embedded database will not work as cannot be accessed from all machines)) - download link
• EclipseLink (WLS 10.3.4 includes EclipseLink 2.1, a 2.2 build or any >= 1.2 version could be used) - download link
• Cache coordination example - download link

Configuring the example

Running the example

1. Install Oracle WebLogic (or your desired JEE application server, or use existing application server)
2. Configure paths to server in the <example>/build.xml (JEE_HOME, JEE_SERVER, JEE_HOST, JEE_USER, JEE_PASSWORD)
3. Upgrade the eclipselink.jar in your application server to be the latest release (not required)
   1. In WebLogic the eclipselink.jar is in <weblogic-home>/modules/ directory named org.eclipse.persistence_1.0.0.0_x-x.jar, where x depends on the version of WebLogic.
   2. If using another application server you may need to add the eclipselink.jar to your application server's library path.
   3. You must also update the path in the <example>/build.xml to point to EclipseLink, JPA and EJB (JPA_LIB, EJB_LIB, ECLIPSELINK_LIB)
4. Install Oracle database (or use existing database, ensure the database is not an embedded database)
5. Configure database in <example>/build.xml (DB_DRIVER, DB_URL, DB_USER, DB_PASSWORD)
   1. or, you could create your own DataSource in your application server using your application server's tools or config,
   2. this example uses ant to automatically create a DataSource in the server.
6. Configure persistence.xml in <example>src/meta-inf/
   1. Configure the JMS host if not running a clustered JMS Topic.
   2. If using another application server, ensure the "eclipselink.target-server" is set to the correct platform for your server.
   3. The example uses JMS by default, if RMI is desired, change the protocol to rmi, or switch the persistence.xml file with the persistence-wls-rmi.xml file.
7. Install ant (or uses existing ant install)
8. Ensure the prompt environment variables have been set to use the JVM provided in the WebLogic install (JRockit was used for this example)
9. Create the WebLogic domain and cluster
   1. Run "ant create-cluster",
   2. this will create a new WebLogic domain, a cluster and three servers on the same machine but with different ports.
   3. An existing domain/cluster could also be used, or separate machines for each server in the cluster.
   4. If using an existing domain/cluster, you will need to manually configure and start each server.
10. Start the cluster
    1. Run "ant start-cluster",
    2. this will start 4 weblogic servers, an admin server, and 3 servers in a cluster.
11. Configure the cluster
    1. Run "ant setup-cluster"
    2. this will create a DataSource, ConnectionPool, JMSServer and deploy then to the cluster.
12. Build the application
    1. Run "ant"
    2. this will compile the example code and build the employee.ear
13. Deploy the application
    1. Run "ant deploy"
    2. this will deploy the ear to the cluster
14. Run the example
    1. Run "ant example"
    2. This should give the following output,

Buildfile: build.xml

example:
     [java] Populating database.
     [java] Connecting to server:t3://qaott48.ca.oracle.com:7031/
     [java] Preloading cache on all servers.
     [java] Looking up next EmployeeServer.
     [java] Connecting to server:t3://qaott48.ca.oracle.com:7041/
     [java] Loading all Employees into cache.
     [java] Looking up next EmployeeServer.
     [java] Connecting to server:t3://qaott48.ca.oracle.com:7021/
     [java] Loading all Employees into cache.
     [java] Looking up next EmployeeServer.
     [java] Connecting to server:t3://qaott48.ca.oracle.com:7031/
     [java] Loading all Employees into cache.
     [java] Preloading done.
     [java] Updating employee on each server.
     [java] Looking up next EmployeeServer.
     [java] Connecting to server:t3://qaott48.ca.oracle.com:7041/
     [java] Finding employee: 31535
     [java] Employee name was: Brendan 94
     [java] Updating employee: 31535
     [java] Employee name updated to: 513101 513101
     [java] Looking up next EmployeeServer.
     [java] Connecting to server:t3://qaott48.ca.oracle.com:7021/
     [java] Finding employee: 31535
     [java] Employee name was: 513101 513101
     [java] Updating employee: 31535
     [java] Employee name updated to: 465529 465529
     [java] Looking up next EmployeeServer.
     [java] Connecting to server:t3://qaott48.ca.oracle.com:7031/
     [java] Finding employee: 31535
     [java] Employee name was: 465529 465529
     [java] Updating employee: 31535
     [java] Employee name updated to: 353681 353681
     [java] Looking up next EmployeeServer.
     [java] Connecting to server:t3://qaott48.ca.oracle.com:7041/
     [java] Finding employee: 31535
     [java] Employee name was: 353681 353681
     [java] Updating employee: 31535
     [java] Employee name updated to: 302792 302792
     [java] Looking up next EmployeeServer.
     [java] Connecting to server:t3://qaott48.ca.oracle.com:7021/
     [java] Finding employee: 31535
     [java] Employee name was: 302792 302792
     [java] Updating employee: 31535
     [java] Employee name updated to: 76582 76582
     [java] Looking up next EmployeeServer.
     [java] Connecting to server:t3://qaott48.ca.oracle.com:7031/
     [java] Finding employee: 31535
     [java] Employee name was: 76582 76582
     [java] Updating employee: 31535
     [java] Employee name updated to: 944086 944086
     [java] Looking up next EmployeeServer.
     [java] Connecting to server:t3://qaott48.ca.oracle.com:7041/
     [java] Finding employee: 31535
     [java] Employee name was: 944086 944086
     [java] Updating employee: 31535
     [java] Employee name updated to: 89857 89857
     [java] Looking up next EmployeeServer.
     [java] Connecting to server:t3://qaott48.ca.oracle.com:7021/
     [java] Finding employee: 31535
     [java] Employee name was: 89857 89857
     [java] Updating employee: 31535
     [java] Employee name updated to: 51640 51640
     [java] Looking up next EmployeeServer.
     [java] Connecting to server:t3://qaott48.ca.oracle.com:7031/
     [java] Finding employee: 31535
     [java] Employee name was: 51640 51640
     [java] Updating employee: 31535
     [java] Employee name updated to: 872883 872883
     [java] Looking up next EmployeeServer.
     [java] Connecting to server:t3://qaott48.ca.oracle.com:7041/
     [java] Finding employee: 31535
     [java] Employee name was: 872883 872883
     [java] Updating employee: 31535
     [java] Employee name updated to: 762396 762396

BUILD SUCCESSFUL

Links

• WLS ant tasks documentation
• WLS admin console documentation
• WLS MBean reference