Save This Page
Home » spring-framework-2.5.5-with-dependencies » org.springframework » orm » hibernate3 » [javadoc | source]
org.springframework.orm.hibernate3
public class: LocalSessionFactoryBean [javadoc | source]
java.lang.Object
   org.springframework.orm.hibernate3.AbstractSessionFactoryBean
      org.springframework.orm.hibernate3.LocalSessionFactoryBean

All Implemented Interfaces:
    BeanClassLoaderAware, PersistenceExceptionTranslator, DisposableBean, InitializingBean, FactoryBean

Direct Known Subclasses:
    AnnotationSessionFactoryBean

org.springframework.beans.factory.FactoryBean that creates a Hibernate org.hibernate.SessionFactory . This is the usual way to set up a shared Hibernate SessionFactory in a Spring application context; the SessionFactory can then be passed to Hibernate-based DAOs via dependency injection.

Configuration settings can either be read from a Hibernate XML file, specified as "configLocation", or completely via this class. A typical local configuration consists of one or more "mappingResources", various "hibernateProperties" (not strictly necessary), and a "dataSource" that the SessionFactory should use. The latter can also be specified via Hibernate properties, but "dataSource" supports any Spring-configured DataSource, instead of relying on Hibernate's own connection providers.

This SessionFactory handling strategy is appropriate for most types of applications, from Hibernate-only single database apps to ones that need distributed transactions. Either HibernateTransactionManager or org.springframework.transaction.jta.JtaTransactionManager can be used for transaction demarcation, with the latter only necessary for transactions which span multiple databases.

This factory bean will by default expose a transaction-aware SessionFactory proxy, letting data access code work with the plain Hibernate SessionFactory and its getCurrentSession() method, while still being able to participate in current Spring-managed transactions: with any transaction management strategy, either local or JTA / EJB CMT, and any transaction synchronization mechanism, either Spring or JTA. Furthermore, getCurrentSession() will also seamlessly work with a request-scoped Session managed by org.springframework.orm.hibernate3.support.OpenSessionInViewFilter / org.springframework.orm.hibernate3.support.OpenSessionInViewInterceptor .

Requires Hibernate 3.1 or later. Note that this factory will use "on_close" as default Hibernate connection release mode, unless in the case of a "jtaTransactionManager" specified, for the reason that this is appropriate for most Spring-based applications (in particular when using Spring's HibernateTransactionManager). Hibernate 3.0 used "on_close" as its own default too; however, Hibernate 3.1 changed this to "auto" (i.e. "after_statement" or "after_transaction").

Fields inherited from org.springframework.orm.hibernate3.AbstractSessionFactoryBean:
logger
Method from org.springframework.orm.hibernate3.LocalSessionFactoryBean Summary:
afterSessionFactoryCreation,   buildSessionFactory,   createDatabaseSchema,   destroy,   dropDatabaseSchema,   executeSchemaScript,   executeSchemaStatement,   getConfigTimeCacheProvider,   getConfigTimeDataSource,   getConfigTimeLobHandler,   getConfigTimeTransactionManager,   getConfiguration,   getHibernateProperties,   newConfiguration,   newSessionFactory,   postProcessConfiguration,   postProcessMappings,   setBeanClassLoader,   setCacheProvider,   setCacheableMappingLocations,   setCollectionCacheStrategies,   setConfigLocation,   setConfigLocations,   setConfigurationClass,   setEntityCacheStrategies,   setEntityInterceptor,   setEventListeners,   setFilterDefinitions,   setHibernateProperties,   setJtaTransactionManager,   setLobHandler,   setMappingDirectoryLocations,   setMappingJarLocations,   setMappingLocations,   setMappingResources,   setNamingStrategy,   setSchemaUpdate,   setTypeDefinitions,   updateDatabaseSchema
Methods from org.springframework.orm.hibernate3.AbstractSessionFactoryBean:
afterPropertiesSet,   afterSessionFactoryCreation,   beforeSessionFactoryDestruction,   buildSessionFactory,   convertHibernateAccessException,   destroy,   getDataSource,   getObject,   getObjectType,   getSessionFactory,   isExposeTransactionAwareSessionFactory,   isSingleton,   isUseTransactionAwareDataSource,   setDataSource,   setExposeTransactionAwareSessionFactory,   setJdbcExceptionTranslator,   setUseTransactionAwareDataSource,   translateExceptionIfPossible,   wrapSessionFactoryIfNecessary
Methods from java.lang.Object:
equals,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from org.springframework.orm.hibernate3.LocalSessionFactoryBean Detail:
 protected  void afterSessionFactoryCreation() throws Exception 
    Executes schema update if requested.
 protected SessionFactory buildSessionFactory() throws Exception 
 public  void createDatabaseSchema() throws DataAccessException 
    Execute schema creation script, determined by the Configuration object used for creating the SessionFactory. A replacement for Hibernate's SchemaExport class, to be invoked on application setup.

    Fetch the LocalSessionFactoryBean itself rather than the exposed SessionFactory to be able to invoke this method, e.g. via LocalSessionFactoryBean lsfb = (LocalSessionFactoryBean) ctx.getBean("&mySessionFactory");.

    Uses the SessionFactory that this bean generates for accessing a JDBC connection to perform the script.

 public  void destroy() throws HibernateException 
    Allows for schema export on shutdown.
 public  void dropDatabaseSchema() throws DataAccessException 
    Execute schema drop script, determined by the Configuration object used for creating the SessionFactory. A replacement for Hibernate's SchemaExport class, to be invoked on application setup.

    Fetch the LocalSessionFactoryBean itself rather than the exposed SessionFactory to be able to invoke this method, e.g. via LocalSessionFactoryBean lsfb = (LocalSessionFactoryBean) ctx.getBean("&mySessionFactory");.

    Uses the SessionFactory that this bean generates for accessing a JDBC connection to perform the script.

 protected  void executeSchemaScript(Connection con,
    String[] sql) throws SQLException 
    Execute the given schema script on the given JDBC Connection.

    Note that the default implementation will log unsuccessful statements and continue to execute. Override the executeSchemaStatement method to treat failures differently.

 protected  void executeSchemaStatement(Statement stmt,
    String sql) throws SQLException 
    Execute the given schema SQL on the given JDBC Statement.

    Note that the default implementation will log unsuccessful statements and continue to execute. Override this method to treat failures differently.

 public static CacheProvider getConfigTimeCacheProvider() 
    Return the CacheProvider for the currently configured Hibernate SessionFactory, to be used by LocalCacheProviderProxy.

    This instance will be set before initialization of the corresponding SessionFactory, and reset immediately afterwards. It is thus only available during configuration.

 public static DataSource getConfigTimeDataSource() 
    Return the DataSource for the currently configured Hibernate SessionFactory, to be used by LocalDataSourceConnectionProvoder.

    This instance will be set before initialization of the corresponding SessionFactory, and reset immediately afterwards. It is thus only available during configuration.

 public static LobHandler getConfigTimeLobHandler() 
    Return the LobHandler for the currently configured Hibernate SessionFactory, to be used by UserType implementations like ClobStringType.

    This instance will be set before initialization of the corresponding SessionFactory, and reset immediately afterwards. It is thus only available during configuration.

 public static TransactionManager getConfigTimeTransactionManager() 
    Return the JTA TransactionManager for the currently configured Hibernate SessionFactory, to be used by LocalTransactionManagerLookup.

    This instance will be set before initialization of the corresponding SessionFactory, and reset immediately afterwards. It is thus only available during configuration.

 public final Configuration getConfiguration() 
    Return the Configuration object used to build the SessionFactory. Allows access to configuration metadata stored there (rarely needed).
 public Properties getHibernateProperties() 
    Return the Hibernate properties, if any. Mainly available for configuration through property paths that specify individual keys.
 protected Configuration newConfiguration() throws HibernateException 
    Subclasses can override this method to perform custom initialization of the Configuration instance used for SessionFactory creation. The properties of this LocalSessionFactoryBean will be applied to the Configuration object that gets returned here.

    The default implementation creates a new Configuration instance. A custom implementation could prepare the instance in a specific way, or use a custom Configuration subclass.

 protected SessionFactory newSessionFactory(Configuration config) throws HibernateException 
    Subclasses can override this method to perform custom initialization of the SessionFactory instance, creating it via the given Configuration object that got prepared by this LocalSessionFactoryBean.

    The default implementation invokes Configuration's buildSessionFactory. A custom implementation could prepare the instance in a specific way, or use a custom SessionFactoryImpl subclass.

 protected  void postProcessConfiguration(Configuration config) throws HibernateException 
    To be implemented by subclasses that want to to perform custom post-processing of the Configuration object after this FactoryBean performed its default initialization.

    Invoked after the Configuration.buildMappings() call, so that it can operate on the completed and fully parsed mapping information.

 protected  void postProcessMappings(Configuration config) throws HibernateException 
    To be implemented by subclasses that want to to register further mappings on the Configuration object after this FactoryBean registered its specified mappings.

    Invoked before the Configuration.buildMappings() call, so that it can still extend and modify the mapping information.

 public  void setBeanClassLoader(ClassLoader beanClassLoader) 
 public  void setCacheProvider(CacheProvider cacheProvider) 
    Set the Hibernate CacheProvider to use for the SessionFactory. Allows for using a Spring-managed CacheProvider instance.

    Note: If this is set, the Hibernate settings should not define a cache provider to avoid meaningless double configuration.

 public  void setCacheableMappingLocations(Resource[] cacheableMappingLocations) 
    Set locations of cacheable Hibernate mapping files, for example as web app resource "/WEB-INF/mapping/example.hbm.xml". Supports any resource location via Spring's resource abstraction, as long as the resource can be resolved in the file system.

    Can be used to add to mappings from a Hibernate XML config file, or to specify all mappings locally.

 public  void setCollectionCacheStrategies(Properties collectionCacheStrategies) 
    Specify the cache strategies for persistent collections (with specific roles). This configuration setting corresponds to the <collection-cache> entry in the "hibernate.cfg.xml" configuration format.

    For example:

    <property name="collectionCacheStrategies">
    <props>
    <prop key="com.mycompany.Order.items">read-write</prop>
    <prop key="com.mycompany.Product.categories">read-only,myRegion</prop>
    </props>
    </property>
    Note that appending a cache region name (with a comma separator) is only supported on Hibernate 3.1, where this functionality is publically available.
 public  void setConfigLocation(Resource configLocation) 
    Set the location of a single Hibernate XML config file, for example as classpath resource "classpath:hibernate.cfg.xml".

    Note: Can be omitted when all necessary properties and mapping resources are specified locally via this bean.

 public  void setConfigLocations(Resource[] configLocations) 
    Set the locations of multiple Hibernate XML config files, for example as classpath resources "classpath:hibernate.cfg.xml,classpath:extension.cfg.xml".

    Note: Can be omitted when all necessary properties and mapping resources are specified locally via this bean.

 public  void setConfigurationClass(Class configurationClass) 
    Specify the Hibernate Configuration class to use. Default is "org.hibernate.cfg.Configuration"; any subclass of this default Hibernate Configuration class can be specified.

    Can be set to "org.hibernate.cfg.AnnotationConfiguration" for using Hibernate3 annotation support (initially only available as alpha download separate from the main Hibernate3 distribution).

    Annotated packages and annotated classes can be specified via the corresponding tags in "hibernate.cfg.xml" then, so this will usually be combined with a "configLocation" property that points at such a standard Hibernate configuration file.

 public  void setEntityCacheStrategies(Properties entityCacheStrategies) 
    Specify the cache strategies for entities (persistent classes or named entities). This configuration setting corresponds to the <class-cache> entry in the "hibernate.cfg.xml" configuration format.

    For example:

    <property name="entityCacheStrategies">
    <props>
    <prop key="com.mycompany.Customer">read-write</prop>
    <prop key="com.mycompany.Product">read-only,myRegion</prop>
    </props>
    </property>
    Note that appending a cache region name (with a comma separator) is only supported on Hibernate 3.1, where this functionality is publically available.
 public  void setEntityInterceptor(Interceptor entityInterceptor) 
    Set a Hibernate entity interceptor that allows to inspect and change property values before writing to and reading from the database. Will get applied to any new Session created by this factory.

    Such an interceptor can either be set at the SessionFactory level, i.e. on LocalSessionFactoryBean, or at the Session level, i.e. on HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. It's preferable to set it on LocalSessionFactoryBean or HibernateTransactionManager to avoid repeated configuration and guarantee consistent behavior in transactions.

 public  void setEventListeners(Map eventListeners) 
    Specify the Hibernate event listeners to register, with listener types as keys and listener objects as values.

    Instead of a single listener object, you can also pass in a list or set of listeners objects as value. However, this is only supported on Hibernate 3.1.

    See the Hibernate documentation for further details on listener types and associated listener interfaces.

 public  void setFilterDefinitions(FilterDefinition[] filterDefinitions) 
    Specify the Hibernate FilterDefinitions to register with the SessionFactory. This is an alternative to specifying <<filter-def> elements in Hibernate mapping files.

    Typically, the passed-in FilterDefinition objects will have been defined as Spring FilterDefinitionFactoryBeans, probably as inner beans within the LocalSessionFactoryBean definition.

 public  void setHibernateProperties(Properties hibernateProperties) 
    Set Hibernate properties, such as "hibernate.dialect".

    Can be used to override values in a Hibernate XML config file, or to specify all necessary properties locally.

    Note: Do not specify a transaction provider here when using Spring-driven transactions. It is also advisable to omit connection provider settings and use a Spring-set DataSource instead.

 public  void setJtaTransactionManager(TransactionManager jtaTransactionManager) 
    Set the JTA TransactionManager to be used for Hibernate's TransactionManagerLookup. Allows for using a Spring-managed JTA TransactionManager for Hibernate's cache synchronization.

    Note: If this is set, the Hibernate settings should not define a transaction manager lookup to avoid meaningless double configuration.

 public  void setLobHandler(LobHandler lobHandler) 
    Set the LobHandler to be used by the SessionFactory. Will be exposed at config time for UserType implementations.
 public  void setMappingDirectoryLocations(Resource[] mappingDirectoryLocations) 
    Set locations of directories that contain Hibernate mapping resources, like "WEB-INF/mappings".

    Can be used to add to mappings from a Hibernate XML config file, or to specify all mappings locally.

 public  void setMappingJarLocations(Resource[] mappingJarLocations) 
    Set locations of jar files that contain Hibernate mapping resources, like "WEB-INF/lib/example.hbm.jar".

    Can be used to add to mappings from a Hibernate XML config file, or to specify all mappings locally.

 public  void setMappingLocations(Resource[] mappingLocations) 
    Set locations of Hibernate mapping files, for example as classpath resource "classpath:example.hbm.xml". Supports any resource location via Spring's resource abstraction, for example relative paths like "WEB-INF/mappings/example.hbm.xml" when running in an application context.

    Can be used to add to mappings from a Hibernate XML config file, or to specify all mappings locally.

 public  void setMappingResources(String[] mappingResources) 
    Set Hibernate mapping resources to be found in the class path, like "example.hbm.xml" or "mypackage/example.hbm.xml". Analogous to mapping entries in a Hibernate XML config file. Alternative to the more generic setMappingLocations method.

    Can be used to add to mappings from a Hibernate XML config file, or to specify all mappings locally.

 public  void setNamingStrategy(NamingStrategy namingStrategy) 
    Set a Hibernate NamingStrategy for the SessionFactory, determining the physical column and table names given the info in the mapping document.
 public  void setSchemaUpdate(boolean schemaUpdate) 
    Set whether to execute a schema update after SessionFactory initialization.

    For details on how to make schema update scripts work, see the Hibernate documentation, as this class leverages the same schema update script support in org.hibernate.cfg.Configuration as Hibernate's own SchemaUpdate tool.

 public  void setTypeDefinitions(TypeDefinitionBean[] typeDefinitions) 
    Specify the Hibernate type definitions to register with the SessionFactory, as Spring TypeDefinitionBean instances. This is an alternative to specifying <<typedef> elements in Hibernate mapping files.

    Unfortunately, Hibernate itself does not define a complete object that represents a type definition, hence the need for Spring's TypeDefinitionBean.

 public  void updateDatabaseSchema() throws DataAccessException 
    Execute schema update script, determined by the Configuration object used for creating the SessionFactory. A replacement for Hibernate's SchemaUpdate class, for automatically executing schema update scripts on application startup. Can also be invoked manually.

    Fetch the LocalSessionFactoryBean itself rather than the exposed SessionFactory to be able to invoke this method, e.g. via LocalSessionFactoryBean lsfb = (LocalSessionFactoryBean) ctx.getBean("&mySessionFactory");.

    Uses the SessionFactory that this bean generates for accessing a JDBC connection to perform the script.