HHH-5444 - Write annotations tutorial chapter

git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@20255 1b8cb986-b30d-0410-93ca-fae66ebed9b2

documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/org/hibernate/tutorial/annotations/EventManager.java

@@ -0,0 +1,87 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * Copyright (c) 2010, Red Hat Inc. or third-party contributors as
+ * indicated by the @author tags or express copyright attribution
+ * statements applied by the authors.  All third-party contributions are
+ * distributed under license by Red Hat Inc.
+ *
+ * This copyrighted material is made available to anyone wishing to use, modify,
+ * copy, or redistribute it subject to the terms and conditions of the GNU
+ * Lesser General Public License, as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this distribution; if not, write to:
+ * Free Software Foundation, Inc.
+ * 51 Franklin Street, Fifth Floor
+ * Boston, MA  02110-1301  USA
+ */
+package org.hibernate.tutorial.annotations;
+
+import org.hibernate.cfg.Configuration;
+import org.hibernate.Session;
+import org.hibernate.SessionFactory;
+
+import java.util.Date;
+import java.util.List;
+
+public class EventManager {
+    private final SessionFactory sessionFactory;
+
+    public static void main(String[] args) {
+        EventManager eventManager = new EventManager();
+
+        if ( args[0].equals( "store" ) ) {
+            eventManager.createAndStoreEvent( "My Event", new Date() );
+        }
+        else if (args[0].equals("list")) {
+            List events = eventManager.listEvents();
+            for (int i = 0; i < events.size(); i++) {
+                Event theEvent = (Event) events.get(i);
+                System.out.println(
+                        "Event: " + theEvent.getTitle()
+                            + " Time: " + theEvent.getDate()
+                );
+            }
+        }
+
+        eventManager.release();
+    }
+
+    public EventManager() {
+        sessionFactory = new Configuration()
+                .configure() // configures settings from hibernate.cfg.xml
+                .buildSessionFactory();
+    }
+
+    public void release() {
+        sessionFactory.close();
+    }
+
+    private void createAndStoreEvent(String title, Date theDate) {
+        Session session = sessionFactory.openSession();
+        session.beginTransaction();
+
+        Event theEvent = new Event();
+        theEvent.setTitle( title );
+        theEvent.setDate( theDate );
+        session.save( theEvent );
+
+        session.getTransaction().commit();
+        session.close();
+    }
+
+    private List listEvents() {
+        Session session = sessionFactory.openSession();
+        session.beginTransaction();
+        List result = session.createQuery("from Event").list();
+        session.getTransaction().commit();
+        session.close();
+        return result;
+    }
+}

documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml

@@ -11,12 +11,10 @@
             <title>Create the Maven POM file</title>
             <para>
                 Create a file named <filename>pom.xml</filename> in the root of your project directory, containing
-                the text in<xref linkend="hibernate-gsg-tutorial-annotations-pom-ex1"/>.
+                the text in <xref linkend="hibernate-gsg-tutorial-annotations-pom-ex1"/>.
             </para>
             <example id="hibernate-gsg-tutorial-annotations-pom-ex1">
-                <title>
+                <title><filename>pom.xml</filename></title>
-                    <filename>pom.xml</filename>
-                </title>
                 <programlisting role="XML"><xi:include href="extras/examples/annotations/pom.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
             </example>
         </step>
@@ -25,14 +23,12 @@
             <title>Create the annotated entity Java class</title>
 
             <para>
-                Create a file named<filename>src/main/java/org/hibernate/tutorial/annotations/Event.java</filename>,
+                Create a file named <filename>src/main/java/org/hibernate/tutorial/annotations/Event.java</filename>,
-                containing the text in<xref linkend="hibernate-gsg-tutorial-annotations-entity-ex1"/>.
+                containing the text in <xref linkend="hibernate-gsg-tutorial-annotations-entity-ex1"/>.
             </para>
 
             <example id="hibernate-gsg-tutorial-annotations-entity-ex1">
-                <title>
+                <title><filename>Entity.java</filename></title>
-                    <filename>Entity.java</filename>
-                </title>
                 <programlisting role="JAVA"><xi:include href="extras/examples/annotations/org/hibernate/tutorial/annotations/Event.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
             </example>
             <para>
@@ -52,7 +48,8 @@
                             class as an entity.  It's function is essentially the same as the <literal>class</literal>
                             mapping element we see in <xref linkend="hibernate-gsg-tutorial-native-hbm-xml-ex1"/>.
                             Additionally the <interfacename>@javax.persistence.Table</interfacename> annotation is
-                            used to override the default table name annotations would have used (<literal>EVENT</literal>).
+                            used to explicitly specify the table name (the default table name would have been
+                            <database class="table">EVENT</database>).
                         </para>
                     </listitem>
                     <listitem>
@@ -60,14 +57,6 @@
                             <interfacename>@javax.persistence.Id</interfacename> marks the property defining the
                             entity's identifier.
                         </para>
-                        <note>
-                            <para>
-                                Property-related annotations are allowed on either the field or the getter method.
-                                However, for a given entity they cannot be mixed.  The placement of the
-                                <interfacename>@javax.persistence.Id</interfacename> indicates where Hibernate
-                                should expect to find other property-related annotations.
-                            </para>
-                        </note>
                     </listitem>
                     <!-- todo : example of defining the generator -->
                     <listitem>
@@ -100,9 +89,57 @@
             </para>
         </step>
 
-        <!-- the rest of the tutorial "here on out" is the same as from the native + hbm.xml -->
+        <step id="hibernate-gsg-tutorial-annotations-working">
-        <!-- todo : is it enough to say that? -->
+            <title>Do stuff</title>
+            <para>
+                Create a file named <filename>src/main/java/org/hibernate/tutorial/annotations/EventManager.java</filename>
+                containing the text in <xref linkend="hibernate-gsg-tutorial-native-working-ex1"/>.
+            </para>
+
+            <example id="hibernate-gsg-tutorial-native-working-ex1">
+                <title>
+                    <filename>EventManager.java</filename>
+                </title>
+                <programlisting role="JAVA"><xi:include href="extras/examples/annotations/org/hibernate/tutorial/annotations/EventManager.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
+            </example>
+
+            <para>
+                Refer back to <xref linkend="hibernate-gsg-tutorial-native-working"/> for a discussion
+            </para>
+        </step>
+
+        <step id="hibernate-gsg-tutorial-annotations-compileAndRun">
+            <title>Compile and run the code</title>
+
+            <para>
+                Follow the directions at <xref linkend="hibernate-gsg-tutorial-native-compile"/> and
+                <xref linkend="hibernate-gsg-tutorial-native-running"/> to compile and then run the code.  Be sure
+                to reference the <classname>org.hibernate.tutorial.annotations.EventManager</classname> class
+                instead of the <classname>org.hibernate.tutorial.hbm.EventManager</classname> class.
+            </para>
+        </step>
 
     </procedure>
 
+    <section id="hibernate-gsg-tutorial-annotations-further">
+        <title>Take it further!</title>
+        <para>
+            Try the following exercises:
+        </para>
+        <itemizedlist>
+            <listitem>
+                <para>
+                    With help of the Developer Guide, 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.
+                </para>
+            </listitem>
+        </itemizedlist>
+    </section>
+
 </chapter>

documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml

@@ -233,7 +233,7 @@
             <title>Do stuff</title>
             <para>
                 Create a file named <filename>src/main/java/org/hibernate/tutorial/hbm/EventManager.java</filename>
-                with the following contents:
+                containing the text in <xref linkend="hibernate-gsg-tutorial-native-working-ex1"/>.
             </para>
 
             <example id="hibernate-gsg-tutorial-native-working-ex1">
@@ -283,10 +283,10 @@
         </step>
 
         <step id="hibernate-gsg-tutorial-native-running">
-            <title>Running the code</title>
+            <title>Run the code</title>
             <para>
                 To perform a store (leveraging the maven exec plugin):
-                <command>mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.native.EventManager" -Dexec.args="store"</command>
+                <command>mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.hbm.EventManager" -Dexec.args="store"</command>
                 You should see Hibernate starting up and, depending on your configuration, lots of log output. Towards
                 the end, the following line will be displayed:
                 <screen>[java] Hibernate: insert into EVENTS (EVENT_DATE, title, EVENT_ID) values (?, ?, ?)</screen>
@@ -295,7 +295,7 @@
 
             <para>
                 To perform a list:
-                <command>mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.native.EventManager"-Dexec.args="list"</command>
+                <command>mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.hbm.EventManager"-Dexec.args="list"</command>
             </para>
 
             <note>
@@ -307,8 +307,11 @@
         </step>
     </procedure>
 
-    <para>
+    <section id="hibernate-gsg-tutorial-annotations-further">
-        Take it further! Try the following:
+        <title>Take it further!</title>
+        <para>
+            Try the following exercises:
+        </para>
         <itemizedlist>
             <listitem>
                 <para>
@@ -322,6 +325,6 @@
                 </para>
             </listitem>
         </itemizedlist>
-    </para>
+    </section>
 
 </chapter>