Seam Framework - Document History How do I use an alternate JPA provider?

Although the Seam development team encourages you to use Hibernate as the JPA provider, Seam is capable of working with any JPA provider. Hibernate is recommended is because it provides several "vendor extensions" that Seam is able to leverage to your advantage. However, if you are willing to pass on these enhancements (most notably manual flushing and Hibernate Search), then you should have no problem swapping out Hibernate for another provider.

Although the Seam development team encourages you to use Hibernate as the JPA provider, Seam is capable of working with any JPA provider. Hibernate is recommended for a good reason. It provides several "vendor extensions" that Seam is able to leverage to your advantage. If you are willing to pass on these enhancements (most notably manual flushing and Hibernate Search), then you should have no problem swapping out Hibernate for another provider.

From line 4 changed to line 4:

There are four steps you have to take to change the JPA persistence provider. The first three are straightforward and the last step will keep you from getting exceptions.

There are three steps to changing the JPA persistence provider in a Seam application:

From lines 6 to 7 changed to lines 6 to 7:

# Make sure JPA provider is deployed to the application server (the JARs are available on the classpath)
# Define the SPI class in persistence.xml

# Make sure the JPA provider is deployed to the application server (the JARs are available on the classpath)
# Declare the SPI class in persistence.xml

From line 9 deleted to line 9:

# Check your code for uses of Hibernate-specific extensions

From line 11 changed to line 10:

The first step is usually just deciding to use the JPA provider that comes with the application server. For instance, if you are using GlassFish V2, TopLink Essentials is the bundled provider.

After you have the JPA provider configured, you should check your code for uses of Hibernate-specific extensions. This will keep you from bumping into exceptions.

From line 13 changed to line 12:

The second step is how you tell JPA which provider you want to use. You enter the SPI class that extends the |javax.persistence.spi.PersistenceProvider| interface in the |<provider>| element of the persistence unit in the persistence unit descriptor (persistence.xml).

++++ Step 1: Preparing an alternate provider

From line 15 added to lines 14 to 19:

The first step is usually just deciding to use the JPA provider that comes with the application server. For instance, if you are using GlassFish V2, TopLink Essentials is the bundled provider. Otherwise, you have to add the JAR files to the application server's extension directory. You had to do this same step if you have ever used Hibernate on GlassFish.

++++ Step 2: Attaching the persistence unit to the provider

The second step is how you tell JPA which provider you want to use. You enter the SPI class that extends the |javax.persistence.spi.PersistenceProvider| interface in the |<provider>| element under |<persistence-unit>| in the persistence unit descriptor (persistence.xml).

From line 25 changed to line 30:

If there is only one provider on the classpath, JPA will automatically detect the class and use it. It's when you have more than one JPA provider on the classpath that you have to be explicit.

If there is only one provider on the classpath, JPA will automatically detect it and use it. It's when you have more than one JPA provider on the classpath that you have to be explicit.

From line 27 changed to line 32:

You may need to specify other settings in persistence.xml that are specific to the provider, just like Hibernate has its own set of properties. For instance, with TopLink, you need to add a property that sets the [target database=>http://www.oracle.com/technology/products/ias/toplink/JPA/essentials/toplink-jpa-extensions.html#CJAEBIJC]:

From line 31 changed to line 36:

I also find that when I am using an exploded archive, I have to tell TopLink not to exclude unlisted classes, but adding the following element above the |<properties>| element:

I also find that when I am using an exploded archive, I have to tell TopLink not to exclude unlisted classes. That's done by adding the following element above the |<properties>| element:

From line 35 changed to line 40:

Your milage may vary. I'll admit that depending on your packaging, getting the persistence unit setup right can be hairy. This has nothing to do with Seam.

Your mileage may vary. I'll admit that depending on your packaging, getting the persistence unit setup right can be hairy. This has nothing to do with Seam.

From line 37 changed to line 42:

The final step to configuring the application is to give Seam the hint as to which persistence provider manager component to use. You define the generic JPA persistence provider in the Seam component descriptor (components.xml).

++++ Step 3: Breaking the news to Seam that you won't be using Hibernate

From line 39 added to lines 44 to 45:

The third and final step to configuring the application is to give Seam the hint as to which persistence provider manager component to use. That's how Seam keeps straight which JPA providers support which features. For any non-Hibernate JPA provider, you define the generic JPA persistence provider in the Seam component descriptor (components.xml).

From line 53 changed to line 60:

However, you will run into problems if you are using Seam \< 2.1.2. In older versions, Seam throws an exception when it attempts to switch the persistence contexts to manual flush mode prior rendering ([JBSEAM-3030=>jbseam://3030]) because that flush mode only available in Hibernate. In this case, you need to instead add the following component to your application to suppress this exception:

However, you will run into problems if you are using Seam \< 2.1.2. In older versions, Seam would throw an exception when it attempted to switch the persistence contexts to manual flush mode prior to rendering ([JBSEAM-3030=>jbseam://3030]), a flush mode that is only available in Hibernate. This has now been fixed. Until you have a chance to upgrade, you need to instead add the following component to your application to suppress this exception:

From line 70 changed to line 77:

You should now be able to start your Seam application using the alternate JPA provider. The last step is to make sure you reset your expectations.

You should now be able to start your Seam application using the alternate JPA provider! The last step is to make sure you reset your expectations.

From line 74 changed to line 81:

First and foremost, manual flushing will not be available. Therefore, when using a long-running conversation, you are likely to get flushing of the persistence context after each request. The reason for this is that Seam uses a wrapper (global) transaction around each non-faces request and two transactions for each faces request. Since a JPA provider auto and commit flush mode will flush prior to the transaction committing, you are guaranteed it will happen on each request. You can choose to disable Seam's wrapper transactions by configuring the |<core:init>| component in the Seam component descriptor:

First and foremost, without Hibernate, manual flushing will not be available. Therefore, when using a long-running conversation, you are likely to get flushing of the persistence context after each request. The reason for this is that Seam uses a wrapper (global) transaction around each non-faces request and two transactions for each faces request. Since a JPA provider will flush prior to the transaction committing, you are guaranteed the flush will happen on every request. You can choose to disable Seam's wrapper transactions by configuring the |<core:init>| component in the Seam component descriptor as follows:

From line 82 changed to line 89:

There you have it, Seam with an alternate JPA provider! It's certainly possible thanks to Seam's commitment to support the Java EE standards.

There you have it, Seam with an alternate JPA provider!