[hibernate-commits] Hibernate SVN: r15066 - core/trunk/documentation/manual/src/main/docbook/en-US/content.

Author: steve.ebersole(a)jboss.com Date: 2008-08-14 11:28:13 -0400 (Thu, 14 Aug 2008) New Revision: 15066 Modified: core/trunk/documentation/manual/src/main/docbook/en-US/content/configuration.xml Log: undo fixes for HHH-3080,HHH-3190,HHH-2976,HHH-3397 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-08-14 14:20:39 UTC (rev 15065) +++ core/trunk/documentation/manual/src/main/docbook/en-US/content/configuration.xml 2008-08-14 15:28:13 UTC (rev 15066) @@ -1,1759 +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>&lt;property&gt;</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>&lt;propertyName&gt;</emphasis> - </entry> - <entry> - Pass the JDBC property <emphasis>&lt;propertyName&gt;</emphasis> - to <literal>DriverManager.getConnection()</literal>. - </entry> - </row> - <row> - <entry> - <property>hibernate.jndi.</property><emphasis>&lt;propertyName&gt;</emphasis> - </entry> - <entry> - Pass the property <emphasis>&lt;propertyName&gt;</emphasis> to - the JNDI <literal>InitialContextFactory</literal>. - </entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="topbot" 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>&lt;cache&gt;</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</uli... 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&mdash;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>&lt;property&gt;</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>&lt;propertyName&gt;</emphasis> + </entry> + <entry> + Pass the JDBC property <emphasis>&lt;propertyName&gt;</emphasis> + to <literal>DriverManager.getConnection()</literal>. + </entry> + </row> + <row> + <entry> + <property>hibernate.jndi.</property><emphasis>&lt;propertyName&gt;</emphasis> + </entry> + <entry> + Pass the property <emphasis>&lt;propertyName&gt;</emphasis> to + the JNDI <literal>InitialContextFactory</literal>. + </entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="topbot" 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>&lt;cache&gt;</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 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</uli... 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&mdash;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> +