Author: steve.ebersole(a)jboss.com Date: 2010-08-24 13:15:42 -0400 (Tue, 24 Aug 2010) New Revision: 20255 Added: core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/org/hibernate/tutorial/annotations/EventManager.java Modified: core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml Log: HHH-5444 - Write annotations tutorial chapter Copied: core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/org/hibernate/tutorial/annotations/EventManager.java (from rev 20248, core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/EventManager.java) =================================================================== --- core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/org/hibernate/tutorial/annotations/EventManager.java (rev 0) +++ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/org/hibernate/tutorial/annotations/EventManager.java 2010-08-24 17:15:42 UTC (rev 20255) @@ -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; + } +} \ No newline at end of file Modified: core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml =================================================================== --- core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml 2010-08-24 17:15:32 UTC (rev 20254) +++ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml 2010-08-24 17:15:42 UTC (rev 20255) @@ -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> - <filename>pom.xml</filename> - </title> + <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>, - containing the text in<xref linkend="hibernate-gsg-tutorial-annotations-entity-ex1"/>. + 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"/>. </para> <example id="hibernate-gsg-tutorial-annotations-entity-ex1"> - <title> - <filename>Entity.java</filename> - </title> + <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&gt;(a)javax.persistence.Table&lt;/interfacename&gt; 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&gt;(a)javax.persistence.Id&lt;/interfacename&gt; 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&gt;(a)javax.persistence.Id&lt;/interfacename&gt; 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 --> - <!-- todo : is it enough to say that? --> + <step id="hibernate-gsg-tutorial-annotations-working"> + <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> \ No newline at end of file Modified: core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml =================================================================== --- core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml 2010-08-24 17:15:32 UTC (rev 20254) +++ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml 2010-08-24 17:15:42 UTC (rev 20255) @@ -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> - Take it further! Try the following: + <section id="hibernate-gsg-tutorial-annotations-further"> + <title>Take it further!</title> + <para> + Try the following exercises: + </para> <itemizedlist> <listitem> <para> @@ -322,6 +325,6 @@ </para> </listitem> </itemizedlist> - </para> + </section> </chapter> \ No newline at end of file