Package org.hibernate.cfg

Class Configuration

  • public class Configuration
extends java.lang.Object
    Represents one approach for bootstrapping Hibernate. In fact, historically this was the way to bootstrap Hibernate.

    The approach here is to define all configuration and mapping sources in one API and to then build the SessionFactory in one-shot. The configuration and mapping sources defined here are just held here until the SessionFactory is built. This is an important distinction from the legacy behavior of this class, where we would try to incrementally build the mappings from sources as they were added. The ramification of this change in behavior is that users can add configuration and mapping sources here, but they can no longer query the in-flight state of mappings (PersistentClass, Collection, etc) here.

    Note: Internally this class uses the new bootstrapping approach when asked to build the SessionFactory.

    See Also:
    SessionFactory

    • Field Detail

      • ARTEFACT_PROCESSING_ORDER

        public static final java.lang.String ARTEFACT_PROCESSING_ORDER
        See Also:
        Constant Field Values

    • Method Detail

      • reset

        protected void reset()

      • getProperties

        public java.util.Properties getProperties()
        Get all properties
        Returns:
        all properties

      • setProperties

        public Configuration setProperties​(java.util.Properties properties)
        Specify a completely new set of properties
        Parameters:
        properties - The new set of properties
        Returns:
        this for method chaining

      • getProperty

        public java.lang.String getProperty​(java.lang.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​(java.lang.String propertyName,
                                 java.lang.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

      • addProperties

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

      • setImplicitNamingStrategy

        public void setImplicitNamingStrategy​(ImplicitNamingStrategy implicitNamingStrategy)

      • setPhysicalNamingStrategy

        public void setPhysicalNamingStrategy​(PhysicalNamingStrategy physicalNamingStrategy)

      • configure

        public Configuration configure​(java.lang.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.
        Parameters:
        resource - The resource to use
        Returns:
        this for method chaining
        Throws:
        HibernateException - Generally indicates we cannot find the named resource

      • getStandardServiceRegistryBuilder

        public StandardServiceRegistryBuilder getStandardServiceRegistryBuilder()
        Intended for internal testing use only!!!

      • configure

        public Configuration configure​(java.net.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

      • configure

        public Configuration configure​(java.io.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

      • registerTypeOverride

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

      • addFile

        public Configuration addFile​(java.lang.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(java.io.File)

      • addFile

        public Configuration addFile​(java.io.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.

      • add

        @Deprecated
public void add​(org.hibernate.internal.util.xml.XmlDocument metadataXml)
        Deprecated.
        No longer supported.

      • addCacheableFile

        public Configuration addCacheableFile​(java.io.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​(java.io.File xmlFile)
                                       throws SerializationException,
                                              java.io.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
        java.io.FileNotFoundException - Indicates that the cached file was not found or was not usable.

      • addCacheableFile

        public Configuration addCacheableFile​(java.lang.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:
        addCacheableFile(java.io.File)

      • addURL

        public Configuration addURL​(java.net.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

        @Deprecated
public Configuration addDocument​(org.w3c.dom.Document doc)
                          throws MappingException
        Deprecated.
        Use addURL, addResource, addFile, etc. instead
        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​(java.io.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

        @Deprecated
public Configuration addResource​(java.lang.String resourceName,
                                 java.lang.ClassLoader classLoader)
                          throws MappingException
        Deprecated.
        This form (accepting a ClassLoader) is no longer supported. Instead, add the ClassLoader to the ClassLoaderService on the ServiceRegistry associated with this Configuration
        Throws:
        MappingException

      • addResource

        public Configuration addResource​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.io.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​(java.io.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.

      • 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

      • setSessionFactoryObserver

        public void setSessionFactoryObserver​(SessionFactoryObserver sessionFactoryObserver)

      • 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 SessionFactory will not affect it.
        Parameters:
        serviceRegistry - The registry of services to be used in creating this session factory.
        Returns:
        The built SessionFactory
        Throws:
        HibernateException - usually indicates an invalid configuration or invalid mapping information

      • getSqlFunctions

        public java.util.Map<java.lang.String,​SQLFunction> getSqlFunctions()

      • addSqlFunction

        public void addSqlFunction​(java.lang.String functionName,
                           SQLFunction function)

      • addAttributeConverter

        public void addAttributeConverter​(java.lang.Class<? extends AttributeConverter> attributeConverterClass,
                                  boolean autoApply)
        Adds the AttributeConverter Class 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?

      • addAttributeConverter

        public void addAttributeConverter​(java.lang.Class<? extends AttributeConverter> attributeConverterClass)
        Adds the AttributeConverter Class to this Configuration.
        Parameters:
        attributeConverterClass - The AttributeConverter class.

      • addAttributeConverter

        public void addAttributeConverter​(AttributeConverter attributeConverter)
        Adds the AttributeConverter instance to this Configuration. This form is mainly intended for developers to programmatically add their own AttributeConverter instance. HEM, instead, uses the addAttributeConverter(Class, boolean) form
        Parameters:
        attributeConverter - The AttributeConverter instance.

      • addAttributeConverter

        public void addAttributeConverter​(AttributeConverter attributeConverter,
                                  boolean autoApply)
        Adds the AttributeConverter instance to this Configuration. This form is mainly intended for developers to programmatically add their own AttributeConverter instance. HEM, instead, uses the addAttributeConverter(Class, boolean) form
        Parameters:
        attributeConverter - The AttributeConverter instance.
        autoApply - Should the AttributeConverter be auto applied to property types as specified by its "entity attribute" parameterized type?

      • setSharedCacheMode

        public void setSharedCacheMode​(SharedCacheMode sharedCacheMode)
        Sets the SharedCacheMode to use. Note that at the moment, only SharedCacheMode.ALL has any effect in terms of hbm.xml binding.
        Parameters:
        sharedCacheMode - The SharedCacheMode to use

      • getNamedSQLQueries

        public java.util.Map getNamedSQLQueries()

      • getSqlResultSetMappings

        public java.util.Map getSqlResultSetMappings()

      • getNamedQueries

        public java.util.Map<java.lang.String,​NamedQueryDefinition> getNamedQueries()

      • buildMappings

        @Deprecated
public void buildMappings()
        Deprecated.
        Does nothing

      • mergeProperties

        public Configuration mergeProperties​(java.util.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