Package org.kuali.rice.krad.data.jpa

Class KradEntityManagerFactoryBean

java.lang.Object
org.kuali.rice.krad.data.jpa.KradEntityManagerFactoryBean
All Implemented Interfaces:
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<javax.persistence.EntityManagerFactory>, org.springframework.beans.factory.InitializingBean, org.springframework.context.ResourceLoaderAware, org.springframework.context.weaving.LoadTimeWeaverAware, org.springframework.dao.support.PersistenceExceptionTranslator, org.springframework.orm.jpa.EntityManagerFactoryInfo
Direct Known Subclasses:
KradEclipseLinkEntityManagerFactoryBean
public class KradEntityManagerFactoryBean extends Object implements org.springframework.beans.factory.FactoryBean<javax.persistence.EntityManagerFactory>, org.springframework.beans.factory.BeanClassLoaderAware, org.springframework.beans.factory.BeanFactoryAware, org.springframework.beans.factory.BeanNameAware, org.springframework.beans.factory.InitializingBean, org.springframework.beans.factory.DisposableBean, org.springframework.orm.jpa.EntityManagerFactoryInfo, org.springframework.dao.support.PersistenceExceptionTranslator, org.springframework.context.ResourceLoaderAware, org.springframework.context.weaving.LoadTimeWeaverAware
A KRAD-managed EntityManagerFactory factory bean which can be used to configure a JPA persistence unit using the Spring Framework.

This implementation does not support the use of a custom PersistenceUnitManager, but rather stores and manages one internally. This is intended to be an alternative to direct usage of Spring's LocalContainerEntityManagerFactoryBean in order to make JPA configuration with KRAD simpler.

Minimal Configuration

Minimal configuration of this factory bean will include the following:

  • persistenceUnitName
  • dataSource or jtaDataSource
  • persistenceProvider or jpaVendorAdapter

Note that persistence unit names must be unique, so choose a name which is unlikely to clash with any potential persistence units configured within the runtime environment.

Behavior

When leveraging this class, persistence.xml files are not used. Rather, persistence unit configuration is loaded via the various settings provided on this factory bean which contain everything needed to create the desired persistence unit configuration in the majority of cases. If a KRAD application needs more control over the configuration of the persistence unit or wants to use persistence.xml and JPA's default bootstrapping and classpath scanning behavior, an EntityManagerFactory can be configured using the other classes provided by the Spring framework or by other means as needed. See LocalContainerEntityManagerFactoryBean for an alternative approach.

Only one of JTA or non-JTA datasource can be set. Depending on which one is set, the underlying persistence unit will have it's PersistenceUnitTransactionType set to either RESOURCE_LOCAL or JTA. If both of these are set, then this class will throw an IllegalStateException when the afterPropertiesSet() method is invoked by the Spring Framework.

Elsewhere, this class delegates to implementations of LocalContainerEntityManagerFactoryBean and DefaultPersistenceUnitManager, so information on the specific behavior of some of the settings and methods on this class can be found on the javadoc for those classes as well.

JPA Property Defaults

When afterPropertiesSet() is invoked, this class will scan the current ConfigContext for JPA properties and make them available to the persistence unit. It will combine these with any properties that were set directly on this factory bean via the setJpaProperties(java.util.Properties) or setJpaPropertyMap(java.util.Map) methods. invalid input: '<'/p

This scanning occurs in the following order, items later in the list will override any properties from earlier if they happen to set the same effective property value:

  1. Scan ConfigContext for properties that begin with "rice.krad.jpa.global." For any found, strip off this prefix prior to placing it into the JPA property map.
  2. Scan ConfigContext for properties that being with "rice.krad.jpa.<persistence-unit-name>" where "persistence-unit-name" is the configured name of this persistence unit. For any found, strip off this prefix prior to placing it into the JPA property map.
  3. Invoke loadCustomJpaDefaults(java.util.Map) to allow for possible subclass customization of JPA property defaults
  4. Load the JPA properties configured via setJpaPropertyMap(java.util.Map) and setJpaProperties(java.util.Properties). It is potentially non-deterministic which of these setters will take precedence over the other, so it is recommended to only invoke one of them on a given instance of this factory bean.

Subclassing

This class can be subclassed to provide additional specialized implementations of this factory bean. A potential use for this might be to provide a factory bean that defaults certain values as part of it's default setup.

This class sets the JpaVendorAdapter from the jpa.vendor.adapter.class property. For example: rice.krad.jpa.global.jpa.vendor.adapter.class=org.springframework.orm.jpa.vendor.EclipseLinkJpaVendorAdapter sets the vendor adapter to eclipselink.

Author:
Kuali Rice Team (rice.collab@kuali.org)

  • Field Details

    • JPA_PROPERTY_PREFIX

      public static final String JPA_PROPERTY_PREFIX
      Prefix for property names that are passed to the JPA persistence context as JPA properties.

      To use this, concatenate this prefix with the persistence context name. The total prefix (including the persistence context) will then be stripped before being passed to the JPA entity manager factory when using the KradEntityManagerFactoryBean.

      See Also:

    • GLOBAL_JPA_PROPERTY_PREFIX

      public static final String GLOBAL_JPA_PROPERTY_PREFIX
      Prefix for property names that are passed to *all* JPA persistence contexts as JPA properties.

      The total prefix will then be stripped before being passed to all JPA entity manager factories that use the KradEntityManagerFactoryBean.

      See Also:

  • Constructor Details

    • KradEntityManagerFactoryBean

      public KradEntityManagerFactoryBean() throws Exception
      Creates a default KRAD-managed factory bean.
      Throws:
      Exception

  • Method Details

    • getInternalFactoryBean

      protected org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean getInternalFactoryBean()
      Retrieve a reference to the internal LocalContainerEntityManagerFactoryBean which is used by this factory bean.

      Primarily intended to allow subclasses to access this internal factory bean when needed.

      Returns:
      the internal LocalContainerEntityManagerFactoryBean managed by this bean

    • createPersistenceUnitManager

      protected org.springframework.orm.jpa.persistenceunit.DefaultPersistenceUnitManager createPersistenceUnitManager()
      Creates a persistence unit manager.
      Returns:
      a persistence unit manager.

    • createInternalFactoryBean

      protected org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean createInternalFactoryBean(org.springframework.orm.jpa.persistenceunit.PersistenceUnitManager manager)
      Creates a JPA-specific entity manager factory bean.
      Parameters:
      manager - the persistence unit manager to use.
      Returns:
      a JPA-specific entity manager factory bean.

    • afterPropertiesSet

      public void afterPropertiesSet() throws javax.persistence.PersistenceException
      Specified by:
      afterPropertiesSet in interface org.springframework.beans.factory.InitializingBean
      Throws:
      javax.persistence.PersistenceException

    • loadCustomJpaDefaults

      protected void loadCustomJpaDefaults(Map<String,String> jpaProperties)
      Allows for loading of custom JPA defaults by subclasses, default implementation does nothing so subclasses need not call super.loadCustomJpaDefaults.

      Subclasses are free to override this method as they see fit. This method is executed after other defaults are loaded. A reference to the current Map of JPA properties is passed. Subclasses should take care if removing or overwriting any of the values which already exist in the given Map.

      Parameters:
      jpaProperties - the current Map of JPA property defaults.

    • loadGlobalJpaDefaults

      protected void loadGlobalJpaDefaults(Map<String,String> jpaProperties)
      Loads the global JPA defaults from the config.
      Parameters:
      jpaProperties - the current Map of JPA property defaults.

    • loadPersistenceUnitJpaDefaults

      protected void loadPersistenceUnitJpaDefaults(Map<String,String> jpaProperties)
      Loads the persistence unit JPA defaults from the config.
      Parameters:
      jpaProperties - the current Map of JPA property defaults.

    • constructPersistenceUnitJpaPropertyPrefix

      protected String constructPersistenceUnitJpaPropertyPrefix()
      Builds a persistence unit JPA property prefix.
      Returns:
      a persistence unit JPA property prefix.

    • assemblePersistenceUnitPostProcessors

      protected org.springframework.orm.jpa.persistenceunit.PersistenceUnitPostProcessor[] assemblePersistenceUnitPostProcessors()
      Assembles the PersistenceUnitPostProcessors into an array.
      Returns:
      an array of the PersistenceUnitPostProcessors.

    • getManagedClassNames

      public List<String> getManagedClassNames()
      Returns the list of all managed class names which have been configured on this factory bean.

      This list is modifiable, so the returned list may be modified directly if desired.

      Returns:
      list of all managed class names, may be an empty list but will never return null

    • getPersistenceUnitPostProcessors

      public org.springframework.orm.jpa.persistenceunit.PersistenceUnitPostProcessor[] getPersistenceUnitPostProcessors()
      Returns an array of the PersistenceUnitPostProcessor instances which have been configured on this factory bean.
      Returns:
      array of post processors, may be empty but will never return null

    • getPersistenceUnitManager

      protected org.springframework.orm.jpa.persistenceunit.DefaultPersistenceUnitManager getPersistenceUnitManager()
      Returns a reference to the internal DefaultPersistenceUnitManager which is used by this factory bean.
      Returns:
      the internal persistence unit manager, will never return null

    • destroy

      public void destroy()
      Specified by:
      destroy in interface org.springframework.beans.factory.DisposableBean

    • getObjectType

      public Class<? extends javax.persistence.EntityManagerFactory> getObjectType()
      Specified by:
      getObjectType in interface org.springframework.beans.factory.FactoryBean<javax.persistence.EntityManagerFactory>

    • isSingleton

      public boolean isSingleton()
      Specified by:
      isSingleton in interface org.springframework.beans.factory.FactoryBean<javax.persistence.EntityManagerFactory>

    • getObject

      public javax.persistence.EntityManagerFactory getObject()
      Specified by:
      getObject in interface org.springframework.beans.factory.FactoryBean<javax.persistence.EntityManagerFactory>

    • getNativeEntityManagerFactory

      public javax.persistence.EntityManagerFactory getNativeEntityManagerFactory()
      Specified by:
      getNativeEntityManagerFactory in interface org.springframework.orm.jpa.EntityManagerFactoryInfo

    • createNativeEntityManager

      public javax.persistence.EntityManager createNativeEntityManager(Map<?,?> map)
      Specified by:
      createNativeEntityManager in interface org.springframework.orm.jpa.EntityManagerFactoryInfo

    • setBeanName

      public void setBeanName(String name)
      Specified by:
      setBeanName in interface org.springframework.beans.factory.BeanNameAware

    • setBeanFactory

      public void setBeanFactory(org.springframework.beans.factory.BeanFactory beanFactory)
      Specified by:
      setBeanFactory in interface org.springframework.beans.factory.BeanFactoryAware

    • getBeanClassLoader

      public ClassLoader getBeanClassLoader()
      Specified by:
      getBeanClassLoader in interface org.springframework.orm.jpa.EntityManagerFactoryInfo

    • setBeanClassLoader

      public void setBeanClassLoader(ClassLoader classLoader)
      Specified by:
      setBeanClassLoader in interface org.springframework.beans.factory.BeanClassLoaderAware

    • getEntityManagerInterface

      public Class<? extends javax.persistence.EntityManager> getEntityManagerInterface()
      Specified by:
      getEntityManagerInterface in interface org.springframework.orm.jpa.EntityManagerFactoryInfo

    • setLoadTimeWeaver

      public void setLoadTimeWeaver(org.springframework.instrument.classloading.LoadTimeWeaver loadTimeWeaver)
      Specified by:
      setLoadTimeWeaver in interface org.springframework.context.weaving.LoadTimeWeaverAware

    • setResourceLoader

      public void setResourceLoader(org.springframework.core.io.ResourceLoader resourceLoader)
      Specified by:
      setResourceLoader in interface org.springframework.context.ResourceLoaderAware

    • getPersistenceUnitInfo

      public javax.persistence.spi.PersistenceUnitInfo getPersistenceUnitInfo()
      Specified by:
      getPersistenceUnitInfo in interface org.springframework.orm.jpa.EntityManagerFactoryInfo

    • getPersistenceUnitName

      public String getPersistenceUnitName()
      Specified by:
      getPersistenceUnitName in interface org.springframework.orm.jpa.EntityManagerFactoryInfo

    • getDataSource

      public DataSource getDataSource()
      Specified by:
      getDataSource in interface org.springframework.orm.jpa.EntityManagerFactoryInfo

    • getJpaDialect

      public org.springframework.orm.jpa.JpaDialect getJpaDialect()
      Specified by:
      getJpaDialect in interface org.springframework.orm.jpa.EntityManagerFactoryInfo

    • getPersistenceProvider

      public javax.persistence.spi.PersistenceProvider getPersistenceProvider()
      Specified by:
      getPersistenceProvider in interface org.springframework.orm.jpa.EntityManagerFactoryInfo

    • translateExceptionIfPossible

      public org.springframework.dao.DataAccessException translateExceptionIfPossible(RuntimeException ex)
      Specified by:
      translateExceptionIfPossible in interface org.springframework.dao.support.PersistenceExceptionTranslator

    • setManagedClassNames

      public void setManagedClassNames(List<String> managedClassNames)
      Specifies a List of class names which should be loaded into the resulting EntityManagerFactory as managed JPA classes.
      Parameters:
      managedClassNames - the List of managed class names to set on this factory bean

    • setEntityManagerInterface

      public void setEntityManagerInterface(Class<? extends javax.persistence.EntityManager> emInterface)
      Specify the (potentially vendor-specific) EntityManager interface that this factory's EntityManagers are supposed to implement.

      The default will be taken from the specific JpaVendorAdapter, if any, or set to the standard EntityManager interface else.

      Parameters:
      emInterface - the EntityManager interface to use
      See Also:
      • JpaVendorAdapter.getEntityManagerInterface()
      • EntityManagerFactoryInfo.getEntityManagerInterface()

    • setEntityManagerFactoryInterface

      public void setEntityManagerFactoryInterface(Class<? extends javax.persistence.EntityManagerFactory> emfInterface)
      Specify the (potentially vendor-specific) EntityManagerFactory interface that this EntityManagerFactory proxy is supposed to implement.

      The default will be taken from the specific JpaVendorAdapter, if any, or set to the standard EntityManagerFactory interface else.

      Parameters:
      emfInterface - the EntityManagerFactory interface to use
      See Also:
      • JpaVendorAdapter.getEntityManagerFactoryInterface()

    • getJpaPropertyMap

      public Map<String,Object> getJpaPropertyMap()
      Allow Map access to the JPA properties to be passed to the persistence provider, with the option to add or override specific entries.

      Useful for specifying entries directly, for example via "jpaPropertyMap[myKey]".

      Returns:
      the map of JPA properties

    • setJpaPropertyMap

      public void setJpaPropertyMap(Map<String,?> jpaProperties)
      Specify JPA properties as a Map, to be passed into Persistence.createEntityManagerFactory (if any).

      Can be populated with a "map" or "props" element in XML bean definitions.

      Parameters:
      jpaProperties - map of JPA properties to set
      See Also:
      • Persistence.createEntityManagerFactory(String, java.util.Map)
      • PersistenceProvider.createContainerEntityManagerFactory(javax.persistence.spi.PersistenceUnitInfo, java.util.Map)

    • setJpaProperties

      public void setJpaProperties(Properties jpaProperties)
      Specify JPA properties, to be passed into Persistence.createEntityManagerFactory (if any).

      Can be populated with a String "value" (parsed via PropertiesEditor) or a "props" element in XML bean definitions.

      Parameters:
      jpaProperties - the properties to set
      See Also:
      • Persistence.createEntityManagerFactory(String, java.util.Map)
      • PersistenceProvider.createContainerEntityManagerFactory(javax.persistence.spi.PersistenceUnitInfo, java.util.Map)

    • setPersistenceUnitName

      public void setPersistenceUnitName(String persistenceUnitName)
      Specify the name of the EntityManagerFactory configuration.

      Default is none, indicating the default EntityManagerFactory configuration. The persistence provider will throw an exception if ambiguous EntityManager configurations are found.

      Parameters:
      persistenceUnitName - the name of the persistence unit
      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).

      Parameters:
      packagesToScan - one or more base packages to search, analogous to Spring's component-scan configuration for regular Spring components
      See Also:
      • DefaultPersistenceUnitManager.setPackagesToScan(String...)

    • 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.

      Parameters:
      mappingResources - one or more mapping resources to use
      See Also:
      • DefaultPersistenceUnitManager.setMappingResources(String...)

    • 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, 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.

      Parameters:
      dataSource - the DataSource to use for this EntityManagerFactory
      See Also:
      • PersistenceUnitInfo.getNonJtaDataSource()
      • DefaultPersistenceUnitManager.setDefaultDataSource(javax.sql.DataSource)

    • setJtaDataSource

      public void setJtaDataSource(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).

      Parameters:
      jtaDataSource - the JTA-enabled DataSource to use for this EntityManagerFactory
      See Also:
      • PersistenceUnitInfo.getJtaDataSource()
      • DefaultPersistenceUnitManager.setDefaultJtaDataSource(javax.sql.DataSource)

    • setPersistenceProvider

      public void setPersistenceProvider(javax.persistence.spi.PersistenceProvider persistenceProvider)
      Set the PersistenceProvider instance to use for creating the EntityManagerFactory.

      If not specified, the persistence provider will be taken from the JpaVendorAdapter (if any) or determined by the persistence unit deployment descriptor (as far as possible).

      Parameters:
      persistenceProvider - the PersistenceProvider to set
      See Also:
      • JpaVendorAdapter.getPersistenceProvider()
      • PersistenceProvider
      • Persistence

    • setJpaDialect

      public void setJpaDialect(org.springframework.orm.jpa.JpaDialect jpaDialect)
      Specify the vendor-specific JpaDialect implementation to associate with this EntityManagerFactory.

      This will be exposed through the EntityManagerFactoryInfo interface, to be picked up as default dialect by accessors that intend to use JpaDialect functionality.

      Parameters:
      jpaDialect - the JPA dialect to set
      See Also:
      • EntityManagerFactoryInfo.getJpaDialect()

    • setJpaVendorAdapter

      public void setJpaVendorAdapter(org.springframework.orm.jpa.JpaVendorAdapter jpaVendorAdapter)
      Specify the JpaVendorAdapter implementation for the desired JPA provider, if any.

      This will initialize appropriate defaults for the given provider, such as persistence provider class and JpaDialect, unless locally overridden in this FactoryBean.

      Parameters:
      jpaVendorAdapter - the JpaVendorAdapter to set

    • setPersistenceUnitPostProcessors

      public void setPersistenceUnitPostProcessors(org.springframework.orm.jpa.persistenceunit.PersistenceUnitPostProcessor... postProcessors)
      Set the PersistenceUnitPostProcessors to be applied to the * PersistenceUnitInfo used for creating this EntityManagerFactory.

      Note that if executed before afterPropertiesSet() then this factory bean may introduce its own post processor instances. If invoked after, then this method will override internally configured post processors.

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

      Parameters:
      postProcessors - one or more post processors to set