An instance of net.sf.hibernate.cfg.Configuration represents an entire set of mappings of an application's Java types to a SQL database. The Configuration is used to build a (immutable)` SessionFactory. The mappings are compiled from various XML mapping files.

You may obtain a Configuration instance by instantiating it directly. Heres an example of setting up a datastore from mappings defined in two XML configuration files (in the classpath):

Configuration cfg = new Configuration()
    .addFile("Item.hbm.xml")
    .addFile("Bid.hbm.xml");

An alternative (sometimes better) way is to let Hibernate load a mapping file using getResourceAsStream():

Configuration cfg = new Configuration()
    .addClass(org.hibernate.auction.Item.class)
    .addClass(org.hibernate.auction.Bid.class);

Then Hibernate will look for mapping files named /org/hibernate/autcion/Item.hbm.xml and /org/hibernate/autcion/Bid.hbm.xml in the classpath. This approach eliminates any hardcoded filenames.

A Configuration also specifies various optional properties:

Properties props = new Properties();
...
Configuration cfg = new Configuration()
    .addClass(org.hibernate.auction.Item.class)
    .addClass(org.hibernate.auction.Bid.class)
    .setProperties(props);

A Configuration is intended as a configuration-time object, to be discarded once a SessionFactory is built.

When all mappings have been parsed by the Configuration, the application must obtain a factory for Session instances. This factory is intended to be shared by all application threads:

SessionFactory sessions = cfg.buildSessionFactory();

However, Hibernate does allow your application to instantiate more than one SessionFactory. This is useful if you are using more than one database.

A SessionFactory may open a Session on a user-provided JDBC connection. This design choice frees the application to obtain JDBC connections wherever it pleases:

java.sql.Connection conn = datasource.getConnection();
Session session = sessions.openSession(conn);

// do some data access work

The application must be careful not to open two concurrent Sessions on the same JDBC connection!

Alternatively, you can have the SessionFactory open connections for you. The SessionFactory must be provided with JDBC connection properties in one of the following ways:

If you take this approach, opening a Session is as simple as:

Session session = sessions.openSession(); // open a new Session
// do some data access work, a JDBC connection will be used on demand

All Hibernate property names and semantics are defined on the class net.sf.hibernate.cfg.Environment. We will now describe the most important settings for JDBC connection configuration.

Hibernate will obtain (and pool) connections using java.sql.DriverManager if you set the following properties:

Hibernate's own connection pooling algorithm is quite rudimentary. It is intended to help you get started and is not intended for use in a production system or even for performance testing. Use a third party pool for best performance and stability, i.e., replace the hibernate.connection.pool_size property with connection pool specific settings.

C3P0 is an open source JDBC connection pool distributed along with Hibernate in the lib directory. Hibernate will use the built-in C3P0ConnectionProvider for connection pooling if you set the hibernate.c3p0.* properties. There is also built-in support for Apache DBCP and for Proxool. You must set the properties hibernate.dbcp.* (DBCP connection pool properties) to enable the DBCPConnectionProvider. Prepared statement caching is enabled (highly recommend) if hibernate.dbcp.ps.* (DBCP statement cache properties) are set. Please refer the the Apache commons-pool documentation for the interpretation of these properties. You should set the hibernate.proxool.* properties if you wish to use Proxool.

This is an example using C3P0:

hibernate.connection.driver_class = org.postgresql.Driver
hibernate.connection.url = jdbc:postgresql://localhost/mydatabase
hibernate.connection.username = myuser
hibernate.connection.password = secret
hibernate.c3p0.min_size=5
hibernate.c3p0.max_size=20
hibernate.c3p0.timeout=1800
hibernate.c3p0.max_statements=50
hibernate.dialect = net.sf.hibernate.dialect.PostgreSQLDialect

For use inside an application server, Hibernate may obtain connections from a javax.sql.Datasource registered in JNDI. Set the following properties:

This is an example using an application server provided JNDI datasource:

hibernate.connection.datasource = java:/comp/env/jdbc/MyDB
hibernate.transaction.factory_class = \
    net.sf.hibernate.transaction.JTATransactionFactory
hibernate.transaction.manager_lookup_class = \
    net.sf.hibernate.transaction.JBossTransactionManagerLookup
hibernate.dialect = \
    net.sf.hibernate.dialect.PostgreSQLDialect

JDBC connections obtained from a JNDI datasource will automatically participate in the container-managed transactions of the application server.

Arbitrary connection properties may be given by prepending "hibernate.connnection" to the property name. For example, you may specify a charSet using hibernate.connnection.charSet.

You may define your own plugin strategy for obtaining JDBC connections by implementing the interface net.sf.hibernate.connection.ConnectionProvider. You may select a custom implementation by setting hibernate.connection.provider_class.

There are a number of other properties that control the behaviour of Hibernate at runtime. All are optional and have reasonable default values.

System-level properties can only be set via java -Dproperty=value or be defined in hibernate.properties and not with an instance of Properties passed to the Configuration.

hibernate.query.substitutions true=1, false=0

hibernate.query.substitutions toLowercase=LOWER

Hibernate logs various events using Apache commons-logging.

The commons-logging service will direct output to either Apache Log4j (if you include log4j.jar in your classpath) or JDK1.4 logging (if running under JDK1.4 or above). You may download Log4j from http://jakarta.apache.org. To use Log4j you will need to place a log4j.properties file in your classpath, an example properties file is distributed with Hibernate in the src/ directory.

We strongly recommend that you familiarize yourself with Hibernate's log messages. A lot of work has been put into making the Hibernate log as detailed as possible, without making it unreadable. It is an essential troubleshooting device. Also don't forget to enable SQL logging as described above (hibernate.show_sql), it is your first step when looking for performance problems.

The interface net.sf.hibernate.cfg.NamingStrategy allows you to specify a "naming standard" for database objects and schema elements.

You may provide rules for automatically generating database identifiers from Java identifiers or for processing "logical" column and table names given in the mapping file into "physical" table and column names. This feature helps reduce the verbosity of the mapping document, eliminating repetitive noise (TBL_ prefixes, for example). The default strategy used by Hibernate is quite minimal.

You may specify a different strategy by calling Configuration.setNamingStrategy() before adding mappings:

SessionFactory sf = new Configuration()
    .setNamingStrategy(ImprovedNamingStrategy.INSTANCE)
    .addFile("Item.hbm.xml")
    .addFile("Bid.hbm.xml")
    .buildSessionFactory();

net.sf.hibernate.cfg.ImprovedNamingStrategy is a built-in strategy that might be a useful starting point for some applications.

An alternative approach is to specify a full configuration in a file named hibernate.cfg.xml. This file can be used as a replacement for the hibernate.properties file or, if both are present, override properties.

The XML configuration file is by default expected to be in the root o your CLASSPATH. Here is an example:

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
        "-//Hibernate/Hibernate Configuration DTD 2.0//EN"

 "http://hibernate.sourceforge.net/hibernate-configuration-2.0.dtd">

<hibernate-configuration>

    <!-- a SessionFactory instance listed as /jndi/name -->
    <session-factory
        name="java:comp/env/hibernate/SessionFactory">

        <!-- properties -->
        <property name="connection.datasource">my/first/datasource</property>
        <property name="dialect">net.sf.hibernate.dialect.MySQLDialect</property>
        <property name="show_sql">false</property>
        <property name="use_outer_join">true</property>
        <property name="transaction.factory_class">
            net.sf.hibernate.transaction.JTATransactionFactory
        </property>
        <property name="jta.UserTransaction">java:comp/UserTransaction</property>

        <!-- mapping files -->
        <mapping resource="org/hibernate/auction/Item.hbm.xml"/>
        <mapping resource="org/hibernate/auction/Bid.hbm.xml"/>

    </session-factory>

</hibernate-configuration>

Configuring Hibernate is then as simple as

SessionFactory sf = new Configuration().configure().buildSessionFactory();

You can pick a different XML configuration file using

SessionFactory sf = new Configuration()
    .configure("/my/package/catdb.cfg.xml")
    .buildSessionFactory();