Setting Up Cache JPA Coordination with the Payara Platform using EclipseLink and JMS/Hazelcast

When it comes to clustering and distributed computing performance, some of the challenges you have to overcome involve cache invalidation and coordination. Fortunately, both Payara Server and Payara Micro come with EclipseLink, which supports cache coordination and invalidation out of the box. This blog will explain how to configure this feature for your Payara Data Grid.  We would also like to thank Sven Diedrichsen who is the community member that created the Hazelcast cache coordination.

Turning on 2nd Level Cache in JPA

In order to utilize the cache in JPA, it needs to be turned on. Turning on the cache in JPA can be accomplished using persistence.xml, annotations or both:

• <shared-cache-mode> element inside persistence.xml
• @javax.persistence.Cacheable entity annotation (JPA 2.0 and above)
• @org.eclipse.persistence.annotations.Cache entity annotation (EclipseLink proprietary, use as a last resort)

Using Hazelcast Cache Coordination Protocol (Available on Payara Platform 5.182 and Later)

The easiest method by far, using the Hazelcast Cache Coordination Protocol requires no management, no code and minimal configuration:

• Add eclipselink.cache.coordination.protocol property
• Add eclipselink.cache.coordination.channel property
• Enable L2 cache as described above

The channel property is optional, but is highly recommended if the application has more than one Persistence Unit. Best practice is to name the channel after the persistence unit.

Here is a complete example below:

<?xml version="1.0" encoding="UTF-8" ?>
<persistence version="2.2"
             xmlns="http://xmlns.jcp.org/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence http://xmlns.jcp.org/xml/ns/persistence/persistence_2_2.xsd">
    <persistence-unit name="MyPU" transaction-type="JTA">
        <properties>
            <property name="eclipselink.cache.coordination.protocol" value="fish.payara.persistence.eclipselink.cache.coordination.HazelcastPublishingTransportManager"/>
            <property name="eclipselink.cache.coordination.channel" value="MyPUChannel"/>
        </properties>
        <jta-data-source>jdbc/myDataSource</jta-data-source>
        <shared-cache-mode>DISABLE_SELECTIVE</shared-cache-mode>
    </persistence-unit>
</persistence>

Yup, it's that easy!

Using JMS Cache Coordination Protocol (if using Payara Platform 5.181 or earlier, or Payara 4.x)

If you're running Payara Platform 5.181 or earlier, or Payara Platform 4.x, you can use the JMS Cache Coordination Protocol as an alternative method. Most of the configuration is the same as with Hazelcast protocol as described above, but with the following differences:

• Protocol property should be as follows: <property name="eclipselink.cache.coordination.protocol" value="jms-publishing"/>
• JMS resources need to be configured in the domain
• JMS MDB needs to be added to the application

Adding JMS Resources to the Domain

EclipseLink protocol JMS connection factory defaults to jms/EclipseLinkTopicConnectionFactory - so we want to keep the default to cut down on configuration.

You can use the asadmin commands below or configure the JMS resources via admin console:

# Create a JMS connection pool
$ asadmin create-connector-connection-pool --connectionDefinitionName=javax.jms.TopicConnectionFactory --resourceAdapterName=jmsra jms/EclipseLinkTopicConnectionFactory-Connection-Pool
 
# Create JMS connection pool resource with jms/EclipseLinkTopicConnectionFactory JNDI name
$ asadmin create-connector-resource --poolName=jms/EclipseLinkTopicConnectionFactory-Connection-Pool --target=domain jms/EclipseLinkTopicConnectionFactory
 
# Create resource references for each instance / cluster / Data Grid element desired
$ asadmin create-resource-ref --target=server jms/EclipseLinkTopicConnectionFactory
 
# Create EclipseLink topic
$ asadmin create-jms-resource --resType=javax.jms.Topic --property=Name=EclipseLinkTopic jms/EclipseLinkTopic

Creating JMS MDB in the Application

You can drop the MDB anywhere in your application's source packages.

MDB Example for EclipseLink 2.5+