Class Configuration
- java.lang.Object
-
- org.hibernate.cfg.Configuration
-
public class Configuration extends Object
A convenience API making it easier to bootstrap an instance of Hibernate.An instance of
Configuration
may be obtained simply by instantiation, and may be used to aggregate:- configuration properties from various sources, and
- entity O/R mappings, defined in either annotated classes, or XML mapping documents.
orm.xml
format, or in Hibernate's legacy.hbm.xml
format.Configuration properties are enumerated by
AvailableSettings
.
In addition, there are convenience methods for addingSessionFactory factory = new Configuration() // scan classes for mapping annotations .addAnnotatedClass(Item.class) .addAnnotatedClass(Bid.class) .addAnnotatedClass(User.class) // read package-level annotations of the named package .addPackage("org.hibernate.auction") // set a configuration property .setProperty(AvailableSettings.DATASOURCE, "java:comp/env/jdbc/test") .getSessionFactory();
attribute converters
,type contributors
,entity name resolvers
,SQL function descriptors
, andauxiliary database objects
, for settingnaming strategies
and atenant id resolver
, and more.Finally, an instance of
SessionFactoryBuilder
is obtained by callingbuildSessionFactory()
.Ultimately, this class simply delegates to
MetadataBuilder
andStandardServiceRegistryBuilder
to actually do the hard work of building theSessionFactory
. Programs may directly use the APIs defined underorg.hibernate.boot
, as an alternative to using an instance of this class.- See Also:
SessionFactory
,AvailableSettings
,org.hibernate.boot
-
-
Field Summary
Fields Modifier and Type Field Description static String
ARTEFACT_PROCESSING_ORDER
-
Constructor Summary
Constructors Constructor Description Configuration()
Create a new instance, using a defaultBootstrapServiceRegistry
and a newly instantiatedMetadataSources
.Configuration(MetadataSources metadataSources)
Create a new instance, using the givenMetadataSources
, and aBootstrapServiceRegistry
obtained from theMetadataSources
.Configuration(BootstrapServiceRegistry serviceRegistry)
Create a new instance, using the givenBootstrapServiceRegistry
and a newly instantiatedMetadataSources
.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description Configuration
addAnnotatedClass(Class annotatedClass)
Read metadata from the annotations associated with this class.void
addAttributeConverter(jakarta.persistence.AttributeConverter<?,?> attributeConverter)
Adds anAttributeConverter
instance to this configuration.void
addAttributeConverter(jakarta.persistence.AttributeConverter<?,?> attributeConverter, boolean autoApply)
Adds anAttributeConverter
instance to this configuration.void
addAttributeConverter(Class<? extends jakarta.persistence.AttributeConverter<?,?>> attributeConverterClass)
Adds anAttributeConverter
to this configuration.void
addAttributeConverter(Class<? extends jakarta.persistence.AttributeConverter<?,?>> attributeConverterClass, boolean autoApply)
Adds anAttributeConverter
to this configuration.void
addAttributeConverter(ConverterDescriptor converterDescriptor)
void
addAuxiliaryDatabaseObject(AuxiliaryDatabaseObject object)
Configuration
addCacheableFile(File xmlFile)
Add a cacheable mapping file.Configuration
addCacheableFile(String xmlFile)
Add a cacheable mapping file.Configuration
addCacheableFileStrictly(File xmlFile)
INTENDED FOR TESTSUITE USE ONLY!Configuration
addClass(Class entityClass)
Read a mapping as an application resource using the convention that a class namedfoo.bar.Foo
is mapped by a filefoo/bar/Foo.hbm.xml
which can be resolved as a classpath resource.Configuration
addDirectory(File dir)
Read all.hbm.xml
mapping documents from a directory tree.void
addEntityNameResolver(EntityNameResolver entityNameResolver)
Add anEntityNameResolver
to this configuration.Configuration
addFile(File xmlFile)
Read mappings from a particular XML file.Configuration
addFile(String xmlFile)
Read mappings from a particular XML fileConfiguration
addInputStream(InputStream xmlInputStream)
Read mappings from anInputStream
.Configuration
addJar(File jar)
Read all.hbm.xml
mappings from a.jar
file.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 an application resource name, that is, using a classpath lookup, trying different class loaders in turn.void
addSqlFunction(String functionName, SqmFunctionDescriptor function)
Configuration
addURL(URL url)
Read mappings from aURL
.Configuration
addXmlMapping(Binding<?> binding)
Read mappings that were parsed usinggetXmlMappingBinderAccess()
.SessionFactory
buildSessionFactory()
Create aSessionFactory
using the properties and mappings in this configuration.SessionFactory
buildSessionFactory(ServiceRegistry serviceRegistry)
Create aSessionFactory
using the properties and mappings in this configuration.Configuration
configure()
Use the mappings and properties specified in an application resource namedhibernate.cfg.xml
.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-suppliedEntityNotFoundDelegate
, ornull
if no delegate has been specified.Interceptor
getInterceptor()
Retrieve the configuredInterceptor
.Collection<NamedEntityGraphDefinition>
getNamedEntityGraphs()
Map<String,NamedProcedureCallDefinition>
getNamedProcedureCallMap()
Map<String,NamedHqlQueryDefinition>
getNamedQueries()
Map<String,NamedNativeQueryDefinition>
getNamedSQLQueries()
Properties
getProperties()
Get all propertiesString
getProperty(String propertyName)
Get a property value by nameSessionFactoryObserver
getSessionFactoryObserver()
Map<String,SqmFunctionDescriptor>
getSqlFunctions()
Map<String,NamedResultSetMappingDescriptor>
getSqlResultSetMappings()
StandardServiceRegistryBuilder
getStandardServiceRegistryBuilder()
Intended for internal testing use only!!!XmlMappingBinderAccess
getXmlMappingBinderAccess()
An object capable of parsing XML mapping files that can then be passed toaddXmlMapping(Binding)
.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)
Register a type into the type registry, potentially replacing a previously registered type.Configuration
registerTypeOverride(UserType<?> type, String[] keys)
protected void
reset()
void
setCurrentTenantIdentifierResolver(CurrentTenantIdentifierResolver currentTenantIdentifierResolver)
void
setEntityNotFoundDelegate(EntityNotFoundDelegate entityNotFoundDelegate)
Specify a user-suppliedEntityNotFoundDelegate
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 currentInterceptor
.void
setPhysicalNamingStrategy(PhysicalNamingStrategy physicalNamingStrategy)
Configuration
setProperties(Properties properties)
Specify a completely new set of propertiesConfiguration
setProperty(String propertyName, String value)
Set a property value by namevoid
setSessionFactoryObserver(SessionFactoryObserver sessionFactoryObserver)
void
setSharedCacheMode(jakarta.persistence.SharedCacheMode sharedCacheMode)
Sets theSharedCacheMode
to use.
-
-
-
Field Detail
-
ARTEFACT_PROCESSING_ORDER
public static final String ARTEFACT_PROCESSING_ORDER
- See Also:
- Constant Field Values
-
-
Constructor Detail
-
Configuration
public Configuration()
Create a new instance, using a defaultBootstrapServiceRegistry
and a newly instantiatedMetadataSources
.This is the usual method of obtaining a
Configuration
.
-
Configuration
public Configuration(BootstrapServiceRegistry serviceRegistry)
Create a new instance, using the givenBootstrapServiceRegistry
and a newly instantiatedMetadataSources
.
-
Configuration
public Configuration(MetadataSources metadataSources)
Create a new instance, using the givenMetadataSources
, and aBootstrapServiceRegistry
obtained from theMetadataSources
.
-
-
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 setvalue
- 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 namedhibernate.cfg.xml
.- Returns:
- this for method chaining
- Throws:
HibernateException
- Generally indicates we cannot findhibernate.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 by
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 by
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 by
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
-
registerTypeContributor
public Configuration registerTypeContributor(TypeContributor typeContributor)
-
registerTypeOverride
public Configuration registerTypeOverride(BasicType<?> type)
Register a type into the type registry, potentially replacing a previously registered type.- Parameters:
type
- The type to register.
-
registerTypeOverride
public Configuration registerTypeOverride(UserType<?> 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(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
-
getXmlMappingBinderAccess
public XmlMappingBinderAccess getXmlMappingBinderAccess()
An object capable of parsing XML mapping files that can then be passed toaddXmlMapping(Binding)
.
-
addXmlMapping
public Configuration addXmlMapping(Binding<?> binding)
Read mappings that were parsed usinggetXmlMappingBinderAccess()
.- Parameters:
binding
- the parsed mapping- Returns:
- this (for method chaining purposes)
-
addCacheableFile
public Configuration addCacheableFile(File xmlFile) throws MappingException
Add a cacheable 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
If a cachedxmlFile + ".bin"
wherexmlFile
is the name of the original mapping file.xmlFile + ".bin"
exists and is newer thanxmlFile
, the".bin"
file will be read directly. Otherwise,xmlFile
is read and then serialized toxmlFile + ".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
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
-
addCacheableFile
public Configuration addCacheableFile(String xmlFile) throws MappingException
Add a cacheable mapping file.- Parameters:
xmlFile
- The name of the file to be added, in a form usable to simply construct aFile
instance- Returns:
- this (for method chaining purposes)
- Throws:
MappingException
- Indicates problems reading the cached file or processing the non-cached file- See Also:
addCacheableFile(File)
-
addURL
public Configuration addURL(URL url) throws MappingException
Read mappings from aURL
.- 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.
-
addInputStream
public Configuration addInputStream(InputStream xmlInputStream) throws MappingException
Read mappings from anInputStream
.- 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
public Configuration addResource(String resourceName) throws MappingException
Read mappings as an application resource name, that is, using a classpath lookup, trying different class loaders in turn.- 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 entityClass) throws MappingException
Read a mapping as an application resource using the convention that a class namedfoo.bar.Foo
is mapped by a filefoo/bar/Foo.hbm.xml
which can be resolved as a classpath resource.- Parameters:
entityClass
- 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.hbm.xml
mappings from a.jar
file.Assumes that any file named
*.hbm.xml
is a mapping document. This method does not supportorm.xml
files!- 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.hbm.xml
mapping documents from a directory tree.Assumes that any file named
*.hbm.xml
is a mapping document. This method does not supportorm.xml
files!- 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 configuredInterceptor
.- Returns:
- The current
Interceptor
-
setInterceptor
public Configuration setInterceptor(Interceptor interceptor)
Set the currentInterceptor
.- Parameters:
interceptor
- TheInterceptor
to use- Returns:
- this for method chaining
-
getEntityNotFoundDelegate
public EntityNotFoundDelegate getEntityNotFoundDelegate()
Retrieve the user-suppliedEntityNotFoundDelegate
, ornull
if no delegate has been specified.- Returns:
- The user-supplied delegate
-
setEntityNotFoundDelegate
public void setEntityNotFoundDelegate(EntityNotFoundDelegate entityNotFoundDelegate)
Specify a user-suppliedEntityNotFoundDelegate
to be used to handle scenarios where an entity could not be located by specified id.- 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 aSessionFactory
using the properties and mappings in this configuration. TheSessionFactory
will be immutable, so changes made to thisConfiguration
after building the factory will not affect it.- Parameters:
serviceRegistry
- The registry of services to be used in creating this session factory.- Returns:
- The newly-built
SessionFactory
- Throws:
HibernateException
- usually indicates an invalid configuration or invalid mapping information
-
buildSessionFactory
public SessionFactory buildSessionFactory() throws HibernateException
Create aSessionFactory
using the properties and mappings in this configuration. TheSessionFactory
will be immutable, so changes made to thisConfiguration
after building the factory will not affect it.- Returns:
- The newly-built
SessionFactory
- Throws:
HibernateException
- usually indicates an invalid configuration or invalid mapping information
-
getSqlFunctions
public Map<String,SqmFunctionDescriptor> getSqlFunctions()
-
addSqlFunction
public void addSqlFunction(String functionName, SqmFunctionDescriptor function)
-
addAuxiliaryDatabaseObject
public void addAuxiliaryDatabaseObject(AuxiliaryDatabaseObject object)
-
addAttributeConverter
public void addAttributeConverter(Class<? extends jakarta.persistence.AttributeConverter<?,?>> attributeConverterClass, boolean autoApply)
Adds anAttributeConverter
to this configuration.- Parameters:
attributeConverterClass
- TheAttributeConverter
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 jakarta.persistence.AttributeConverter<?,?>> attributeConverterClass)
Adds anAttributeConverter
to this configuration.- Parameters:
attributeConverterClass
- TheAttributeConverter
class.
-
addAttributeConverter
public void addAttributeConverter(jakarta.persistence.AttributeConverter<?,?> attributeConverter)
Adds anAttributeConverter
instance to this configuration. This form is mainly intended for developers to programmatically add their ownAttributeConverter
instance.- Parameters:
attributeConverter
- TheAttributeConverter
instance.
-
addAttributeConverter
public void addAttributeConverter(jakarta.persistence.AttributeConverter<?,?> attributeConverter, boolean autoApply)
Adds anAttributeConverter
instance to this configuration. This form is mainly intended for developers to programmatically add their ownAttributeConverter
instance.- Parameters:
attributeConverter
- TheAttributeConverter
instance.autoApply
- Should theAttributeConverter
be auto applied to property types as specified by its "entity attribute" parameterized type?
-
addAttributeConverter
public void addAttributeConverter(ConverterDescriptor converterDescriptor)
-
addEntityNameResolver
public void addEntityNameResolver(EntityNameResolver entityNameResolver)
Add anEntityNameResolver
to this configuration.- Since:
- 6.2
-
setSharedCacheMode
public void setSharedCacheMode(jakarta.persistence.SharedCacheMode sharedCacheMode)
Sets theSharedCacheMode
to use.Note that currently only
SharedCacheMode.ALL
has any effect in terms ofhbm.xml
binding.- Parameters:
sharedCacheMode
- The SharedCacheMode to use
-
getNamedSQLQueries
public Map<String,NamedNativeQueryDefinition> getNamedSQLQueries()
-
getSqlResultSetMappings
public Map<String,NamedResultSetMappingDescriptor> getSqlResultSetMappings()
-
getNamedEntityGraphs
public Collection<NamedEntityGraphDefinition> getNamedEntityGraphs()
-
getNamedQueries
public Map<String,NamedHqlQueryDefinition> getNamedQueries()
-
getNamedProcedureCallMap
public Map<String,NamedProcedureCallDefinition> getNamedProcedureCallMap()
-
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
-
-