configuration.xml

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

<chapter xml:id="session-configuration" revision="1" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Configuration</title>

  <para>Hibernate is designed to operate in many different environments and,
  as such, there is a broad range of configuration parameters. Fortunately,
  most have sensible default values and Hibernate is distributed with an
  example <literal>hibernate.properties</literal> file in
  <literal>etc/</literal> that displays the various options. Simply put the
  example file in your classpath and customize it to suit your needs.</para>

  <section xml:id="configuration-programmatic" revision="1">
    <title>Programmatic configuration</title>

    <para>An instance of
    <classname>org.hibernate.cfg.Configuration</classname> represents an
    entire set of mappings of an application's Java types to an SQL database.
    The <classname>org.hibernate.cfg.Configuration</classname> is used to
    build an immutable
    <interfacename>org.hibernate.SessionFactory</interfacename>. The mappings
    are compiled from various XML mapping files.</para>

    <para>You can obtain a
    <classname>org.hibernate.cfg.Configuration</classname> instance by
    instantiating it directly and specifying XML mapping documents. If the
    mapping files are in the classpath, use <literal>addResource()</literal>.
    For example:</para>

    <programlisting role="JAVA">Configuration cfg = new Configuration()
    .addResource("Item.hbm.xml")
    .addResource("Bid.hbm.xml");</programlisting>

    <para>An alternative way is to specify the mapped class and allow
    Hibernate to find the mapping document for you:</para>

    <programlisting role="JAVA">Configuration cfg = new Configuration()
    .addClass(org.hibernate.auction.Item.class)
    .addClass(org.hibernate.auction.Bid.class);</programlisting>

    <para>Hibernate will then search for mapping files named
    <filename>/org/hibernate/auction/Item.hbm.xml</filename> and
    <filename>/org/hibernate/auction/Bid.hbm.xml</filename> in the classpath.
    This approach eliminates any hardcoded filenames.</para>

    <para>A <classname>org.hibernate.cfg.Configuration</classname> also allows
    you to specify configuration properties. For example:</para>

    <programlisting role="JAVA">Configuration cfg = new Configuration()
    .addClass(org.hibernate.auction.Item.class)
    .addClass(org.hibernate.auction.Bid.class)
    .setProperty("hibernate.dialect", "org.hibernate.dialect.MySQLInnoDBDialect")
    .setProperty("hibernate.connection.datasource", "java:comp/env/jdbc/test")
    .setProperty("hibernate.order_updates", "true");</programlisting>

    <para>This is not the only way to pass configuration properties to
    Hibernate. Some alternative options include:</para>

    <orderedlist spacing="compact">
      <listitem>
        <para>Pass an instance of <classname>java.util.Properties</classname>
        to <literal>Configuration.setProperties()</literal>.</para>
      </listitem>

      <listitem>
        <para>Place a file named <filename>hibernate.properties</filename> in
        a root directory of the classpath.</para>
      </listitem>

      <listitem>
        <para>Set <literal>System</literal> properties using <literal>java
        -Dproperty=value</literal>.</para>
      </listitem>

      <listitem>
        <para>Include <literal>&lt;property&gt;</literal> elements in
        <literal>hibernate.cfg.xml</literal> (this is discussed later).</para>
      </listitem>
    </orderedlist>

    <para>If you want to get started
    quickly<filename>hibernate.properties</filename> is the easiest
    approach.</para>

    <para>The <classname>org.hibernate.cfg.Configuration</classname> is
    intended as a startup-time object that will be discarded once a
    <literal>SessionFactory</literal> is created.</para>
  </section>

  <section xml:id="configuration-sessionfactory">
    <title>Obtaining a SessionFactory</title>

    <para>When all mappings have been parsed by the
    <classname>org.hibernate.cfg.Configuration</classname>, the application
    must obtain a factory for
    <interfacename>org.hibernate.Session</interfacename> instances. This
    factory is intended to be shared by all application threads:</para>

    <programlisting role="JAVA">SessionFactory sessions = cfg.buildSessionFactory();</programlisting>

    <para>Hibernate does allow your application to instantiate more than one
    <interfacename>org.hibernate.SessionFactory</interfacename>. This is
    useful if you are using more than one database.</para>
  </section>

  <section xml:id="configuration-hibernatejdbc" revision="1">
    <title>JDBC connections</title>

    <para>It is advisable to have the
    <interfacename>org.hibernate.SessionFactory</interfacename> create and
    pool JDBC connections for you. If you take this approach, opening a
    <interfacename>org.hibernate.Session</interfacename> is as simple
    as:</para>

    <programlisting role="JAVA">Session session = sessions.openSession(); // open a new Session</programlisting>

    <para>Once you start a task that requires access to the database, a JDBC
    connection will be obtained from the pool.</para>

    <para>Before you can do this, you first need to pass some JDBC connection
    properties to Hibernate. All Hibernate property names and semantics are
    defined on the class <classname>org.hibernate.cfg.Environment</classname>.
    The most important settings for JDBC connection configuration are outlined
    below.</para>

    <para>Hibernate will obtain and pool connections using
    <classname>java.sql.DriverManager</classname> if you set the following
    properties:</para>

    <table frame="topbot">
      <title>Hibernate JDBC Properties</title>

      <tgroup cols="2">
        <colspec colname="c1" colwidth="1*" />

        <colspec colname="c2" colwidth="1*" />

        <thead>
          <row>
            <entry>Property name</entry>

            <entry>Purpose</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry><property>hibernate.connection.driver_class</property></entry>

            <entry><emphasis>JDBC driver class</emphasis></entry>
          </row>

          <row>
            <entry><property>hibernate.connection.url</property></entry>

            <entry><emphasis>JDBC URL</emphasis></entry>
          </row>

          <row>
            <entry><property>hibernate.connection.username</property></entry>

            <entry><emphasis>database user</emphasis></entry>
          </row>

          <row>
            <entry><property>hibernate.connection.password</property></entry>

            <entry><emphasis>database user password</emphasis></entry>
          </row>

          <row>
            <entry><property>hibernate.connection.pool_size</property></entry>

            <entry><emphasis>maximum number of pooled
            connections</emphasis></entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <para>Hibernate's own connection pooling algorithm is, however, quite
    rudimentary. It is intended to help you get started and is <emphasis>not
    intended for use in a production system</emphasis>, or even for
    performance testing. You should use a third party pool for best
    performance and stability. Just replace the
    <property>hibernate.connection.pool_size</property> property with
    connection pool specific settings. This will turn off Hibernate's internal
    pool. For example, you might like to use c3p0.</para>

    <para>C3P0 is an open source JDBC connection pool distributed along with
    Hibernate in the <filename>lib</filename> directory. Hibernate will use
    its <classname>org.hibernate.connection.C3P0ConnectionProvider</classname>
    for connection pooling if you set <property>hibernate.c3p0.*</property>
    properties. If you would like to use Proxool, refer to the packaged
    <filename>hibernate.properties</filename> and the Hibernate web site for
    more information.</para>

    <para>The following is an example
    <filename>hibernate.properties</filename> file for c3p0:</para>

    <programlisting>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 = org.hibernate.dialect.PostgreSQL82Dialect</programlisting>

    <para>For use inside an application server, you should almost always
    configure Hibernate to obtain connections from an application server
    <interfacename>javax.sql.Datasource</interfacename> registered in JNDI.
    You will need to set at least one of the following properties:</para>

    <table frame="topbot">
      <title>Hibernate Datasource Properties</title>

      <tgroup cols="2">
        <colspec colname="c1" colwidth="1*" />

        <colspec colname="c2" colwidth="1*" />

        <thead>
          <row>
            <entry>Property name</entry>

            <entry>Purpose</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry><property>hibernate.connection.datasource</property></entry>

            <entry><emphasis>datasource JNDI name</emphasis></entry>
          </row>

          <row>
            <entry><property>hibernate.jndi.url</property></entry>

            <entry><emphasis>URL of the JNDI provider</emphasis>
            (optional)</entry>
          </row>

          <row>
            <entry><property>hibernate.jndi.class</property></entry>

            <entry><emphasis>class of the JNDI
            <literal>InitialContextFactory</literal></emphasis>
            (optional)</entry>
          </row>

          <row>
            <entry><property>hibernate.connection.username</property></entry>

            <entry><emphasis>database user</emphasis> (optional)</entry>
          </row>

          <row>
            <entry><property>hibernate.connection.password</property></entry>

            <entry><emphasis>database user password</emphasis>
            (optional)</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <para>Here is an example <filename>hibernate.properties</filename> file
    for an application server provided JNDI datasource:</para>

    <programlisting>hibernate.connection.datasource = java:/comp/env/jdbc/test
hibernate.transaction.factory_class = \
    org.hibernate.transaction.JTATransactionFactory
hibernate.transaction.manager_lookup_class = \
    org.hibernate.transaction.JBossTransactionManagerLookup
hibernate.dialect = org.hibernate.dialect.PostgreSQL82Dialect</programlisting>

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

    <para>Arbitrary connection properties can be given by prepending
    "<literal>hibernate.connection</literal>" to the connection property name.
    For example, you can specify a <property>charSet</property> connection
    property using <property>hibernate.connection.charSet</property>.</para>

    <para>You can define your own plugin strategy for obtaining JDBC
    connections by implementing the interface
    <interfacename>org.hibernate.connection.ConnectionProvider</interfacename>,
    and specifying your custom implementation via the
    <property>hibernate.connection.provider_class</property> property.</para>
  </section>

  <section xml:id="configuration-optional" revision="1">
    <title>Optional configuration properties</title>

    <para>There are a number of other properties that control the behavior of
    Hibernate at runtime. All are optional and have reasonable default
    values.</para>

    <para><warning>
        <para><emphasis>Some of these properties are "system-level"
        only.</emphasis> System-level properties can be set only via
        <literal>java -Dproperty=value</literal> or
        <filename>hibernate.properties</filename>. They
        <emphasis>cannot</emphasis> be set by the other techniques described
        above.</para>
      </warning></para>

    <table frame="topbot" xml:id="configuration-optional-properties" revision="8">
      <title>Hibernate Configuration Properties</title>

      <tgroup cols="2">
        <colspec colname="c1" colwidth="1*" />

        <colspec colname="c2" colwidth="1*" />

        <thead>
          <row>
            <entry>Property name</entry>

            <entry>Purpose</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry><property>hibernate.dialect</property></entry>

            <entry>The classname of a Hibernate
            <classname>org.hibernate.dialect.Dialect</classname> which allows
            Hibernate to generate SQL optimized for a particular relational
            database. <para> <emphasis role="strong">e.g.</emphasis>
            <literal>full.classname.of.Dialect</literal> </para> <para> In
            most cases Hibernate will actually be able to choose the correct
            <classname>org.hibernate.dialect.Dialect</classname>
            implementation based on the <literal>JDBC metadata</literal>
            returned by the JDBC driver. </para></entry>
          </row>

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

            <entry>Write all SQL statements to console. This is an alternative
            to setting the log category <literal>org.hibernate.SQL</literal>
            to <literal>debug</literal>. <para> <emphasis
            role="strong">e.g.</emphasis> <literal>true</literal> |
            <literal>false</literal> </para></entry>
          </row>

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

            <entry>Pretty print the SQL in the log and console. <para>
            <emphasis role="strong">e.g.</emphasis> <literal>true</literal> |
            <literal>false</literal> </para></entry>
          </row>

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

            <entry>Qualify unqualified table names with the given
            schema/tablespace in generated SQL. <para> <emphasis
            role="strong">e.g.</emphasis> <literal>SCHEMA_NAME</literal>
            </para></entry>
          </row>

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

            <entry>Qualifies unqualified table names with the given catalog in
            generated SQL. <para> <emphasis role="strong">e.g.</emphasis>
            <literal>CATALOG_NAME</literal> </para></entry>
          </row>

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

            <entry>The
            <interfacename>org.hibernate.SessionFactory</interfacename> will
            be automatically bound to this name in JNDI after it has been
            created. <para> <emphasis role="strong">e.g.</emphasis>
            <literal>jndi/composite/name</literal> </para></entry>
          </row>

          <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> <para>
            <literal>dynamic-map</literal>, <literal>dom4j</literal>,
            <literal>pojo</literal> </para></entry>
          </row>

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

            <entry>Forces Hibernate to order SQL updates by the primary key
            value of the items being updated. This will result in fewer
            transaction deadlocks in highly concurrent systems. <para>
            <emphasis role="strong">e.g.</emphasis> <literal>true</literal> |
            <literal>false</literal> </para></entry>
          </row>

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

            <entry>If enabled, Hibernate will collect statistics useful for
            performance tuning. <para> <emphasis role="strong">e.g.</emphasis>
            <literal>true</literal> | <literal>false</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>
        </tbody>
      </tgroup>
    </table>

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

    <table frame="topbot" xml:id="configuration-jdbc-properties" revision="8">
      <title>Hibernate JDBC and Connection Properties</title>

      <tgroup cols="2">
        <!--
                <colspec colname="c1" colwidth="1*"/>
                <colspec colname="c2" colwidth="1*"/>
-->

        <thead>
          <row>
            <entry>Property name</entry>

            <entry>Purpose</entry>
          </row>
        </thead>

        <tbody>
          <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.batch_size</property></entry>

            <entry>A non-zero value enables use of JDBC2 batch updates by
            Hibernate. <para> <emphasis role="strong">e.g.</emphasis>
            recommended values between <literal>5</literal> and
            <literal>30</literal> </para></entry>
          </row>

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

            <entry>Set this property to <literal>true</literal> if your JDBC
            driver returns correct row counts from
            <literal>executeBatch()</literal>. It is usually safe to turn this
            option on. Hibernate will then use batched DML for automatically
            versioned data. 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.jdbc.factory_class</property></entry>

            <entry>Select a custom
            <interfacename>org.hibernate.jdbc.Batcher</interfacename>. Most
            applications will not need this configuration property. <para>
            <emphasis role="strong">e.g.</emphasis>
            <literal>classname.of.BatcherFactory</literal> </para></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><property>hibernate.connection.provider_class</property></entry>

            <entry>The classname of a custom
            <interfacename>org.hibernate.connection.ConnectionProvider</interfacename>
            which provides JDBC connections to Hibernate. <para> <emphasis
            role="strong">e.g.</emphasis>
            <literal>classname.of.ConnectionProvider</literal> </para></entry>
          </row>

          <row>
            <entry><property>hibernate.connection.isolation</property></entry>

            <entry>Sets the JDBC transaction isolation level. Check
            <interfacename>java.sql.Connection</interfacename> for meaningful
            values, but note that most databases do not support all isolation
            levels and some define additional, non-standard isolations. <para>
            <emphasis role="strong">e.g.</emphasis> <literal>1, 2, 4,
            8</literal> </para></entry>
          </row>

          <row>
            <entry><property>hibernate.connection.autocommit</property></entry>

            <entry>Enables autocommit for JDBC pooled connections (it is not
            recommended). <para> <emphasis role="strong">e.g.</emphasis>
            <literal>true</literal> | <literal>false</literal> </para></entry>
          </row>

          <row>
            <entry><property>hibernate.connection.release_mode</property></entry>

            <entry>Specifies when Hibernate should release JDBC connections.
            By default, a JDBC connection is held until the session is
            explicitly closed or disconnected. For an application server JTA
            datasource, use <literal>after_statement</literal> to aggressively
            release connections after every JDBC call. For a non-JTA
            connection, it often makes sense to release the connection at the
            end of each transaction, by using
            <literal>after_transaction</literal>. <literal>auto</literal> will
            choose <literal>after_statement</literal> for the JTA and CMT
            transaction strategies and <literal>after_transaction</literal>
            for the JDBC transaction strategy. <para> <emphasis
            role="strong">e.g.</emphasis> <literal>auto</literal> (default) |
            <literal>on_close</literal> | <literal>after_transaction</literal>
            | <literal>after_statement</literal> </para> <para> This setting
            only affects <literal>Session</literal>s returned from
            <literal>SessionFactory.openSession</literal>. For
            <literal>Session</literal>s obtained through
            <literal>SessionFactory.getCurrentSession</literal>, the
            <literal>CurrentSessionContext</literal> implementation configured
            for use controls the connection release mode for those
            <literal>Session</literal>s. See <xref
            linkend="architecture-current-session" /> </para></entry>
          </row>

          <row>
            <entry><property>hibernate.connection.</property><emphasis>&lt;propertyName&gt;</emphasis></entry>

            <entry>Pass the JDBC property
            <emphasis>&lt;propertyName&gt;</emphasis> to
            <literal>DriverManager.getConnection()</literal>.</entry>
          </row>

          <row>
            <entry><property>hibernate.jndi.</property><emphasis>&lt;propertyName&gt;</emphasis></entry>

            <entry>Pass the property <emphasis>&lt;propertyName&gt;</emphasis>
            to the JNDI <literal>InitialContextFactory</literal>.</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <table frame="topbot" xml:id="configuration-cache-properties" revision="7">
      <title>Hibernate Cache Properties</title>

      <tgroup cols="2">
        <colspec colname="c1" colwidth="1*" />

        <colspec colname="c2" colwidth="1*" />

        <thead>
          <row>
            <entry>Property name</entry>

            <entry>Purpose</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry><literal>hibernate.cache.provider_class</literal></entry>

            <entry>The classname of a custom <literal>CacheProvider</literal>.
            <para> <emphasis role="strong">e.g.</emphasis>
            <literal>classname.of.CacheProvider</literal> </para></entry>
          </row>

          <row>
            <entry><literal>hibernate.cache.use_minimal_puts</literal></entry>

            <entry>Optimizes second-level cache operation to minimize writes,
            at the cost of more frequent reads. This setting is most useful
            for clustered caches and, in Hibernate3, is enabled by default for
            clustered cache implementations. <para> <emphasis
            role="strong">e.g.</emphasis> <literal>true|false</literal>
            </para></entry>
          </row>

          <row>
            <entry><literal>hibernate.cache.use_query_cache</literal></entry>

            <entry>Enables the query cache. Individual queries still have to
            be set cachable. <para> <emphasis role="strong">e.g.</emphasis>
            <literal>true|false</literal> </para></entry>
          </row>

          <row>
            <entry><literal>hibernate.cache.use_second_level_cache</literal></entry>

            <entry>Can be used to completely disable the second level cache,
            which is enabled by default for classes which specify a
            <literal>&lt;cache&gt;</literal> mapping. <para> <emphasis
            role="strong">e.g.</emphasis> <literal>true|false</literal>
            </para></entry>
          </row>

          <row>
            <entry><literal>hibernate.cache.query_cache_factory</literal></entry>

            <entry>The classname of a custom <literal>QueryCache</literal>
            interface, defaults to the built-in
            <literal>StandardQueryCache</literal>. <para> <emphasis
            role="strong">e.g.</emphasis>
            <literal>classname.of.QueryCache</literal> </para></entry>
          </row>

          <row>
            <entry><literal>hibernate.cache.region_prefix</literal></entry>

            <entry>A prefix to use for second-level cache region names. <para>
            <emphasis role="strong">e.g.</emphasis> <literal>prefix</literal>
            </para></entry>
          </row>

          <row>
            <entry><literal>hibernate.cache.use_structured_entries</literal></entry>

            <entry>Forces Hibernate to store data in the second-level cache in
            a more human-friendly format. <para> <emphasis
            role="strong">e.g.</emphasis> <literal>true|false</literal>
            </para></entry>
          </row>

          <row>
            <entry><literal>hibernate.cache.default_cache_concurrency_strategy</literal></entry>

            <entry>Setting used to give the name of the default
            <classname>org.hibernate.annotations.CacheConcurrencyStrategy</classname>
            to use when either <classname>@Cacheable</classname> or
            <classname>@Cache</classname> is used.
            <code>@Cache(strategy="..")</code> is used to override this
            default.</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <table frame="topbot" xml:id="configuration-transaction-properties"
           revision="9">
      <title>Hibernate Transaction Properties</title>

      <tgroup cols="2">
        <colspec colname="c1" colwidth="1*" />

        <colspec colname="c2" colwidth="1*" />

        <thead>
          <row>
            <entry>Property name</entry>

            <entry>Purpose</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry><literal>hibernate.transaction.factory_class</literal></entry>

            <entry>The classname of a <literal>TransactionFactory</literal> to
            use with Hibernate <literal>Transaction</literal> API (defaults to
            <literal>JDBCTransactionFactory</literal>). <para> <emphasis
            role="strong">e.g.</emphasis>
            <literal>classname.of.TransactionFactory</literal> </para></entry>
          </row>

          <row>
            <entry><literal>jta.UserTransaction</literal></entry>

            <entry>A JNDI name used by
            <literal>JTATransactionFactory</literal> to obtain the JTA
            <literal>UserTransaction</literal> from the application server.
            <para> <emphasis role="strong">e.g.</emphasis>
            <literal>jndi/composite/name</literal> </para></entry>
          </row>

          <row>
            <entry><literal>hibernate.transaction.manager_lookup_class</literal></entry>

            <entry>The classname of a
            <literal>TransactionManagerLookup</literal>. It is required when
            JVM-level caching is enabled or when using hilo generator in a JTA
            environment. <para> <emphasis role="strong">e.g.</emphasis>
            <literal>classname.of.TransactionManagerLookup</literal>
            </para></entry>
          </row>

          <row>
            <entry><literal>hibernate.transaction.flush_before_completion</literal></entry>

            <entry>If enabled, the session will be automatically flushed
            during the before completion phase of the transaction. Built-in
            and automatic session context management is preferred, see <xref
            linkend="architecture-current-session" />. <para> <emphasis
            role="strong">e.g.</emphasis> <literal>true</literal> |
            <literal>false</literal> </para></entry>
          </row>

          <row>
            <entry><literal>hibernate.transaction.auto_close_session</literal></entry>

            <entry>If enabled, the session will be automatically closed during
            the after completion phase of the transaction. Built-in and
            automatic session context management is preferred, see <xref
            linkend="architecture-current-session" />. <para> <emphasis
            role="strong">e.g.</emphasis> <literal>true</literal> |
            <literal>false</literal> </para></entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <table frame="topbot" xml:id="configuration-misc-properties" revision="11">
      <title>Miscellaneous Properties</title>

      <tgroup cols="2">
        <colspec colname="c1" colwidth="1*" />

        <colspec colname="c2" colwidth="1*" />

        <thead>
          <row>
            <entry>Property name</entry>

            <entry>Purpose</entry>
          </row>
        </thead>

        <tbody>
          <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.query.factory_class</literal></entry>

            <entry>Chooses the HQL parser implementation. <para> <emphasis
            role="strong">e.g.</emphasis>
            <literal>org.hibernate.hql.internal.ast.ASTQueryTranslatorFactory</literal>
            or
            <literal>org.hibernate.hql.internal.classic.ClassicQueryTranslatorFactory</literal>
            </para></entry>
          </row>

          <row>
            <entry><literal>hibernate.query.substitutions</literal></entry>

            <entry>Is used to map from tokens in Hibernate queries to SQL
            tokens (tokens might be function or literal names, for example).
            <para> <emphasis role="strong">e.g.</emphasis>
            <literal>hqlLiteral=SQL_LITERAL, hqlFunction=SQLFUNC</literal>
            </para></entry>
          </row>

          <row>
            <entry><literal>hibernate.hbm2ddl.auto</literal></entry>

            <entry>Automatically validates or exports schema DDL to the
            database when the <literal>SessionFactory</literal> is created.
            With <literal>create-drop</literal>, the database schema will be
            dropped when the <literal>SessionFactory</literal> is closed
            explicitly. <para> <emphasis role="strong">e.g.</emphasis>
            <literal>validate</literal> | <literal>update</literal> |
            <literal>create</literal> | <literal>create-drop</literal>
            </para></entry>
          </row>

          <row>
            <entry><literal>hibernate.hbm2ddl.import_files</literal></entry>

            <entry><para>Comma-separated names of the optional files
            containing SQL DML statements executed during the
            <classname>SessionFactory</classname> creation. This is useful for
            testing or demoing: by adding INSERT statements for example you
            can populate your database with a minimal set of data when it is
            deployed.</para><para>File order matters, the statements of a give
            file are executed before the statements of the following files.
            These statements are only executed if the schema is created ie if
            <literal>hibernate.hbm2ddl.auto</literal> is set to
            <literal>create</literal> or
            <literal>create-drop</literal>.</para><para> <emphasis
            role="strong">e.g.</emphasis>
            <literal>/humans.sql,/dogs.sql</literal> </para></entry>
          </row>

          <row>
            <entry><literal>hibernate.hbm2ddl.import_files_sql_extractor</literal></entry>

            <entry><para>The classname of a custom <interfacename>ImportSqlCommandExtractor</interfacename>
            (defaults to the built-in <classname>SingleLineSqlCommandExtractor</classname>).
            This is useful for implementing dedicated parser that extracts
            single SQL statements from each import file. Hibernate provides
            also <classname>MultipleLinesSqlCommandExtractor</classname> which
            supports instructions/comments and quoted strings spread over
            multiple lines (mandatory semicolon at the end of each statement).
            </para><para><emphasis role="strong">e.g.</emphasis>
            <literal>classname.of.ImportSqlCommandExtractor</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 either CGLIB or 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>Both javassist or cglib can be used as byte
            manipulation engines; the default is
            <literal>javassist</literal>.</para><para> <emphasis
            role="strong">e.g.</emphasis> <literal>javassist</literal> |
            <literal>cglib</literal> </para></entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <section xml:id="configuration-optional-dialects" revision="1">
      <title>SQL Dialects</title>

      <para>Always set the <literal>hibernate.dialect</literal> property to
      the correct <literal>org.hibernate.dialect.Dialect</literal> subclass
      for your database. If you specify a dialect, Hibernate will use sensible
      defaults for some of the other properties listed above. This means that
      you will not have to specify them manually.</para>

      <table frame="topbot" xml:id="sql-dialects" revision="3">
        <title>Hibernate SQL Dialects
        (<literal>hibernate.dialect</literal>)</title>

        <tgroup cols="2">
          <!--
                    <colspec colwidth="1*"/>
                    <colspec colwidth="2.5*"/>
-->

          <thead>
            <row>
              <entry>RDBMS</entry>

              <entry>Dialect</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>DB2</entry>

              <entry><literal>org.hibernate.dialect.DB2Dialect</literal></entry>
            </row>

            <row>
              <entry>DB2 AS/400</entry>

              <entry><literal>org.hibernate.dialect.DB2400Dialect</literal></entry>
            </row>

            <row>
              <entry>DB2 OS390</entry>

              <entry><literal>org.hibernate.dialect.DB2390Dialect</literal></entry>
            </row>

            <row>
              <entry>PostgreSQL 8.1</entry>

              <entry><literal>org.hibernate.dialect.PostgreSQL81Dialect</literal></entry>
            </row>
              <row>
                  <entry>PostgreSQL 8.2 and later</entry>

                  <entry><literal>org.hibernate.dialect.PostgreSQL82Dialect</literal></entry>
              </row>
            <row>
              <entry>MySQL5</entry>

              <entry><literal>org.hibernate.dialect.MySQL5Dialect</literal></entry>
            </row>

            <row>
              <entry>MySQL5 with InnoDB</entry>

              <entry><literal>org.hibernate.dialect.MySQL5InnoDBDialect</literal></entry>
            </row>

            <row>
              <entry>MySQL with MyISAM</entry>

              <entry><literal>org.hibernate.dialect.MySQLMyISAMDialect</literal></entry>
            </row>

            <row>
              <entry>Oracle (any version)</entry>

              <entry><literal>org.hibernate.dialect.OracleDialect</literal></entry>
            </row>

            <row>
              <entry>Oracle 9i</entry>

              <entry><literal>org.hibernate.dialect.Oracle9iDialect</literal></entry>
            </row>

            <row>
              <entry>Oracle 10g</entry>

              <entry><literal>org.hibernate.dialect.Oracle10gDialect</literal></entry>
            </row>

            <row>
              <entry>Oracle 11g</entry>

              <entry><literal>org.hibernate.dialect.Oracle10gDialect</literal></entry>
            </row>

            <row>
              <entry>Sybase ASE 15.5</entry>

              <entry><literal>org.hibernate.dialect.SybaseASE15Dialect</literal></entry>
            </row>

              <row>
                  <entry>Sybase ASE 15.7</entry>

                  <entry><literal>org.hibernate.dialect.SybaseASE157Dialect</literal></entry>
              </row>
            <row>
              <entry>Sybase Anywhere</entry>

              <entry><literal>org.hibernate.dialect.SybaseAnywhereDialect</literal></entry>
            </row>

            <row>
              <entry>Microsoft SQL Server 2000</entry>

              <entry><literal>org.hibernate.dialect.SQLServerDialect</literal></entry>
            </row>

            <row>
              <entry>Microsoft SQL Server 2005</entry>

              <entry><literal>org.hibernate.dialect.SQLServer2005Dialect</literal></entry>
            </row>

            <row>
              <entry>Microsoft SQL Server 2008</entry>

              <entry><literal>org.hibernate.dialect.SQLServer2008Dialect</literal></entry>
            </row>

            <row>
              <entry>SAP DB</entry>

              <entry><literal>org.hibernate.dialect.SAPDBDialect</literal></entry>
            </row>

            <row>
              <entry>Informix</entry>

              <entry><literal>org.hibernate.dialect.InformixDialect</literal></entry>
            </row>

            <row>
              <entry>HypersonicSQL</entry>

              <entry><literal>org.hibernate.dialect.HSQLDialect</literal></entry>
            </row>

            <row>
              <entry>H2 Database</entry>

              <entry><literal>org.hibernate.dialect.H2Dialect</literal></entry>
            </row>

            <row>
              <entry>Ingres</entry>

              <entry><literal>org.hibernate.dialect.IngresDialect</literal></entry>
            </row>

            <row>
              <entry>Progress</entry>

              <entry><literal>org.hibernate.dialect.ProgressDialect</literal></entry>
            </row>

            <row>
              <entry>Mckoi SQL</entry>

              <entry><literal>org.hibernate.dialect.MckoiDialect</literal></entry>
            </row>

            <row>
              <entry>Interbase</entry>

              <entry><literal>org.hibernate.dialect.InterbaseDialect</literal></entry>
            </row>

            <row>
              <entry>Pointbase</entry>

              <entry><literal>org.hibernate.dialect.PointbaseDialect</literal></entry>
            </row>

            <row>
              <entry>FrontBase</entry>

              <entry><literal>org.hibernate.dialect.FrontbaseDialect</literal></entry>
            </row>

            <row>
              <entry>Firebird</entry>

              <entry><literal>org.hibernate.dialect.FirebirdDialect</literal></entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </section>

    <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 xml:id="configuration-optional-cacheprovider" revision="2">
      <title>Second-level and query cache</title>

      <para>The properties prefixed by <literal>hibernate.cache</literal>
      allow you to use a process or cluster scoped second-level cache system
      with Hibernate. See the <xref linkend="performance-cache" /> for more
      information.</para>
    </section>

    <section xml:id="configuration-optional-querysubstitution">
      <title>Query Language Substitution</title>

      <para>You can define new Hibernate query tokens using
      <literal>hibernate.query.substitutions</literal>. For example:</para>

      <programlisting>hibernate.query.substitutions true=1, false=0</programlisting>

      <para>This would cause the tokens <literal>true</literal> and
      <literal>false</literal> to be translated to integer literals in the
      generated SQL.</para>

      <programlisting>hibernate.query.substitutions toLowercase=LOWER</programlisting>

      <para>This would allow you to rename the SQL <literal>LOWER</literal>
      function.</para>
    </section>

    <section xml:id="configuration-optional-statistics" revision="2">
      <title>Hibernate statistics</title>

      <para>If you enable <literal>hibernate.generate_statistics</literal>,
      Hibernate exposes a number of metrics that are useful when tuning a
      running system via <literal>SessionFactory.getStatistics()</literal>.
      Hibernate can even be configured to expose these statistics via JMX.
      Read the Javadoc of the interfaces in
      <literal>org.hibernate.stats</literal> for more information.</para>
    </section>
  </section>

  <section xml:id="configuration-logging">
    <title>Logging</title>

      <important>
          <para>
              Completely out of date.  Hibernate uses JBoss Logging starting in 4.0.
              This will get documented as we migrate this content to the Developer Guide.
          </para>
      </important>

    <para>Hibernate utilizes <link xlink:href="http://www.slf4j.org/" >Simple Logging
    Facade for Java</link> (SLF4J) in order to log various system events.
    SLF4J can direct your logging output to several logging frameworks (NOP,
    Simple, log4j version 1.2, JDK 1.4 logging, JCL or logback) depending on
    your chosen binding. In order to setup logging you will need
    <filename>slf4j-api.jar</filename> in your classpath together with the jar
    file for your preferred binding - <filename>slf4j-log4j12.jar</filename>
    in the case of Log4J. See the SLF4J
        <link xlink:href="http://www.slf4j.org/manual.html">documentation</link>
        for more
    detail. To use Log4j you will also need to place a
    <filename>log4j.properties</filename> file in your classpath. An example
    properties file is distributed with Hibernate in the
    <literal>src/</literal> directory.</para>

    <para>It is recommended 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. The most interesting log categories are the
    following:</para>

    <table frame="topbot" xml:id="log-categories" revision="2">
      <title>Hibernate Log Categories</title>

      <tgroup cols="2">
        <colspec colwidth="1*" />

        <colspec colwidth="2.5*" />

        <thead>
          <row>
            <entry>Category</entry>

            <entry>Function</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry><literal>org.hibernate.SQL</literal></entry>

            <entry>Log all SQL DML statements as they are executed</entry>
          </row>

          <row>
            <entry><literal>org.hibernate.type</literal></entry>

            <entry>Log all JDBC parameters</entry>
          </row>

          <row>
            <entry><literal>org.hibernate.tool.hbm2ddl</literal></entry>

            <entry>Log all SQL DDL statements as they are executed</entry>
          </row>

          <row>
            <entry><literal>org.hibernate.pretty</literal></entry>

            <entry>Log the state of all entities (max 20 entities) associated
            with the session at flush time</entry>
          </row>

          <row>
            <entry><literal>org.hibernate.cache</literal></entry>

            <entry>Log all second-level cache activity</entry>
          </row>

          <row>
            <entry><literal>org.hibernate.transaction</literal></entry>

            <entry>Log transaction related activity</entry>
          </row>

          <row>
            <entry><literal>org.hibernate.jdbc</literal></entry>

            <entry>Log all JDBC resource acquisition</entry>
          </row>

          <row>
            <entry><literal>org.hibernate.hql.internal.ast.AST</literal></entry>

            <entry>Log HQL and SQL ASTs during query parsing</entry>
          </row>

          <row>
            <entry><literal>org.hibernate.secure</literal></entry>

            <entry>Log all JAAS authorization requests</entry>
          </row>

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

            <entry>Log everything. This is a lot of information but it is
            useful for troubleshooting</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <para>When developing applications with Hibernate, you should almost
    always work with <literal>debug</literal> enabled for the category
    <literal>org.hibernate.SQL</literal>, or, alternatively, the property
    <literal>hibernate.show_sql</literal> enabled.</para>
  </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>

  <section xml:id="configuration-j2ee" revision="1">
    <title>Java EE Application Server integration</title>

    <para>Hibernate has the following integration points for J2EE
    infrastructure:</para>

    <itemizedlist>
      <listitem>
        <para><emphasis>Container-managed datasources</emphasis>: Hibernate
        can use JDBC connections managed by the container and provided through
        JNDI. Usually, a JTA compatible <literal>TransactionManager</literal>
        and a <literal>ResourceManager</literal> take care of transaction
        management (CMT), especially distributed transaction handling across
        several datasources. You can also demarcate transaction boundaries
        programmatically (BMT), or you might want to use the optional
        Hibernate <literal>Transaction</literal> API for this to keep your
        code portable.</para>
      </listitem>
    </itemizedlist>

    <itemizedlist>
      <listitem>
        <para><emphasis>Automatic JNDI binding</emphasis>: Hibernate can bind
        its <literal>SessionFactory</literal> to JNDI after startup.</para>
      </listitem>
    </itemizedlist>

    <itemizedlist>
      <listitem>
        <para><emphasis>JTA Session binding:</emphasis> the Hibernate
        <literal>Session</literal> can be automatically bound to the scope of
        JTA transactions. Simply lookup the <literal>SessionFactory</literal>
        from JNDI and get the current <literal>Session</literal>. Let
        Hibernate manage flushing and closing the <literal>Session</literal>
        when your JTA transaction completes. Transaction demarcation is either
        declarative (CMT) or programmatic (BMT/UserTransaction).</para>
      </listitem>
    </itemizedlist>

    <itemizedlist>
      <listitem>
        <para><emphasis>JMX deployment:</emphasis> if you have a JMX capable
        application server (e.g. JBoss AS), you can choose to deploy Hibernate
        as a managed MBean. This saves you the one line startup code to build
        your <literal>SessionFactory</literal> from a
        <literal>Configuration</literal>. The container will startup your
        <literal>HibernateService</literal> and also take care of service
        dependencies (datasource has to be available before Hibernate starts,
        etc).</para>
      </listitem>
    </itemizedlist>

    <para>Depending on your environment, you might have to set the
    configuration option
    <literal>hibernate.connection.aggressive_release</literal> to true if your
    application server shows "connection containment" exceptions.</para>

    <section xml:id="configuration-optional-transactionstrategy" revision="3">
      <title>Transaction strategy configuration</title>

      <para>The Hibernate <literal>Session</literal> API is independent of any
      transaction demarcation system in your architecture. If you let
      Hibernate use JDBC directly through a connection pool, you can begin and
      end your transactions by calling the JDBC API. If you run in a J2EE
      application server, you might want to use bean-managed transactions and
      call the JTA API and <literal>UserTransaction</literal> when
      needed.</para>

      <para>To keep your code portable between these two (and other)
      environments we recommend the optional Hibernate
      <literal>Transaction</literal> API, which wraps and hides the underlying
      system. You have to specify a factory class for
      <literal>Transaction</literal> instances by setting the Hibernate
      configuration property
      <literal>hibernate.transaction.factory_class</literal>.</para>

      <para>There are three standard, or built-in, choices:</para>

      <variablelist spacing="compact">
        <varlistentry>
          <term><literal>org.hibernate.transaction.JDBCTransactionFactory</literal></term>

          <listitem>
            <para>delegates to database (JDBC) transactions (default)</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><literal>org.hibernate.transaction.JTATransactionFactory</literal></term>

          <listitem>
            <para>delegates to container-managed transactions if an existing
            transaction is underway in this context (for example, EJB session
            bean method). Otherwise, a new transaction is started and
            bean-managed transactions are used.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><literal>org.hibernate.transaction.CMTTransactionFactory</literal></term>

          <listitem>
            <para>delegates to container-managed JTA transactions</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>You can also define your own transaction strategies (for a CORBA
      transaction service, for example).</para>

      <para>Some features in Hibernate (i.e., the second level cache,
      Contextual Sessions with JTA, etc.) require access to the JTA
      <literal>TransactionManager</literal> in a managed environment. In an
      application server, since J2EE does not standardize a single mechanism,
      you have to specify how Hibernate should obtain a reference to the
      <literal>TransactionManager</literal>:</para>

      <table frame="topbot" xml:id="jtamanagerlookup" revision="1">
        <title>JTA TransactionManagers</title>

        <tgroup cols="2">
          <colspec colwidth="2.5*" />

          <colspec colwidth="1*" />

          <thead>
            <row>
              <entry>Transaction Factory</entry>

              <entry align="center">Application Server</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry><literal>org.hibernate.transaction.JBossTransactionManagerLookup</literal></entry>

              <entry align="center">JBoss AS</entry>
            </row>

            <row>
              <entry><literal>org.hibernate.transaction.WeblogicTransactionManagerLookup</literal></entry>

              <entry align="center">Weblogic</entry>
            </row>

            <row>
              <entry><literal>org.hibernate.transaction.WebSphereTransactionManagerLookup</literal></entry>

              <entry align="center">WebSphere</entry>
            </row>

            <row>
              <entry><literal>org.hibernate.transaction.WebSphereExtendedJTATransactionLookup</literal></entry>

              <entry align="center">WebSphere 6</entry>
            </row>

            <row>
              <entry><literal>org.hibernate.transaction.OrionTransactionManagerLookup</literal></entry>

              <entry align="center">Orion</entry>
            </row>

            <row>
              <entry><literal>org.hibernate.transaction.ResinTransactionManagerLookup</literal></entry>

              <entry align="center">Resin</entry>
            </row>

            <row>
              <entry><literal>org.hibernate.transaction.JOTMTransactionManagerLookup</literal></entry>

              <entry align="center">JOTM</entry>
            </row>

            <row>
              <entry><literal>org.hibernate.transaction.JOnASTransactionManagerLookup</literal></entry>

              <entry align="center">JOnAS</entry>
            </row>

            <row>
              <entry><literal>org.hibernate.transaction.JRun4TransactionManagerLookup</literal></entry>

              <entry align="center">JRun4</entry>
            </row>

            <row>
              <entry><literal>org.hibernate.transaction.BESTransactionManagerLookup</literal></entry>

              <entry align="center">Borland ES</entry>
            </row>

            <row>
              <entry><literal>org.hibernate.transaction.JBossTSStandaloneTransactionManagerLookup</literal></entry>

              <entry align="center">JBoss TS used standalone (ie. outside
              JBoss AS and a JNDI environment generally). Known to work for
              <literal>org.jboss.jbossts:jbossjta:4.11.0.Final</literal></entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </section>

    <section xml:id="configuration-optional-jndi" revision="3">
      <title>JNDI-bound <literal>SessionFactory</literal></title>

      <para>A JNDI-bound Hibernate <literal>SessionFactory</literal> can
      simplify the lookup function of the factory and create new
      <literal>Session</literal>s. This is not, however, related to a JNDI
      bound <literal>Datasource</literal>; both simply use the same
      registry.</para>

      <para>If you wish to have the <literal>SessionFactory</literal> bound to
      a JNDI namespace, specify a name (e.g.
      <literal>java:hibernate/SessionFactory</literal>) using the property
      <literal>hibernate.session_factory_name</literal>. If this property is
      omitted, the <literal>SessionFactory</literal> will not be bound to
      JNDI. This is especially useful in environments with a read-only JNDI
      default implementation (in Tomcat, for example).</para>

      <para>When binding the <literal>SessionFactory</literal> to JNDI,
      Hibernate will use the values of <literal>hibernate.jndi.url</literal>,
      <literal>hibernate.jndi.class</literal> to instantiate an initial
      context. If they are not specified, the default
      <literal>InitialContext</literal> will be used.</para>

      <para>Hibernate will automatically place the
      <literal>SessionFactory</literal> in JNDI after you call
      <literal>cfg.buildSessionFactory()</literal>. This means you will have
      this call in some startup code, or utility class in your application,
      unless you use JMX deployment with the
      <literal>HibernateService</literal> (this is discussed later in greater
      detail).</para>

      <para>If you use a JNDI <literal>SessionFactory</literal>, an EJB or any
      other class, you can obtain the <literal>SessionFactory</literal> using
      a JNDI lookup.</para>

      <para>It is recommended that you bind the
      <literal>SessionFactory</literal> to JNDI in a managed environment and
      use a <literal>static</literal> singleton otherwise. To shield your
      application code from these details, we also recommend to hide the
      actual lookup code for a <literal>SessionFactory</literal> in a helper
      class, such as <literal>HibernateUtil.getSessionFactory()</literal>.
      Note that such a class is also a convenient way to startup Hibernate—see
      chapter 1.</para>
    </section>

    <section xml:id="configuration-j2ee-currentsession" revision="4">
      <title>Current Session context management with JTA</title>

      <para>The easiest way to handle <literal>Sessions</literal> and
      transactions is Hibernate's automatic "current"
      <literal>Session</literal> management. For a discussion of contextual
      sessions see <xref linkend="architecture-current-session" />. Using the
      <literal>"jta"</literal> session context, if there is no Hibernate
      <literal>Session</literal> associated with the current JTA transaction,
      one will be started and associated with that JTA transaction the first
      time you call <literal>sessionFactory.getCurrentSession()</literal>. The
      <literal>Session</literal>s retrieved via
      <literal>getCurrentSession()</literal> in the <literal>"jta"</literal>
      context are set to automatically flush before the transaction completes,
      close after the transaction completes, and aggressively release JDBC
      connections after each statement. This allows the
      <literal>Session</literal>s to be managed by the life cycle of the JTA
      transaction to which it is associated, keeping user code clean of such
      management concerns. Your code can either use JTA programmatically
      through <literal>UserTransaction</literal>, or (recommended for portable
      code) use the Hibernate <literal>Transaction</literal> API to set
      transaction boundaries. If you run in an EJB container, declarative
      transaction demarcation with CMT is preferred.</para>
    </section>

    <section xml:id="configuration-j2ee-jmx" revision="1">
      <title>JMX deployment</title>

      <para>The line <literal>cfg.buildSessionFactory()</literal> still has to
      be executed somewhere to get a <literal>SessionFactory</literal> into
      JNDI. You can do this either in a <literal>static</literal> initializer
      block, like the one in <literal>HibernateUtil</literal>, or you can
      deploy Hibernate as a <emphasis>managed service</emphasis>.</para>

      <para>Hibernate is distributed with
      <literal>org.hibernate.jmx.HibernateService</literal> for deployment on
      an application server with JMX capabilities, such as JBoss AS. The
      actual deployment and configuration is vendor-specific. Here is an
      example <literal>jboss-service.xml</literal> for JBoss 4.0.x:</para>

      <programlisting role="XML">&lt;?xml version="1.0"?&gt;
&lt;server&gt;

&lt;mbean code="org.hibernate.jmx.HibernateService"
    name="jboss.jca:service=HibernateFactory,name=HibernateFactory"&gt;

    &lt;!-- Required services --&gt;
    &lt;depends&gt;jboss.jca:service=RARDeployer&lt;/depends&gt;
    &lt;depends&gt;jboss.jca:service=LocalTxCM,name=HsqlDS&lt;/depends&gt;

    &lt;!-- Bind the Hibernate service to JNDI --&gt;
    &lt;attribute name="JndiName"&gt;java:/hibernate/SessionFactory&lt;/attribute&gt;

    &lt;!-- Datasource settings --&gt;
    &lt;attribute name="Datasource"&gt;java:HsqlDS&lt;/attribute&gt;
    &lt;attribute name="Dialect"&gt;org.hibernate.dialect.HSQLDialect&lt;/attribute&gt;

    &lt;!-- Transaction integration --&gt;
    &lt;attribute name="TransactionStrategy"&gt;
        org.hibernate.transaction.JTATransactionFactory&lt;/attribute&gt;
    &lt;attribute name="TransactionManagerLookupStrategy"&gt;
        org.hibernate.transaction.JBossTransactionManagerLookup&lt;/attribute&gt;
    &lt;attribute name="FlushBeforeCompletionEnabled"&gt;true&lt;/attribute&gt;
    &lt;attribute name="AutoCloseSessionEnabled"&gt;true&lt;/attribute&gt;

    &lt;!-- Fetching options --&gt;
    &lt;attribute name="MaximumFetchDepth"&gt;5&lt;/attribute&gt;

    &lt;!-- Second-level caching --&gt;
    &lt;attribute name="SecondLevelCacheEnabled"&gt;true&lt;/attribute&gt;
    &lt;attribute name="CacheProviderClass"&gt;org.hibernate.cache.internal.EhCacheProvider&lt;/attribute&gt;
    &lt;attribute name="QueryCacheEnabled"&gt;true&lt;/attribute&gt;

    &lt;!-- Logging --&gt;
    &lt;attribute name="ShowSqlEnabled"&gt;true&lt;/attribute&gt;

    &lt;!-- Mapping files --&gt;
    &lt;attribute name="MapResources"&gt;auction/Item.hbm.xml,auction/Category.hbm.xml&lt;/attribute&gt;

&lt;/mbean&gt;

&lt;/server&gt;</programlisting>

      <para>This file is deployed in a directory called
      <literal>META-INF</literal> and packaged in a JAR file with the
      extension <literal>.sar</literal> (service archive). You also need to
      package Hibernate, its required third-party libraries, your compiled
      persistent classes, as well as your mapping files in the same archive.
      Your enterprise beans (usually session beans) can be kept in their own
      JAR file, but you can include this EJB JAR file in the main service
      archive to get a single (hot-)deployable unit. Consult the JBoss AS
      documentation for more information about JMX service and EJB
      deployment.</para>
    </section>
  </section>
</chapter>