7:15 p.m.
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>(a)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>(a)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>(a)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 -->
- <!-- 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