1:59 p.m.
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/tutorial_jpa.xml
Modified:
core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml
core/trunk/documentation/quickstart/tutorials/entitymanager/src/test/java/org/hibernate/tutorial/em/EntityManagerIllustrationTest.java
core/trunk/documentation/quickstart/tutorials/entitymanager/src/test/resources/META-INF/persistence.xml
Log:
HHH-5445 - Write a jpa/entitymanager tutorial guide
Modified:
core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml
===================================================================
---
core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml 2010-08-31
16:05:27 UTC (rev 20291)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml 2010-08-31
17:59:31 UTC (rev 20292)
@@ -31,6 +31,7 @@
</partintro>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
href="content/tutorial_native.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
href="content/tutorial_annotations.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
href="content/tutorial_jpa.xml" />
</part>
</book>
\ No newline at end of file
Modified:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml
===================================================================
---
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml 2010-08-31
16:05:27 UTC (rev 20291)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml 2010-08-31
17:59:31 UTC (rev 20292)
@@ -30,7 +30,7 @@
</para>
</section>
- <section id="hibernate-gsg-tutorial-basic-entity">
+ <section id="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
<filename>hbm.xml</filename> file.
</para>
- <example id="hibernate-gsg-tutorial-basic-entity-entity">
+ <example id="hibernate-gsg-tutorial-annotations-entity-entity">
<title>Identifying the class as an entity</title>
<programlisting role="JAVA">@Entity
@Table( name = "EVENTS" )
@@ -57,7 +57,7 @@
<database class="table">EVENT</database>).
</para>
- <example id="hibernate-gsg-tutorial-basic-entity-id">
+ <example id="hibernate-gsg-tutorial-annotations-entity-id">
<title>Identifying the identifier property</title>
<programlisting role="JAVA">@Id
@GeneratedValue(generator="increment")
@@ -75,7 +75,7 @@
strategy for this entity's identifier values.
</para>
- <example id="hibernate-gsg-tutorial-basic-entity-properties">
+ <example
id="hibernate-gsg-tutorial-annotations-entity-properties">
<title>Identifying basic properties</title>
<programlisting role="JAVA">public String getTitle() {
return title;
@@ -112,14 +112,15 @@
<itemizedlist>
<listitem>
<para>
- With help of the Developer Guide, add an association to the
<classname>Event</classname>
- entity to model a message thread.
+ With help of the <citetitle pubwork="book">Developer
Guide</citetitle>, add an association to
+ the <classname>Event</classname> entity to model a
message thread.
</para>
</listitem>
<listitem>
<para>
- With help of the Developer Guide, add a callback to receive
notifications when an
- <classname>Event</classname> is created, updated or
deleted. Try the same with an event listener.
+ With help of the <citetitle pubwork="book">Developer
Guide</citetitle>, add a callback to
+ receive notifications when an
<classname>Event</classname> 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/tutorial_jpa.xml
===================================================================
--- core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_jpa.xml
(rev 0)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_jpa.xml 2010-08-31
17:59:31 UTC (rev 20292)
@@ -0,0 +1,128 @@
+<?xml version='1.0' encoding='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="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
<filename>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="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></filename>
configuration file. <phrase>JPA</phrase>,
+ however, defines a different <phrase>bootstrap</phrase> process
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 locate all
<phrase>JPA</phrase>
+ configuration files by classpath lookup of the
<filename>META-INF/persistence.xml</filename> resource
+ name.
+ </para>
+
+ <example id="hibernate-gsg-tutorial-jpa-config-pu">
+ <title><filename>persistence.xml</filename></title>
+ <programlisting role="XML"><![CDATA[<persistence
xmlns="http://java.sun.com/xml/ns/persistence"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/persistence
http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
+ version="2.0">
+ <persistence-unit name="org.hibernate.tutorial.jpa">
+ ...
+ </persistence-unit>
+</persistence>]]></programlisting>
+ </example>
+
+ <para>
+ <filename>persistence.xml</filename> files should provide a
unique name for each
+ <phrase>persistence unit</phrase>. This name is how applications
reference the configuration
+ while obtaining an
<interfacename>javax.persistence.EntityManagerFactory</interfacename>
reference.
+ </para>
+
+ <para>
+ The settings defined in the <literal>properties</literal> element
were already discussed in
+ <xref linkend="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 the
same as discussed in
+ <xref linkend="hibernate-gsg-tutorial-annotations-config"/>.
+ </para>
+ </section>
+
+ <section id="hibernate-gsg-tutorial-jpa-entity">
+ <title>The annotated entity Java class</title>
+ <para>
+ The entity is exactly the same as that from the annotations tutorial. See
+ <xref linkend="hibernate-gsg-tutorial-annotations-entity"/>
+ </para>
+ </section>
+
+ <section id="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="hibernate-gsg-tutorial-jpa-test-setUp">
+ <title>Obtaining the
<interfacename>javax.persistence.EntityManagerFactory</interfacename></title>
+ <programlisting role="JAVA">protected void setUp() throws
Exception {
+ entityManagerFactory = Persistence.createEntityManagerFactory(
"org.hibernate.tutorial.jpa" );
+}</programlisting>
+ </example>
+
+ <para>
+ Notice again the use of
<literal>org.hibernate.tutorial.jpa</literal> as the
+ <phrase>persistence unit</phrase> name, which matches from
<xref linkend="hibernate-gsg-tutorial-jpa-config-pu"/>
+ </para>
+
+ <example id="hibernate-gsg-tutorial-jpa-test-saving">
+ <title>Saving (persisting) entities</title>
+ <programlisting role="JAVA">EntityManager entityManager =
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="hibernate-gsg-tutorial-basic-test-saving"/>. Here
+ we use an
<interfacename>javax.persistence.EntityManager</interfacename> 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="hibernate-gsg-tutorial-jpa-test-list">
+ <title>Obtaining a list of entities</title>
+ <programlisting role="JAVA"><![CDATA[entityManager =
entityManagerFactory.createEntityManager();
+entityManager.getTransaction().begin();
+List<Event> result = entityManager.createQuery( "from Event", Event.class
).getResultList();
+for ( Event event : result ) {
+ System.out.println( "Event (" + event.getDate() + ") : " +
event.getTitle() );
+}
+entityManager.getTransaction().commit();
+entityManager.close();]]></programlisting>
+ </example>
+
+ <para>
+ Again, the code is pretty similar to <xref
linkend="hibernate-gsg-tutorial-basic-test-list"/>.
+ </para>
+ </section>
+
+</chapter>
\ No newline at end of file
Modified:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml
===================================================================
---
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml 2010-08-31
16:05:27 UTC (rev 20291)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_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 to the
<classname>Event</classname>
- entity to model a message thread.
+ With help of the <citetitle pubwork="book">Developer
Guide</citetitle>, add an association to
+ the <classname>Event</classname> entity to model a
message thread.
</para>
</listitem>
</itemizedlist>
Modified:
core/trunk/documentation/quickstart/tutorials/entitymanager/src/test/java/org/hibernate/tutorial/em/EntityManagerIllustrationTest.java
===================================================================
---
core/trunk/documentation/quickstart/tutorials/entitymanager/src/test/java/org/hibernate/tutorial/em/EntityManagerIllustrationTest.java 2010-08-31
16:05:27 UTC (rev 20291)
+++
core/trunk/documentation/quickstart/tutorials/entitymanager/src/test/java/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 EntityManagerFactory is set up
once for an application
- entityManagerFactory = Persistence.createEntityManagerFactory(
"hibernate-jpa-tutorial" );
+ // IMPORTANT: notice how the name here matches the name we gave the persistence-unit
in persistence.xml!
+ entityManagerFactory = Persistence.createEntityManagerFactory(
"org.hibernate.tutorial.jpa" );
}
@Override
Modified:
core/trunk/documentation/quickstart/tutorials/entitymanager/src/test/resources/META-INF/persistence.xml
===================================================================
---
core/trunk/documentation/quickstart/tutorials/entitymanager/src/test/resources/META-INF/persistence.xml 2010-08-31
16:05:27 UTC (rev 20291)
+++
core/trunk/documentation/quickstart/tutorials/entitymanager/src/test/resources/META-INF/persistence.xml 2010-08-31
17:59:31 UTC (rev 20292)
@@ -26,7 +26,7 @@
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence
http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
version="2.0">
- <persistence-unit name="hibernate-jpa-tutorial">
+ <persistence-unit name="org.hibernate.tutorial.jpa">
<description>
Persistence unit for the JPA tutorial of the Hibernate Getting Started Guide
</description>