Dealing with multiple persistence units - Documentation Corrections [SPR-6781]

[spring-projects-issues]

Rob Winch opened SPR-6781 and commented

I have a few corrections for the "Dealing with multiple persistence units" example provided in the spring documentation (http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/orm.html#orm-jpa-multiple-pu).

First, the bean of type DefaultPersistenceUnitManager should change the property name persistenceXmlLocation to persistenceXmlLocations to avoid the error below.

Caused by: java.lang.IllegalStateException: Cannot convert value of type [java.util.ArrayList] to required type [java.lang.String] for property 'persistenceXmlLocation': no matching editors or conversion strategy found
at org.springframework.beans.TypeConverterDelegate.convertIfNecessary(TypeConverterDelegate.java:289)
at org.springframework.beans.TypeConverterDelegate.convertIfNecessary(TypeConverterDelegate.java:154)
at org.springframework.beans.BeanWrapperImpl.convertForProperty(BeanWrapperImpl.java:452)
... 40 more

Second, LocalContainerEntityManagerFactoryBean should specify the property persistenceUnitName to avoid the following exception from being thrown:

Caused by: java.lang.IllegalStateException: No single default persistence unit defined in {org/springframework/orm/jpa/domain/persistence-multi.xml, classpath:/my/package/**/custom-persistence.xml, classpath*:META-INF/persistence.xml}
at org.springframework.orm.jpa.persistenceunit.DefaultPersistenceUnitManager.obtainDefaultPersistenceUnitInfo(DefaultPersistenceUnitManager.java:367)
at org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean.determinePersistenceUnitInfo(LocalContainerEntityManagerFactoryBean.java:247)
at org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean.createNativeEntityManagerFactory(LocalContainerEntityManagerFactoryBean.java:196)
at org.springframework.orm.jpa.AbstractEntityManagerFactoryBean.afterPropertiesSet(AbstractEntityManagerFactoryBean.java:288)
at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.invokeInitMethods(AbstractAutowireCapableBeanFactory.java:1460)
at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.initializeBean(AbstractAutowireCapableBeanFactory.java:1398)
... 37 more

Last, the second correction leads me to ask how do I appropriately deal with the other persistence unit names? Do I have to create a new instance of LocalContainerEntityManagerFactoryBean for each persistence unit (hope not)?

---

Affects: 2.5.6, 3.0 GA

Referenced from: commits 2d6ea2f

[spring-projects-issues]

Juergen Hoeller commented

I'm afraid you do have to create a new instance of LocalContainerEntityManagerFactoryBean for each persistence unit - since JPA maps exactly one persistence unit onto exactly one EntityManagerFactory.

We could potentially provide a more convenient way to set up several persistence units. However, since the number of units is usually very low, it wasn't much of an issue up to now...

Juergen

[spring-projects-issues]

Rob Winch commented

Thanks for the quick turnaround. I believe I could have been more clear on my last point. It appears this section is intended to demonstrate how to deal with multiple persistence units. With the modifications I suggested, the example only demonstrates how to use one persistence unit. In addition to the changes that were made, I think it would be helpful for the documentation to:

1. state that there will need to be a new instance of the LocalContainerEntityManagerFactoryBean per persistence unit (as you mentioned in the bug comment)

2. update the example to have a second instance of LocalContainerEntityManagerFactoryBean defined

[spring-projects-issues]

jean commented

??We could potentially provide a more convenient way to set up several persistence units. However, since the number of units is usually very low, it wasn't much of an issue up to now...??

Actually yes! That'd be very nice and useful. I feel it is not such an uncommon pattern in the enterprise world.
For now I guess the way to go is http://dev.c-ware.de/confluence/display/PUBLIC/Multiple+persistence.xml+in+a+multi-module+application

Jean

[spring-projects-issues]

jean commented

Sorry, MergingPersistenceUnitManager from the link is never going to work as it is since MutablePersistenceUnitInfo doesn't implement PersistentUnitInfo.getValidationMode(). http://jira.springframework.org/browse/SPR-6408

[spring-projects-issues]

Derrick commented

I wish to second jean's comment, that having more than one persistence unit is not an uncommon use case. It is certainly not impossible, but more difficult than it should be. Also note that the example here doesn't really do full justice to the use case. Why is only one entityManagerFactoryBean mentioned in the example, when there are two of everything else?

[mauromol]

@jhoeller doesn't this still apply?
In the documentation at (for Spring Framework 7.0.3 at the time of writing):
https://docs.spring.io/spring-framework/reference/data-access/orm/jpa.html#orm-jpa-setup-multiple
it's defining just a single LocalContainerEntityManagerFactoryBean, not multiple ones.
Additionally, LocalContainerEntityManagerFactoryBean#setPersistenceUnitName(String) javadoc says:

Uses the specified persistence unit name as the name of the default persistence unit, if applicable.
NOTE: Only applied if no external PersistenceUnitManager specified.

To my understanding, instead, this is wrong. It's the persistence unit name that this factory should create an entity manager factory for, and it perfectly applies also to the case in which you do have a persistence unit manager. Looking at the source, it seems like, in case it's not specified, the returned entity manager factory will use the persistence unit manager default persistence unit name, that doesn't mean that it's not applied if a persistence unit manager is specified.

[jhoeller]

@mauromol good point, that javadoc note only applies to the additional behavior in the overridden setPersistenceUnitName method. It needs to reflect the original behavior inherited from the superclass as well, which is indeed the selection semantics.

I've derived #36205 for fixing this in 7.0.4 and 6.2.16.