DefaultPersistenceUnitManager (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.orm.jpa.persistenceunit

## Class DefaultPersistenceUnitManager

- java.lang.Object
- - org.springframework.orm.jpa.persistenceunit.DefaultPersistenceUnitManager

- All Implemented Interfaces:
    Aware, InitializingBean, ResourceLoaderAware, LoadTimeWeaverAware, PersistenceUnitManager

      public class DefaultPersistenceUnitManager
      extends Object
      implements PersistenceUnitManager, ResourceLoaderAware, LoadTimeWeaverAware, InitializingBean

  Default implementation of the `PersistenceUnitManager` interface. Used as internal default by `LocalContainerEntityManagerFactoryBean`.

  Supports standard JPA scanning for `persistence.xml` files, with configurable file locations, JDBC DataSource lookup and load-time weaving.

  The default XML file location is `classpath*:META-INF/persistence.xml`, scanning for all matching files in the class path (as defined in the JPA specification). DataSource names are by default interpreted as JNDI names, and no load time weaving is available (which requires weaving to be turned off in the persistence provider).

  Since:
    2.0
  Author:
    Juergen Hoeller
  See Also:
    `setPersistenceXmlLocations(java.lang.String...)`, `setDataSourceLookup(org.springframework.jdbc.datasource.lookup.DataSourceLookup)`, `setLoadTimeWeaver(org.springframework.instrument.classloading.LoadTimeWeaver)`, `LocalContainerEntityManagerFactoryBean.setPersistenceUnitManager(org.springframework.orm.jpa.persistenceunit.PersistenceUnitManager)`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `DEFAULT_PERSISTENCE_XML_LOCATION` Default location of the `persistence.xml` file: "classpath*:META-INF/persistence.xml".
    `static String` | `ORIGINAL_DEFAULT_PERSISTENCE_UNIT_NAME`
    `static String` | `ORIGINAL_DEFAULT_PERSISTENCE_UNIT_ROOT_LOCATION` Default location for the persistence unit root URL: "classpath:", indicating the root of the class path.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DefaultPersistenceUnitManager()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `afterPropertiesSet()` Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).
    `DataSourceLookup` | `getDataSourceLookup()` Return the JDBC DataSourceLookup that provides DataSources for the persistence provider, resolving data source names in `persistence.xml` against Spring-managed DataSource instances.
    `DataSource` | `getDefaultDataSource()` Return the JDBC DataSource that the JPA persistence provider is supposed to use for accessing the database if none has been specified in `persistence.xml`.
    `DataSource` | `getDefaultJtaDataSource()` Return the JTA-aware DataSource that the JPA persistence provider is supposed to use for accessing the database if none has been specified in `persistence.xml`.
    `LoadTimeWeaver` | `getLoadTimeWeaver()` Return the Spring LoadTimeWeaver to use for class instrumentation according to the JPA class transformer contract.
    `protected MutablePersistenceUnitInfo` | `getPersistenceUnitInfo(String persistenceUnitName)` Return the specified PersistenceUnitInfo from this manager's cache of processed persistence units, keeping it in the cache (i.e.
    `PersistenceUnitPostProcessor[]` | `getPersistenceUnitPostProcessors()` Return the PersistenceUnitPostProcessors to be applied to each PersistenceUnitInfo that has been parsed by this manager.
    `protected boolean` | `isPersistenceUnitOverrideAllowed()` Return whether an override of a same-named persistence unit is allowed.
    `PersistenceUnitInfo` | `obtainDefaultPersistenceUnitInfo()` Obtain the default PersistenceUnitInfo from this manager.
    `PersistenceUnitInfo` | `obtainPersistenceUnitInfo(String persistenceUnitName)` Obtain the specified PersistenceUnitInfo from this manager.
    `protected void` | `postProcessPersistenceUnitInfo(MutablePersistenceUnitInfo pui)` Hook method allowing subclasses to customize each PersistenceUnitInfo.
    `void` | `preparePersistenceUnitInfos()` Prepare the PersistenceUnitInfos according to the configuration of this manager: scanning for `persistence.xml` files, parsing all matching files, configuring and post-processing them.
    `void` | `setDataSourceLookup(DataSourceLookup dataSourceLookup)` Specify the JDBC DataSourceLookup that provides DataSources for the persistence provider, resolving data source names in `persistence.xml` against Spring-managed DataSource instances.
    `void` | `setDataSources(Map<String,DataSource> dataSources)` Specify the JDBC DataSources that the JPA persistence provider is supposed to use for accessing the database, resolving data source names in `persistence.xml` against Spring-managed DataSources.
    `void` | `setDefaultDataSource(DataSource defaultDataSource)` Specify the JDBC DataSource that the JPA persistence provider is supposed to use for accessing the database if none has been specified in `persistence.xml`.
    `void` | `setDefaultJtaDataSource(DataSource defaultJtaDataSource)` Specify the JDBC DataSource that the JPA persistence provider is supposed to use for accessing the database if none has been specified in `persistence.xml`.
    `void` | `setDefaultPersistenceUnitName(String defaultPersistenceUnitName)` Specify the name of the default persistence unit, if any.
    `void` | `setDefaultPersistenceUnitRootLocation(String defaultPersistenceUnitRootLocation)` Set the default persistence unit root location, to be applied if no unit-specific persistence unit root could be determined.
    `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 `&lt;mapping-file&gt;` 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` | `setPersistenceUnitPostProcessors(PersistenceUnitPostProcessor... postProcessors)` Set the PersistenceUnitPostProcessors to be applied to each PersistenceUnitInfo that has been parsed by this manager.
    `void` | `setPersistenceXmlLocation(String persistenceXmlLocation)` Specify the location of the `persistence.xml` files to load.
    `void` | `setPersistenceXmlLocations(String... persistenceXmlLocations)` Specify multiple locations of `persistence.xml` files to load.
    `void` | `setResourceLoader(ResourceLoader resourceLoader)` Set the ResourceLoader that this object runs in.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### DEFAULT_PERSISTENCE_XML_LOCATION

          public static final String DEFAULT_PERSISTENCE_XML_LOCATION

      Default location of the `persistence.xml` file: "classpath*:META-INF/persistence.xml".
      See Also:
        Constant Field Values

    - #### ORIGINAL_DEFAULT_PERSISTENCE_UNIT_ROOT_LOCATION

          public static final String ORIGINAL_DEFAULT_PERSISTENCE_UNIT_ROOT_LOCATION

      Default location for the persistence unit root URL: "classpath:", indicating the root of the class path.
      See Also:
        Constant Field Values

    - #### ORIGINAL_DEFAULT_PERSISTENCE_UNIT_NAME

          public static final String ORIGINAL_DEFAULT_PERSISTENCE_UNIT_NAME

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### DefaultPersistenceUnitManager

          public DefaultPersistenceUnitManager()

  - ### Method Detail

    - #### setPersistenceXmlLocation

          public void setPersistenceXmlLocation(String persistenceXmlLocation)

      Specify the location of the `persistence.xml` files to load. These can be specified as Spring resource locations and/or location patterns.

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

    - #### setPersistenceXmlLocations

          public void setPersistenceXmlLocations(String... persistenceXmlLocations)

      Specify multiple locations of `persistence.xml` files to load. These can be specified as Spring resource locations and/or location patterns.

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

      Parameters:
        `persistenceXmlLocations` - an array of Spring resource Strings identifying the location of the `persistence.xml` files to read

    - #### setDefaultPersistenceUnitRootLocation

          public void setDefaultPersistenceUnitRootLocation(String defaultPersistenceUnitRootLocation)

      Set the default persistence unit root location, to be applied if no unit-specific persistence unit root could be determined.

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

    - #### setDefaultPersistenceUnitName

          public void setDefaultPersistenceUnitName(String defaultPersistenceUnitName)

      Specify the name of the default persistence unit, if any. Default is "default".

      Primarily applied to a scanned persistence unit without `persistence.xml`. Also applicable to selecting a default unit from several persistence units available.

      See Also:
        `setPackagesToScan(java.lang.String...)`, `obtainDefaultPersistenceUnitInfo()`

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

    - #### setMappingResources

          public void setMappingResources(String... mappingResources)

      Specify one or more mapping resources (equivalent to `&lt;mapping-file&gt;` 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`.

      See Also:
        `setPackagesToScan(java.lang.String...)`

    - #### setDataSources

          public void setDataSources(Map<String,DataSource> dataSources)

      Specify the JDBC DataSources that the JPA persistence provider is supposed to use for accessing the database, resolving data source names in `persistence.xml` against Spring-managed DataSources.

      The specified Map needs to define data source names for specific DataSource objects, matching the data source names used in `persistence.xml`. If not specified, data source names will be resolved as JNDI names instead (as defined by standard JPA).

      See Also:
        `MapDataSourceLookup`

    - #### setDataSourceLookup

          public void setDataSourceLookup(DataSourceLookup dataSourceLookup)

      Specify the JDBC DataSourceLookup that provides DataSources for the persistence provider, resolving data source names in `persistence.xml` against Spring-managed DataSource instances.

      Default is JndiDataSourceLookup, which resolves DataSource names as JNDI names (as defined by standard JPA). Specify a BeanFactoryDataSourceLookup instance if you want DataSource names to be resolved against Spring bean names.

      Alternatively, consider passing in a map from names to DataSource instances via the "dataSources" property. If the `persistence.xml` file does not define DataSource names at all, specify a default DataSource via the "defaultDataSource" property.

      See Also:
        `JndiDataSourceLookup`, `BeanFactoryDataSourceLookup`, `setDataSources(java.util.Map<java.lang.String, javax.sql.DataSource>)`, `setDefaultDataSource(javax.sql.DataSource)`

    - #### getDataSourceLookup

          public DataSourceLookup getDataSourceLookup()

      Return the JDBC DataSourceLookup that provides DataSources for the persistence provider, resolving data source names in `persistence.xml` against Spring-managed DataSource instances.

    - #### setDefaultDataSource

          public void setDefaultDataSource(DataSource defaultDataSource)

      Specify the JDBC DataSource that the JPA persistence provider is supposed to use for accessing the database if none has been specified in `persistence.xml`. This variant indicates no special transaction setup, i.e. typical resource-local.

      In JPA speak, a DataSource passed in here will be uses as "nonJtaDataSource" on the PersistenceUnitInfo passed to the PersistenceProvider, provided that none has been registered before.

      See Also:
        `PersistenceUnitInfo.getNonJtaDataSource()`

    - #### getDefaultDataSource

          public DataSource getDefaultDataSource()

      Return the JDBC DataSource that the JPA persistence provider is supposed to use for accessing the database if none has been specified in `persistence.xml`.

    - #### setDefaultJtaDataSource

          public void setDefaultJtaDataSource(DataSource defaultJtaDataSource)

      Specify the JDBC DataSource that the JPA persistence provider is supposed to use for accessing the database if none has been specified in `persistence.xml`. This variant indicates that JTA is supposed to be used as transaction type.

      In JPA speak, a DataSource passed in here will be uses as "jtaDataSource" on the PersistenceUnitInfo passed to the PersistenceProvider, provided that none has been registered before.

      See Also:
        `PersistenceUnitInfo.getJtaDataSource()`

    - #### getDefaultJtaDataSource

          public DataSource getDefaultJtaDataSource()

      Return the JTA-aware DataSource that the JPA persistence provider is supposed to use for accessing the database if none has been specified in `persistence.xml`.

    - #### setPersistenceUnitPostProcessors

          public void setPersistenceUnitPostProcessors(PersistenceUnitPostProcessor... postProcessors)

      Set the PersistenceUnitPostProcessors to be applied to each PersistenceUnitInfo that has been parsed by this manager.

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

    - #### getPersistenceUnitPostProcessors

          public PersistenceUnitPostProcessor[] getPersistenceUnitPostProcessors()

      Return the PersistenceUnitPostProcessors to be applied to each PersistenceUnitInfo that has been parsed by this manager.

    - #### setLoadTimeWeaver

          public void setLoadTimeWeaver(LoadTimeWeaver loadTimeWeaver)

      Specify the Spring LoadTimeWeaver to use for class instrumentation according to the JPA class transformer contract.

      It is 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).

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

    - #### getLoadTimeWeaver

          public LoadTimeWeaver getLoadTimeWeaver()

      Return the Spring LoadTimeWeaver to use for class instrumentation according to the JPA class transformer contract.

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

    - #### afterPropertiesSet

          public void afterPropertiesSet()

      Description copied from interface: `InitializingBean`
      Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).

      This method allows the bean instance to perform initialization only possible when all bean properties have been set and to throw an exception in the event of misconfiguration.

      Specified by:
        `afterPropertiesSet` in interface `InitializingBean`

    - #### preparePersistenceUnitInfos

          public void preparePersistenceUnitInfos()

      Prepare the PersistenceUnitInfos according to the configuration of this manager: scanning for `persistence.xml` files, parsing all matching files, configuring and post-processing them.

      PersistenceUnitInfos cannot be obtained before this preparation method has been invoked.

      See Also:
        `obtainDefaultPersistenceUnitInfo()`, `obtainPersistenceUnitInfo(String)`

    - #### getPersistenceUnitInfo

          protected final MutablePersistenceUnitInfo getPersistenceUnitInfo(String persistenceUnitName)

      Return the specified PersistenceUnitInfo from this manager's cache of processed persistence units, keeping it in the cache (i.e. not 'obtaining' it for use but rather just accessing it for post-processing).

      This can be used in `postProcessPersistenceUnitInfo(org.springframework.orm.jpa.persistenceunit.MutablePersistenceUnitInfo)` implementations, detecting existing persistence units of the same name and potentially merging them.

      Parameters:
        `persistenceUnitName` - the name of the desired persistence unit
      Returns:
        the PersistenceUnitInfo in mutable form, or `null` if not available

    - #### postProcessPersistenceUnitInfo

          protected void postProcessPersistenceUnitInfo(MutablePersistenceUnitInfo pui)

      Hook method allowing subclasses to customize each PersistenceUnitInfo.

      The default implementation delegates to all registered PersistenceUnitPostProcessors. It is usually preferable to register further entity classes, jar files etc there rather than in a subclass of this manager, to be able to reuse the post-processors.

      Parameters:
        `pui` - the chosen PersistenceUnitInfo, as read from `persistence.xml`. Passed in as MutablePersistenceUnitInfo.
      See Also:
        `setPersistenceUnitPostProcessors(org.springframework.orm.jpa.persistenceunit.PersistenceUnitPostProcessor...)`

    - #### isPersistenceUnitOverrideAllowed

          protected boolean isPersistenceUnitOverrideAllowed()

      Return whether an override of a same-named persistence unit is allowed.

      Default is `false`. May be overridden to return `true`, for example if `postProcessPersistenceUnitInfo(org.springframework.orm.jpa.persistenceunit.MutablePersistenceUnitInfo)` is able to handle that case.

    - #### obtainDefaultPersistenceUnitInfo

          public PersistenceUnitInfo obtainDefaultPersistenceUnitInfo()

      Description copied from interface: `PersistenceUnitManager`
      Obtain the default PersistenceUnitInfo from this manager.
      Specified by:
        `obtainDefaultPersistenceUnitInfo` in interface `PersistenceUnitManager`
      Returns:
        the PersistenceUnitInfo (never `null`)

    - #### obtainPersistenceUnitInfo

          public PersistenceUnitInfo obtainPersistenceUnitInfo(String persistenceUnitName)

      Description copied from interface: `PersistenceUnitManager`
      Obtain the specified PersistenceUnitInfo from this manager.
      Specified by:
        `obtainPersistenceUnitInfo` in interface `PersistenceUnitManager`
      Parameters:
        `persistenceUnitName` - the name of the desired persistence unit
      Returns:
        the PersistenceUnitInfo (never `null`)