From hibernate-commits at lists.jboss.org Wed Jun 10 13:28:55 2009
Content-Type: multipart/mixed; boundary="===============7507922504910344565=="
MIME-Version: 1.0
From: hibernate-commits at lists.jboss.org
To: hibernate-commits at lists.jboss.org
Subject: [hibernate-commits] Hibernate SVN: r16742 -
 core/branches/Branch_3_3/documentation/manual/src/main/docbook/en-US/content.
Date: Wed, 10 Jun 2009 13:18:14 -0400
Message-ID: <E1MERRG-000519-1c@committer01.frg.pub.inap.atl.jboss.com>

--===============7507922504910344565==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

Author: steve.ebersole(a)jboss.com
Date: 2009-06-10 13:18:13 -0400 (Wed, 10 Jun 2009)
New Revision: 16742

Modified:
   core/branches/Branch_3_3/documentation/manual/src/main/docbook/en-US/con=
tent/tutorial.xml
Log:
HHH-3953 - Update tutorial chapter


Modified: core/branches/Branch_3_3/documentation/manual/src/main/docbook/en=
-US/content/tutorial.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- core/branches/Branch_3_3/documentation/manual/src/main/docbook/en-US/co=
ntent/tutorial.xml	2009-06-10 17:17:48 UTC (rev 16741)
+++ core/branches/Branch_3_3/documentation/manual/src/main/docbook/en-US/co=
ntent/tutorial.xml	2009-06-10 17:18:13 UTC (rev 16742)
@@ -27,25 +27,17 @@
         <!ENTITY mdash "-">
 ]>
 =

-        <!-- todo : need separate sections, one for each tutorial -->
-
 <chapter id=3D"tutorial">
-    <title>Introduction to Hibernate</title>
-    =

-    <sect1 id=3D"tutorial-intro">
-        <title>Preface</title>
+    <title>Tutorial</title>
 =

-        <para>
-            Intended for new users, this chapter provides an introduction =
to Hibernate
-      The chapter provides a step-by-step tutorial, starting with a simple
-            application using an in-memory database.  The tutorial is
-            based on an earlier tutorial developed by Michael Gloegl.  All
-            code is contained in the <filename>tutorials/web</filename> di=
rectory
-            of the project source.
-        </para>
+    <para>
+        Intended for new users, this chapter provides an step-by-step intr=
oduction
+        to Hibernate, starting with a simple application using an in-memor=
y database.  The
+        tutorial is based on an earlier tutorial developed by Michael Gloe=
gl.  All
+        code is contained in the <filename>tutorials/web</filename> direct=
ory of the project
+        source.
+    </para>
 =

-    </sect1>
-
     <important>
         <para>
             This tutorial expects the user have knowledge of both Java and
@@ -57,11 +49,9 @@
 =

     <note>
         <para>
-            There is another tutorial/example application in the
-            <filename>/tutorials/eg</filename> directory of the project so=
urce.
-            That example is console-based and, as such, would not have the
-            dependency on a servlet container to execute.  The basic setup=
 is
-            the same as the instructions below.
+            The distribution contains another example application under
+            the <filename>tutorial/eg</filename> project source
+            directory.
         </para>
     </note>
 =

@@ -70,34 +60,56 @@
 =

         <para>
             For this example, we will set up a small database application =
that can store
-            events we want to attend, and information about the host(s) of
-            these events.  Although you can use whatever database you feel=
 comfortable using, we will use an in-memory, Java database named HSQLDB
-            to avoid describing installation/setup of any particular datab=
ase
-            servers. =

+            events we want to attend and information about the host(s) of =
these events.
         </para>
-            =

-        <para>
-            The first thing we need to do is set up the development enviro=
nment,
-            including all the required dependencies to Hibernate,
-            as well as other libraries.  Hibernate is built using Maven wh=
ich, =

-            amongst other features, provides <literal>dependency managemen=
t</literal>;
-            moreover it provides <emphasis>transitive</emphasis>
-            <literal>dependency management</literal>, which simply means t=
hat by using
-            Hibernate we can define our dependency on Hibernate. Hibernate
-            itself defines the dependencies it needs which then become tra=
nsitive
-            dependencies of our project.
-        </para>
 =

-        <programlisting><![CDATA[.
-<project xmlns=3D"http://maven.apache.org/POM/4.0.0"
+        <note>
+            <para>
+                Although you can use whatever database you feel comfortabl=
e using, we
+                will use <ulink url=3D"http://hsqldb.org/">HSQLDB</ulink> =
(an in-memory,
+                Java database) to avoid describing installation/setup of a=
ny particular
+                database servers.
+            </para>
+        </note>
+
+        <sect2 id=3D"tutorial-firstapp-setup">
+            <title>Setup</title>
+
+            <para>
+                The first thing we need to do is to set up the development=
 environment.  We
+                will be using the "standard layout" advocated by alot of b=
uild tools such
+                as <ulink url=3D"http://maven.org">Maven</ulink>.  Maven, =
in particular, has a
+                good resource describing this <ulink url=3D"http://maven.a=
pache.org/guides/introduction/introduction-to-the-standard-directory-layout=
.html">layout</ulink>.
+                As this tutorial is to be a web application, we will be cr=
eating and making
+                use of <filename>src/main/java</filename>, <filename>src/m=
ain/resources</filename>
+                and <filename>src/main/webapp</filename> directories.
+            </para>
+
+            <para>
+                We will be using Maven in this tutorial, taking advantage =
of its
+                transitive dependency management capabilities as well as t=
he ability of
+                many IDEs to automatically set up a project for us based o=
n the maven descriptor.
+            </para>
+
+        <programlisting><![CDATA[<project xmlns=3D"http://maven.apache.org=
/POM/4.0.0"
          xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation=3D"http://maven.apache.org/POM/4.0.0 http://ma=
ven.apache.org/xsd/maven-4.0.0.xsd">
 =

-    ...
+    <modelVersion>4.0.0</modelVersion>
 =

+    <groupId>org.hibernate.tutorials</groupId>
+    <artifactId>hibernate-tutorial</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+    <name>First Hibernate Tutorial</name>
+
+    <build>
+         <!-- we dont want the version to be part of the generated war fil=
e name -->
+         <finalName>${artifactId}</finalName>
+    </build>
+
     <dependencies>
         <dependency>
-            <groupId>${groupId}</groupId>
+            <groupId>org.hibernate</groupId>
             <artifactId>hibernate-core</artifactId>
         </dependency>
 =

@@ -106,34 +118,52 @@
             <groupId>javax.servlet</groupId>
             <artifactId>servlet-api</artifactId>
         </dependency>
+
+        <!-- Hibernate uses slf4j for logging, for our purposes here use t=
he simple backend -->
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-simple</artifactId>
+        </dependency>
+
+        <!-- Hibernate gives you a choice of bytecode providers between cg=
lib and javassist -->
+        <dependency>
+            <groupId>javassist</groupId>
+            <artifactId>javassist</artifactId>
+        </dependency>
     </dependencies>
 =

 </project>]]></programlisting>
 =

-        <note>
-            <para>
-                Essentially we are describing here the
-                <filename>/tutorials/web/pom.xml</filename> file.  See the
-                <ulink url=3D"http://maven.org">Maven</ulink> site for mor=
e information.
-            </para>
-        </note>
+            <tip>
+                <para>
+                    It is not a requirement to use Maven.  If you wish to =
use something else to
+                    build this tutoial (such as Ant), the layout will rema=
in the same.  The only
+                    change is that you will need to manually account for a=
ll the needed
+                    dependencies.  If you use something like <ulink url=3D=
"http://ant.apache.org/ivy/">Ivy</ulink>
+                    providing transitive dependency management you would s=
till use the dependencies
+                    mentioned below.  Otherwise, you'd need to grab <empha=
sis>all</emphasis>
+                    dependencies, both explicit and transitive, and add th=
em to the project's
+                    classpath.  If working from the Hibernate distribution=
 bundle, this would mean
+                    <filename>hibernate3.jar</filename>, all artifacts in =
the
+                    <filename>lib/required</filename> directory and all fi=
les from either the
+                    <filename>lib/bytecode/cglib</filename> or <filename>l=
ib/bytecode/javassist</filename>
+                    directory; additionally you will need both the servlet=
-api jar and one of the slf4j
+                    logging backends.
+                </para>
+            </tip>
 =

-        <tip>
             <para>
-                While not strictly necessary, most IDEs have integration w=
ith Maven
-                to read these POM files and automatically set up a project=
 for you.
+                Save this file as <filename>pom.xml</filename> in the proj=
ect root directory.
             </para>
-        </tip>
+        </sect2>
 =

-        <para>
-            Next, create a class that represents the event you want to sto=
re in the database.
-        </para>
-      =

+
         <sect2 id=3D"tutorial-firstapp-firstclass">
             <title>The first class</title>
             =

             <para>
-                The first persistent class is a simple JavaBean class with=
 some properties:
+                Next, we create a class that represents the event we want =
to store in the
+                database; it is a simple JavaBean class with some properti=
es:
             </para>
 =

             <programlisting><![CDATA[package org.hibernate.tutorial.domain;
@@ -175,57 +205,50 @@
 =

             <para>
                 This class uses standard JavaBean naming conventions for p=
roperty
-                getter and setter methods, as well as private visibility f=
or the fields. Although this is
-                a recommended design, it is not required. Hibernate can al=
so access fields directly,
-                the benefit of accessor methods is robustness for refactor=
ing. The no-argument
-                constructor is required to instantiate an object of this c=
lass through reflection.
+                getter and setter methods, as well as private visibility f=
or the
+                fields.  Although this is the recommended design, it is no=
t required.
+                Hibernate can also access fields directly,  the benefit of=
 accessor
+                methods is robustness for refactoring.
             </para>
 =

             <para>
-                The <literal>id</literal> property holds a unique identifi=
er value for a particular event.
-                All persistent entity classes (there are less important de=
pendent classes as well) will need
-                such an identifier property if we want to use the full fea=
ture set of Hibernate. In fact,
-                most applications, especially web applications, need to di=
stinguish objects by identifier, so you
-                should consider this a feature rather than a limitation. H=
owever, we usually do not manipulate
-                the identity of an object, hence the setter method should =
be private. Only Hibernate will assign
-                identifiers when an object is saved. Hibernate can access =
public, private,
-                and protected accessor methods, as well as public, private=
 and protected fields directly. The
-                choice is up to you and you can match it to fit your appli=
cation design.
+                The <literal>id</literal> property holds a unique identifi=
er value
+                for a particular event.  All persistent entity classes (th=
ere are
+                less important dependent classes as well) will need such a=
n identifier
+                property if we want to use the full feature set of Hiberna=
te. In fact,
+                most applications, especially web applications, need to di=
stinguish
+                objects by identifier, so you should consider this a featu=
re rather
+                than a limitation.  However, we usually do not manipulate =
the identity
+                of an object, hence the setter method should be private.  =
Only Hibernate
+                will assign identifiers when an object is saved.  Hibernat=
e can access
+                public, private, and protected accessor methods, as well a=
s public,
+                private and protected fields directly.  The choice is up t=
o you and
+                you can match it to fit your application design.
             </para>
 =

             <para>
-                The no-argument constructor is a requirement for all persi=
stent classes; Hibernate
-                has to create objects for you, using Java Reflection. The =
constructor can be
-                private, however, package visibility is required for runti=
me proxy generation and
-                efficient data retrieval without bytecode instrumentation.
+                The no-argument constructor is a requirement for all persi=
stent
+                classes; Hibernate has to create objects for you, using Ja=
va
+                Reflection.  The constructor can be private, however packa=
ge or public
+                visibility is required for runtime proxy generation and ef=
ficient data
+                retrieval without bytecode instrumentation.
             </para>
 =

             <para>
-                Place the Java source file in a directory called <literal>=
src</literal> in the
-                development folder, and in its correct package. The direct=
ory should now look like this:
+                Save this file to the <filename>src/main/java/org/hibernat=
e/tutorial/domain</filename>
+                directory.
             </para>
-
-            <programlisting><![CDATA[.
-+lib
-  <Hibernate and third-party libraries>
-+src
-  +events
-    Event.java]]></programlisting>
-
-            <para>
-                In the next step, we tell Hibernate about this persistent =
class.
-            </para>
-                =

         </sect2>
 =

         <sect2 id=3D"tutorial-firstapp-mapping">
             <title>The mapping file</title>
 =

             <para>
-                Hibernate needs to know how to load and store objects of t=
he persistent class.
-                This is where the Hibernate mapping file comes into play. =
The mapping file
-                tells Hibernate what table in the database it has to acces=
s, and what columns
-                in that table it should use.
+                Hibernate needs to know how to load and store objects of t=
he
+                persistent class.  This is where the Hibernate mapping file
+                comes into play. The mapping file tells Hibernate what tab=
le in
+                the database it has to access, and what columns in that ta=
ble
+                it should use.
             </para>
 =

             <para>
@@ -237,25 +260,28 @@
         "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
         "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">
 =

-<hibernate-mapping>
+<hibernate-mapping package=3D"org.hibernate.tutorial.domain">
 [...]
 </hibernate-mapping>]]></programlisting>
 =

             <para>
-                Hibernate DTD is sophisticated. You can use it for
-                auto-completion of XML mapping elements and attributes in =
your editor or
-                IDE. Opening up the DTD file in your text editor is the
-                easiest way to get an overview of all elements and attribu=
tes, and to view
-                the defaults, as well as some comments.  Hibernate will not
-                load the DTD file from the web, but first look it up from =
the classpath
-                of the application. The DTD file is included in <literal>h=
ibernate3.jar</literal>
-                as well as in the <literal>src/</literal> directory of the=
 Hibernate distribution.
+                Hibernate DTD is sophisticated.  You can use it for auto-c=
ompletion
+                of XML mapping elements and attributes in your editor or I=
DE.
+                Opening up the DTD file in your text editor is the easiest=
 way to
+                get an overview of all elements and attributes, and to vie=
w the
+                defaults, as well as some comments.  Hibernate will not lo=
ad the
+                DTD file from the web, but first look it up from the class=
path of
+                the application.  The DTD file is included in
+                <filename>hibernate-core.jar</filename> (it is also includ=
ed in the
+                <filename>hibernate3.jar</filename>, if using the distribu=
tion bundle).
             </para>
 =

-            <para>
-                We will omit the DTD declaration in future examples to sho=
rten the code. It is,
-                of course, not optional.
-            </para>
+            <important>
+                <para>
+                    We will omit the DTD declaration in future examples to=
 shorten the code. It is,
+                    of course, not optional.
+                </para>
+            </important>
 =

             <para>
                 Between the two <literal>hibernate-mapping</literal> tags,=
 include a
@@ -264,25 +290,27 @@
                 a mapping to a table in the SQL database:
             </para>
 =

-            <programlisting><![CDATA[<hibernate-mapping>
+            <programlisting><![CDATA[<hibernate-mapping package=3D"org.hib=
ernate.tutorial.domain">
 =

-    <class name=3D"events.Event" table=3D"EVENTS">
+    <class name=3D"Event" table=3D"EVENTS">
 =

     </class>
 =

 </hibernate-mapping>]]></programlisting>
 =

             <para>
-                So far we have told Hibernate how to persist and load obje=
ct of class <literal>Event</literal>
-                to the table <literal>EVENTS</literal>. Each instance is n=
ow represented by a row in that table.
-                Now we can continue by mapping the unique identifier prope=
rty to the tables primary key.
-                As we do not want to care about handling this identifier, =
we configure Hibernate's
+                So far we have told Hibernate how to persist and load obje=
ct of
+                class <literal>Event</literal> to the table
+                <literal>EVENTS</literal>. Each instance is now represente=
d by a
+                row in that table.  Now we can continue by mapping the uni=
que
+                identifier property to the tables primary key.  As we do n=
ot want
+                to care about handling this identifier, we configure Hiber=
nate's
                 identifier generation strategy for a surrogate primary key=
 column:
             </para>
 =

-            <programlisting><![CDATA[<hibernate-mapping>
+            <programlisting><![CDATA[<hibernate-mapping package=3D"org.hib=
ernate.tutorial.domain">
 =

-    <class name=3D"events.Event" table=3D"EVENTS">
+    <class name=3D"Event" table=3D"EVENTS">
         <id name=3D"id" column=3D"EVENT_ID">
             <generator class=3D"native"/>
         </id>
@@ -291,29 +319,43 @@
 </hibernate-mapping>]]></programlisting>
 =

             <para>
-                The <literal>id</literal> element is the declaration of th=
e identifier property,
-                <literal>name=3D"id"</literal> declares the name of the Ja=
va property.
-                Hibernate will use the getter and setter methods to access=
 the property.
-                The column attribute tells Hibernate which column of the
-                <literal>EVENTS</literal> table to use for this primary ke=
y. The nested
-                <literal>generator</literal> element specifies the identif=
ier generation strategy.
-                =

-		In this case you used <literal>native</literal>, which selects the best =
strategy depending
-                on the configured database dialect. Hibernate supports dat=
abase generated, globally
-                unique, as well as application assigned, identifiers. Hibe=
rnate supports any strategy you have written
-                an extension for.
+                The <literal>id</literal> element is the declaration of the
+                identifier property.  The <literal>name=3D"id"</literal> m=
apping
+                attribute declares the name of the JavaBean property and t=
ells
+                Hibernate to use the <literal>getId()</literal> and
+                <literal>setId()</literal> methods to access the property.=
  The
+                column attribute tells Hibernate which column of the
+                <literal>EVENTS</literal> table holds the primary key valu=
e.
             </para>
 =

             <para>
-                Finally, include declarations for the persistent propertie=
s of the class in
-                the mapping file. By default, no properties of the class a=
re considered
+                The nested <literal>generator</literal> element specifies =
the
+                identifier generation strategy (aka how are identifier val=
ues
+                generated?).  In this case we choose <literal>native</lite=
ral>,
+                which offers a level of portability depending on the confi=
gured
+                database dialect.  Hibernate supports database generated, =
globally
+                unique, as well as application assigned, identifiers.  Ide=
ntifier
+                value generation is also one of Hibernate's many extension=
 points
+                and you can plugin in your own strategy.
+            </para>
+
+            <tip>
+                <para>
+                    <literal>native</literal> is no longer consider the be=
st strategy in terms of portability.  for further
+                    discussion, see <xref linkend=3D"portability-idgen"/>
+                </para>
+            </tip>
+
+            <para>
+                Lastly, we need to tell Hibernate about the remaining enti=
ty class
+                properties.  By default, no properties of the class are co=
nsidered
                 persistent:
             </para>
             =

             <programlisting><![CDATA[
-<hibernate-mapping>
+<hibernate-mapping package=3D"org.hibernate.tutorial.domain">
 =

-    <class name=3D"events.Event" table=3D"EVENTS">
+    <class name=3D"Event" table=3D"EVENTS">
         <id name=3D"id" column=3D"EVENT_ID">
             <generator class=3D"native"/>
         </id>
@@ -324,27 +366,31 @@
 </hibernate-mapping>]]></programlisting>
             =

             <para>
-                Similar to the <literal>id</literal> element, the <literal=
>name</literal>
-                attribute of the <literal>property</literal> element tells=
 Hibernate which getter
-                and setter methods to use.  In this case, Hibernate will s=
earch for
-                <literal>getDate()/setDate()</literal>, as well as <litera=
l>getTitle()/setTitle()</literal>.
+                Similar to the <literal>id</literal> element, the
+                <literal>name</literal> attribute of the
+                <literal>property</literal> element tells Hibernate which =
getter
+                and setter methods to use.  In this case, Hibernate will s=
earch
+                for <literal>getDate()</literal>, <literal>setDate()</lite=
ral>,
+                <literal>getTitle()</literal> and <literal>setTitle()</lit=
eral>
+                methods.
             </para>
 =

-            <para>
-                Why does the <literal>date</literal> property mapping incl=
ude the
-                <literal>column</literal> attribute, but the <literal>titl=
e</literal>
-                does not? Without the <literal>column</literal> attribute,=
 Hibernate
-                by default uses the property name as the column name. This=
 works for
-                <literal>title</literal>, however, <literal>date</literal>=
 is a reserved
-                keyword in most databases so you will need to map it to a =
different name.
-            </para>
+            <note>
+                <para>
+                    Why does the <literal>date</literal> property mapping =
include the
+                    <literal>column</literal> attribute, but the <literal>=
title</literal>
+                    does not? Without the <literal>column</literal> attrib=
ute, Hibernate
+                    by default uses the property name as the column name. =
This works for
+                    <literal>title</literal>, however, <literal>date</lite=
ral> is a reserved
+                    keyword in most databases so you will need to map it t=
o a different name.
+                </para>
+            </note>
 =

             <para>
-                The <literal>title</literal> mapping also lacks
-                a <literal>type</literal> attribute. The types declared an=
d used in the mapping
-                files are not, as you might expect, Java data types. They =
are also not SQL
-                database types. These types are called <emphasis>Hibernate=
 mapping types</emphasis>,
-                converters which can translate from Java to SQL data types=
 and vice versa. Again,
+                The <literal>title</literal> mapping also lacks a <literal=
>type</literal> attribute. The
+                types declared and used in the mapping files are not Java =
data types; they are not SQL
+                database types either.  These types are called <emphasis>H=
ibernate mapping types</emphasis>,
+                converters which can translate from Java to SQL data types=
 and vice versa.  Again,
                 Hibernate will try to determine the correct conversion and=
 mapping type itself if
                 the <literal>type</literal> attribute is not present in th=
e mapping. In some cases this
                 automatic detection using Reflection on the Java class mig=
ht not have the default you
@@ -355,59 +401,64 @@
                 <literal>timestamp</literal> converter.
             </para>
 =

+            <tip>
+                <para>
+                    Hibernate makes this mapping type determination using =
reflection when the mapping files
+                    are processed.  This can take time and resources, so i=
f startup performance is important
+                    you should consider explicitly defining the type to us=
e.
+                </para>
+            </tip>
+
             <para>
-                Save the mapping file as <literal>Event.hbm.xml</literal> =
in
-                the directory next to the <literal>Event</literal> Java cl=
ass source file.
-                The naming of mapping files can be arbitrary, however, the=
 <literal>hbm.xml</literal>
-                suffix is a convention in the Hibernate developer communit=
y. The directory structure
-                should now look like this:
+                Save this mapping file as
+                <filename>src/main/resources/org/hibernate/tutorial/domain=
/Event.hbm.xml</filename>.
             </para>
 =

-            <programlisting><![CDATA[.
-+lib
-  <Hibernate and third-party libraries>
-+src
-  +events
-    Event.java
-    Event.hbm.xml]]></programlisting>
-
-             <para>
-                 The next section continues with the main configuration of=
 Hibernate.
-             </para>
-
         </sect2>
 =

         <sect2 id=3D"tutorial-firstapp-configuration" revision=3D"2">
             <title>Hibernate configuration</title>
 =

             <para>
-                You should have a persistent class and its mapping file in=
 place. It is now time to configure
-                Hibernate. Before you do this, you will need a database. H=
SQL DB, a java-based SQL DBMS,
-                can be downloaded from the HSQL DB website(http://hsqldb.o=
rg/). You only need the <literal>hsqldb.jar</literal>
-                from this download. Place this file in the <literal>lib/</=
literal> directory of the
-                development folder.
+                At this point, you should have the persistent class and it=
s mapping
+                file in place. It is now time to configure Hibernate.  Fir=
st let's set up
+                HSQLDB to run in "server mode"
             </para>
 =

+            <note>
+                <para>
+                    We do this do that the data remains between runs.
+                </para>
+            </note>
+
             <para>
-                Create a directory called <literal>data</literal> in the r=
oot of the development directory.
-                This is where HSQL DB will store its data files. Start the=
 database by running
-                <literal>java -classpath ../lib/hsqldb.jar org.hsqldb.Serv=
er</literal> in this data directory.
-                You will see it start up and bind to a TCP/IP socket; this=
 is where our application
-                will connect later. If you want to start with a fresh data=
base during this tutorial,
-                shutdown HSQL DB (press <literal>CTRL + C</literal> in the=
 window), delete all files in the
-                <literal>data/</literal> directory, and start HSQL DB agai=
n.
+                We will utilize the Maven exec plugin to launch the HSQLDB=
 server
+                by running:
+                <command> mvn exec:java -Dexec.mainClass=3D"org.hsqldb.Ser=
ver" -Dexec.args=3D"-database.0 file:target/data/tutorial"</command>
+                You will see it start up and bind to a TCP/IP socket; this=
 is where
+                our application will connect later.  If you want to start
+                with a fresh database during this tutorial, shutdown HSQLD=
B, delete
+                all files in the <filename>target/data</filename> director=
y,
+                and start HSQLDB again.
             </para>
 =

             <para>
-                Hibernate is the layer in your application that connects t=
o this database, so it needs
-                connection information. The connections are made through a=
 JDBC connection pool, which you
-               will also have to configure. The Hibernate distribution con=
tains several open source JDBC connection
-                pooling tools, but you will use the Hibernate built-in con=
nection pool for this tutorial.
-                You will have to copy the required library into your class=
path and use different
-                connection pooling settings if you want to use a productio=
n-quality third party
-                JDBC pooling software.
+                Hibernate will be connecting to the database on behalf of =
your application, so it needs to know
+                how to obtain connections.  For this tutorial we will be u=
sing a standalone connection
+                pool (as opposed to a <interfacename>javax.sql.DataSource<=
/interfacename>).  Hibernate comes with
+                support for two third-party open source JDBC connection po=
ols:
+                <ulink url=3D"https://sourceforge.net/projects/c3p0">c3p0<=
/ulink> and
+                <ulink url=3D"http://proxool.sourceforge.net/">proxool</ul=
ink>.  However, we will be using the
+                Hibernate built-in connection pool for this tutorial.
             </para>
 =

+            <caution>
+                <para>
+                    The built-in Hibernate connection pool is in no way in=
tended for production use.  It
+                    lacks several features found on any decent connection =
pool.
+                </para>
+            </caution>
+
             <para>
                 For Hibernate's configuration, we can use a simple <litera=
l>hibernate.properties</literal> file, a
                 more sophisticated <literal>hibernate.cfg.xml</literal> fi=
le, or even complete
@@ -445,19 +496,22 @@
         <property name=3D"show_sql">true</property>
 =

         <!-- Drop and re-create the database schema on startup -->
-        <property name=3D"hbm2ddl.auto">create</property>
+        <property name=3D"hbm2ddl.auto">update</property>
 =

-        <mapping resource=3D"events/Event.hbm.xml"/>
+        <mapping resource=3D"org/hibernate/tutorial/domain/Event.hbm.xml"/>
 =

     </session-factory>
 =

 </hibernate-configuration>]]></programlisting>
 =

+            <note>
+                <para>Notice that this configuration file specifies a diff=
erent DTD</para>
+            </note>
+
             <para>
-                This XML configuration uses a different DTD. You configure
-                Hibernate's <literal>SessionFactory</literal>. SessionFact=
ory is a global factory responsible
-                for a particular database. If you have several databases, =
for easier startup you should use several
-                <literal>&lt;session-factory&gt;</literal> configurations =
in
+                You configure Hibernate's <literal>SessionFactory</literal=
>. SessionFactory is a global
+                factory responsible for a particular database. If you have=
 several databases, for easier
+                startup you should use several <literal>&lt;session-factor=
y&gt;</literal> configurations in
                 several configuration files.
             </para>
 =

@@ -465,9 +519,18 @@
                 The first four <literal>property</literal> elements contai=
n the necessary
                 configuration for the JDBC connection. The dialect <litera=
l>property</literal>
                 element specifies the particular SQL variant Hibernate gen=
erates.
-                Hibernate's automatic session management for persistence c=
ontexts is particularly useful in this context.
+            </para>
 =

-                The <literal>hbm2ddl.auto</literal> option turns on automa=
tic generation of
+            <tip>
+                <para>
+                    In most cases, Hibernate is able to properly determine=
 which dialect to use.  See
+                    <xref linkend=3D"portability-dialectresolver"/> for mo=
re information.
+                </para>
+            </tip>
+
+            <para>
+                Hibernate's automatic session management for persistence c=
ontexts is particularly useful
+                in this context.  The <literal>hbm2ddl.auto</literal> opti=
on turns on automatic generation of
                 database schemas directly into the database. This can also=
 be turned
                 off by removing the configuration option, or redirected to=
 a file with the help of
                 the <literal>SchemaExport</literal> Ant task. Finally, add=
 the mapping file(s)
@@ -475,116 +538,83 @@
             </para>
 =

             <para>
-                Copy the file into the source directory, so it will end up=
 in the
-                root of the classpath. On startup, Hibernate automatically=
 searches for a file called
-                <literal>hibernate.cfg.xml</literal> in the root of the cl=
asspath.
+                Save this file as <filename>hibernate.cfg.xml</filename> i=
nto the
+                <filename>src/main/resources</filename> directory.
             </para>
 =

         </sect2>
 =

-        <sect2 id=3D"tutorial-firstapp-ant" revision=3D"1">
-            <title>Building with Ant</title>
+        <sect2 id=3D"tutorial-firstapp-mvn" revision=3D"1">
+            <title>Building with Maven</title>
 =

             <para>
-                We will now build the tutorial with Ant. You will need to =
have Ant installed.
-                It is available from the <ulink url=3D"http://ant.apache.o=
rg/bindownload.cgi">Ant download page</ulink>.
-                Installation instructions for Ant, however, are not be cov=
ered here. Please refer to the
-                <ulink url=3D"http://ant.apache.org/manual/index.html">Ant=
 manual</ulink> for further information. After you
-                have installed Ant, you can start to create the buildfile.=
 It will be called
-                <literal>build.xml</literal> and placed directly in the de=
velopment directory.
+                We will now build the tutorial with Maven.  You will need =
to
+                have Maven installed; it is available from the
+                <ulink url=3D"http://maven.apache.org/download.html">Maven=
 download page</ulink>.
+                Maven will read the <filename>/pom.xml</filename> file we =
created
+                earlier and know how to perform some basic project tasks. =
 First,
+                lets run the <literal>compile</literal> goal to make sure =
we can compile
+                everything so far:
             </para>
 =

-            <para>
-                A basic build file looks like this:
-            </para>
+            <programlisting><![CDATA[[hibernateTutorial]$ mvn compile
+[INFO] Scanning for projects...
+[INFO] -------------------------------------------------------------------=
-----
+[INFO] Building First Hibernate Tutorial
+[INFO]    task-segment: [compile]
+[INFO] -------------------------------------------------------------------=
-----
+[INFO] [resources:resources]
+[INFO] Using default encoding to copy filtered resources.
+[INFO] [compiler:compile]
+[INFO] Compiling 1 source file to /home/steve/projects/sandbox/hibernateTu=
torial/target/classes
+[INFO] -------------------------------------------------------------------=
-----
+[INFO] BUILD SUCCESSFUL
+[INFO] -------------------------------------------------------------------=
-----
+[INFO] Total time: 2 seconds
+[INFO] Finished at: Tue Jun 09 12:25:25 CDT 2009
+[INFO] Final Memory: 5M/547M
+[INFO] -------------------------------------------------------------------=
-----]]></programlisting>
 =

-            <programlisting><![CDATA[<project name=3D"hibernate-tutorial" =
default=3D"compile">
-
-    <property name=3D"sourcedir" value=3D"${basedir}/src"/>
-    <property name=3D"targetdir" value=3D"${basedir}/bin"/>
-    <property name=3D"librarydir" value=3D"${basedir}/lib"/>
-
-    <path id=3D"libraries">
-        <fileset dir=3D"${librarydir}">
-            <include name=3D"*.jar"/>
-        </fileset>
-    </path>
-
-    <target name=3D"clean">
-        <delete dir=3D"${targetdir}"/>
-        <mkdir dir=3D"${targetdir}"/>
-    </target>
-
-    <target name=3D"compile" depends=3D"clean, copy-resources">
-      <javac srcdir=3D"${sourcedir}"
-             destdir=3D"${targetdir}"
-             classpathref=3D"libraries"/>
-    </target>
-
-    <target name=3D"copy-resources">
-        <copy todir=3D"${targetdir}">
-            <fileset dir=3D"${sourcedir}">
-                <exclude name=3D"**/*.java"/>
-            </fileset>
-        </copy>
-    </target>
-
-</project>]]></programlisting>
-
-            <para>
-                This will tell Ant to add all files in the library directo=
ry ending with <literal>.jar</literal>
-                to the classpath used for compilation. It will also copy a=
ll non-Java source files to the
-                target directory, configuration and Hibernate mapping file=
s, for example. If you now run Ant, you
-                will get this output:
-            </para>
-
-            <programlisting><![CDATA[C:\hibernateTutorial\>ant
-Buildfile: build.xml
-
-copy-resources:
-     [copy] Copying 2 files to C:\hibernateTutorial\bin
-
-compile:
-    [javac] Compiling 1 source file to C:\hibernateTutorial\bin
-
-BUILD SUCCESSFUL
-Total time: 1 second ]]></programlisting>
-
         </sect2>
 =

         <sect2 id=3D"tutorial-firstapp-helpers" revision=3D"3">
             <title>Startup and helpers</title>
 =

             <para>
-                It is time to load and store some <literal>Event</literal>=
 objects, but first
-                you have to complete the setup with some infrastructure co=
de. You have to startup
-                Hibernate by building a global <literal>SessionFactory</li=
teral>
-                object and storing it somewhere for easy access in applica=
tion code.
-                A <literal>SessionFactory</literal> can open up new <liter=
al>Session</literal>s.
-                A <literal>Session</literal> represents a single-threaded =
unit of work.  The
-                <literal>SessionFactory</literal> is a thread-safe global =
object, that is instantiated once.
+                It is time to load and store some <literal>Event</literal>
+                objects, but first you have to complete the setup with some
+                infrastructure code. You have to startup Hibernate by buil=
ding
+                a global <interfacename>org.hibernate.SessionFactory</inte=
rfacename>
+                object and storing it somewhere for easy access in applica=
tion code.  A
+                <interfacename>org.hibernate.SessionFactory</interfacename=
> is used to
+                obtain <interfacename>org.hibernate.Session</interfacename=
> instances.
+                A <interfacename>org.hibernate.Session</interfacename> rep=
resents a
+                single-threaded unit of work.  The
+                <interfacename>org.hibernate.SessionFactory</interfacename=
> is a
+                thread-safe global object that is instantiated once.
             </para>
 =

             <para>
-                Create a <literal>HibernateUtil</literal> helper class tha=
t takes care
-                of startup and makes accessing a <literal>SessionFactory</=
literal> convenient.
-                The following example illustrates the implementation:
+                We will create a <literal>HibernateUtil</literal> helper c=
lass that
+                takes care of startup and makes accessing the
+                <interfacename>org.hibernate.SessionFactory</interfacename=
> more convenient.
             </para>
 =

-            <programlisting><![CDATA[package util;
+            <programlisting><![CDATA[package org.hibernate.tutorial.util;
 =

-import org.hibernate.*;
-import org.hibernate.cfg.*;
+import org.hibernate.SessionFactory;
+import org.hibernate.cfg.Configuration;
 =

 public class HibernateUtil {
 =

-    private static final SessionFactory sessionFactory;
+    private static final SessionFactory sessionFactory =3D buildSessionFac=
tory();
 =

-    static {
+    private static SessionFactory buildSessionFactory() {
         try {
             // Create the SessionFactory from hibernate.cfg.xml
-            sessionFactory =3D new Configuration().configure().buildSessio=
nFactory();
-        } catch (Throwable ex) {
+            return new Configuration().configure().buildSessionFactory();
+        }
+        catch (Throwable ex) {
             // Make sure you log the exception, as it might be swallowed
             System.err.println("Initial SessionFactory creation failed." +=
 ex);
             throw new ExceptionInInitializerError(ex);
@@ -598,39 +628,28 @@
 }]]></programlisting>
 =

             <para>
-                This class not only produces the global <literal>SessionFa=
ctory</literal> in
-                its static initializer that is called once by the JVM when=
 the class is loaded. It also
-                hides the fact that it uses a static singleton. It might a=
s well lookup the
-                <literal>SessionFactory</literal> from JNDI in an applicat=
ion server.
+                Save this code as
+                <filename>src/main/java/org/hibernate/tutorial/util/Hibern=
ateUtil.java</filename>
             </para>
 =

             <para>
-                If you give the <literal>SessionFactory</literal> a name i=
n your configuration
-                file, Hibernate will try to bind it to JNDI after it has b=
een built.
-                To avoid this code completely you could also use JMX deplo=
yment and let the
-                JMX-capable container instantiate and bind a <literal>Hibe=
rnateService</literal>
-                to JNDI. These advanced options are discussed in the Hiber=
nate reference
-                documentation.
+                This class not only produces the global
+                <interfacename>org.hibernate.SessionFactory</interfacename=
> reference in
+                its static initializer; it also hides the fact that it use=
s a
+                static singleton.  We might just as well have looked up the
+                <interfacename>org.hibernate.SessionFactory</interfacename=
> reference from
+                JNDI in an application server or any other location for th=
at matter.
             </para>
 =

             <para>
-                Place <literal>HibernateUtil.java</literal> in the develop=
ment source directory in
-                a package next to <literal>events</literal>:
+                If you give the <interfacename>org.hibernate.SessionFactor=
y</interfacename>
+                a name in your configuration, Hibernate will try to bind i=
t to
+                JNDI under that name after it has been built.  Another, be=
tter option is to
+                use a JMX deployment and let the JMX-capable container ins=
tantiate and bind
+                a <literal>HibernateService</literal> to JNDI. Such advanc=
ed options are
+                discussed later.
             </para>
 =

-            <programlisting><![CDATA[.
-+lib
-  <Hibernate and third-party libraries>
-+src
-  +events
-    Event.java
-    Event.hbm.xml
-  +util
-    HibernateUtil.java
-  hibernate.cfg.xml
-+data
-build.xml]]></programlisting>
-
             <para>
                 You now need to configure a logging
                 system.  Hibernate uses commons logging and provides two c=
hoices: Log4j and
@@ -652,16 +671,19 @@
             <title>Loading and storing objects</title>
 =

             <para>
-                You can use Hibernate to load and store objects. Write an
-                <literal>EventManager</literal> class with a <literal>main=
()</literal> method:
+                We are now ready to start doing some real worjk with Hiber=
nate.
+                Let's start by writing an <literal>EventManager</literal> =
class
+                with a <literal>main()</literal> method:
             </para>
 =

-            <programlisting><![CDATA[package events;
+            <programlisting><![CDATA[package org.hibernate.tutorial;
+
 import org.hibernate.Session;
 =

-import java.util.Date;
+import java.util.*;
 =

-import util.HibernateUtil;
+import org.hibernate.tutorial.domain.Event;
+import org.hibernate.tutorial.util.HibernateUtil;
 =

 public class EventManager {
 =

@@ -676,15 +698,12 @@
     }
 =

     private void createAndStoreEvent(String title, Date theDate) {
-
         Session session =3D HibernateUtil.getSessionFactory().getCurrentSe=
ssion();
-
         session.beginTransaction();
 =

         Event theEvent =3D new Event();
         theEvent.setTitle(title);
         theEvent.setDate(theDate);
-
         session.save(theEvent);
 =

         session.getTransaction().commit();
@@ -693,165 +712,149 @@
 }]]></programlisting>
 =

             <para>
-                You can create a new <literal>Event</literal> object and h=
and it over to Hibernate.
-                Hibernate takes care of the SQL and executes <literal>INSE=
RT</literal>
-                on the database. We will explain the <literal>Session</lit=
eral> and
-                <literal>Transaction</literal>-handling code before we run=
 this.
+                In <literal>createAndStoreEvent()</literal> we created a n=
ew
+                <literal>Event</literal> object and handed it over to Hibe=
rnate.
+                At that point, Hibernate takes care of the SQL and execute=
s an
+                <literal>INSERT</literal> on the database.
             </para>
 =

             <para>
-                A <literal>Session</literal> is a single unit of work. For=
 now we will keep things
-                simple and assume a one-to-one granularity between a Hiber=
nate <literal>Session</literal>
-                and a database transaction. To shield our code from the ac=
tual underlying transaction
-                system we use the
-                <literal>Transaction</literal> API that is available on th=
e Hibernate <literal>Session</literal>. =

-		In this case plain JDBC, but it could also run with JTA.
+                A <interface>org.hibernate.Session</interface> is designed=
 to
+                represent a single unit of work (a single atmoic piece of =
work
+                to be performed).  For now we will keep things simple and =
assume
+                a one-to-one granularity between a Hibernate
+                <interface>org.hibernate.Session</interface> and a database
+                transaction.  To shield our code from the actual underlying
+                transaction system we use the Hibernate
+                <interfacename>org.hibernate.Transaction</interfacename> A=
PI.
+                In this particular case we are using JDBC-based transactio=
nal
+                semantics, but it could also run with JTA.
             </para>
 =

             <para>
-                What does <literal>sessionFactory.getCurrentSession()</lit=
eral> do? First, you can call it
-                as many times and anywhere you like, once you get hold of =
your <literal>SessionFactory</literal>.
-                This is easy thanks to <literal>HibernateUtil</literal>). =
The <literal>getCurrentSession()</literal>
-                method always returns the "current" unit of work. Remember=
 that we switched the configuration
-                option for this mechanism to "thread" in <literal>hibernat=
e.cfg.xml</literal>? The current unit of work is bound to the current Java =
thread that executes the application.
-                However, you also have to consider when a unit of work
-                begins and when it ends.
+                What does <literal>sessionFactory.getCurrentSession()</lit=
eral> do?
+                First, you can call it as many times and anywhere you like
+                once you get hold of your
+                <interfacename>org.hibernate.SessionFactory</interfacename=
>.
+                The <literal>getCurrentSession()</literal> method always r=
eturns
+                the "current" unit of work.  Remember that we switched
+                the configuration option for this mechanism to "thread" in=
 our
+                <filename>src/main/resources/hibernate.cfg.xml</filename>?
+                Due to that setting, the context of a current unit of work=
 is bound
+                to the current Java thread that executes the application.
             </para>
 =

+            <important>
+                <para>
+                    Hibernate offers three methods of current session trac=
king.
+                    The "thread" based method is not intended for producti=
on use;
+                    it is merely useful for prototyping and tutorials such=
 as this
+                    one.  Current session tracking is discussed in more de=
tail
+                    later on.
+                </para>
+            </important>
+
             <para>
-                A <literal>Session</literal> begins when the first call to
-                <literal>getCurrentSession()</literal> is made. It is then=
 bound by Hibernate to the current
-                thread. When the transaction ends, either through commit o=
r rollback, Hibernate automatically
-                unbinds the <literal>Session</literal> from the thread and=
 closes it for you. If you call
-                <literal>getCurrentSession()</literal> again, you get a ne=
w <literal>Session</literal> and can
-                start a new unit of work. This <emphasis>thread-bound</emp=
hasis> programming model is the most
-                popular way of using Hibernate, as it allows flexible laye=
ring of your code. Transaction
-                demarcation code can be separated from data access code. T=
his will be covered later in this tutorial.
+                A <interface>org.hibernate.Session</interface> begins when=
 the
+                first call to <literal>getCurrentSession()</literal> is ma=
de for
+                the current thread.  It is then bound by Hibernate to the =
current
+                thread.  When the transaction ends, either through commit =
or
+                rollback, Hibernate automatically unbinds the
+                <interface>org.hibernate.Session</interface> from the thre=
ad
+                and closes it for you. If you call
+                <literal>getCurrentSession()</literal> again, you get a new
+                <interface>org.hibernate.Session</interface> and can start=
 a
+                new unit of work.
             </para>
 =

             <para>
-                Related to the unit of work scope, should the Hibernate <l=
iteral>Session</literal> be used to
-                execute one or several database operations? The above exam=
ple uses one <literal>Session</literal>
-                for one operation. This is pure coincidence, the example i=
s just not complex enough to show any
-                other approach. The scope of a Hibernate <literal>Session<=
/literal> is flexible but you should
-                never design your application to use a new Hibernate <lite=
ral>Session</literal> for
-                <emphasis>every</emphasis> database operation. Even though=
 it is used in
-                the following examples, consider <emphasis>session-per-ope=
ration</emphasis>
-                an anti-pattern. A real web application is shown later in =
the tutorial.
+                Related to the unit of work scope, should the Hibernate
+                <interface>org.hibernate.Session</interface> be used to ex=
ecute
+                one or several database operations?  The above example use=
s one
+                <interface>org.hibernate.Session</interface> for one opera=
tion.
+                However this is pure coincidence; the example is just not =
complex
+                enough to show any other approach. The scope of a Hibernate
+                <interface>org.hibernate.Session</interface> is flexible b=
ut you
+                should never design your application to use a new Hibernate
+                <interface>org.hibernate.Session</interface> for
+                <emphasis>every</emphasis> database operation. Even though=
 it is
+                used in the following examples, consider
+                <emphasis>session-per-operation</emphasis> an anti-pattern.
+                A real web application is shown later in the tutorial whic=
h will
+                help illustrate this.
             </para>
 =

             <para>
                 See <xref linkend=3D"transactions"/> for more information
-                about transaction handling and demarcation. The previous e=
xample also skipped any error handling and
-                rollback.
+                about transaction handling and demarcation. The previous
+                example also skipped any error handling and rollback.
             </para>
 =

             <para>
-                To run this first routine we have to add a callable target=
 to the Ant build file:
+                To run this, we will make use of the Maven exec plugin to =
call our class
+                with the necessary classpath setup:
+                <command>mvn exec:java -Dexec.mainClass=3D"org.hibernate.t=
utorial.EventManager" -Dexec.args=3D"store"</command>
             </para>
 =

-            <programlisting><![CDATA[<target name=3D"run" depends=3D"compi=
le">
-    <java fork=3D"true" classname=3D"events.EventManager" classpathref=3D"=
libraries">
-        <classpath path=3D"${targetdir}"/>
-        <arg value=3D"${action}"/>
-    </java>
-</target>]]></programlisting>
+            <note>
+                <para>
+                    You may need to perform <command>mvn compile</command>=
 first.
+                </para>
+            </note>
 =

             <para>
-                The value of the <literal>action</literal> argument is set=
 on the command line when
-                calling the target:
+                You should see Hibernate starting up and, depending on you=
r configuration,
+                lots of log output. Towards the end, the following line wi=
ll be displayed:
             </para>
 =

-            <programlisting><![CDATA[C:\hibernateTutorial\>ant run -Dactio=
n=3Dstore]]></programlisting>
-
-            <para>
-                After compilation, you should see Hibernate starting up an=
d, depending on your
-                configuration, lots of log output. At the end, the followi=
ng line will be displayed:
-            </para>
-
             <programlisting><![CDATA[[java] Hibernate: insert into EVENTS =
(EVENT_DATE, title, EVENT_ID) values (?, ?, ?)]]></programlisting>
 =

             <para>
-                This is the <literal>INSERT</literal> executed by Hibernat=
e. The question marks
-                represent JDBC bind parameters. To view the values bound a=
s arguments, or to reduce
-                the verbosity of the log, check your <literal>log4j.proper=
ties</literal>.
+                This is the <literal>INSERT</literal> executed by Hibernat=
e.
             </para>
 =

             <para>
                 To list stored events an option is added to the main metho=
d:
             </para>
 =

-            <programlisting><![CDATA[if (args[0].equals("store")) {
-    mgr.createAndStoreEvent("My Event", new Date());
-}
-else if (args[0].equals("list")) {
-    List events =3D mgr.listEvents();
-    for (int i =3D 0; i < events.size(); i++) {
-        Event theEvent =3D (Event) events.get(i);
-        System.out.println("Event: " + theEvent.getTitle() +
-                           " Time: " + theEvent.getDate());
-    }
-}]]></programlisting>
+            <programlisting><![CDATA[        if (args[0].equals("store")) {
+            mgr.createAndStoreEvent("My Event", new Date());
+        }
+        else if (args[0].equals("list")) {
+            List events =3D mgr.listEvents();
+            for (int i =3D 0; i < events.size(); i++) {
+                Event theEvent =3D (Event) events.get(i);
+                System.out.println(
+                        "Event: " + theEvent.getTitle() + " Time: " + theE=
vent.getDate()
+                );
+            }
+        }]]></programlisting>
 =

             <para>
                 A new <literal>listEvents() method is also added</literal>:
             </para>
 =

-            <programlisting><![CDATA[private List listEvents() {
+            <programlisting><![CDATA[    private List listEvents() {
+        Session session =3D HibernateUtil.getSessionFactory().getCurrentSe=
ssion();
+        session.beginTransaction();
+        List result =3D session.createQuery("from Event").list();
+        session.getTransaction().commit();
+        return result;
+    }]]></programlisting>
 =

-    Session session =3D HibernateUtil.getSessionFactory().getCurrentSessio=
n();
-
-    session.beginTransaction();
-
-    List result =3D session.createQuery("from Event").list();
-
-    session.getTransaction().commit();
-
-    return result;
-}]]></programlisting>
-
             <para>
-                Use an HQL (Hibernate Query Language) query to load all ex=
isting
+                Here, we are using a Hibernate Query Language (HQL) query =
to load all existing
                 <literal>Event</literal> objects from the database. Hibern=
ate will generate the
                 appropriate SQL, send it to the database and populate <lit=
eral>Event</literal> objects
-                with the data. You can create more complex queries with HQ=
L.
+                with the data. You can create more complex queries with HQ=
L. See <xref linkend=3D"query-hql"/>
+                for more information.
             </para>
 =

             <para>
-                To execute and test all of this, follow these steps:
+                Now we can call our new functionality, again using the Mav=
en exec plugin:
+                <command>mvn exec:java -Dexec.mainClass=3D"org.hibernate.t=
utorial.EventManager" -Dexec.args=3D"list"</command>
             </para>
 =

-            <itemizedlist>
-                <listitem>
-                    <para>
-                        Run <literal>ant run -Daction=3Dstore</literal> to=
 store something in the database
-                        and, of course, to generate the database schema be=
fore through hbm2ddl.
-                    </para>
-                </listitem>
-                <listitem>
-                    <para>
-                        Disable hbm2ddl by commenting out the property in =
your <literal>hibernate.cfg.xml</literal>
-                        file. It is only turned on in continuous unit test=
ing.  Another
-                        run of hbm2ddl would <emphasis>drop</emphasis> eve=
rything you have stored. The
-                        <literal>create</literal> configuration setting tr=
anslates into "drop all
-                        tables from the schema, then re-create all tables,=
 when the SessionFactory is built".
-                    </para>
-                </listitem>
-            </itemizedlist>
-
-            <para>
-                If you can call Ant with <literal>-Daction=3Dlist</literal=
>, you will be able to view the events
-                you have stored so far. You can also call the <literal>sto=
re</literal> action.
-            </para>
-
-            <para>
-                Most new Hibernate users fail at this point and we regular=
ly receive questions relating to
-                <emphasis>Table not found</emphasis> error messages. Howev=
er, if you follow the
-                steps outlined above you will not have this problem, as hb=
m2ddl creates the database
-                schema on the first run, and subsequent application restar=
ts will use this schema. If
-                you change the mapping and/or database schema, you will ha=
ve to re-enable hbm2ddl.
-            </para>
-
         </sect2>
 =

     </sect1>
@@ -860,8 +863,10 @@
         <title>Part 2 - Mapping associations</title>
 =

         <para>
-            You have mapped a persistent entity class to a table. You can =
now build on this by adding some class associations.
-            First you will add people to your application, and store a lis=
t of events they participate in.
+            So far we have mapped a single persistent entity class to a ta=
ble in
+            isolation.  Let's expand on that a bit and add some class asso=
ciations.
+            We will add people to the application and store a list of even=
ts in
+            which they participate.
         </para>
 =

         <sect2 id=3D"tutorial-associations-mappinguser" revision=3D"1">
@@ -871,7 +876,7 @@
                 The first cut of the <literal>Person</literal> class looks=
 like this:
             </para>
 =

-            <programlisting><![CDATA[package events;
+            <programlisting><![CDATA[package org.hibernate.tutorial.domain;
 =

 public class Person {
 =

@@ -887,13 +892,18 @@
 }]]></programlisting>
 =

             <para>
-                Create a new mapping file called <literal>Person.hbm.xml</=
literal>. Do not forget the
-                DTD reference at the top:
+                Save this to a file named
+                <filename>src/main/java/org/hibernate/tutorial/domain/Pers=
on.java</filename>
             </para>
 =

-            <programlisting><![CDATA[<hibernate-mapping>
+            <para>
+                Next, create the new mapping file as
+                <filename>src/main/resources/org/hibernate/tutorial/domain=
/Person.hbm.xml</filename>
+            </para>
 =

-    <class name=3D"events.Person" table=3D"PERSON">
+            <programlisting><![CDATA[<hibernate-mapping package=3D"org.hib=
ernate.tutorial.domain">
+
+    <class name=3D"Person" table=3D"PERSON">
         <id name=3D"id" column=3D"PERSON_ID">
             <generator class=3D"native"/>
         </id>
@@ -924,17 +934,16 @@
             <title>A unidirectional Set-based association</title>
 =

             <para>
-                By adding a collection of events to the <literal>Person</l=
iteral> class, you can
-                easily navigate to the events for a particular person, wit=
hout executing an explicit query -
-                by calling <literal>aPerson.getEvents()</literal>. A Java =
collection, a <literal>Set</literal>, is used
-                because the collection will not contain duplicate elements=
 and the ordering is not relevant to our examples.
+                By adding a collection of events to the <literal>Person</l=
iteral>
+                class, you can easily navigate to the events for a particu=
lar person,
+                without executing an explicit query - by calling
+                <literal>Person#getEvents</literal>.  Multi-valued associa=
tions
+                are represented in Hibernate by one of the Java Collection=
 Framework
+                contracts; here we choose a <interfacename>java.util.Set</=
interfacename>
+                because the collection will not contain duplicate elements=
 and the ordering
+                is not relevant to our examples:
             </para>
 =

-            <para>
-                We need unidirectional, many-valued associations, implemen=
ted with a <literal>Set</literal>.
-                Write the code for this in the Java classes and then map i=
t:
-            </para>
-
             <programlisting><![CDATA[public class Person {
 =

     private Set events =3D new HashSet();
@@ -949,17 +958,19 @@
 }]]></programlisting>
 =

             <para>
-                Before you map this association, consider the other side. =
You could just keep this
-                unidirectional. Or, you could create another collection on=
 the <literal>Event</literal>, if you
-                want to be able to navigate it bi-directional, i.e., <lite=
ral>anEvent.getParticipants()</literal>.
-                This is not necessary, from a functional perspective. You =
can always execute an explicit query
-                to retrieve the participants for a particular event. This =
is a design choice left to you, but what
-                is clear from this discussion is the multiplicity of the a=
ssociation: "many" valued on both sides
-                is called a <emphasis>many-to-many</emphasis> association.=
 Hence, we use Hibernate's
-                many-to-many mapping:
+                Before mapping this association, let's consider the other =
side.
+                We could just keep this unidirectional or create another
+                collection on the <literal>Event</literal>, if we wanted t=
o be
+                able to navigate it from both directions.  This is not nec=
essary,
+                from a functional perspective. You can always execute an e=
xplicit
+                query to retrieve the participants for a particular event.=
  This
+                is a design choice left to you, but what is clear from this
+                discussion is the multiplicity of the association: "many" =
valued
+                on both sides is called a <emphasis>many-to-many</emphasis>
+                association. Hence, we use Hibernate's many-to-many mappin=
g:
             </para>
 =

-            <programlisting><![CDATA[<class name=3D"events.Person" table=
=3D"PERSON">
+            <programlisting><![CDATA[<class name=3D"Person" table=3D"PERSO=
N">
     <id name=3D"id" column=3D"PERSON_ID">
         <generator class=3D"native"/>
     </id>
@@ -969,20 +980,24 @@
 =

     <set name=3D"events" table=3D"PERSON_EVENT">
         <key column=3D"PERSON_ID"/>
-        <many-to-many column=3D"EVENT_ID" class=3D"events.Event"/>
+        <many-to-many column=3D"EVENT_ID" class=3D"Event"/>
     </set>
 =

 </class>]]></programlisting>
 =

             <para>
-                Hibernate supports a broad range of collection mappings, a=
 <literal>&lt;set&gt;</literal> being most
-                common. For a many-to-many association, or <emphasis>n:m</=
emphasis> entity relationship, an
-                association table is required. Each row in this table repr=
esents a link between a person and an event.
-                The table name is configured with the <literal>table</lite=
ral> attribute of the <literal>set</literal>
-                element. The identifier column name in the association, fo=
r the person side, is defined with the
-                <literal>&lt;key&gt;</literal> element, the column name fo=
r the event's side with the
-                <literal>column</literal> attribute of the <literal>&lt;ma=
ny-to-many&gt;</literal>. You also
-                have to tell Hibernate the class of the objects in your co=
llection (the class on the
+                Hibernate supports a broad range of collection mappings, a
+                <literal>set</literal> being most common.  For a many-to-m=
any
+                association, or <emphasis>n:m</emphasis> entity relationsh=
ip, an
+                association table is required.  Each row in this table rep=
resents
+                a link between a person and an event.  The table name is
+                decalred using the <literal>table</literal> attribute of t=
he
+                <literal>set</literal> element.  The identifier column nam=
e in
+                the association, for the person side, is defined with the
+                <literal>key</literal> element, the column name for the ev=
ent's
+                side with the <literal>column</literal> attribute of the
+                <literal>many-to-many</literal>. You also have to tell Hib=
ernate
+                the class of the objects in your collection (the class on =
the
                 other side of the collection of references).
             </para>
 =

@@ -1013,73 +1028,77 @@
                 Now we will bring some people and events together in a new=
 method in <literal>EventManager</literal>:
             </para>
 =

-            <programlisting><![CDATA[private void addPersonToEvent(Long pe=
rsonId, Long eventId) {
+            <programlisting><![CDATA[    private void addPersonToEvent(Lon=
g personId, Long eventId) {
+        Session session =3D HibernateUtil.getSessionFactory().getCurrentSe=
ssion();
+        session.beginTransaction();
 =

-    Session session =3D HibernateUtil.getSessionFactory().getCurrentSessio=
n();
-    session.beginTransaction();
+        Person aPerson =3D (Person) session.load(Person.class, personId);
+        Event anEvent =3D (Event) session.load(Event.class, eventId);
+        aPerson.getEvents().add(anEvent);
 =

-    Person aPerson =3D (Person) session.load(Person.class, personId);
-    Event anEvent =3D (Event) session.load(Event.class, eventId);
+        session.getTransaction().commit();
+    }]]></programlisting>
 =

-    aPerson.getEvents().add(anEvent);
-
-    session.getTransaction().commit();
-}]]></programlisting>
-
             <para>
-                After loading a <literal>Person</literal> and an <literal>=
Event</literal>, simply
-                modify the collection using the normal collection methods.=
 There is no explicit call
-                to <literal>update()</literal> or <literal>save()</literal=
>; Hibernate automatically
-                detects that the collection has been modified and needs to=
 be updated. This is called <emphasis>automatic
-                dirty checking</emphasis>. You can also try it by modifyin=
g the name or the date property of
-                any of your objects. As long as they are in <emphasis>pers=
istent</emphasis> state, that is, bound
-                to a particular Hibernate <literal>Session</literal> (i.e.=
 they have been just loaded or saved in
-                a unit of work), Hibernate monitors any changes and execut=
es SQL in a write-behind fashion. The
-                process of synchronizing the memory state with the databas=
e, usually only at the end of a unit of
-                work, is called <emphasis>flushing</emphasis>. In our code=
, the unit of work ends with a commit,
-                or rollback, of the database transaction. This is defined =
by the <literal>thread</literal> configuration
-                option for the <literal>CurrentSessionContext</literal> cl=
ass.
+                After loading a <literal>Person</literal> and an
+                <literal>Event</literal>, simply modify the collection usi=
ng the
+                normal collection methods. There is no explicit call to
+                <literal>update()</literal> or <literal>save()</literal>;
+                Hibernate automatically detects that the collection has be=
en modified
+                and needs to be updated. This is called
+                <emphasis>automatic dirty checking</emphasis>. You can als=
o try
+                it by modifying the name or the date property of any of yo=
ur
+                objects.  As long as they are in <emphasis>persistent</emp=
hasis>
+                state, that is, bound to a particular Hibernate
+                <interfacename>org.hibernate.Session</interfacename>, Hibe=
rnate
+                monitors any changes and executes SQL in a write-behind fa=
shion.
+                The process of synchronizing the memory state with the dat=
abase,
+                usually only at the end of a unit of work, is called
+                <emphasis>flushing</emphasis>.  In our code, the unit of w=
ork
+                ends with a commit, or rollback, of the database transacti=
on.
             </para>
 =

             <para>
-                You can load person and event in different units of work. =
Or you can modify an object
-                outside of a <literal>Session</literal>, when it is not in=
 persistent state (if it was persistent
-                before, this state is called <emphasis>detached</emphasis>=
). You can even modify a collection when
-                it is detached:
+                You can load person and event in different units of work. =
 Or
+                you can modify an object outside of a
+                <interfacename>org.hibernate.Session</interfacename>, when=
 it
+                is not in persistent state (if it was persistent before, t=
his
+                state is called <emphasis>detached</emphasis>).  You can e=
ven
+                modify a collection when it is detached:
             </para>
 =

-            <programlisting><![CDATA[private void addPersonToEvent(Long pe=
rsonId, Long eventId) {
+            <programlisting><![CDATA[    private void addPersonToEvent(Lon=
g personId, Long eventId) {
+        Session session =3D HibernateUtil.getSessionFactory().getCurrentSe=
ssion();
+        session.beginTransaction();
 =

-    Session session =3D HibernateUtil.getSessionFactory().getCurrentSessio=
n();
-    session.beginTransaction();
+        Person aPerson =3D (Person) session
+                .createQuery("select p from Person p left join fetch p.eve=
nts where p.id =3D :pid")
+                .setParameter("pid", personId)
+                .uniqueResult(); // Eager fetch the collection so we can u=
se it detached
+        Event anEvent =3D (Event) session.load(Event.class, eventId);
 =

-    Person aPerson =3D (Person) session
-            .createQuery("select p from Person p left join fetch p.events =
where p.id =3D :pid")
-            .setParameter("pid", personId)
-            .uniqueResult(); // Eager fetch the collection so we can use i=
t detached
+        session.getTransaction().commit();
 =

-    Event anEvent =3D (Event) session.load(Event.class, eventId);
+        // End of first unit of work
 =

-    session.getTransaction().commit();
+        aPerson.getEvents().add(anEvent); // aPerson (and its collection) =
is detached
 =

-    // End of first unit of work
+        // Begin second unit of work
 =

-    aPerson.getEvents().add(anEvent); // aPerson (and its collection) is d=
etached
+        Session session2 =3D HibernateUtil.getSessionFactory().getCurrentS=
ession();
+        session2.beginTransaction();
+        session2.update(aPerson); // Reattachment of aPerson
 =

-    // Begin second unit of work
+        session2.getTransaction().commit();
+    }]]></programlisting>
 =

-    Session session2 =3D HibernateUtil.getSessionFactory().getCurrentSessi=
on();
-    session2.beginTransaction();
-
-    session2.update(aPerson); // Reattachment of aPerson
-
-    session2.getTransaction().commit();
-}]]></programlisting>
-
             <para>
-                The call to <literal>update</literal> makes a detached obj=
ect persistent again by binding it to a new unit of work, so any modificati=
ons you made to it while detached
-                can be saved to the database. This includes any modificati=
ons (additions/deletions) you
-                made to a collection of that entity object.
+                The call to <literal>update</literal> makes a detached obj=
ect
+                persistent again by binding it to a new unit of work, so a=
ny
+                modifications you made to it while detached can be saved to
+                the database. This includes any modifications
+                (additions/deletions) you made to a collection of that ent=
ity
+                object.
             </para>
 =

             <para>
@@ -1090,29 +1109,35 @@
                 returns it (you might have to modify some of the previous =
methods to return that identifier):
             </para>
 =

-            <programlisting><![CDATA[else if (args[0].equals("addpersontoe=
vent")) {
-    Long eventId =3D mgr.createAndStoreEvent("My Event", new Date());
-    Long personId =3D mgr.createAndStorePerson("Foo", "Bar");
-    mgr.addPersonToEvent(personId, eventId);
-    System.out.println("Added person " + personId + " to event " + eventId=
);
-}]]></programlisting>
+            <programlisting><![CDATA[        else if (args[0].equals("addp=
ersontoevent")) {
+            Long eventId =3D mgr.createAndStoreEvent("My Event", new Date(=
));
+            Long personId =3D mgr.createAndStorePerson("Foo", "Bar");
+            mgr.addPersonToEvent(personId, eventId);
+            System.out.println("Added person " + personId + " to event " +=
 eventId);
+        }]]></programlisting>
 =

             <para>
-                This is an example of an association between two equally i=
mportant classes, two entities.
-                As mentioned earlier, there are other classes and types in=
 a typical model, usually "less
-                important". Some you have already seen, like an <literal>i=
nt</literal> or a <literal>String</literal>.
-                We call these classes <emphasis>value types</emphasis>, an=
d their instances <emphasis>depend</emphasis>
-                on a particular entity. Instances of these types do not ha=
ve their own identity, nor are they
-                shared between entities. Two persons do not reference the =
same <literal>firstname</literal>
-                object, even if they have the same first name. Value types=
 cannot only be found in
-                the JDK , but
-                you can also write dependent classes yourself (<literal>Ad=
dress</literal> or <literal>MonetaryAmount</literal>,
-                for example). In fact, in a Hibernate application all JDK =
classes are considered value types.
+                This is an example of an association between two equally i=
mportant
+                classes : two entities.  As mentioned earlier, there are o=
ther
+                classes and types in a typical model, usually "less import=
ant".
+                Some you have already seen, like an <literal>int</literal>=
 or a
+                <classname>java.lang.String</classname>.  We call these cl=
asses
+                <emphasis>value types</emphasis>, and their instances
+                <emphasis>depend</emphasis> on a particular entity.  Insta=
nces of
+                these types do not have their own identity, nor are they s=
hared
+                between entities.  Two persons do not reference the same
+                <literal>firstname</literal> object, even if they have the=
 same
+                first name.  Value types cannot only be found in the JDK ,=
 but
+                you can also write dependent classes yourself
+                such as an <literal>Address</literal> or
+                <literal>MonetaryAmount</literal> class.  In fact, in a Hi=
bernate
+                application all JDK classes are considered value types.
             </para>
 =

             <para>
-                You can also design a collection of value types. This is c=
onceptually different from a
-                collection of references to other entities, but looks almo=
st the same in Java.
+                You can also design a collection of value types.  This is
+                conceptually different from a collection of references to =
other
+                entities, but looks almost the same in Java.
             </para>
 =

         </sect2>
@@ -1121,37 +1146,44 @@
             <title>Collection of values</title>
 =

             <para>
-                You can add a collection of value typed objects to the <li=
teral>Person</literal> entity. If you want to
-                store email addresses, the type you use is <literal>String=
</literal>, and the collection is
-                again a <literal>Set</literal>:
+                Let's add a collection of email addresses to the
+                <literal>Person</literal> entity.  This will be represente=
d as a
+                <interfacename>java.util.Set</interfacename> of
+                <classname>java.lang.String</classname> instances:
             </para>
-            <programlisting><![CDATA[private Set emailAddresses =3D new Ha=
shSet();
+            <programlisting><![CDATA[    private Set emailAddresses =3D ne=
w HashSet();
 =

-public Set getEmailAddresses() {
-    return emailAddresses;
-}
+    public Set getEmailAddresses() {
+        return emailAddresses;
+    }
 =

-public void setEmailAddresses(Set emailAddresses) {
-    this.emailAddresses =3D emailAddresses;
-}]]></programlisting>
+    public void setEmailAddresses(Set emailAddresses) {
+        this.emailAddresses =3D emailAddresses;
+    }]]></programlisting>
 =

             <para>
                 The mapping of this <literal>Set</literal> is as follows:
             </para>
 =

-            <programlisting><![CDATA[<set name=3D"emailAddresses" table=3D=
"PERSON_EMAIL_ADDR">
-    <key column=3D"PERSON_ID"/>
-    <element type=3D"string" column=3D"EMAIL_ADDR"/>
-</set>]]></programlisting>
+            <programlisting><![CDATA[        <set name=3D"emailAddresses" =
table=3D"PERSON_EMAIL_ADDR">
+            <key column=3D"PERSON_ID"/>
+            <element type=3D"string" column=3D"EMAIL_ADDR"/>
+        </set>]]></programlisting>
 =

             <para>
-                The difference compared with the earlier mapping is the <l=
iteral>element</literal> part which tells Hibernate that the collection
-                does not contain references to another entity, but a colle=
ction of elements of type
-                <literal>String</literal>. The lowercase name tells you it=
 is a Hibernate mapping type/converter.
-                Again the <literal>table</literal> attribute of the <liter=
al>set</literal> element determines
-                the table name for the collection. The <literal>key</liter=
al> element defines the foreign-key column
-                name in the collection table. The <literal>column</literal=
> attribute in the <literal>element</literal>
-                element defines the column name where the <literal>String<=
/literal> values will actually be stored.
+                The difference compared with the earlier mapping is the us=
e of
+                the <literal>element</literal> part which tells Hibernate =
that the
+                collection does not contain references to another entity, =
but is
+                rather a collection whose elements are values types, here =
specifically
+                of type <literal>string</literal>.  The lowercase name tel=
ls you
+                it is a Hibernate mapping type/converter.  Again the
+                <literal>table</literal> attribute of the <literal>set</li=
teral>
+                element determines the table name for the collection.   The
+                <literal>key</literal> element defines the foreign-key col=
umn
+                name in the collection table. The <literal>column</literal>
+                attribute in the <literal>element</literal> element define=
s the
+                column name where the email address values will actually
+                be stored.
             </para>
 =

             <para>
@@ -1183,24 +1215,21 @@
                 linking persons and events. It is the same code in Java:
             </para>
 =

-            <programlisting><![CDATA[private void addEmailToPerson(Long pe=
rsonId, String emailAddress) {
+            <programlisting><![CDATA[    private void addEmailToPerson(Lon=
g personId, String emailAddress) {
+        Session session =3D HibernateUtil.getSessionFactory().getCurrentSe=
ssion();
+        session.beginTransaction();
 =

-    Session session =3D HibernateUtil.getSessionFactory().getCurrentSessio=
n();
-    session.beginTransaction();
+        Person aPerson =3D (Person) session.load(Person.class, personId);
+        // adding to the emailAddress collection might trigger a lazy load=
 of the collection
+        aPerson.getEmailAddresses().add(emailAddress);
 =

-    Person aPerson =3D (Person) session.load(Person.class, personId);
+        session.getTransaction().commit();
+    }]]></programlisting>
 =

-    // The getEmailAddresses() might trigger a lazy load of the collection
-    aPerson.getEmailAddresses().add(emailAddress);
-
-    session.getTransaction().commit();
-}]]></programlisting>
-
             <para>
-                This time we did not use a <emphasis>fetch</emphasis> quer=
y to initialize the collection.
-                Hence, the call to its getter method will trigger an addit=
ional select to initialize
-                it, so we can add an element to it. Monitor the SQL log an=
d try to optimize this with
-                an eager fetch.
+                This time we did not use a <emphasis>fetch</emphasis> quer=
y to
+                initialize the collection.  Monitor the SQL log and try to
+                optimize this with an eager fetch.
             </para>
 =

         </sect2>
@@ -1209,35 +1238,44 @@
             <title>Bi-directional associations</title>
 =

             <para>
-                Next you will map a bi-directional association. You will m=
ake the association between
-                person and event work from both sides in Java. The databas=
e schema does not
-                change, so you will still have many-to-many multiplicity. =
A relational database is more flexible
-                than a network programming language, so it does not need a=
 navigation
-                direction; data can be viewed and retrieved in any possibl=
e way.
+                Next you will map a bi-directional association.  You will =
make
+                the association between person and event work from both si=
des
+                in Java.  The database schema does not change, so you will=
 still
+                have many-to-many multiplicity.
             </para>
 =

+            <note>
+                <para>
+                    A relational database is more flexible than a network
+                    programming language, in that it does not need a navig=
ation
+                    direction; data can be viewed and retrieved in any pos=
sible
+                    way.
+                </para>
+            </note>
+
             <para>
-                First, add a collection of participants to the <literal>Ev=
ent</literal> Event class:
+                First, add a collection of participants to the
+                <literal>Event</literal> class:
             </para>
 =

-            <programlisting><![CDATA[private Set participants =3D new Hash=
Set();
+            <programlisting><![CDATA[    private Set participants =3D new =
HashSet();
 =

-public Set getParticipants() {
-    return participants;
-}
+    public Set getParticipants() {
+        return participants;
+    }
 =

-public void setParticipants(Set participants) {
-    this.participants =3D participants;
-}]]></programlisting>
+    public void setParticipants(Set participants) {
+        this.participants =3D participants;
+    }]]></programlisting>
 =

             <para>
                 Now map this side of the association in <literal>Event.hbm=
.xml</literal>.
             </para>
 =

-            <programlisting><![CDATA[<set name=3D"participants" table=3D"P=
ERSON_EVENT" inverse=3D"true">
-    <key column=3D"EVENT_ID"/>
-    <many-to-many column=3D"PERSON_ID" class=3D"events.Person"/>
-</set>]]></programlisting>
+            <programlisting><![CDATA[        <set name=3D"participants" ta=
ble=3D"PERSON_EVENT" inverse=3D"true">
+            <key column=3D"EVENT_ID"/>
+            <many-to-many column=3D"PERSON_ID" class=3D"events.Person"/>
+        </set>]]></programlisting>
 =

             <para>
                 These are normal <literal>set</literal> mappings in both m=
apping documents.
@@ -1273,23 +1311,23 @@
                 correctly set both sides (for example, in <literal>Person<=
/literal>):
             </para>
 =

-            <programlisting><![CDATA[protected Set getEvents() {
-    return events;
-}
+            <programlisting><![CDATA[    protected Set getEvents() {
+        return events;
+    }
 =

-protected void setEvents(Set events) {
-    this.events =3D events;
-}
+    protected void setEvents(Set events) {
+        this.events =3D events;
+    }
 =

-public void addToEvent(Event event) {
-    this.getEvents().add(event);
-    event.getParticipants().add(this);
-}
+    public void addToEvent(Event event) {
+        this.getEvents().add(event);
+        event.getParticipants().add(this);
+    }
 =

-public void removeFromEvent(Event event) {
-    this.getEvents().remove(event);
-    event.getParticipants().remove(this);
-}]]></programlisting>
+    public void removeFromEvent(Event event) {
+        this.getEvents().remove(event);
+        event.getParticipants().remove(this);
+    }]]></programlisting>
 =

             <para>
                 The get and set methods for the collection are now protect=
ed. This allows classes in the
@@ -1309,7 +1347,6 @@
                 and in many-to-many association you can select either side.
             </para>
 =

-	<para>In the next section we will turn this into a small web application.=
</para>
         </sect2>
 =

     </sect1>
@@ -1328,50 +1365,51 @@
             <title>Writing the basic servlet</title>
 =

             <para>
-                Create a new class in your source directory in the <litera=
l>events</literal>
-                package:
+                First we need create our basic processing servlet.  Since =
our
+                servlet only handles HTTP <literal>GET</literal> requests,=
 we
+                will only implement the <literal>doGet()</literal> method:
             </para>
 =

-            <programlisting><![CDATA[package events;
+            <programlisting><![CDATA[package org.hibernate.tutorial.web;
 =

 // Imports
 =

 public class EventManagerServlet extends HttpServlet {
 =

-    // Servlet code
-}]]></programlisting>
+    protected void doGet(
+            HttpServletRequest request,
+            HttpServletResponse response) throws ServletException, IOExcep=
tion {
 =

-            <para>
-                The servlet handles HTTP <literal>GET</literal> requests o=
nly. It is for this reason that the method
-                we implement is <literal>doGet()</literal>:
-            </para>
+        SimpleDateFormat dateFormatter =3D new SimpleDateFormat( "dd.MM.yy=
yy" );
 =

-            <programlisting><![CDATA[protected void doGet(HttpServletReque=
st request,
-                     HttpServletResponse response)
-        throws ServletException, IOException {
+        try {
+            // Begin unit of work
+            HibernateUtil.getSessionFactory().getCurrentSession().beginTra=
nsaction();
 =

-    SimpleDateFormat dateFormatter =3D new SimpleDateFormat("dd.MM.yyyy");
+            // Process request and render page...
 =

-    try {
-        // Begin unit of work
-        HibernateUtil.getSessionFactory()
-                .getCurrentSession().beginTransaction();
-
-        // Process request and render page...
-
-        // End unit of work
-        HibernateUtil.getSessionFactory()
-                .getCurrentSession().getTransaction().commit();
-
-    } catch (Exception ex) {
-        HibernateUtil.getSessionFactory()
-                .getCurrentSession().getTransaction().rollback();
-        throw new ServletException(ex);
+            // End unit of work
+            HibernateUtil.getSessionFactory().getCurrentSession().getTrans=
action().commit();
+        }
+        catch (Exception ex) {
+            HibernateUtil.getSessionFactory().getCurrentSession().getTrans=
action().rollback();
+            if ( ServletException.class.isInstance( ex ) ) {
+                throw ( ServletException ) ex;
+            }
+            else {
+                throw new ServletException( ex );
+            }
+        }
     }
 =

 }]]></programlisting>
 =

             <para>
+                Save this servlet as
+                <filename>src/main/java/org/hibernate/tutorial/web/EventMa=
nagerServlet.java</filename>
+            </para>
+
+            <para>
                 The pattern applied here is called <emphasis>session-per-r=
equest</emphasis>.
                 When a request hits the servlet, a new Hibernate <literal>=
Session</literal> is
                 opened through the first call to <literal>getCurrentSessio=
n()</literal> on the
@@ -1412,32 +1450,33 @@
                 Now you can implement the processing of the request and th=
e rendering of the page.
             </para>
 =

-<programlisting><![CDATA[// Write HTML header
-PrintWriter out =3D response.getWriter();
-out.println("<html><head><title>Event Manager</title></head><body>");
+<programlisting><![CDATA[        // Write HTML header
+        PrintWriter out =3D response.getWriter();
+        out.println("<html><head><title>Event Manager</title></head><body>=
");
 =

-// Handle actions
-if ( "store".equals(request.getParameter("action")) ) {
+        // Handle actions
+        if ( "store".equals(request.getParameter("action")) ) {
 =

-    String eventTitle =3D request.getParameter("eventTitle");
-    String eventDate =3D request.getParameter("eventDate");
+            String eventTitle =3D request.getParameter("eventTitle");
+            String eventDate =3D request.getParameter("eventDate");
 =

-    if ( "".equals(eventTitle) || "".equals(eventDate) ) {
-        out.println("<b><i>Please enter event title and date.</i></b>");
-    } else {
-        createAndStoreEvent(eventTitle, dateFormatter.parse(eventDate));
-        out.println("<b><i>Added event.</i></b>");
-    }
-}
+            if ( "".equals(eventTitle) || "".equals(eventDate) ) {
+                out.println("<b><i>Please enter event title and date.</i><=
/b>");
+            }
+            else {
+                createAndStoreEvent(eventTitle, dateFormatter.parse(eventD=
ate));
+                out.println("<b><i>Added event.</i></b>");
+            }
+        }
 =

-// Print page
-printEventForm(out);
-listEvents(out, dateFormatter);
+        // Print page
+       printEventForm(out);
+       listEvents(out, dateFormatter);
 =

-// Write HTML footer
-out.println("</body></html>");
-out.flush();
-out.close();]]></programlisting>
+       // Write HTML footer
+       out.println("</body></html>");
+       out.flush();
+       out.close();]]></programlisting>
 =

             <para>
                 This coding style, with a mix of Java and HTML, would not =
scale
@@ -1448,14 +1487,14 @@
                 trivial and only outputs HTML:
             </para>
 =

-            <programlisting><![CDATA[private void printEventForm(PrintWrit=
er out) {
-    out.println("<h2>Add new event:</h2>");
-    out.println("<form>");
-    out.println("Title: <input name=3D'eventTitle' length=3D'50'/><br/>");
-    out.println("Date (e.g. 24.12.2009): <input name=3D'eventDate' length=
=3D'10'/><br/>");
-    out.println("<input type=3D'submit' name=3D'action' value=3D'store'/>"=
);
-    out.println("</form>");
-}]]></programlisting>
+            <programlisting><![CDATA[    private void printEventForm(Print=
Writer out) {
+        out.println("<h2>Add new event:</h2>");
+        out.println("<form>");
+        out.println("Title: <input name=3D'eventTitle' length=3D'50'/><br/=
>");
+        out.println("Date (e.g. 24.12.2009): <input name=3D'eventDate' len=
gth=3D'10'/><br/>");
+        out.println("<input type=3D'submit' name=3D'action' value=3D'store=
'/>");
+        out.println("</form>");
+    }]]></programlisting>
 =

             <para>
                 The <literal>listEvents()</literal> method uses the Hibern=
ate
@@ -1463,27 +1502,28 @@
                 a query:
             </para>
 =

-            <programlisting><![CDATA[private void listEvents(PrintWriter o=
ut, SimpleDateFormat dateFormatter) {
+            <programlisting><![CDATA[    private void listEvents(PrintWrit=
er out, SimpleDateFormat dateFormatter) {
 =

-    List result =3D HibernateUtil.getSessionFactory()
-                    .getCurrentSession().createCriteria(Event.class).list(=
);
-    if (result.size() > 0) {
-        out.println("<h2>Events in database:</h2>");
-        out.println("<table border=3D'1'>");
-        out.println("<tr>");
-        out.println("<th>Event title</th>");
-        out.println("<th>Event date</th>");
-        out.println("</tr>");
-        for (Iterator it =3D result.iterator(); it.hasNext();) {
-            Event event =3D (Event) it.next();
+        List result =3D HibernateUtil.getSessionFactory()
+                .getCurrentSession().createCriteria(Event.class).list();
+        if (result.size() > 0) {
+            out.println("<h2>Events in database:</h2>");
+            out.println("<table border=3D'1'>");
             out.println("<tr>");
-            out.println("<td>" + event.getTitle() + "</td>");
-            out.println("<td>" + dateFormatter.format(event.getDate()) + "=
</td>");
+            out.println("<th>Event title</th>");
+            out.println("<th>Event date</th>");
             out.println("</tr>");
+            Iterator it =3D result.iterator();
+            while (it.hasNext()) {
+                Event event =3D (Event) it.next();
+                out.println("<tr>");
+                out.println("<td>" + event.getTitle() + "</td>");
+                out.println("<td>" + dateFormatter.format(event.getDate())=
 + "</td>");
+                out.println("</tr>");
+            }
+            out.println("</table>");
         }
-        out.println("</table>");
-    }
-}]]></programlisting>
+    }]]></programlisting>
 =

             <para>
                 Finally, the <literal>store</literal> action is dispatched=
 to the
@@ -1491,14 +1531,14 @@
                 the <literal>Session</literal> of the current thread:
             </para>
 =

-            <programlisting><![CDATA[protected void createAndStoreEvent(St=
ring title, Date theDate) {
-    Event theEvent =3D new Event();
-    theEvent.setTitle(title);
-    theEvent.setDate(theDate);
+            <programlisting><![CDATA[    protected void createAndStoreEven=
t(String title, Date theDate) {
+        Event theEvent =3D new Event();
+        theEvent.setTitle(title);
+        theEvent.setDate(theDate);
 =

-    HibernateUtil.getSessionFactory()
-                    .getCurrentSession().save(theEvent);
-}]]></programlisting>
+        HibernateUtil.getSessionFactory()
+                .getCurrentSession().save(theEvent);
+    }]]></programlisting>
 =

             <para>
                 The servlet is now complete. A request to the servlet will=
 be processed
@@ -1517,26 +1557,11 @@
             <title>Deploying and testing</title>
 =

             <para>
-                To deploy this application you have to create a web archiv=
e, or what is known as a WAR. Add the
-                following Ant target to your <literal>build.xml</literal>:
+                To deploy this application for testing we must create a
+                Web ARchive (WAR).  First we must define the WAR descriptor
+                as <filename>src/main/webapp/WEB-INF/web.xml</filename>
             </para>
 =

-<programlisting><![CDATA[<target name=3D"war" depends=3D"compile">
-    <war destfile=3D"hibernate-tutorial.war" webxml=3D"web.xml">
-        <lib dir=3D"${librarydir}">
-          <exclude name=3D"jsdk*.jar"/>
-        </lib>
-
-        <classes dir=3D"${targetdir}"/>
-    </war>
-</target>]]></programlisting>
-
-            <para>
-                This target creates a file called <literal>hibernate-tutor=
ial.war</literal>
-                in your project directory. It packages all libraries and t=
he <literal>web.xml</literal>
-                descriptor, which is expected in the base directory of you=
r project:
-            </para>
-
             <programlisting><![CDATA[<?xml version=3D"1.0" encoding=3D"UTF=
-8"?>
 <web-app version=3D"2.4"
     xmlns=3D"http://java.sun.com/xml/ns/j2ee"
@@ -1545,7 +1570,7 @@
 =

     <servlet>
         <servlet-name>Event Manager</servlet-name>
-        <servlet-class>events.EventManagerServlet</servlet-class>
+        <servlet-class>org.hibernate.tutorial.web.EventManagerServlet</ser=
vlet-class>
     </servlet>
 =

     <servlet-mapping>
@@ -1555,20 +1580,19 @@
 </web-app>]]></programlisting>
 =

             <para>
-                Before you compile and deploy the web application, an addi=
tional library
-                is required: <literal>jsdk.jar</literal>. This is the Java=
 servlet development kit.
-                If you do not have this library already, get it from the S=
un website and copy it to
-                your library directory. However, it will be only used for =
compilation and excluded
-                from the WAR package.
+                To build and deploy call <literal>mvn package</literal> in=
 your
+                project directory and copy the <filename>hibernate-tutoria=
l.war</filename>
+                file into your Tomcat <filename>webapps</filename> directo=
ry.
             </para>
 =

-            <para>
-                To build and deploy call <literal>ant war</literal> in you=
r project directory
-                and copy the <literal>hibernate-tutorial.war</literal> fil=
e into your Tomcat
-                <literal>webapp</literal> directory. If you do not have To=
mcat installed, download
-                it and follow the installation instructions. You do not ha=
ve to change any Tomcat
-                configuration to deploy this application though.
-            </para>
+            <note>
+                <para>
+                    If you do not have Tomcat installed, download it from
+                    <ulink url=3D"http://tomcat.apache.org/"/> and follow =
the
+                    installation instructions.  Our application requires
+                    no changes to the standard Tomcat configuration.
+                </para>
+            </note>
 =

             <para>
                 Once deployed and Tomcat is running, access the applicatio=
n at
@@ -1587,21 +1611,10 @@
 =

         <para>
             This tutorial covered the basics of writing a simple standalon=
e Hibernate application
-            and a small web application.
+            and a small web application.  More tutorials are available fro=
m the Hibernate
+            <ulink url=3D"http://hibernate.org">website</ulink>.
         </para>
 =

-        <para>
-            If you already feel confident with Hibernate, continue browsin=
g through the reference
-            documentation table of contents for topics you find interestin=
g. The most popular are
-            transactional processing (<xref linkend=3D"transactions"/>), f=
etch
-            performance (<xref linkend=3D"performance"/>), or the usage of=
 the API (<xref linkend=3D"objectstate"/>)
-            and the query features (<xref linkend=3D"objectstate-querying"=
/>).
-        </para>
-
-        <para>
-            More tutorials are available from the Hibernate website.
-        </para>
-
     </sect1>
 =

 </chapter>


--===============7507922504910344565==--