[hibernate-commits] Hibernate SVN: r14073 - in
core/trunk/documentation/manual/en-US/src/main/docbook:
content and 1 other directory.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Tue Oct 9 14:14:36 EDT 2007
Author: steve.ebersole at jboss.com
Date: 2007-10-09 14:14:35 -0400 (Tue, 09 Oct 2007)
New Revision: 14073
Added:
core/trunk/documentation/manual/en-US/src/main/docbook/Hibernate_Reference.xml
core/trunk/documentation/manual/en-US/src/main/docbook/author_group.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/
core/trunk/documentation/manual/en-US/src/main/docbook/content/architecture.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/association_mapping.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/basic_mapping.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/batch.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/best_practices.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/collection_mapping.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/component_mapping.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/configuration.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/events.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/example_mappings.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/example_parentchild.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/example_weblog.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/filters.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/inheritance_mapping.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/performance.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/persistent_classes.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/preface.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/query_criteria.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/query_hql.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/query_sql.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/session_api.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/toolset_guide.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/transactions.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/tutorial.xml
core/trunk/documentation/manual/en-US/src/main/docbook/content/xml.xml
core/trunk/documentation/manual/en-US/src/main/docbook/legal_notice.xml
Removed:
core/trunk/documentation/manual/en-US/src/main/docbook/master.xml
core/trunk/documentation/manual/en-US/src/main/docbook/modules/
Log:
new docbook layout
Added: core/trunk/documentation/manual/en-US/src/main/docbook/Hibernate_Reference.xml
===================================================================
--- core/trunk/documentation/manual/en-US/src/main/docbook/Hibernate_Reference.xml (rev 0)
+++ core/trunk/documentation/manual/en-US/src/main/docbook/Hibernate_Reference.xml 2007-10-09 18:14:35 UTC (rev 14073)
@@ -0,0 +1,90 @@
+<?xml version='1.0' encoding="iso-8859-1"?>
+<!--
+ ~ Copyright (c) 2007, Red Hat Middleware, LLC. All rights reserved.
+ ~
+ ~ 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, v. 2.1. This program is distributed in the
+ ~ hope that it will be useful, but WITHOUT A 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, v.2.1 along with this
+ ~ distribution; if not, write to the Free Software Foundation, Inc.,
+ ~ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ ~
+ ~ Red Hat Author(s): Steve Ebersole
+ -->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+ <!ENTITY versionNumber "3.3.0.alpha1">
+ <!ENTITY copyrightYear "2004">
+ <!ENTITY copyrightHolder "Red Hat Middleware, LLC.">
+]>
+
+<book>
+
+ <bookinfo>
+ <title>HIBERNATE - Relational Persistence for Idiomatic Java</title>
+ <subtitle>Hibernate Reference Documentation</subtitle>
+ <releaseinfo>&versionNumber;</releaseinfo>
+ <productnumber>&versionNumber;</productnumber>
+ <issuenum>1</issuenum>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="images/hibernate_logo_a.png" align="center" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata fileref="images/hibernate_logo_a.png" depth="3cm" />
+ </imageobject>
+ </mediaobject>
+ <copyright>
+ <year>©rightYear;</year>
+ <holder>©rightHolder;</holder>
+ </copyright>
+ <!--
+ todo : figure out how best to include translator info...
+ <xi:include href="author_group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ -->
+ <xi:include href="legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </bookinfo>
+
+ <toc/>
+
+ <xi:include href="content/preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="content/tutorial.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="content/architecture.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="content/configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="content/persistent_classes.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="content/basic_mapping.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="content/collection_mapping.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="content/association_mapping.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="content/component_mapping.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="content/inheritance_mapping.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="content/session_api.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="content/transactions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="content/events.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="content/batch.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="content/query_hql.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="content/query_criteria.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="content/query_sql.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="content/filters.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="content/xml.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="content/performance.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="content/toolset_guide.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="content/example_parentchild.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="content/example_weblog.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="content/example_mappings.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="content/best_practices.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</book>
+
Added: core/trunk/documentation/manual/en-US/src/main/docbook/author_group.xml
===================================================================
--- core/trunk/documentation/manual/en-US/src/main/docbook/author_group.xml (rev 0)
+++ core/trunk/documentation/manual/en-US/src/main/docbook/author_group.xml 2007-10-09 18:14:35 UTC (rev 14073)
@@ -0,0 +1,30 @@
+<?xml version='1.0'?>
+<!--
+ ~ Copyright (c) 2007, Red Hat Middleware, LLC. All rights reserved.
+ ~
+ ~ 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, v. 2.1. This program is distributed in the
+ ~ hope that it will be useful, but WITHOUT A 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, v.2.1 along with this
+ ~ distribution; if not, write to the Free Software Foundation, Inc.,
+ ~ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ ~
+ ~ Red Hat Author(s): Steve Ebersole
+ -->
+<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<authorgroup id="AuthorGroup">
+ <collab>
+ <collabname>The Hibernate team</collabname>
+ </collab>
+ <!-- translations should list all contributors to the translation using the 'translator' class
+ <othercredit class="translator">
+ <firstname>Jane</firstname>
+ <surname>Doe</surname>
+ <contrib>Japenese translation</contrib>
+ </othercredit>
+ -->
+</authorgroup>
\ No newline at end of file
Copied: core/trunk/documentation/manual/en-US/src/main/docbook/content/architecture.xml (from rev 12794, core/trunk/documentation/manual/en-US/src/main/docbook/modules/architecture.xml)
===================================================================
--- core/trunk/documentation/manual/en-US/src/main/docbook/content/architecture.xml (rev 0)
+++ core/trunk/documentation/manual/en-US/src/main/docbook/content/architecture.xml 2007-10-09 18:14:35 UTC (rev 14073)
@@ -0,0 +1,373 @@
+<?xml version='1.0' encoding="iso-8859-1"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<!--
+ ~ Copyright (c) 2007, Red Hat Middleware, LLC. All rights reserved.
+ ~
+ ~ 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, v. 2.1. This program is distributed in the
+ ~ hope that it will be useful, but WITHOUT A 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, v.2.1 along with this
+ ~ distribution; if not, write to the Free Software Foundation, Inc.,
+ ~ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ ~
+ ~ Red Hat Author(s): Steve Ebersole
+ -->
+<chapter id="architecture">
+
+ <title>Architecture</title>
+
+ <sect1 id="architecture-overview" revision="1">
+ <title>Overview</title>
+
+ <para>
+ A (very) high-level view of the Hibernate architecture:
+ </para>
+
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="../images/overview.svg" format="SVG" align="center"/>
+ </imageobject>
+ <imageobject role="html">
+ <imagedata fileref="../images/overview.png" format="PNG" align="center"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>
+ This diagram shows Hibernate using the database and configuration data to
+ provide persistence services (and persistent objects) to the application.
+ </para>
+
+ <para>
+ We would like to show a more detailed view of the runtime architecture.
+ Unfortunately, Hibernate is flexible and supports several approaches. We will
+ show the two extremes. The "lite" architecture has the application
+ provide its own JDBC connections and manage its own transactions. This approach
+ uses a minimal subset of Hibernate's APIs:
+ </para>
+
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="../images/lite.svg" format="SVG" align="center"/>
+ </imageobject>
+ <imageobject role="html">
+ <imagedata fileref="../images/lite.png" format="PNG" align="center"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>
+ The "full cream" architecture abstracts the application away from the
+ underlying JDBC/JTA APIs and lets Hibernate take care of the details.
+ </para>
+
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="../images/full_cream.svg" format="SVG" align="center"/>
+ </imageobject>
+ <imageobject role="html">
+ <imagedata fileref="../images/full_cream.png" format="PNG" align="center"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>
+ Heres some definitions of the objects in the diagrams:
+
+ <variablelist spacing="compact">
+ <varlistentry>
+ <term>SessionFactory (<literal>org.hibernate.SessionFactory</literal>)</term>
+ <listitem>
+ <para>
+ A threadsafe (immutable) cache of compiled mappings for a single database.
+ A factory for <literal>Session</literal> and a client of
+ <literal>ConnectionProvider</literal>. Might hold an optional (second-level)
+ cache of data that is reusable between transactions, at a
+ process- or cluster-level.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Session (<literal>org.hibernate.Session</literal>)</term>
+ <listitem>
+ <para>
+ A single-threaded, short-lived object representing a conversation between
+ the application and the persistent store. Wraps a JDBC connection. Factory
+ for <literal>Transaction</literal>. Holds a mandatory (first-level) cache
+ of persistent objects, used when navigating the object graph or looking up
+ objects by identifier.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Persistent objects and collections</term>
+ <listitem>
+ <para>
+ Short-lived, single threaded objects containing persistent state and business
+ function. These might be ordinary JavaBeans/POJOs, the only special thing about
+ them is that they are currently associated with (exactly one)
+ <literal>Session</literal>. As soon as the <literal>Session</literal> is closed,
+ they will be detached and free to use in any application layer (e.g. directly
+ as data transfer objects to and from presentation).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Transient and detached objects and collections</term>
+ <listitem>
+ <para>
+ Instances of persistent classes that are not currently associated with a
+ <literal>Session</literal>. They may have been instantiated by
+ the application and not (yet) persisted or they may have been instantiated by a
+ closed <literal>Session</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Transaction (<literal>org.hibernate.Transaction</literal>)</term>
+ <listitem>
+ <para>
+ (Optional) A single-threaded, short-lived object used by the application to
+ specify atomic units of work. Abstracts application from underlying JDBC,
+ JTA or CORBA transaction. A <literal>Session</literal> might span several
+ <literal>Transaction</literal>s in some cases. However, transaction demarcation,
+ either using the underlying API or <literal>Transaction</literal>, is never
+ optional!
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ConnectionProvider (<literal>org.hibernate.connection.ConnectionProvider</literal>)</term>
+ <listitem>
+ <para>
+ (Optional) A factory for (and pool of) JDBC connections. Abstracts application from
+ underlying <literal>Datasource</literal> or <literal>DriverManager</literal>.
+ Not exposed to application, but can be extended/implemented by the developer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>TransactionFactory (<literal>org.hibernate.TransactionFactory</literal>)</term>
+ <listitem>
+ <para>
+ (Optional) A factory for <literal>Transaction</literal> instances. Not exposed to the
+ application, but can be extended/implemented by the developer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Extension Interfaces</emphasis></term>
+ <listitem>
+ <para>
+ Hibernate offers many optional extension interfaces you can implement to customize
+ the behavior of your persistence layer. See the API documentation for details.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ Given a "lite" architecture, the application bypasses the
+ <literal>Transaction</literal>/<literal>TransactionFactory</literal> and/or
+ <literal>ConnectionProvider</literal> APIs to talk to JTA or JDBC directly.
+ </para>
+ </sect1>
+
+ <sect1 id="architecture-states" revision="1">
+ <title>Instance states</title>
+ <para>
+ An instance of a persistent classes may be in one of three different states,
+ which are defined with respect to a <emphasis>persistence context</emphasis>.
+ The Hibernate <literal>Session</literal> object is the persistence context:
+ </para>
+
+ <variablelist spacing="compact">
+ <varlistentry>
+ <term>transient</term>
+ <listitem>
+ <para>
+ The instance is not, and has never been associated with
+ any persistence context. It has no persistent identity
+ (primary key value).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>persistent</term>
+ <listitem>
+ <para>
+ The instance is currently associated with a persistence
+ context. It has a persistent identity (primary key value)
+ and, perhaps, a corresponding row in the database. For a
+ particular persistence context, Hibernate
+ <emphasis>guarantees</emphasis> that persistent identity
+ is equivalent to Java identity (in-memory location of the
+ object).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>detached</term>
+ <listitem>
+ <para>
+ The instance was once associated with a persistence
+ context, but that context was closed, or the instance
+ was serialized to another process. It has a persistent
+ identity and, perhaps, a corrsponding row in the database.
+ For detached instances, Hibernate makes no guarantees
+ about the relationship between persistent identity and
+ Java identity.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect1>
+
+ <sect1 id="architecture-jmx" revision="1">
+ <title>JMX Integration</title>
+
+ <para>
+ JMX is the J2EE standard for management of Java components. Hibernate may be managed via
+ a JMX standard service. We provide an MBean implementation in the distribution,
+ <literal>org.hibernate.jmx.HibernateService</literal>.
+ </para>
+
+ <para>
+ For an example how to deploy Hibernate as a JMX service on the JBoss Application Server,
+ please see the JBoss User Guide. On JBoss AS, you also get these benefits if you deploy
+ using JMX:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>Session Management:</emphasis> The Hibernate <literal>Session</literal>'s life cycle
+ can be automatically bound to the scope of a JTA transaction. This means you no
+ longer have to manually open and close the <literal>Session</literal>, this
+ becomes the job of a JBoss EJB interceptor. You also don't have to worry about
+ transaction demarcation in your code anymore (unless you'd like to write a portable
+ persistence layer of course, use the optional Hibernate <literal>Transaction</literal>
+ API for this). You call the <literal>HibernateContext</literal> to access a
+ <literal>Session</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>HAR deployment:</emphasis> Usually you deploy the Hibernate JMX service using a JBoss
+ service deployment descriptor (in an EAR and/or SAR file), it supports all the usual
+ configuration options of a Hibernate <literal>SessionFactory</literal>. However, you still
+ have to name all your mapping files in the deployment descriptor. If you decide to use
+ the optional HAR deployment, JBoss will automatically detect all mapping files in your
+ HAR file.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Consult the JBoss AS user guide for more information about these options.
+ </para>
+
+ <para>
+ Another feature available as a JMX service are runtime Hibernate statistics. See
+ <xref linkend="configuration-optional-statistics"/>.
+ </para>
+ </sect1>
+
+ <sect1 id="architecture-jca" revision="1">
+ <title>JCA Support</title>
+ <para>
+ Hibernate may also be configured as a JCA connector. Please see the website for more
+ details. Please note that Hibernate JCA support is still considered experimental.
+ </para>
+ </sect1>
+
+ <sect1 id="architecture-current-session" revision="2">
+ <title>Contextual Sessions</title>
+ <para>
+ Most applications using Hibernate need some form of "contextual" sessions, where a given
+ session is in effect throughout the scope of a given context. However, across applications
+ the definition of what constitutes a context is typically different; and different contexts
+ define different scopes to the notion of current. Applications using Hibernate prior
+ to version 3.0 tended to utilize either home-grown <literal>ThreadLocal</literal>-based
+ contextual sessions, helper classes such as <literal>HibernateUtil</literal>, or utilized
+ third-party frameworks (such as Spring or Pico) which provided proxy/interception-based contextual sessions.
+ </para>
+ <para>
+ Starting with version 3.0.1, Hibernate added the <literal>SessionFactory.getCurrentSession()</literal>
+ method. Initially, this assumed usage of <literal>JTA</literal> transactions, where the
+ <literal>JTA</literal> transaction defined both the scope and context of a current session.
+ The Hibernate team maintains that, given the maturity of the numerous stand-alone
+ <literal>JTA TransactionManager</literal> implementations out there, most (if not all)
+ applications should be using <literal>JTA</literal> transaction management whether or not
+ they are deployed into a <literal>J2EE</literal> container. Based on that, the
+ <literal>JTA</literal>-based contextual sessions is all you should ever need to use.
+ </para>
+ <para>
+ However, as of version 3.1, the processing behind
+ <literal>SessionFactory.getCurrentSession()</literal> is now pluggable. To that
+ end, a new extension interface (<literal>org.hibernate.context.CurrentSessionContext</literal>)
+ and a new configuration parameter (<literal>hibernate.current_session_context_class</literal>)
+ have been added to allow pluggability of the scope and context of defining current sessions.
+ </para>
+ <para>
+ See the Javadocs for the <literal>org.hibernate.context.CurrentSessionContext</literal>
+ interface for a detailed discussion of its contract. It defines a single method,
+ <literal>currentSession()</literal>, by which the implementation is responsible for
+ tracking the current contextual session. Out-of-the-box, Hibernate comes with three
+ implementations of this interface.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>org.hibernate.context.JTASessionContext</literal> - current sessions
+ are tracked and scoped by a <literal>JTA</literal> transaction. The processing
+ here is exactly the same as in the older JTA-only approach. See the Javadocs
+ for details.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.hibernate.context.ThreadLocalSessionContext</literal> - current
+ sessions are tracked by thread of execution. Again, see the Javadocs for details.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.hibernate.context.ManagedSessionContext</literal> - current
+ sessions are tracked by thread of execution. However, you are responsible to
+ bind and unbind a <literal>Session</literal> instance with static methods
+ on this class, it does never open, flush, or close a <literal>Session</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ The first two implementations provide a "one session - one database transaction" programming
+ model, also known and used as <emphasis>session-per-request</emphasis>. The beginning
+ and end of a Hibernate session is defined by the duration of a database transaction.
+ If you use programatic transaction demarcation in plain JSE without JTA, you are adviced to
+ use the Hibernate <literal>Transaction</literal> API to hide the underlying transaction system
+ from your code. If you use JTA, use the JTA interfaces to demarcate transactions. If you
+ execute in an EJB container that supports CMT, transaction boundaries are defined declaratively
+ and you don't need any transaction or session demarcation operations in your code.
+ Refer to <xref linkend="transactions"/> for more information and code examples.
+ </para>
+
+ <para>
+ The <literal>hibernate.current_session_context_class</literal> configuration parameter
+ defines which <literal>org.hibernate.context.CurrentSessionContext</literal> implementation
+ should be used. Note that for backwards compatibility, if this config param is not set
+ but a <literal>org.hibernate.transaction.TransactionManagerLookup</literal> is configured,
+ Hibernate will use the <literal>org.hibernate.context.JTASessionContext</literal>.
+ Typically, the value of this parameter would just name the implementation class to
+ use; for the three out-of-the-box implementations, however, there are three corresponding
+ short names, "jta", "thread", and "managed".
+ </para>
+
+ </sect1>
+
+</chapter>
+
Copied: core/trunk/documentation/manual/en-US/src/main/docbook/content/association_mapping.xml (from rev 12794, core/trunk/documentation/manual/en-US/src/main/docbook/modules/association_mapping.xml)
===================================================================
--- core/trunk/documentation/manual/en-US/src/main/docbook/content/association_mapping.xml (rev 0)
+++ core/trunk/documentation/manual/en-US/src/main/docbook/content/association_mapping.xml 2007-10-09 18:14:35 UTC (rev 14073)
@@ -0,0 +1,626 @@
+<?xml version='1.0' encoding="iso-8859-1"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<chapter id="associations">
+
+ <title>Association Mappings</title>
+
+ <sect1 id="assoc-intro" revision="1">
+ <title>Introduction</title>
+
+ <para>
+ Association mappings are the often most difficult thing to get right. In
+ this section we'll go through the canonical cases one by one, starting
+ with unidirectional mappings, and then considering the bidirectional cases.
+ We'll use <literal>Person</literal> and <literal>Address</literal> in all
+ the examples.
+ </para>
+
+ <para>
+ We'll classify associations by whether or not they map to an intervening
+ join table, and by multiplicity.
+ </para>
+
+ <para>
+ Nullable foreign keys are not considered good practice in traditional data
+ modelling, so all our examples use not null foreign keys. This is not a
+ requirement of Hibernate, and the mappings will all work if you drop the
+ nullability constraints.
+ </para>
+
+ </sect1>
+
+ <sect1 id="assoc-unidirectional" revision="1">
+ <title>Unidirectional associations</title>
+
+ <sect2 id="assoc-unidirectional-m21">
+ <title>many to one</title>
+
+ <para>
+ A <emphasis>unidirectional many-to-one association</emphasis> is the most
+ common kind of unidirectional association.
+ </para>
+
+ <programlisting><![CDATA[<class name="Person">
+ <id name="id" column="personId">
+ <generator class="native"/>
+ </id>
+ <many-to-one name="address"
+ column="addressId"
+ not-null="true"/>
+</class>
+
+<class name="Address">
+ <id name="id" column="addressId">
+ <generator class="native"/>
+ </id>
+</class>]]></programlisting>
+ <programlisting><![CDATA[
+create table Person ( personId bigint not null primary key, addressId bigint not null )
+create table Address ( addressId bigint not null primary key )
+ ]]></programlisting>
+
+ </sect2>
+
+ <sect2 id="assoc-unidirectional-121">
+ <title>one to one</title>
+
+ <para>
+ A <emphasis>unidirectional one-to-one association on a foreign key</emphasis>
+ is almost identical. The only difference is the column unique constraint.
+ </para>
+
+ <programlisting><![CDATA[<class name="Person">
+ <id name="id" column="personId">
+ <generator class="native"/>
+ </id>
+ <many-to-one name="address"
+ column="addressId"
+ unique="true"
+ not-null="true"/>
+</class>
+
+<class name="Address">
+ <id name="id" column="addressId">
+ <generator class="native"/>
+ </id>
+</class>]]></programlisting>
+ <programlisting><![CDATA[
+create table Person ( personId bigint not null primary key, addressId bigint not null unique )
+create table Address ( addressId bigint not null primary key )
+ ]]></programlisting>
+
+ <para>
+ A <emphasis>unidirectional one-to-one association on a primary key</emphasis>
+ usually uses a special id generator. (Notice that we've reversed the direction
+ of the association in this example.)
+ </para>
+
+ <programlisting><![CDATA[<class name="Person">
+ <id name="id" column="personId">
+ <generator class="native"/>
+ </id>
+</class>
+
+<class name="Address">
+ <id name="id" column="personId">
+ <generator class="foreign">
+ <param name="property">person</param>
+ </generator>
+ </id>
+ <one-to-one name="person" constrained="true"/>
+</class>]]></programlisting>
+ <programlisting><![CDATA[
+create table Person ( personId bigint not null primary key )
+create table Address ( personId bigint not null primary key )
+ ]]></programlisting>
+
+ </sect2>
+
+ <sect2 id="assoc-unidirectional-12m">
+ <title>one to many</title>
+
+ <para>
+ A <emphasis>unidirectional one-to-many association on a foreign key</emphasis>
+ is a very unusual case, and is not really recommended.
+ </para>
+
+ <programlisting><![CDATA[<class name="Person">
+ <id name="id" column="personId">
+ <generator class="native"/>
+ </id>
+ <set name="addresses">
+ <key column="personId"
+ not-null="true"/>
+ <one-to-many class="Address"/>
+ </set>
+</class>
+
+<class name="Address">
+ <id name="id" column="addressId">
+ <generator class="native"/>
+ </id>
+</class>]]></programlisting>
+ <programlisting><![CDATA[
+create table Person ( personId bigint not null primary key )
+create table Address ( addressId bigint not null primary key, personId bigint not null )
+ ]]></programlisting>
+
+ <para>
+ We think it's better to use a join table for this kind of association.
+ </para>
+
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="assoc-unidirectional-join" revision="1">
+ <title>Unidirectional associations with join tables</title>
+
+ <sect2 id="assoc-unidirectional-join-12m">
+ <title>one to many</title>
+
+ <para>
+ A <emphasis>unidirectional one-to-many association on a join table</emphasis>
+ is much preferred. Notice that by specifying <literal>unique="true"</literal>,
+ we have changed the multiplicity from many-to-many to one-to-many.
+ </para>
+
+ <programlisting><![CDATA[<class name="Person">
+ <id name="id" column="personId">
+ <generator class="native"/>
+ </id>
+ <set name="addresses" table="PersonAddress">
+ <key column="personId"/>
+ <many-to-many column="addressId"
+ unique="true"
+ class="Address"/>
+ </set>
+</class>
+
+<class name="Address">
+ <id name="id" column="addressId">
+ <generator class="native"/>
+ </id>
+</class>]]></programlisting>
+ <programlisting><![CDATA[
+create table Person ( personId bigint not null primary key )
+create table PersonAddress ( personId not null, addressId bigint not null primary key )
+create table Address ( addressId bigint not null primary key )
+ ]]></programlisting>
+
+ </sect2>
+
+ <sect2 id="assoc-unidirectional-join-m21">
+ <title>many to one</title>
+
+ <para>
+ A <emphasis>unidirectional many-to-one association on a join table</emphasis>
+ is quite common when the association is optional.
+ </para>
+
+ <programlisting><![CDATA[<class name="Person">
+ <id name="id" column="personId">
+ <generator class="native"/>
+ </id>
+ <join table="PersonAddress"
+ optional="true">
+ <key column="personId" unique="true"/>
+ <many-to-one name="address"
+ column="addressId"
+ not-null="true"/>
+ </join>
+</class>
+
+<class name="Address">
+ <id name="id" column="addressId">
+ <generator class="native"/>
+ </id>
+</class>]]></programlisting>
+ <programlisting><![CDATA[
+create table Person ( personId bigint not null primary key )
+create table PersonAddress ( personId bigint not null primary key, addressId bigint not null )
+create table Address ( addressId bigint not null primary key )
+ ]]></programlisting>
+
+ </sect2>
+
+ <sect2 id="assoc-unidirectional-join-121">
+ <title>one to one</title>
+
+ <para>
+ A <emphasis>unidirectional one-to-one association on a join table</emphasis>
+ is extremely unusual, but possible.
+ </para>
+
+ <programlisting><![CDATA[<class name="Person">
+ <id name="id" column="personId">
+ <generator class="native"/>
+ </id>
+ <join table="PersonAddress"
+ optional="true">
+ <key column="personId"
+ unique="true"/>
+ <many-to-one name="address"
+ column="addressId"
+ not-null="true"
+ unique="true"/>
+ </join>
+</class>
+
+<class name="Address">
+ <id name="id" column="addressId">
+ <generator class="native"/>
+ </id>
+</class>]]></programlisting>
+ <programlisting><![CDATA[
+create table Person ( personId bigint not null primary key )
+create table PersonAddress ( personId bigint not null primary key, addressId bigint not null unique )
+create table Address ( addressId bigint not null primary key )
+ ]]></programlisting>
+
+ </sect2>
+
+ <sect2 id="assoc-unidirectional-join-m2m">
+ <title>many to many</title>
+
+ <para>
+ Finally, we have a <emphasis>unidirectional many-to-many association</emphasis>.
+ </para>
+
+ <programlisting><![CDATA[<class name="Person">
+ <id name="id" column="personId">
+ <generator class="native"/>
+ </id>
+ <set name="addresses" table="PersonAddress">
+ <key column="personId"/>
+ <many-to-many column="addressId"
+ class="Address"/>
+ </set>
+</class>
+
+<class name="Address">
+ <id name="id" column="addressId">
+ <generator class="native"/>
+ </id>
+</class>]]></programlisting>
+ <programlisting><![CDATA[
+create table Person ( personId bigint not null primary key )
+create table PersonAddress ( personId bigint not null, addressId bigint not null, primary key (personId, addressId) )
+create table Address ( addressId bigint not null primary key )
+ ]]></programlisting>
+
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="assoc-bidirectional" revision="1">
+ <title>Bidirectional associations</title>
+
+ <sect2 id="assoc-bidirectional-m21" revision="2">
+ <title>one to many / many to one</title>
+
+ <para>
+ A <emphasis>bidirectional many-to-one association</emphasis> is the
+ most common kind of association. (This is the standard parent/child
+ relationship.)
+ </para>
+
+ <programlisting><![CDATA[<class name="Person">
+ <id name="id" column="personId">
+ <generator class="native"/>
+ </id>
+ <many-to-one name="address"
+ column="addressId"
+ not-null="true"/>
+</class>
+
+<class name="Address">
+ <id name="id" column="addressId">
+ <generator class="native"/>
+ </id>
+ <set name="people" inverse="true">
+ <key column="addressId"/>
+ <one-to-many class="Person"/>
+ </set>
+</class>]]></programlisting>
+
+ <programlisting><![CDATA[
+create table Person ( personId bigint not null primary key, addressId bigint not null )
+create table Address ( addressId bigint not null primary key )
+ ]]></programlisting>
+
+ <para>
+ If you use a <literal>List</literal> (or other indexed collection) you need
+ to set the <literal>key</literal> column of the foreign key to <literal>not null</literal>,
+ and let Hibernate manage the association from the collections side to maintain the index
+ of each element (making the other side virtually inverse by setting
+ <literal>update="false"</literal> and <literal>insert="false"</literal>):
+ </para>
+
+ <programlisting><![CDATA[<class name="Person">
+ <id name="id"/>
+ ...
+ <many-to-one name="address"
+ column="addressId"
+ not-null="true"
+ insert="false"
+ update="false"/>
+</class>
+
+<class name="Address">
+ <id name="id"/>
+ ...
+ <list name="people">
+ <key column="addressId" not-null="true"/>
+ <list-index column="peopleIdx"/>
+ <one-to-many class="Person"/>
+ </list>
+</class>]]></programlisting>
+
+ <para>
+ It is important that you define <literal>not-null="true"</literal> on the
+ <literal><key></literal> element of the collection mapping if the
+ underlying foreign key column is <literal>NOT NULL</literal>. Don't only
+ declare <literal>not-null="true"</literal> on a possible nested
+ <literal><column></literal> element, but on the <literal><key></literal>
+ element.
+ </para>
+
+ </sect2>
+
+ <sect2 id="assoc-bidirectional-121">
+ <title>one to one</title>
+
+ <para>
+ A <emphasis>bidirectional one-to-one association on a foreign key</emphasis>
+ is quite common.
+ </para>
+
+ <programlisting><![CDATA[<class name="Person">
+ <id name="id" column="personId">
+ <generator class="native"/>
+ </id>
+ <many-to-one name="address"
+ column="addressId"
+ unique="true"
+ not-null="true"/>
+</class>
+
+<class name="Address">
+ <id name="id" column="addressId">
+ <generator class="native"/>
+ </id>
+ <one-to-one name="person"
+ property-ref="address"/>
+</class>]]></programlisting>
+ <programlisting><![CDATA[
+create table Person ( personId bigint not null primary key, addressId bigint not null unique )
+create table Address ( addressId bigint not null primary key )
+ ]]></programlisting>
+
+ <para>
+ A <emphasis>bidirectional one-to-one association on a primary key</emphasis>
+ uses the special id generator.
+ </para>
+
+ <programlisting><![CDATA[<class name="Person">
+ <id name="id" column="personId">
+ <generator class="native"/>
+ </id>
+ <one-to-one name="address"/>
+</class>
+
+<class name="Address">
+ <id name="id" column="personId">
+ <generator class="foreign">
+ <param name="property">person</param>
+ </generator>
+ </id>
+ <one-to-one name="person"
+ constrained="true"/>
+</class>]]></programlisting>
+ <programlisting><![CDATA[
+create table Person ( personId bigint not null primary key )
+create table Address ( personId bigint not null primary key )
+ ]]></programlisting>
+
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="assoc-bidirectional-join" revision="1">
+ <title>Bidirectional associations with join tables</title>
+
+ <sect2 id="assoc-bidirectional-join-12m">
+ <title>one to many / many to one</title>
+
+ <para>
+ A <emphasis>bidirectional one-to-many association on a join table</emphasis>.
+ Note that the <literal>inverse="true"</literal> can go on either end of the
+ association, on the collection, or on the join.
+ </para>
+
+ <programlisting><![CDATA[<class name="Person">
+ <id name="id" column="personId">
+ <generator class="native"/>
+ </id>
+ <set name="addresses"
+ table="PersonAddress">
+ <key column="personId"/>
+ <many-to-many column="addressId"
+ unique="true"
+ class="Address"/>
+ </set>
+</class>
+
+<class name="Address">
+ <id name="id" column="addressId">
+ <generator class="native"/>
+ </id>
+ <join table="PersonAddress"
+ inverse="true"
+ optional="true">
+ <key column="addressId"/>
+ <many-to-one name="person"
+ column="personId"
+ not-null="true"/>
+ </join>
+</class>]]></programlisting>
+ <programlisting><![CDATA[
+create table Person ( personId bigint not null primary key )
+create table PersonAddress ( personId bigint not null, addressId bigint not null primary key )
+create table Address ( addressId bigint not null primary key )
+ ]]></programlisting>
+
+ </sect2>
+
+ <sect2 id="assoc-bidirectional-join-121">
+ <title>one to one</title>
+
+ <para>
+ A <emphasis>bidirectional one-to-one association on a join table</emphasis>
+ is extremely unusual, but possible.
+ </para>
+
+ <programlisting><![CDATA[<class name="Person">
+ <id name="id" column="personId">
+ <generator class="native"/>
+ </id>
+ <join table="PersonAddress"
+ optional="true">
+ <key column="personId"
+ unique="true"/>
+ <many-to-one name="address"
+ column="addressId"
+ not-null="true"
+ unique="true"/>
+ </join>
+</class>
+
+<class name="Address">
+ <id name="id" column="addressId">
+ <generator class="native"/>
+ </id>
+ <join table="PersonAddress"
+ optional="true"
+ inverse="true">
+ <key column="addressId"
+ unique="true"/>
+ <many-to-one name="person"
+ column="personId"
+ not-null="true"
+ unique="true"/>
+ </join>
+</class>]]></programlisting>
+ <programlisting><![CDATA[
+create table Person ( personId bigint not null primary key )
+create table PersonAddress ( personId bigint not null primary key, addressId bigint not null unique )
+create table Address ( addressId bigint not null primary key )
+ ]]></programlisting>
+
+ </sect2>
+
+ <sect2 id="assoc-bidirectional-join-m2m" revision="1">
+ <title>many to many</title>
+
+ <para>
+ Finally, we have a <emphasis>bidirectional many-to-many association</emphasis>.
+ </para>
+
+ <programlisting><![CDATA[<class name="Person">
+ <id name="id" column="personId">
+ <generator class="native"/>
+ </id>
+ <set name="addresses" table="PersonAddress">
+ <key column="personId"/>
+ <many-to-many column="addressId"
+ class="Address"/>
+ </set>
+</class>
+
+<class name="Address">
+ <id name="id" column="addressId">
+ <generator class="native"/>
+ </id>
+ <set name="people" inverse="true" table="PersonAddress">
+ <key column="addressId"/>
+ <many-to-many column="personId"
+ class="Person"/>
+ </set>
+</class>]]></programlisting>
+
+ <programlisting><![CDATA[
+create table Person ( personId bigint not null primary key )
+create table PersonAddress ( personId bigint not null, addressId bigint not null, primary key (personId, addressId) )
+create table Address ( addressId bigint not null primary key )
+ ]]></programlisting>
+
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="assoc-complex">
+ <title>More complex association mappings</title>
+
+ <para>
+ More complex association joins are <emphasis>extremely</emphasis> rare.
+ Hibernate makes it possible to handle more complex situations using
+ SQL fragments embedded in the mapping document. For example, if a table
+ with historical account information data defines
+ <literal>accountNumber</literal>, <literal>effectiveEndDate</literal>
+ and <literal>effectiveStartDate</literal>columns, mapped as follows:
+ </para>
+
+ <programlisting><![CDATA[<properties name="currentAccountKey">
+ <property name="accountNumber" type="string" not-null="true"/>
+ <property name="currentAccount" type="boolean">
+ <formula>case when effectiveEndDate is null then 1 else 0 end</formula>
+ </property>
+</properties>
+<property name="effectiveEndDate" type="date"/>
+<property name="effectiveStateDate" type="date" not-null="true"/>]]></programlisting>
+
+ <para>
+ Then we can map an association to the <emphasis>current</emphasis> instance
+ (the one with null <literal>effectiveEndDate</literal>) using:
+ </para>
+
+ <programlisting><![CDATA[<many-to-one name="currentAccountInfo"
+ property-ref="currentAccountKey"
+ class="AccountInfo">
+ <column name="accountNumber"/>
+ <formula>'1'</formula>
+</many-to-one>]]></programlisting>
+
+ <para>
+ In a more complex example, imagine that the association between
+ <literal>Employee</literal> and <literal>Organization</literal> is maintained
+ in an <literal>Employment</literal> table full of historical employment data.
+ Then an association to the employee's <emphasis>most recent</emphasis> employer
+ (the one with the most recent <literal>startDate</literal>) might be mapped this way:
+ </para>
+
+ <programlisting><![CDATA[<join>
+ <key column="employeeId"/>
+ <subselect>
+ select employeeId, orgId
+ from Employments
+ group by orgId
+ having startDate = max(startDate)
+ </subselect>
+ <many-to-one name="mostRecentEmployer"
+ class="Organization"
+ column="orgId"/>
+</join>]]></programlisting>
+
+ <para>
+ You can get quite creative with this functionality, but it is usually more practical
+ to handle these kinds of cases using HQL or a criteria query.
+ </para>
+
+ </sect1>
+
+
+</chapter>
+
Copied: core/trunk/documentation/manual/en-US/src/main/docbook/content/basic_mapping.xml (from rev 12794, core/trunk/documentation/manual/en-US/src/main/docbook/modules/basic_mapping.xml)
===================================================================
--- core/trunk/documentation/manual/en-US/src/main/docbook/content/basic_mapping.xml (rev 0)
+++ core/trunk/documentation/manual/en-US/src/main/docbook/content/basic_mapping.xml 2007-10-09 18:14:35 UTC (rev 14073)
@@ -0,0 +1,3565 @@
+<?xml version='1.0' encoding="iso-8859-1"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+ <!ENTITY mdash "-">
+]>
+
+<chapter id="mapping">
+ <title>Basic O/R Mapping</title>
+
+ <sect1 id="mapping-declaration" revision="2">
+ <title>Mapping declaration</title>
+
+ <para>
+ Object/relational mappings are usually defined in an XML document. The mapping
+ document is designed to be readable and hand-editable. The mapping language is
+ Java-centric, meaning that mappings are constructed around persistent class
+ declarations, not table declarations.
+ </para>
+
+ <para>
+ Note that, even though many Hibernate users choose to write the XML by hand,
+ a number of tools exist to generate the mapping document, including XDoclet,
+ Middlegen and AndroMDA.
+ </para>
+
+ <para>
+ Lets kick off with an example mapping:
+ </para>
+
+ <programlisting id="mapping-declaration-ex1" revision="1"><![CDATA[<?xml version="1.0"?>
+<!DOCTYPE hibernate-mapping PUBLIC
+ "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
+ "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">
+
+<hibernate-mapping package="eg">
+
+ <class name="Cat"
+ table="cats"
+ discriminator-value="C">
+
+ <id name="id">
+ <generator class="native"/>
+ </id>
+
+ <discriminator column="subclass"
+ type="character"/>
+
+ <property name="weight"/>
+
+ <property name="birthdate"
+ type="date"
+ not-null="true"
+ update="false"/>
+
+ <property name="color"
+ type="eg.types.ColorUserType"
+ not-null="true"
+ update="false"/>
+
+ <property name="sex"
+ not-null="true"
+ update="false"/>
+
+ <property name="litterId"
+ column="litterId"
+ update="false"/>
+
+ <many-to-one name="mother"
+ column="mother_id"
+ update="false"/>
+
+ <set name="kittens"
+ inverse="true"
+ order-by="litter_id">
+ <key column="mother_id"/>
+ <one-to-many class="Cat"/>
+ </set>
+
+ <subclass name="DomesticCat"
+ discriminator-value="D">
+
+ <property name="name"
+ type="string"/>
+
+ </subclass>
+
+ </class>
+
+ <class name="Dog">
+ <!-- mapping for Dog could go here -->
+ </class>
+
+</hibernate-mapping>]]></programlisting>
+
+ <para>
+ We will now discuss the content of the mapping document. We will only describe the
+ document elements and attributes that are used by Hibernate at runtime. The mapping
+ document also contains some extra optional attributes and elements that affect the
+ database schemas exported by the schema export tool. (For example the <literal>
+ not-null</literal> attribute.)
+ </para>
+
+
+
+ <sect2 id="mapping-declaration-doctype" revision="3">
+ <title>Doctype</title>
+
+ <para>
+ All XML mappings should declare the doctype shown. The actual DTD may be found
+ at the URL above, in the directory <literal>hibernate-x.x.x/src/org/hibernate
+ </literal> or in <literal>hibernate3.jar</literal>. Hibernate will always look for
+ the DTD in its classpath first. If you experience lookups of the DTD using an
+ Internet connection, check your DTD declaration against the contents of your
+ claspath.
+ </para>
+
+ <sect3 id="mapping-declaration-entity-resolution">
+ <title>EntityResolver</title>
+ <para>
+ As mentioned previously, Hibernate will first attempt to resolve DTDs in its classpath. The
+ manner in which it does this is by registering a custom <literal>org.xml.sax.EntityResolver</literal>
+ implementation with the SAXReader it uses to read in the xml files. This custom
+ <literal>EntityResolver</literal> recognizes two different systemId namespaces.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ a <literal>hibernate namespace</literal> is recognized whenever the
+ resolver encounteres a systemId starting with
+ <literal>http://hibernate.sourceforge.net/</literal>; the resolver
+ attempts to resolve these entities via the classlaoder which loaded
+ the Hibernate classes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ a <literal>user namespace</literal> is recognized whenever the
+ resolver encounteres a systemId using a <literal>classpath://</literal>
+ URL protocol; the resolver will attempt to resolve these entities
+ via (1) the current thread context classloader and (2) the
+ classloader which loaded the Hibernate classes.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ An example of utilizing user namespacing:
+ </para>
+ <programlisting><![CDATA[<?xml version="1.0"?>
+<!DOCTYPE hibernate-mapping PUBLIC
+ "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
+ "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd" [
+ <!ENTITY types SYSTEM "classpath://your/domain/types.xml">
+]>
+
+<hibernate-mapping package="your.domain">
+ <class name="MyEntity">
+ <id name="id" type="my-custom-id-type">
+ ...
+ </id>
+ <class>
+ &types;
+</hibernate-mapping>]]></programlisting>
+ <para>
+ Where <literal>types.xml</literal> is a resource in the <literal>your.domain</literal>
+ package and contains a custom <xref linkend="mapping-types-custom">typedef</xref>.
+ </para>
+ </sect3>
+ </sect2>
+
+ <sect2 id="mapping-declaration-mapping" revision="3">
+ <title>hibernate-mapping</title>
+
+ <para>
+ This element has several optional attributes. The <literal>schema</literal> and
+ <literal>catalog</literal> attributes specify that tables referred to in this mapping
+ belong to the named schema and/or catalog. If specified, tablenames will be qualified
+ by the given schema and catalog names. If missing, tablenames will be unqualified.
+ The <literal>default-cascade</literal> attribute specifies what cascade style
+ should be assumed for properties and collections which do not specify a
+ <literal>cascade</literal> attribute. The <literal>auto-import</literal> attribute lets us
+ use unqualified class names in the query language, by default.
+ </para>
+
+ <programlistingco>
+ <areaspec>
+ <area id="hm1" coords="2 55"/>
+ <area id="hm2" coords="3 55"/>
+ <area id="hm3" coords="4 55"/>
+ <area id="hm4" coords="5 55"/>
+ <area id="hm5" coords="6 55"/>
+ <area id="hm6" coords="7 55"/>
+ <area id="hm7" coords="8 55"/>
+ </areaspec>
+ <programlisting><![CDATA[<hibernate-mapping
+ schema="schemaName"
+ catalog="catalogName"
+ default-cascade="cascade_style"
+ default-access="field|property|ClassName"
+ default-lazy="true|false"
+ auto-import="true|false"
+ package="package.name"
+ />]]></programlisting>
+ <calloutlist>
+ <callout arearefs="hm1">
+ <para>
+ <literal>schema</literal> (optional): The name of a database schema.
+ </para>
+ </callout>
+ <callout arearefs="hm2">
+ <para>
+ <literal>catalog</literal> (optional): The name of a database catalog.
+ </para>
+ </callout>
+ <callout arearefs="hm3">
+ <para>
+ <literal>default-cascade</literal> (optional - defaults to <literal>none</literal>):
+ A default cascade style.
+ </para>
+ </callout>
+ <callout arearefs="hm4">
+ <para>
+ <literal>default-access</literal> (optional - defaults to <literal>property</literal>):
+ The strategy Hibernate should use for accessing all properties. Can be a custom
+ implementation of <literal>PropertyAccessor</literal>.
+ </para>
+ </callout>
+ <callout arearefs="hm5">
+ <para>
+ <literal>default-lazy</literal> (optional - defaults to <literal>true</literal>):
+ The default value for unspecifed <literal>lazy</literal> attributes of class and
+ collection mappings.
+ </para>
+ </callout>
+ <callout arearefs="hm6">
+ <para>
+ <literal>auto-import</literal> (optional - defaults to <literal>true</literal>):
+ Specifies whether we can use unqualified class names (of classes in this mapping)
+ in the query language.
+ </para>
+ </callout>
+ <callout arearefs="hm7">
+ <para>
+ <literal>package</literal> (optional): Specifies a package prefix to assume for
+ unqualified class names in the mapping document.
+ </para>
+ </callout>
+ </calloutlist>
+ </programlistingco>
+
+ <para>
+ If you have two persistent classes with the same (unqualified) name, you should set
+ <literal>auto-import="false"</literal>. Hibernate will throw an exception if you attempt
+ to assign two classes to the same "imported" name.
+ </para>
+
+ <para>
+ Note that the <literal>hibernate-mapping</literal> element allows you to nest
+ several persistent <literal><class></literal> mappings, as shown above.
+ It is however good practice (and expected by some tools) to map only a single
+ persistent class (or a single class hierarchy) in one mapping file and name
+ it after the persistent superclass, e.g. <literal>Cat.hbm.xml</literal>,
+ <literal>Dog.hbm.xml</literal>, or if using inheritance,
+ <literal>Animal.hbm.xml</literal>.
+ </para>
+
+ </sect2>
+
+ <sect2 id="mapping-declaration-class" revision="3">
+ <title>class</title>
+
+ <para>
+ You may declare a persistent class using the <literal>class</literal> element:
+ </para>
+
+ <programlistingco>
+ <areaspec>
+ <area id="class1" coords="2 55"/>
+ <area id="class2" coords="3 55" />
+ <area id="class3" coords="4 55"/>
+ <area id="class4" coords="5 55" />
+ <area id="class5" coords="6 55"/>
+ <area id="class6" coords="7 55" />
+ <area id="class7" coords="8 55"/>
+ <area id="class8" coords="9 55" />
+ <area id="class9" coords="10 55" />
+ <area id="class10" coords="11 55"/>
+ <area id="class11" coords="12 55"/>
+ <area id="class12" coords="13 55"/>
+ <area id="class13" coords="14 55"/>
+ <area id="class14" coords="15 55"/>
+ <area id="class15" coords="16 55"/>
+ <area id="class16" coords="17 55"/>
+ <area id="class17" coords="18 55"/>
+ <area id="class18" coords="19 55"/>
+ <area id="class19" coords="20 55"/>
+ <area id="class20" coords="21 55"/>
+ <area id="class21" coords="22 55"/>
+ </areaspec>
+ <programlisting><![CDATA[<class
+ name="ClassName"
+ table="tableName"
+ discriminator-value="discriminator_value"
+ mutable="true|false"
+ schema="owner"
+ catalog="catalog"
+ proxy="ProxyInterface"
+ dynamic-update="true|false"
+ dynamic-insert="true|false"
+ select-before-update="true|false"
+ polymorphism="implicit|explicit"
+ where="arbitrary sql where condition"
+ persister="PersisterClass"
+ batch-size="N"
+ optimistic-lock="none|version|dirty|all"
+ lazy="true|false"
+ entity-name="EntityName"
+ check="arbitrary sql check condition"
+ rowid="rowid"
+ subselect="SQL expression"
+ abstract="true|false"
+ node="element-name"
+/>]]></programlisting>
+ <calloutlist>
+ <callout arearefs="class1">
+ <para>
+ <literal>name</literal> (optional): The fully qualified Java class name of the
+ persistent class (or interface). If this attribute is missing, it is assumed
+ that the mapping is for a non-POJO entity.
+ </para>
+ </callout>
+ <callout arearefs="class2">
+ <para>
+ <literal>table</literal> (optional - defaults to the unqualified class name): The
+ name of its database table.
+ </para>
+ </callout>
+ <callout arearefs="class3">
+ <para>
+ <literal>discriminator-value</literal> (optional - defaults to the class name): A value
+ that distiguishes individual subclasses, used for polymorphic behaviour. Acceptable
+ values include <literal>null</literal> and <literal>not null</literal>.
+ </para>
+ </callout>
+ <callout arearefs="class4">
+ <para>
+ <literal>mutable</literal> (optional, defaults to <literal>true</literal>): Specifies
+ that instances of the class are (not) mutable.
+ </para>
+ </callout>
+ <callout arearefs="class5">
+ <para>
+ <literal>schema</literal> (optional): Override the schema name specified by
+ the root <literal><hibernate-mapping></literal> element.
+ </para>
+ </callout>
+ <callout arearefs="class6">
+ <para>
+ <literal>catalog</literal> (optional): Override the catalog name specified by
+ the root <literal><hibernate-mapping></literal> element.
+ </para>
+ </callout>
+ <callout arearefs="class7">
+ <para>
+ <literal>proxy</literal> (optional): Specifies an interface to use for lazy
+ initializing proxies. You may specify the name of the class itself.
+ </para>
+ </callout>
+ <callout arearefs="class8">
+ <para>
+ <literal>dynamic-update</literal> (optional, defaults to <literal>false</literal>):
+ Specifies that <literal>UPDATE</literal> SQL should be generated at runtime and
+ contain only those columns whose values have changed.
+ </para>
+ </callout>
+ <callout arearefs="class9">
+ <para>
+ <literal>dynamic-insert</literal> (optional, defaults to <literal>false</literal>):
+ Specifies that <literal>INSERT</literal> SQL should be generated at runtime and
+ contain only the columns whose values are not null.
+ </para>
+ </callout>
+ <callout arearefs="class10">
+ <para>
+ <literal>select-before-update</literal> (optional, defaults to <literal>false</literal>):
+ Specifies that Hibernate should <emphasis>never</emphasis> perform an SQL <literal>UPDATE</literal>
+ unless it is certain that an object is actually modified. In certain cases (actually, only
+ when a transient object has been associated with a new session using <literal>update()</literal>),
+ this means that Hibernate will perform an extra SQL <literal>SELECT</literal> to determine
+ if an <literal>UPDATE</literal> is actually required.
+ </para>
+ </callout>
+ <callout arearefs="class11">
+ <para>
+ <literal>polymorphism</literal> (optional, defaults to <literal>implicit</literal>):
+ Determines whether implicit or explicit query polymorphism is used.
+ </para>
+ </callout>
+ <callout arearefs="class12">
+ <para>
+ <literal>where</literal> (optional) specify an arbitrary SQL <literal>WHERE</literal>
+ condition to be used when retrieving objects of this class
+ </para>
+ </callout>
+ <callout arearefs="class13">
+ <para>
+ <literal>persister</literal> (optional): Specifies a custom <literal>ClassPersister</literal>.
+ </para>
+ </callout>
+ <callout arearefs="class14">
+ <para>
+ <literal>batch-size</literal> (optional, defaults to <literal>1</literal>) specify a "batch size"
+ for fetching instances of this class by identifier.
+ </para>
+ </callout>
+ <callout arearefs="class15">
+ <para>
+ <literal>optimistic-lock</literal> (optional, defaults to <literal>version</literal>):
+ Determines the optimistic locking strategy.
+ </para>
+ </callout>
+ <callout arearefs="class16">
+ <para>
+ <literal>lazy</literal> (optional): Lazy fetching may be completely disabled by setting
+ <literal>lazy="false"</literal>.
+ </para>
+ </callout>
+ <callout arearefs="class17">
+ <para>
+ <literal>entity-name</literal> (optional, defaults to the class name): Hibernate3
+ allows a class to be mapped multiple times (to different tables, potentially),
+ and allows entity mappings that are represented by Maps or XML at the Java level.
+ In these cases, you should provide an explicit arbitrary name for the entity. See
+ <xref linkend="persistent-classes-dynamicmodels"/> and <xref linkend="xml"/>
+ for more information.
+ </para>
+ </callout>
+ <callout arearefs="class18">
+ <para>
+ <literal>check</literal> (optional): A SQL expression used to generate a multi-row
+ <emphasis>check</emphasis> constraint for automatic schema generation.
+ </para>
+ </callout>
+ <callout arearefs="class19">
+ <para>
+ <literal>rowid</literal> (optional): Hibernate can use so called ROWIDs on databases
+ which support. E.g. on Oracle, Hibernate can use the <literal>rowid</literal> extra
+ column for fast updates if you set this option to <literal>rowid</literal>. A ROWID
+ is an implementation detail and represents the physical location of a stored tuple.
+ </para>
+ </callout>
+ <callout arearefs="class20">
+ <para>
+ <literal>subselect</literal> (optional): Maps an immutable and read-only entity
+ to a database subselect. Useful if you want to have a view instead of a base table,
+ but don't. See below for more information.
+ </para>
+ </callout>
+ <callout arearefs="class21">
+ <para>
+ <literal>abstract</literal> (optional): Used to mark abstract superclasses in
+ <literal><union-subclass></literal> hierarchies.
+ </para>
+ </callout>
+ </calloutlist>
+ </programlistingco>
+
+ <para>
+ It is perfectly acceptable for the named persistent class to be an interface. You would then
+ declare implementing classes of that interface using the <literal><subclass></literal>
+ element. You may persist any <emphasis>static</emphasis> inner class. You should specify the
+ class name using the standard form ie. <literal>eg.Foo$Bar</literal>.
+ </para>
+
+ <para>
+ Immutable classes, <literal>mutable="false"</literal>, may not be updated or deleted by the
+ application. This allows Hibernate to make some minor performance optimizations.
+ </para>
+
+ <para>
+ The optional <literal>proxy</literal> attribute enables lazy initialization of persistent
+ instances of the class. Hibernate will initially return CGLIB proxies which implement
+ the named interface. The actual persistent object will be loaded when a method of the
+ proxy is invoked. See "Initializing collections and proxies" below.
+ </para>
+
+ <para><emphasis>Implicit</emphasis> polymorphism means that instances of the class will be returned
+ by a query that names any superclass or implemented interface or the class and that instances
+ of any subclass of the class will be returned by a query that names the class itself.
+ <emphasis>Explicit</emphasis> polymorphism means that class instances will be returned only
+ by queries that explicitly name that class and that queries that name the class will return
+ only instances of subclasses mapped inside this <literal><class></literal> declaration
+ as a <literal><subclass></literal> or <literal><joined-subclass></literal>. For
+ most purposes the default, <literal>polymorphism="implicit"</literal>, is appropriate.
+ Explicit polymorphism is useful when two different classes are mapped to the same table
+ (this allows a "lightweight" class that contains a subset of the table columns).
+ </para>
+
+ <para>
+ The <literal>persister</literal> attribute lets you customize the persistence strategy used for
+ the class. You may, for example, specify your own subclass of
+ <literal>org.hibernate.persister.EntityPersister</literal> or you might even provide a
+ completely new implementation of the interface
+ <literal>org.hibernate.persister.ClassPersister</literal> that implements persistence via,
+ for example, stored procedure calls, serialization to flat files or LDAP. See
+ <literal>org.hibernate.test.CustomPersister</literal> for a simple example (of "persistence"
+ to a <literal>Hashtable</literal>).
+ </para>
+
+ <para>
+ Note that the <literal>dynamic-update</literal> and <literal>dynamic-insert</literal>
+ settings are not inherited by subclasses and so may also be specified on the
+ <literal><subclass></literal> or <literal><joined-subclass></literal> elements.
+ These settings may increase performance in some cases, but might actually decrease
+ performance in others. Use judiciously.
+ </para>
+
+ <para>
+ Use of <literal>select-before-update</literal> will usually decrease performance. It is very
+ useful to prevent a database update trigger being called unnecessarily if you reattach a
+ graph of detached instances to a <literal>Session</literal>.
+ </para>
+
+ <para>
+ If you enable <literal>dynamic-update</literal>, you will have a choice of optimistic
+ locking strategies:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>version</literal> check the version/timestamp columns
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>all</literal> check all columns
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>dirty</literal> check the changed columns, allowing some concurrent updates
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>none</literal> do not use optimistic locking
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ We <emphasis>very</emphasis> strongly recommend that you use version/timestamp
+ columns for optimistic locking with Hibernate. This is the optimal strategy with
+ respect to performance and is the only strategy that correctly handles modifications
+ made to detached instances (ie. when <literal>Session.merge()</literal> is used).
+ </para>
+
+ <para>
+ There is no difference between a view and a base table for a Hibernate mapping, as
+ expected this is transparent at the database level (note that some DBMS don't support
+ views properly, especially with updates). Sometimes you want to use a view, but can't
+ create one in the database (ie. with a legacy schema). In this case, you can map an
+ immutable and read-only entity to a given SQL subselect expression:
+ </para>
+
+ <programlisting><![CDATA[<class name="Summary">
+ <subselect>
+ select item.name, max(bid.amount), count(*)
+ from item
+ join bid on bid.item_id = item.id
+ group by item.name
+ </subselect>
+ <synchronize table="item"/>
+ <synchronize table="bid"/>
+ <id name="name"/>
+ ...
+</class>]]></programlisting>
+
+ <para>
+ Declare the tables to synchronize this entity with, ensuring that auto-flush happens
+ correctly, and that queries against the derived entity do not return stale data.
+ The <literal><subselect></literal> is available as both as an attribute and
+ a nested mapping element.
+ </para>
+
+ </sect2>
+
+ <sect2 id="mapping-declaration-id" revision="4">
+ <title>id</title>
+
+ <para>
+ Mapped classes <emphasis>must</emphasis> declare the primary key column of the database
+ table. Most classes will also have a JavaBeans-style property holding the unique identifier
+ of an instance. The <literal><id></literal> element defines the mapping from that
+ property to the primary key column.
+ </para>
+
+ <programlistingco>
+ <areaspec>
+ <area id="id1" coords="2 70"/>
+ <area id="id2" coords="3 70" />
+ <area id="id3" coords="4 70"/>
+ <area id="id4" coords="5 70" />
+ <area id="id5" coords="6 70" />
+ </areaspec>
+ <programlisting><![CDATA[<id
+ name="propertyName"
+ type="typename"
+ column="column_name"
+ unsaved-value="null|any|none|undefined|id_value"
+ access="field|property|ClassName">
+ node="element-name|@attribute-name|element/@attribute|."
+
+ <generator class="generatorClass"/>
+</id>]]></programlisting>
+ <calloutlist>
+ <callout arearefs="id1">
+ <para>
+ <literal>name</literal> (optional): The name of the identifier property.
+ </para>
+ </callout>
+ <callout arearefs="id2">
+ <para>
+ <literal>type</literal> (optional): A name that indicates the Hibernate type.
+ </para>
+ </callout>
+ <callout arearefs="id3">
+ <para>
+ <literal>column</literal> (optional - defaults to the property name): The
+ name of the primary key column.
+ </para>
+ </callout>
+ <callout arearefs="id4">
+ <para>
+ <literal>unsaved-value</literal> (optional - defaults to a "sensible" value):
+ An identifier property value that indicates that an instance is newly instantiated
+ (unsaved), distinguishing it from detached instances that were saved or loaded
+ in a previous session.
+ </para>
+ </callout>
+ <callout arearefs="id5">
+ <para>
+ <literal>access</literal> (optional - defaults to <literal>property</literal>): The
+ strategy Hibernate should use for accessing the property value.
+ </para>
+ </callout>
+ </calloutlist>
+ </programlistingco>
+
+ <para>
+ If the <literal>name</literal> attribute is missing, it is assumed that the class has no
+ identifier property.
+ </para>
+
+ <para>
+ The <literal>unsaved-value</literal> attribute is almost never needed in Hibernate3.
+ </para>
+
+ <para>
+ There is an alternative <literal><composite-id></literal> declaration to allow access to
+ legacy data with composite keys. We strongly discourage its use for anything else.
+ </para>
+
+ <sect3 id="mapping-declaration-id-generator" revision="2">
+ <title>Generator</title>
+
+ <para>
+ The optional <literal><generator></literal> child element names a Java class used
+ to generate unique identifiers for instances of the persistent class. If any parameters
+ are required to configure or initialize the generator instance, they are passed using the
+ <literal><param></literal> element.
+ </para>
+
+ <programlisting><![CDATA[<id name="id" type="long" column="cat_id">
+ <generator class="org.hibernate.id.TableHiLoGenerator">
+ <param name="table">uid_table</param>
+ <param name="column">next_hi_value_column</param>
+ </generator>
+</id>]]></programlisting>
+
+ <para>
+ All generators implement the interface <literal>org.hibernate.id.IdentifierGenerator</literal>.
+ This is a very simple interface; some applications may choose to provide their own specialized
+ implementations. However, Hibernate provides a range of built-in implementations. There are shortcut
+ names for the built-in generators:
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>increment</literal></term>
+ <listitem>
+ <para>
+ generates identifiers of type <literal>long</literal>, <literal>short</literal> or
+ <literal>int</literal> that are unique only when no other process is inserting data
+ into the same table.
+ <emphasis>Do not use in a cluster.</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>identity</literal></term>
+ <listitem>
+ <para>
+ supports identity columns in DB2, MySQL, MS SQL Server, Sybase and
+ HypersonicSQL. The returned identifier is of type <literal>long</literal>,
+ <literal>short</literal> or <literal>int</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>sequence</literal></term>
+ <listitem>
+ <para>
+ uses a sequence in DB2, PostgreSQL, Oracle, SAP DB, McKoi or a generator
+ in Interbase. The returned identifier is of type <literal>long</literal>,
+ <literal>short</literal> or <literal>int</literal>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>hilo</literal></term>
+ <listitem>
+ <para id="mapping-declaration-id-hilodescription" revision="1">
+ uses a hi/lo algorithm to efficiently generate identifiers of
+ type <literal>long</literal>, <literal>short</literal> or <literal>int</literal>,
+ given a table and column (by default <literal>hibernate_unique_key</literal> and
+ <literal>next_hi</literal> respectively) as a source of hi values. The hi/lo
+ algorithm generates identifiers that are unique only for a particular database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>seqhilo</literal></term>
+ <listitem>
+ <para>
+ uses a hi/lo algorithm to efficiently generate identifiers of type
+ <literal>long</literal>, <literal>short</literal> or <literal>int</literal>,
+ given a named database sequence.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>uuid</literal></term>
+ <listitem>
+ <para>
+ uses a 128-bit UUID algorithm to generate identifiers of type string,
+ unique within a network (the IP address is used). The UUID is encoded
+ as a string of hexadecimal digits of length 32.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>guid</literal></term>
+ <listitem>
+ <para>
+ uses a database-generated GUID string on MS SQL Server and MySQL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>native</literal></term>
+ <listitem>
+ <para>
+ picks <literal>identity</literal>, <literal>sequence</literal> or
+ <literal>hilo</literal> depending upon the capabilities of the
+ underlying database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>assigned</literal></term>
+ <listitem>
+ <para>
+ lets the application to assign an identifier to the object before
+ <literal>save()</literal> is called. This is the default strategy
+ if no <literal><generator></literal> element is specified.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>select</literal></term>
+ <listitem>
+ <para>
+ retrieves a primary key assigned by a database trigger by selecting
+ the row by some unique key and retrieving the primary key value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>foreign</literal></term>
+ <listitem>
+ <para>
+ uses the identifier of another associated object. Usually used in conjunction
+ with a <literal><one-to-one></literal> primary key association.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>sequence-identity</literal></term>
+ <listitem>
+ <para>
+ a specialized sequence generation strategy which utilizes a
+ database sequence for the actual value generation, but combines
+ this with JDBC3 getGeneratedKeys to actually return the generated
+ identifier value as part of the insert statement execution. This
+ strategy is only known to be supported on Oracle 10g drivers
+ targetted for JDK 1.4. Note comments on these insert statements
+ are disabled due to a bug in the Oracle drivers.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </para>
+ </sect3>
+
+ <sect3 id="mapping-declaration-id-hilo" revision="1">
+ <title>Hi/lo algorithm</title>
+ <para>
+ The <literal>hilo</literal> and <literal>seqhilo</literal> generators provide two alternate
+ implementations of the hi/lo algorithm, a favorite approach to identifier generation. The
+ first implementation requires a "special" database table to hold the next available "hi" value.
+ The second uses an Oracle-style sequence (where supported).
+ </para>
+
+ <programlisting><![CDATA[<id name="id" type="long" column="cat_id">
+ <generator class="hilo">
+ <param name="table">hi_value</param>
+ <param name="column">next_value</param>
+ <param name="max_lo">100</param>
+ </generator>
+</id>]]></programlisting>
+
+ <programlisting><![CDATA[<id name="id" type="long" column="cat_id">
+ <generator class="seqhilo">
+ <param name="sequence">hi_value</param>
+ <param name="max_lo">100</param>
+ </generator>
+</id>]]></programlisting>
+
+ <para>
+ Unfortunately, you can't use <literal>hilo</literal> when supplying your own
+ <literal>Connection</literal> to Hibernate. When Hibernate is using an application
+ server datasource to obtain connections enlisted with JTA, you must properly configure
+ the <literal>hibernate.transaction.manager_lookup_class</literal>.
+ </para>
+ </sect3>
+
+ <sect3 id="mapping-declaration-id-uuid">
+ <title>UUID algorithm</title>
+ <para>
+ The UUID contains: IP address, startup time of the JVM (accurate to a quarter
+ second), system time and a counter value (unique within the JVM). It's not
+ possible to obtain a MAC address or memory address from Java code, so this is
+ the best we can do without using JNI.
+ </para>
+ </sect3>
+
+ <sect3 id="mapping-declaration-id-sequences">
+ <title>Identity columns and sequences</title>
+ <para>
+ For databases which support identity columns (DB2, MySQL, Sybase, MS SQL), you
+ may use <literal>identity</literal> key generation. For databases that support
+ sequences (DB2, Oracle, PostgreSQL, Interbase, McKoi, SAP DB) you may use
+ <literal>sequence</literal> style key generation. Both these strategies require
+ two SQL queries to insert a new object.
+ </para>
+
+ <programlisting><![CDATA[<id name="id" type="long" column="person_id">
+ <generator class="sequence">
+ <param name="sequence">person_id_sequence</param>
+ </generator>
+</id>]]></programlisting>
+
+ <programlisting><![CDATA[<id name="id" type="long" column="person_id" unsaved-value="0">
+ <generator class="identity"/>
+</id>]]></programlisting>
+
+ <para>
+ For cross-platform development, the <literal>native</literal> strategy will
+ choose from the <literal>identity</literal>, <literal>sequence</literal> and
+ <literal>hilo</literal> strategies, dependant upon the capabilities of the
+ underlying database.
+ </para>
+ </sect3>
+
+ <sect3 id="mapping-declaration-id-assigned">
+ <title>Assigned identifiers</title>
+ <para>
+ If you want the application to assign identifiers (as opposed to having
+ Hibernate generate them), you may use the <literal>assigned</literal> generator.
+ This special generator will use the identifier value already assigned to the
+ object's identifier property. This generator is used when the primary key
+ is a natural key instead of a surrogate key. This is the default behavior
+ if you do no specify a <literal><generator></literal> element.
+ </para>
+
+ <para>
+ Choosing the <literal>assigned</literal> generator makes Hibernate use
+ <literal>unsaved-value="undefined"</literal>, forcing Hibernate to go to
+ the database to determine if an instance is transient or detached, unless
+ there is a version or timestamp property, or you define
+ <literal>Interceptor.isUnsaved()</literal>.
+ </para>
+ </sect3>
+
+ <sect3 id="mapping-declaration-id-select">
+ <title>Primary keys assigned by triggers</title>
+ <para>
+ For legacy schemas only (Hibernate does not generate DDL with triggers).
+ </para>
+
+ <programlisting><![CDATA[<id name="id" type="long" column="person_id">
+ <generator class="select">
+ <param name="key">socialSecurityNumber</param>
+ </generator>
+</id>]]></programlisting>
+
+ <para>
+ In the above example, there is a unique valued property named
+ <literal>socialSecurityNumber</literal> defined by the class, as a
+ natural key, and a surrogate key named <literal>person_id</literal>
+ whose value is generated by a trigger.
+ </para>
+
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="mapping-declaration-id-enhanced">
+ <title>Enhanced identifier generators</title>
+
+ <para>
+ Starting with release 3.2.3, there are 2 new generators which represent a re-thinking of 2 different
+ aspects of identifier generation. The first aspect is database portability; the second is optimization
+ (not having to query the database for every request for a new identifier value). These two new
+ generators are intended to take the place of some of the named generators described above (starting
+ in 3.3.x); however, they are included in the current releases and can be referenced by FQN.
+ </para>
+
+ <para>
+ The first of these new generators is <literal>org.hibernate.id.enhanced.SequenceStyleGenerator</literal>
+ which is intended firstly as a replacement for the <literal>sequence</literal> generator and secondly as
+ a better portability generator than <literal>native</literal> (because <literal>native</literal>
+ (generally) chooses between <literal>identity</literal> and <literal>sequence</literal> which have
+ largely different semantics which can cause subtle isssues in applications eyeing portability).
+ <literal>org.hibernate.id.enhanced.SequenceStyleGenerator</literal> however achieves portability in
+ a different manner. It chooses between using a table or a sequence in the database to store its
+ incrementing values depending on the capabilities of the dialect being used. The difference between this
+ and <literal>native</literal> is that table-based and sequence-based storage have the same exact
+ semantic (in fact sequences are exactly what Hibernate tries to emmulate with its table-based
+ generators). This generator has a number of configuration parameters:
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>
+ <literal>sequence_name</literal> (optional, defaults to <literal>hibernate_sequence</literal>):
+ The name of the sequence (or table) to be used.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>initial_value</literal> (optional, defaults to <literal>1</literal>): The initial
+ value to be retrieved from the sequence/table. In sequence creation terms, this is analogous
+ to the clause typical named "STARTS WITH".
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>increment_size</literal> (optional, defaults to <literal>1</literal>): The value by
+ which subsequent calls to the sequence/table should differ. In sequence creation terms, this
+ is analogous to the clause typical named "INCREMENT BY".
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>force_table_use</literal> (optional, defaults to <literal>false</literal>): Should
+ we force the use of a table as the backing structure even though the dialect might support
+ sequence?
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>value_column</literal> (optional, defaults to <literal>next_val</literal>): Only
+ relevant for table structures! The name of the column on the table which is used to
+ hold the value.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>optimizer</literal> (optional, defaults to <literal>none</literal>):
+ See <xref linkend="mapping-declaration-id-enhanced-optimizers"/>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ The second of these new generators is <literal>org.hibernate.id.enhanced.TableGenerator</literal> which
+ is intended firstly as a replacement for the <literal>table</literal> generator (although it actually
+ functions much more like <literal>org.hibernate.id.MultipleHiLoPerTableGenerator</literal>) and secondly
+ as a re-implementation of <literal>org.hibernate.id.MultipleHiLoPerTableGenerator</literal> utilizing the
+ notion of pluggable optimiziers. Essentially this generator defines a table capable of holding
+ a number of different increment values simultaneously by using multiple distinctly keyed rows. This
+ generator has a number of configuration parameters:
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>
+ <literal>table_name</literal> (optional, defaults to <literal>hibernate_sequences</literal>):
+ The name of the table to be used.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>value_column_name</literal> (optional, defaults to <literal>next_val</literal>):
+ The name of the column on the table which is used to hold the value.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>segment_column_name</literal> (optional, defaults to <literal>sequence_name</literal>):
+ The name of the column on the table which is used to hold the "segement key". This is the
+ value which distinctly identifies which increment value to use.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>segment_value</literal> (optional, defaults to <literal>default</literal>):
+ The "segment