3 EclipseLink Native ORM Configurations

This chapter contains the following sections:

Understanding EclipseLink Native ORM
API for EclipseLink Native ORM
Configuring an Amendment Method
Configuring the EclipseLink Native ORM Cache Store and Cache Loader

3.1 Understanding EclipseLink Native ORM

EclipseLink Native Object Relational Mapping (ORM) provides an extensible object-relational mapping framework. It provides high-performance object persistence with extended capabilities configured declaratively through XML. These extended capabilities include caching (including support for clustered caching), advanced database-specific capabilities, and performance tuning and management options.

Like JPA on the Grid configurations, applications that employ EclipseLink ORM can access Coherence caches. However, unlike JPA on the grid configurations, EclipseLink ORM applications do not use the @Customizer annotation to configure how the cache is used. Instead, they typically call an amendment method that defines the appropriate cache behavior.

3.2 API for EclipseLink Native ORM

The cache store and cache loader API used in EclipseLink Native ORM configurations are shipped in the toplink-grid.jar file. Table 3-1 describes the API for EclipseLink Native ORM. These classes can be found in the oracle.eclipselink.coherence.integrated package.

Table 3-1 EclipseLink Classes for Native ORM Configurations

Class Name	Description
`EclipseLinkNativeCacheStore(String cacheName, String sessionName)`	Coherence cache store that should be used with native EclipseLink configuration (`sessions.xml`).
`EclipseLinkNativeCacheLoader(String cacheName, String sessionName)`	Coherence cache loader that should be used with native EclipseLink configuration (`sessions.xml`).
`oracle.eclipselink.coherence.integrated.config.CoherenceReadCustomizer`	Enables a Coherence read configuration.
`oracle.eclipselink.coherence.integrated.config.CoherenceReadWriteCustomizer`	Enables a Coherence read/write configuration.
`oracle.eclipselink.coherence.integrated.config.GridCacheCustomizer`	Enables entity instances to be cached in Coherence instead of in the internal EclipseLink shared cache

Note that the second initialization parameter in the signatures, sessionName, represents the name of the mapping project that must be listed in the native EclipseLink configuration file, META-INF/sessions.xml.

The EclipseLinkNativeCacheStore and EclipseLinkNativeCacheLoader classes allow applications that use EclipseLink Native ORM to access Coherence caches. Use these classes when Coherence cache behavior has been configured through an amendment method. These classes can be used to configure a cache store or cache loader for each persistent class in the same way as described in Chapter 2, "JPA on the Grid Configurations".

Use the Coherence cache configuration file coherence-cache-config.xml to define the cache store caching scheme and to override any default Coherence settings.

The configuration uses the native EclipseLink sessions.xml file and the project.xml file. The sessions.xml file, and all of the deployment XML files (which have user-defined names) listed in it, must be available on the classpath or packaged within a JAR file within the META-INF directory.

You must also configure an amendment method to define the appropriate cache behavior. See "Configuring an Amendment Method" for more information.

3.3 Configuring an Amendment Method

An amendment method is a method that uses the EclipseLink descriptor API to customize the ORM mapping metadata for a class. The method is called when the descriptor is loaded at runtime. The purpose of the amendment methods provided by TopLink Grid is to define how the Coherence cache is going to be used. Amendment methods are the TopLink native ORM alternative to the @Customizer annotation; they produce the same configuration.

The TopLink Grid customizer classes in the toplink-grid.jar file (CoherenceReadCustomizer, CoherenceReadWriteCustomizer, and GridCacheCustomizer) provide an afterLoad amendment method that can be selected to enable the appropriate Coherence cache behavior.

You can select the amendment method using either JDeveloper or EclipseLink Workbench. How to configure amendment methods in EclipseLink Workbench is beyond the scope of this document. You can find information on this topic in "Amendment and After-Load Methods" at Eclipsepedia:

http://wiki.eclipse.org/Introduction_to_Descriptors_(ELUG)#Amendment_and_After-Load_Methods

3.3.1 Configuring the Amendment Method in JDeveloper

To configure an amendment method:

In the JDeveloper Structure pane, expand the desired tlMap descriptor name.

Figure 3-1 tlMap Descriptors in the JDeveloper Structure Pane

Description of "Figure 3-1 tlMap Descriptors in the JDeveloper Structure Pane"
Right-click the desired TopLink descriptor element. Select Advanced Properties to open the Advanced Properties dialog box. Select the After Loading check box and click OK.

Figure 3-2 Advanced Properties Dialog Box

Description of "Figure 3-2 Advanced Properties Dialog Box"
In the After Load tab of the tlMap configuration window, enter the name of the class containing the afterLoad amendment method you want to use for the selected TopLink descriptor. You can also use the class browser to search for the class. Figure 3-3 illustrates the After Load tab of the tlMap configuration window.

Figure 3-3 After Load Tab for a TopLink Descriptor

Description of "Figure 3-3 After Load Tab for a TopLink Descriptor "

Figure 3-4 illustrates the class browser with the with the CoherenceReadCustomizer class selected.

Figure 3-4 Searching for the Class containing the Amendment Method

Description of "Figure 3-4 Searching for the Class containing the Amendment Method"
In the After Load tab of the tlMap configuration window, select the amendment method from the Static Method dropdown list. For the Coherence Customizer classes, this will be the afterLoad method.

Figure 3-5 Selecting the Amendment Method

Description of "Figure 3-5 Selecting the Amendment Method"

3.4 Configuring the EclipseLink Native ORM Cache Store and Cache Loader

The coherence-cache-config.xml file must specify the cache loader or cache store class and provide parameters for the cache name and session name (that is, project name). The following examples illustrate that aside from changing the class name (EclipseLinkNativeCacheStore or EclipseLinkNativeCacheLoader), you do not have to make any changes to the Coherence cache configuration depending on whether you are using the cache loader or cache store.

Example 3-1 illustrates a configuration in the coherence-cache-config.xml file for a cache that can communicate with EclipseLink Native ORM applications. The class-name element identifies the EclipseLinkNativeCacheStore class as the cache store scheme. The param-value elements specify the cache name and the session (project) name that are passed to the class.

Example 3-1 Configuration for an Integrated EclipseLinkNativeCacheStore

...
<distributed-scheme>
      <scheme-name>eclipselink-native-distributed-store</scheme-name>
      <service-name>EclipseLinkNative</service-name>
  <serializer> 
     <class-name>oracle.eclipselink.coherence.integrated.cache.WrapperSerializer</class-name> 
  </serializer>
      <backing-map-scheme>
        <read-write-backing-map-scheme>
          <internal-cache-scheme>
            <local-scheme/>
          </internal-cache-scheme>
          <!-- Define the cache scheme -->
          <cachestore-scheme>
            <class-scheme>
              <class-name>oracle.eclipselink.coherence.integrated.EclipseLinkNativeCacheStore</class-name>
              <init-params>
                <init-param>
                  <param-type>java.lang.String</param-type>
                  <param-value>{cache-name}</param-value>
                </init-param>
                <init-param>
                  <param-type>java.lang.String</param-type>
                  <param-value>coherence-native-project</param-value>
                </init-param>
              </init-params>
            </class-scheme>
          </cachestore-scheme>
        </read-write-backing-map-scheme>
      </backing-map-scheme>
      <autostart>true</autostart>
    </distributed-scheme>
...

Example 3-2 illustrates an integrated EclipseLinkNativeCacheLoader instance configuration in the coherence-cache-config.xml file. The cache name ({cache-name}) and session name (coherence-native-project) parameter values are passed to the class.

Example 3-2 Configuration for an Integrated EclipseLinkNativeCacheLoader

...
<cachestore-scheme>
   <class-scheme>
      <class-name>oracle.eclipselink.coherence.integrated.EclipseLinkNativeCacheLoader</class-name> 
      <init-params> 
         <init-param>
            <param-type>java.lang.String</param-type>
            <param-value>{cache-name}</param-value> 
         </init-param>
         <init-param>
            <param-type>java.lang.String</param-type>
            <param-value>coherence-native-project</param-value> 
         </init-param> 
      </init-params>
   </class-scheme>
</cachestore-scheme>
...