This chapter contains the following sections:
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.
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
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.
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
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
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
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
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
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
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> ...