Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

HHH-5441 - Create "Getting Started Guide" 

git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@20151 1b8cb986-b30d-0410-93ca-fae66ebed9b2
This commit is contained in:
Steve Ebersole 2010-08-16 18:42:39 +00:00
parent 5c8aa8b292
commit 54ae3b1dae
10 changed files with 253 additions and 248 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
documentation/quickstart/pom.xml
View File

@ -117,4 +117,22 @@ Error at xsl:text on line 111 of jar:file:/home/steve/.m2/repository/net/sf/docb
</plugins>
</build>
<dependencies>
<!-- For code samples -->
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>hibernate-core</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>hibernate-entitymanager</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>hibernate-envers</artifactId>
<version>${project.version}</version>
</dependency>
</dependencies>
</project>

2
documentation/quickstart/src/main/docbook/en-US/Book_Info.xml
View File

@ -4,7 +4,7 @@
%BOOK_ENTITIES;
]>
<bookinfo id="Hibernate_Getting_Started_Guide" xmlns="http://www.oasis-open.org/docbook/xml/4.5/">
<bookinfo id="Hibernate_Getting_Started_Guide">
<title>Hibernate Getting Started Guide</title>
<releaseinfo>&version;</releaseinfo>
<edition>1.0</edition>

2
documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml
View File

@ -4,7 +4,7 @@
%BOOK_ENTITIES;
]>
<book xmlns="http://www.oasis-open.org/docbook/xml/4.5/">
<book>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Book_Info.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/preface.xml" />

17
documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/compile-output.txt Normal file
View File

@ -0,0 +1,17 @@
[hibernateTutorial]$ mvn compile
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building First Hibernate Tutorial
[INFO] task-segment: [compile]
[INFO] ------------------------------------------------------------------------
[INFO] [resources:resources]
[INFO] Using default encoding to copy filtered resources.
[INFO] [compiler:compile]
[INFO] Compiling 2 source file to hibernateTutorial/target/classes
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2 seconds
[INFO] Finished at: Tue Jun 09 12:25:25 CDT 2009
[INFO] Final Memory: 5M/547M
[INFO] ------------------------------------------------------------------------

35
documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/hibernate.cfg.xml Normal file
View File

@ -0,0 +1,35 @@
<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
"-//Hibernate/Hibernate Configuration DTD 3.0//EN"
"http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">
<hibernate-configuration>
<session-factory>
<!-- Database connection settings -->
<property name="connection.driver_class">org.h2.Driver</property>
<property name="connection.url">jdbc:h2:mem:db1;DB_CLOSE_DELAY=-1;MVCC=TRUE</property>
<property name="connection.username">sa</property>
<property name="connection.password"></property>
<!-- JDBC connection pool (use the built-in) -->
<property name="connection.pool_size">1</property>
<!-- SQL dialect -->
<property name="dialect">org.hibernate.dialect.H2Dialect</property>
<!-- Disable the second-level cache -->
<property name="cache.provider_class">org.hibernate.cache.NoCacheProvider</property>
<!-- Echo all executed SQL to stdout -->
<property name="show_sql">true</property>
<!-- Drop and re-create the database schema on startup -->
<property name="hbm2ddl.auto">update</property>
<mapping resource="org/hibernate/tutorial/native/domain/Event.hbm.xml"/>
</session-factory>
</hibernate-configuration>

2
documentation/quickstart/src/main/docbook/en-US/content/extras/example-Event.hbm.xml → documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/Event.hbm.xml
View File

@ -1,5 +1,5 @@
<![CDATA[
<hibernate-mapping package="org.hibernate.tutorial.native">
<hibernate-mapping package="org.hibernate.tutorial.hbm">
<class name="Event" table="EVENTS">
<id name="id" column="EVENT_ID">

2
documentation/quickstart/src/main/docbook/en-US/content/extras/example-entity.java → documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/Event.java
View File

@ -1,4 +1,4 @@
package org.hibernate.tutorial.native;
package org.hibernate.tutorial.hbm;
import java.util.Date;

64
documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/EventManager.java Normal file
View File

@ -0,0 +1,64 @@
package org.hibernate.tutorial.hbm;
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;
}
}

0
documentation/quickstart/src/main/docbook/en-US/content/extras/example-pom.xml → documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/pom.xml
View File

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

@ -6,18 +6,18 @@
<note>
<para>
This tutorial uses the <phrase>standard layout</phrase> described in
<ulink
url="http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html"/>.
This tutorial uses the
<phrase>standard layout</phrase>
described in
<ulink url="http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html"/>.
</para>
</note>
<tip>
<para>
The tutorials in this guide use Maven, which includes superior
transitive dependency management capabilities and is easy to use
with many integrated development environments (IDEs). You can use
another build tool, adapting the examples to fit your needs.
The tutorials in this guide use Maven, in order to leverage its transitive dependency management
capabilities and its integration with many development environments (IDEs). You can use another build
tool, adapting the examples to fit your needs.
</para>
</tip>
@ -27,13 +27,14 @@
<step id="hibernate-gsg-tutorial-native-pom">
<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 the text in <xref
linkend="hibernate-gsg-tutorial-native-pom-ex1" />.
Create a file named <filename>pom.xml</filename> in the root of your project directory, containing
the text in<xref linkend="hibernate-gsg-tutorial-native-pom-ex1"/>.
</para>
<example id="hibernate-gsg-tutorial-native-pom-ex1">
<title><filename>pom.xml</filename></title>
<programlisting role="XML"><xi:include href="extras/example-pom.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
<title>
<filename>pom.xml</filename>
</title>
<programlisting role="XML"><xi:include href="extras/examples/hbm/pom.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
</example>
</step>
@ -41,24 +42,27 @@
<title>Create the entity Java class</title>
<para>
Create a file named <filename>src/main/java/org/hibernate/tutorial/native/Event.java</filename>, containing the text in <xref linkend="hibernate-gsg-tutorial-native-entity-ex1" />.
Create a file named<filename>src/main/java/org/hibernate/tutorial/hbm/Event.java</filename>,
containing the text in<xref linkend="hibernate-gsg-tutorial-native-entity-ex1"/>.
</para>
<example id="hibernate-gsg-tutorial-native-entity-ex1">
<title><filename>Entity.java</filename></title>
<programlisting role="JAVA"><xi:include href="extras/example-entity.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
<title>
<filename>Entity.java</filename>
</title>
<programlisting role="JAVA"><xi:include href="extras/examples/hbm/org/hibernate/tutorial/hbm/Event.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
</example>
<para>
<!-- todo : what's the best way to refer to content in other books? -->
<!-- like here it would be nice to say something like: -->
<!-- "Entity class requirements are covered in detail in <x.y.z Some Developer Guide Chapter/Section>" -->
<itemizedlist>
<title>Notes About the Entity</title>
<title>Notes About the Entity</title>
<listitem>
<para>
This class uses standard JavaBean naming conventions
for property getter and setter methods, as well as
private visibility for the fields. Although this is
private visibility for the fields. Although this is
the recommended design, it is not required.
</para>
</listitem>
@ -66,8 +70,8 @@
<para>
The no-argument constructor, which is also a JavaBean
convention, is a requirement for all persistent
classes. Hibernate needs to create objects for you,
using Java Reflection. The constructor can be
classes. Hibernate needs to create objects for you,
using Java Reflection. The constructor can be
private. However, package or public visibility is
required for runtime proxy generation and efficient
data retrieval without bytecode instrumentation.
@ -81,116 +85,95 @@
<title>Create the entity mapping file</title>
<para>
Create a file named <filename>src/main/resources/org/hibernate/tutorial/native/Event.hbm.xml</filename>, with the contents in <xref linkend="example-Event.hbm.xml" />.
Create a file named<filename>src/main/resources/org/hibernate/tutorial/native/Event.hbm.xml</filename>,
with the contents in <xref linkend="hibernate-gsg-tutorial-native-hbm-xml-ex1"/>.
</para>
<example>
<title><filename>Event.hbm.xml</filename></title>
<programlisting role="XML"><xi:include href="extras/example-Event.hbm.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
<example id="hibernate-gsg-tutorial-native-hbm-xml-ex1">
<title>
<filename>Event.hbm.xml</filename>
</title>
<programlisting role="XML"><xi:include href="extras/examples/hbm/org/hibernate/tutorial/hbm/Event.hbm.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
</example>
<para>
Hibernate uses the mapping metadata to find out how to load and
store objects of the persistent class. The Hibernate mapping
store objects of the persistent class. The Hibernate mapping
file is one choice for providing Hibernate with this metadata.
</para>
<orderedlist>
<title>Functions of the <literal>class</literal> element</title>
<listitem>
<para>
The <literal>class</literal> attribute, combined here with the
<literal>package</literal> attribute from the containing
<literal>hibernate-mapping</literal> element, names the FQN of
the class you want to define as an entity.
</para>
</listitem>
<listitem>
<para>
The <literal>table</literal> attribute names the database
table which contains the data for this entity.
</para>
</listitem>
</orderedlist>
<orderedlist>
<title>Functions of the <literal>class</literal> element</title>
<listitem>
<para>
The <literal>class</literal> attribute, combined here with the <literal>package</literal>
attribute from the containing <literal>hibernate-mapping</literal> element, names the FQN of
the class you want to define as an entity.
</para>
</listitem>
<listitem>
<para>
The <literal>table</literal> attribute names the database table which contains the data for
this entity.
</para>
</listitem>
</orderedlist>
<para>
Instances of <classname>Event</classname> are now mapped to rows
in the <literal>EVENTS</literal> table. Hibernate uses the
<literal>id</literal> element to uniquely identify rows in the
table.
Instances of <classname>Event</classname> are now mapped to rows in the <literal>EVENTS</literal>
table. Hibernate uses the <literal>id</literal> element to uniquely identify rows in the table.
</para>
<important>
<para>
It is not strictly necessary that the <literal>id</literal>
element map to the table's actual primary key column(s), but
it is the normal convention. Tables mapped in Hibernate do
not even need to define primary keys. However, the Hibernate
team <emphasis>strongly</emphasis> recommends that all
schemas define proper referential integrity. Therefore
<literal>id</literal> and <phrase>primary key</phrase> are
used interchangeably throughout Hibernate documentation.
It is not strictly necessary that the <literal>id</literal> element map to the table's actual
primary key column(s), but it is the normal convention. Tables mapped in Hibernate do not even
need to define primary keys. However, the Hibernate team <emphasis>strongly</emphasis>
recommends that all schemas define proper referential integrity. Therefore <literal>id</literal>
and <phrase>primary key</phrase> are used interchangeably throughout Hibernate documentation.
</para>
</important>
<para>
The <literal>id</literal> element here identifies the
<literal>EVENT_ID</literal> column as the primary key of the
<literal>EVENTS</literal> table. It also identifies the
<literal>id</literal> property of the
<classname>Event</classname> class as the property to hold the
identifier value.
The <literal>id</literal> element here identifies the <literal>EVENT_ID</literal> column as the
primary key of the <literal>EVENTS</literal> table. It also identifies the <literal>id</literal>
property of the <classname>Event</classname> class as the property to hold the identifier value.
</para>
<para>
The important thing to be aware of about the
<literal>generator</literal> element nested inside the
<literal>id</literal> element is that it informs Hibernate which
strategy is used to generated primary key values for this
entity. In this instance, it uses a sequence-like value
generation.
The important thing to be aware of about the <literal>generator</literal> element nested inside the
<literal>id</literal> element is that it informs Hibernate which strategy is used to generated primary
key values for this entity. In this instance, it uses a sequence-like value generation.
</para>
<para>
The two <literal>property</literal> elements declare the
remaining two properties of the <classname>Event</classname>
class: <literal>date</literal> and <literal>title</literal>.
The <literal>date</literal> property mapping include the
<literal>column</literal> attribute, but the
<literal>title</literal> does not. In the absense of a
<literal>column</literal> attribute, Hibernate uses the property
name as the column name. This is appropriate for
<literal>title</literal>, but since <literal>date</literal> is a
reserved keyword in most databases, you need to specify a
non-reserved word for the column name.
The two <literal>property</literal> elements declare the remaining two properties of the
<classname>Event</classname> class: <literal>date</literal> and<literal>title</literal>. The
<literal>date</literal> property mapping include the <literal>column</literal> attribute, but the
<literal>title</literal> does not. In the absence of a <literal>column</literal> attribute, Hibernate
uses the property name as the column name. This is appropriate for <literal>title</literal>, but since
<literal>date</literal> is a reserved keyword in most databases, you need to specify a non-reserved
word for the column name.
</para>
<para>
The <literal>title</literal> mapping also lacks a
<literal>type</literal> attribute. The types declared and used
in the mapping files are neither Java data types nor SQL
database types. Instead, they are <firstterm><phrase>Hibernate
mapping types</phrase></firstterm>. Hibernate mapping types are
converters which translate between Java and SQL data types.
Hibernate attempts to determine the correct conversion and
mapping type autonomously if the <literal>type</literal>
attribute is not present in the mapping, by using Java
reflection to determine the Java type of the declared property
and using a default mapping type for that Java type.
</para>
<para>
In some cases this automatic detection might not have the
default you expect or need, as seen with the
<literal>date</literal> property. Hibernate cannot know if the
property, which is of type
<classname>java.util.Date</classname>, should map to a SQL
<literal>DATE</literal>, <literal>TIME</literal>, or
<literal>TIMESTAMP</literal> datatype. Full date and time
information is preserved by mapping the property to a
<literal>timestamp</literal> converter.
The <literal>title</literal> mapping also lacks a <literal>type</literal> attribute. The types
declared and used in the mapping files are neither Java data types nor SQL database types. Instead,
they are <firstterm><phrase>Hibernate mapping types</phrase></firstterm>. Hibernate mapping types are
converters which translate between Java and SQL data types. Hibernate attempts to determine the correct
conversion and mapping type autonomously if the <literal>type</literal> attribute is not present in the
mapping, by using Java reflection to determine the Java type of the declared property and using a
default mapping type for that Java type.
</para>
<para>
In some cases this automatic detection might not have the default you expect or need, as seen with the
<literal>date</literal> property. Hibernate cannot know if the property, which is of type
<classname>java.util.Date</classname>, should map to a SQL <literal>DATE</literal>,
<literal>TIME</literal>, or <literal>TIMESTAMP</literal> datatype. Full date and time information is
preserved by mapping the property to a <literal>timestamp</literal>
converter.
</para>
<tip>
<para>
Hibernate makes this mapping type determination using
reflection when the mapping files are processed. This can
take time and resources. If startup performance is
important, consider explicitly defining the type to use.
Hibernate makes this mapping type determination using reflection when the mapping files are
processed. This can take time and resources. If startup performance is important, consider
explicitly defining the type to use.
</para>
</tip>
</step>
@ -199,59 +182,25 @@
<title>Create the Hibernate configuration file</title>
<para>
Create a file named <filename>src/main/resources/hibernate.cfg.xml</filename>
with the following contents:
Create a file named <filename>src/main/resources/hibernate.cfg.xml</filename> with the following contents:
</para>
<example id="hibernate-gsg-tutorial-native-config-ex1">
<title><filename>hibernate.cfg.xml</filename></title>
<programlisting role="XML"><![CDATA[<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
"-//Hibernate/Hibernate Configuration DTD 3.0//EN"
"http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">
<hibernate-configuration>
<session-factory>
<!-- Database connection settings -->
<property name="connection.driver_class">org.h2.Driver</property>
<property name="connection.url">jdbc:h2:mem:db1;DB_CLOSE_DELAY=-1;MVCC=TRUE</property>
<property name="connection.username">sa</property>
<property name="connection.password"></property>
<!-- JDBC connection pool (use the built-in) -->
<property name="connection.pool_size">1</property>
<!-- SQL dialect -->
<property name="dialect">org.hibernate.dialect.H2Dialect</property>
<!-- Disable the second-level cache -->
<property name="cache.provider_class">org.hibernate.cache.NoCacheProvider</property>
<!-- Echo all executed SQL to stdout -->
<property name="show_sql">true</property>
<!-- Drop and re-create the database schema on startup -->
<property name="hbm2ddl.auto">update</property>
<mapping resource="org/hibernate/tutorial/native/domain/Event.hbm.xml"/>
</session-factory>
</hibernate-configuration>]]></programlisting>
<programlisting role="XML"><xi:include href="extras/examples/hbm/hibernate.cfg.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
</example>
<para>
The first few <literal>property</literal> are defining JDBC connection information. These tutorials
utilize the H2 in-memory database. So these are all specific to running H2 in its in-memory mode.
The 'connection.pool_size' is used to configure Hibernate's built-in connection pool how many connections
The first few <literal>property</literal> are defining JDBC connection information. These tutorials
utilize the H2 in-memory database. So these are all specific to running H2 in its in-memory mode.
The 'connection.pool_size' is used to configure Hibernate's built-in connection pool how many
connections
to pool.
</para>
<caution>
<para>
The built-in Hibernate connection pool is in no way intended for production use. It
The built-in Hibernate connection pool is in no way intended for production use. It
lacks several features found on any decent connection pool.
</para>
</caution>
@ -262,14 +211,14 @@
<tip>
<para>
In most cases, Hibernate is able to properly determine which dialect to use which is invaluable if your
application targets multiple databases.
In most cases, Hibernate is able to properly determine which dialect to use which is invaluable if
your application targets multiple databases.
</para>
</tip>
<para>
The <literal>hbm2ddl.auto</literal> option turns on automatic generation of
database schemas directly into the database.
The <literal>hbm2ddl.auto</literal> option turns on automatic generation of database schemas directly
into the database.
</para>
<para>
Finally, add the mapping file(s) for persistent classes to the configuration.
@ -279,106 +228,46 @@
<step id="hibernate-gsg-tutorial-native-working">
<title>Do stuff</title>
<para>
Create a file named <filename>src/main/java/org/hibernate/tutorial/native/EvetManager.java</filename>
Create a file named <filename>src/main/java/org/hibernate/tutorial/hbm/EventManager.java</filename>
with the following contents:
</para>
<example id="hibernate-gsg-tutorial-native-working-ex1">
<title><filename>EventManager.java</filename></title>
<programlisting role="JAVA"><![CDATA[package org.hibernate.tutorial.native;
import org.hibernate.cfg.Configuration;
import org.hibernate.Session;
import org.hibernate.SessionFactory;
import java.util.Date;
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 = mgr.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;
}
}]]></programlisting>
<title>
<filename>EventManager.java</filename>
</title>
<programlisting role="JAVA"><xi:include href="extras/examples/hbm/org/hibernate/tutorial/hbm/EventManager.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
</example>
<para>
The <classname>org.hibernate.cfg.Configuration</classname> class is the first thing to notice. In this
The <classname>org.hibernate.cfg.Configuration</classname> class is the first thing to notice. In this
tutorial we simply configure everything via the <filename>hibernate.cfg.xml</filename> file
discussed in <xref linkend="hibernate-gsg-tutorial-native-config"/>.
discussed in<xref linkend="hibernate-gsg-tutorial-native-config"/>.
</para>
<para>
The <classname>org.hibernate.cfg.Configuration</classname> is then used to create the
<interfacename>org.hibernate.SessionFactory</interfacename> which is a
thread-safe object that is instantiated once to serve the entire application.
<interfacename>org.hibernate.SessionFactory</interfacename> which is a thread-safe object that is
instantiated once to serve the entire application.
</para>
<para>
The <interfacename>org.hibernate.SessionFactory</interfacename> acts as a factory for
<interfacename>org.hibernate.Session</interfacename> instances as can be seen in the
<methodname>createAndStoreEvent</methodname> and <methodname>listEvents</methodname> methods of the
<classname>EventManager</classname> class. A <interfacename>org.hibernate.Session</interfacename>
<classname>EventManager</classname> class. A <interfacename>org.hibernate.Session</interfacename>
should be thought of as a corollary to a "unit of work". <!-- todo : reference to a discussion in dev guide -->
</para>
<para>
<methodname>createAndStoreEvent</methodname> creates a new <classname>Event</classname> object
and hands it over to Hibernate for "management". At that point, Hibernate takes responsibility to
and hands it over to Hibernate for "management". At that point, Hibernate takes responsibility to
perform an <literal>INSERT</literal> on the database.
</para>
<para>
<methodname>listEvents</methodname> illustrates use of the Hibernate Query Language (HQL) to load all
existing <classname>Event</classname> objects from the database. Hibernate will generate the
existing <classname>Event</classname> objects from the database. Hibernate will generate the
appropriate <literal>SELECT</literal> SQL, send it to the database and populate
<classname>Event</classname> objects with the result set data.
</para>
@ -386,25 +275,7 @@ public class EventManager {
<step id="hibernate-gsg-tutorial-native-compile">
<title>Compile the source</title>
<screen>
[hibernateTutorial]$ mvn compile
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building First Hibernate Tutorial
[INFO] task-segment: [compile]
[INFO] ------------------------------------------------------------------------
[INFO] [resources:resources]
[INFO] Using default encoding to copy filtered resources.
[INFO] [compiler:compile]
[INFO] Compiling 2 source file to hibernateTutorial/target/classes
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2 seconds
[INFO] Finished at: Tue Jun 09 12:25:25 CDT 2009
[INFO] Final Memory: 5M/547M
[INFO] ------------------------------------------------------------------------
</screen>
<screen><xi:include href="extras/examples/hbm/compile-output.txt" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></screen>
</step>
<step id="hibernate-gsg-tutorial-native-running">
@ -415,25 +286,25 @@ public class EventManager {
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>
This is the <literal>INSERT</literal> executed by Hibernate.
This is the <literal>INSERT</literal>executed by Hibernate.
</para>
<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.native.EventManager"-Dexec.args="list"</command>
</para>
<note>
<para>
Currently nothing will ever be output when performing the list because the database is recreated
every time the <interfacename>org.hibernate.SessionFactory</interfacename> is created. See the
every time the <interfacename>org.hibernate.SessionFactory</interfacename> is created.
</para>
</note>
</step>
</procedure>
<para>
Take it further! Try the following:
Take it further! Try the following:
<itemizedlist>
<listitem>
<para>
@ -442,8 +313,8 @@ public class EventManager {
</listitem>
<listitem>
<para>
With help of the Developer Guide, add an association to the <classname>Event</classname> entity
to model a message thread.
With help of the Developer Guide, add an association to the <classname>Event</classname>
entity to model a message thread.
</para>
</listitem>
</itemizedlist>