Providing a complete persistence.xml rather than just a fragment.

Providing additional Maven dependencies

Doc/Persist/topics.xml

@@ -103,35 +103,6 @@
                   <quote>Airline</quote>.</para>
                 </listitem>
 
-                <listitem>
-                  <para><link
-                  xlink:href="http://techbus.safaribooksonline.com/book/programming/java/9781617290459/part-1dot-getting-started-with-orm/kindle_split_013_html">Chapter
-                  2</link> of <xref linkend="bib_Bauer15"/> provides hints
-                  starting a project. Rather than using the described more
-                  elaborate <xref linkend="glo_JTA"/> based setup you may just
-                  want to follow a simpler <xref linkend="glo_JDBC"/> based
-                  approach when defining a persistence unit in your project's
-                  <filename>src/main/resources/META-INF/persistence.xml</filename>
-                  file:</para>
-
-                  <programlisting language="xml">&lt;persistence... &gt;
-    &lt;persistence-unit name="AirlinePU"&gt;
-   ...
-        &lt;class&gt;de.hdm_stuttgart.mi.persist.airline.model.Airline&lt;/class&gt;
-        &lt;properties&gt;
-            &lt;!--  JDBC database connection parameter (MI local MySQL installation) --&gt;
-            &lt;property name="javax.persistence.jdbc.driver" value="com.mysql.jdbc.Driver"/&gt;
-            &lt;property name="javax.persistence.jdbc.url" value="jdbc:mysql://localhost:3306/hdm"/&gt;
-            &lt;property name="javax.persistence.jdbc.user" value="hdmuser"/&gt;
-            &lt;property name="javax.persistence.jdbc.password" value="XYZ"/&gt;
-         ...            
-
-        &lt;/properties&gt;
-    &lt;/persistence-unit&gt;
-    ...
-&lt;/persistence&gt;</programlisting>
-                </listitem>
-
                 <listitem>
                   <para>Create an <classname>Airline</classname> <classname
                   xlink:href="http://docs.oracle.com/javaee/7/api/javax/persistence/Entity.html">@Entity</classname>
@@ -158,10 +129,93 @@ public class Airline {
    protected Airline(){}   
 }</programlisting>
 
+                  <para>The three imports require additional libraries to be
+                  present. Using Maven this may be achieved by adding the
+                  following dependency to your project's
+                  <filename>pom.xml</filename> file:</para>
+
+                  <programlisting language="xml">&lt;dependency&gt;
+  &lt;groupId&gt;org.hibernate&lt;/groupId&gt;
+  &lt;artifactId&gt;hibernate-entitymanager&lt;/artifactId&gt;
+  &lt;version&gt;5.1.0.Final&lt;/version&gt;
+&lt;/dependency&gt;</programlisting>
+
                   <para>Why do we need <code>protected Airline(){}</code>
                   ?</para>
                 </listitem>
 
+                <listitem>
+                  <para><link
+                  xlink:href="http://techbus.safaribooksonline.com/book/programming/java/9781617290459/part-1dot-getting-started-with-orm/kindle_split_013_html">Chapter
+                  2</link> of <xref linkend="bib_Bauer15"/> provides hints
+                  starting a project. Rather than using the described more
+                  elaborate <xref linkend="glo_JTA"/> based setup you may just
+                  want to follow a simpler <xref linkend="glo_JDBC"/> based
+                  approach when defining a persistence unit in your project's
+                  <filename>src/main/resources/META-INF/persistence.xml</filename>
+                  file:</para>
+
+                  <programlisting language="xml">&lt;persistence
+    version="2.1"
+    xmlns="http://xmlns.jcp.org/xml/ns/persistence"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence 
+    http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/persistence/persistence_2_1.xsd"&gt;
+
+    &lt;!-- 
+         The &lt;code&gt;persistence.xml&lt;/code&gt; file configures at least one persistence unit;
+         each unit must have a unique name.
+    --&gt;
+    &lt;persistence-unit name="AirlinePU"&gt;
+
+        &lt;!-- A persistent unit has persistent (mapped) classes, you list them here. --&gt;
+        &lt;class&gt;de.hdm_stuttgart.mi.persist.airline.model.Airline&lt;/class&gt;
+
+        &lt;!-- Hibernate can scan your classpath for mapped classes and add them automatically
+             to your persistence unit. This setting disables that feature. --&gt;
+        &lt;exclude-unlisted-classes&gt;true&lt;/exclude-unlisted-classes&gt;
+
+        &lt;!-- Standard or vendor-specific options can be set as properties on a persistence unit.
+             Any standard properties have the &lt;code&gt;javax.persistence&lt;/code&gt; name prefix, Hibernate's
+             settings use &lt;code&gt;hibernate&lt;/code&gt; --&gt;
+        &lt;properties&gt;
+            &lt;!-- JDBC database connection parameter --&gt;
+            &lt;property name="javax.persistence.jdbc.driver" value="com.mysql.jdbc.Driver"/&gt;
+            &lt;property name="javax.persistence.jdbc.url" value="jdbc:mysql://localhost:3306/hdm"/&gt;
+            &lt;property name="javax.persistence.jdbc.user" value="hdmuser"/&gt;
+            &lt;property name="javax.persistence.jdbc.password" value="XYZ"/&gt;
+
+            &lt;!-- The JPA engine should drop and re-create the SQL schema in the database
+                 automatically when it boots. This is ideal for automated testing, when
+                 you want to work with a clean database for every test run. --&gt;
+            &lt;property
+                name="javax.persistence.schema-generation.database.action"
+                value="drop-and-create"/&gt;
+
+            &lt;!-- When printing SQL in logs, let Hibernate format the SQL nicely and generate
+                 comments into the SQL string so we know why Hibernate executed the SQL statement. --&gt;
+            &lt;property name="hibernate.format_sql" value="true"/&gt;
+            &lt;property name="hibernate.use_sql_comments" value="true"/&gt;
+
+            &lt;!-- Disable Hibernate scanning completely, we also don't want any hbm.xml files
+                 discovered and added automatically. --&gt;
+            &lt;property name="hibernate.archive.autodetection" value="none"/&gt;
+
+        &lt;/properties&gt;
+    &lt;/persistence-unit&gt;
+&lt;/persistence&gt;</programlisting>
+
+                  <para>Our persistence unit connecting to a <xref
+                  linkend="glo_Soft_Mysql"/> database server requires another
+                  Maven dependency:</para>
+
+                  <programlisting language="xml">&lt;dependency&gt;
+  &lt;groupId&gt;mysql&lt;/groupId&gt;
+  &lt;artifactId&gt;mysql-connector-java&lt;/artifactId&gt;
+  &lt;version&gt;5.1.38&lt;/version&gt;
+&lt;/dependency&gt;</programlisting>
+                </listitem>
+
                 <listitem>
                   <para>Our <methodname>main()</methodname> class will just
                   write a single <classname>Airline</classname> instance to
@@ -250,9 +304,9 @@ mysql&gt; show create table hibernate_sequence;
 )</programlisting>
 
               <para>On object creation the <xref linkend="glo_JPA"/> provider
-              will use <code>hibernate_sequence</code> to generate
-              <code>id</code> values. Thus the <xref
-              linkend="glo_Soft_Mysql"/> <link
+              will use the additional <code>hibernate_sequence</code> table
+              for generating <code>id</code> values. Thus <xref
+              linkend="glo_Soft_Mysql"/>'s <link
               xlink:href="http://dev.mysql.com/doc/refman/5.7/en/example-auto-increment.html">AUTO_INCREMENT</link>
               feature is not yet being used.</para>
             </answer>
@@ -269,8 +323,8 @@ mysql&gt; show create table hibernate_sequence;
         <qandadiv>
           <qandaentry>
             <question>
-              <para>Modify the current class <classname>Airline</classname>
-              to: like:</para>
+              <para>Modify the current <classname>Airline</classname>
+              class:</para>
 
               <orderedlist>
                 <listitem>
@@ -445,12 +499,12 @@ public class Airline {
                       <listitem>
                         <para>Stable approach with respect to <xref
                         linkend="glo_Java"/> code refactoring: If e.g. the
-                        property <property>icaoCode</property> gets
+                        <property>icaoCode</property> property gets
                         consistently renamed to
                         <property>icaoCode</property>Number <xref
-                        linkend="glo_SqlDdl"/> code will still be properly
-                        generated. However this problem may be overcome for
-                        our complex solution by providing stable <xref
+                        linkend="glo_SqlDdl"/> code will still be generated
+                        properly. However our complex solution may overcome
+                        this problem by providing stable <xref
                         linkend="glo_SqlDdl"/> attribute names via
                         <code>@Column(name="icaoCode" ...)</code> thereby
                         protecting the database from unnecessary schema