org.hibernate.cfg
Class Configuration

java.lang.Object
  extended byorg.hibernate.cfg.Configuration
All Implemented Interfaces:
Serializable

public class Configuration
extends Object
implements Serializable

An instance of Configuration allows the application to specify properties and mapping documents to be used when creating a SessionFactory. Usually an application will create a single Configuration, build a single instance of SessionFactory and then instantiate Sessions in threads servicing client requests. The Configuration is meant only as an initialization-time object. SessionFactorys are immutable and do not retain any association back to the Configuration.

A new Configuration will use the properties specified in hibernate.properties by default.

Author:
Gavin King
See Also:
SessionFactory, Serialized Form

Field Summary
protected  List auxiliaryDatabaseObjects
           
protected  Map classes
           
protected  Map collections
           
protected  Map columnNameBindingPerTable
           
protected  Map extendsQueue
           
protected  Map filterDefinitions
           
protected  Map imports
           
protected  Map namedQueries
           
protected  Map namedSqlQueries
           
protected  NamingStrategy namingStrategy
           
protected  List propertyReferences
           
protected  List secondPasses
           
protected  SettingsFactory settingsFactory
           
protected  Map sqlResultSetMappings
          Map result set name, result set description
protected  Map tableNameBinding
           
protected  Map tables
           
protected  Map typeDefs
           
 
Constructor Summary
  Configuration()
           
protected Configuration(SettingsFactory settingsFactory)
           
 
Method Summary
protected  void add(org.dom4j.Document doc)
           
 void addAuxiliaryDatabaseObject(AuxiliaryDatabaseObject object)
           
 Configuration addCacheableFile(File xmlFile)
          If a cached xmlFile + ".bin" exists and is newer than xmlFile the ".bin" file will be read directly.
 Configuration addCacheableFile(String xmlFile)
           
 Configuration addClass(Class persistentClass)
          Read a mapping from an application resource, using a convention.
 Configuration addDirectory(File dir)
          Read all mapping documents from a directory tree.
 Configuration addDocument(org.w3c.dom.Document doc)
          Read mappings from a DOM Document
 Configuration addFile(File xmlFile)
          Read mappings from a particular XML file
 Configuration addFile(String xmlFile)
          Read mappings from a particular XML file
 void addFilterDefinition(FilterDefinition definition)
           
 Configuration addInputStream(InputStream xmlInputStream)
          Read mappings from an InputStream
 Configuration addJar(File jar)
          Read all mappings from a jar file
 Configuration addProperties(Properties extraProperties)
          Set the given properties
 Configuration addResource(String path)
          Read mappings from an application resource trying different classloaders.
 Configuration addResource(String path, ClassLoader classLoader)
          Read mappings from an application resource
 Configuration addURL(URL url)
          Read mappings from a URL
 Configuration addXML(String xml)
          Read mappings from a String
 void buildMappings()
          Call this to ensure the mappings are fully compiled/built.
 SessionFactory buildSessionFactory()
          Instantiate a new SessionFactory, using the properties and mappings in this configuration.
 Settings buildSettings()
          Create an object-oriented view of the configuration properties
 Settings buildSettings(Properties props)
           
 Configuration configure()
          Use the mappings and properties specified in an application resource named hibernate.cfg.xml.
 Configuration configure(org.w3c.dom.Document document)
          Use the mappings and properties specified in the given XML document.
 Configuration configure(File configFile)
          Use the mappings and properties specified in the given application file.
 Configuration configure(String resource)
          Use the mappings and properties specified in the given application resource.
 Configuration configure(URL url)
          Use the mappings and properties specified in the given document.
 Mappings createMappings()
          Create a new Mappings to add class and collection mappings to.
protected  Configuration doConfigure(org.dom4j.Document doc)
           
protected  Configuration doConfigure(InputStream stream, String resourceName)
          Use the mappings and properties specified in the given application resource.
protected  org.dom4j.Document findPossibleExtends()
          Find the first possible element in the queue of extends.
 String[] generateDropSchemaScript(Dialect dialect)
          Generate DDL for dropping tables
 String[] generateSchemaCreationScript(Dialect dialect)
          Generate DDL for creating tables
 String[] generateSchemaUpdateScript(Dialect dialect, DatabaseMetadata databaseMetadata)
          Generate DDL for altering tables
 PersistentClass getClassMapping(String persistentClass)
          Get the mapping for a particular class
 Iterator getClassMappings()
          Iterate the class mappings
 Collection getCollectionMapping(String role)
          Get the mapping for a particular collection role
 Iterator getCollectionMappings()
          Iterate the collection mappings
protected  InputStream getConfigurationInputStream(String resource)
          Get the configuration file as an InputStream.
 EventListeners getEventListeners()
           
 Map getFilterDefinitions()
           
 Map getImports()
          Get the query language imports
 Interceptor getInterceptor()
          Return the configured Interceptor
 Map getNamedQueries()
          Get the named queries
 Map getNamedSQLQueries()
           
 NamingStrategy getNamingStrategy()
           
 Properties getProperties()
          Get all properties
 String getProperty(String propertyName)
          Get a property
 Map getSqlResultSetMappings()
           
 Iterator getTableMappings()
          Iterate the table mappings
 Configuration mergeProperties(Properties properties)
          Adds the incoming properties to the internap properties structure, as long as the internal structure does not already contain an entry for the given key.
protected  void parseMappingElement(org.dom4j.Element subelement, String name)
           
protected  void reset()
           
protected  void secondPassCompile()
           
protected  void secondPassCompileForeignKeys(Table table, Set done)
           
 Configuration setCacheConcurrencyStrategy(String clazz, String concurrencyStrategy)
          Set up a cache for an entity class
 void setCacheConcurrencyStrategy(String clazz, String concurrencyStrategy, String region)
           
 Configuration setCollectionCacheConcurrencyStrategy(String collectionRole, String concurrencyStrategy)
          Set up a cache for a collection role
 void setCollectionCacheConcurrencyStrategy(String collectionRole, String concurrencyStrategy, String region)
           
 void setEntityResolver(org.xml.sax.EntityResolver entityResolver)
          Set a custom entity resolver.
 Configuration setInterceptor(Interceptor interceptor)
          Configure an Interceptor
 void setListener(String type, Object listener)
           
 void setListeners(String type, Object[] listeners)
           
 void setListeners(String type, String[] listenerClasses)
           
 Configuration setNamingStrategy(NamingStrategy namingStrategy)
          Set a custom naming strategy
 Configuration setProperties(Properties properties)
          Specify a completely new set of properties
 Configuration setProperty(String propertyName, String value)
          Set a property
 void validateSchema(Dialect dialect, DatabaseMetadata databaseMetadata)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

classes

protected Map classes

imports

protected Map imports

collections

protected Map collections

tables

protected Map tables

auxiliaryDatabaseObjects

protected List auxiliaryDatabaseObjects

namedQueries

protected Map namedQueries

namedSqlQueries

protected Map namedSqlQueries

sqlResultSetMappings

protected Map sqlResultSetMappings
Map result set name, result set description


filterDefinitions

protected Map filterDefinitions

secondPasses

protected List secondPasses

propertyReferences

protected List propertyReferences

extendsQueue

protected Map extendsQueue

tableNameBinding

protected Map tableNameBinding

columnNameBindingPerTable

protected Map columnNameBindingPerTable

typeDefs

protected transient Map typeDefs

namingStrategy

protected NamingStrategy namingStrategy

settingsFactory

protected final SettingsFactory settingsFactory
Constructor Detail

Configuration

protected Configuration(SettingsFactory settingsFactory)

Configuration

public Configuration()
Method Detail

reset

protected void reset()

getClassMappings

public Iterator getClassMappings()
Iterate the class mappings


getCollectionMappings

public Iterator getCollectionMappings()
Iterate the collection mappings


getTableMappings

public Iterator getTableMappings()
Iterate the table mappings


getClassMapping

public PersistentClass getClassMapping(String persistentClass)
Get the mapping for a particular class


getCollectionMapping

public Collection getCollectionMapping(String role)
Get the mapping for a particular collection role

Parameters:
role - a collection role
Returns:
Collection

setEntityResolver

public void setEntityResolver(org.xml.sax.EntityResolver entityResolver)
Set a custom entity resolver. This entity resolver must be set before addXXX(misc) call. Default value is DTDEntityResolver

Parameters:
entityResolver - entity resolver to use

addFile

public Configuration addFile(String xmlFile)
                      throws MappingException
Read mappings from a particular XML file

Parameters:
xmlFile - a path to a file
Throws:
MappingException

addFile

public Configuration addFile(File xmlFile)
                      throws MappingException
Read mappings from a particular XML file

Parameters:
xmlFile - a path to a file
Throws:
MappingException

addCacheableFile

public Configuration addCacheableFile(File xmlFile)
                               throws MappingException
If a cached xmlFile + ".bin" exists and is newer than xmlFile the ".bin" file will be read directly. Otherwise xmlFile is read and then serialized to xmlFile + ".bin" for use the next time.

Throws:
MappingException

addCacheableFile

public Configuration addCacheableFile(String xmlFile)
                               throws MappingException
Throws:
MappingException

addXML

public Configuration addXML(String xml)
                     throws MappingException
Read mappings from a String

Parameters:
xml - an XML string
Throws:
MappingException

addURL

public Configuration addURL(URL url)
                     throws MappingException
Read mappings from a URL

Parameters:
url -
Throws:
MappingException

addDocument

public Configuration addDocument(org.w3c.dom.Document doc)
                          throws MappingException
Read mappings from a DOM Document

Parameters:
doc - a DOM document
Throws:
MappingException

add

protected void add(org.dom4j.Document doc)
            throws MappingException
Throws:
MappingException

createMappings

public Mappings createMappings()
Create a new Mappings to add class and collection mappings to.


addInputStream

public Configuration addInputStream(InputStream xmlInputStream)
                             throws MappingException
Read mappings from an InputStream

Parameters:
xmlInputStream - an InputStream containing XML
Throws:
MappingException

addResource

public Configuration addResource(String path,
                                 ClassLoader classLoader)
                          throws MappingException
Read mappings from an application resource

Parameters:
path - a resource
classLoader - a ClassLoader to use
Throws:
MappingException

addResource

public Configuration addResource(String path)
                          throws MappingException
Read mappings from an application resource trying different classloaders. This method will try to load the resource first from the thread context classloader and then from the classloader that loaded Hibernate.

Throws:
MappingException

addClass

public Configuration addClass(Class persistentClass)
                       throws MappingException
Read a mapping from an application resource, using a convention. The class foo.bar.Foo is mapped by the file foo/bar/Foo.hbm.xml.

Parameters:
persistentClass - the mapped class
Throws:
MappingException

addJar

public Configuration addJar(File jar)
                     throws MappingException
Read all mappings from a jar file

Parameters:
jar - a jar file
Throws:
MappingException

addDirectory

public Configuration addDirectory(File dir)
                           throws MappingException
Read all mapping documents from a directory tree. Assume that any file named *.hbm.xml is a mapping document.

Parameters:
dir - a directory
Throws:
MappingException

generateDropSchemaScript

public String[] generateDropSchemaScript(Dialect dialect)
                                  throws HibernateException
Generate DDL for dropping tables

Throws:
HibernateException
See Also:
SchemaExport

generateSchemaCreationScript

public String[] generateSchemaCreationScript(Dialect dialect)
                                      throws HibernateException
Generate DDL for creating tables

Throws:
HibernateException
See Also:
SchemaExport

generateSchemaUpdateScript

public String[] generateSchemaUpdateScript(Dialect dialect,
                                           DatabaseMetadata databaseMetadata)
                                    throws HibernateException
Generate DDL for altering tables

Throws:
HibernateException
See Also:
SchemaUpdate

validateSchema

public void validateSchema(Dialect dialect,
                           DatabaseMetadata databaseMetadata)
                    throws HibernateException
Throws:
HibernateException

buildMappings

public void buildMappings()
Call this to ensure the mappings are fully compiled/built. Usefull to ensure getting access to all information in the metamodel when calling e.g. getClassMappings().


secondPassCompile

protected void secondPassCompile()
                          throws MappingException
Throws:
MappingException

findPossibleExtends

protected org.dom4j.Document findPossibleExtends()
Find the first possible element in the queue of extends.


secondPassCompileForeignKeys

protected void secondPassCompileForeignKeys(Table table,
                                            Set done)
                                     throws MappingException
Throws:
MappingException

getNamedQueries

public Map getNamedQueries()
Get the named queries


buildSessionFactory

public SessionFactory buildSessionFactory()
                                   throws HibernateException
Instantiate a new SessionFactory, using the properties and mappings in this configuration. The SessionFactory will be immutable, so changes made to the Configuration after building the SessionFactory will not affect it.

Returns:
a new factory for Sessions
Throws:
HibernateException
See Also:
SessionFactory

getInterceptor

public Interceptor getInterceptor()
Return the configured Interceptor


getProperties

public Properties getProperties()
Get all properties


setInterceptor

public Configuration setInterceptor(Interceptor interceptor)
Configure an Interceptor


setProperties

public Configuration setProperties(Properties properties)
Specify a completely new set of properties


addProperties

public Configuration addProperties(Properties extraProperties)
Set the given properties


mergeProperties

public Configuration mergeProperties(Properties properties)
Adds the incoming properties to the internap properties structure, as long as the internal structure does not already contain an entry for the given key.

Parameters:
properties -
Returns:
this

setProperty

public Configuration setProperty(String propertyName,
                                 String value)
Set a property


getProperty

public String getProperty(String propertyName)
Get a property


getConfigurationInputStream

protected InputStream getConfigurationInputStream(String resource)
                                           throws HibernateException
Get the configuration file as an InputStream. Might be overridden by subclasses to allow the configuration to be located by some arbitrary mechanism.

Throws:
HibernateException

configure

public Configuration configure()
                        throws HibernateException
Use the mappings and properties specified in an application resource named hibernate.cfg.xml.

Throws:
HibernateException

configure

public Configuration configure(String resource)
                        throws HibernateException
Use the mappings and properties specified in the given application resource. The format of the resource is defined in hibernate-configuration-3.0.dtd.

The resource is found via getConfigurationInputStream(resource).

Throws:
HibernateException

configure

public Configuration configure(URL url)
                        throws HibernateException
Use the mappings and properties specified in the given document. The format of the document is defined in hibernate-configuration-3.0.dtd.

Parameters:
url - URL from which you wish to load the configuration
Returns:
A configuration configured via the file
Throws:
HibernateException

configure

public Configuration configure(File configFile)
                        throws HibernateException
Use the mappings and properties specified in the given application file. The format of the file is defined in hibernate-configuration-3.0.dtd.

Parameters:
configFile - File from which you wish to load the configuration
Returns:
A configuration configured via the file
Throws:
HibernateException

doConfigure

protected Configuration doConfigure(InputStream stream,
                                    String resourceName)
                             throws HibernateException
Use the mappings and properties specified in the given application resource. The format of the resource is defined in hibernate-configuration-3.0.dtd.

Parameters:
stream - Inputstream to be read from
resourceName - The name to use in warning/error messages
Returns:
A configuration configured via the stream
Throws:
HibernateException

configure

public Configuration configure(org.w3c.dom.Document document)
                        throws HibernateException
Use the mappings and properties specified in the given XML document. The format of the file is defined in hibernate-configuration-3.0.dtd.

Parameters:
document - an XML document from which you wish to load the configuration
Returns:
A configuration configured via the Document
Throws:
HibernateException - if there is problem in accessing the file.

doConfigure

protected Configuration doConfigure(org.dom4j.Document doc)
                             throws HibernateException
Throws:
HibernateException

parseMappingElement

protected void parseMappingElement(org.dom4j.Element subelement,
                                   String name)

setListeners

public void setListeners(String type,
                         String[] listenerClasses)

setListener

public void setListener(String type,
                        Object listener)

setListeners

public void setListeners(String type,
                         Object[] listeners)

getEventListeners

public EventListeners getEventListeners()

setCacheConcurrencyStrategy

public Configuration setCacheConcurrencyStrategy(String clazz,
                                                 String concurrencyStrategy)
                                          throws MappingException
Set up a cache for an entity class

Parameters:
clazz -
concurrencyStrategy -
Returns:
Configuration
Throws:
MappingException

setCacheConcurrencyStrategy

public void setCacheConcurrencyStrategy(String clazz,
                                        String concurrencyStrategy,
                                        String region)
                                 throws MappingException
Throws:
MappingException

setCollectionCacheConcurrencyStrategy

public Configuration setCollectionCacheConcurrencyStrategy(String collectionRole,
                                                           String concurrencyStrategy)
                                                    throws MappingException
Set up a cache for a collection role

Parameters:
collectionRole -
concurrencyStrategy -
Returns:
Configuration
Throws:
MappingException

setCollectionCacheConcurrencyStrategy

public void setCollectionCacheConcurrencyStrategy(String collectionRole,
                                                  String concurrencyStrategy,
                                                  String region)
                                           throws MappingException
Throws:
MappingException

getImports

public Map getImports()
Get the query language imports

Returns:
a mapping from "import" names to fully qualified class names

buildSettings

public Settings buildSettings()
                       throws HibernateException
Create an object-oriented view of the configuration properties

Throws:
HibernateException

buildSettings

public Settings buildSettings(Properties props)
                       throws HibernateException
Throws:
HibernateException

getNamedSQLQueries

public Map getNamedSQLQueries()

getSqlResultSetMappings

public Map getSqlResultSetMappings()

getNamingStrategy

public NamingStrategy getNamingStrategy()
Returns:
the NamingStrategy.

setNamingStrategy

public Configuration setNamingStrategy(NamingStrategy namingStrategy)
Set a custom naming strategy

Parameters:
namingStrategy - the NamingStrategy to set

getFilterDefinitions

public Map getFilterDefinitions()

addFilterDefinition

public void addFilterDefinition(FilterDefinition definition)

addAuxiliaryDatabaseObject

public void addAuxiliaryDatabaseObject(AuxiliaryDatabaseObject object)