2004-08-17 06:42:31 -04:00
|
|
|
<chapter id="session-configuration" revision="1">
|
2004-06-03 12:31:32 -04:00
|
|
|
|
2004-08-17 06:42:31 -04:00
|
|
|
<title>Configuration</title>
|
2004-06-03 12:31:32 -04:00
|
|
|
|
|
|
|
|
<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
|
2004-08-17 06:42:31 -04:00
|
|
|
<literal>hibernate.properties</literal> file in <literal>etc/</literal> that shows
|
2005-01-30 07:43:12 -05:00
|
|
|
the various options. Just put the example file in your classpath and customize it.
|
2004-06-03 12:31:32 -04:00
|
|
|
</para>
|
|
|
|
|
|
2004-08-17 06:42:31 -04:00
|
|
|
<sect1 id="configuration-programmatic" revision="1">
|
|
|
|
|
<title>Programmatic configuration</title>
|
2004-06-03 12:31:32 -04:00
|
|
|
|
|
|
|
|
<para>
|
2004-08-09 23:16:42 -04:00
|
|
|
An instance of <literal>org.hibernate.cfg.Configuration</literal>
|
2004-08-20 08:48:17 -04:00
|
|
|
represents an entire set of mappings of an application's Java types to an
|
|
|
|
|
SQL database. The <literal>Configuration</literal> is used to build an
|
|
|
|
|
(immutable) <literal>SessionFactory</literal>. The mappings are compiled
|
2004-06-03 12:31:32 -04:00
|
|
|
from various XML mapping files.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
2005-01-30 07:43:12 -05:00
|
|
|
You may obtain a <literal>Configuration</literal> instance by instantiating
|
|
|
|
|
it directly and specifying XML mapping documents. If the mapping files are
|
|
|
|
|
in the classpath, use <literal>addResource()</literal>:
|
2004-06-03 12:31:32 -04:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<programlisting><![CDATA[Configuration cfg = new Configuration()
|
2005-01-30 07:43:12 -05:00
|
|
|
.addResource("Item.hbm.xml")
|
|
|
|
|
.addResource("Bid.hbm.xml");]]></programlisting>
|
2004-06-03 12:31:32 -04:00
|
|
|
|
|
|
|
|
<para>
|
2005-01-30 07:43:12 -05:00
|
|
|
An alternative (sometimes better) way is to specify the mapped class, and
|
|
|
|
|
let Hibernate find the mapping document for you:
|
2004-06-03 12:31:32 -04:00
|
|
|
</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
|
2004-08-20 08:48:17 -04:00
|
|
|
<literal>/org/hibernate/auction/Item.hbm.xml</literal> and
|
|
|
|
|
<literal>/org/hibernate/auction/Bid.hbm.xml</literal> in the classpath.
|
2004-06-03 12:31:32 -04:00
|
|
|
This approach eliminates any hardcoded filenames.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
2005-01-30 07:43:12 -05:00
|
|
|
A <literal>Configuration</literal> also allows you to specify configuration
|
|
|
|
|
properties:
|
2004-06-03 12:31:32 -04:00
|
|
|
</para>
|
|
|
|
|
|
2005-01-30 07:43:12 -05:00
|
|
|
<programlisting><![CDATA[Configuration cfg = new Configuration()
|
2004-06-03 12:31:32 -04:00
|
|
|
.addClass(org.hibernate.auction.Item.class)
|
|
|
|
|
.addClass(org.hibernate.auction.Bid.class)
|
2005-01-30 07:43:12 -05:00
|
|
|
.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 <literal>java.util.Properties</literal> to
|
|
|
|
|
<literal>Configuration.setProperties()</literal>.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
Place <literal>hibernate.properties</literal> in a root directory
|
|
|
|
|
of the classpath.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
Set <literal>System</literal> properties using
|
|
|
|
|
<literal>java -Dproperty=value</literal>.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
Include <literal><property></literal> elements in
|
|
|
|
|
<literal>hibernate.cfg.xml</literal> (discussed later).
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</orderedlist>
|
2004-06-03 12:31:32 -04:00
|
|
|
|
|
|
|
|
<para>
|
2005-02-28 07:43:52 -05:00
|
|
|
<literal>hibernate.properties</literal> is the easiest approach if you
|
2005-01-30 07:43:12 -05:00
|
|
|
want to get started quickly.
|
2004-06-03 12:31:32 -04:00
|
|
|
</para>
|
|
|
|
|
|
2004-08-17 06:42:31 -04:00
|
|
|
<para>
|
2005-01-30 07:43:12 -05:00
|
|
|
The <literal>Configuration</literal> is intended as a startup-time object,
|
|
|
|
|
to be discarded once a <literal>SessionFactory</literal> is created.
|
2004-08-17 06:42:31 -04:00
|
|
|
</para>
|
|
|
|
|
|
2004-06-03 12:31:32 -04:00
|
|
|
</sect1>
|
|
|
|
|
|
|
|
|
|
<sect1 id="configuration-sessionfactory">
|
|
|
|
|
<title>Obtaining a SessionFactory</title>
|
|
|
|
|
|
|
|
|
|
<para>
|
2005-01-30 07:43:12 -05:00
|
|
|
When all mappings have been parsed by the <literal>Configuration</literal>,
|
|
|
|
|
the application must obtain a factory for <literal>Session</literal> instances.
|
|
|
|
|
This factory is intended to be shared by all application threads:
|
2004-06-03 12:31:32 -04:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<programlisting><![CDATA[SessionFactory sessions = cfg.buildSessionFactory();]]></programlisting>
|
|
|
|
|
|
|
|
|
|
<para>
|
2005-01-30 07:43:12 -05:00
|
|
|
Hibernate does allow your application to instantiate more than one
|
|
|
|
|
<literal>SessionFactory</literal>. This is useful if you are using more than
|
|
|
|
|
one database.
|
2004-06-03 12:31:32 -04:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
</sect1>
|
|
|
|
|
|
2004-08-17 06:42:31 -04:00
|
|
|
<sect1 id="configuration-hibernatejdbc" revision="1">
|
2005-01-30 07:43:12 -05:00
|
|
|
<title>JDBC connections</title>
|
2004-06-03 12:31:32 -04:00
|
|
|
|
|
|
|
|
<para>
|
2005-01-30 07:43:12 -05:00
|
|
|
Usually, you want to have the <literal>SessionFactory</literal> create and pool JDBC
|
|
|
|
|
connections for you. If you take this approach, opening a <literal>Session</literal>
|
|
|
|
|
is as simple as:
|
2004-06-03 12:31:32 -04:00
|
|
|
</para>
|
|
|
|
|
|
2005-01-30 07:43:12 -05:00
|
|
|
<programlisting><![CDATA[Session session = sessions.openSession(); // open a new Session]]></programlisting>
|
|
|
|
|
|
2004-06-03 12:31:32 -04:00
|
|
|
<para>
|
2005-01-30 07:43:12 -05:00
|
|
|
As soon as you do something that requires access to the database, a JDBC connection
|
|
|
|
|
will be obtained from the pool.
|
2004-06-03 12:31:32 -04:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
2005-01-30 07:43:12 -05:00
|
|
|
For this to work, we need to pass some JDBC connection properties to Hibernate.
|
2004-06-03 12:31:32 -04:00
|
|
|
All Hibernate property names and semantics are defined on the class
|
2004-08-09 23:16:42 -04:00
|
|
|
<literal>org.hibernate.cfg.Environment</literal>. We will now describe the most
|
2004-06-03 12:31:32 -04:00
|
|
|
important settings for JDBC connection configuration.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
Hibernate will obtain (and pool) connections using <literal>java.sql.DriverManager</literal>
|
|
|
|
|
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>
|
|
|
|
|
<literal>hibernate.connection.driver_class</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
<emphasis>jdbc driver class</emphasis>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.connection.url</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
<emphasis>jdbc URL</emphasis>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.connection.username</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
<emphasis>database user</emphasis>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.connection.password</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
<emphasis>database user password</emphasis>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.connection.pool_size</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
<emphasis>maximum number of pooled connections</emphasis>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
|
|
|
|
</tbody>
|
|
|
|
|
</tgroup>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
<para>
|
2005-01-30 07:43:12 -05:00
|
|
|
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
|
|
|
|
|
<literal>hibernate.connection.pool_size</literal> property with connection
|
|
|
|
|
pool specific settings. This will turn off Hibernate's internal pool. For
|
|
|
|
|
example, you might like to use C3P0.
|
2004-06-03 12:31:32 -04:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
C3P0 is an open source JDBC connection pool distributed along with
|
2004-08-17 06:42:31 -04:00
|
|
|
Hibernate in the <literal>lib</literal> directory. Hibernate will use its
|
2004-06-03 12:31:32 -04:00
|
|
|
<literal>C3P0ConnectionProvider</literal> for connection pooling if you set
|
2004-08-17 06:42:31 -04:00
|
|
|
<literal>hibernate.c3p0.*</literal> properties. If you'd like to use Proxool
|
|
|
|
|
refer to the packaged <literal>hibernate.properties</literal> and the Hibernate
|
|
|
|
|
web site for more information.
|
2004-06-03 12:31:32 -04:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
2005-01-30 07:43:12 -05:00
|
|
|
Here is an example <literal>hibernate.properties</literal> file for C3P0:
|
2004-06-03 12:31:32 -04:00
|
|
|
</para>
|
|
|
|
|
|
2004-07-13 09:24:33 -04:00
|
|
|
<programlisting id="c3p0-configuration" revision="1"><![CDATA[hibernate.connection.driver_class = org.postgresql.Driver
|
2004-06-03 12:31:32 -04:00
|
|
|
hibernate.connection.url = jdbc:postgresql://localhost/mydatabase
|
|
|
|
|
hibernate.connection.username = myuser
|
|
|
|
|
hibernate.connection.password = secret
|
2004-07-13 09:24:33 -04:00
|
|
|
hibernate.c3p0.min_size=5
|
|
|
|
|
hibernate.c3p0.max_size=20
|
2004-06-03 12:31:32 -04:00
|
|
|
hibernate.c3p0.timeout=1800
|
2004-07-13 09:24:33 -04:00
|
|
|
hibernate.c3p0.max_statements=50
|
2004-08-09 23:16:42 -04:00
|
|
|
hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect]]></programlisting>
|
2004-06-03 12:31:32 -04:00
|
|
|
|
|
|
|
|
<para>
|
2005-01-30 07:43:12 -05:00
|
|
|
For use inside an application server, you should almost always configure
|
|
|
|
|
Hibernate to obtain connections from an application server
|
|
|
|
|
<literal>Datasource</literal> registered in JNDI. You'll need to set at
|
|
|
|
|
least one of the following properties:
|
2004-06-03 12:31:32 -04:00
|
|
|
</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>Propery name</entry>
|
|
|
|
|
<entry>Purpose</entry>
|
|
|
|
|
</row>
|
|
|
|
|
</thead>
|
|
|
|
|
<tbody>
|
|
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.connection.datasource</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
<emphasis>datasource JNDI name</emphasis>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.jndi.url</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
<emphasis>URL of the JNDI provider</emphasis> (optional)
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.jndi.class</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
<emphasis>class of the JNDI <literal>InitialContextFactory</literal></emphasis> (optional)
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.connection.username</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
<emphasis>database user</emphasis> (optional)
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.connection.password</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
<emphasis>database user password</emphasis> (optional)
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
|
|
|
|
</tbody>
|
|
|
|
|
</tgroup>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
<para>
|
2005-01-30 07:43:12 -05:00
|
|
|
Here's an example <literal>hibernate.properties</literal> file for an
|
|
|
|
|
application server provided JNDI datasource:
|
2004-06-03 12:31:32 -04:00
|
|
|
</para>
|
|
|
|
|
|
2005-01-30 07:43:12 -05:00
|
|
|
<programlisting><![CDATA[hibernate.connection.datasource = java:/comp/env/jdbc/test
|
2004-06-03 12:31:32 -04:00
|
|
|
hibernate.transaction.factory_class = \
|
2004-08-09 23:16:42 -04:00
|
|
|
org.hibernate.transaction.JTATransactionFactory
|
2004-06-03 12:31:32 -04:00
|
|
|
hibernate.transaction.manager_lookup_class = \
|
2004-08-09 23:16:42 -04:00
|
|
|
org.hibernate.transaction.JBossTransactionManagerLookup
|
2005-01-30 07:54:29 -05:00
|
|
|
hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect]]></programlisting>
|
2004-06-03 12:31:32 -04:00
|
|
|
|
|
|
|
|
<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.connnection</literal>" to the property name. For example, you
|
2005-01-30 07:43:12 -05:00
|
|
|
may specify a <literal>charSet</literal> using <literal>hibernate.connection.charSet</literal>.
|
2004-06-03 12:31:32 -04:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
You may define your own plugin strategy for obtaining JDBC connections by implementing the
|
2004-08-09 23:16:42 -04:00
|
|
|
interface <literal>org.hibernate.connection.ConnectionProvider</literal>. You may select
|
2004-06-03 12:31:32 -04:00
|
|
|
a custom implementation by setting <literal>hibernate.connection.provider_class</literal>.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
</sect1>
|
|
|
|
|
|
2004-08-17 06:42:31 -04:00
|
|
|
<sect1 id="configuration-optional" revision="1">
|
2004-06-03 12:31:32 -04:00
|
|
|
<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>
|
2005-01-30 07:43:12 -05:00
|
|
|
<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
|
|
|
|
|
<literal>hibernate.properties</literal>. They may <emphasis>not</emphasis> be set by
|
|
|
|
|
the other techniques described above.
|
2004-06-03 12:31:32 -04:00
|
|
|
</para>
|
|
|
|
|
|
2005-03-16 06:44:48 -05:00
|
|
|
<table frame="topbot" id="configuration-optional-properties" revision="8">
|
2004-06-03 12:31:32 -04:00
|
|
|
<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>
|
|
|
|
|
<literal>hibernate.dialect</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
2005-01-30 07:43:12 -05:00
|
|
|
The classname of a Hibernate <literal>Dialect</literal> which
|
|
|
|
|
allows Hibernate to generate SQL optimized for a particular
|
|
|
|
|
relational database.
|
2004-06-03 12:31:32 -04:00
|
|
|
<para>
|
|
|
|
|
<emphasis role="strong">eg.</emphasis>
|
|
|
|
|
<literal>full.classname.of.Dialect</literal>
|
|
|
|
|
</para>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
2005-01-30 07:43:12 -05:00
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.show_sql</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
Write all SQL statements to console.
|
|
|
|
|
<para>
|
|
|
|
|
<emphasis role="strong">eg.</emphasis>
|
|
|
|
|
<literal>true</literal> | <literal>false</literal>
|
|
|
|
|
</para>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
2004-06-03 12:31:32 -04:00
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.default_schema</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
Qualify unqualified tablenames with the given schema/tablespace
|
|
|
|
|
in generated SQL.
|
|
|
|
|
<para>
|
|
|
|
|
<emphasis role="strong">eg.</emphasis>
|
|
|
|
|
<literal>SCHEMA_NAME</literal>
|
|
|
|
|
</para>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
2004-08-20 08:48:17 -04:00
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.default_catalog</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
Qualify unqualified tablenames with the given catalog
|
|
|
|
|
in generated SQL.
|
|
|
|
|
<para>
|
|
|
|
|
<emphasis role="strong">eg.</emphasis>
|
|
|
|
|
<literal>CATALOG_NAME</literal>
|
|
|
|
|
</para>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
2004-06-03 12:31:32 -04:00
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.session_factory_name</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
The <literal>SessionFactory</literal> 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>
|
|
|
|
|
<literal>hibernate.max_fetch_depth</literal>
|
|
|
|
|
</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>
|
2005-01-30 07:43:12 -05:00
|
|
|
recommended values between <literal>0</literal> and
|
|
|
|
|
<literal>3</literal>
|
|
|
|
|
</para>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.default_batch_fetch_size</literal>
|
|
|
|
|
</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>
|
2005-03-16 06:44:48 -05:00
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.default_entity_mode</literal>
|
|
|
|
|
</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>
|
2005-01-30 07:43:12 -05:00
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.order_updates</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
Force Hibernate to order SQL updates by the primary key value
|
|
|
|
|
of the items being updates. 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>
|
|
|
|
|
<literal>hibernate.generate_statistics</literal>
|
|
|
|
|
</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>
|
|
|
|
|
<literal>hibernate.use_identifer_rollback</literal>
|
|
|
|
|
</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>
|
2004-06-03 12:31:32 -04:00
|
|
|
</para>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
2005-01-30 07:43:12 -05:00
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.use_sql_comments</literal>
|
|
|
|
|
</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>
|
|
|
|
|
|
2005-04-26 11:53:46 -04:00
|
|
|
<table frame="topbot" id="configuration-jdbc-properties" revision="8">
|
2005-01-30 07:43:12 -05:00
|
|
|
<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>
|
2004-06-03 12:31:32 -04:00
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.jdbc.fetch_size</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
A non-zero value determines the JDBC fetch size (calls
|
|
|
|
|
<literal>Statement.setFetchSize()</literal>).
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.jdbc.batch_size</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
A non-zero value enables use of JDBC2 batch updates by Hibernate.
|
|
|
|
|
<para>
|
2004-08-09 23:08:00 -04:00
|
|
|
<emphasis role="strong">eg.</emphasis>
|
2004-06-03 12:31:32 -04:00
|
|
|
recommended values between <literal>5</literal> and <literal>30</literal>
|
|
|
|
|
</para>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
2004-08-09 23:08:00 -04:00
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.jdbc.batch_versioned_data</literal>
|
|
|
|
|
</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>
|
2004-08-25 10:02:13 -04:00
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.jdbc.factory_class</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
Select a custom <literal>Batcher</literal>. Most applications
|
|
|
|
|
will not need this configuration property.
|
|
|
|
|
<para>
|
|
|
|
|
<emphasis role="strong">eg.</emphasis>
|
|
|
|
|
<literal>classname.of.Batcher</literal>
|
|
|
|
|
</para>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
2004-06-03 12:31:32 -04:00
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.jdbc.use_scrollable_resultset</literal>
|
|
|
|
|
</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>
|
|
|
|
|
<literal>hibernate.jdbc.use_streams_for_binary</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
Use streams when writing/reading <literal>binary</literal>
|
|
|
|
|
or <literal>serializable</literal> types to/from JDBC
|
|
|
|
|
(system-level property).
|
|
|
|
|
<para>
|
|
|
|
|
<emphasis role="strong">eg.</emphasis>
|
|
|
|
|
<literal>true</literal> | <literal>false</literal>
|
|
|
|
|
</para>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.jdbc.use_get_generated_keys</literal>
|
|
|
|
|
</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 capabilites
|
|
|
|
|
using connection metadata.
|
|
|
|
|
<para>
|
|
|
|
|
<emphasis role="strong">eg.</emphasis>
|
|
|
|
|
<literal>true|false</literal>
|
|
|
|
|
</para>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry>
|
2005-01-30 07:43:12 -05:00
|
|
|
<literal>hibernate.connection.provider_class</literal>
|
2004-06-03 12:31:32 -04:00
|
|
|
</entry>
|
|
|
|
|
<entry>
|
2005-01-30 07:43:12 -05:00
|
|
|
The classname of a custom <literal>ConnectionProvider</literal> which provides
|
|
|
|
|
JDBC connections to Hibernate.
|
2004-06-03 12:31:32 -04:00
|
|
|
<para>
|
|
|
|
|
<emphasis role="strong">eg.</emphasis>
|
2005-01-30 07:43:12 -05:00
|
|
|
<literal>classname.of.ConnectionProvider</literal>
|
2004-06-03 12:31:32 -04:00
|
|
|
</para>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.connection.isolation</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
Set the JDBC transaction isolation level. Check
|
|
|
|
|
<literal>java.sql.Connection</literal> for meaningful values but
|
|
|
|
|
note that most databases do not support all isolation levels.
|
|
|
|
|
<para>
|
|
|
|
|
<emphasis role="strong">eg.</emphasis>
|
|
|
|
|
<literal>1, 2, 4, 8</literal>
|
|
|
|
|
</para>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
2005-01-30 07:43:12 -05:00
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.connection.autocommit</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
Enables autocommit for JDBC pooled connections (not recommended).
|
|
|
|
|
<para>
|
|
|
|
|
<emphasis role="strong">eg.</emphasis>
|
|
|
|
|
<literal>true</literal> | <literal>false</literal>
|
|
|
|
|
</para>
|
|
|
|
|
</entry>
|
2005-04-26 11:41:51 -04:00
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry>
|
2005-05-03 20:30:31 -04:00
|
|
|
<literal>hibernate.connection.release_mode</literal>
|
|
|
|
|
</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.
|
2005-04-26 17:24:26 -04:00
|
|
|
<para>
|
2005-05-03 20:30:31 -04:00
|
|
|
<literal>on_close</literal> | <literal>after_transaction</literal> |
|
|
|
|
|
<literal>after_statement</literal> | <literal>auto</literal>
|
2005-04-26 17:24:26 -04:00
|
|
|
</para>
|
2005-04-26 11:41:51 -04:00
|
|
|
</entry>
|
2005-01-30 07:43:12 -05:00
|
|
|
</row>
|
2004-06-03 12:31:32 -04:00
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.connection.<emphasis><propertyName></emphasis></literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
Pass the JDBC property <literal>propertyName</literal>
|
|
|
|
|
to <literal>DriverManager.getConnection()</literal>.
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry>
|
2005-01-30 07:43:12 -05:00
|
|
|
<literal>hibernate.jndi.<emphasis><propertyName></emphasis></literal>
|
2004-06-03 12:31:32 -04:00
|
|
|
</entry>
|
|
|
|
|
<entry>
|
2005-01-30 07:43:12 -05:00
|
|
|
Pass the property <literal>propertyName</literal> to
|
|
|
|
|
the JNDI <literal>InitialContextFactory</literal>.
|
2004-06-03 12:31:32 -04:00
|
|
|
</entry>
|
|
|
|
|
</row>
|
2005-01-30 07:43:12 -05:00
|
|
|
</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>
|
2004-06-03 12:31:32 -04:00
|
|
|
<row>
|
2005-01-30 07:43:12 -05:00
|
|
|
<entry>Property name</entry>
|
|
|
|
|
<entry>Purpose</entry>
|
|
|
|
|
</row>
|
|
|
|
|
</thead>
|
|
|
|
|
<tbody>
|
|
|
|
|
<row>
|
2004-06-03 12:31:32 -04:00
|
|
|
<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
|
2005-02-05 23:12:30 -05:00
|
|
|
cost of more frequent reads. This setting is most useful for
|
|
|
|
|
clustered caches and, in Hibernate3, is enabled by default for
|
|
|
|
|
clustered cache implementations.
|
2004-06-03 12:31:32 -04:00
|
|
|
<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>
|
2005-01-30 07:43:12 -05:00
|
|
|
<row>
|
|
|
|
|
<entry>
|
2005-02-05 23:12:30 -05:00
|
|
|
<literal>hibernate.cache.use_second_level_cache</literal>
|
2005-01-30 07:43:12 -05:00
|
|
|
</entry>
|
|
|
|
|
<entry>
|
|
|
|
|
May be used to completely disable the second level cache, which is enabled
|
|
|
|
|
by default for classes which specify a <literal><cache></literal>
|
|
|
|
|
mapping.
|
|
|
|
|
<para>
|
|
|
|
|
<emphasis role="strong">eg.</emphasis>
|
|
|
|
|
<literal>true|false</literal>
|
|
|
|
|
</para>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
2004-08-09 23:08:00 -04:00
|
|
|
<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>
|
2004-06-03 12:31:32 -04:00
|
|
|
<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>
|
2005-01-24 11:51:49 -05:00
|
|
|
<row>
|
|
|
|
|
<entry>
|
|
|
|
|
<literal>hibernate.cache.use_structured_entries</literal>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>
|
2005-01-30 07:43:12 -05:00
|
|
|
Forces Hibernate to store data in the second-level cache
|
|
|
|
|
in a more human-friendly format.
|
2005-01-24 11:51:49 -05:00
|
|
|
<para>
|
|
|
|
|
<emphasis role="strong">eg.</emphasis>
|
|
|
|
|
<literal>true|false</literal>
|
|
|
|
|
</para>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
2005-01-30 07:43:12 -05:00
|
|
|
</tbody>
|
|
|
|
|
</tgroup>
|
|
|
|
|
</table>
|
|
|
|
|
|
2005-02-13 17:39:49 -05:00
|
|
|
<table frame="topbot" id="configuration-transaction-properties" revision="8">
|
2005-01-30 07:43:12 -05:00
|
|
|
<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>
|
2004-06-03 12:31:32 -04:00
|
|
|
<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>
|
2005-02-13 17:39:49 -05:00
|
|
|
- required when JVM-level caching is enabled or when using hilo
|
|
|
|
|
generator in a JTA environment.
|
2004-06-03 12:31:32 -04:00
|
|
|
<para>
|
|
|
|
|
<emphasis role="strong">eg.</emphasis>
|
|
|
|
|
<literal>classname.of.TransactionManagerLookup</literal>
|
|
|
|
|
</para>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry>
|
2005-01-30 07:43:12 -05:00
|
|
|
<literal>hibernate.transaction.flush_before_completion</literal>
|
2004-06-03 12:31:32 -04:00
|
|
|
</entry>
|
|
|
|
|
<entry>
|
2005-01-30 07:43:12 -05:00
|
|
|
If enabled, the session will be automatically flushed during the
|
|
|
|
|
before completion phase of the transaction. (Very useful when
|
|
|
|
|
using Hibernate with CMT.)
|
2004-06-03 12:31:32 -04:00
|
|
|
<para>
|
|
|
|
|
<emphasis role="strong">eg.</emphasis>
|
2005-01-30 07:43:12 -05:00
|
|
|
<literal>true</literal> | <literal>false</literal>
|
2004-06-03 12:31:32 -04:00
|
|
|
</para>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry>
|
2005-01-30 07:43:12 -05:00
|
|
|
<literal>hibernate.transaction.auto_close_session</literal>
|
2004-06-03 12:31:32 -04:00
|
|
|
</entry>
|
|
|
|
|
<entry>
|
2005-01-30 07:43:12 -05:00
|
|
|
If enabled, the session will be automatically closed during the
|
|
|
|
|
before completion phase of the transaction. (Very useful when
|
|
|
|
|
using Hibernate with CMT.)
|
2004-06-03 12:31:32 -04:00
|
|
|
<para>
|
|
|
|
|
<emphasis role="strong">eg.</emphasis>
|
|
|
|
|
<literal>true</literal> | <literal>false</literal>
|
|
|
|
|
</para>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
2005-01-30 07:43:12 -05:00
|
|
|
</tbody>
|
|
|
|
|
</tgroup>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
<table frame="topbot" id="configuration-misc-properties" revision="7">
|
|
|
|
|
<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>
|
2004-06-03 12:31:32 -04:00
|
|
|
<row>
|
|
|
|
|
<entry>
|
2005-01-30 07:43:12 -05:00
|
|
|
<literal>hibernate.query.factory_class</literal>
|
2004-06-03 12:31:32 -04:00
|
|
|
</entry>
|
|
|
|
|
<entry>
|
2005-01-30 07:43:12 -05:00
|
|
|
Chooses the HQL parser implementation.
|
2004-06-03 12:31:32 -04:00
|
|
|
<para>
|
|
|
|
|
<emphasis role="strong">eg.</emphasis>
|
2005-01-30 07:43:12 -05:00
|
|
|
<literal>org.hibernate.hql.ast.ASTQueryTranslatorFactory</literal> or
|
|
|
|
|
<literal>org.hibernate.hql.classic.ClassicQueryTranslatorFactory</literal>
|
2004-06-03 12:31:32 -04:00
|
|
|
</para>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
2004-08-17 06:42:31 -04:00
|
|
|
<row>
|
|
|
|
|
<entry>
|
2005-01-30 07:43:12 -05:00
|
|
|
<literal>hibernate.query.substitutions</literal>
|
2004-08-17 06:42:31 -04:00
|
|
|
</entry>
|
|
|
|
|
<entry>
|
2005-01-30 07:43:12 -05:00
|
|
|
Mapping from tokens in Hibernate queries to SQL tokens
|
|
|
|
|
(tokens might be function or literal names, for example).
|
2004-08-20 08:48:17 -04:00
|
|
|
<para>
|
2005-01-30 07:43:12 -05:00
|
|
|
<emphasis role="strong">eg.</emphasis>
|
|
|
|
|
<literal>hqlLiteral=SQL_LITERAL, hqlFunction=SQLFUNC</literal>
|
2004-08-20 08:48:17 -04:00
|
|
|
</para>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry>
|
2005-01-30 07:43:12 -05:00
|
|
|
<literal>hibernate.hbm2ddl.auto</literal>
|
2004-08-20 08:48:17 -04:00
|
|
|
</entry>
|
|
|
|
|
<entry>
|
2005-01-30 07:43:12 -05:00
|
|
|
Automatically 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.
|
2004-08-17 06:42:31 -04:00
|
|
|
<para>
|
2005-01-30 07:43:12 -05:00
|
|
|
<emphasis role="strong">eg.</emphasis>
|
|
|
|
|
<literal>update</literal> | <literal>create</literal> | <literal>create-drop</literal>
|
2004-08-17 06:42:31 -04:00
|
|
|
</para>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
2004-08-17 12:03:26 -04:00
|
|
|
<row>
|
|
|
|
|
<entry>
|
2005-01-30 07:43:12 -05:00
|
|
|
<literal>hibernate.cglib.use_reflection_optimizer</literal>
|
2004-08-17 12:03:26 -04:00
|
|
|
</entry>
|
|
|
|
|
<entry>
|
2005-01-30 07:43:12 -05:00
|
|
|
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>.
|
2004-08-17 12:03:26 -04:00
|
|
|
<para>
|
2005-01-30 07:43:12 -05:00
|
|
|
<emphasis role="strong">eg.</emphasis>
|
2004-08-17 12:03:26 -04:00
|
|
|
<literal>true</literal> | <literal>false</literal>
|
|
|
|
|
</para>
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
2004-06-03 12:31:32 -04:00
|
|
|
</tbody>
|
|
|
|
|
</tgroup>
|
|
|
|
|
</table>
|
|
|
|
|
|
2005-01-27 08:34:18 -05:00
|
|
|
<sect2 id="configuration-optional-dialects" revision="1">
|
2004-06-03 12:31:32 -04:00
|
|
|
<title>SQL Dialects</title>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
You should always set the <literal>hibernate.dialect</literal> property to the correct
|
2005-01-27 08:34:18 -05:00
|
|
|
<literal>org.hibernate.dialect.Dialect</literal> subclass for your database. If you
|
|
|
|
|
specify a dialect, Hibernate will use sensible defaults for some of the
|
2004-06-03 12:31:32 -04:00
|
|
|
other properties listed above, saving you the effort of specifying them manually.
|
|
|
|
|
</para>
|
|
|
|
|
|
2004-08-09 23:08:00 -04:00
|
|
|
<table frame="topbot" id="sql-dialects" revision="2">
|
2004-06-03 12:31:32 -04:00
|
|
|
<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>
|
2004-08-09 23:16:42 -04:00
|
|
|
<entry>DB2</entry> <entry><literal>org.hibernate.dialect.DB2Dialect</literal></entry>
|
2004-06-03 12:31:32 -04:00
|
|
|
</row>
|
|
|
|
|
<row>
|
2004-08-09 23:16:42 -04:00
|
|
|
<entry>DB2 AS/400</entry> <entry><literal>org.hibernate.dialect.DB2400Dialect</literal></entry>
|
2004-06-03 12:31:32 -04:00
|
|
|
</row>
|
|
|
|
|
<row>
|
2004-08-09 23:16:42 -04:00
|
|
|
<entry>DB2 OS390</entry> <entry><literal>org.hibernate.dialect.DB2390Dialect</literal></entry>
|
2004-08-09 23:08:00 -04:00
|
|
|
</row>
|
|
|
|
|
<row>
|
2004-08-09 23:16:42 -04:00
|
|
|
<entry>PostgreSQL</entry> <entry><literal>org.hibernate.dialect.PostgreSQLDialect</literal></entry>
|
2004-08-09 23:08:00 -04:00
|
|
|
</row>
|
|
|
|
|
<row>
|
2004-08-09 23:16:42 -04:00
|
|
|
<entry>MySQL</entry> <entry><literal>org.hibernate.dialect.MySQLDialect</literal></entry>
|
2004-06-03 12:31:32 -04:00
|
|
|
</row>
|
2005-01-30 07:43:12 -05:00
|
|
|
<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>
|
2004-06-03 12:31:32 -04:00
|
|
|
<row>
|
2004-08-09 23:16:42 -04:00
|
|
|
<entry>Oracle (any version)</entry> <entry><literal>org.hibernate.dialect.OracleDialect</literal></entry>
|
2004-06-03 12:31:32 -04:00
|
|
|
</row>
|
|
|
|
|
<row>
|
2005-01-30 07:43:12 -05:00
|
|
|
<entry>Oracle 9i/10g</entry> <entry><literal>org.hibernate.dialect.Oracle9Dialect</literal></entry>
|
2004-06-03 12:31:32 -04:00
|
|
|
</row>
|
|
|
|
|
<row>
|
2004-08-09 23:16:42 -04:00
|
|
|
<entry>Sybase</entry> <entry><literal>org.hibernate.dialect.SybaseDialect</literal></entry>
|
2004-06-03 12:31:32 -04:00
|
|
|
</row>
|
|
|
|
|
<row>
|
2004-08-09 23:16:42 -04:00
|
|
|
<entry>Sybase Anywhere</entry> <entry><literal>org.hibernate.dialect.SybaseAnywhereDialect</literal></entry>
|
2004-06-03 12:31:32 -04:00
|
|
|
</row>
|
|
|
|
|
<row>
|
2004-08-09 23:16:42 -04:00
|
|
|
<entry>Microsoft SQL Server</entry> <entry><literal>org.hibernate.dialect.SQLServerDialect</literal></entry>
|
2004-06-03 12:31:32 -04:00
|
|
|
</row>
|
|
|
|
|
<row>
|
2004-08-09 23:16:42 -04:00
|
|
|
<entry>SAP DB</entry> <entry><literal>org.hibernate.dialect.SAPDBDialect</literal></entry>
|
2004-06-03 12:31:32 -04:00
|
|
|
</row>
|
|
|
|
|
<row>
|
2004-08-09 23:16:42 -04:00
|
|
|
<entry>Informix</entry> <entry><literal>org.hibernate.dialect.InformixDialect</literal></entry>
|
2004-06-03 12:31:32 -04:00
|
|
|
</row>
|
|
|
|
|
<row>
|
2004-08-09 23:16:42 -04:00
|
|
|
<entry>HypersonicSQL</entry> <entry><literal>org.hibernate.dialect.HSQLDialect</literal></entry>
|
2004-06-03 12:31:32 -04:00
|
|
|
</row>
|
|
|
|
|
<row>
|
2004-08-09 23:16:42 -04:00
|
|
|
<entry>Ingres</entry> <entry><literal>org.hibernate.dialect.IngresDialect</literal></entry>
|
2004-06-03 12:31:32 -04:00
|
|
|
</row>
|
|
|
|
|
<row>
|
2004-08-09 23:16:42 -04:00
|
|
|
<entry>Progress</entry> <entry><literal>org.hibernate.dialect.ProgressDialect</literal></entry>
|
2004-06-03 12:31:32 -04:00
|
|
|
</row>
|
|
|
|
|
<row>
|
2004-08-09 23:16:42 -04:00
|
|
|
<entry>Mckoi SQL</entry> <entry><literal>org.hibernate.dialect.MckoiDialect</literal></entry>
|
2004-06-03 12:31:32 -04:00
|
|
|
</row>
|
|
|
|
|
<row>
|
2004-08-09 23:16:42 -04:00
|
|
|
<entry>Interbase</entry> <entry><literal>org.hibernate.dialect.InterbaseDialect</literal></entry>
|
2004-06-03 12:31:32 -04:00
|
|
|
</row>
|
|
|
|
|
<row>
|
2004-08-09 23:16:42 -04:00
|
|
|
<entry>Pointbase</entry> <entry><literal>org.hibernate.dialect.PointbaseDialect</literal></entry>
|
2004-06-03 12:31:32 -04:00
|
|
|
</row>
|
|
|
|
|
<row>
|
2004-08-09 23:16:42 -04:00
|
|
|
<entry>FrontBase</entry> <entry><literal>org.hibernate.dialect.FrontbaseDialect</literal></entry>
|
2004-06-03 12:31:32 -04:00
|
|
|
</row>
|
2004-08-09 23:08:00 -04:00
|
|
|
<row>
|
2004-08-09 23:16:42 -04:00
|
|
|
<entry>Firebird</entry> <entry><literal>org.hibernate.dialect.FirebirdDialect</literal></entry>
|
2004-08-09 23:08:00 -04:00
|
|
|
</row>
|
2004-06-03 12:31:32 -04:00
|
|
|
</tbody>
|
|
|
|
|
</tgroup>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
</sect2>
|
|
|
|
|
|
2005-01-30 07:43:12 -05:00
|
|
|
<sect2 id="configuration-optional-outerjoin" revision="4">
|
2004-06-03 12:31:32 -04:00
|
|
|
<title>Outer Join Fetching</title>
|
|
|
|
|
|
|
|
|
|
<para>
|
2004-08-20 08:48:17 -04:00
|
|
|
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
|
2004-06-03 12:31:32 -04:00
|
|
|
trips to and from the database (at the cost of possibly more work performed by
|
2004-08-20 08:48:17 -04:00
|
|
|
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
|
2004-12-13 17:15:30 -05:00
|
|
|
in a single SQL <literal>SELECT</literal>.
|
2004-06-03 12:31:32 -04:00
|
|
|
</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
|
2005-01-30 07:43:12 -05:00
|
|
|
one-to-one and many-to-one associations which have been mapped with
|
|
|
|
|
<literal>fetch="join"</literal>.
|
2005-01-24 09:54:21 -05:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
See <xref linkend="performance-fetching"/> for more information.
|
2004-06-03 12:31:32 -04:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
</sect2>
|
|
|
|
|
|
2004-08-17 06:42:31 -04:00
|
|
|
<sect2 id="configuration-optional-binarystreams" revision="1">
|
2004-06-03 12:31:32 -04:00
|
|
|
<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>.
|
2004-08-17 06:42:31 -04:00
|
|
|
<emphasis>This is a system-level setting only.</emphasis>
|
2004-06-03 12:31:32 -04:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
</sect2>
|
|
|
|
|
|
2005-01-27 08:34:18 -05:00
|
|
|
<sect2 id="configuration-optional-cacheprovider" revision="2">
|
2004-08-20 08:48:17 -04:00
|
|
|
<title>Second-level and query cache</title>
|
2004-06-03 12:31:32 -04:00
|
|
|
|
|
|
|
|
<para>
|
2004-08-20 08:48:17 -04:00
|
|
|
The properties prefixed by <literal>hibernate.cache</literal>
|
2004-12-13 17:15:30 -05:00
|
|
|
allow you to use a process or cluster scoped second-level cache system
|
2005-01-27 08:34:18 -05:00
|
|
|
with Hibernate. See the <xref linkend="performance-cache"/> for
|
|
|
|
|
more details.
|
2004-06-03 12:31:32 -04:00
|
|
|
</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>
|
|
|
|
|
|
2005-01-27 08:34:18 -05:00
|
|
|
<sect2 id="configuration-optional-statistics" revision="2">
|
2004-08-20 08:48:17 -04:00
|
|
|
<title>Hibernate statistics</title>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
If you enable <literal>hibernate.generate_statistics</literal>, Hibernate will
|
2004-12-13 17:15:30 -05:00
|
|
|
expose a number of metrics that are useful when tuning a running system via
|
|
|
|
|
<literal>SessionFactory.getStatistics()</literal>. Hibernate can even be configured
|
2005-01-27 08:34:18 -05:00
|
|
|
to expose these statistics via JMX. Read the Javadoc of the interfaces in
|
|
|
|
|
<literal>org.hibernate.stats</literal> for more information.
|
2004-08-20 08:48:17 -04:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
</sect2>
|
2004-06-03 12:31:32 -04:00
|
|
|
</sect1>
|
|
|
|
|
|
|
|
|
|
<sect1 id="configuration-logging">
|
|
|
|
|
<title>Logging</title>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
Hibernate logs various events using Apache commons-logging.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
The commons-logging service will direct output to either Apache Log4j
|
|
|
|
|
(if you include <literal>log4j.jar</literal> in your classpath) or
|
|
|
|
|
JDK1.4 logging (if running under JDK1.4 or above). You may download
|
|
|
|
|
Log4j from <literal>http://jakarta.apache.org</literal>.
|
|
|
|
|
To use Log4j you will need to place a <literal>log4j.properties</literal>
|
|
|
|
|
file in your classpath, an example properties file is distributed with
|
|
|
|
|
Hibernate in the <literal>src/</literal> directory.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
We strongly recommend that you familiarize yourself with Hibernate's log
|
|
|
|
|
messages. A lot of work has been put into making the Hibernate log as
|
|
|
|
|
detailed as possible, without making it unreadable. It is an essential
|
2005-02-06 01:42:54 -05:00
|
|
|
troubleshooting device. The most interesting log categories are the
|
|
|
|
|
following:
|
2004-06-03 12:31:32 -04:00
|
|
|
</para>
|
|
|
|
|
|
2005-02-06 01:42:54 -05:00
|
|
|
<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>
|
2005-02-08 09:06:50 -05:00
|
|
|
<row>
|
|
|
|
|
<entry><literal>org.hibernate.transaction</literal></entry>
|
|
|
|
|
<entry>Log transaction related activity</entry>
|
|
|
|
|
</row>
|
2005-02-06 01:42:54 -05:00
|
|
|
<row>
|
|
|
|
|
<entry><literal>org.hibernate.jdbc</literal></entry>
|
|
|
|
|
<entry>Log all JDBC resource acquisition</entry>
|
|
|
|
|
</row>
|
2005-04-05 09:48:35 -04:00
|
|
|
<row>
|
|
|
|
|
<entry><literal>org.hibernate.hql.ast</literal></entry>
|
|
|
|
|
<entry>
|
|
|
|
|
Log HQL and SQL ASTs and other information about
|
|
|
|
|
query parsing
|
|
|
|
|
</entry>
|
|
|
|
|
</row>
|
2005-02-06 01:42:54 -05:00
|
|
|
<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
|
2005-02-06 01:43:30 -05:00
|
|
|
troubleshooting)
|
2005-02-06 01:42:54 -05:00
|
|
|
</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>
|
|
|
|
|
|
|
|
|
|
|
2004-06-03 12:31:32 -04:00
|
|
|
</sect1>
|
|
|
|
|
|
|
|
|
|
<sect1 id="configuration-namingstrategy">
|
|
|
|
|
<title>Implementing a <literal>NamingStrategy</literal></title>
|
|
|
|
|
|
|
|
|
|
<para>
|
2004-08-09 23:16:42 -04:00
|
|
|
The interface <literal>org.hibernate.cfg.NamingStrategy</literal> allows you
|
2004-06-03 12:31:32 -04:00
|
|
|
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>
|
2004-08-09 23:16:42 -04:00
|
|
|
<literal>org.hibernate.cfg.ImprovedNamingStrategy</literal> is a built-in
|
2004-06-03 12:31:32 -04:00
|
|
|
strategy that might be a useful starting point for some applications.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
</sect1>
|
|
|
|
|
|
2005-01-27 08:34:18 -05:00
|
|
|
<sect1 id="configuration-xmlconfig" revision="2">
|
|
|
|
|
<title>XML configuration file</title>
|
2004-06-03 12:31:32 -04:00
|
|
|
|
|
|
|
|
<para>
|
2004-08-17 06:42:31 -04:00
|
|
|
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
|
2004-08-20 08:48:17 -04:00
|
|
|
are present, to override properties.
|
2004-06-03 12:31:32 -04:00
|
|
|
</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
|
2004-08-09 23:16:42 -04:00
|
|
|
"-//Hibernate/Hibernate Configuration DTD//EN"
|
|
|
|
|
"http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">
|
2004-06-03 12:31:32 -04:00
|
|
|
|
|
|
|
|
<hibernate-configuration>
|
|
|
|
|
|
|
|
|
|
<!-- a SessionFactory instance listed as /jndi/name -->
|
|
|
|
|
<session-factory
|
2004-08-17 06:42:31 -04:00
|
|
|
name="java:hibernate/SessionFactory">
|
2004-06-03 12:31:32 -04:00
|
|
|
|
|
|
|
|
<!-- properties -->
|
2004-08-17 06:42:31 -04:00
|
|
|
<property name="connection.datasource">java:/comp/env/jdbc/MyDB</property>
|
2004-08-09 23:16:42 -04:00
|
|
|
<property name="dialect">org.hibernate.dialect.MySQLDialect</property>
|
2004-06-03 12:31:32 -04:00
|
|
|
<property name="show_sql">false</property>
|
|
|
|
|
<property name="transaction.factory_class">
|
2004-08-09 23:16:42 -04:00
|
|
|
org.hibernate.transaction.JTATransactionFactory
|
2004-06-03 12:31:32 -04:00
|
|
|
</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"/>
|
|
|
|
|
|
2005-01-27 08:34:18 -05:00
|
|
|
<!-- cache settings -->
|
|
|
|
|
<class-cache class="org.hibernate.auction.Item" usage="read-write"/>
|
|
|
|
|
<class-cache class="org.hibernate.auction.Bid" usage="read-only"/>
|
|
|
|
|
<collection-cache class="org.hibernate.auction.Item.bids" usage="read-write"/>
|
|
|
|
|
|
2004-06-03 12:31:32 -04:00
|
|
|
</session-factory>
|
|
|
|
|
|
|
|
|
|
</hibernate-configuration>]]></programlisting>
|
|
|
|
|
|
2004-08-17 06:42:31 -04:00
|
|
|
<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>
|
2005-01-27 08:34:18 -05:00
|
|
|
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.
|
2004-08-17 06:42:31 -04:00
|
|
|
</para>
|
|
|
|
|
|
2004-06-03 12:31:32 -04:00
|
|
|
<para>
|
2005-01-27 08:34:18 -05:00
|
|
|
With the XML configuration, starting Hibernate is then as simple as
|
2004-06-03 12:31:32 -04:00
|
|
|
</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>
|
|
|
|
|
|
2005-04-19 13:35:20 -04:00
|
|
|
<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 programatically (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 if you use EJBs. 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 declarative, in EJB deployment descriptors.
|
|
|
|
|
</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>
|
|
|
|
|
|
2005-04-26 17:24:26 -04:00
|
|
|
<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>
|
|
|
|
|
|
2005-04-19 13:35:20 -04:00
|
|
|
<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, automatic JTA and Session binding, 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="2">
|
|
|
|
|
<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. Note that this
|
|
|
|
|
setup is not neccessary if you use the <literal>HibernateUtil</literal> helper class
|
|
|
|
|
introduced in chapter one, which acts as a Singleton registry. However,
|
|
|
|
|
<literal>HibernateUtil</literal> is more common in a non-managed environment.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
|
|
<sect2 id="configuration-j2ee-currentsession" revision="1">
|
|
|
|
|
<title>Automatic JTA and Session binding</title>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
For non-managed environments we suggested <literal>HibernateUtil</literal> with
|
|
|
|
|
a static <literal>SessionFactory</literal>, and <literal>ThreadLocal</literal>
|
|
|
|
|
management of the Hibernate <literal>Session</literal>. This approach isn't easy
|
|
|
|
|
to use in an EJB environment, as several EJB's may execute inside the same
|
|
|
|
|
transaction but not the same thread. We recommend that you bind the
|
|
|
|
|
<literal>SessionFactory</literal> to JNDI in a managend environment.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
Instead of rolling your own <literal>ThreadLocal</literal> utility, use the
|
|
|
|
|
<literal>getCurrentSession()</literal> method on the <literal>SessionFactory</literal>
|
|
|
|
|
to obtain a Hibernate <literal>Session</literal>. If there is no Hibernate
|
|
|
|
|
<literal>Session</literal> in current JTA transaction, one will be started and
|
2005-04-20 11:00:47 -04:00
|
|
|
assigned. Both the <literal>hibernate.transaction.flush_before_completion</literal>
|
|
|
|
|
and <literal>hibernate.transaction.auto_close_session</literal> configuration option,
|
|
|
|
|
will be set automatically for every <literal>Session</literal> you retrieve with
|
|
|
|
|
<literal>getCurrentSession()</literal>, so they will also be flushed and closed
|
|
|
|
|
automatically when the container ends the JTA transactions.
|
2005-04-19 13:35:20 -04:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
If you, for example, use the DAO design pattern to write your persistence layer,
|
|
|
|
|
all DAO's lookup the <literal>SessionFactory</literal> when needed and open the
|
|
|
|
|
"current" Session. There is no need to pass instances of <literal>SessionFactory</literal>
|
|
|
|
|
or <literal>Session</literal> around between controlling code and DAO code.
|
|
|
|
|
</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>
|
2005-04-19 13:36:44 -04:00
|
|
|
|
2005-04-19 13:35:20 -04:00
|
|
|
<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
|
2005-04-19 13:36:44 -04:00
|
|
|
main service archive to get a single (hot-)deployable unit. Consult the JBoss AS
|
2005-04-19 13:35:20 -04:00
|
|
|
documentation for more information about JMX service and EJB deployment.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
|
|
</sect1>
|
|
|
|
|
|
2004-06-03 12:31:32 -04:00
|
|
|
</chapter>
|
|
|
|
|
|
