org.hibernate
Interface SessionFactory

All Superinterfaces:
Referenceable, Serializable
All Known Subinterfaces:
SessionFactoryImplementor
All Known Implementing Classes:
SessionFactoryImpl, SessionFactoryStub

public interface SessionFactory
extends Referenceable, Serializable

The main contract here is the creation of Session instances. Usually an application has a single SessionFactory instance and threads servicing client requests obtain Session instances from this factory.

The internal state of a SessionFactory is immutable. Once it is created this internal state is set. This internal state includes all of the metadata about Object/Relational Mapping.

Implementors must be threadsafe.

Author:
Gavin King, Steve Ebersole
See Also:
Configuration

Method Summary
 void close()
          Destroy this SessionFactory and release all resources (caches, connection pools, etc).
 boolean containsFetchProfileDefinition(String name)
          Determine if this session factory contains a fetch profile definition registered under the given name.
 void evict(Class persistentClass)
          Deprecated. Use Cache.evictEntityRegion(Class) accessed through getCache() instead.
 void evict(Class persistentClass, Serializable id)
          Deprecated. Use Cache.containsEntity(Class, Serializable) accessed through getCache() instead.
 void evictCollection(String roleName)
          Deprecated. Use Cache.evictCollectionRegion(String) accessed through getCache() instead.
 void evictCollection(String roleName, Serializable id)
          Deprecated. Use Cache.evictCollection(String,Serializable) accessed through getCache() instead.
 void evictEntity(String entityName)
          Deprecated. Use Cache.evictEntityRegion(String) accessed through getCache() instead.
 void evictEntity(String entityName, Serializable id)
          Deprecated. Use Cache.evictEntity(String,Serializable) accessed through getCache() instead.
 void evictQueries()
          Deprecated. Use Cache.evictQueryRegions() accessed through getCache() instead.
 void evictQueries(String cacheRegion)
          Deprecated. Use Cache.evictQueryRegion(String) accessed through getCache() instead.
 Map<String,ClassMetadata> getAllClassMetadata()
          Retrieve the ClassMetadata for all mapped entities.
 Map getAllCollectionMetadata()
          Get the CollectionMetadata for all mapped collections
 Cache getCache()
          Obtain direct access to the underlying cache regions.
 ClassMetadata getClassMetadata(Class entityClass)
          Retrieve the ClassMetadata associated with the given entity class.
 ClassMetadata getClassMetadata(String entityName)
          Retrieve the ClassMetadata associated with the given entity class.
 CollectionMetadata getCollectionMetadata(String roleName)
          Get the CollectionMetadata associated with the named collection role.
 Session getCurrentSession()
          Obtains the current session.
 Set getDefinedFilterNames()
          Obtain a set of the names of all filters defined on this SessionFactory.
 FilterDefinition getFilterDefinition(String filterName)
          Obtain the definition of a filter by name.
 Statistics getStatistics()
          Retrieve the statistics fopr this factory.
 TypeHelper getTypeHelper()
          Retrieve this factory's TypeHelper
 boolean isClosed()
          Is this factory already closed?
 Session openSession()
          Open a Session.
 Session openSession(Connection connection)
          Open a Session, utilizing the specfied JDBC Connection.
 Session openSession(Connection connection, Interceptor interceptor)
          Open a Session, utilizing the specfied JDBC Connection and specified Interceptor.
 Session openSession(Interceptor interceptor)
          Open a Session, utilizing the specified Interceptor.
 StatelessSession openStatelessSession()
          Open a new stateless session.
 StatelessSession openStatelessSession(Connection connection)
          Open a new stateless session, utilizing the specified JDBC Connection.
 
Methods inherited from interface javax.naming.Referenceable
getReference
 

Method Detail

openSession

Session openSession()
                    throws HibernateException
Open a Session.

JDBC connection(s will be obtained from the configured ConnectionProvider as needed to perform requested work.

Returns:
The created session.
Throws:
HibernateException - Indicates a peroblem opening the session; pretty rare here.

openSession

Session openSession(Interceptor interceptor)
                    throws HibernateException
Open a Session, utilizing the specified Interceptor.

JDBC connection(s will be obtained from the configured ConnectionProvider as needed to perform requested work.

Parameters:
interceptor - a session-scoped interceptor
Returns:
The created session.
Throws:
HibernateException - Indicates a peroblem opening the session; pretty rare here.

openSession

Session openSession(Connection connection)
Open a Session, utilizing the specfied JDBC Connection.

Note that the second-level cache will be disabled if you supply a JDBC connection. Hibernate will not be able to track any statements you might have executed in the same transaction. Consider implementing your own ConnectionProvider instead as a highly recommended alternative.

Parameters:
connection - a connection provided by the application.
Returns:
The created session.

openSession

Session openSession(Connection connection,
                    Interceptor interceptor)
Open a Session, utilizing the specfied JDBC Connection and specified Interceptor.

Note that the second-level cache will be disabled if you supply a JDBC connection. Hibernate will not be able to track any statements you might have executed in the same transaction. Consider implementing your own ConnectionProvider instead as a highly recommended alternative.

Parameters:
connection - a connection provided by the application.
interceptor - a session-scoped interceptor
Returns:
The created session.

getCurrentSession

Session getCurrentSession()
                          throws HibernateException
Obtains the current session. The definition of what exactly "current" means controlled by the CurrentSessionContext impl configured for use.

Note that for backwards compatibility, if a CurrentSessionContext is not configured but a JTA TransactionManagerLookup is configured this will default to the JTASessionContext impl.

Returns:
The current session.
Throws:
HibernateException - Indicates an issue locating a suitable current session.

openStatelessSession

StatelessSession openStatelessSession()
Open a new stateless session.

Returns:
The created stateless session.

openStatelessSession

StatelessSession openStatelessSession(Connection connection)
Open a new stateless session, utilizing the specified JDBC Connection.

Parameters:
connection - Connection provided by the application.
Returns:
The created stateless session.

getClassMetadata

ClassMetadata getClassMetadata(Class entityClass)
Retrieve the ClassMetadata associated with the given entity class.

Parameters:
entityClass - The entity class
Returns:
The metadata associated with the given entity; may be null if no such entity was mapped.
Throws:
HibernateException - Generally null is returned instead of throwing.

getClassMetadata

ClassMetadata getClassMetadata(String entityName)
Retrieve the ClassMetadata associated with the given entity class.

Parameters:
entityName - The entity class
Returns:
The metadata associated with the given entity; may be null if no such entity was mapped.
Throws:
HibernateException - Generally null is returned instead of throwing.
Since:
3.0

getCollectionMetadata

CollectionMetadata getCollectionMetadata(String roleName)
Get the CollectionMetadata associated with the named collection role.

Parameters:
roleName - The collection role (in form [owning-entity-name].[collection-property-name]).
Returns:
The metadata associated with the given collection; may be null if no such collection was mapped.
Throws:
HibernateException - Generally null is returned instead of throwing.

getAllClassMetadata

Map<String,ClassMetadata> getAllClassMetadata()
Retrieve the ClassMetadata for all mapped entities.

Returns:
A map containing all ClassMetadata keyed by the corresponding String entity-name.
Throws:
HibernateException - Generally empty map is returned instead of throwing.
Since:
3.0 changed key from Class to String.

getAllCollectionMetadata

Map getAllCollectionMetadata()
Get the CollectionMetadata for all mapped collections

Returns:
a map from String to CollectionMetadata
Throws:
HibernateException - Generally empty map is returned instead of throwing.

getStatistics

Statistics getStatistics()
Retrieve the statistics fopr this factory.

Returns:
The statistics.

close

void close()
           throws HibernateException
Destroy this SessionFactory and release all resources (caches, connection pools, etc).

It is the responsibility of the application to ensure that there are no open sessions before calling this method as the impact on those sessions is indeterminate.

No-ops if already closed.

Throws:
HibernateException - Indicates an issue closing the factory.

isClosed

boolean isClosed()
Is this factory already closed?

Returns:
True if this factory is already closed; false otherwise.

getCache

Cache getCache()
Obtain direct access to the underlying cache regions.

Returns:
The direct cache access API.

evict

void evict(Class persistentClass)
           throws HibernateException
Deprecated. Use Cache.evictEntityRegion(Class) accessed through getCache() instead.

Evict all entries from the second-level cache. This method occurs outside of any transaction; it performs an immediate "hard" remove, so does not respect any transaction isolation semantics of the usage strategy. Use with care.

Parameters:
persistentClass - The entity class for which to evict data.
Throws:
HibernateException - Generally will mean that either that 'persisttentClass' did not name a mapped entity or a problem communicating with underlying cache impl.

evict

void evict(Class persistentClass,
           Serializable id)
           throws HibernateException
Deprecated. Use Cache.containsEntity(Class, Serializable) accessed through getCache() instead.

Evict an entry from the second-level cache. This method occurs outside of any transaction; it performs an immediate "hard" remove, so does not respect any transaction isolation semantics of the usage strategy. Use with care.

Parameters:
persistentClass - The entity class for which to evict data.
id - The entity id
Throws:
HibernateException - Generally will mean that either that 'persisttentClass' did not name a mapped entity or a problem communicating with underlying cache impl.

evictEntity

void evictEntity(String entityName)
                 throws HibernateException
Deprecated. Use Cache.evictEntityRegion(String) accessed through getCache() instead.

Evict all entries from the second-level cache. This method occurs outside of any transaction; it performs an immediate "hard" remove, so does not respect any transaction isolation semantics of the usage strategy. Use with care.

Parameters:
entityName - The entity name for which to evict data.
Throws:
HibernateException - Generally will mean that either that 'persisttentClass' did not name a mapped entity or a problem communicating with underlying cache impl.

evictEntity

void evictEntity(String entityName,
                 Serializable id)
                 throws HibernateException
Deprecated. Use Cache.evictEntity(String,Serializable) accessed through getCache() instead.

Evict an entry from the second-level cache. This method occurs outside of any transaction; it performs an immediate "hard" remove, so does not respect any transaction isolation semantics of the usage strategy. Use with care.

Parameters:
entityName - The entity name for which to evict data.
id - The entity id
Throws:
HibernateException - Generally will mean that either that 'persisttentClass' did not name a mapped entity or a problem communicating with underlying cache impl.

evictCollection

void evictCollection(String roleName)
                     throws HibernateException
Deprecated. Use Cache.evictCollectionRegion(String) accessed through getCache() instead.

Evict all entries from the second-level cache. This method occurs outside of any transaction; it performs an immediate "hard" remove, so does not respect any transaction isolation semantics of the usage strategy. Use with care.

Parameters:
roleName - The name of the collection role whose regions should be evicted
Throws:
HibernateException - Generally will mean that either that 'roleName' did not name a mapped collection or a problem communicating with underlying cache impl.

evictCollection

void evictCollection(String roleName,
                     Serializable id)
                     throws HibernateException
Deprecated. Use Cache.evictCollection(String,Serializable) accessed through getCache() instead.

Evict an entry from the second-level cache. This method occurs outside of any transaction; it performs an immediate "hard" remove, so does not respect any transaction isolation semantics of the usage strategy. Use with care.

Parameters:
roleName - The name of the collection role
id - The id of the collection owner
Throws:
HibernateException - Generally will mean that either that 'roleName' did not name a mapped collection or a problem communicating with underlying cache impl.

evictQueries

void evictQueries(String cacheRegion)
                  throws HibernateException
Deprecated. Use Cache.evictQueryRegion(String) accessed through getCache() instead.

Evict any query result sets cached in the named query cache region.

Parameters:
cacheRegion - The named query cache region from which to evict.
Throws:
HibernateException - Since a not-found 'cacheRegion' simply no-ops, this should indicate a problem communicating with underlying cache impl.

evictQueries

void evictQueries()
                  throws HibernateException
Deprecated. Use Cache.evictQueryRegions() accessed through getCache() instead.

Evict any query result sets cached in the default query cache region.

Throws:
HibernateException - Indicate a problem communicating with underlying cache impl.

getDefinedFilterNames

Set getDefinedFilterNames()
Obtain a set of the names of all filters defined on this SessionFactory.

Returns:
The set of filter names.

getFilterDefinition

FilterDefinition getFilterDefinition(String filterName)
                                     throws HibernateException
Obtain the definition of a filter by name.

Parameters:
filterName - The name of the filter for which to obtain the definition.
Returns:
The filter definition.
Throws:
HibernateException - If no filter defined with the given name.

containsFetchProfileDefinition

boolean containsFetchProfileDefinition(String name)
Determine if this session factory contains a fetch profile definition registered under the given name.

Parameters:
name - The name to check
Returns:
True if there is such a fetch profile; false otherwise.

getTypeHelper

TypeHelper getTypeHelper()
Retrieve this factory's TypeHelper

Returns:
The factory's TypeHelper


Copyright © 2001-2010 Red Hat, Inc. All Rights Reserved.