Package org.springframework.orm.jpa

# Class LocalContainerEntityManagerFactoryBean

java.lang.Object
org.springframework.orm.jpa.AbstractEntityManagerFactoryBean
org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean

All Implemented Interfaces:
  `Serializable`, `org.springframework.beans.factory.Aware`, `org.springframework.beans.factory.BeanClassLoaderAware`, `org.springframework.beans.factory.BeanFactoryAware`, `org.springframework.beans.factory.BeanNameAware`, `org.springframework.beans.factory.DisposableBean`, `org.springframework.beans.factory.FactoryBean<EntityManagerFactory>`, `org.springframework.beans.factory.InitializingBean`, `org.springframework.beans.factory.SmartInitializingSingleton`, `org.springframework.context.ResourceLoaderAware`, `org.springframework.context.weaving.LoadTimeWeaverAware`, `org.springframework.dao.support.PersistenceExceptionTranslator`, `EntityManagerFactoryInfo`

public class LocalContainerEntityManagerFactoryBean extends AbstractEntityManagerFactoryBean implements org.springframework.context.ResourceLoaderAware, org.springframework.context.weaving.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(jakarta.persistence.spi.PersistenceUnitInfo, java.util.Map)`
  - Serialized Form

## Field Summary

### Fields inherited from class org.springframework.orm.jpa.AbstractEntityManagerFactoryBean

`logger`

### Fields inherited from interface org.springframework.beans.factory.FactoryBean

`OBJECT_TYPE_ATTRIBUTE`

## Constructor Summary

Constructors
Constructor
Description
`LocalContainerEntityManagerFactoryBean()`

## Method Summary

Modifier and Type
Method
Description
`void`
`afterPropertiesSet()`
`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`
`setJtaDataSource(DataSource jtaDataSource)`
Specify the JDBC DataSource that the JPA persistence provider is supposed to use for accessing the database.
`void`
`setLoadTimeWeaver(org.springframework.instrument.classloading.LoadTimeWeaver loadTimeWeaver)`
Specify the Spring LoadTimeWeaver to use for class instrumentation according to the JPA class transformer contract.
`void`
`setManagedClassNameFilter(ManagedClassNameFilter managedClassNameFilter)`
Set the `ManagedClassNameFilter` to apply on entity classes discovered using classpath scanning.
`void`
`setManagedTypes(PersistenceManagedTypes managedTypes)`
Set the `PersistenceManagedTypes` to use to build the list of managed types as an alternative to entity scanning.
`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`
`setPersistenceUnitRootLocation(String defaultPersistenceUnitRootLocation)`
Set a persistence unit root location for the default persistence unit.
`void`
`setPersistenceXmlLocation(String persistenceXmlLocation)`
Set the location of the `persistence.xml` file we want to use.
`void`
`setResourceLoader(org.springframework.core.io.ResourceLoader resourceLoader)`
`void`
`setSharedCacheMode(SharedCacheMode sharedCacheMode)`
Specify the JPA 2.0 shared cache mode for this persistence unit, overriding a value in `persistence.xml` if set.
`void`
`setValidationMode(ValidationMode validationMode)`
Specify the JPA 2.0 validation mode for this persistence unit, overriding a value in `persistence.xml` if set.

### Methods inherited from class org.springframework.orm.jpa.AbstractEntityManagerFactoryBean

`afterSingletonsInstantiated, createEntityManagerFactoryProxy, createNativeEntityManager, destroy, getBeanClassLoader, getBootstrapExecutor, getEntityManagerInterface, getJpaDialect, getJpaPropertyMap, getJpaVendorAdapter, getNativeEntityManagerFactory, getObject, getObjectType, getPersistenceProvider, isSingleton, postProcessEntityManager, setBeanClassLoader, setBeanFactory, setBeanName, setBootstrapExecutor, setEntityManagerFactoryInterface, setEntityManagerInitializer, 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 Details

### LocalContainerEntityManagerFactoryBean

public LocalContainerEntityManagerFactoryBean()

## Method Details

### 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(@Nullable 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:
  - `DefaultPersistenceUnitManager.setDefaultPersistenceUnitName(java.lang.String)`

### setPersistenceUnitRootLocation

public void setPersistenceUnitRootLocation(String defaultPersistenceUnitRootLocation)
Set a persistence unit root location for the default persistence unit.

Default is "classpath:", that is, the root of the current classpath (nearest root directory). To be overridden if unit-specific resolution does not work and the classpath root is not appropriate either.

NOTE: Only applied if no external PersistenceUnitManager specified.

Since:
  4.3.3
See Also:
  - `DefaultPersistenceUnitManager.setDefaultPersistenceUnitRootLocation(java.lang.String)`

### setManagedTypes

public void setManagedTypes(PersistenceManagedTypes managedTypes)
Set the `PersistenceManagedTypes` to use to build the list of managed types as an alternative to entity scanning.

Parameters:
  `managedTypes` - the managed types
Since:
  6.0
See Also:
  - `DefaultPersistenceUnitManager.setManagedTypes(PersistenceManagedTypes)`

### 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`).

Consider setting a `PersistenceManagedTypes` instead that allows the scanning logic to be optimized by AOT processing.

Note: There may be limitations in comparison to regular JPA scanning. In particular, JPA providers may pick up annotated packages for provider-specific annotations only when driven by `persistence.xml`. As of 4.1, Spring's scan can detect annotated packages as well if supported by the given `JpaVendorAdapter` (for example, for Hibernate).

If no explicit `mapping resources` have been specified in addition to these packages, Spring's setup looks for a default `META-INF/orm.xml` file in the classpath, registering it as a mapping resource for the default unit if the mapping file is not co-located with a `persistence.xml` file (in which case we assume it is only meant to be used with the persistence units defined there, like in standard JPA).

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)`
  - `DefaultPersistenceUnitManager.setPackagesToScan(java.lang.String...)`

### setManagedClassNameFilter

public void setManagedClassNameFilter(ManagedClassNameFilter managedClassNameFilter)
Set the `ManagedClassNameFilter` to apply on entity classes discovered using classpath scanning.

Parameters:
  `managedClassNameFilter` - a predicate to filter entity classes
Since:
  6.1.4
See Also:
  - `DefaultPersistenceUnitManager.setManagedClassNameFilter(org.springframework.orm.jpa.persistenceunit.ManagedClassNameFilter)`

### 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, for example, "META-INF/mappings.xml" or "com/mycompany/repository/mappings.xml", so that they can be loaded through `ClassLoader.getResource`.

If no explicit mapping resources have been specified next to `packages to scan`, Spring's setup looks for a default `META-INF/orm.xml` file in the classpath, registering it as a mapping resource for the default unit if the mapping file is not co-located with a `persistence.xml` file (in which case we assume it is only meant to be used with the persistence units defined there, like in standard JPA).

Note that specifying an empty array/list here suppresses the default `META-INF/orm.xml` check. On the other hand, explicitly specifying `META-INF/orm.xml` here will register that file even if it happens to be co-located with a `persistence.xml` file.

NOTE: Only applied if no external PersistenceUnitManager specified.

See Also:
  - `setPersistenceUnitManager(org.springframework.orm.jpa.persistenceunit.PersistenceUnitManager)`
  - `DefaultPersistenceUnitManager.setMappingResources(java.lang.String...)`

### setSharedCacheMode

public void setSharedCacheMode(SharedCacheMode sharedCacheMode)
Specify the JPA 2.0 shared cache mode for this persistence unit, overriding a value in `persistence.xml` if set.

NOTE: Only applied if no external PersistenceUnitManager specified.

Since:
  4.0
See Also:
  - `PersistenceUnitInfo.getSharedCacheMode()`
  - `setPersistenceUnitManager(org.springframework.orm.jpa.persistenceunit.PersistenceUnitManager)`

### setValidationMode

public void setValidationMode(ValidationMode validationMode)
Specify the JPA 2.0 validation mode for this persistence unit, overriding a value in `persistence.xml` if set.

NOTE: Only applied if no external PersistenceUnitManager specified.

Since:
  4.0
See Also:
  - `PersistenceUnitInfo.getValidationMode()`
  - `setPersistenceUnitManager(org.springframework.orm.jpa.persistenceunit.PersistenceUnitManager)`

### setDataSource

public void setDataSource(@Nullable 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, as well as overriding data source configuration in `persistence.xml` (if any). Note that this variant typically works for JTA transaction management as well; if it does not, consider using the explicit `setJtaDataSource(javax.sql.DataSource)` instead.

NOTE: Only applied if no external PersistenceUnitManager specified.

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

### setJtaDataSource

public void setJtaDataSource(@Nullable DataSource jtaDataSource)
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 "jtaDataSource" on the PersistenceUnitInfo passed to the PersistenceProvider, as well as overriding data source configuration in `persistence.xml` (if any).

NOTE: Only applied if no external PersistenceUnitManager specified.

See Also:
  - `PersistenceUnitInfo.getJtaDataSource()`
  - `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 from `persistence.xml`.

NOTE: Only applied if no external PersistenceUnitManager specified.

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

### setLoadTimeWeaver

public void setLoadTimeWeaver(org.springframework.instrument.classloading.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.

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 `org.springframework.context.weaving.LoadTimeWeaverAware`
See Also:
  - `InstrumentationLoadTimeWeaver`
  - `ReflectiveLoadTimeWeaver`

### setResourceLoader

public void setResourceLoader(org.springframework.core.io.ResourceLoader resourceLoader)

Specified by:
  `setResourceLoader` in interface `org.springframework.context.ResourceLoaderAware`

### afterPropertiesSet

public void afterPropertiesSet() throws PersistenceException

Specified by:
  `afterPropertiesSet` in interface `org.springframework.beans.factory.InitializingBean`
Overrides:
  `afterPropertiesSet` in class `AbstractEntityManagerFactoryBean`
Throws:
  `PersistenceException`

### 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:
  the 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(jakarta.persistence.spi.PersistenceUnitInfo, java.util.Map)`

### getPersistenceUnitInfo

@Nullable 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

@Nullable 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

@Nullable 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