Package org.hibernate.cfg

Class Configuration

java.lang.Object
org.hibernate.cfg.Configuration
public classConfigurationextendsObject
A convenience API making it easier to bootstrap an instance of Hibernate.

An instance ofConfiguration may be obtained simply byinstantiation, and may be used to aggregate:

Note that XML mappings may be expressed using either:

  • the JPA-standardorm.xml format, or
  • the legacy.hbm.xml format, which is considered deprecated.

Configuration properties are enumerated byAvailableSettings.

When instantiated, an instance ofConfiguration has its properties initially populated from theenvironment, including:

These initial properties may be completely discarded by callingsetProperties(Properties), or they may be overridden individually by callingsetProperty(String, String).

 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 addingattribute converters,type contributors,entity name resolvers,SQL function descriptors, andauxiliary database objects, for settingnaming strategies and atenant id resolver, and more.

Finally, an instance ofSessionFactoryBuilder is obtained by callingbuildSessionFactory().

Ultimately, this class simply delegates toMetadataBuilder andStandardServiceRegistryBuilder to actually do the hard work ofbuilding theSessionFactory. Programs may directly use the APIs defined underorg.hibernate.boot, as an alternative to using an instance of this class.

See Also:
API Note:
TheHibernatePersistenceConfiguration is a new alternative to this venerable API, and extends the JPA-standardPersistenceConfiguration.

  • 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()
      TheImplicitNamingStrategy, if any, to use in this configuration.

    • setImplicitNamingStrategy

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

    • getPhysicalNamingStrategy

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

    • setPhysicalNamingStrategy

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

    • configure

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

      public Configuration configure(String resource) throwsHibernateException
      Use the mappings and properties specified in the given application resource.

      The format of the resource is defined byhibernate-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

      @Internalpublic StandardServiceRegistryBuilder getStandardServiceRegistryBuilder()
      Intended for internal testing use only!!!

    • configure

      public Configuration configure(URL url) throwsHibernateException
      Use the mappings and properties specified in the given document.

      The format of the document is defined byhibernate-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) throwsHibernateException
      Use the mappings and properties specified in the given application file.

      The format of the file is defined byhibernate-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

      public Configuration showSql(boolean showSql, boolean formatSql, boolean highlightSql)
      Parameters:
      showSql - should SQL be logged to console?
      formatSql - should logged SQL be formatted
      highlightSql - should logged SQL be highlighted with pretty colors

    • setSchemaExportAction

      public Configuration setSchemaExportAction(Action action)
      Parameters:
      action - theAction

    • setCredentials

      public Configuration setCredentials(String user,String pass)
      Parameters:
      user - the user id
      pass - the password

    • setJdbcUrl

      public Configuration setJdbcUrl(String url)
      Parameters:
      url - the JDBC URL

    • setDatasource

      public Configuration setDatasource(String jndiName)
      Parameters:
      jndiName - the JNDI name of the datasource

    • setTransactionType

      public Configuration setTransactionType(PersistenceUnitTransactionType transactionType)
      Parameters:
      transactionType - thePersistenceUnitTransactionType

    • registerTypeContributor

      public Configuration registerTypeContributor(TypeContributor typeContributor)
      Add aTypeContributor to this configuration.
      Returns:
      this for method chaining

    • registerFunctionContributor

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

    • registerTypeOverride

      public Configuration registerTypeOverride(BasicType<?> type)
      Register atype 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 atype 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) throwsMappingException
      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) throwsMappingException
      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 toaddXmlMapping(Binding).

    • addXmlMapping

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

    • addCacheableFile

      public Configuration addCacheableFile(File xmlFile) throwsMappingException
      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 namexmlFile + ".bin" wherexmlFile is the name of the original mapping file.

      If a cachedxmlFile + ".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

      public Configuration addCacheableFileStrictly(File xmlFile) throwsSerializationException
      INTENDED FOR TESTSUITE USE ONLY!

      Much likeaddCacheableFile(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) throwsMappingException
      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

      public Configuration addURL(URL url) throwsMappingException
      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

      public Configuration addInputStream(InputStream xmlInputStream) throwsMappingException
      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

      public Configuration addResource(String resourceName) throwsMappingException
      Read mappings as an application resource name, that is, using aclasspath 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) throwsMappingException
      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 aclasspath 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

    • addAnnotatedClasses

      public Configuration addAnnotatedClasses(Class... annotatedClasses)
      Read metadata from the annotations associated with the given classes.
      Parameters:
      annotatedClasses - The classes containing annotations
      Returns:
      this (for method chaining)

    • addPackage

      public Configuration addPackage(String packageName) throwsMappingException
      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

      public Configuration addPackages(String... packageNames) throwsMappingException
      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

      public Configuration addJar(File jar) throwsMappingException
      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

      public Configuration addDirectory(File dir) throwsMappingException
      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

      public Interceptor getInterceptor()
      Retrieve the configuredInterceptor.
      Returns:
      The currentInterceptor

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

    • getSessionFactoryObserver

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

    • setSessionFactoryObserver

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

    • getStatementInspector

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

    • setStatementInspector

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

    • getCurrentTenantIdentifierResolver

      public CurrentTenantIdentifierResolver<Object> 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

      public CustomEntityDirtinessStrategy 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

      @Incubatingpublic ColumnOrderingStrategy getColumnOrderingStrategy()
      TheCustomEntityDirtinessStrategy, if any, that was added to this configuration.

    • setColumnOrderingStrategy

      @Incubatingpublic Configuration setColumnOrderingStrategy(ColumnOrderingStrategy columnOrderingStrategy)
      Specify aCustomEntityDirtinessStrategy to be added to this configuration.
      Returns:
      this for method chaining

    • buildSessionFactory

      public SessionFactory buildSessionFactory(ServiceRegistry serviceRegistry) throwsHibernateException
      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-builtSessionFactory
      Throws:
      HibernateException - usually indicates an invalid configuration or invalid mapping information

    • buildSessionFactory

      public SessionFactory buildSessionFactory() throwsHibernateException
      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-builtSessionFactory
      Throws:
      HibernateException - usually indicates an invalid configuration or invalid mapping information

    • addSqlFunction

      public Configuration addSqlFunction(String functionName,SqmFunctionDescriptor function)
      Adds afunction 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 anAuxiliaryDatabaseObject to this configuration.
      Returns:
      this for method chaining

    • addAttributeConverter

      public Configuration addAttributeConverter(Class<? extendsAttributeConverter<?,?>> 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<? extendsAttributeConverter<?,?>> attributeConverterClass)
      Adds anAttributeConverter to this configuration.
      Parameters:
      attributeConverterClass - TheAttributeConverter class.
      Returns:
      this for method chaining

    • addAttributeConverter

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

      public Configuration addAttributeConverter(ConverterDescriptor<?,?> converterDescriptor)
      Adds anConverterDescriptor instance to this configuration.
      Parameters:
      converterDescriptor - TheConverterDescriptor instance.
      Returns:
      this for method chaining

    • addEntityNameResolver

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

    • setSharedCacheMode

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

      Note that currently onlySharedCacheMode.ALL has any effect onhbm.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 doesnot 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 foraddProperties(Properties).