From hibernate-commits at lists.jboss.org Tue Aug 31 13:59:31 2010
Content-Type: multipart/mixed; boundary="===============8329380371290274033=="
MIME-Version: 1.0
From: hibernate-commits at lists.jboss.org
To: hibernate-commits at lists.jboss.org
Subject: [hibernate-commits] Hibernate SVN: r20292 - in
 core/trunk/documentation/quickstart: src/main/docbook/en-US/content and 2
 other directories.
Date: Tue, 31 Aug 2010 13:59:31 -0400
Message-ID: <201008311759.o7VHxVwv018502@svn01.web.mwc.hst.phx2.redhat.com>

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

Author: steve.ebersole(a)jboss.com
Date: 2010-08-31 13:59:31 -0400 (Tue, 31 Aug 2010)
New Revision: 20292

Added:
   core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutor=
ial_jpa.xml
Modified:
   core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_Get=
ting_Started_Guide.xml
   core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutor=
ial_annotations.xml
   core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutor=
ial_native.xml
   core/trunk/documentation/quickstart/tutorials/entitymanager/src/test/jav=
a/org/hibernate/tutorial/em/EntityManagerIllustrationTest.java
   core/trunk/documentation/quickstart/tutorials/entitymanager/src/test/res=
ources/META-INF/persistence.xml
Log:
HHH-5445 - Write a jpa/entitymanager tutorial guide


Modified: core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibern=
ate_Getting_Started_Guide.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/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_Ge=
tting_Started_Guide.xml	2010-08-31 16:05:27 UTC (rev 20291)
+++ core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_Ge=
tting_Started_Guide.xml	2010-08-31 17:59:31 UTC (rev 20292)
@@ -31,6 +31,7 @@
         </partintro>
         <xi:include xmlns:xi=3D"http://www.w3.org/2001/XInclude" href=3D"c=
ontent/tutorial_native.xml" />
         <xi:include xmlns:xi=3D"http://www.w3.org/2001/XInclude" href=3D"c=
ontent/tutorial_annotations.xml" />
+        <xi:include xmlns:xi=3D"http://www.w3.org/2001/XInclude" href=3D"c=
ontent/tutorial_jpa.xml" />
     </part>
 =

 </book>
\ No newline at end of file

Modified: core/trunk/documentation/quickstart/src/main/docbook/en-US/conten=
t/tutorial_annotations.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/trunk/documentation/quickstart/src/main/docbook/en-US/content/tuto=
rial_annotations.xml	2010-08-31 16:05:27 UTC (rev 20291)
+++ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tuto=
rial_annotations.xml	2010-08-31 17:59:31 UTC (rev 20292)
@@ -30,7 +30,7 @@
         </para>
     </section>
 =

-    <section id=3D"hibernate-gsg-tutorial-basic-entity">
+    <section id=3D"hibernate-gsg-tutorial-annotations-entity">
         <title>The annotated entity Java class</title>
         <para>
             The entity class in this tutorial is <classname>org.hibernate.=
tutorial.annotations.Event</classname>
@@ -39,7 +39,7 @@
             annotations to provide the metadata instead of a separate <fil=
ename>hbm.xml</filename> file.
         </para>
 =

-        <example id=3D"hibernate-gsg-tutorial-basic-entity-entity">
+        <example id=3D"hibernate-gsg-tutorial-annotations-entity-entity">
             <title>Identifying the class as an entity</title>
             <programlisting role=3D"JAVA">@Entity
 @Table( name =3D "EVENTS" )
@@ -57,7 +57,7 @@
             <database class=3D"table">EVENT</database>).
         </para>
 =

-        <example id=3D"hibernate-gsg-tutorial-basic-entity-id">
+        <example id=3D"hibernate-gsg-tutorial-annotations-entity-id">
             <title>Identifying the identifier property</title>
             <programlisting role=3D"JAVA">@Id
 @GeneratedValue(generator=3D"increment")
@@ -75,7 +75,7 @@
             strategy for this entity's identifier values.
         </para>
 =

-        <example id=3D"hibernate-gsg-tutorial-basic-entity-properties">
+        <example id=3D"hibernate-gsg-tutorial-annotations-entity-propertie=
s">
             <title>Identifying basic properties</title>
             <programlisting role=3D"JAVA">public String getTitle() {
     return title;
@@ -112,14 +112,15 @@
         <itemizedlist>
             <listitem>
                 <para>
-                    With help of the Developer Guide, add an association t=
o the <classname>Event</classname>
-                    entity to model a message thread.
+                    With help of the <citetitle pubwork=3D"book">Developer=
 Guide</citetitle>, add an association to
+                    the <classname>Event</classname> entity to model a mes=
sage thread.
                 </para>
             </listitem>
             <listitem>
                 <para>
-                    With help of the Developer Guide, add a callback to re=
ceive notifications when an
-                    <classname>Event</classname> is created, updated or de=
leted.  Try the same with an event listener.
+                    With help of the <citetitle pubwork=3D"book">Developer=
 Guide</citetitle>, add a callback to
+                    receive notifications when an <classname>Event</classn=
ame> is created, updated or deleted.  Try =

+                    the same with an event listener.
                 </para>
             </listitem>
         </itemizedlist>

Added: core/trunk/documentation/quickstart/src/main/docbook/en-US/content/t=
utorial_jpa.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/trunk/documentation/quickstart/src/main/docbook/en-US/content/tuto=
rial_jpa.xml	                        (rev 0)
+++ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tuto=
rial_jpa.xml	2010-08-31 17:59:31 UTC (rev 20292)
@@ -0,0 +1,128 @@
+<?xml version=3D'1.0' encoding=3D'UTF-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.=
oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<chapter id=3D"hibernate-gsg-tutorial-jpa">
+    <title>Tutorial Using the <firstterm><phrase>Java Persistence API (JPA=
)</phrase></firstterm></title>
+
+    <para>
+        This tutorial is located within the download bundle under <filenam=
e>entitymanager</filename> and illustrates
+        <itemizedlist>
+            <listitem>
+                <para>
+                    using annotations to provide mapping information
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    using <phrase>JPA</phrase>
+                </para>
+            </listitem>
+        </itemizedlist>
+    </para>
+
+    <section id=3D"hibernate-gsg-tutorial-jpa-config">
+        <title><filename>persistence.xml</filename></title>
+
+        <para>
+            The previous tutorials used the Hibernate-specific
+            <filename><replaceable>hibernate.cfg.xml</replaceable></filena=
me> configuration file.  <phrase>JPA</phrase>,
+            however, defines a different <phrase>bootstrap</phrase> proces=
s that uses its own configuration file
+            named <filename>persistence.xml</filename>.  How this <phrase>=
bootstrapping</phrase> works is defined
+            by the <phrase>JPA</phrase> specification.  In <trademark>Java=
</trademark> SE environments the
+            persistence provider (Hibernate in this case) is required to l=
ocate all <phrase>JPA</phrase>
+            configuration files by classpath lookup of the <filename>META-=
INF/persistence.xml</filename> resource
+            name.
+        </para>
+
+        <example id=3D"hibernate-gsg-tutorial-jpa-config-pu">
+            <title><filename>persistence.xml</filename></title>
+            <programlisting role=3D"XML"><![CDATA[<persistence xmlns=3D"ht=
tp://java.sun.com/xml/ns/persistence"
+        xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation=3D"http://java.sun.com/xml/ns/persistence http:=
//java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
+        version=3D"2.0">
+    <persistence-unit name=3D"org.hibernate.tutorial.jpa">
+        ...
+    </persistence-unit>
+</persistence>]]></programlisting>
+        </example>
+
+        <para>
+            <filename>persistence.xml</filename> files should provide a un=
ique name for each
+            <phrase>persistence unit</phrase>.  This name is how applicati=
ons reference the configuration
+            while obtaining an <interfacename>javax.persistence.EntityMana=
gerFactory</interfacename> reference.
+        </para>
+
+        <para>
+            The settings defined in the <literal>properties</literal> elem=
ent were already discussed in
+            <xref linkend=3D"hibernate-gsg-tutorial-basic-config"/>.  Here=
 the <literal>javax.persistence</literal>-prefixed
+            varieties are used when possible.  For the remaining Hibernate=
-specific configuration setting names notice
+            that they are now prefixed with <literal>hibernate.</literal>.
+        </para>
+
+        <para>
+            Additionally, the <literal>class</literal> element functions t=
he same as discussed in
+            <xref linkend=3D"hibernate-gsg-tutorial-annotations-config"/>.
+        </para>
+    </section>
+
+    <section id=3D"hibernate-gsg-tutorial-jpa-entity">
+        <title>The annotated entity Java class</title>
+        <para>
+            The entity is exactly the same as that from the annotations tu=
torial.  See
+            <xref linkend=3D"hibernate-gsg-tutorial-annotations-entity"/>
+        </para>
+    </section>
+
+    <section id=3D"hibernate-gsg-tutorial-jpa-test">
+        <title>Example code</title>
+        <para>
+            The previous tutorials used the Hibernate APIs.  This tutorial=
 uses the <phrase>JPA</phrase> APIs.
+        </para>
+
+        <example id=3D"hibernate-gsg-tutorial-jpa-test-setUp">
+            <title>Obtaining the <interfacename>javax.persistence.EntityMa=
nagerFactory</interfacename></title>
+            <programlisting role=3D"JAVA">protected void setUp() throws Ex=
ception {
+    entityManagerFactory =3D Persistence.createEntityManagerFactory( "org.=
hibernate.tutorial.jpa" );
+}</programlisting>
+        </example>
+
+        <para>
+            Notice again the use of <literal>org.hibernate.tutorial.jpa</l=
iteral> as the
+            <phrase>persistence unit</phrase> name, which matches from <xr=
ef linkend=3D"hibernate-gsg-tutorial-jpa-config-pu"/>
+        </para>
+
+        <example id=3D"hibernate-gsg-tutorial-jpa-test-saving">
+            <title>Saving (persisting) entities</title>
+            <programlisting role=3D"JAVA">EntityManager entityManager =3D =
entityManagerFactory.createEntityManager();
+entityManager.getTransaction().begin();
+entityManager.persist( new Event( "Our very first event!", new Date() ) );
+entityManager.persist( new Event( "A follow up event", new Date() ) );
+entityManager.getTransaction().commit();
+entityManager.close();</programlisting>
+        </example>
+
+        <para>
+            The code is pretty similar to <xref linkend=3D"hibernate-gsg-t=
utorial-basic-test-saving"/>.  Here
+            we use an <interfacename>javax.persistence.EntityManager</inte=
rfacename> as opposed to a
+            <interfacename>org.hibernate.Session</interfacename>.  <phrase=
>JPA</phrase> calls this operation
+            <literal>persist</literal> instead of <literal>save</literal>.
+        </para>
+
+        <example id=3D"hibernate-gsg-tutorial-jpa-test-list">
+            <title>Obtaining a list of entities</title>
+            <programlisting role=3D"JAVA"><![CDATA[entityManager =3D entit=
yManagerFactory.createEntityManager();
+entityManager.getTransaction().begin();
+List<Event> result =3D entityManager.createQuery( "from Event", Event.clas=
s ).getResultList();
+for ( Event event : result ) {
+    System.out.println( "Event (" + event.getDate() + ") : " + event.getTi=
tle() );
+}
+entityManager.getTransaction().commit();
+entityManager.close();]]></programlisting>
+        </example>
+
+        <para>
+            Again, the code is pretty similar to <xref linkend=3D"hibernat=
e-gsg-tutorial-basic-test-list"/>.
+        </para>
+    </section>
+
+</chapter>
\ No newline at end of file

Modified: core/trunk/documentation/quickstart/src/main/docbook/en-US/conten=
t/tutorial_native.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/trunk/documentation/quickstart/src/main/docbook/en-US/content/tuto=
rial_native.xml	2010-08-31 16:05:27 UTC (rev 20291)
+++ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tuto=
rial_native.xml	2010-08-31 17:59:31 UTC (rev 20292)
@@ -320,8 +320,8 @@
             </listitem>
             <listitem>
                 <para>
-                    With help of the Developer Guide, add an association t=
o the <classname>Event</classname>
-                    entity to model a message thread.
+                    With help of the <citetitle pubwork=3D"book">Developer=
 Guide</citetitle>, add an association to
+                    the <classname>Event</classname> entity to model a mes=
sage thread.
                 </para>
             </listitem>
         </itemizedlist>

Modified: core/trunk/documentation/quickstart/tutorials/entitymanager/src/t=
est/java/org/hibernate/tutorial/em/EntityManagerIllustrationTest.java
=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/trunk/documentation/quickstart/tutorials/entitymanager/src/test/ja=
va/org/hibernate/tutorial/em/EntityManagerIllustrationTest.java	2010-08-31 =
16:05:27 UTC (rev 20291)
+++ core/trunk/documentation/quickstart/tutorials/entitymanager/src/test/ja=
va/org/hibernate/tutorial/em/EntityManagerIllustrationTest.java	2010-08-31 =
17:59:31 UTC (rev 20292)
@@ -42,7 +42,8 @@
 	@Override
 	protected void setUp() throws Exception {
 		// like discussed with regards to SessionFactory, an EntityManagerFactor=
y is set up once for an application
-		entityManagerFactory =3D Persistence.createEntityManagerFactory( "hibern=
ate-jpa-tutorial" );
+		// 		IMPORTANT: notice how the name here matches the name we gave the pe=
rsistence-unit in persistence.xml!
+		entityManagerFactory =3D Persistence.createEntityManagerFactory( "org.hi=
bernate.tutorial.jpa" );
 	}
 =

 	@Override

Modified: core/trunk/documentation/quickstart/tutorials/entitymanager/src/t=
est/resources/META-INF/persistence.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/trunk/documentation/quickstart/tutorials/entitymanager/src/test/re=
sources/META-INF/persistence.xml	2010-08-31 16:05:27 UTC (rev 20291)
+++ core/trunk/documentation/quickstart/tutorials/entitymanager/src/test/re=
sources/META-INF/persistence.xml	2010-08-31 17:59:31 UTC (rev 20292)
@@ -26,7 +26,7 @@
              xsi:schemaLocation=3D"http://java.sun.com/xml/ns/persistence =
http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
              version=3D"2.0">
 =

-    <persistence-unit name=3D"hibernate-jpa-tutorial">
+    <persistence-unit name=3D"org.hibernate.tutorial.jpa">
         <description>
             Persistence unit for the JPA tutorial of the Hibernate Getting=
 Started Guide
         </description>


--===============8329380371290274033==--