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

Uncategorized

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)
<shared-cache-mode> element value
Description
ALL Try to Cache all entities
ENABLE_SELECTIVE Try to Cache only entities that are selected by @Cacheable
DISABLE_SELECTIVE Try to Cache all entities, except those selected by @Cacheable(false)
NONE Disable the cache
UNSPECIFIED Use EclipseLink default

 

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+

 

Comments (6)

Post a comment

Your email address will not be published. Required fields are marked *

Payara needs the contact information you provide to us to contact you about our products and services. You may unsubscribe from these communications at any time. For information on how to unsubscribe, as well as our privacy practices and commitment to protecting your privacy, please review our Legal & Privacy Policy.

  1. Guillermo González de Agüero

    Great post! Does the JMS coordination also work when resources are defined via annotations/deployment descriptor? That eliminates management there too.

  2. Bogdan Popa

    Hi Lenny, thanks for this blog post.
    I’m having some issues to enable the EclipseLink cache coordination in a setup of 2 standalone Payara 4.1.2.148 server instances.
    Hazelcast is configured for AWS and the 2 servers are joining in a HZ cluster. I have configured the persistence as in your example and I have dropped the MDB and change it for my persistence unit.
    The JPA cache coordination doesn’t work when changing the entity values on one server. I’ll get the old values on the other server.

    I was wondering if the HZ cluster will automatically configure itself as a JMS cluster or I’ll need to create a JMS cluster between the 2 servers?

    Thank-you for any feedback on this issue.

  3. Kamlendu Pandey

    Can I have an example application for JPA Coordination cache? . Pl give the link. It will be very helpful

    1. Sven Diedrichsen

      Hi Kamlendu,
      there is a good example project provided by Hans here: https://github.com/thehpi/cache-coordination

  4. Hans Pikkemaat

    Hi Lenny I’m trying to get this working but no luck. I created a little test application for this: https://github.com/thehpi/cache-coordination
    Would be great if you could point me in the right direction.

  5. Jadon Ortlepp

    Hi Hans,

    Could you please post to https://groups.google.com/g/payara-forum where a few more of the team can see this and hopefully offer some advice.

    Many thanks.

Related Posts

4 minutes
Uncategorized

Leading the Way: Payara Platform Community 7 Beta Now Fully Jakarta EE 11 Certified

We’re excited to announce that Payara Platform Community 7 Beta application server is now fully certified as Jakarta EE 11 […]

What Is a Java Application Server? A Short Guide 6 minutes
Jakarta EE

What Is a Java Application Server? A Short Guide

Enterprise Java applications power global commerce, healthcare, government and countless other industries. These systems must be scalable, secure and […]

10 minutes
Uncategorized

Java’s 30th Anniversary: A Celebration of Legacy, Evolution and Community

May 2025 marks a monumental milestone in software development: Java turns 30. The impact of this language on the […]