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>