Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Edited the JPA chapter.

This commit is contained in:
mstanleyjones 2010-10-13 14:12:31 +10:00
parent 5d6317e715
commit e34e464103
1 changed files with 63 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
documentation/quickstart/src/main/docbook/en-US/content/tutorial_jpa.xml
View File

@ -5,38 +5,38 @@
<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>
This tutorial is located within the download bundle under <filename>entitymanager</filename>.
</para>
<itemizedlist>
<title>Objectives</title>
<listitem>
<para>
Use annotations to provide mapping information.
</para>
</listitem>
<listitem>
<para>
Use <systemitem>JPA</systemitem>.
</para>
</listitem>
</itemizedlist>
<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.
<filename><replaceable>hibernate.cfg.xml</replaceable></filename> configuration file.
<systemitem>JPA</systemitem>, however, defines a different bootstrap process that uses its own configuration
file named <filename>persistence.xml</filename>. This bootstrapping process is defined by the
<systemitem>JPA</systemitem> specification. In <trademark>Java</trademark> SE environments the persistence
provider (Hibernate in this case) is required to locate all <systemitem>JPA</systemitem> 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"
<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">
@ -47,53 +47,52 @@
</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.
<filename>persistence.xml</filename> files should provide a unique name for each <phrase>persistence
unit</phrase>. Applications use this name to reference the configuration when 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>.
The settings defined in the <varname>properties</varname> element are discussed in <xref
linkend="hibernate-gsg-tutorial-basic-config"/>. Here the <literal>javax.persistence</literal>-prefixed
varieties are used when possible. Notice that the remaining Hibernate-specific configuration setting names
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"/>.
Additionally, the <varname>class</varname> element functions the same as 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"/>
The entity is exactly the same as in <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.
The previous tutorials used the Hibernate APIs. This tutorial uses the <systemitem>JPA</systemitem> 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 {
<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"/>
Notice again that the persistence unit name is <literal>org.hibernate.tutorial.jpa</literal>, which matches
<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();
<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() ) );
@ -102,15 +101,15 @@ 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>.
The code is similar to <xref linkend="hibernate-gsg-tutorial-basic-test-saving"/>. An
<interfacename>javax.persistence.EntityManager</interfacename> interface is used instead of a
<interfacename>org.hibernate.Session</interfacename> interface. <systemitem>JPA</systemitem> calls this
operation <methodname>persist</methodname> instead of <methodname>save</methodname>.
</para>
<example id="hibernate-gsg-tutorial-jpa-test-list">
<title>Obtaining a list of entities</title>
<programlisting role="JAVA"><![CDATA[entityManager = entityManagerFactory.createEntityManager();
<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 ) {
@ -121,8 +120,25 @@ entityManager.close();]]></programlisting>
</example>
<para>
Again, the code is pretty similar to <xref linkend="hibernate-gsg-tutorial-basic-test-list"/>.
Again, the code is pretty similar to <xref linkend="hibernate-gsg-tutorial-basic-test-list"/>.
</para>
</section>
<section id="hibernate-gsg-tutorial-annotations-further">
<title>Take it further!</title>
<itemizedlist>
<title>Practice Exercises</title>
<listitem>
<para>
</para>
</listitem>
<listitem>
<para>
</para>
</listitem>
</itemizedlist>
</section>
</chapter>