Package org.hibernate.cfg

Class Configuration

java.lang.Object
org.hibernate.cfg.Configuration
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
AnnotationConfiguration
public class Configuration extends Object implements Serializable
An instance of Configuration allows the application to specify properties and mapping documents to be used when creating a SessionFactory. Usually an application will create a single Configuration, build a single instance of SessionFactory and then instantiate Sessions in threads servicing client requests. The Configuration is meant only as an initialization-time object. SessionFactorys are immutable and do not retain any association back to the Configuration.

A new Configuration will use the properties specified in hibernate.properties by default.
See Also:

  • Field Details

  • Constructor Details

    • Configuration

      protected Configuration(SettingsFactory settingsFactory)

    • Configuration

      public Configuration()

  • Method Details

    • reset

      protected void reset()

    • getEntityTuplizerFactory

      public EntityTuplizerFactory getEntityTuplizerFactory()

    • getReflectionManager

      public ReflectionManager getReflectionManager()

    • getClassMappings

      public Iterator<PersistentClass> getClassMappings()
      Iterate the entity mappings
      Returns:
      Iterator of the entity mappings currently contained in the configuration.

    • getCollectionMappings

      public Iterator getCollectionMappings()
      Iterate the collection mappings
      Returns:
      Iterator of the collection mappings currently contained in the configuration.

    • getTableMappings

      public Iterator<Table> getTableMappings()
      Iterate the table mappings
      Returns:
      Iterator of the table mappings currently contained in the configuration.

    • getMappedSuperclassMappings

      public Iterator<MappedSuperclass> getMappedSuperclassMappings()
      Iterate the mapped super class mappings EXPERIMENTAL Consider this API as PRIVATE
      Returns:
      iterator over the MappedSuperclass mapping currently contained in the configuration.

    • getClassMapping

      public PersistentClass getClassMapping(String entityName)
      Get the mapping for a particular entity
      Parameters:
      entityName - An entity name.
      Returns:
      the entity mapping information

    • getCollectionMapping

      public Collection getCollectionMapping(String role)
      Get the mapping for a particular collection role
      Parameters:
      role - a collection role
      Returns:
      The collection mapping information

    • setEntityResolver

      public void setEntityResolver(EntityResolver entityResolver)
      Set a custom entity resolver. This entity resolver must be set before addXXX(misc) call. Default value is DTDEntityResolver
      Parameters:
      entityResolver - entity resolver to use

    • getEntityResolver

      public EntityResolver getEntityResolver()

    • getEntityNotFoundDelegate

      public EntityNotFoundDelegate getEntityNotFoundDelegate()
      Retrieve the user-supplied delegate to handle non-existent entity scenarios. May be null.
      Returns:
      The user-supplied delegate

    • setEntityNotFoundDelegate

      public void setEntityNotFoundDelegate(EntityNotFoundDelegate entityNotFoundDelegate)
      Specify a user-supplied delegate to be used to handle scenarios where an entity could not be located by specified id. This is mainly intended for EJB3 implementations to be able to control how proxy initialization errors should be handled...
      Parameters:
      entityNotFoundDelegate - The delegate to use

    • 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

      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. Historically this could have indicated a problem parsing the XML document, but that is now delayed until after buildMappings()

    • add

      public void add(XmlDocument metadataXml)

    • addCacheableFile

      public Configuration addCacheableFile(File xmlFile) throws MappingException
      Add a cached mapping file. A cached file is a serialized representation of the DOM structure of a particular mapping. It is saved from a previous call as a file with the name xmlFile + ".bin" where xmlFile is the name of the original mapping file.

      If a cached xmlFile + ".bin" exists and is newer than xmlFile the ".bin" file will be read directly. Otherwise xmlFile is read and then serialized to xmlFile + ".bin" for use the next time.
      Parameters:
      xmlFile - The cacheable mapping file to be added.
      Returns:
      this (for method chaining purposes)
      Throws:
      MappingException - Indicates problems reading the cached file or processing the non-cached file.

    • addCacheableFileStrictly

      public Configuration addCacheableFileStrictly(File xmlFile) throws SerializationException, FileNotFoundException
      INTENDED FOR TESTSUITE USE ONLY!

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

      Parameters:
      xmlFile - The xml file, not the bin!
      Returns:
      The dom "deserialized" from the cached file.
      Throws:
      SerializationException - Indicates a problem deserializing the cached dom tree
      FileNotFoundException - Indicates that the cached file was not found or was not usable.

    • addCacheableFile

      public Configuration addCacheableFile(String xmlFile) throws MappingException
      Add a cacheable mapping file.
      Parameters:
      xmlFile - The name of the file to be added. This must be in a form useable to simply construct a File instance.
      Returns:
      this (for method chaining purposes)
      Throws:
      MappingException - Indicates problems reading the cached file or processing the non-cached file.
      See Also:

    • addXML

      public Configuration addXML(String xml) throws MappingException
      Read mappings from a String
      Parameters:
      xml - an XML string
      Returns:
      this (for method chaining purposes)
      Throws:
      MappingException - Indicates problems parsing the given XML string

    • addURL

      public Configuration addURL(URL url) throws MappingException
      Read mappings from a URL
      Parameters:
      url - The url for the mapping document to be read.
      Returns:
      this (for method chaining purposes)
      Throws:
      MappingException - Indicates problems reading the URL or processing the mapping document.

    • addDocument

      public Configuration addDocument(Document doc) throws MappingException
      Read mappings from a DOM Document
      Parameters:
      doc - The DOM document
      Returns:
      this (for method chaining purposes)
      Throws:
      MappingException - Indicates problems reading the DOM or processing the mapping document.

    • addInputStream

      public Configuration addInputStream(InputStream xmlInputStream) throws MappingException
      Read mappings from an InputStream.
      Parameters:
      xmlInputStream - The input stream containing a DOM.
      Returns:
      this (for method chaining purposes)
      Throws:
      MappingException - Indicates problems reading the stream, or processing the contained mapping document.

    • addResource

      public Configuration addResource(String resourceName, ClassLoader classLoader) throws MappingException
      Read mappings as a application resource (i.e. classpath lookup).
      Parameters:
      resourceName - The resource name
      classLoader - The class loader to use.
      Returns:
      this (for method chaining purposes)
      Throws:
      MappingException - Indicates problems locating the resource or processing the contained mapping document.

    • addResource

      public Configuration addResource(String resourceName) throws MappingException
      Read mappings as a application resourceName (i.e. classpath lookup) trying different class loaders.
      Parameters:
      resourceName - The resource name
      Returns:
      this (for method chaining purposes)
      Throws:
      MappingException - Indicates problems locating the resource or processing the contained mapping document.

    • addClass

      public Configuration addClass(Class persistentClass) throws MappingException
      Read a mapping as an application resource using the convention that a class named foo.bar.Foo is mapped by a file foo/bar/Foo.hbm.xml which can be resolved as a classpath resource.
      Parameters:
      persistentClass - The mapped class
      Returns:
      this (for method chaining purposes)
      Throws:
      MappingException - Indicates problems locating the resource or processing the contained mapping document.

    • addAnnotatedClass

      public Configuration addAnnotatedClass(Class annotatedClass)
      Read metadata from the annotations associated with this class.
      Parameters:
      annotatedClass - The class containing annotations
      Returns:
      this (for method chaining)

    • addPackage

      public Configuration addPackage(String packageName) throws MappingException
      Read package-level metadata.
      Parameters:
      packageName - java package name
      Returns:
      this (for method chaining)
      Throws:
      MappingException - in case there is an error in the mapping data

    • addJar

      public Configuration addJar(File jar) throws MappingException
      Read all mappings from a jar file

      Assumes that any file named *.hbm.xml is a mapping document.

      Parameters:
      jar - a jar file
      Returns:
      this (for method chaining purposes)
      Throws:
      MappingException - Indicates problems reading the jar file or processing the contained mapping documents.

    • addDirectory

      public Configuration addDirectory(File dir) throws MappingException
      Read all mapping documents from a directory tree.

      Assumes that any file named *.hbm.xml is a mapping document.

      Parameters:
      dir - The directory
      Returns:
      this (for method chaining purposes)
      Throws:
      MappingException - Indicates problems reading the jar file or processing the contained mapping documents.

    • createMappings

      public Mappings createMappings()
      Create a new Mappings to add class and collection mappings to.
      Returns:
      The created mappings

    • generateDropSchemaScript

      public String[] generateDropSchemaScript(Dialect dialect) throws HibernateException
      Generate DDL for dropping tables
      Parameters:
      dialect - The dialect for which to generate the drop script
      Returns:
      The sequence of DDL commands to drop the schema objects
      Throws:
      HibernateException - Generally indicates a problem calling buildMappings()
      See Also:

    • generateSchemaCreationScript

      public String[] generateSchemaCreationScript(Dialect dialect) throws HibernateException
      Parameters:
      dialect - The dialect for which to generate the creation script
      Returns:
      The sequence of DDL commands to create the schema objects
      Throws:
      HibernateException - Generally indicates a problem calling buildMappings()
      See Also:

    • generateSchemaUpdateScript

      public String[] generateSchemaUpdateScript(Dialect dialect, DatabaseMetadata databaseMetadata) throws HibernateException
      Parameters:
      dialect - The dialect for which to generate the creation script
      databaseMetadata - The database catalog information for the database to be updated; needed to work out what should be created/altered
      Returns:
      The sequence of DDL commands to apply the schema objects
      Throws:
      HibernateException - Generally indicates a problem calling buildMappings()
      See Also:

    • validateSchema

      public void validateSchema(Dialect dialect, DatabaseMetadata databaseMetadata) throws HibernateException
      Throws:
      HibernateException

    • buildMappings

      public void buildMappings()
      Call this to ensure the mappings are fully compiled/built. Usefull to ensure getting access to all information in the metamodel when calling e.g. getClassMappings().

    • secondPassCompile

      protected void secondPassCompile() throws MappingException
      Throws:
      MappingException

    • findPossibleExtends

      protected ExtendsQueueEntry findPossibleExtends()

    • secondPassCompileForeignKeys

      protected void secondPassCompileForeignKeys(Table table, Set done) throws MappingException
      Throws:
      MappingException

    • getNamedQueries

      public Map<String,NamedQueryDefinition> getNamedQueries()

    • buildSessionFactory

      public SessionFactory buildSessionFactory() throws HibernateException
      Create a SessionFactory using the properties and mappings in this configuration. The SessionFactory will be immutable, so changes made to this Configuration after building the SessionFactory will not affect it.
      Returns:
      The build SessionFactory
      Throws:
      HibernateException - usually indicates an invalid configuration or invalid mapping information

    • getInterceptor

      public Interceptor getInterceptor()
      Rterieve the configured Interceptor.
      Returns:
      The current Interceptor

    • setInterceptor

      public Configuration setInterceptor(Interceptor interceptor)
      Set the current Interceptor
      Parameters:
      interceptor - The Interceptor to use for the built SessionFactory.
      Returns:
      this for method chaining

    • getProperties

      public Properties getProperties()
      Get all properties
      Returns:
      all properties

    • getProperty

      public String getProperty(String propertyName)
      Get a property value by name
      Parameters:
      propertyName - The name of the property
      Returns:
      The value curently associated with that property name; may be null.

    • 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

    • addProperties

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

    • 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 ethod chaining

    • 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

    • 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 in hibernate-configuration-3.0.dtd.

      The resource is found via getConfigurationInputStream(java.lang.String)

      Parameters:
      resource - The resource to use
      Returns:
      this for method chaining
      Throws:
      HibernateException - Generally indicates we cannot find the named resource
      See Also:

    • getConfigurationInputStream

      protected InputStream getConfigurationInputStream(String resource) throws HibernateException
      Get the configuration file as an InputStream. Might be overridden by subclasses to allow the configuration to be located by some arbitrary mechanism.

      By default here we use classpath resource resolution

      Parameters:
      resource - The resource to locate
      Returns:
      The stream
      Throws:
      HibernateException - Generally indicates we cannot find the named resource

    • configure

      public Configuration configure(URL url) throws HibernateException
      Use the mappings and properties specified in the given document. The format of the document is defined in hibernate-configuration-3.0.dtd.
      Parameters:
      url - URL from which you wish to load the configuration
      Returns:
      this for method chaining
      Throws:
      HibernateException - Generally indicates a problem access the url
      See Also:

    • configure

      public Configuration configure(File configFile) throws HibernateException
      Use the mappings and properties specified in the given application file. The format of the file is defined in hibernate-configuration-3.0.dtd.
      Parameters:
      configFile - File from which you wish to load the configuration
      Returns:
      this for method chaining
      Throws:
      HibernateException - Generally indicates a problem access the file
      See Also:

    • doConfigure

      protected Configuration doConfigure(InputStream stream, String resourceName) throws HibernateException
      Configure this configuration's state from the contents of the given input stream. The expectation is that the stream contents represent an XML document conforming to the Hibernate Configuration DTD. See doConfigure(Document) for further details.
      Parameters:
      stream - The input stream from which to read
      resourceName - The name to use in warning/error messages
      Returns:
      this for method chaining
      Throws:
      HibernateException - Indicates a problem reading the stream contents.

    • configure

      public Configuration configure(Document document) throws HibernateException
      Use the mappings and properties specified in the given XML document. The format of the file is defined in hibernate-configuration-3.0.dtd.
      Parameters:
      document - an XML document from which you wish to load the configuration
      Returns:
      A configuration configured via the Document
      Throws:
      HibernateException - if there is problem in accessing the file.

    • doConfigure

      protected Configuration doConfigure(org.dom4j.Document doc) throws HibernateException
      Parse a dom4j document conforming to the Hibernate Configuration DTD (hibernate-configuration-3.0.dtd) and use its information to configure this Configuration's state
      Parameters:
      doc - The dom4j document
      Returns:
      this for method chaining
      Throws:
      HibernateException - Indicates a problem performing the configuration task

    • setListener

      public void setListener(String type, String listener)

    • setListeners

      public void setListeners(String type, String[] listenerClasses)

    • setListener

      public void setListener(String type, Object listener)

    • setListeners

      public void setListeners(String type, Object[] listeners)

    • getEventListeners

      public EventListeners getEventListeners()

    • setCacheConcurrencyStrategy

      public Configuration setCacheConcurrencyStrategy(String entityName, String concurrencyStrategy)
      Set up a cache for an entity class
      Parameters:
      entityName - The name of the entity to which we shoudl associate these cache settings
      concurrencyStrategy - The cache strategy to use
      Returns:
      this for method chaining

    • setCacheConcurrencyStrategy

      public Configuration setCacheConcurrencyStrategy(String entityName, String concurrencyStrategy, String region)
      Set up a cache for an entity class, giving an explicit region name
      Parameters:
      entityName - The name of the entity to which we should associate these cache settings
      concurrencyStrategy - The cache strategy to use
      region - The name of the cache region to use
      Returns:
      this for method chaining

    • setCacheConcurrencyStrategy

      public void setCacheConcurrencyStrategy(String entityName, String concurrencyStrategy, String region, boolean cacheLazyProperty) throws MappingException
      Throws:
      MappingException

    • setCollectionCacheConcurrencyStrategy

      public Configuration setCollectionCacheConcurrencyStrategy(String collectionRole, String concurrencyStrategy)
      Set up a cache for a collection role
      Parameters:
      collectionRole - The name of the collection to which we should associate these cache settings
      concurrencyStrategy - The cache strategy to use
      Returns:
      this for method chaining

    • setCollectionCacheConcurrencyStrategy

      public void setCollectionCacheConcurrencyStrategy(String collectionRole, String concurrencyStrategy, String region)
      Set up a cache for a collection role, giving an explicit region name
      Parameters:
      collectionRole - The name of the collection to which we should associate these cache settings
      concurrencyStrategy - The cache strategy to use
      region - The name of the cache region to use

    • getImports

      public Map<String,String> getImports()
      Get the query language imports
      Returns:
      a mapping from "import" names to fully qualified class names

    • buildSettings

      public Settings buildSettings()
      Create an object-oriented view of the configuration properties
      Returns:
      The build settings

    • buildSettings

      public Settings buildSettings(Properties props) throws HibernateException
      Throws:
      HibernateException

    • getNamedSQLQueries

      public Map getNamedSQLQueries()

    • getSqlResultSetMappings

      public Map getSqlResultSetMappings()

    • getNamingStrategy

      public NamingStrategy getNamingStrategy()

    • setNamingStrategy

      public Configuration setNamingStrategy(NamingStrategy namingStrategy)
      Set a custom naming strategy
      Parameters:
      namingStrategy - the NamingStrategy to set
      Returns:
      this for method chaining

    • getPersisterClassProvider

      public PersisterClassProvider getPersisterClassProvider()

    • setPersisterClassProvider

      public Configuration setPersisterClassProvider(PersisterClassProvider persisterClassProvider)
      Defines a custom persister class provider. The persister class is chosen according to the following rules in decreasing priority: - the persister class defined explicitly via annotation or XML - the persister class returned by the PersisterClassProvider implementation (if not null) - the default provider as chosen by Hibernate Core (best choice most of the time)
      Parameters:
      persisterClassProvider - implementation

    • getIdentifierGeneratorFactory

      public DefaultIdentifierGeneratorFactory getIdentifierGeneratorFactory()
      Retrieve the IdentifierGeneratorFactory in effect for this configuration.
      Returns:
      This configuration's IdentifierGeneratorFactory.

    • buildMapping

      public Mapping buildMapping()

    • getFilterDefinitions

      public Map getFilterDefinitions()

    • addFilterDefinition

      public void addFilterDefinition(FilterDefinition definition)

    • iterateFetchProfiles

      public Iterator iterateFetchProfiles()

    • addFetchProfile

      public void addFetchProfile(FetchProfile fetchProfile)

    • addAuxiliaryDatabaseObject

      public void addAuxiliaryDatabaseObject(AuxiliaryDatabaseObject object)

    • getSqlFunctions

      public Map getSqlFunctions()

    • addSqlFunction

      public void addSqlFunction(String functionName, SQLFunction function)

    • getTypeResolver

      public TypeResolver getTypeResolver()

    • registerTypeOverride

      public void registerTypeOverride(BasicType type)
      Allows registration of a type into the type registry. The phrase 'override' in the method name simply reminds that registration *potentially* replaces a previously registered type .
      Parameters:
      type - The type to register.

    • registerTypeOverride

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

    • registerTypeOverride

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

    • getSessionFactoryObserver

      public SessionFactoryObserver getSessionFactoryObserver()

    • setSessionFactoryObserver

      public void setSessionFactoryObserver(SessionFactoryObserver sessionFactoryObserver)

    • setPrecedence

      public void setPrecedence(String precedence)