Class Configuration
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.
Note that XML mappings may be expressed using the JPA orm.xml
format, or in Hibernate's legacy .hbm.xml
format.
Configuration properties are enumerated by AvailableSettings
.
SessionFactory 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") .buildSessionFactory();
In addition, there are convenience methods for adding attribute converters, type contributors, entity name resolvers, SQL function descriptors, and auxiliary database objects, for setting naming strategies and a tenant id resolver, and more.
Finally, an instance of SessionFactoryBuilder
is obtained by
calling buildSessionFactory()
.
Ultimately, this class simply delegates to MetadataBuilder
and
StandardServiceRegistryBuilder
to actually do the hard work of
building the SessionFactory
.
Programs may directly use the APIs defined under org.hibernate.boot
,
as an alternative to using an instance of this class.
- See Also:
- API Note:
- The
HibernatePersistenceConfiguration
is a new alternative to this venerable API, and extends the JPA-standardPersistenceConfiguration
.
-
Constructor Summary
ConstructorsConstructorDescriptionCreate 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
Modifier and TypeMethodDescriptionaddAnnotatedClass
(Class<?> annotatedClass) Read metadata from the annotations associated with this class.addAnnotatedClasses
(Class... annotatedClasses) Read metadata from the annotations associated with the given classes.addAttributeConverter
(AttributeConverter<?, ?> attributeConverter) Adds anAttributeConverter
instance to this configuration.addAttributeConverter
(AttributeConverter<?, ?> attributeConverter, boolean autoApply) Adds anAttributeConverter
instance to this configuration.addAttributeConverter
(Class<? extends AttributeConverter<?, ?>> attributeConverterClass) Adds anAttributeConverter
to this configuration.addAttributeConverter
(Class<? extends AttributeConverter<?, ?>> attributeConverterClass, boolean autoApply) Adds anAttributeConverter
to this configuration.addAttributeConverter
(ConverterDescriptor converterDescriptor) Adds anConverterDescriptor
instance to this configuration.Adds anAuxiliaryDatabaseObject
to this configuration.addCacheableFile
(File xmlFile) Add a cacheable mapping file.addCacheableFile
(String xmlFile) Add a cacheable mapping file.addCacheableFileStrictly
(File xmlFile) INTENDED FOR TESTSUITE USE ONLY!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.addDirectory
(File dir) Read all.hbm.xml
mapping documents from a directory tree.addEntityNameResolver
(EntityNameResolver entityNameResolver) Add anEntityNameResolver
to this configuration.Read mappings from a particular XML file.Read mappings from a particular XML fileaddInputStream
(InputStream xmlInputStream) Read mappings from anInputStream
.Read all.hbm.xml
mappings from a.jar
file.addPackage
(String packageName) Read package-level metadata.addPackages
(String... packageNames) Read package-level metadata.addProperties
(Properties properties) Add the given properties to ours.addResource
(String resourceName) Read mappings as an application resource name, that is, using a classpath lookup, trying different class loaders in turn.addSqlFunction
(String functionName, SqmFunctionDescriptor function) Adds a function descriptor to this configuration.Read mappings from aURL
.addXmlMapping
(Binding<?> binding) Read mappings that were parsed usinggetXmlMappingBinderAccess()
.Create aSessionFactory
using the properties and mappings in this configuration.buildSessionFactory
(ServiceRegistry serviceRegistry) Create aSessionFactory
using the properties and mappings in this configuration.Use the mappings and properties specified in an application resource namedhibernate.cfg.xml
.Use the mappings and properties specified in the given application file.Use the mappings and properties specified in the given application resource.Use the mappings and properties specified in the given document.TheCustomEntityDirtinessStrategy
, if any, that was added to this configuration.TheCurrentTenantIdentifierResolver
, if any, that was added to this configuration.TheCustomEntityDirtinessStrategy
, if any, that was added to this configuration.Retrieve the user-suppliedEntityNotFoundDelegate
, ornull
if no delegate has been specified.TheImplicitNamingStrategy
, if any, to use in this configuration.Retrieve the configuredInterceptor
.ThePhysicalNamingStrategy
, if any, to use in this configuration.Get all propertiesgetProperty
(String propertyName) Get a property value by nameTheSessionFactoryObserver
, if any, that was added to this configuration.Intended for internal testing use only!!!TheStatementInspector
, if any, that was added to this configuration.An object capable of parsing XML mapping files that can then be passed toaddXmlMapping(Binding)
.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.registerFunctionContributor
(FunctionContributor functionContributor) Add aFunctionContributor
to this configuration.registerTypeContributor
(TypeContributor typeContributor) Add aTypeContributor
to this configuration.registerTypeOverride
(BasicType<?> type) Register a type into the type registry, potentially replacing a previously registered type.registerTypeOverride
(UserType<?> type, String[] keys) Register a type into the type registry, potentially replacing a previously registered type.setColumnOrderingStrategy
(ColumnOrderingStrategy columnOrderingStrategy) Specify aCustomEntityDirtinessStrategy
to be added to this configuration.setCredentials
(String user, String pass) setCurrentTenantIdentifierResolver
(CurrentTenantIdentifierResolver<Object> currentTenantIdentifierResolver) Specify aCurrentTenantIdentifierResolver
to be added to this configuration.setCustomEntityDirtinessStrategy
(CustomEntityDirtinessStrategy customEntityDirtinessStrategy) Specify aCustomEntityDirtinessStrategy
to be added to this configuration.setDatasource
(String jndiName) setEntityNotFoundDelegate
(EntityNotFoundDelegate entityNotFoundDelegate) Specify a user-suppliedEntityNotFoundDelegate
to be used to handle scenarios where an entity could not be located by specified id.setImplicitNamingStrategy
(ImplicitNamingStrategy implicitNamingStrategy) Set anImplicitNamingStrategy
to use in this configuration.setInterceptor
(Interceptor interceptor) Set the currentInterceptor
.setJdbcUrl
(String url) setPhysicalNamingStrategy
(PhysicalNamingStrategy physicalNamingStrategy) Set aPhysicalNamingStrategy
to use in this configuration.setProperties
(Properties properties) Specify a completely new set of propertiessetProperty
(String propertyName, boolean value) Set a property to a boolean value by namesetProperty
(String propertyName, int value) Set a property to an integer value by namesetProperty
(String propertyName, Class<?> value) Set a property to a Java class namesetProperty
(String propertyName, Enum<?> value) Set a property to the name of a value of an enumerated typesetProperty
(String propertyName, String value) Set a property value by namesetSchemaExportAction
(Action action) setSessionFactoryObserver
(SessionFactoryObserver sessionFactoryObserver) Specify aSessionFactoryObserver
to be added to this configuration.setSharedCacheMode
(SharedCacheMode sharedCacheMode) Sets theSharedCacheMode
to use.setStatementInspector
(StatementInspector statementInspector) Specify aStatementInspector
to be added to this configuration.setTransactionType
(PersistenceUnitTransactionType transactionType) showSql
(boolean showSql, boolean formatSql, boolean highlightSql)
-
Constructor Details
-
Configuration
public Configuration()Create a new instance, using a defaultBootstrapServiceRegistry
and a newly instantiatedMetadataSources
.This is the usual method of obtaining a
Configuration
. -
Configuration
Create a new instance, using the givenBootstrapServiceRegistry
and a newly instantiatedMetadataSources
. -
Configuration
Create a new instance, using the givenMetadataSources
, and aBootstrapServiceRegistry
obtained from theMetadataSources
.
-
-
Method Details
-
getProperties
Get all properties- Returns:
- all properties
-
setProperties
Specify a completely new set of properties- Parameters:
properties
- The new set of properties- Returns:
this
for method chaining
-
getProperty
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
Set a property value by name- Parameters:
propertyName
- The name of the property to setvalue
- The new property value- Returns:
this
for method chaining
-
setProperty
Set a property to a boolean value by name- Parameters:
propertyName
- The name of the property to setvalue
- The new boolean property value- Returns:
this
for method chaining- Since:
- 6.5
-
setProperty
Set a property to a Java class name- Parameters:
propertyName
- The name of the property to setvalue
- The Java class- Returns:
this
for method chaining- Since:
- 6.5
-
setProperty
Set a property to the name of a value of an enumerated type- Parameters:
propertyName
- The name of the property to setvalue
- A value of an enumerated type- Returns:
this
for method chaining- Since:
- 6.5
-
setProperty
Set a property to an integer value by name- Parameters:
propertyName
- The name of the property to setvalue
- The new integer property value- Returns:
this
for method chaining- Since:
- 6.5
-
addProperties
Add the given properties to ours.- Parameters:
properties
- The properties to add.- Returns:
this
for method chaining
-
getImplicitNamingStrategy
TheImplicitNamingStrategy
, if any, to use in this configuration. -
setImplicitNamingStrategy
Set anImplicitNamingStrategy
to use in this configuration.- Returns:
this
for method chaining
-
getPhysicalNamingStrategy
ThePhysicalNamingStrategy
, if any, to use in this configuration. -
setPhysicalNamingStrategy
Set aPhysicalNamingStrategy
to use in this configuration.- Returns:
this
for method chaining
-
configure
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
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
Intended for internal testing use only!!! -
configure
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
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
-
showSql
- Parameters:
showSql
- should SQL be logged to console?formatSql
- should logged SQL be formattedhighlightSql
- should logged SQL be highlighted with pretty colors
-
setSchemaExportAction
- Parameters:
action
- theAction
-
setCredentials
- Parameters:
user
- the user idpass
- the password
-
setJdbcUrl
- Parameters:
url
- the JDBC URL
-
setDatasource
- Parameters:
jndiName
- the JNDI name of the datasource
-
setTransactionType
- Parameters:
transactionType
- thePersistenceUnitTransactionType
-
registerTypeContributor
Add aTypeContributor
to this configuration.- Returns:
this
for method chaining
-
registerFunctionContributor
Add aFunctionContributor
to this configuration.- Returns:
this
for method chaining
-
registerTypeOverride
Register a type into the type registry, potentially replacing a previously registered type.- Parameters:
type
- The type to register.- Returns:
this
for method chaining
-
registerTypeOverride
Register a type into the type registry, potentially replacing a previously registered type.- Parameters:
type
- The type to register.keys
- The keys under which to register the type.- Returns:
this
for method chaining
-
addFile
Read mappings from a particular XML file- Parameters:
xmlFile
- a path to a file- Returns:
this
for method chaining- Throws:
MappingException
- Indicates inability to locate or parse the specified mapping file.- See Also:
-
addFile
Read mappings from a particular XML file.- Parameters:
xmlFile
- a path to a file- Returns:
this
for method chaining- Throws:
MappingException
- Indicates inability to locate the specified mapping file
-
getXmlMappingBinderAccess
An object capable of parsing XML mapping files that can then be passed toaddXmlMapping(Binding)
. -
addXmlMapping
Read mappings that were parsed usinggetXmlMappingBinderAccess()
.- Parameters:
binding
- the parsed mapping- Returns:
this
for method chaining
-
addCacheableFile
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- Throws:
MappingException
- Indicates problems reading the cached file or processing the non-cached file.
-
addCacheableFileStrictly
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:
this
for method chaining- Throws:
SerializationException
- Indicates a problem deserializing the cached dom tree
-
addCacheableFile
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- Throws:
MappingException
- Indicates problems reading the cached file or processing the non-cached file- See Also:
-
addURL
Read mappings from aURL
.- Parameters:
url
- The url for the mapping document to be read.- Returns:
this
for method chaining- Throws:
MappingException
- Indicates problems reading the URL or processing the mapping document.
-
addInputStream
Read mappings from anInputStream
.- Parameters:
xmlInputStream
- The input stream containing a DOM.- Returns:
this
for method chaining- Throws:
MappingException
- Indicates problems reading the stream, or processing the contained mapping document.
-
addResource
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- Throws:
MappingException
- Indicates problems locating the resource or processing the contained mapping document.
-
addClass
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- Throws:
MappingException
- Indicates problems locating the resource or processing the contained mapping document.
-
addAnnotatedClass
Read metadata from the annotations associated with this class.- Parameters:
annotatedClass
- The class containing annotations- Returns:
this
for method chaining
-
addAnnotatedClasses
Read metadata from the annotations associated with the given classes.- Parameters:
annotatedClasses
- The classes containing annotations- Returns:
- this (for method chaining)
-
addPackage
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
-
addPackages
Read package-level metadata.- Parameters:
packageNames
- java package names- Returns:
- this (for method chaining)
- Throws:
MappingException
- in case there is an error in the mapping data
-
addJar
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- Throws:
MappingException
- Indicates problems reading the jar file or processing the contained mapping documents.
-
addDirectory
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- Throws:
MappingException
- Indicates problems reading the jar file or processing the contained mapping documents.
-
getInterceptor
Retrieve the configuredInterceptor
.- Returns:
- The current
Interceptor
-
setInterceptor
Set the currentInterceptor
.- Parameters:
interceptor
- TheInterceptor
to use- Returns:
this
for method chaining
-
getEntityNotFoundDelegate
Retrieve the user-suppliedEntityNotFoundDelegate
, ornull
if no delegate has been specified.- Returns:
- The user-supplied delegate
-
setEntityNotFoundDelegate
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- Returns:
this
for method chaining
-
getSessionFactoryObserver
TheSessionFactoryObserver
, if any, that was added to this configuration. -
setSessionFactoryObserver
Specify aSessionFactoryObserver
to be added to this configuration.- Returns:
this
for method chaining
-
getStatementInspector
TheStatementInspector
, if any, that was added to this configuration. -
setStatementInspector
Specify aStatementInspector
to be added to this configuration.- Returns:
this
for method chaining
-
getCurrentTenantIdentifierResolver
TheCurrentTenantIdentifierResolver
, if any, that was added to this configuration. -
setCurrentTenantIdentifierResolver
public Configuration setCurrentTenantIdentifierResolver(CurrentTenantIdentifierResolver<Object> currentTenantIdentifierResolver) Specify aCurrentTenantIdentifierResolver
to be added to this configuration.- Returns:
this
for method chaining
-
getCustomEntityDirtinessStrategy
TheCustomEntityDirtinessStrategy
, if any, that was added to this configuration. -
setCustomEntityDirtinessStrategy
public Configuration setCustomEntityDirtinessStrategy(CustomEntityDirtinessStrategy customEntityDirtinessStrategy) Specify aCustomEntityDirtinessStrategy
to be added to this configuration.- Returns:
this
for method chaining
-
getColumnOrderingStrategy
TheCustomEntityDirtinessStrategy
, if any, that was added to this configuration. -
setColumnOrderingStrategy
@Incubating public Configuration setColumnOrderingStrategy(ColumnOrderingStrategy columnOrderingStrategy) Specify aCustomEntityDirtinessStrategy
to be added to this configuration.- Returns:
this
for method chaining
-
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
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
-
addSqlFunction
Adds a function descriptor to this configuration.- Returns:
this
for method chaining- See Also:
- API Note:
- For historical reasons, this method is misnamed. The function descriptor actually describes a function available in HQL, and it may or may not map directly to a function defined in SQL.
-
addAuxiliaryDatabaseObject
Adds anAuxiliaryDatabaseObject
to this configuration.- Returns:
this
for method chaining
-
addAttributeConverter
public Configuration addAttributeConverter(Class<? extends AttributeConverter<?, ?>> attributeConverterClass, boolean autoApply) Adds anAttributeConverter
to this configuration.- Parameters:
attributeConverterClass
- TheAttributeConverter
class.autoApply
- Should theAttributeConverter
be auto applied to property types as specified by its "entity attribute" parameterized type?- Returns:
this
for method chaining
-
addAttributeConverter
public Configuration addAttributeConverter(Class<? extends AttributeConverter<?, ?>> attributeConverterClass) Adds anAttributeConverter
to this configuration.- Parameters:
attributeConverterClass
- TheAttributeConverter
class.- Returns:
this
for method chaining
-
addAttributeConverter
Adds anAttributeConverter
instance to this configuration. This form is mainly intended for developers to programmatically add their ownAttributeConverter
instance.- Parameters:
attributeConverter
- TheAttributeConverter
instance.- Returns:
this
for method chaining
-
addAttributeConverter
public Configuration addAttributeConverter(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?- Returns:
this
for method chaining
-
addAttributeConverter
Adds anConverterDescriptor
instance to this configuration.- Parameters:
converterDescriptor
- TheConverterDescriptor
instance.- Returns:
this
for method chaining
-
addEntityNameResolver
Add anEntityNameResolver
to this configuration.- Parameters:
entityNameResolver
- TheEntityNameResolver
instance.- Returns:
this
for method chaining- Since:
- 6.2
-
getNamedSQLQueries
-
getSqlResultSetMappings
-
getNamedEntityGraphs
-
getNamedQueries
-
getNamedProcedureCallMap
-
mergeProperties
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. If a given property is already set in thisConfiguration
, ignore the setting specified in the argumentProperties
object.- Parameters:
properties
- The properties to merge- Returns:
this
for method chaining- API Note:
- You're probably looking for
addProperties(Properties)
.
-