org.springframework.orm.jpa
Class LocalContainerEntityManagerFactoryBean

java.lang.Object
  extended by org.springframework.orm.jpa.AbstractEntityManagerFactoryBean
      extended by org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean
All Implemented Interfaces:
Serializable, Aware, BeanClassLoaderAware, BeanFactoryAware, BeanNameAware, DisposableBean, FactoryBean<EntityManagerFactory>, InitializingBean, ResourceLoaderAware, LoadTimeWeaverAware, PersistenceExceptionTranslator, EntityManagerFactoryInfo

public class LocalContainerEntityManagerFactoryBean
extends AbstractEntityManagerFactoryBean
implements ResourceLoaderAware, LoadTimeWeaverAware

FactoryBean that creates a JPA EntityManagerFactory according to JPA's standard container bootstrap contract. This is the most powerful way to set up a shared JPA EntityManagerFactory in a Spring application context; the EntityManagerFactory can then be passed to JPA-based DAOs via dependency injection. Note that switching to a JNDI lookup or to a LocalEntityManagerFactoryBean definition is just a matter of configuration!

As with LocalEntityManagerFactoryBean, configuration settings are usually read in from a META-INF/persistence.xml config file, residing in the class path, according to the general JPA configuration contract. However, this FactoryBean is more flexible in that you can override the location of the persistence.xml file, specify the JDBC DataSources to link to, etc. Furthermore, it allows for pluggable class instrumentation through Spring's LoadTimeWeaver abstraction, instead of being tied to a special VM agent specified on JVM startup.

Internally, this FactoryBean parses the persistence.xml file itself and creates a corresponding PersistenceUnitInfo object (with further configuration merged in, such as JDBC DataSources and the Spring LoadTimeWeaver), to be passed to the chosen JPA PersistenceProvider. This corresponds to a local JPA container with full support for the standard JPA container contract.

The exposed EntityManagerFactory object will implement all the interfaces of the underlying native EntityManagerFactory returned by the PersistenceProvider, plus the EntityManagerFactoryInfo interface which exposes additional metadata as assembled by this FactoryBean.

Since:
2.0
Author:
Juergen Hoeller, Rod Johnson
See Also:
setPersistenceXmlLocation(java.lang.String), AbstractEntityManagerFactoryBean.setJpaProperties(java.util.Properties), AbstractEntityManagerFactoryBean.setJpaVendorAdapter(org.springframework.orm.jpa.JpaVendorAdapter), setLoadTimeWeaver(org.springframework.instrument.classloading.LoadTimeWeaver), setDataSource(javax.sql.DataSource), EntityManagerFactoryInfo, LocalEntityManagerFactoryBean, SharedEntityManagerBean, PersistenceProvider.createContainerEntityManagerFactory(javax.persistence.spi.PersistenceUnitInfo, java.util.Map), Serialized Form

Field Summary
 
Fields inherited from class org.springframework.orm.jpa.AbstractEntityManagerFactoryBean
logger, nativeEntityManagerFactory
 
Constructor Summary
LocalContainerEntityManagerFactoryBean()
           
 
Method Summary
protected  EntityManagerFactory createNativeEntityManagerFactory()
          Subclasses must implement this method to create the EntityManagerFactory that will be returned by the getObject() method.
protected  PersistenceUnitInfo determinePersistenceUnitInfo(PersistenceUnitManager persistenceUnitManager)
          Determine the PersistenceUnitInfo to use for the EntityManagerFactory created by this bean.
 DataSource getDataSource()
          Return the JDBC DataSource that this EntityManagerFactory obtains its JDBC Connections from.
 PersistenceUnitInfo getPersistenceUnitInfo()
          Return the PersistenceUnitInfo used to create this EntityManagerFactory, if the in-container API was used.
 String getPersistenceUnitName()
          Return the name of the persistence unit used to create this EntityManagerFactory, or null if it is an unnamed default.
protected  void postProcessEntityManagerFactory(EntityManagerFactory emf, PersistenceUnitInfo pui)
          Hook method allowing subclasses to customize the EntityManagerFactory after its creation via the PersistenceProvider.
 void setDataSource(DataSource dataSource)
          Specify the JDBC DataSource that the JPA persistence provider is supposed to use for accessing the database.
 void setLoadTimeWeaver(LoadTimeWeaver loadTimeWeaver)
          Specify the Spring LoadTimeWeaver to use for class instrumentation according to the JPA class transformer contract.
 void setMappingResources(String... mappingResources)
          Specify one or more mapping resources (equivalent to <mapping-file> entries in persistence.xml) for the default persistence unit.
 void setPackagesToScan(String... packagesToScan)
          Set whether to use Spring-based scanning for entity classes in the classpath instead of using JPA's standard scanning of jar files with persistence.xml markers in them.
 void setPersistenceUnitManager(PersistenceUnitManager persistenceUnitManager)
          Set the PersistenceUnitManager to use for obtaining the JPA persistence unit that this FactoryBean is supposed to build an EntityManagerFactory for.
 void setPersistenceUnitName(String persistenceUnitName)
          Uses the specified persistence unit name as the name of the default persistence unit, if applicable.
 void setPersistenceUnitPostProcessors(PersistenceUnitPostProcessor... postProcessors)
          Set the PersistenceUnitPostProcessors to be applied to the PersistenceUnitInfo used for creating this EntityManagerFactory.
 void setPersistenceXmlLocation(String persistenceXmlLocation)
          Set the location of the persistence.xml file we want to use.
 void setResourceLoader(ResourceLoader resourceLoader)
          Set the ResourceLoader that this object runs in.
 
Methods inherited from class org.springframework.orm.jpa.AbstractEntityManagerFactoryBean
afterPropertiesSet, createEntityManagerFactoryProxy, destroy, getBeanClassLoader, getEntityManagerInterface, getJpaDialect, getJpaPropertyMap, getJpaVendorAdapter, getNativeEntityManagerFactory, getObject, getObjectType, getPersistenceProvider, isSingleton, setBeanClassLoader, setBeanFactory, setBeanName, setEntityManagerFactoryInterface, setEntityManagerInterface, setJpaDialect, setJpaProperties, setJpaPropertyMap, setJpaVendorAdapter, setPersistenceProvider, setPersistenceProviderClass, translateExceptionIfPossible, writeReplace
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

LocalContainerEntityManagerFactoryBean

public LocalContainerEntityManagerFactoryBean()
Method Detail

setPersistenceUnitManager

public void setPersistenceUnitManager(PersistenceUnitManager persistenceUnitManager)
Set the PersistenceUnitManager to use for obtaining the JPA persistence unit that this FactoryBean is supposed to build an EntityManagerFactory for.

The default is to rely on the local settings specified on this FactoryBean, such as "persistenceXmlLocation", "dataSource" and "loadTimeWeaver".

For reuse of existing persistence unit configuration or more advanced forms of custom persistence unit handling, consider defining a separate PersistenceUnitManager bean (typically a DefaultPersistenceUnitManager instance) and linking it in here. persistence.xml location, DataSource configuration and LoadTimeWeaver will be defined on that separate DefaultPersistenceUnitManager bean in such a scenario.

See Also:
setPersistenceXmlLocation(java.lang.String), setDataSource(javax.sql.DataSource), setLoadTimeWeaver(org.springframework.instrument.classloading.LoadTimeWeaver), DefaultPersistenceUnitManager

setPersistenceXmlLocation

public void setPersistenceXmlLocation(String persistenceXmlLocation)
Set the location of the persistence.xml file we want to use. This is a Spring resource location.

Default is "classpath:META-INF/persistence.xml".

NOTE: Only applied if no external PersistenceUnitManager specified.

Parameters:
persistenceXmlLocation - a Spring resource String identifying the location of the persistence.xml file that this LocalContainerEntityManagerFactoryBean should parse
See Also:
setPersistenceUnitManager(org.springframework.orm.jpa.persistenceunit.PersistenceUnitManager)

setPersistenceUnitName

public void setPersistenceUnitName(String persistenceUnitName)
Uses the specified persistence unit name as the name of the default persistence unit, if applicable.

NOTE: Only applied if no external PersistenceUnitManager specified.

Overrides:
setPersistenceUnitName in class AbstractEntityManagerFactoryBean
See Also:
Persistence.createEntityManagerFactory(String)

setPackagesToScan

public void setPackagesToScan(String... packagesToScan)
Set whether to use Spring-based scanning for entity classes in the classpath instead of using JPA's standard scanning of jar files with persistence.xml markers in them. In case of Spring-based scanning, no persistence.xml is necessary; all you need to do is to specify base packages to search here.

Default is none. Specify packages to search for autodetection of your entity classes in the classpath. This is analogous to Spring's component-scan feature (ClassPathBeanDefinitionScanner).

NOTE: Only applied if no external PersistenceUnitManager specified.

Parameters:
packagesToScan - one or more base packages to search, analogous to Spring's component-scan configuration for regular Spring components
See Also:
setPersistenceUnitManager(org.springframework.orm.jpa.persistenceunit.PersistenceUnitManager)

setMappingResources

public void setMappingResources(String... mappingResources)
Specify one or more mapping resources (equivalent to <mapping-file> entries in persistence.xml) for the default persistence unit. Can be used on its own or in combination with entity scanning in the classpath, in both cases avoiding persistence.xml.

Note that mapping resources must be relative to the classpath root, e.g. "META-INF/mappings.xml" or "com/mycompany/repository/mappings.xml", so that they can be loaded through ClassLoader.getResource.

NOTE: Only applied if no external PersistenceUnitManager specified.

See Also:
setPersistenceUnitManager(org.springframework.orm.jpa.persistenceunit.PersistenceUnitManager)

setDataSource

public void setDataSource(DataSource dataSource)
Specify the JDBC DataSource that the JPA persistence provider is supposed to use for accessing the database. This is an alternative to keeping the JDBC configuration in persistence.xml, passing in a Spring-managed DataSource instead.

In JPA speak, a DataSource passed in here will be used as "nonJtaDataSource" on the PersistenceUnitInfo passed to the PersistenceProvider, overriding data source configuration in persistence.xml (if any).

NOTE: Only applied if no external PersistenceUnitManager specified.

See Also:
PersistenceUnitInfo.getNonJtaDataSource(), setPersistenceUnitManager(org.springframework.orm.jpa.persistenceunit.PersistenceUnitManager)

setPersistenceUnitPostProcessors

public void setPersistenceUnitPostProcessors(PersistenceUnitPostProcessor... postProcessors)
Set the PersistenceUnitPostProcessors to be applied to the PersistenceUnitInfo used for creating this EntityManagerFactory.

Such post-processors can, for example, register further entity classes and jar files, in addition to the metadata read in from persistence.xml.

NOTE: Only applied if no external PersistenceUnitManager specified.

See Also:
setPersistenceUnitManager(org.springframework.orm.jpa.persistenceunit.PersistenceUnitManager)

setLoadTimeWeaver

public void setLoadTimeWeaver(LoadTimeWeaver loadTimeWeaver)
Specify the Spring LoadTimeWeaver to use for class instrumentation according to the JPA class transformer contract.

It is a not required to specify a LoadTimeWeaver: Most providers will be able to provide a subset of their functionality without class instrumentation as well, or operate with their VM agent specified on JVM startup.

In terms of Spring-provided weaving options, the most important ones are InstrumentationLoadTimeWeaver, which requires a Spring-specific (but very general) VM agent specified on JVM startup, and ReflectiveLoadTimeWeaver, which interacts with an underlying ClassLoader based on specific extended methods being available on it (for example, interacting with Spring's TomcatInstrumentableClassLoader).

NOTE: As of Spring 2.5, the context's default LoadTimeWeaver (defined as bean with name "loadTimeWeaver") will be picked up automatically, if available, removing the need for LoadTimeWeaver configuration on each affected target bean. Consider using the context:load-time-weaver XML tag for creating such a shared LoadTimeWeaver (autodetecting the environment by default).

NOTE: Only applied if no external PersistenceUnitManager specified. Otherwise, the external PersistenceUnitManager is responsible for the weaving configuration.

Specified by:
setLoadTimeWeaver in interface LoadTimeWeaverAware
Parameters:
loadTimeWeaver - the LoadTimeWeaver instance (never null)
See Also:
InstrumentationLoadTimeWeaver, ReflectiveLoadTimeWeaver, TomcatInstrumentableClassLoader

setResourceLoader

public void setResourceLoader(ResourceLoader resourceLoader)
Description copied from interface: ResourceLoaderAware
Set the ResourceLoader that this object runs in.

This might be a ResourcePatternResolver, which can be checked through instanceof ResourcePatternResolver. See also the ResourcePatternUtils.getResourcePatternResolver method.

Invoked after population of normal bean properties but before an init callback like InitializingBean's afterPropertiesSet or a custom init-method. Invoked before ApplicationContextAware's setApplicationContext.

Specified by:
setResourceLoader in interface ResourceLoaderAware
Parameters:
resourceLoader - ResourceLoader object to be used by this object
See Also:
ResourcePatternResolver, ResourcePatternUtils.getResourcePatternResolver(org.springframework.core.io.ResourceLoader)

createNativeEntityManagerFactory

protected EntityManagerFactory createNativeEntityManagerFactory()
                                                         throws PersistenceException
Description copied from class: AbstractEntityManagerFactoryBean
Subclasses must implement this method to create the EntityManagerFactory that will be returned by the getObject() method.

Specified by:
createNativeEntityManagerFactory in class AbstractEntityManagerFactoryBean
Returns:
EntityManagerFactory instance returned by this FactoryBean
Throws:
PersistenceException - if the EntityManager cannot be created

determinePersistenceUnitInfo

protected PersistenceUnitInfo determinePersistenceUnitInfo(PersistenceUnitManager persistenceUnitManager)
Determine the PersistenceUnitInfo to use for the EntityManagerFactory created by this bean.

The default implementation reads in all persistence unit infos from persistence.xml, as defined in the JPA specification. If no entity manager name was specified, it takes the first info in the array as returned by the reader. Otherwise, it checks for a matching name.

Parameters:
persistenceUnitManager - the PersistenceUnitManager to obtain from
Returns:
the chosen PersistenceUnitInfo

postProcessEntityManagerFactory

protected void postProcessEntityManagerFactory(EntityManagerFactory emf,
                                               PersistenceUnitInfo pui)
Hook method allowing subclasses to customize the EntityManagerFactory after its creation via the PersistenceProvider.

The default implementation is empty.

Parameters:
emf - the newly created EntityManagerFactory we are working with
pui - the PersistenceUnitInfo used to configure the EntityManagerFactory
See Also:
PersistenceProvider.createContainerEntityManagerFactory(javax.persistence.spi.PersistenceUnitInfo, java.util.Map)

getPersistenceUnitInfo

public PersistenceUnitInfo getPersistenceUnitInfo()
Description copied from interface: EntityManagerFactoryInfo
Return the PersistenceUnitInfo used to create this EntityManagerFactory, if the in-container API was used.

Specified by:
getPersistenceUnitInfo in interface EntityManagerFactoryInfo
Overrides:
getPersistenceUnitInfo in class AbstractEntityManagerFactoryBean
Returns:
the PersistenceUnitInfo used to create this EntityManagerFactory, or null if the in-container contract was not used to configure the EntityManagerFactory

getPersistenceUnitName

public String getPersistenceUnitName()
Description copied from interface: EntityManagerFactoryInfo
Return the name of the persistence unit used to create this EntityManagerFactory, or null if it is an unnamed default.

If getPersistenceUnitInfo() returns non-null, the result of getPersistenceUnitName() must be equal to the value returned by PersistenceUnitInfo.getPersistenceUnitName().

Specified by:
getPersistenceUnitName in interface EntityManagerFactoryInfo
Overrides:
getPersistenceUnitName in class AbstractEntityManagerFactoryBean
See Also:
EntityManagerFactoryInfo.getPersistenceUnitInfo(), PersistenceUnitInfo.getPersistenceUnitName()

getDataSource

public DataSource getDataSource()
Description copied from interface: EntityManagerFactoryInfo
Return the JDBC DataSource that this EntityManagerFactory obtains its JDBC Connections from.

Specified by:
getDataSource in interface EntityManagerFactoryInfo
Overrides:
getDataSource in class AbstractEntityManagerFactoryBean
Returns:
the JDBC DataSource, or null if not known