Implementing the Solution

Disabling Entity Caching

Disable the shared cache for highly volatile entities or for all entities as required. To disable the shared cache for all objects, use the <shared-cache-mode> element in the persistence.xml file. For example:

<shared-cache-mode>NONE</shared-cache-mode>

The default configuration is DISABLE_SELECTIVE and allows caching to be disabled per entity. To selectively enable or disable the shared cache, use the shared attribute of the @Cache annotation when defining an entity. For example:

@Entity
@Cache(shared=false)
public class Employee {
}

Refreshing the Cache

Refreshing a cache reloads the cache from the database to ensure that an application is using current data. There are different ways to refresh a cache.

The @Cache annotation provides the alwaysRefresh and refreshOnlyIfNewer attributes which force all queries that go to the database to refresh the cache. The cache is only actually refreshed if the optimistic lock value in the database is newer than in the cache.

@Entity
@Cache(
   alwaysRefresh=true, 
   refreshOnlyIfNewer=true)
public class Employee {
}

The jakarta.persistence.Cache interface includes methods that remove stale objects if the cache is out of date:

• The evictAll method invalidates all of the objects in the cache.

  em.getEntityManagerFactory().getCache().evictAll();
  

• The evict method invalidates specific classes.

  em.getEntityManagerFactory().getCache().evict(MyClass);
  

The preceding methods are passive and refresh objects only the next time the cache is accessed. To actively refresh an object, use the EntityManager.refresh method. The method refreshes a single object at a time.

Another possibility is to use the setHint method to set a query hint that triggers the query to refresh the cache. For example:

Query query = em.createQuery("Select e from Employee e");
query.setHint("jakarta.persistence.cache.storeMode", "REFRESH");

Lastly, native API methods are also available. For details, see the ClassDescriptor documentation in Java API Reference for EclipseLink.

Setting Entity Caching Expiration

Cache expiration makes a cached object instance invalid after a specified amount of time. Any attempt to use the object causes the most up-to-date version of the object to be reloaded from the data source. Expiration can help ensure that an application is always using the most recent data. There are different ways to set expiration.

The @Cache annotation provides the expiry and expiryTimeOfDay attributes, which remove cache instances after a specific amount of time. The expiry attribute is entered in milliseconds. The default value if no value is specified is -1, which indicates that expiry is disabled. The expiryTimeOfDay attribute is an instance of the org.eclipse.persistence.annotations.TimeOfDay interface. The following example sets the object to expire after 5 minutes:

@Entity
@Cache(expiry=300000)
public class Employee {
}

Setting Optimistic Locking

Optimistic locking prevents one user from writing over another user's work. Locking is important when multiple servers or multiple applications access the same data and is relevant in both single-server and multiple-server environments. In a multiple-server environment, locking is still required if an application uses cache refreshing or cache coordination. There are different ways to set optimistic locking.

The standard JPA @Version annotation is used for single valued value and timestamp based locking. However, for advanced locking features use the @OptimisticLocking annotation. The @OptimisticLocking annotation specifies the type of optimistic locking to use when updating or deleting entities. Optimistic locking is supported on an @Entity or @MappedSuperclass annotation. The following policies are available and are set within the type attribute:

• ALL_COLUMNS: This policy compares every field in the table in the WHERE clause when performing an update or delete operation.

• CHANGED_COLUMNS: This policy compares only the changed fields in the WHERE clause when performing an update operation. A delete operation compares only the primary key.

• SELECTED_COLUMNS: This policy compares selected fields in the WHERE clause when performing an update or delete operation. The fields that are specified must be mapped and not be primary keys.

• VERSION_COLUMN: (Default) This policy allows a single version number to be used for optimistic locking. The version field must be mapped and not be the primary key. To automatically force a version field update on a parent object when its privately owned child object's version field changes, use the cascaded method set to true. The method is set to false by default.

Using Cache Coordination

Cache coordination synchronizes changes among distributed sessions. Cache coordination is most useful in application server clusters where maintaining consistent data for all applications is challenging. Moreover, cache consistency becomes increasingly more difficult as the number of servers within an environment increases.

Cache coordination works by broadcasting notifications of transactional object changes among sessions (EntityManagerFactory or persistence unit) in the cluster. Cache coordination is most useful for applications that are primarily read-based and when changes are performed by the same application operating with multiple, distributed sessions.

Cache coordination significantly minimizes stale data, but does not completely eliminate the possibility that stale data might occur because of latency. In addition, cache coordination reduces the number of optimistic lock exceptions encountered in distributed architectures, and reduces the number of failed or repeated transactions in an application. However, cache coordination in no way eliminates the need for an effective locking policy. To ensure the most current data, use cache coordination with optimistic or pessimistic locking; optimistic locking is preferred.

Cache coordination is supported over the Remote Method Invocation (RMI) and Java Message Service (JMS) protocols and is configured either declaratively by using persistence properties in a persistence.xml file or by using the cache coordination API. System properties that match the persistence properties are available as well.

For additional details on cache coordination see:

Jakarta Persistence API (JPA) Extensions Reference for EclipseLink

@Entity
@Cache(CacheCoordinationType.SEND_NEW_OBJECTS_CHANGES)
public class Employee {
}

<property name="eclipselink.cache.coordination.protocol" value="jms" />
<property name="eclipselink.cache.coordination.jms.topic" 
   value="jms/EmployeeTopic" />
<property name="eclipselink.cache.coordination.jms.factory"
   value="jms/EmployeeTopicConnectionFactory" />

<property name="eclipselink.cache.coordination.jms.host"
   value="t3://myserver:7001/" />

<property name="eclipselink.cache.coordination.jndi.user" value="user" />
<property name="eclipselink.cache.coordination.jndi.password" value="password" />

<property name="eclipselink.cache.coordination.protocol" value="rmi" />

-Declipselink.cache.coordination.jms.host=t3://myserver:7001/

<property name="eclipselink.cache.coordination.jndi.user" value="user" /><property name="eclipselink.cache.coordination.jndi.password" value="password" />

<property name="eclipselink.cache.coordination.propagate-asynchronously"
   value="false" />

<property name="eclipselink.cache.coordination.channel" value="EmployeeChannel" />

<property name="eclipselink.cache.coordination.rmi.announcement-delay"
   value="1000" />
<property name="eclipselink.cache.coordination.rmi.multicast-group"
   value="239.192.0.0" />
<property name="eclipselink.cache.coordination.rmi.multicast-group.port"
   value="3121" />
<property name="eclipselink.cache.coordination.packet-time-to-live" value="2" />

Clustered Databases and Oracle RAC

Some databases support clustering the database across multiple servers. Oracle Real Application Clusters (RAC) allows for a single database to span multiple different server nodes. Oracle RAC also supports table and node partitioning of data. A database cluster allows for any of the data to be accessed from any node in the cluster. However, it is generally more efficient to partition the data access to specific nodes, to reduce cross node communication. Partitioning can be used in conjunction with a clustered database to reduce cross node communication, and improve scalability. For details on using EclipseLink with Oracle RAC, see Using EclipseLink with Oracle RAC.

Adhere to the following requirements when using data partitioning with a database cluster:

• Partition policy should not enable replication, as database cluster makes data available to all nodes.

• Partition policy should not use unions, as database cluster returns the complete query result from any node.

• A DataSource and connection pool should be defined for each node in the cluster.

• The application's data access and data partitioning should be designed to have each transaction only require access to a single node.

• Usage of an exclusive connection for an EntityManager is recommended to avoid having multiple nodes in a single transaction and avoid 2-phase commit.