Package org.hibernate.cfg

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:

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:

  • Constructor Details

  • Method Details

    • 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

    • setProperty

      public Configuration setProperty(String propertyName, boolean value)
      Set a property to a boolean value by name
      Parameters:
      propertyName - The name of the property to set
      value - The new boolean property value
      Returns:
      this for method chaining
      Since:
      6.5

    • setProperty

      public Configuration setProperty(String propertyName, Class<?> value)
      Set a property to a Java class name
      Parameters:
      propertyName - The name of the property to set
      value - The Java class
      Returns:
      this for method chaining
      Since:
      6.5

    • setProperty

      public Configuration setProperty(String propertyName, Enum<?> value)
      Set a property to the name of a value of an enumerated type
      Parameters:
      propertyName - The name of the property to set
      value - A value of an enumerated type
      Returns:
      this for method chaining
      Since:
      6.5

    • setProperty

      public Configuration setProperty(String propertyName, int value)
      Set a property to an integer value by name
      Parameters:
      propertyName - The name of the property to set
      value - The new integer property value
      Returns:
      this for method chaining
      Since:
      6.5

    • addProperties

      public Configuration addProperties(Properties properties)
      Add the given properties to ours.
      Parameters:
      properties - The properties to add.
      Returns:
      this for method chaining

    • getImplicitNamingStrategy

      public ImplicitNamingStrategy getImplicitNamingStrategy()
      The ImplicitNamingStrategy, if any, to use in this configuration.

    • setImplicitNamingStrategy

      public Configuration setImplicitNamingStrategy(ImplicitNamingStrategy implicitNamingStrategy)
      Set an ImplicitNamingStrategy to use in this configuration.
      Returns:
      this for method chaining

    • getPhysicalNamingStrategy

      public PhysicalNamingStrategy getPhysicalNamingStrategy()
      The PhysicalNamingStrategy, if any, to use in this configuration.

    • setPhysicalNamingStrategy

      public Configuration setPhysicalNamingStrategy(PhysicalNamingStrategy physicalNamingStrategy)
      Set a PhysicalNamingStrategy to use in this configuration.
      Returns:
      this for method chaining

    • 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

      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

      @Internal 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)
      Add a TypeContributor to this configuration.
      Returns:
      this for method chaining

    • registerFunctionContributor

      public Configuration registerFunctionContributor(FunctionContributor functionContributor)
      Add a FunctionContributor to this configuration.
      Returns:
      this for method chaining

    • 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.
      Returns:
      this for method chaining

    • registerTypeOverride

      public Configuration registerTypeOverride(UserType<?> type, String[] keys)
      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

      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
      Throws:
      MappingException - Indicates inability to locate or parse the specified mapping file.
      See Also:

    • 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
      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 to addXmlMapping(Binding).

    • addXmlMapping

      public Configuration addXmlMapping(Binding<?> binding)
      Read mappings that were parsed using getXmlMappingBinderAccess().
      Parameters:
      binding - the parsed mapping
      Returns:
      this for method chaining

    • 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 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
      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:
      this for method chaining
      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 a File instance
      Returns:
      this for method chaining
      Throws:
      MappingException - Indicates problems reading the cached file or processing the non-cached file
      See Also:

    • 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
      Throws:
      MappingException - Indicates problems reading the URL 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
      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
      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 named foo.bar.Foo is mapped by a file foo/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

      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 support orm.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

      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 support orm.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

      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
      Returns:
      this for method chaining

    • getEntityNotFoundDelegate

      public EntityNotFoundDelegate getEntityNotFoundDelegate()
      Retrieve the user-supplied EntityNotFoundDelegate, or null if no delegate has been specified.
      Returns:
      The user-supplied delegate

    • setEntityNotFoundDelegate

      public Configuration setEntityNotFoundDelegate(EntityNotFoundDelegate entityNotFoundDelegate)
      Specify a user-supplied EntityNotFoundDelegate 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

      public SessionFactoryObserver getSessionFactoryObserver()
      The SessionFactoryObserver, if any, that was added to this configuration.

    • setSessionFactoryObserver

      public Configuration setSessionFactoryObserver(SessionFactoryObserver sessionFactoryObserver)
      Specify a SessionFactoryObserver to be added to this configuration.
      Returns:
      this for method chaining

    • getStatementInspector

      public StatementInspector getStatementInspector()
      The StatementInspector, if any, that was added to this configuration.

    • setStatementInspector

      public Configuration setStatementInspector(StatementInspector statementInspector)
      Specify a StatementInspector to be added to this configuration.
      Returns:
      this for method chaining

    • getCurrentTenantIdentifierResolver

      public CurrentTenantIdentifierResolver<Object> getCurrentTenantIdentifierResolver()
      The CurrentTenantIdentifierResolver, if any, that was added to this configuration.

    • setCurrentTenantIdentifierResolver

      public Configuration setCurrentTenantIdentifierResolver(CurrentTenantIdentifierResolver<Object> currentTenantIdentifierResolver)
      Specify a CurrentTenantIdentifierResolver to be added to this configuration.
      Returns:
      this for method chaining

    • getCustomEntityDirtinessStrategy

      public CustomEntityDirtinessStrategy getCustomEntityDirtinessStrategy()
      The CustomEntityDirtinessStrategy, if any, that was added to this configuration.

    • setCustomEntityDirtinessStrategy

      public Configuration setCustomEntityDirtinessStrategy(CustomEntityDirtinessStrategy customEntityDirtinessStrategy)
      Specify a CustomEntityDirtinessStrategy to be added to this configuration.
      Returns:
      this for method chaining

    • getColumnOrderingStrategy

      @Incubating public ColumnOrderingStrategy getColumnOrderingStrategy()
      The CustomEntityDirtinessStrategy, if any, that was added to this configuration.

    • setColumnOrderingStrategy

      @Incubating public Configuration setColumnOrderingStrategy(ColumnOrderingStrategy columnOrderingStrategy)
      Specify a CustomEntityDirtinessStrategy to be added to this configuration.
      Returns:
      this for method chaining

    • 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 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 a SessionFactory using the properties and mappings in this configuration. The SessionFactory will be immutable, so changes made to this Configuration 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

      public Configuration addSqlFunction(String functionName, SqmFunctionDescriptor function)
      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

      public Configuration addAuxiliaryDatabaseObject(AuxiliaryDatabaseObject object)
      Adds an AuxiliaryDatabaseObject to this configuration.
      Returns:
      this for method chaining

    • addAttributeConverter

      public Configuration addAttributeConverter(Class<? extends AttributeConverter<?,?>> attributeConverterClass, boolean autoApply)
      Adds an AttributeConverter 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?
      Returns:
      this for method chaining

    • addAttributeConverter

      public Configuration addAttributeConverter(Class<? extends AttributeConverter<?,?>> attributeConverterClass)
      Adds an AttributeConverter to this configuration.
      Parameters:
      attributeConverterClass - The AttributeConverter class.
      Returns:
      this for method chaining

    • addAttributeConverter

      public Configuration addAttributeConverter(AttributeConverter<?,?> attributeConverter)
      Adds an AttributeConverter instance to this configuration. This form is mainly intended for developers to programmatically add their own AttributeConverter instance.
      Parameters:
      attributeConverter - The AttributeConverter instance.
      Returns:
      this for method chaining

    • addAttributeConverter

      public Configuration addAttributeConverter(AttributeConverter<?,?> attributeConverter, boolean autoApply)
      Adds an AttributeConverter instance to this configuration. This form is mainly intended for developers to programmatically add their own AttributeConverter instance.
      Parameters:
      attributeConverter - The AttributeConverter instance.
      autoApply - Should the AttributeConverter be auto applied to property types as specified by its "entity attribute" parameterized type?
      Returns:
      this for method chaining

    • addAttributeConverter

      public Configuration addAttributeConverter(ConverterDescriptor converterDescriptor)
      Adds an ConverterDescriptor instance to this configuration.
      Parameters:
      converterDescriptor - The ConverterDescriptor instance.
      Returns:
      this for method chaining

    • addEntityNameResolver

      public Configuration addEntityNameResolver(EntityNameResolver entityNameResolver)
      Add an EntityNameResolver to this configuration.
      Parameters:
      entityNameResolver - The EntityNameResolver instance.
      Returns:
      this for method chaining
      Since:
      6.2

    • setSharedCacheMode

      public Configuration setSharedCacheMode(SharedCacheMode sharedCacheMode)
      Sets the SharedCacheMode to use.

      Note that currently only SharedCacheMode.ALL has any effect on hbm.xml binding.

      Parameters:
      sharedCacheMode - The SharedCacheMode to use
      Returns:
      this for method chaining

    • 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