org.hibernate.cfg

Class Configuration

Implemented Interfaces:
Serializable

public class Configuration
extends java.lang.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

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
sqlFunctions
protected Map
sqlResultSetMappings
Map result set name, result set description
protected Map
tableNameBinding
protected Map
tables
protected Map
typeDefs
protected XMLHelper
xmlHelper

Constructor Summary

Configuration()
Configuration(SettingsFactory settingsFactory)

Method Summary

protected void
add(org.dom4j.Document doc)
void
addAuxiliaryDatabaseObject(AuxiliaryDatabaseObject object)
Configuration
addCacheableFile(File xmlFile)
Add a cached mapping file.
Configuration
addCacheableFile(String xmlFile)
Add a cacheable mapping file.
Configuration
addClass(Class persistentClass)
Read a mapping as an application resouurce using the convention that a class named foo.bar.Foo is mapped by a file foo/bar/Foo.hbm.xml which can be resolved as a classpath resource.
Configuration
addDirectory(File dir)
Read all mapping documents from a directory tree.
Configuration
addDocument(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 java.io.InputStream.
Configuration
addJar(File jar)
Read all mappings from a jar file

Assumes that any file named *.hbm.xml is a mapping document.

Configuration
addProperties(Properties extraProperties)
Set the given properties
Configuration
addResource(String resourceName)
Read mappings as a application resourceName (i.e.
Configuration
addResource(String resourceName, ClassLoader classLoader)
Read mappings as a application resource (i.e.
void
addSqlFunction(String functionName, SQLFunction function)
Configuration
addURL(URL url)
Read mappings from a URL
Configuration
addXML(String xml)
Read mappings from a String
Mapping
buildMapping()
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(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(InputStream stream, String resourceName)
Use the mappings and properties specified in the given application resource.
protected Configuration
doConfigure(org.dom4j.Document doc)
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 entityName)
Get the mapping for a particular entity
Iterator
getClassMappings()
Iterate the entity 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.
EntityNotFoundDelegate
getEntityNotFoundDelegate()
Retrieve the user-supplied delegate to handle non-existent entity scenarios.
EntityResolver
getEntityResolver()
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
SessionFactoryObserver
getSessionFactoryObserver()
Map
getSqlFunctions()
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(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
setEntityNotFoundDelegate(EntityNotFoundDelegate entityNotFoundDelegate)
Specify a user-supplied delegate to be used to handle scenarios where an entity could not be located by specified id.
void
setEntityResolver(EntityResolver entityResolver)
Set a custom entity resolver.
Configuration
setInterceptor(Interceptor interceptor)
Configure an Interceptor
void
setListener(String type, Object listener)
void
setListener(String type, String 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
setSessionFactoryObserver(SessionFactoryObserver sessionFactoryObserver)
void
validateSchema(Dialect dialect, DatabaseMetadata databaseMetadata)

Field Details

auxiliaryDatabaseObjects

protected List auxiliaryDatabaseObjects

classes

protected Map classes

collections

protected Map collections

columnNameBindingPerTable

protected Map columnNameBindingPerTable

extendsQueue

protected Map extendsQueue

filterDefinitions

protected Map filterDefinitions

imports

protected Map imports

namedQueries

protected Map namedQueries

namedSqlQueries

protected Map namedSqlQueries

namingStrategy

protected NamingStrategy namingStrategy

propertyReferences

protected List propertyReferences

secondPasses

protected List secondPasses

settingsFactory

protected final SettingsFactory settingsFactory

sqlFunctions

protected Map sqlFunctions

sqlResultSetMappings

protected Map sqlResultSetMappings
Map result set name, result set description

tableNameBinding

protected Map tableNameBinding

tables

protected Map tables

typeDefs

protected Map typeDefs

xmlHelper

protected XMLHelper xmlHelper

Constructor Details

Configuration

public Configuration()

Configuration

protected Configuration(SettingsFactory settingsFactory)

Method Details

add

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

addAuxiliaryDatabaseObject

public void addAuxiliaryDatabaseObject(AuxiliaryDatabaseObject object)

addCacheableFile

public Configuration addCacheableFile(File xmlFile)
            throws MappingException
Add a cached mapping file. A cached file is a serialized representation of the DOM structure of a particular mapping. It is saved from a previous call as a file with the name xmlFile + ".bin" where xmlFile is the name of the original mapping file. 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.
Parameters:
xmlFile - The cacheable mapping file to be added.
Returns:
this (for method chaining purposes)
Throws:
MappingException - Indicates problems reading the cached file or processing the non-cached file.

addCacheableFile

public Configuration addCacheableFile(String xmlFile)
            throws MappingException
Add a cacheable mapping file.
Parameters:
xmlFile - The name of the file to be added. This must be in a form useable to simply construct a java.io.File instance.
Returns:
this (for method chaining purposes)
Throws:
MappingException - Indicates problems reading the cached file or processing the non-cached file.
See Also:
addCacheableFile(java.io.File)

addClass

public Configuration addClass(Class persistentClass)
            throws MappingException
Read a mapping as an application resouurce using the convention that a class named foo.bar.Foo is mapped by a file foo/bar/Foo.hbm.xml which can be resolved as a classpath resource.
Parameters:
persistentClass - The mapped class
Returns:
this (for method chaining purposes)
Throws:
MappingException - Indicates problems locating the resource or processing the contained mapping document.

addDirectory

public Configuration addDirectory(File dir)
            throws MappingException
Read all mapping documents from a directory tree.

Assumes that any file named *.hbm.xml is a mapping document.

Parameters:
dir - The directory
Returns:
this (for method chaining purposes)
Throws:
MappingException - Indicates problems reading the jar file or processing the contained mapping documents.

addDocument

public Configuration addDocument(Document doc)
            throws MappingException
Read mappings from a DOM Document
Parameters:
doc - The DOM document
Returns:
this (for method chaining purposes)
Throws:
MappingException - Indicates problems reading the DOM or processing the mapping document.

addFile

public Configuration addFile(File xmlFile)
            throws MappingException
Read mappings from a particular XML file
Parameters:
xmlFile - a path to a file
Returns:
this (for method chaining purposes)
Throws:
MappingException - Indicates inability to locate or parse the specified mapping file.

addFile

public Configuration addFile(String xmlFile)
            throws MappingException
Read mappings from a particular XML file
Parameters:
xmlFile - a path to a file
Returns:
this (for method chaining purposes)
Throws:
MappingException - Indicates inability to locate or parse the specified mapping file.
See Also:
addFile(java.io.File)

addFilterDefinition

public void addFilterDefinition(FilterDefinition definition)

addInputStream

public Configuration addInputStream(InputStream xmlInputStream)
            throws MappingException
Read mappings from an java.io.InputStream.
Parameters:
xmlInputStream - The input stream containing a DOM.
Returns:
this (for method chaining purposes)
Throws:
MappingException - Indicates problems reading the stream, or processing the contained mapping document.

addJar

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

Assumes that any file named *.hbm.xml is a mapping document.

Parameters:
jar - a jar file
Returns:
this (for method chaining purposes)
Throws:
MappingException - Indicates problems reading the jar file or processing the contained mapping documents.

addProperties

public Configuration addProperties(Properties extraProperties)
Set the given properties

addResource

public Configuration addResource(String resourceName)
            throws MappingException
Read mappings as a application resourceName (i.e. classpath lookup) trying different classloaders.
Parameters:
resourceName - The resource name
Returns:
this (for method chaining purposes)
Throws:
MappingException - Indicates problems locating the resource or processing the contained mapping document.

addResource

public Configuration addResource(String resourceName,
                                 ClassLoader classLoader)
            throws MappingException
Read mappings as a application resource (i.e. classpath lookup).
Parameters:
resourceName - The resource name
classLoader - The class loader to use.
Returns:
this (for method chaining purposes)
Throws:
MappingException - Indicates problems locating the resource or processing the contained mapping document.

addSqlFunction

public void addSqlFunction(String functionName,
                           SQLFunction function)

addURL

public Configuration addURL(URL url)
            throws MappingException
Read mappings from a URL
Parameters:
url - The url for the mapping document to be read.
Returns:
this (for method chaining purposes)
Throws:
MappingException - Indicates problems reading the URL or processing the mapping document.

addXML

public Configuration addXML(String xml)
            throws MappingException
Read mappings from a String
Parameters:
xml - an XML string
Returns:
this (for method chaining purposes)
Throws:
MappingException - Indicates problems parsing the given XML string

buildMapping

public Mapping buildMapping()

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().

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

buildSettings

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

buildSettings

public Settings buildSettings(Properties props)
            throws HibernateException

configure

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

configure

public Configuration configure(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.

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

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


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

createMappings

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

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

doConfigure

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

findPossibleExtends

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

generateDropSchemaScript

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

generateSchemaCreationScript

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

generateSchemaUpdateScript

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

getClassMapping

public PersistentClass getClassMapping(String entityName)
Get the mapping for a particular entity
Parameters:
entityName - An entity name.
Returns:
the entity mapping information

getClassMappings

public Iterator getClassMappings()
Iterate the entity mappings
Returns:
Iterator of the entity mappings currently contained in the configuration.

getCollectionMapping

public Collection getCollectionMapping(String role)
Get the mapping for a particular collection role
Parameters:
role - a collection role
Returns:
The collection mapping information

getCollectionMappings

public Iterator getCollectionMappings()
Iterate the collection mappings
Returns:
Iterator of the collection mappings currently contained in the configuration.

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.

getEntityNotFoundDelegate

public EntityNotFoundDelegate getEntityNotFoundDelegate()
Retrieve the user-supplied delegate to handle non-existent entity scenarios. May be null.
Returns:
The user-supplied delegate

getEntityResolver

public EntityResolver getEntityResolver()

getEventListeners

public EventListeners getEventListeners()

getFilterDefinitions

public Map getFilterDefinitions()

getImports

public Map getImports()
Get the query language imports
Returns:
a mapping from "import" names to fully qualified class names

getInterceptor

public Interceptor getInterceptor()
Return the configured Interceptor

getNamedQueries

public Map getNamedQueries()
Get the named queries

getNamedSQLQueries

public Map getNamedSQLQueries()

getNamingStrategy

public NamingStrategy getNamingStrategy()
Returns:
the NamingStrategy.

getProperties

public Properties getProperties()
Get all properties

getProperty

public String getProperty(String propertyName)
Get a property

getSessionFactoryObserver

public SessionFactoryObserver getSessionFactoryObserver()

getSqlFunctions

public Map getSqlFunctions()

getSqlResultSetMappings

public Map getSqlResultSetMappings()

getTableMappings

public Iterator getTableMappings()
Iterate the table mappings
Returns:
Iterator of the table mappings currently contained in the configuration.

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

parseMappingElement

protected void parseMappingElement(Element subelement,
                                   String name)

reset

protected void reset()

secondPassCompile

protected void secondPassCompile()
            throws MappingException

secondPassCompileForeignKeys

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

setCacheConcurrencyStrategy

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

setCacheConcurrencyStrategy

public void setCacheConcurrencyStrategy(String clazz,
                                        String concurrencyStrategy,
                                        String region)
            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

setCollectionCacheConcurrencyStrategy

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

setEntityNotFoundDelegate

public void setEntityNotFoundDelegate(EntityNotFoundDelegate entityNotFoundDelegate)
Specify a user-supplied delegate to be used to handle scenarios where an entity could not be located by specified id. This is mainly intended for EJB3 implementations to be able to control how proxy initialization errors should be handled...
Parameters:
entityNotFoundDelegate - The delegate to use

setEntityResolver

public void setEntityResolver(EntityResolver entityResolver)
Parameters:
entityResolver - entity resolver to use

setInterceptor

public Configuration setInterceptor(Interceptor interceptor)
Configure an Interceptor

setListener

public void setListener(String type,
                        Object listener)

setListener

public void setListener(String type,
                        String listener)

setListeners

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

setListeners

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

setNamingStrategy

public Configuration setNamingStrategy(NamingStrategy namingStrategy)
Set a custom naming strategy
Parameters:
namingStrategy - the NamingStrategy to set

setProperties

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

setProperty

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

setSessionFactoryObserver

public void setSessionFactoryObserver(SessionFactoryObserver sessionFactoryObserver)

validateSchema

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