5 Best Practices

This chapter contains recommendations of how to use TopLink Grid with byte code weaving and lazy loading:

5.1 Changing Compiled Java Classes with Byte Code Weaving

Byte code weaving is a technique for changing the byte code of compiled Java classes. You can configure byte code weaving to enable a number of EclipseLink JPA performance optimizations, including support for the lazy loading of one-to-one and many-to-one relationships, attribute-level change tracking, and fetch groups.

Weaving can be performed either dynamically when entity classes are loaded, or statically as part of the build process. Static byte code weaving can be incorporated into an Ant build using the weaver task provided by EclipseLink.

Dynamic byte code weaving is automatically enabled in Java EE 5-compliant application servers such as Oracle WebLogic. However, in Java SE it must be explicitly enabled by using the JRE 1.5 javaagent JVM command line argument. See "How to Configure Dynamic Weaving for JPA Entities Using the EclipseLink Agent" at the following URL for more information about dynamic byte code weaving for JRE 1.5.


To enable byte code weaving in a Coherence cache server, the Java VM should be invoked with -javaagent:<PATH>\eclipselink.jar. Java SE client applications should be run with the -javaagent argument.

See "Using EclipseLink JPA Weaving" at Eclipsepedia for more information on configuring and disabling static and dynamic byte code weaving.


5.2 Deferring Database Queries with Lazy Loading

Lazy loading is a technique used to defer the querying of objects from the database until they are required. This can reduce the amount of data loaded by an application and improve throughput. A TopLink Grid JPA or native ORM application should lazily load all relationships. Lazy loading is the default for one-to-many and many-to-many relationships in JPA, but is eager for one-to-one and many-to-one relationships. You must explicitly select lazy loading on these relationship types. For example, you can specify lazy loading as an attribute for many of the relationship annotations:

private Publisher parent

For maximum efficiency, lazy loading should be specified for all one-to-one and many-to-one entity relationships that TopLink Grid stores in the Coherence cache. Lazy loading is implemented through byte code weaving in EclipseLink and must be enabled explicitly if not running in a Java EE 5-compliant application server. For more information, see "Changing Compiled Java Classes with Byte Code Weaving".

5.3 Defining Near Caches for Applications Using TopLInk Grid

Near cache is one of the standard cache configurations offered by Oracle Coherence. The use of near caches can improve throughput by avoiding network access when an object is retrieved repeatedly. For example, in an environment where users are pinned to a particular Web server, near caching may improve performance.

The near cache is a hybrid cache consisting of a front cache, which is of limited size and offers fast data access, and a larger back cache, which can be scalable, can load on demand, and provide failover protection.

For applications using Toplink Grid, you configure the near cache in the same way as any other application using Oracle Coherence. See "Near Cache" and "Defining Near Cache Schemes" in the Developers Guide for Oracle Coherence for more information on near caches.


Near caches are used only on a Coherence cache get operation, but not when a Filter operation is executed. This is because the Filter operation is sent to each member, and they return results directly to the caller. In this case, a near cache will not add value.

This can also become an issue if you are using JPQL queries. In the TopLink Grid Grid Read or Grid Entity configurations, JPQL queries are mapped to Filter operations. In the case of either of these configurations, if you execute TopLink JPQL queries, you will not see any cache hits.

5.4 Ensuring Prefixed Cache Names Use Wildcard in Cache Configuration

When using TopLink Grid with applications that use Coherence caches and Coherence*Web, you might want to apply different configuration properties to the TopLink Grid caches for entities and the Coherence*Web caches. The most efficient way to specify and configure a set of caches is to use a wildcard character ("*"). However, this will match both sets of caches. To separate the Coherence*Web caches from entity caches, you must create a wildcard pattern that will match entities only. One way to do this is to prepend a unique prefix to the entity cache names.

The following steps describe how to create and use a custom session customizer to prepend a specified prefix to TopLink Grid-enabled classes.

  1. Create a session customizer class that will prepend TopLink-enabled classes with a specified prefix.

    Example 5-1 illustrates a custom session customizer class, CacheNamePrefixCustomizer, which implements the EclipseLink SessionCustomizer class. The class defines a PREFIX_PROPERTY myapp.cache-prefix that represents the prefix that will be added to the TopLink-enabled classes. The value of the property can be either specified in the persistence.xml file (described in Step 2) or passed in an optional property map to the Persistence.createEntityManagerFactory method.

    Example 5-1 Session Customizer to Prepend

    import java.util.Collection;
    import oracle.eclipselink.coherence.IntegrationProperties;
    import oracle.eclipselink.coherence.integrated.cache.CoherenceInterceptor;
    import oracle.eclipselink.coherence.integrated.internal.cache.CoherenceCacheHelper;
    import org.eclipse.persistence.config.SessionCustomizer;
    import org.eclipse.persistence.descriptors.ClassDescriptor;
    import org.eclipse.persistence.sessions.Session;
    public class CacheNamePrefixCustomizer implements SessionCustomizer {
       private static final String PREFIX_PROPERTY = "myapp.cache-prefix";
       public void customize(Session session) throws Exception {
          // Look up custom persistence unit cache prefix property
          String prefix = (String) session.getProperty(PREFIX_PROPERTY);
          if (prefix == null) {
             throw new RuntimeException(
                "Cache name prefix customizer configured but prefix property '" +
                PREFIX_PROPERTY + "' not specified");
          // Iterate over all entity descriptors
          Collection<ClassDescriptor> descriptors = session.getDescriptors().values();
          for (ClassDescriptor classDescriptor : descriptors) {
             // If entity is TopLink Grid-enabled, prepend cache name with prefix
             if (CoherenceInterceptor.class.equals(classDescriptor.getCacheInterceptorClass())) {
                String cacheName = CoherenceCacheHelper.getCacheName(classDescriptor);
                classDescriptor.setProperty(IntegrationProperties.COHERENCE_CACHE_NAME, prefix + cacheName);
  2. Edit the persistence.xml file to declare a value for the prefix property.

    In the following example, MyApp_ is defined as the value of the prefix property myapp.cache-prefix in the persistence.xml file. The myapp.cache-prefix prefix property is defined in the custom session customizer file.

    <property name="myapp.cache-prefix" value="MyApp_"/>

    See http://www.eclipse.org/eclipselink/ for more information on the EclipseLink SessionCustomizer class.

  3. Edit the persistence.xml file to add the name of the custom session customizer class as the value of the eclipselink.session.customizer context property.

    <property name="eclipselink.session.customizer" value="CacheNamePrefixCustomizer"/>
  4. Edit the coherence-cache-config.xml file to add the name of the prefix with a wildcard character to the cache mapping.


5.5 Overriding the Default Cache Name

There may be situations where you want to override the default name given to an entity cache. In TopLink Grid, entity cache names default to the entity name. The following list describes how the name of the cache can be determined, and how you can change it explicitly:

Cache Name—the cache name can be set either by default, or set explicitly:

  • Default: cache name defaults to entity name. The entity name, in turn can be set either by default, or set explicitly:

    • Default: Entity name defaults to class short name.

    • Explicit: Entity name can be set explicitly by using the name property of the @Entity annotation.

  • Explicit: the cache name can be set explicitly by using the @Property annotation.

For example, the following code fragment illustrates the Employee class. By default, the entity cache name would be Employee. However, you can force the name of the Employee entity cache to be EMP_CACHE by using the @Property annotation.

import static oracle.eclipselink.coherence.IntegrationProperties.COHERENCE_CACHE_NAME;
import org.eclipse.persistence.annotations.Property;
    @Property(name=COHERENCE_CACHE_NAME, value="EMP_CACHE")
    public class Employee implements Serializable {

Notice that the code explicitly specifies the entity name as Emp. If the name="Emp" value were not present, then the entity name would have defaulted to the short class name Employee.