HHH-5444 - Write annotations tutorial chapter

git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@20255 1b8cb986-b30d-0410-93ca-fae66ebed9b2
This commit is contained in:
Steve Ebersole 2010-08-24 17:15:42 +00:00
parent adc1ab6c02
commit 034c7b77c1
3 changed files with 154 additions and 27 deletions

View File

@ -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;
}
}

View File

@ -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>@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 -->
<!-- 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>

View File

@ -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>