EclipseLink/Examples/JPA/Spring

Introduction

This example describes how EclipseLink can be used within a Spring Framework enabled application as the JPA provider. With EclipseLink developers have access to a fully compliant JPA implementation with extensions enabling simplified access to EclipseLink's advanced Object-Relational functionality. This how-to is intended for developers with some experience using JPA within Spring. The steps provided can be easily used with Spring's Pet Clinic sample, which is part of the Spring installation under the "samples" directory.

Step 1: Extending Spring for EclipseLink JPA

The Spring Framework provides support for plugging in any JPA provider. Through this standard mechanism you can specify the usage of EclipseLink with all of its JPA extensions for use within your Spring enabled application. This is accomplished through the use of a JPA Vendor and a JPA Dialect. Within Spring 2.0 and higher you will find implementations of these for use with TopLink Essentials.

EclipseLinkJpaDialect is derived from the TopLinkJpaDialect shipped in the Spring Framework 2.0.4. Customized for EclipseLink package names.

EclipseLinkJpaVendorAdapter is derived from TopLinkJpaVendorAdapter

The spring.jar must be configured on your classpath along with the necessary Spring libraries (including the ASM jar).

If you already have a Spring application using TopLink Essentials (or Oracle TopLink) as the JPA provider and are using only the JPA annotations, XML, and TopLink Essentials' JPA Extensions you can switch to EclipseLink simply by including these additional classes and making the necessary changes to your application context XML.

Step 2: Modify your Spring Application Context XML

The Spring application context XML used by the application must be slightly modified to make use of the new JPA vendor adapter provided.

<bean id="jpaAdapter" class="org.springframework.orm.jpa.vendor.EclipseLinkJpaVendorAdapter">
   <property name="databasePlatform" value="org.eclipse.persistence.platform.database.OraclePlatform" />
   <property name="showSql" value="true" />
</bean>

As you can see the only changes required are to specify the new JPA adapter class and to use the EclipseLink package names for the database platform configuration.

Common Issues

Some common issues that you may encounter when using EclipseLink JPA in Spring:

• Weaving will not occur on classes in org.eclipse.persistence or oracle packages (fixed in EclipseLink 2.0)
• Spring does not work with <exclude-unlisted-classes>false</exclude-unlisted-classes> in the persistence.xml, it will interpret it as true, for false just omit the tag.
• Additional jar files added in the persistence.xml using <jar> require the directory that they are contained in to also be on the classpath.
• Spring forces the database transaction to begin with the JPA transaction, this will cause objects read in a transaction to not be cached in EclipseLink's shared cache.
  • There is a setLazyDatabaseTransaction() option in the EclipseLinkJpaDialect that resolves this.
  • See Spring bug#7753, EclipseLink bug#288383
• Spring's agent does not initialize the persistence context until the application accesses the Spring context. If the application has already triggered the loading of the persistent class before accessing the Spring context, weaving will not occur.

Configuring Eclipse to compile the eclipselink.jpa.spring.test SVN test project

• The following classpath variables need to be defined in your workspace in order to test Spring 2.5.6 from our SVN repository.
  • SPRING_AGENT_LIB
    • C:/opt/spring-framework-2.5.6.SEC01/dist/weaving/spring-agent.jar
  • SPRING_CGLIB_LIB
    • C:/opt/spring-framework-2.5.6.SEC01/lib/cglib/cglib-nodep-2.1_3.jar
  • SPRING_COMMONS_LOGGING_LIB
    • C:/opt/spring-framework-2.5.6.SEC01/lib/jakarta-commons/commons-logging.jar
  • SPRING_JOTM_CLIENT_LIB
    • C:/opt/spring-framework-2.5.6.SEC01/lib/jotm/jotm.jar
  • SPRING_JPA_SPRING_LIB
    • /eclipselink.jpa.spring.test/jpa-spring.jar (ant generated)
  • SPRING_LIB
    • C:/opt/spring-framework-2.5.6.SEC01/dist/spring.jar
  • SPRING_TEST_LIB
    • C:/opt/spring-framework-2.5.6.SEC01/dist/modules/spring-test.jar
  • SPRING_XAPOOL_LIB
    • C:/opt/spring-framework-2.5.6.SEC01/lib/jotm/xapool.jar

Summary

As shown in this example it is quite simple to use EclipseLink as your JPA provider within Spring. The Eclipselink adapter and dialect classes have been contributed into the Spring Framework project as of Spring release 2.5.2 and EclipseLink 1.0M4.

References

• SpringSource Tool Suite and Eclipse Galileo Downloads