[hibernate-commits] Hibernate SVN: r14837 - core/trunk/documentation/manual/src/main/docbook/en-US/content.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Tue Jul 1 11:06:42 EDT 2008
Author: hardy.ferentschik
Date: 2008-07-01 11:06:41 -0400 (Tue, 01 Jul 2008)
New Revision: 14837
Modified:
core/trunk/documentation/manual/src/main/docbook/en-US/content/configuration.xml
Log:
Updated the Logging paragraph regrading the switch to slf4j.
Modified: core/trunk/documentation/manual/src/main/docbook/en-US/content/configuration.xml
===================================================================
--- core/trunk/documentation/manual/src/main/docbook/en-US/content/configuration.xml 2008-07-01 14:54:50 UTC (rev 14836)
+++ core/trunk/documentation/manual/src/main/docbook/en-US/content/configuration.xml 2008-07-01 15:06:41 UTC (rev 14837)
@@ -1,1762 +1,1759 @@
-<?xml version='1.0' encoding="UTF-8"?>
-<!--
- ~ Hibernate, Relational Persistence for Idiomatic Java
- ~
- ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as
- ~ indicated by the @author tags or express copyright attribution
- ~ statements applied by the authors. All third-party contributions are
- ~ distributed under license by Red Hat Middleware LLC.
- ~
- ~ This copyrighted material is made available to anyone wishing to use, modify,
- ~ copy, or redistribute it subject to the terms and conditions of the GNU
- ~ Lesser General Public License, as published by the Free Software Foundation.
- ~
- ~ This program is distributed in the hope that it will be useful,
- ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
- ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
- ~ for more details.
- ~
- ~ You should have received a copy of the GNU Lesser General Public License
- ~ along with this distribution; if not, write to:
- ~ Free Software Foundation, Inc.
- ~ 51 Franklin Street, Fifth Floor
- ~ Boston, MA 02110-1301 USA
- -->
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-
-<chapter id="session-configuration" revision="1">
- <title>Configuration</title>
-
- <para>
- Because Hibernate is designed to operate in many different environments, there
- are a large number 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 shows
- the various options. Just put the example file in your classpath and customize it.
- </para>
-
- <sect1 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 may 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>:
- </para>
-
- <programlisting><![CDATA[Configuration cfg = new Configuration()
- .addResource("Item.hbm.xml")
- .addResource("Bid.hbm.xml");]]></programlisting>
-
- <para>
- An alternative (sometimes better) way is to specify the mapped class, and
- let Hibernate find the mapping document for you:
- </para>
-
- <programlisting><![CDATA[Configuration cfg = new Configuration()
- .addClass(org.hibernate.auction.Item.class)
- .addClass(org.hibernate.auction.Bid.class);]]></programlisting>
-
- <para>
- Then Hibernate will look 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:
- </para>
-
- <programlisting><![CDATA[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.
- The various 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><property></literal> elements in
- <literal>hibernate.cfg.xml</literal> (discussed later).
- </para>
- </listitem>
- </orderedlist>
-
- <para>
- <filename>hibernate.properties</filename> is the easiest approach if you want to get started quickly.
- </para>
-
- <para>
- The <classname>org.hibernate.cfg.Configuration</classname> is intended as a startup-time object,
- to be discarded once a <literal>SessionFactory</literal> is created.
- </para>
-
- </sect1>
-
- <sect1 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><![CDATA[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>
-
- </sect1>
-
- <sect1 id="configuration-hibernatejdbc" revision="1">
- <title>JDBC connections</title>
-
- <para>
- Usually, you want 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><![CDATA[Session session = sessions.openSession(); // open a new Session]]></programlisting>
-
- <para>
- As soon as you do something that requires access to the database, a JDBC connection will be obtained from
- the pool.
- </para>
-
- <para>
- For this to work, we 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>. We will
- now describe the most important settings for JDBC connection configuration.
- </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'd like to use Proxool
- refer to the packaged <filename>hibernate.properties</filename> and the Hibernate web site for more
- information.
- </para>
-
- <para>
- Here is an example <filename>hibernate.properties</filename> file for C3P0:
- </para>
-
- <programlisting id="c3p0-configuration" revision="1"><![CDATA[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.PostgreSQLDialect]]></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'll
- 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's an example <filename>hibernate.properties</filename> file for an application server provided JNDI
- datasource:
- </para>
-
- <programlisting><![CDATA[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.PostgreSQLDialect]]></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 may be given by prepending "<literal>hibernate.connection</literal>" to the
- connection property name. For example, you may specify a <property>charSet</property>
- connection property using <property>hibernate.connection.charSet</property>.
- </para>
-
- <para>
- You may 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>
-
- </sect1>
-
- <sect1 id="configuration-optional" revision="1">
- <title>Optional configuration properties</title>
-
- <para>
- There are a number of other properties that control the behaviour of Hibernate at runtime. All are optional
- and have reasonable default values.
- </para>
-
- <para>
- <emphasis>Warning: 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
- may <emphasis>not</emphasis> be set by the other techniques described above.
- </para>
-
- <table frame="topbot" 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">eg.</emphasis>
- <literal>full.classname.of.Dialect</literal>
- </para>
- <para>
- In most cases Hibernate will actually be able to chose the correct
- <classname>org.hibernate.dialect.Dialect</classname> implementation to use 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">eg.</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">eg.</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">eg.</emphasis>
- <literal>SCHEMA_NAME</literal>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <property>hibernate.default_catalog</property>
- </entry>
- <entry>
- Qualify unqualified table names with the given catalog
- in generated SQL.
- <para>
- <emphasis role="strong">eg.</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">eg.</emphasis>
- <literal>jndi/composite/name</literal>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <property>hibernate.max_fetch_depth</property>
- </entry>
- <entry>
- Set 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">eg.</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>
- Set a default size for Hibernate batch fetching of associations.
- <para>
- <emphasis role="strong">eg.</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>
- Set 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>
- Force 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">eg.</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">eg.</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">eg.</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">eg.</emphasis>
- <literal>true</literal> | <literal>false</literal>
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="topbot" 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">eg.</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">eg.</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">eg.</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">eg.</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">eg.</emphasis>
- <literal>true</literal> | <literal>false</literal>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <property>hibernate.jdbc.use_get_generated_keys</property>
- </entry>
- <entry>
- Enable 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, tries to determine the driver capabilities
- using connection metadata.
- <para>
- <emphasis role="strong">eg.</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">eg.</emphasis>
- <literal>classname.of.ConnectionProvider</literal>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <property>hibernate.connection.isolation</property>
- </entry>
- <entry>
- Set 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">eg.</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 (not recommended).
- <para>
- <emphasis role="strong">eg.</emphasis>
- <literal>true</literal> | <literal>false</literal>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <property>hibernate.connection.release_mode</property>
- </entry>
- <entry>
- Specify 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, you should 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">eg.</emphasis>
- <literal>auto</literal> (default) | <literal>on_close</literal> |
- <literal>after_transaction</literal> | <literal>after_statement</literal>
- </para>
- <para>
- Note that 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><propertyName></emphasis>
- </entry>
- <entry>
- Pass the JDBC property <emphasis><propertyName></emphasis>
- to <literal>DriverManager.getConnection()</literal>.
- </entry>
- </row>
- <row>
- <entry>
- <property>hibernate.jndi.</property><emphasis><propertyName></emphasis>
- </entry>
- <entry>
- Pass the property <emphasis><propertyName></emphasis> to
- the JNDI <literal>InitialContextFactory</literal>.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="topbot" 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">eg.</emphasis>
- <literal>classname.of.CacheProvider</literal>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <literal>hibernate.cache.use_minimal_puts</literal>
- </entry>
- <entry>
- Optimize 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">eg.</emphasis>
- <literal>true|false</literal>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <literal>hibernate.cache.use_query_cache</literal>
- </entry>
- <entry>
- Enable the query cache, individual queries still have to be set cachable.
- <para>
- <emphasis role="strong">eg.</emphasis>
- <literal>true|false</literal>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <literal>hibernate.cache.use_second_level_cache</literal>
- </entry>
- <entry>
- May be used to completely disable the second level cache, which is enabled
- by default for classes which specify a <literal><cache></literal>
- mapping.
- <para>
- <emphasis role="strong">eg.</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">eg.</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">eg.</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">eg.</emphasis>
- <literal>true|false</literal>
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="topbot" 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">eg.</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">eg.</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>
- - required when JVM-level caching is enabled or when using hilo
- generator in a JTA environment.
- <para>
- <emphasis role="strong">eg.</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">eg.</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
- utomatic session context management is preferred, see
- <xref linkend="architecture-current-session"/>.
- <para>
- <emphasis role="strong">eg.</emphasis>
- <literal>true</literal> | <literal>false</literal>
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="topbot" id="configuration-misc-properties" revision="10">
- <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">eg.</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">eg.</emphasis>
- <literal>org.hibernate.hql.ast.ASTQueryTranslatorFactory</literal> or
- <literal>org.hibernate.hql.classic.ClassicQueryTranslatorFactory</literal>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <literal>hibernate.query.substitutions</literal>
- </entry>
- <entry>
- Mapping from tokens in Hibernate queries to SQL tokens
- (tokens might be function or literal names, for example).
- <para>
- <emphasis role="strong">eg.</emphasis>
- <literal>hqlLiteral=SQL_LITERAL, hqlFunction=SQLFUNC</literal>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <literal>hibernate.hbm2ddl.auto</literal>
- </entry>
- <entry>
- Automatically validate or export 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">eg.</emphasis>
- <literal>validate</literal> | <literal>update</literal> |
- <literal>create</literal> | <literal>create-drop</literal>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <literal>hibernate.cglib.use_reflection_optimizer</literal>
- </entry>
- <entry>
- Enables use of CGLIB instead of runtime reflection (System-level
- property). Reflection can sometimes be useful when troubleshooting,
- note that Hibernate always requires CGLIB even if you turn off the
- optimizer. You can not set this property in <literal>hibernate.cfg.xml</literal>.
- <para>
- <emphasis role="strong">eg.</emphasis>
- <literal>true</literal> | <literal>false</literal>
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <sect2 id="configuration-optional-dialects" revision="1">
- <title>SQL Dialects</title>
-
- <para>
- You should 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, saving you the effort of specifying them manually.
- </para>
-
- <table frame="topbot" id="sql-dialects" revision="2">
- <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</entry> <entry><literal>org.hibernate.dialect.PostgreSQLDialect</literal></entry>
- </row>
- <row>
- <entry>MySQL</entry> <entry><literal>org.hibernate.dialect.MySQLDialect</literal></entry>
- </row>
- <row>
- <entry>MySQL with InnoDB</entry> <entry><literal>org.hibernate.dialect.MySQLInnoDBDialect</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/10g</entry> <entry><literal>org.hibernate.dialect.Oracle9Dialect</literal></entry>
- </row>
- <row>
- <entry>Sybase</entry> <entry><literal>org.hibernate.dialect.SybaseDialect</literal></entry>
- </row>
- <row>
- <entry>Sybase Anywhere</entry> <entry><literal>org.hibernate.dialect.SybaseAnywhereDialect</literal></entry>
- </row>
- <row>
- <entry>Microsoft SQL Server</entry> <entry><literal>org.hibernate.dialect.SQLServerDialect</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>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>
-
- </sect2>
-
- <sect2 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 (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 may 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 which have been mapped with
- <literal>fetch="join"</literal>.
- </para>
-
- <para>
- See <xref linkend="performance-fetching"/> for more information.
- </para>
-
- </sect2>
-
- <sect2 id="configuration-optional-binarystreams" revision="1">
- <title>Binary Streams</title>
-
- <para>
- Oracle limits the size of <literal>byte</literal> arrays that may
- be passed to/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>
-
- </sect2>
-
- <sect2 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 details.
- </para>
-
- </sect2>
-
- <sect2 id="configuration-optional-querysubstitution">
- <title>Query Language Substitution</title>
-
- <para>
- You may define new Hibernate query tokens using <literal>hibernate.query.substitutions</literal>.
- For example:
- </para>
-
- <programlisting>hibernate.query.substitutions true=1, false=0</programlisting>
-
- <para>
- 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>
- would allow you to rename the SQL <literal>LOWER</literal> function.
- </para>
-
- </sect2>
-
- <sect2 id="configuration-optional-statistics" revision="2">
- <title>Hibernate statistics</title>
-
- <para>
- If you enable <literal>hibernate.generate_statistics</literal>, Hibernate will
- expose 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>
-
- </sect2>
- </sect1>
-
- <sect1 id="configuration-logging">
- <title>Logging</title>
-
- <para>
- Hibernate logs various events using Apache commons-logging.
- </para>
-
- <para>
- The commons-logging service will direct output to either Apache Log4j
- (if you include <literal>log4j.jar</literal> in your classpath) or
- JDK1.4 logging (if running under JDK1.4 or above). You may download
- Log4j from <literal>http://jakarta.apache.org</literal>.
- To use Log4j you will need to place a <literal>log4j.properties</literal>
- file in your classpath, an example properties file is distributed with
- Hibernate in the <literal>src/</literal> directory.
- </para>
-
- <para>
- We strongly recommend that you familiarize yourself with Hibernate's log
- messages. A lot of work has been put into making the Hibernate log as
- detailed as possible, without making it unreadable. It is an essential
- troubleshooting device. The most interesting log categories are the
- following:
- </para>
-
- <table frame="topbot" 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.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 (a lot of information, but very 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>
-
-
- </sect1>
-
- <sect1 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 may provide rules for automatically generating database identifiers from
- Java identifiers or for processing "logical" column and table names given in
- the mapping file into "physical" table and column names. This feature helps
- reduce the verbosity of the mapping document, eliminating repetitive noise
- (<literal>TBL_</literal> prefixes, for example). The default strategy used by
- Hibernate is quite minimal.
- </para>
-
- <para>
- You may specify a different strategy by calling
- <literal>Configuration.setNamingStrategy()</literal> before adding mappings:
- </para>
-
- <programlisting><![CDATA[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>
-
- </sect1>
-
- <sect1 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 o
- your <literal>CLASSPATH</literal>. Here is an example:
- </para>
-
- <programlisting><![CDATA[<?xml version='1.0' encoding='utf-8'?>
-<!DOCTYPE hibernate-configuration PUBLIC
- "-//Hibernate/Hibernate Configuration DTD//EN"
- "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">
-
-<hibernate-configuration>
-
- <!-- a SessionFactory instance listed as /jndi/name -->
- <session-factory
- name="java:hibernate/SessionFactory">
-
- <!-- properties -->
- <property name="connection.datasource">java:/comp/env/jdbc/MyDB</property>
- <property name="dialect">org.hibernate.dialect.MySQLDialect</property>
- <property name="show_sql">false</property>
- <property name="transaction.factory_class">
- org.hibernate.transaction.JTATransactionFactory
- </property>
- <property name="jta.UserTransaction">java:comp/UserTransaction</property>
-
- <!-- mapping files -->
- <mapping resource="org/hibernate/auction/Item.hbm.xml"/>
- <mapping resource="org/hibernate/auction/Bid.hbm.xml"/>
-
- <!-- cache settings -->
- <class-cache class="org.hibernate.auction.Item" usage="read-write"/>
- <class-cache class="org.hibernate.auction.Bid" usage="read-only"/>
- <collection-cache collection="org.hibernate.auction.Item.bids" usage="read-write"/>
-
- </session-factory>
-
-</hibernate-configuration>]]></programlisting>
-
- <para>
- As you can see, 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. Note that 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><![CDATA[SessionFactory sf = new Configuration().configure().buildSessionFactory();]]></programlisting>
-
- <para>
- You can pick a different XML configuration file using
- </para>
-
- <programlisting><![CDATA[SessionFactory sf = new Configuration()
- .configure("catdb.cfg.xml")
- .buildSessionFactory();]]></programlisting>
-
- </sect1>
-
- <sect1 id="configuration-j2ee" revision="1">
- <title>J2EE 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),
- esp. distributed transaction handling across several datasources. You may
- of course 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>
- may 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 take care of 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 chose 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 ideally 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>
-
- <sect2 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 may 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 (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 transaction if an existing transaction is
- underway in this context (e.g. EJB session bean method), otherwise
- a new transaction is started and bean-managed transaction 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 may 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 you have to specify how Hibernate should obtain a reference to the
- <literal>TransactionManager</literal>, since J2EE does not standardize a single mechanism:
- </para>
-
- <table frame="topbot" 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</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>
- </tbody>
- </tgroup>
- </table>
-
- </sect2>
-
- <sect2 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
- of the factory and the creation of new <literal>Session</literal>s. Note that this
- is not 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 (eg. <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, e.g. Tomcat.)
- </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 at least have
- this call in some startup code (or utility class) in your application, unless you use
- JMX deployment with the <literal>HibernateService</literal> (discussed later).
- </para>
-
- <para>
- If you use a JNDI <literal>SessionFactory</literal>, an EJB or any other class may
- obtain the <literal>SessionFactory</literal> using a JNDI lookup.
- </para>
-
- <para>
- We recommend 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>
-
- </sect2>
-
- <sect2 id="configuration-j2ee-currentsession" revision="4">
- <title>Current Session context management with JTA</title>
-
- <para>
- The easiest way to handle <literal>Session</literal>s and transactions is
- Hibernates automatic "current" <literal>Session</literal> management.
- See the discussion of <link linkend="architecture-current-session">current sessions</link>.
- 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 <literal>"jta"</literal> context
- will be 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>
-
- </sect2>
-
- <sect2 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 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><![CDATA[<?xml version="1.0"?>
-<server>
-
-<mbean code="org.hibernate.jmx.HibernateService"
- name="jboss.jca:service=HibernateFactory,name=HibernateFactory">
-
- <!-- Required services -->
- <depends>jboss.jca:service=RARDeployer</depends>
- <depends>jboss.jca:service=LocalTxCM,name=HsqlDS</depends>
-
- <!-- Bind the Hibernate service to JNDI -->
- <attribute name="JndiName">java:/hibernate/SessionFactory</attribute>
-
- <!-- Datasource settings -->
- <attribute name="Datasource">java:HsqlDS</attribute>
- <attribute name="Dialect">org.hibernate.dialect.HSQLDialect</attribute>
-
- <!-- Transaction integration -->
- <attribute name="TransactionStrategy">
- org.hibernate.transaction.JTATransactionFactory</attribute>
- <attribute name="TransactionManagerLookupStrategy">
- org.hibernate.transaction.JBossTransactionManagerLookup</attribute>
- <attribute name="FlushBeforeCompletionEnabled">true</attribute>
- <attribute name="AutoCloseSessionEnabled">true</attribute>
-
- <!-- Fetching options -->
- <attribute name="MaximumFetchDepth">5</attribute>
-
- <!-- Second-level caching -->
- <attribute name="SecondLevelCacheEnabled">true</attribute>
- <attribute name="CacheProviderClass">org.hibernate.cache.EhCacheProvider</attribute>
- <attribute name="QueryCacheEnabled">true</attribute>
-
- <!-- Logging -->
- <attribute name="ShowSqlEnabled">true</attribute>
-
- <!-- Mapping files -->
- <attribute name="MapResources">auction/Item.hbm.xml,auction/Category.hbm.xml</attribute>
-
-</mbean>
-
-</server>]]></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) may be kept in their own JAR file, but you may 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>
-
- </sect2>
-
- </sect1>
-
-</chapter>
-
+<?xml version='1.0' encoding="UTF-8"?>
+<!--
+ ~ Hibernate, Relational Persistence for Idiomatic Java
+ ~
+ ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as
+ ~ indicated by the @author tags or express copyright attribution
+ ~ statements applied by the authors. All third-party contributions are
+ ~ distributed under license by Red Hat Middleware LLC.
+ ~
+ ~ This copyrighted material is made available to anyone wishing to use, modify,
+ ~ copy, or redistribute it subject to the terms and conditions of the GNU
+ ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~
+ ~ This program is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+ ~ for more details.
+ ~
+ ~ You should have received a copy of the GNU Lesser General Public License
+ ~ along with this distribution; if not, write to:
+ ~ Free Software Foundation, Inc.
+ ~ 51 Franklin Street, Fifth Floor
+ ~ Boston, MA 02110-1301 USA
+ -->
+
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<chapter id="session-configuration" revision="1">
+ <title>Configuration</title>
+
+ <para>
+ Because Hibernate is designed to operate in many different environments, there
+ are a large number 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 shows
+ the various options. Just put the example file in your classpath and customize it.
+ </para>
+
+ <sect1 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 may 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>:
+ </para>
+
+ <programlisting><![CDATA[Configuration cfg = new Configuration()
+ .addResource("Item.hbm.xml")
+ .addResource("Bid.hbm.xml");]]></programlisting>
+
+ <para>
+ An alternative (sometimes better) way is to specify the mapped class, and
+ let Hibernate find the mapping document for you:
+ </para>
+
+ <programlisting><![CDATA[Configuration cfg = new Configuration()
+ .addClass(org.hibernate.auction.Item.class)
+ .addClass(org.hibernate.auction.Bid.class);]]></programlisting>
+
+ <para>
+ Then Hibernate will look 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:
+ </para>
+
+ <programlisting><![CDATA[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.
+ The various 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><property></literal> elements in
+ <literal>hibernate.cfg.xml</literal> (discussed later).
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <para>
+ <filename>hibernate.properties</filename> is the easiest approach if you want to get started quickly.
+ </para>
+
+ <para>
+ The <classname>org.hibernate.cfg.Configuration</classname> is intended as a startup-time object,
+ to be discarded once a <literal>SessionFactory</literal> is created.
+ </para>
+
+ </sect1>
+
+ <sect1 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><![CDATA[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>
+
+ </sect1>
+
+ <sect1 id="configuration-hibernatejdbc" revision="1">
+ <title>JDBC connections</title>
+
+ <para>
+ Usually, you want 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><![CDATA[Session session = sessions.openSession(); // open a new Session]]></programlisting>
+
+ <para>
+ As soon as you do something that requires access to the database, a JDBC connection will be obtained from
+ the pool.
+ </para>
+
+ <para>
+ For this to work, we 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>. We will
+ now describe the most important settings for JDBC connection configuration.
+ </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'd like to use Proxool
+ refer to the packaged <filename>hibernate.properties</filename> and the Hibernate web site for more
+ information.
+ </para>
+
+ <para>
+ Here is an example <filename>hibernate.properties</filename> file for C3P0:
+ </para>
+
+ <programlisting id="c3p0-configuration" revision="1"><![CDATA[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.PostgreSQLDialect]]></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'll
+ 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's an example <filename>hibernate.properties</filename> file for an application server provided JNDI
+ datasource:
+ </para>
+
+ <programlisting><![CDATA[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.PostgreSQLDialect]]></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 may be given by prepending "<literal>hibernate.connection</literal>" to the
+ connection property name. For example, you may specify a <property>charSet</property>
+ connection property using <property>hibernate.connection.charSet</property>.
+ </para>
+
+ <para>
+ You may 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>
+
+ </sect1>
+
+ <sect1 id="configuration-optional" revision="1">
+ <title>Optional configuration properties</title>
+
+ <para>
+ There are a number of other properties that control the behaviour of Hibernate at runtime. All are optional
+ and have reasonable default values.
+ </para>
+
+ <para>
+ <emphasis>Warning: 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
+ may <emphasis>not</emphasis> be set by the other techniques described above.
+ </para>
+
+ <table frame="topbot" 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">eg.</emphasis>
+ <literal>full.classname.of.Dialect</literal>
+ </para>
+ <para>
+ In most cases Hibernate will actually be able to chose the correct
+ <classname>org.hibernate.dialect.Dialect</classname> implementation to use 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">eg.</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">eg.</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">eg.</emphasis>
+ <literal>SCHEMA_NAME</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <property>hibernate.default_catalog</property>
+ </entry>
+ <entry>
+ Qualify unqualified table names with the given catalog
+ in generated SQL.
+ <para>
+ <emphasis role="strong">eg.</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">eg.</emphasis>
+ <literal>jndi/composite/name</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <property>hibernate.max_fetch_depth</property>
+ </entry>
+ <entry>
+ Set 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">eg.</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>
+ Set a default size for Hibernate batch fetching of associations.
+ <para>
+ <emphasis role="strong">eg.</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>
+ Set 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>
+ Force 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">eg.</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">eg.</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">eg.</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">eg.</emphasis>
+ <literal>true</literal> | <literal>false</literal>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table frame="topbot" 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">eg.</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">eg.</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">eg.</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">eg.</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">eg.</emphasis>
+ <literal>true</literal> | <literal>false</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <property>hibernate.jdbc.use_get_generated_keys</property>
+ </entry>
+ <entry>
+ Enable 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, tries to determine the driver capabilities
+ using connection metadata.
+ <para>
+ <emphasis role="strong">eg.</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">eg.</emphasis>
+ <literal>classname.of.ConnectionProvider</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <property>hibernate.connection.isolation</property>
+ </entry>
+ <entry>
+ Set 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">eg.</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 (not recommended).
+ <para>
+ <emphasis role="strong">eg.</emphasis>
+ <literal>true</literal> | <literal>false</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <property>hibernate.connection.release_mode</property>
+ </entry>
+ <entry>
+ Specify 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, you should 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">eg.</emphasis>
+ <literal>auto</literal> (default) | <literal>on_close</literal> |
+ <literal>after_transaction</literal> | <literal>after_statement</literal>
+ </para>
+ <para>
+ Note that 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><propertyName></emphasis>
+ </entry>
+ <entry>
+ Pass the JDBC property <emphasis><propertyName></emphasis>
+ to <literal>DriverManager.getConnection()</literal>.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <property>hibernate.jndi.</property><emphasis><propertyName></emphasis>
+ </entry>
+ <entry>
+ Pass the property <emphasis><propertyName></emphasis> to
+ the JNDI <literal>InitialContextFactory</literal>.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table frame="topbot" 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">eg.</emphasis>
+ <literal>classname.of.CacheProvider</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>hibernate.cache.use_minimal_puts</literal>
+ </entry>
+ <entry>
+ Optimize 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">eg.</emphasis>
+ <literal>true|false</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>hibernate.cache.use_query_cache</literal>
+ </entry>
+ <entry>
+ Enable the query cache, individual queries still have to be set cachable.
+ <para>
+ <emphasis role="strong">eg.</emphasis>
+ <literal>true|false</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>hibernate.cache.use_second_level_cache</literal>
+ </entry>
+ <entry>
+ May be used to completely disable the second level cache, which is enabled
+ by default for classes which specify a <literal><cache></literal>
+ mapping.
+ <para>
+ <emphasis role="strong">eg.</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">eg.</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">eg.</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">eg.</emphasis>
+ <literal>true|false</literal>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table frame="topbot" 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">eg.</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">eg.</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>
+ - required when JVM-level caching is enabled or when using hilo
+ generator in a JTA environment.
+ <para>
+ <emphasis role="strong">eg.</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">eg.</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
+ utomatic session context management is preferred, see
+ <xref linkend="architecture-current-session"/>.
+ <para>
+ <emphasis role="strong">eg.</emphasis>
+ <literal>true</literal> | <literal>false</literal>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table frame="topbot" id="configuration-misc-properties" revision="10">
+ <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">eg.</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">eg.</emphasis>
+ <literal>org.hibernate.hql.ast.ASTQueryTranslatorFactory</literal> or
+ <literal>org.hibernate.hql.classic.ClassicQueryTranslatorFactory</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>hibernate.query.substitutions</literal>
+ </entry>
+ <entry>
+ Mapping from tokens in Hibernate queries to SQL tokens
+ (tokens might be function or literal names, for example).
+ <para>
+ <emphasis role="strong">eg.</emphasis>
+ <literal>hqlLiteral=SQL_LITERAL, hqlFunction=SQLFUNC</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>hibernate.hbm2ddl.auto</literal>
+ </entry>
+ <entry>
+ Automatically validate or export 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">eg.</emphasis>
+ <literal>validate</literal> | <literal>update</literal> |
+ <literal>create</literal> | <literal>create-drop</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>hibernate.cglib.use_reflection_optimizer</literal>
+ </entry>
+ <entry>
+ Enables use of CGLIB instead of runtime reflection (System-level
+ property). Reflection can sometimes be useful when troubleshooting,
+ note that Hibernate always requires CGLIB even if you turn off the
+ optimizer. You can not set this property in <literal>hibernate.cfg.xml</literal>.
+ <para>
+ <emphasis role="strong">eg.</emphasis>
+ <literal>true</literal> | <literal>false</literal>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <sect2 id="configuration-optional-dialects" revision="1">
+ <title>SQL Dialects</title>
+
+ <para>
+ You should 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, saving you the effort of specifying them manually.
+ </para>
+
+ <table frame="topbot" id="sql-dialects" revision="2">
+ <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</entry> <entry><literal>org.hibernate.dialect.PostgreSQLDialect</literal></entry>
+ </row>
+ <row>
+ <entry>MySQL</entry> <entry><literal>org.hibernate.dialect.MySQLDialect</literal></entry>
+ </row>
+ <row>
+ <entry>MySQL with InnoDB</entry> <entry><literal>org.hibernate.dialect.MySQLInnoDBDialect</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/10g</entry> <entry><literal>org.hibernate.dialect.Oracle9Dialect</literal></entry>
+ </row>
+ <row>
+ <entry>Sybase</entry> <entry><literal>org.hibernate.dialect.SybaseDialect</literal></entry>
+ </row>
+ <row>
+ <entry>Sybase Anywhere</entry> <entry><literal>org.hibernate.dialect.SybaseAnywhereDialect</literal></entry>
+ </row>
+ <row>
+ <entry>Microsoft SQL Server</entry> <entry><literal>org.hibernate.dialect.SQLServerDialect</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>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>
+
+ </sect2>
+
+ <sect2 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 (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 may 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 which have been mapped with
+ <literal>fetch="join"</literal>.
+ </para>
+
+ <para>
+ See <xref linkend="performance-fetching"/> for more information.
+ </para>
+
+ </sect2>
+
+ <sect2 id="configuration-optional-binarystreams" revision="1">
+ <title>Binary Streams</title>
+
+ <para>
+ Oracle limits the size of <literal>byte</literal> arrays that may
+ be passed to/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>
+
+ </sect2>
+
+ <sect2 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 details.
+ </para>
+
+ </sect2>
+
+ <sect2 id="configuration-optional-querysubstitution">
+ <title>Query Language Substitution</title>
+
+ <para>
+ You may define new Hibernate query tokens using <literal>hibernate.query.substitutions</literal>.
+ For example:
+ </para>
+
+ <programlisting>hibernate.query.substitutions true=1, false=0</programlisting>
+
+ <para>
+ 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>
+ would allow you to rename the SQL <literal>LOWER</literal> function.
+ </para>
+
+ </sect2>
+
+ <sect2 id="configuration-optional-statistics" revision="2">
+ <title>Hibernate statistics</title>
+
+ <para>
+ If you enable <literal>hibernate.generate_statistics</literal>, Hibernate will
+ expose 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>
+
+ </sect2>
+ </sect1>
+
+ <sect1 id="configuration-logging">
+ <title>Logging</title>
+
+ <para>
+ Hibernate Annotations utilizes <ulink url="http://www.slf4j.org/">Simple Logging Facade for Java</ulink>
+ (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 properly 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 <ulink url="http://www.slf4j.org/manual.html">documentation</ulink> 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>
+ We strongly recommend that you familiarize yourself with Hibernate's log
+ messages. A lot of work has been put into making the Hibernate log as
+ detailed as possible, without making it unreadable. It is an essential
+ troubleshooting device. The most interesting log categories are the
+ following:
+ </para>
+
+ <table frame="topbot" 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.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 (a lot of information, but very 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>
+
+
+ </sect1>
+
+ <sect1 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 may provide rules for automatically generating database identifiers from
+ Java identifiers or for processing "logical" column and table names given in
+ the mapping file into "physical" table and column names. This feature helps
+ reduce the verbosity of the mapping document, eliminating repetitive noise
+ (<literal>TBL_</literal> prefixes, for example). The default strategy used by
+ Hibernate is quite minimal.
+ </para>
+
+ <para>
+ You may specify a different strategy by calling
+ <literal>Configuration.setNamingStrategy()</literal> before adding mappings:
+ </para>
+
+ <programlisting><![CDATA[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>
+
+ </sect1>
+
+ <sect1 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 o
+ your <literal>CLASSPATH</literal>. Here is an example:
+ </para>
+
+ <programlisting><![CDATA[<?xml version='1.0' encoding='utf-8'?>
+<!DOCTYPE hibernate-configuration PUBLIC
+ "-//Hibernate/Hibernate Configuration DTD//EN"
+ "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">
+
+<hibernate-configuration>
+
+ <!-- a SessionFactory instance listed as /jndi/name -->
+ <session-factory
+ name="java:hibernate/SessionFactory">
+
+ <!-- properties -->
+ <property name="connection.datasource">java:/comp/env/jdbc/MyDB</property>
+ <property name="dialect">org.hibernate.dialect.MySQLDialect</property>
+ <property name="show_sql">false</property>
+ <property name="transaction.factory_class">
+ org.hibernate.transaction.JTATransactionFactory
+ </property>
+ <property name="jta.UserTransaction">java:comp/UserTransaction</property>
+
+ <!-- mapping files -->
+ <mapping resource="org/hibernate/auction/Item.hbm.xml"/>
+ <mapping resource="org/hibernate/auction/Bid.hbm.xml"/>
+
+ <!-- cache settings -->
+ <class-cache class="org.hibernate.auction.Item" usage="read-write"/>
+ <class-cache class="org.hibernate.auction.Bid" usage="read-only"/>
+ <collection-cache collection="org.hibernate.auction.Item.bids" usage="read-write"/>
+
+ </session-factory>
+
+</hibernate-configuration>]]></programlisting>
+
+ <para>
+ As you can see, 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. Note that 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><![CDATA[SessionFactory sf = new Configuration().configure().buildSessionFactory();]]></programlisting>
+
+ <para>
+ You can pick a different XML configuration file using
+ </para>
+
+ <programlisting><![CDATA[SessionFactory sf = new Configuration()
+ .configure("catdb.cfg.xml")
+ .buildSessionFactory();]]></programlisting>
+
+ </sect1>
+
+ <sect1 id="configuration-j2ee" revision="1">
+ <title>J2EE 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),
+ esp. distributed transaction handling across several datasources. You may
+ of course 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>
+ may 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 take care of 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 chose 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 ideally 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>
+
+ <sect2 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 may 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 (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 transaction if an existing transaction is
+ underway in this context (e.g. EJB session bean method), otherwise
+ a new transaction is started and bean-managed transaction 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 may 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 you have to specify how Hibernate should obtain a reference to the
+ <literal>TransactionManager</literal>, since J2EE does not standardize a single mechanism:
+ </para>
+
+ <table frame="topbot" 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</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>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </sect2>
+
+ <sect2 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
+ of the factory and the creation of new <literal>Session</literal>s. Note that this
+ is not 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 (eg. <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, e.g. Tomcat.)
+ </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 at least have
+ this call in some startup code (or utility class) in your application, unless you use
+ JMX deployment with the <literal>HibernateService</literal> (discussed later).
+ </para>
+
+ <para>
+ If you use a JNDI <literal>SessionFactory</literal>, an EJB or any other class may
+ obtain the <literal>SessionFactory</literal> using a JNDI lookup.
+ </para>
+
+ <para>
+ We recommend 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>
+
+ </sect2>
+
+ <sect2 id="configuration-j2ee-currentsession" revision="4">
+ <title>Current Session context management with JTA</title>
+
+ <para>
+ The easiest way to handle <literal>Session</literal>s and transactions is
+ Hibernates automatic "current" <literal>Session</literal> management.
+ See the discussion of <link linkend="architecture-current-session">current sessions</link>.
+ 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 <literal>"jta"</literal> context
+ will be 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>
+
+ </sect2>
+
+ <sect2 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 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><![CDATA[<?xml version="1.0"?>
+<server>
+
+<mbean code="org.hibernate.jmx.HibernateService"
+ name="jboss.jca:service=HibernateFactory,name=HibernateFactory">
+
+ <!-- Required services -->
+ <depends>jboss.jca:service=RARDeployer</depends>
+ <depends>jboss.jca:service=LocalTxCM,name=HsqlDS</depends>
+
+ <!-- Bind the Hibernate service to JNDI -->
+ <attribute name="JndiName">java:/hibernate/SessionFactory</attribute>
+
+ <!-- Datasource settings -->
+ <attribute name="Datasource">java:HsqlDS</attribute>
+ <attribute name="Dialect">org.hibernate.dialect.HSQLDialect</attribute>
+
+ <!-- Transaction integration -->
+ <attribute name="TransactionStrategy">
+ org.hibernate.transaction.JTATransactionFactory</attribute>
+ <attribute name="TransactionManagerLookupStrategy">
+ org.hibernate.transaction.JBossTransactionManagerLookup</attribute>
+ <attribute name="FlushBeforeCompletionEnabled">true</attribute>
+ <attribute name="AutoCloseSessionEnabled">true</attribute>
+
+ <!-- Fetching options -->
+ <attribute name="MaximumFetchDepth">5</attribute>
+
+ <!-- Second-level caching -->
+ <attribute name="SecondLevelCacheEnabled">true</attribute>
+ <attribute name="CacheProviderClass">org.hibernate.cache.EhCacheProvider</attribute>
+ <attribute name="QueryCacheEnabled">true</attribute>
+
+ <!-- Logging -->
+ <attribute name="ShowSqlEnabled">true</attribute>
+
+ <!-- Mapping files -->
+ <attribute name="MapResources">auction/Item.hbm.xml,auction/Category.hbm.xml</attribute>
+
+</mbean>
+
+</server>]]></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) may be kept in their own JAR file, but you may 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>
+
+ </sect2>
+
+ </sect1>
+
+</chapter>
+
More information about the hibernate-commits
mailing list