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

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

@ -5,33 +5,33 @@
<title>Tutorial Using the <firstterm><phrase>Java Persistence API (JPA)</phrase></firstterm></title> <title>Tutorial Using the <firstterm><phrase>Java Persistence API (JPA)</phrase></firstterm></title>
<para> <para>
This tutorial is located within the download bundle under <filename>entitymanager</filename> and illustrates This tutorial is located within the download bundle under <filename>entitymanager</filename>.
</para>
<itemizedlist> <itemizedlist>
<title>Objectives</title>
<listitem> <listitem>
<para> <para>
using annotations to provide mapping information Use annotations to provide mapping information.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
using <phrase>JPA</phrase> Use <systemitem>JPA</systemitem>.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para>
<section id="hibernate-gsg-tutorial-jpa-config"> <section id="hibernate-gsg-tutorial-jpa-config">
<title><filename>persistence.xml</filename></title> <title><filename>persistence.xml</filename></title>
<para> <para>
The previous tutorials used the Hibernate-specific The previous tutorials used the Hibernate-specific
<filename><replaceable>hibernate.cfg.xml</replaceable></filename> configuration file. <phrase>JPA</phrase>, <filename><replaceable>hibernate.cfg.xml</replaceable></filename> configuration file.
however, defines a different <phrase>bootstrap</phrase> process that uses its own configuration file <systemitem>JPA</systemitem>, however, defines a different bootstrap process that uses its own configuration
named <filename>persistence.xml</filename>. How this <phrase>bootstrapping</phrase> works is defined file named <filename>persistence.xml</filename>. This bootstrapping process is defined by the
by the <phrase>JPA</phrase> specification. In <trademark>Java</trademark> SE environments the <systemitem>JPA</systemitem> specification. In <trademark>Java</trademark> SE environments the persistence
persistence provider (Hibernate in this case) is required to locate all <phrase>JPA</phrase> provider (Hibernate in this case) is required to locate all <systemitem>JPA</systemitem> configuration files
configuration files by classpath lookup of the <filename>META-INF/persistence.xml</filename> resource by classpath lookup of the <filename>META-INF/persistence.xml</filename> resource name.
name.
</para> </para>
<example id="hibernate-gsg-tutorial-jpa-config-pu"> <example id="hibernate-gsg-tutorial-jpa-config-pu">
@ -47,36 +47,35 @@
</example> </example>
<para> <para>
<filename>persistence.xml</filename> files should provide a unique name for each <filename>persistence.xml</filename> files should provide a unique name for each <phrase>persistence
<phrase>persistence unit</phrase>. This name is how applications reference the configuration unit</phrase>. Applications use this name to reference the configuration when obtaining an
while obtaining an <interfacename>javax.persistence.EntityManagerFactory</interfacename> reference. <interfacename>javax.persistence.EntityManagerFactory</interfacename> reference.
</para> </para>
<para> <para>
The settings defined in the <literal>properties</literal> element were already discussed in The settings defined in the <varname>properties</varname> element are discussed in <xref
<xref linkend="hibernate-gsg-tutorial-basic-config"/>. Here the <literal>javax.persistence</literal>-prefixed 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 varieties are used when possible. Notice that the remaining Hibernate-specific configuration setting names
that they are now prefixed with <literal>hibernate.</literal>. are now prefixed with <literal>hibernate.</literal>.
</para> </para>
<para> <para>
Additionally, the <literal>class</literal> element functions the same as discussed in Additionally, the <varname>class</varname> element functions the same as in <xref
<xref linkend="hibernate-gsg-tutorial-annotations-config"/>. linkend="hibernate-gsg-tutorial-annotations-config"/>.
</para> </para>
</section> </section>
<section id="hibernate-gsg-tutorial-jpa-entity"> <section id="hibernate-gsg-tutorial-jpa-entity">
<title>The annotated entity Java class</title> <title>The annotated entity Java class</title>
<para> <para>
The entity is exactly the same as that from the annotations tutorial. See The entity is exactly the same as in <xref linkend="hibernate-gsg-tutorial-annotations-entity"/>
<xref linkend="hibernate-gsg-tutorial-annotations-entity"/>
</para> </para>
</section> </section>
<section id="hibernate-gsg-tutorial-jpa-test"> <section id="hibernate-gsg-tutorial-jpa-test">
<title>Example code</title> <title>Example code</title>
<para> <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> </para>
<example id="hibernate-gsg-tutorial-jpa-test-setUp"> <example id="hibernate-gsg-tutorial-jpa-test-setUp">
@ -87,8 +86,8 @@
</example> </example>
<para> <para>
Notice again the use of <literal>org.hibernate.tutorial.jpa</literal> as the Notice again that the persistence unit name is <literal>org.hibernate.tutorial.jpa</literal>, which matches
<phrase>persistence unit</phrase> name, which matches from <xref linkend="hibernate-gsg-tutorial-jpa-config-pu"/> <xref linkend="hibernate-gsg-tutorial-jpa-config-pu"/>
</para> </para>
<example id="hibernate-gsg-tutorial-jpa-test-saving"> <example id="hibernate-gsg-tutorial-jpa-test-saving">
@ -102,10 +101,10 @@ entityManager.close();</programlisting>
</example> </example>
<para> <para>
The code is pretty similar to <xref linkend="hibernate-gsg-tutorial-basic-test-saving"/>. Here The code is similar to <xref linkend="hibernate-gsg-tutorial-basic-test-saving"/>. An
we use an <interfacename>javax.persistence.EntityManager</interfacename> as opposed to a <interfacename>javax.persistence.EntityManager</interfacename> interface is used instead of a
<interfacename>org.hibernate.Session</interfacename>. <phrase>JPA</phrase> calls this operation <interfacename>org.hibernate.Session</interfacename> interface. <systemitem>JPA</systemitem> calls this
<literal>persist</literal> instead of <literal>save</literal>. operation <methodname>persist</methodname> instead of <methodname>save</methodname>.
</para> </para>
<example id="hibernate-gsg-tutorial-jpa-test-list"> <example id="hibernate-gsg-tutorial-jpa-test-list">
@ -125,4 +124,21 @@ entityManager.close();]]></programlisting>
</para> </para>
</section> </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> </chapter>