<?xml version="1.0" encoding="UTF-8"?>

<!--
  ~ Hibernate, Relational Persistence for Idiomatic Java
  ~
  ~ License: GNU Lesser General Public License (LGPL), version 2.1 or later.
  ~ See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
  -->
<chapter xml:id="session-configuration" revision="1" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
    <title>Bootstrapping</title>

    <abstract>
        This chapter discusses the methods and options for bootstrapping Hibernate.
    </abstract>


    <para>
        The discussion of "bootstrapping Hibernate" is really 2 different discussions depending on
        whether the application wants to bootstrap a JPA EntityManagerFactory or a native Hibernate
        SessionFactory.  Each topic is discussed in detail in its own topical guide:
        <citetitle pubwork="article">Bootstrapping Hibernate JPA</citetitle> for bootrapping a JPA EntityManagerFactory,
        and <citetitle pubwork="article">Native Bootstrapping</citetitle> for bootstrapping a native Hibernate
        SessionFactory.  These topical guides discuss the various API calls involved in detail; this
        discussion will focus on the various settings and their effect.
    </para>

    <para>
        Most of the available settings for native bootstrapping are exposed as constants on the
        <interfacename>org.hibernate.cfg.AvailableSettings</interfacename> interface.  Most of the available
        settings for JPA bootstrapping (beyond the native ones) are exposed as constants on the
        <interfacename>org.hibernate.jpa.AvailableSettings</interfacename> interface.  Each setting
        is explained individually in detail in the javadoc.  Those javadocs are the authoritative source for the
        discussion of each individual setting.  The focus of this chapter is more about groupings of settings and
        values to achieve certain goals.
    </para>

    <important>
        <para>
            The Hibernate team have made a concerted effort in recent releases to begin removing the need for users
            to name Hibernate classes by FQN in configurations.  The reason being that referencing Hibernate classes
            by FQN can cause troubles when upgrading between releases where those class have undergone refactoring.
            We call this improvement "short naming".  Whenever possible, users should prefer to use short names for
            configuration values over Hibernate class FQNs.
        </para>
    </important>

    <section xml:id="bootstrap-connectionprovider">
        <title>ConnectionProvider</title>
        <para>
            As an ORM tool, probably the single most important thing you need to tell Hibernate is how to connect to
            your database.  This is ultimately the function of the <interfacename>org.hibernate.engine.jdbc.connections.spi.ConnectionProvider</interfacename>
            interface.  Every SessionFactory or EntityManagerFactory an application ever builds will contain
            a ConnectionProvider (unless the application is using Hibernate's multi-tenancy support, which is currently
            beyond the scope of this documentation).  ConnectionProvider is an interface; Hibernate provides some
            out of the box implementations of this interface.  ConnectionProvider is also an extension point, so
            you can also use custom implementations from third parties or written yourself.  The ConnectionProvider
            to use is defined by the <literal>hibernate.connection.provider_class</literal> setting.  See
            the <interfacename>org.hibernate.cfg.AvailableSettings#CONNECTION_PROVIDER</interfacename>
        </para>

        <para>
            Generally speaking applications should not have to configure a ConnectionProvider explicitly if using
            one of the Hibernate-provided implementations.  Hibernate will internally determine which ConnectionProvider
            to use based on the following algorithm:

            <orderedlist spacing="compact">
                <listitem>
                    <para>
                        If <literal>hibernate.connection.provider_class</literal> is set, it takes precedence
                    </para>
                </listitem>
                <listitem>
                    <para>
                        else if <literal>hibernate.connection.datasource</literal> is set -> <xref linkend="bootstrap-connectionprovider-datasource"/>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        else if any setting prefixed by <literal>hibernate.c3p0.</literal> is set -> <xref linkend="bootstrap-connectionprovider-c3p0"/>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        else if any setting prefixed by <literal>hibernate.proxool.</literal> is set -> <xref linkend="bootstrap-connectionprovider-proxool"/>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        else if any setting prefixed by <literal>hibernate.hikari.</literal> is set -> <xref linkend="bootstrap-connectionprovider-hikari"/>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        else if <literal>hibernate.connection.url</literal> is set -> <xref linkend="bootstrap-connectionprovider-drivermanager"/>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        else -> <xref linkend="bootstrap-connectionprovider-provided"/>
                    </para>
                </listitem>
            </orderedlist>

        </para>


        <section xml:id="bootstrap-connectionprovider-datasource">
            <title>Using DataSources</title>

            <para>
                Hibernate can integrate with a <interfacename>javax.sql.DataSource</interfacename> for obtaining
                JDBC Connections.  Applications would tell Hibernate about the DataSource via the (required)
                <literal>hibernate.connection.datasource</literal> setting which can either specify a JNDI name
                or would reference the actual DataSource instance.  For cases where a JNDI namespace is specified, be
                sure to read <xref linkend="bootstrap-jndi"/>.
            </para>

            <note>
                <para>
                    For JPA applications, note that <literal>hibernate.connection.datasource</literal> corresponds to
                    either <literal>javax.persistence.jtaDataSource</literal> or <literal>javax.persistence.nonJtaDataSource</literal>.
                </para>
            </note>

            <para>
                The DataSource ConnectionProvider also (optionally) accepts the <literal>hibernate.connection.username</literal>
                and <literal>hibernate.connection.password</literal>.  If specified, the form of DataSource#getConnection
                accepting username and password will be used.  Otherwise the no-arg form is used.
            </para>
        </section>

        <section xml:id="bootstrap-connectionprovider-c3p0">
            <title>Using c3p0</title>

            <important>
                <para>
                    To use this integration, the application must include the hibernate-c3p0
                    module jar (as well as its dependencies) on the classpath.
                </para>
            </important>

            <para>
                Hibernate also provides support for applications to use <link xlink:href="http://www.mchange.com/projects/c3p0/">c3p0</link>
                connection pooling.  When using this c3p0 support, a number of additional configuration settings
                are recognized.
            </para>

            <variablelist>
                <title>Additional settings</title>
                <varlistentry>
                    <term><literal>hibernate.connection.driver_class</literal></term>
                    <listitem>
                        <para>
                            The name of the JDBC Driver class to use
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><literal>hibernate.connection.url</literal></term>
                    <listitem>
                        <para>
                            The JDBC connection url.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>Any settings prefixed with <literal>hibernate.connection.</literal> (other than the "special ones")</term>
                    <listitem>
                        <para>
                            These all have the <literal>hibernate.connection.</literal> prefix stripped and the
                            rest will be passed as JDBC connection properties
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><literal>hibernate.c3p0.min_size</literal> or <literal>c3p0.minPoolSize</literal></term>
                    <listitem>
                        <para>
                            The minimum size of the c3p0 pool.  See <link xlink:href="http://www.mchange.com/projects/c3p0/#minPoolSize"/>
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><literal>hibernate.c3p0.max_size</literal> or <literal>c3p0.maxPoolSize</literal></term>
                    <listitem>
                        <para>
                            The maximum size of the c3p0 pool.  See <link xlink:href="http://www.mchange.com/projects/c3p0/#maxPoolSize"/>
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><literal>hibernate.c3p0.timeout</literal> or <literal>c3p0.maxIdleTime</literal></term>
                    <listitem>
                        <para>
                            The Connection idle time.  See <link xlink:href="http://www.mchange.com/projects/c3p0/#maxIdleTime"/>
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><literal>hibernate.c3p0.max_statements</literal> or <literal>c3p0.maxStatements</literal></term>
                    <listitem>
                        <para>
                            Controls the c3p0 PreparedStatement cache size (if using).  See <link xlink:href="http://www.mchange.com/projects/c3p0/#maxStatements"/>
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><literal>hibernate.c3p0.acquire_increment</literal> or <literal>c3p0.acquireIncrement</literal></term>
                    <listitem>
                        <para>
                            Number of connections c3p0 should acquire at a time when pool is exhauted.  See <link xlink:href="http://www.mchange.com/projects/c3p0/#acquireIncrement"/>
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><literal>hibernate.c3p0.idle_test_period</literal> or <literal>c3p0.idleConnectionTestPeriod</literal></term>
                    <listitem>
                        <para>
                            Idle time before a c3p0 pooled connection is validated.  See <link xlink:href="http://www.mchange.com/projects/c3p0/#idleConnectionTestPeriod"/>
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><literal>c3p0.initialPoolSize</literal></term>
                    <listitem>
                        <para>
                            The initial c3p0 pool size.  If not specified, default is to use the min pool size.
                            See <link xlink:href="http://www.mchange.com/projects/c3p0/#initialPoolSize"/>
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>Any other settings prefixed with <literal>hibernate.c3p0.</literal></term>
                    <listitem>
                        <para>
                            Will have the <literal>hibernate.</literal> portion stripped and be passed to c3p0.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>Any other settings prefixed with <literal>c3p0.</literal></term>
                    <listitem>
                        <para>
                            Get passed to c3p0 as is.  See <link xlink:href="http://www.mchange.com/projects/c3p0/#configuration"/>
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </section>

        <section xml:id="bootstrap-connectionprovider-proxool">
            <title>Using Proxool</title>

            <important>
                <para>
                    To use this integration, the application must include the hibernate-proxool
                    module jar (as well as its dependencies) on the classpath.
                </para>
            </important>

            <para>
                Hibernate also provides support for applications to use <link xlink:href="http://proxool.sourceforge.net/">Proxool</link>
                connection pooling.
            </para>

            <section xml:id="bootstrap-connectionprovider-proxool-existing">
                <title>Using existing Proxool pools</title>

                <para>
                    Controlled by the <literal>hibernate.proxool.existing_pool</literal> setting.  If set to true,
                    this ConnectionProvider will use an already existing Proxool pool by alias as indicated by
                    the <literal>hibernate.proxool.pool_alias</literal> setting
                </para>
            </section>

            <section xml:id="bootstrap-connectionprovider-proxool-jaxp">
                <title>Configuring Proxool via XML</title>

                <para>
                    The <literal>hibernate.proxool.xml</literal> setting names a Proxool configuration XML
                    file to be loaded as a classpath resource and loaded by Proxool's JAXPConfigurator.
                    See <link xlink:href="http://proxool.sourceforge.net/configure.html"/>.
                    <literal>hibernate.proxool.pool_alias</literal> must be set to indicate which pool to use.
                </para>
            </section>

            <section xml:id="bootstrap-connectionprovider-proxool-properties">
                <title>Configuring Proxool via Properties</title>

                <para>
                    The <literal>hibernate.proxool.properties</literal> setting names a Proxool configuration Properties
                    file to be loaded as a classpath resource and loaded by Proxool's PropertyConfigurator.
                    See <link xlink:href="http://proxool.sourceforge.net/configure.html"/>.
                    <literal>hibernate.proxool.pool_alias</literal> must be set to indicate which pool to use.
                </para>

            </section>
        </section>

        <section xml:id="bootstrap-connectionprovider-hikari">
            <title>Using Hikari</title>

            <important>
                <para>
                    To use this integration, the application must include the hibernate-hikari
                    module jar (as well as its dependencies) on the classpath.
                </para>
            </important>

            <para>
                Hibernate also provides support for applications to use
                <link xlink:href="http://brettwooldridge.github.io/HikariCP/">Hikari</link> connection pool.
            </para>

            <para>
                Set all of your Hikari settings in Hibernate prefixed by <literal>hibernate.hikari.</literal>
                and this ConnectionProvider will pick them up and pass them along to Hikari.  Additionally, this
                ConnectionProvider will pick up the following Hibernate-specific properties and map
                them to the corresponding Hikari ones (any <literal>hibernate.hikari.</literal> prefixed ones have precedence):
            </para>

            <variablelist>
                <title>Hibernate-specific properties recognized by Hikari ConnectionProvider</title>
                <varlistentry>
                    <term><literal>hibernate.connection.driver_class</literal></term>
                    <listitem>
                        <para>Mapped to Hikari's <literal>driverClassName</literal> setting</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><literal>hibernate.connection.url</literal></term>
                    <listitem>
                        <para>Mapped to Hikari's <literal>jdbcUrl</literal> setting</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><literal>hibernate.connection.username</literal></term>
                    <listitem>
                        <para>Mapped to Hikari's <literal>username</literal> setting</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><literal>hibernate.connection.password</literal></term>
                    <listitem>
                        <para>Mapped to Hikari's <literal>password</literal> setting</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><literal>hibernate.connection.isolation</literal></term>
                    <listitem>
                        <para>Mapped to Hikari's <literal>transactionIsolation</literal> setting</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term><literal>hibernate.connection.autocommit</literal></term>
                    <listitem>
                        <para>Mapped to Hikari's <literal>autoCommit</literal> setting</para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </section>

        <section xml:id="bootstrap-connectionprovider-drivermanager">
            <title>Using Hibernate's built-in (and unsupported) pooling</title>

            <important>
                <para>
                    The built-in connection pool is not supported supported for use.
                </para>
            </important>

            <para>
                This section is here just for completeness.
            </para>
        </section>

        <section xml:id="bootstrap-connectionprovider-provided">
            <title>User-provided Connections</title>

            <para>
                It is possible to use Hibernate by simply passing a Connection to use to the Session when the Session
                is opened.  This usage is discouraged and not discussed here.
            </para>
        </section>
    </section>

    <section xml:id="bootstrap-dialect">
        <title>Database Dialect</title>

        <para>
            All databases vary from the ANSI standard to some degree.  Each database's variance makes up its dialect.
            Hibernate needs to understand how to talk to your specific database.  That is the function of
            the <interfacename>org.hibernate.dialect.Dialect</interfacename> (in conjunction with information from
            <interfacename>java.sql.DatabaseMetaData</interfacename>).
        </para>

        <para>
            In most cases Hibernate will be able to determine the proper Dialect to use by asking some questions
            of the JDBC Connection during bootstrap.  If for some reason it is not able to determine the proper one
            or you want to use a custom Dialect, you will need to set the <literal>hibernate.dialect</literal> setting.
        </para>

        <para>
            <!-- todo : document short-names -->
            TODO : document short names
        </para>
    </section>

    <section xml:id="bootstrap-txn">
        <title>Transaction configuration</title>

        <para>
            Transaction handling per Session is handled by the <interfacename>org.hibernate.resource.transaction.TransactionCoordinator</interfacename>
            contract, which are built by the <interfacename>org.hibernate.resource.transaction.TransactionCoordinatorBuilder</interfacename>
            service.  TransactionCoordinatorBuilder represents a strategy for dealing with transactions whereas
            TransactionCoordinator represents one instance of that strategy related to a Session.  Which
            TransactionCoordinatorBuilder implementation to use is defined by the <literal>hibernate.transaction.coordinator_class</literal>
            setting.
        </para>

        <itemizedlist>
            <title>Hibernate-provided TransactionCoordinatorBuilder implementations</title>
            <listitem>
                <para>
                    <literal>jdbc</literal> (the default) - Manages transactions via calls to <interfacename>java.sql.Connection</interfacename>
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>jta</literal> - Manages transactions via JTA.  See <xref linkend="bootstrap-jtaplatform"/>
                </para>
            </listitem>
        </itemizedlist>
    </section>

    <section xml:id="bootstrap-jtaplatform">
        <title>JTA configuration</title>

        <para>
            Interaction with a JTA system is consolidated behind a single contract named
            <interfacename>org.hibernate.engine.transaction.jta.platform.spi.JtaPlatform</interfacename> which
            exposes access to the <interfacename>javax.transaction.TransactionManager</interfacename> and
            <interfacename>javax.transaction.UserTransaction</interfacename> for that system as well as exposing
            the ability to register <interfacename>javax.transaction.Synchronization</interfacename> instances,
            check transaction status, etc.
        </para>

        <para>
            Hibernate tries to discover the JtaPlatform it should use through the use of another service named
            <interfacename>org.hibernate.engine.transaction.jta.platform.spi.JtaPlatformResolver</interfacename>.
            If that resolution does not work, or if you wish to provide a custom implementation you will need to
            specify the <literal>hibernate.transaction.jta.platform</literal> setting.  Hibernate provides many
            implementations of the JtaPlatform contract, all with short-names:
        </para>

        <itemizedlist>
            <title>Built-in JtaPlatform implementations by short name</title>
            <listitem>
                <para>
                    <literal>Borland</literal> - JtaPlatform for the Borland Enterprise Server.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>Bitronix</literal> - JtaPlatform for Bitronix.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>JBossAS</literal> - JtaPlatform for Arjuna/JBossTransactions/Narnya when used within the JBoss/WildFly Application Server.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>JBossTS</literal> - JtaPlatform for Arjuna/JBossTransactions/Narnya when used standalone.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>JOnAS</literal> - JtaPlatform for JOTM when used within JOnAS.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>JOTM</literal> - JtaPlatform for JOTM when used standalone.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>JRun4</literal> - JtaPlatform for the JRun 4 Application Server.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>OC4J</literal> - JtaPlatform for Oracle's OC4J container.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>Orion</literal> - JtaPlatform for the Orion Application Server.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>Resin</literal> - JtaPlatform for the Resin Application Server.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>SunOne</literal> - JtaPlatform for the SunOne Application Server.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>Weblogic</literal> - JtaPlatform for the Weblogic Application Server.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>WebSphere</literal> - JtaPlatform for older versions of the WebSphere Application Server.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>WebSphereExtended</literal> - JtaPlatform for newer versions of the WebSphere Application Server.
                </para>
            </listitem>
        </itemizedlist>
    </section>

    <section xml:id="bootstrap-jndi">
        <title>JNDI configuration</title>

        <para>
            Hibernate's JNDI capabilities are represented by the <interfacename>org.hibernate.engine.jndi.spi.JndiService</interfacename>
            contract.  The default implementation assumes that anything it is asked to retrieve from JNDI comes from
            the same JNDI root context.  If that is not the case in your set up you will need to supply a custom
            JndiService implementation.
        </para>

        <variablelist>
            <title>Settings recognized by the default JndiService implementation</title>
            <varlistentry>
                <term><literal>hibernate.jndi.class</literal></term>
                <listitem>
                    <para>
                        Names the JNDI <interfacename>javax.naming.spi.InitialContextFactory</interfacename>
                        implementation class to use.  Leave null to pick up the system default, if one.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><literal>hibernate.jndi.url</literal></term>
                <listitem>
                    <para>
                        Names the JNDI <interfacename>javax.naming.InitialContext</interfacename> url.
                        Leave null to pick up the system default, if one.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Any other settings prefixed with <literal>hibernate.jndi.</literal></term>
                <listitem>
                    <para>
                        The <literal>hibernate.jndi.</literal> prefix will be stripped off and the value
                        passed in while obtaining the <interfacename>javax.naming.InitialContext</interfacename>
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </section>


    <section xml:id="bootstrap-l2cache">
        <title>Second level caching</title>

        <para>
            Hibernate defines the ability to integrate with pluggable providers for the purpose of
            caching data outside the context of a particular Session.  This section defines
            the settings which control that behavior.
        </para>

        <section xml:id="bootstrap-l2cache-provider">
            <title>RegionFactory</title>
            <para>
                <interfacename>org.hibernate.cache.spi.RegionFactory</interfacename> defines the integration
                between Hibernate and a pluggable caching provider.  <literal>hibernate.cache.region.factory_class</literal>
                is used to declare the provider to use.  Hibernate comes with support for 2 popular caching
                libraries: Ehcache and Infinispan.
            </para>

            <section xml:id="bootstrap-l2cache-provider-ehcache">
                <title>Ehcache</title>
                <important>
                    <para>
                        Use of the build-in integration for Ehcache requires that the hibernate-ehcache module
                        jar (and all of its dependencies) are on the classpath.
                    </para>
                </important>
                <para>
                    The hibernate-ehcache module defines 2 specific providers:
                    <itemizedlist>
                        <listitem>
                            <para>
                                <!-- todo : document -->
                                <literal>ehcache</literal> - todo : document
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <!-- todo : document -->
                                <literal>ehcache-singleton</literal> - todo : document
                            </para>
                        </listitem>
                    </itemizedlist>
                </para>
            </section>

            <section xml:id="bootstrap-l2cache-provider-infinispan">
                <title>Infinispan</title>
                <important>
                    <para>
                        Use of the build-in integration for Infinispan requires that the hibernate-infinispan module
                        jar (and all of its dependencies) are on the classpath.
                    </para>
                </important>
                <para>
                    The hibernate-infinispan module defines 2 specific providers:
                    <itemizedlist>
                        <listitem>
                            <para>
                                <!-- todo : document -->
                                <literal>infinispan</literal> - todo : document
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <!-- todo : document -->
                                <literal>infinispan-jndi</literal> - todo : document
                            </para>
                        </listitem>
                    </itemizedlist>
                </para>
            </section>
        </section>

        <section xml:id="bootstrap-l2cache-behavior">
            <title>Caching behavior</title>

            <para>
                Besides specific provider configuration, there are a number of configurations options on the
                Hibernate side of the integration that control various caching behavior:
                <itemizedlist>
                    <listitem>
                        <literal>hibernate.cache.use_second_level_cache</literal> - Enable or disable
                        second level caching overall.  Default is true.
                    </listitem>
                    <listitem>
                        <literal>hibernate.cache.use_query_cache</literal> - Enable or disable second level
                        caching of query results.  Default is false.
                    </listitem>
                    <listitem>
                        <literal>hibernate.cache.query_cache_factory</literal> - Query result caching is
                        handled by a special contract that deals with staleness-based invalidation of the results.
                        The default implementation does not allow stale results at all.  Use this for applications
                        that would like to relax that.  Names an implementation of
                        <interfacename>org.hibernate.cache.spi.QueryCacheFactory</interfacename>
                    </listitem>
                    <listitem>
                        <literal>hibernate.cache.use_minimal_puts</literal> - Optimizes second-level cache
                        operations to minimize writes, at the cost of more frequent reads.  Providers typically
                        set this appropriately.
                    </listitem>
                    <listitem>
                        <literal>hibernate.cache.region_prefix</literal> - Defines a name to be used as a prefix to
                        all second-level cache region names.
                    </listitem>
                    <listitem>
                        <literal>hibernate.cache.default_cache_concurrency_strategy</literal> - In Hibernate
                        second-level caching, all regions can be configured differently including the concurrency
                        strategy to use when accessing the region.  This setting allows to define a default strategy to
                        be used.  This setting is very rarely required as the pluggable providers do specify the
                        default strategy to use.  Valid values include: <literal>read-only</literal>,
                        <literal>read-write</literal>, <literal>nonstrict-read-write</literal>,
                        <literal>transactional</literal>.
                    </listitem>
                    <listitem>
                        <literal>hibernate.cache.use_structured_entries</literal> - If <literal>true</literal>,
                        forces Hibernate to store data in the second-level cache in a more human-friendly format.
                        Can be useful if you'd like to be able to "browse" the data directly in your cache, but does
                        have a performance impact.
                    </listitem>
                    <listitem>
                        <literal>hibernate.cache.auto_evict_collection_cache</literal> - Enables or disables the
                        automatic eviction of a bi-directional association's collection cache entry when the association
                        is changed just from the owning side.  This is disabled by default, as it has a performance
                        impact to track this state.  However if your application does not manage both sides
                        of bi-directional association where the collection side is cached, the alternative is to
                        have stale data in that collection cache.
                    </listitem>
                </itemizedlist>
            </para>
        </section>
    </section>


    <section xml:id="bootstrap-stats">
        <title>Statistics and monitoring</title>

        <para>
            At the SessionFactory-level Hibernate provides a set of comprehensive statistics that
            it can collect for your application to help troubleshoot problems via its
            <interfacename>org.hibernate.stat.Statistics</interfacename> interface.  You can enable or disable
            Hibernate collecting this information by setting <literal>hibernate.generate_statistics</literal> to
            <literal>true</literal> or <literal>false</literal> (disabled is the default).
        </para>

        <para>
            At runtime these Statistics can be obtained by calling
            <interfacename>SessionFactory.getStatistics()</interfacename>.  Collecting these statistics can have a
            performance hit (we collect timings, etc).  To help alleviate that, the collection of statistics
            can be toggled at runtime by calling <interfacename>Statistics.setStatisticsEnabled</interfacename>
            with <literal>true</literal> or <literal>false</literal>.
        </para>

        <para>
            Hibernate also allows performance related monitoring at the Session level through the
            <interfacename>org.hibernate.SessionEventListener</interfacename> contract.  Multiple
            SessionEventListener may be associated with a given Session.  Hibernate provides one
            implementation out of the box that simply logs some useful statistics at the end of each Session.
            This implementation can be enabled by setting <literal>hibernate.session.events.log</literal> to
            <literal>true</literal> (it is <literal>false</literal> by default).
        </para>

        <para>
            An application can also provide its own SessionEventListener implementation.  To define a
            SessionEventListener that should apply to all Sessions, use the
            <literal>hibernate.session.events.auto</literal> setting.  The SessionEventListeners for a given Session
            can be further controlled when opening the Session via the <methodname>clearEventListeners</methodname>
            and <methodname>eventListeners</methodname> methods of
            <interfacename>org.hibernate.SessionBuilder</interfacename>
        </para>

        <para>
            For details, see <xref linkend="performance-monitoring"/>.
        </para>
    </section>


    <section xml:id="bootstrap-jdbcbatch">
        <title>JDBC batching</title>

        <para>
            JDBC offers support for batching together SQL statements that can be represented
            as a single PreparedStatement.  Implementation wise this generally means that drivers
            will send the batched operation to the server in one call, which can save on network calls
            to the database.  Hibernate can leverage JDBC batching.  The following settings control this
            behavior.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <literal>hibernate.jdbc.batch_size</literal> - Controls the maximum number of
                    statements Hibernate will batch together before asking the driver to execute
                    the batch.  Zero or a negative number disables this feature.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>hibernate.jdbc.batch_versioned_data</literal> - Some JDBC drivers
                    return incorrect row counts when a batch is executed.  If your JDBC driver
                    falls into this category this setting should be set to <literal>false</literal>.
                    Otherwise it is safe to enable this which will allow Hibernate to still
                    batch the DML for versioned entities and still use the returned row counts for
                    optimitic lock checks.  Currently defaults to false to be safe.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>hibernate.jdbc.batch.builder</literal> - Names the implementation class
                    used to manage batching capabilities.  It is almost never a good idea to switch from
                    Hibernate's default implementation.  But if you wish to, this setting would name the
                    <interfacename>org.hibernate.engine.jdbc.batch.spi.BatchBuilder</interfacename>
                    implementation to use.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>hibernate.order_updates</literal> - Forces Hibernate to order SQL updates by the
                    entity type and the primary key value of the items being updated. This allows for more batching
                    to be used.  It will also result in fewer transaction deadlocks in highly concurrent systems.
                    Comes with a performance hit, so benchmark before and after to see if this actually helps or
                    hurts your application.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>hibernate.order_inserts</literal> - Forces Hibernate to order inserts to allow for
                    more batching to be used.  Comes with a performance hit, so benchmark before and after to see
                    if this actually helps or hurts your application.
                </para>
            </listitem>
        </itemizedlist>
    </section>



    <section xml:id="bootstrap-schematooling">
        <title>Schema tooling</title>

        <para>
            Hibernate offers the ability to perform some schema management tasks for you including creating
            and dropping schemas, validating schemas and limited support for migrating schemas.
            The following settings control this behavior.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <literal>hibernate.hbm2ddl.auto</literal> - Tells Hibernate to automatically
                    perform the indicated schema management tasks when the SessionFactory is bootstrapped.
                </para>
                <itemizedlist>
                    <listitem>
                        <para>
                            <literal>create</literal> - Hibernate will drop and then create the necessary database
                            objects when the SessionFactory starts.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            <literal>create-drop</literal> - Hibernate will drop and then create the necessary database
                            objects when the SessionFactory starts.  It will also drop them when the SessionFactory ends.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            <literal>validate</literal> - Hibernate will validate that the database is compatible with
                            what you have told it about the database.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            <literal>update</literal> - Hibernate will alter an existing database making sure it looks
                            like what you said it should look like.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>
            <listitem>
                <para>
                    <literal>hibernate.hbm2dll.create_namespaces</literal> - Should Hibernate create/drop catalogs and
                    schemas as part of its create and drop processes?
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>hibernate.hbm2ddl.import_files</literal> - Comma-separated names of the optional files
                    containing additional SQL DML statements to be executed during the creation of the database.
                    The files are resolved by classpath resource lookup.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>hibernate.hbm2ddl.import_files_sql_extractor</literal> - The classname of a
                    custom <interfacename>org.hibernate.tool.hbm2ddl.ImportSqlCommandExtractor</interfacename>
                    implementation to be used to extract the commands from the indicated import files.  The default
                    implementation Hibernate uses assumes that each line is a command.  Hibernate also provides
                    an alternative implementation (<interfacename>org.hibernate.tool.hbm2ddl.MultipleLinesSqlCommandExtractor</interfacename>)
                    you can tell it to use which can read multi-line commands delimited by semicolon.  You could also
                    develop a custom ImportSqlCommandExtractor implementation and specify it here.
                </para>
            </listitem>
        </itemizedlist>
    </section>


    <section xml:id="bootstrap-query">
        <title>Query settings</title>

        <para>
            Multiple settings affect how Hibernate handles HQL, JPQL and native queries.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <literal>hibernate.query.factory_class</literal> - Names the
                    <interfacename>org.hibernate.hql.spi.QueryTranslatorFactory</interfacename> implementation to use.
                    QueryTranslatorFactory is responsible for parsing HQL.  It is generally best to accept Hibernate's
                    default implementation.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>hibernate.query.jpaql_strict_compliance</literal> - HQL is superset of JPQL.  This setting
                    tells the default QueryTranslatorFactory to strictly comply with the JPQL restrictions from the
                    JPA specification.  The default is to accept the HQL superset.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>hibernate.query.startup_check</literal> - By default, when the SessionFactory starts it
                    will cycle through all the named queries and validate them.  Setting this to <literal>false</literal>
                    tells Hibernate to skip that.  Useful mainly for some testing/development environment.
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>hibernate.query.plan_cache_max_size</literal> - Controls the maximum number of "plans"
                    Hibernate will cache in its <interfacename>org.hibernate.engine.query.spi.QueryPlanCache</interfacename>.
                    The default is 2048
                </para>
            </listitem>
            <listitem>
                <para>
                    <literal>hibernate.query.plan_parameter_metadata_max_size</literal> - Controls the maximum number of
                    <interfacename>org.hibernate.engine.query.spi.ParameterMetadata</interfacename> instances Hibernate
                    will maintain in its QueryPlanCache.  The default is 128.
                </para>
            </listitem>
        </itemizedlist>
    </section>


    <section xml:id="bootstrap-misc">
        <title>Miscellaneous settings</title>

        <para>
            There are a number of other properties that control the behavior of Hibernate at runtime.
        </para>

        <variablelist>
            <title>Miscellaneous settings</title>
            <varlistentry>
                <term><literal>hibernate.show_sql</literal></term>
                <listitem>
                    <para>
                        Write all SQL statements to stdout.  This is an alternative to setting the log
                        category <literal>org.hibernate.SQL</literal> to <literal>debug</literal>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><literal>hibernate.format_sql</literal></term>
                <listitem>
                    <para>
                        Pretty print the SQL in the log and console.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><literal>hibernate.default_catalog</literal></term>
                <listitem>
                    <para>
                        Defines an implicit catalog for any database objects (tables, sequences, etc) that
                        did not define one.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><literal>hibernate.default_schema</literal></term>
                <listitem>
                    <para>
                        Defines an implicit schema for any database objects (tables, sequences, etc) that
                        did not define one.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><literal>hibernate.session_factory_name</literal></term>
                <listitem>
                    <para>
                        Names a SessionFactory.  This is often important if using Hibernate in a cluster; the
                        "related" SessionFactory instances should share the same name on all nodes.  If
                        <literal>hibernate.session_factory_name_is_jndi</literal> is set to <literal>true</literal>
                        (the default) then the SessionFactory name is also taken as a JNDI name and Hibernate
                        will try to bind the SessionFactory into JNDI for you when the SessionFactory starts (and unbind
                        it when the SessionFactory closes).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><literal>hibernate.connection.release_mode</literal></term>
                <listitem>
                    <para>
                        Specifies when Hibernate should release JDBC connections. By default, a JDBC connection is
                        held until the session is explicitly closed or disconnected.  Occasionally this can lead to
                        problems in Java EE environments; this setting allows to control this behavior.  Allowed values
                        include:
                        <itemizedlist>
                            <listitem>
                                <para>
                                    <literal>on_close</literal> (the default) - release the Connection when the Session is closed.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    <literal>auto</literal> - chooses an appropriate release mode per the
                                    transaction strategy via the <methodname>getDefaultConnectionReleaseMode</methodname>
                                    method on TransactionCoordinatorBuilder.  Generally that means
                                    <literal>after_statement</literal> for JTA-based transaction strategies and
                                    <literal>after_transaction</literal> for JDBC-based strategies.
                                    See <xref linkend="bootstrap-txn"/>.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    <literal>after_transaction</literal> - release the Connection at the end of each
                                    transaction.  This is often useful for applications which hold a Session open
                                    during user think time.  This would allow the Connection to be released back into
                                    the pool prior to returning back to the user for their think time.
                                    Generally speaking this setting is not compatible with JTA DataSources.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    <literal>after_statement</literal> - aggressively release the Connection
                                    after the execution of each JDBC call.  This is sometimes useful with JTA DataSources
                                    in containers.  If you see errors or warnings from your container regarding leaked
                                    Connections (and you are sure your code is closing Sessions) you may need this setting.
                                </para>
                            </listitem>
                        </itemizedlist>
                    </para>

                    <note>
                        <para>
                            This setting only affects Sessions opened manually from the SessionFactory.  For "current Sessions"
                            the CurrentSessionContext controls the release mode.  See <xref linkend="architecture-current-session" />
                        </para>
                    </note>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><literal></literal></term>
                <listitem>
                    <para>

                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><literal></literal></term>
                <listitem>
                    <para>

                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </section>



          <row>
            <entry><property>hibernate.max_fetch_depth</property></entry>

            <entry>Sets a maximum "depth" for the outer join fetch tree for
            single-ended associations (one-to-one, many-to-one). A
            <literal>0</literal> disables default outer join fetching. <para>
            <emphasis role="strong">e.g.</emphasis> recommended values between
            <literal>0</literal> and <literal>3</literal> </para></entry>
          </row>

          <row>
            <entry><property>hibernate.default_batch_fetch_size</property></entry>

            <entry>Sets a default size for Hibernate batch fetching of
            associations. <para> <emphasis role="strong">e.g.</emphasis>
            recommended values <literal>4</literal>, <literal>8</literal>,
            <literal>16</literal> </para></entry>
          </row>

          <row>
            <entry><property>hibernate.default_entity_mode</property></entry>

            <entry>Sets a default mode for entity representation for all
            sessions opened from this <literal>SessionFactory</literal>,
            defaults to <literal>pojo</literal>.<para>
            <emphasis role="strong">e.g.</emphasis> <literal>dynamic-map</literal> |
            <literal>pojo</literal> </para> </entry>
          </row>


          <row>
            <entry><property>hibernate.use_identifier_rollback</property></entry>

            <entry>If enabled, generated identifier properties will be reset
            to default values when objects are deleted. <para> <emphasis
            role="strong">e.g.</emphasis> <literal>true</literal> |
            <literal>false</literal> </para></entry>
          </row>

          <row>
            <entry><property>hibernate.use_sql_comments</property></entry>

            <entry>If turned on, Hibernate will generate comments inside the
            SQL, for easier debugging, defaults to <literal>false</literal>.
            <para> <emphasis role="strong">e.g.</emphasis>
            <literal>true</literal> | <literal>false</literal> </para></entry>
          </row>

          <row>
            <entry><property>hibernate.id.new_generator_mappings</property></entry>

            <entry>Setting is relevant when using
            <classname>@GeneratedValue</classname>. It indicates whether or
            not the new <classname>IdentifierGenerator</classname>
            implementations are used for
            <classname>javax.persistence.GenerationType.AUTO</classname>,
            <classname>javax.persistence.GenerationType.TABLE</classname> and
            <classname>javax.persistence.GenerationType.SEQUENCE</classname>.
            Default to <literal>false</literal> to keep backward
            compatibility. <para> <emphasis role="strong">e.g.</emphasis>
            <literal>true</literal> | <literal>false</literal> </para></entry>
          </row>

    <note>
      <para>We recommend all new projects which make use of to use
      <classname>@GeneratedValue</classname> to also set
      <code>hibernate.id.new_generator_mappings=true</code> as the new
      generators are more efficient and closer to the JPA 2 specification
      semantic. However they are not backward compatible with existing
      databases (if a sequence or a table is used for id generation).</para>
    </note>

          <row>
            <entry><property>hibernate.jdbc.fetch_size</property></entry>

            <entry>A non-zero value determines the JDBC fetch size (calls
            <literal>Statement.setFetchSize()</literal>).</entry>
          </row>

          <row>
            <entry><property>hibernate.jdbc.use_scrollable_resultset</property></entry>

            <entry>Enables use of JDBC2 scrollable resultsets by Hibernate.
            This property is only necessary when using user-supplied JDBC
            connections. Hibernate uses connection metadata otherwise. <para>
            <emphasis role="strong">e.g.</emphasis> <literal>true</literal> |
            <literal>false</literal> </para></entry>
          </row>

          <row>
            <entry><property>hibernate.jdbc.use_streams_for_binary</property></entry>

            <entry>Use streams when writing/reading <literal>binary</literal>
            or <literal>serializable</literal> types to/from JDBC.
            <emphasis>*system-level property*</emphasis> <para> <emphasis
            role="strong">e.g.</emphasis> <literal>true</literal> |
            <literal>false</literal> </para></entry>
          </row>

          <row>
            <entry><property>hibernate.jdbc.use_get_generated_keys</property></entry>

            <entry>Enables use of JDBC3
            <literal>PreparedStatement.getGeneratedKeys()</literal> to
            retrieve natively generated keys after insert. Requires JDBC3+
            driver and JRE1.4+, set to false if your driver has problems with
            the Hibernate identifier generators. By default, it tries to
            determine the driver capabilities using connection metadata.
            <para> <emphasis role="strong">e.g.</emphasis>
            <literal>true|false</literal> </para></entry>
          </row>


    <row>
        <entry><literal>hibernate.current_session_context_class</literal></entry>

        <entry>Supply a custom strategy for the scoping of the "current"
            <literal>Session</literal>. See <xref
                    linkend="architecture-current-session" /> for more information
            about the built-in strategies. <para> <emphasis
                    role="strong">e.g.</emphasis> <literal>jta</literal> |
                <literal>thread</literal> | <literal>managed</literal> |
                <literal>custom.Class</literal> </para></entry>
    </row>


    <row>
        <entry><literal>hibernate.bytecode.use_reflection_optimizer</literal></entry>

        <entry><para>Enables the use of bytecode manipulation instead of
            runtime reflection. This is a System-level property and cannot be
            set in <literal>hibernate.cfg.xml</literal>. Reflection can
            sometimes be useful when troubleshooting. Hibernate always
            requires javassist even if you turn off the
            optimizer.</para><para> <emphasis role="strong">e.g.</emphasis>
            <literal>true</literal> | <literal>false</literal> </para></entry>
    </row>

    <row>
        <entry><literal>hibernate.bytecode.provider</literal></entry>

        <entry><para>At the moment, <literal>javassist</literal> is the only supported bytecode provider.</para><para> <emphasis
                role="strong">e.g.</emphasis> <literal>javassist</literal></para></entry>
    </row>



    <section xml:id="configuration-optional-outerjoin" revision="4">
      <title>Outer Join Fetching</title>

      <para>If your database supports ANSI, Oracle or Sybase style outer
      joins, <emphasis>outer join fetching</emphasis> will often increase
      performance by limiting the number of round trips to and from the
      database. This is, however, at the cost of possibly more work performed
      by the database itself. Outer join fetching allows a whole graph of
      objects connected by many-to-one, one-to-many, many-to-many and
      one-to-one associations to be retrieved in a single SQL
      <literal>SELECT</literal>.</para>

      <para>Outer join fetching can be disabled <emphasis>globally</emphasis>
      by setting the property <literal>hibernate.max_fetch_depth</literal> to
      <literal>0</literal>. A setting of <literal>1</literal> or higher
      enables outer join fetching for one-to-one and many-to-one associations
      that have been mapped with <literal>fetch="join"</literal>.</para>

      <para>See <xref linkend="performance-fetching" /> for more
      information.</para>
    </section>

    <section xml:id="configuration-optional-binarystreams" revision="1">
      <title>Binary Streams</title>

      <para>Oracle limits the size of <literal>byte</literal> arrays that can
      be passed to and/or from its JDBC driver. If you wish to use large
      instances of <literal>binary</literal> or
      <literal>serializable</literal> type, you should enable
      <literal>hibernate.jdbc.use_streams_for_binary</literal>. <emphasis>This
      is a system-level setting only.</emphasis></para>
    </section>

  </section>


  <section xml:id="configuration-namingstrategy">
    <title>Implementing a <literal>NamingStrategy</literal></title>

    <para>The interface <literal>org.hibernate.cfg.NamingStrategy</literal>
    allows you to specify a "naming standard" for database objects and schema
    elements.</para>

    <para>You can 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 (<literal>TBL_</literal> prefixes, for
    example). The default strategy used by Hibernate is quite minimal.</para>

    <para>You can specify a different strategy by calling
    <literal>Configuration.setNamingStrategy()</literal> before adding
    mappings:</para>

    <programlisting role="JAVA">SessionFactory sf = new Configuration()
    .setNamingStrategy(ImprovedNamingStrategy.INSTANCE)
    .addFile("Item.hbm.xml")
    .addFile("Bid.hbm.xml")
    .buildSessionFactory();</programlisting>

    <para><literal>org.hibernate.cfg.ImprovedNamingStrategy</literal> is a
    built-in strategy that might be a useful starting point for some
    applications.</para>
  </section>

  <section>
    <title>Implementing a PersisterClassProvider</title>

    <para>You can configure the persister implementation used to persist your
    entities and collections:</para>

    <itemizedlist>
      <listitem>
        <para>by default, Hibernate uses persisters that make sense in a
        relational model and follow Java Persistence's specification</para>
      </listitem>

      <listitem>
        <para>you can define a <classname>PersisterClassProvider</classname>
        implementation that provides the persister class used of a given
        entity or collection</para>
      </listitem>

      <listitem>
        <para>finally, you can override them on a per entity and collection
        basis in the mapping using <classname>@Persister</classname> or its
        XML equivalent</para>
      </listitem>
    </itemizedlist>

    <para>The latter in the list the higher in priority.</para>

    <para>You can pass the <classname>PersisterClassProvider</classname>
    instance to the <classname>Configuration</classname> object.</para>

    <programlisting role="JAVA">SessionFactory sf = new Configuration()
    .setPersisterClassProvider(customPersisterClassProvider)
    .addAnnotatedClass(Order.class)
    .buildSessionFactory();</programlisting>

    <para>The persister class provider methods, when returning a non null
    persister class, override the default Hibernate persisters. The entity
    name or the collection role are passed to the methods. It is a nice way to
    centralize the overriding logic of the persisters instead of spreading
    them on each entity or collection mapping. </para>
  </section>

  <section xml:id="configuration-xmlconfig" revision="2">
    <title>XML configuration file</title>

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

    <para>The XML configuration file is by default expected to be in the root
    of your <literal>CLASSPATH</literal>. Here is an example:</para>

    <programlisting role="XML">&lt;?xml version='1.0' encoding='utf-8'?&gt;
&lt;!DOCTYPE hibernate-configuration PUBLIC
    "-//Hibernate/Hibernate Configuration DTD//EN"
    "http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd"&gt;

&lt;hibernate-configuration&gt;

    &lt;!-- a SessionFactory instance listed as /jndi/name --&gt;
    &lt;session-factory
        name="java:hibernate/SessionFactory"&gt;

        &lt;!-- properties --&gt;
        &lt;property name="connection.datasource"&gt;java:/comp/env/jdbc/MyDB&lt;/property&gt;
        &lt;property name="dialect"&gt;org.hibernate.dialect.MySQLDialect&lt;/property&gt;
        &lt;property name="show_sql"&gt;false&lt;/property&gt;
        &lt;property name="transaction.factory_class"&gt;
            org.hibernate.transaction.JTATransactionFactory
        &lt;/property&gt;
        &lt;property name="jta.UserTransaction"&gt;java:comp/UserTransaction&lt;/property&gt;

        &lt;!-- mapping files --&gt;
        &lt;mapping resource="org/hibernate/auction/Item.hbm.xml"/&gt;
        &lt;mapping resource="org/hibernate/auction/Bid.hbm.xml"/&gt;

        &lt;!-- cache settings --&gt;
        &lt;class-cache class="org.hibernate.auction.Item" usage="read-write"/&gt;
        &lt;class-cache class="org.hibernate.auction.Bid" usage="read-only"/&gt;
        &lt;collection-cache collection="org.hibernate.auction.Item.bids" usage="read-write"/&gt;

    &lt;/session-factory&gt;

&lt;/hibernate-configuration&gt;</programlisting>

    <para>The advantage of this approach is the externalization of the mapping
    file names to configuration. The <literal>hibernate.cfg.xml</literal> is
    also more convenient once you have to tune the Hibernate cache. It is your
    choice to use either <literal>hibernate.properties</literal> or
    <literal>hibernate.cfg.xml</literal>. Both are equivalent, except for the
    above mentioned benefits of using the XML syntax.</para>

    <para>With the XML configuration, starting Hibernate is then as simple
    as:</para>

    <programlisting role="JAVA">SessionFactory sf = new Configuration().configure().buildSessionFactory();</programlisting>

    <para>You can select a different XML configuration file using:</para>

    <programlisting role="JAVA">SessionFactory sf = new Configuration()
    .configure("catdb.cfg.xml")
    .buildSessionFactory();</programlisting>
  </section>

</chapter>
