org.hibernate.cfg

Class Configuration

java.lang.Object

org.hibernate.cfg.Configuration

public class Configuration
extends Object

Represents one approach for bootstrapping Hibernate. In fact, historically this was the way to bootstrap Hibernate.

The approach here is to define all configuration and mapping sources in one API and to then build the SessionFactory in one-shot. The configuration and mapping sources defined here are just held here until the SessionFactory is built. This is an important distinction from the legacy behavior of this class, where we would try to incrementally build the mappings from sources as they were added. The ramification of this change in behavior is that users can add configuration and mapping sources here, but they can no longer query the in-flight state of mappings (PersistentClass, Collection, etc) here.

Note: Internally this class uses the new bootstrapping approach when asked to build the SessionFactory.

Author:

Gavin King, Steve Ebersole

See Also:

SessionFactory

Field Summary

Fields

Modifier and Type	Field and Description
static String	ARTEFACT_PROCESSING_ORDER

Constructor Summary

Constructors

Constructor and Description
Configuration()
Configuration(BootstrapServiceRegistry serviceRegistry)
Configuration(MetadataSources metadataSources)

Method Summary

Modifier and Type	Method and Description
void	add(XmlDocument metadataXml) Deprecated. No longer supported.
Configuration	addAnnotatedClass(Class annotatedClass) Read metadata from the annotations associated with this class.
void	addAttributeConverter(AttributeConverter attributeConverter) Adds the AttributeConverter instance to this Configuration.
void	addAttributeConverter(AttributeConverter attributeConverter, boolean autoApply) Adds the AttributeConverter instance to this Configuration.
void	addAttributeConverter(AttributeConverterDefinition definition)
void	addAttributeConverter(Class<? extends AttributeConverter> attributeConverterClass) Adds the AttributeConverter Class to this Configuration.
void	addAttributeConverter(Class<? extends AttributeConverter> attributeConverterClass, boolean autoApply) Adds the AttributeConverter Class to this Configuration.
void	addAuxiliaryDatabaseObject(AuxiliaryDatabaseObject object)
Configuration	addCacheableFile(File xmlFile) Add a cached mapping file.
Configuration	addCacheableFile(String xmlFile) Add a cacheable mapping file.
Configuration	addCacheableFileStrictly(File xmlFile) INTENDED FOR TESTSUITE USE ONLY! Much like addCacheableFile(File) except that here we will fail immediately if the cache version cannot be found or used for whatever reason
Configuration	addClass(Class persistentClass) Read a mapping as an application resource 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) Deprecated. Use addURL, addResource, addFile, etc. instead
Configuration	addFile(File xmlFile) Read mappings from a particular XML file
Configuration	addFile(String xmlFile) Read mappings from a particular XML file
Configuration	addInputStream(InputStream xmlInputStream) Read mappings from an InputStream.
Configuration	addJar(File jar) Read all mappings from a jar file Assumes that any file named *.hbm.xml is a mapping document.
Configuration	addPackage(String packageName) Read package-level metadata.
Configuration	addProperties(Properties properties) Add the given properties to ours.
Configuration	addResource(String resourceName) Read mappings as a application resourceName (i.e.
Configuration	addResource(String resourceName, ClassLoader classLoader) Deprecated. This form (accepting a ClassLoader) is no longer supported. Instead, add the ClassLoader to the ClassLoaderService on the ServiceRegistry associated with this Configuration
void	addSqlFunction(String functionName, SQLFunction function)
Configuration	addURL(URL url) Read mappings from a URL
Configuration	addXML(String xml) Deprecated. No longer supported
void	buildMappings() Deprecated. Does nothing
SessionFactory	buildSessionFactory() Create a SessionFactory using the properties and mappings in this configuration.
SessionFactory	buildSessionFactory(ServiceRegistry serviceRegistry) Create a SessionFactory using the properties and mappings in this configuration.
Configuration	configure() Use the mappings and properties specified in an application resource named hibernate.cfg.xml.
Configuration	configure(Document document) Deprecated. No longer supported.
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.
CurrentTenantIdentifierResolver	getCurrentTenantIdentifierResolver()
EntityNotFoundDelegate	getEntityNotFoundDelegate() Retrieve the user-supplied delegate to handle non-existent entity scenarios.
EntityTuplizerFactory	getEntityTuplizerFactory()
Interceptor	getInterceptor() Retrieve the configured Interceptor.
Collection<NamedEntityGraphDefinition>	getNamedEntityGraphs()
Map<String,NamedProcedureCallDefinition>	getNamedProcedureCallMap()
Map<String,NamedQueryDefinition>	getNamedQueries()
Map	getNamedSQLQueries()
Properties	getProperties() Get all properties
String	getProperty(String propertyName) Get a property value by name
SessionFactoryObserver	getSessionFactoryObserver()
Map<String,SQLFunction>	getSqlFunctions()
Map	getSqlResultSetMappings()
StandardServiceRegistryBuilder	getStandardServiceRegistryBuilder() Intended for internal testing use only!!!
Configuration	mergeProperties(Properties properties) Adds the incoming properties to the internal properties structure, as long as the internal structure does not already contain an entry for the given key.
Configuration	registerTypeContributor(TypeContributor typeContributor)
Configuration	registerTypeOverride(BasicType type) Allows registration of a type into the type registry.
Configuration	registerTypeOverride(CompositeUserType type, String[] keys)
Configuration	registerTypeOverride(UserType type, String[] keys)
protected void	reset()
void	setCurrentTenantIdentifierResolver(CurrentTenantIdentifierResolver currentTenantIdentifierResolver)
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	setImplicitNamingStrategy(ImplicitNamingStrategy implicitNamingStrategy)
Configuration	setInterceptor(Interceptor interceptor) Set the current Interceptor
void	setPhysicalNamingStrategy(PhysicalNamingStrategy physicalNamingStrategy)
Configuration	setProperties(Properties properties) Specify a completely new set of properties
Configuration	setProperty(String propertyName, String value) Set a property value by name
void	setSessionFactoryObserver(SessionFactoryObserver sessionFactoryObserver)
void	setSharedCacheMode(SharedCacheMode sharedCacheMode) Sets the SharedCacheMode to use.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ARTEFACT_PROCESSING_ORDER

public static final String ARTEFACT_PROCESSING_ORDER

See Also:

Constant Field Values

Constructor Detail

Configuration

public Configuration()

Configuration

public Configuration(BootstrapServiceRegistry serviceRegistry)

Configuration

public Configuration(MetadataSources metadataSources)

Method Detail

reset

protected void reset()

getProperties

public Properties getProperties()

Get all properties

Returns:

all properties

setProperties

public Configuration setProperties(Properties properties)

Specify a completely new set of properties

Parameters:

properties - The new set of properties

Returns:

this for method chaining

getProperty

public String getProperty(String propertyName)

Get a property value by name

Parameters:

propertyName - The name of the property

Returns:

The value currently associated with that property name; may be null.

setProperty

public Configuration setProperty(String propertyName,
                                 String value)

Set a property value by name

Parameters:

propertyName - The name of the property to set

value - The new property value

Returns:

this for method chaining

addProperties

public Configuration addProperties(Properties properties)

Add the given properties to ours.

Parameters:

properties - The properties to add.

Returns:

this for method chaining

setImplicitNamingStrategy

public void setImplicitNamingStrategy(ImplicitNamingStrategy implicitNamingStrategy)

setPhysicalNamingStrategy

public void setPhysicalNamingStrategy(PhysicalNamingStrategy physicalNamingStrategy)

configure

public Configuration configure()
                        throws HibernateException

Use the mappings and properties specified in an application resource named hibernate.cfg.xml.

Returns:

this for method chaining

Throws:

HibernateException - Generally indicates we cannot find hibernate.cfg.xml

See Also:

configure(String)

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.

Parameters:

resource - The resource to use

Returns:

this for method chaining

Throws:

HibernateException - Generally indicates we cannot find the named resource

getStandardServiceRegistryBuilder

public StandardServiceRegistryBuilder getStandardServiceRegistryBuilder()

Intended for internal testing use only!!!

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:

this for method chaining

Throws:

HibernateException - Generally indicates a problem access the url

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:

this for method chaining

Throws:

HibernateException - Generally indicates a problem access the file

configure

@Deprecated
public Configuration configure(Document document)
                                    throws HibernateException

Deprecated. No longer supported.

Throws:

HibernateException

registerTypeContributor

public Configuration registerTypeContributor(TypeContributor typeContributor)

registerTypeOverride

public Configuration registerTypeOverride(BasicType type)

Allows registration of a type into the type registry. The phrase 'override' in the method name simply reminds that registration *potentially* replaces a previously registered type .

Parameters:

type - The type to register.

registerTypeOverride

public Configuration registerTypeOverride(UserType type,
                                          String[] keys)

registerTypeOverride

public Configuration registerTypeOverride(CompositeUserType type,
                                          String[] keys)

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)

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 the specified mapping file.

add

@Deprecated
public void add(XmlDocument metadataXml)

Deprecated. No longer supported.

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.

addCacheableFileStrictly

public Configuration addCacheableFileStrictly(File xmlFile)
                                       throws SerializationException,
                                              FileNotFoundException

INTENDED FOR TESTSUITE USE ONLY!

Much like addCacheableFile(File) except that here we will fail immediately if the cache version cannot be found or used for whatever reason

Parameters:

xmlFile - The xml file, not the bin!

Returns:

The dom "deserialized" from the cached file.

Throws:

SerializationException - Indicates a problem deserializing the cached dom tree

FileNotFoundException - Indicates that the cached file was not found or was not usable.

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

addXML

@Deprecated
public Configuration addXML(String xml)
                                 throws MappingException

Deprecated. No longer supported

Throws:

MappingException

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.

addDocument

@Deprecated
public Configuration addDocument(Document doc)
                                      throws MappingException

Deprecated. Use addURL, addResource, addFile, etc. instead

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.

addInputStream

public Configuration addInputStream(InputStream xmlInputStream)
                             throws MappingException

Read mappings from an 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.

addResource

@Deprecated
public Configuration addResource(String resourceName,
                                             ClassLoader classLoader)
                                      throws MappingException

Deprecated. This form (accepting a ClassLoader) is no longer supported. Instead, add the ClassLoader to the ClassLoaderService on the ServiceRegistry associated with this Configuration

Throws:

MappingException

addResource

public Configuration addResource(String resourceName)
                          throws MappingException

Read mappings as a application resourceName (i.e. classpath lookup) trying different class loaders.

Parameters:

resourceName - The resource name

Returns:

this (for method chaining purposes)

Throws:

MappingException - Indicates problems locating the resource or processing the contained mapping document.

addClass

public Configuration addClass(Class persistentClass)
                       throws MappingException

Read a mapping as an application resource 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.

addAnnotatedClass

public Configuration addAnnotatedClass(Class annotatedClass)

Read metadata from the annotations associated with this class.

Parameters:

annotatedClass - The class containing annotations

Returns:

this (for method chaining)

addPackage

public Configuration addPackage(String packageName)
                         throws MappingException

Read package-level metadata.

Parameters:

packageName - java package name

Returns:

this (for method chaining)

Throws:

MappingException - in case there is an error in the mapping data

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.

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.

getInterceptor

public Interceptor getInterceptor()

Retrieve the configured Interceptor.

Returns:

The current Interceptor

setInterceptor

public Configuration setInterceptor(Interceptor interceptor)

Set the current Interceptor

Parameters:

interceptor - The Interceptor to use for the built SessionFactory.

Returns:

this for method chaining

getEntityTuplizerFactory

public EntityTuplizerFactory getEntityTuplizerFactory()

getEntityNotFoundDelegate

public EntityNotFoundDelegate getEntityNotFoundDelegate()

Retrieve the user-supplied delegate to handle non-existent entity scenarios. May be null.

Returns:

The user-supplied delegate

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

getSessionFactoryObserver

public SessionFactoryObserver getSessionFactoryObserver()

setSessionFactoryObserver

public void setSessionFactoryObserver(SessionFactoryObserver sessionFactoryObserver)

getCurrentTenantIdentifierResolver

public CurrentTenantIdentifierResolver getCurrentTenantIdentifierResolver()

setCurrentTenantIdentifierResolver

public void setCurrentTenantIdentifierResolver(CurrentTenantIdentifierResolver currentTenantIdentifierResolver)

buildSessionFactory

public SessionFactory buildSessionFactory(ServiceRegistry serviceRegistry)
                                   throws HibernateException

Create a SessionFactory using the properties and mappings in this configuration. The SessionFactory will be immutable, so changes made to this Configuration after building the SessionFactory will not affect it.

Parameters:

serviceRegistry - The registry of services to be used in creating this session factory.

Returns:

The built SessionFactory

Throws:

HibernateException - usually indicates an invalid configuration or invalid mapping information

buildSessionFactory

public SessionFactory buildSessionFactory()
                                   throws HibernateException

Create a SessionFactory using the properties and mappings in this configuration. The SessionFactory will be immutable, so changes made to this Configuration after building the SessionFactory will not affect it.

Returns:

The build SessionFactory

Throws:

HibernateException - usually indicates an invalid configuration or invalid mapping information

getSqlFunctions

public Map<String,SQLFunction> getSqlFunctions()

addSqlFunction

public void addSqlFunction(String functionName,
                           SQLFunction function)

addAuxiliaryDatabaseObject

public void addAuxiliaryDatabaseObject(AuxiliaryDatabaseObject object)

addAttributeConverter

public void addAttributeConverter(Class<? extends AttributeConverter> attributeConverterClass,
                                  boolean autoApply)

Adds the AttributeConverter Class to this Configuration.

Parameters:

attributeConverterClass - The AttributeConverter class.

autoApply - Should the AttributeConverter be auto applied to property types as specified by its "entity attribute" parameterized type?

addAttributeConverter

public void addAttributeConverter(Class<? extends AttributeConverter> attributeConverterClass)

Adds the AttributeConverter Class to this Configuration.

Parameters:

attributeConverterClass - The AttributeConverter class.

addAttributeConverter

public void addAttributeConverter(AttributeConverter attributeConverter)

Adds the AttributeConverter instance to this Configuration. This form is mainly intended for developers to programmatically add their own AttributeConverter instance. HEM, instead, uses the addAttributeConverter(Class, boolean) form

Parameters:

attributeConverter - The AttributeConverter instance.

addAttributeConverter

public void addAttributeConverter(AttributeConverter attributeConverter,
                                  boolean autoApply)

Adds the AttributeConverter instance to this Configuration. This form is mainly intended for developers to programmatically add their own AttributeConverter instance. HEM, instead, uses the addAttributeConverter(Class, boolean) form

Parameters:

attributeConverter - The AttributeConverter instance.

autoApply - Should the AttributeConverter be auto applied to property types as specified by its "entity attribute" parameterized type?

addAttributeConverter

public void addAttributeConverter(AttributeConverterDefinition definition)

setSharedCacheMode

public void setSharedCacheMode(SharedCacheMode sharedCacheMode)

Sets the SharedCacheMode to use. Note that at the moment, only SharedCacheMode.ALL has any effect in terms of hbm.xml binding.

Parameters:

sharedCacheMode - The SharedCacheMode to use

getNamedSQLQueries

public Map getNamedSQLQueries()

getSqlResultSetMappings

public Map getSqlResultSetMappings()

getNamedEntityGraphs

public Collection<NamedEntityGraphDefinition> getNamedEntityGraphs()

getNamedQueries

public Map<String,NamedQueryDefinition> getNamedQueries()

getNamedProcedureCallMap

public Map<String,NamedProcedureCallDefinition> getNamedProcedureCallMap()

buildMappings

@Deprecated
public void buildMappings()

Deprecated. Does nothing

mergeProperties

public Configuration mergeProperties(Properties properties)

Adds the incoming properties to the internal properties structure, as long as the internal structure does not already contain an entry for the given key.

Parameters:

properties - The properties to merge

Returns:

this for method chaining