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>
<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>
<title>Objectives</title>
<listitem>
<para>
using annotations to provide mapping information
Use annotations to provide mapping information.
</para>
</listitem>
<listitem>
<para>
using <phrase>JPA</phrase>
Use <systemitem>JPA</systemitem>.
</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.
<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">
@ -47,36 +47,35 @@
</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">
@ -87,8 +86,8 @@
</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">
@ -102,10 +101,10 @@ 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">
@ -125,4 +124,21 @@ entityManager.close();]]></programlisting>
</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>