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> </plugins>
</build> </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> </project>

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

@ -4,7 +4,7 @@
%BOOK_ENTITIES; %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> <title>Hibernate Getting Started Guide</title>
<releaseinfo>&version;</releaseinfo> <releaseinfo>&version;</releaseinfo>
<edition>1.0</edition> <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_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="Book_Info.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/preface.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[ <![CDATA[
<hibernate-mapping package="org.hibernate.tutorial.native"> <hibernate-mapping package="org.hibernate.tutorial.hbm">
<class name="Event" table="EVENTS"> <class name="Event" table="EVENTS">
<id name="id" column="EVENT_ID"> <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; 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> <note>
<para> <para>
This tutorial uses the <phrase>standard layout</phrase> described in This tutorial uses the
<ulink <phrase>standard layout</phrase>
url="http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html"/>. described in
<ulink url="http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html"/>.
</para> </para>
</note> </note>
<tip> <tip>
<para> <para>
The tutorials in this guide use Maven, which includes superior The tutorials in this guide use Maven, in order to leverage its transitive dependency management
transitive dependency management capabilities and is easy to use capabilities and its integration with many development environments (IDEs). You can use another build
with many integrated development environments (IDEs). You can use tool, adapting the examples to fit your needs.
another build tool, adapting the examples to fit your needs.
</para> </para>
</tip> </tip>
@ -27,13 +27,14 @@
<step id="hibernate-gsg-tutorial-native-pom"> <step id="hibernate-gsg-tutorial-native-pom">
<title>Create the Maven POM file</title> <title>Create the Maven POM file</title>
<para> <para>
Create a file named <filename>pom.xml</filename> in the root of Create a file named <filename>pom.xml</filename> in the root of your project directory, containing
your project directory, containing the the text in <xref the text in<xref linkend="hibernate-gsg-tutorial-native-pom-ex1"/>.
linkend="hibernate-gsg-tutorial-native-pom-ex1" />.
</para> </para>
<example id="hibernate-gsg-tutorial-native-pom-ex1"> <example id="hibernate-gsg-tutorial-native-pom-ex1">
<title><filename>pom.xml</filename></title> <title>
<programlisting role="XML"><xi:include href="extras/example-pom.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting> <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> </example>
</step> </step>
@ -41,24 +42,27 @@
<title>Create the entity Java class</title> <title>Create the entity Java class</title>
<para> <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> </para>
<example id="hibernate-gsg-tutorial-native-entity-ex1"> <example id="hibernate-gsg-tutorial-native-entity-ex1">
<title><filename>Entity.java</filename></title> <title>
<programlisting role="JAVA"><xi:include href="extras/example-entity.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting> <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> </example>
<para> <para>
<!-- todo : what's the best way to refer to content in other books? --> <!-- todo : what's the best way to refer to content in other books? -->
<!-- like here it would be nice to say something like: --> <!-- 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>" --> <!-- "Entity class requirements are covered in detail in <x.y.z Some Developer Guide Chapter/Section>" -->
<itemizedlist> <itemizedlist>
<title>Notes About the Entity</title> <title>Notes About the Entity</title>
<listitem> <listitem>
<para> <para>
This class uses standard JavaBean naming conventions This class uses standard JavaBean naming conventions
for property getter and setter methods, as well as 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. the recommended design, it is not required.
</para> </para>
</listitem> </listitem>
@ -66,8 +70,8 @@
<para> <para>
The no-argument constructor, which is also a JavaBean The no-argument constructor, which is also a JavaBean
convention, is a requirement for all persistent convention, is a requirement for all persistent
classes. Hibernate needs to create objects for you, classes. Hibernate needs to create objects for you,
using Java Reflection. The constructor can be using Java Reflection. The constructor can be
private. However, package or public visibility is private. However, package or public visibility is
required for runtime proxy generation and efficient required for runtime proxy generation and efficient
data retrieval without bytecode instrumentation. data retrieval without bytecode instrumentation.
@ -81,116 +85,95 @@
<title>Create the entity mapping file</title> <title>Create the entity mapping file</title>
<para> <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> </para>
<example> <example id="hibernate-gsg-tutorial-native-hbm-xml-ex1">
<title><filename>Event.hbm.xml</filename></title> <title>
<programlisting role="XML"><xi:include href="extras/example-Event.hbm.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting> <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> </example>
<para> <para>
Hibernate uses the mapping metadata to find out how to load and 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. file is one choice for providing Hibernate with this metadata.
</para> </para>
<orderedlist> <orderedlist>
<title>Functions of the <literal>class</literal> element</title> <title>Functions of the <literal>class</literal> element</title>
<listitem> <listitem>
<para> <para>
The <literal>class</literal> attribute, combined here with the The <literal>class</literal> attribute, combined here with the <literal>package</literal>
<literal>package</literal> attribute from the containing attribute from the containing <literal>hibernate-mapping</literal> element, names the FQN of
<literal>hibernate-mapping</literal> element, names the FQN of the class you want to define as an entity.
the class you want to define as an entity. </para>
</para> </listitem>
</listitem> <listitem>
<listitem> <para>
<para> The <literal>table</literal> attribute names the database table which contains the data for
The <literal>table</literal> attribute names the database this entity.
table which contains the data for this entity. </para>
</para> </listitem>
</listitem> </orderedlist>
</orderedlist>
<para> <para>
Instances of <classname>Event</classname> are now mapped to rows Instances of <classname>Event</classname> are now mapped to rows in the <literal>EVENTS</literal>
in the <literal>EVENTS</literal> table. Hibernate uses the table. Hibernate uses the <literal>id</literal> element to uniquely identify rows in the table.
<literal>id</literal> element to uniquely identify rows in the
table.
</para> </para>
<important> <important>
<para> <para>
It is not strictly necessary that the <literal>id</literal> It is not strictly necessary that the <literal>id</literal> element map to the table's actual
element map to the table's actual primary key column(s), but primary key column(s), but it is the normal convention. Tables mapped in Hibernate do not even
it is the normal convention. Tables mapped in Hibernate do need to define primary keys. However, the Hibernate team <emphasis>strongly</emphasis>
not even need to define primary keys. However, the Hibernate recommends that all schemas define proper referential integrity. Therefore <literal>id</literal>
team <emphasis>strongly</emphasis> recommends that all and <phrase>primary key</phrase> are used interchangeably throughout Hibernate documentation.
schemas define proper referential integrity. Therefore
<literal>id</literal> and <phrase>primary key</phrase> are
used interchangeably throughout Hibernate documentation.
</para> </para>
</important> </important>
<para> <para>
The <literal>id</literal> element here identifies the The <literal>id</literal> element here identifies the <literal>EVENT_ID</literal> column as the
<literal>EVENT_ID</literal> column as the primary key of the primary key of the <literal>EVENTS</literal> table. It also identifies the <literal>id</literal>
<literal>EVENTS</literal> table. It also identifies the property of the <classname>Event</classname> class as the property to hold the identifier value.
<literal>id</literal> property of the
<classname>Event</classname> class as the property to hold the
identifier value.
</para> </para>
<para> <para>
The important thing to be aware of about the The important thing to be aware of about the <literal>generator</literal> element nested inside the
<literal>generator</literal> element nested inside the <literal>id</literal> element is that it informs Hibernate which strategy is used to generated primary
<literal>id</literal> element is that it informs Hibernate which key values for this entity. In this instance, it uses a sequence-like value generation.
strategy is used to generated primary key values for this
entity. In this instance, it uses a sequence-like value
generation.
</para> </para>
<para> <para>
The two <literal>property</literal> elements declare the The two <literal>property</literal> elements declare the remaining two properties of the
remaining two properties of the <classname>Event</classname> <classname>Event</classname> class: <literal>date</literal> and<literal>title</literal>. The
class: <literal>date</literal> and <literal>title</literal>. <literal>date</literal> property mapping include the <literal>column</literal> attribute, but the
The <literal>date</literal> property mapping include the <literal>title</literal> does not. In the absence of a <literal>column</literal> attribute, Hibernate
<literal>column</literal> attribute, but the uses the property name as the column name. This is appropriate for <literal>title</literal>, but since
<literal>title</literal> does not. In the absense of a <literal>date</literal> is a reserved keyword in most databases, you need to specify a non-reserved
<literal>column</literal> attribute, Hibernate uses the property word for the column name.
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>
<para> <para>
The <literal>title</literal> mapping also lacks a The <literal>title</literal> mapping also lacks a <literal>type</literal> attribute. The types
<literal>type</literal> attribute. The types declared and used declared and used in the mapping files are neither Java data types nor SQL database types. Instead,
in the mapping files are neither Java data types nor SQL they are <firstterm><phrase>Hibernate mapping types</phrase></firstterm>. Hibernate mapping types are
database types. Instead, they are <firstterm><phrase>Hibernate converters which translate between Java and SQL data types. Hibernate attempts to determine the correct
mapping types</phrase></firstterm>. Hibernate mapping types are conversion and mapping type autonomously if the <literal>type</literal> attribute is not present in the
converters which translate between Java and SQL data types. mapping, by using Java reflection to determine the Java type of the declared property and using a
Hibernate attempts to determine the correct conversion and default mapping type for that Java type.
mapping type autonomously if the <literal>type</literal> </para>
attribute is not present in the mapping, by using Java <para>
reflection to determine the Java type of the declared property In some cases this automatic detection might not have the default you expect or need, as seen with the
and using a default mapping type for that Java type. <literal>date</literal> property. Hibernate cannot know if the property, which is of type
</para> <classname>java.util.Date</classname>, should map to a SQL <literal>DATE</literal>,
<para> <literal>TIME</literal>, or <literal>TIMESTAMP</literal> datatype. Full date and time information is
In some cases this automatic detection might not have the preserved by mapping the property to a <literal>timestamp</literal>
default you expect or need, as seen with the converter.
<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> </para>
<tip> <tip>
<para> <para>
Hibernate makes this mapping type determination using Hibernate makes this mapping type determination using reflection when the mapping files are
reflection when the mapping files are processed. This can processed. This can take time and resources. If startup performance is important, consider
take time and resources. If startup performance is explicitly defining the type to use.
important, consider explicitly defining the type to use.
</para> </para>
</tip> </tip>
</step> </step>
@ -199,59 +182,25 @@
<title>Create the Hibernate configuration file</title> <title>Create the Hibernate configuration file</title>
<para> <para>
Create a file named <filename>src/main/resources/hibernate.cfg.xml</filename> Create a file named <filename>src/main/resources/hibernate.cfg.xml</filename> with the following contents:
with the following contents:
</para> </para>
<example id="hibernate-gsg-tutorial-native-config-ex1"> <example id="hibernate-gsg-tutorial-native-config-ex1">
<title><filename>hibernate.cfg.xml</filename></title> <title><filename>hibernate.cfg.xml</filename></title>
<programlisting role="XML"><![CDATA[<?xml version='1.0' encoding='utf-8'?> <programlisting role="XML"><xi:include href="extras/examples/hbm/hibernate.cfg.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
<!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>
</example> </example>
<para> <para>
The first few <literal>property</literal> are defining JDBC connection information. These tutorials 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. 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 'connection.pool_size' is used to configure Hibernate's built-in connection pool how many
connections
to pool. to pool.
</para> </para>
<caution> <caution>
<para> <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. lacks several features found on any decent connection pool.
</para> </para>
</caution> </caution>
@ -262,14 +211,14 @@
<tip> <tip>
<para> <para>
In most cases, Hibernate is able to properly determine which dialect to use which is invaluable if your In most cases, Hibernate is able to properly determine which dialect to use which is invaluable if
application targets multiple databases. your application targets multiple databases.
</para> </para>
</tip> </tip>
<para> <para>
The <literal>hbm2ddl.auto</literal> option turns on automatic generation of The <literal>hbm2ddl.auto</literal> option turns on automatic generation of database schemas directly
database schemas directly into the database. into the database.
</para> </para>
<para> <para>
Finally, add the mapping file(s) for persistent classes to the configuration. Finally, add the mapping file(s) for persistent classes to the configuration.
@ -279,106 +228,46 @@
<step id="hibernate-gsg-tutorial-native-working"> <step id="hibernate-gsg-tutorial-native-working">
<title>Do stuff</title> <title>Do stuff</title>
<para> <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: with the following contents:
</para> </para>
<example id="hibernate-gsg-tutorial-native-working-ex1"> <example id="hibernate-gsg-tutorial-native-working-ex1">
<title><filename>EventManager.java</filename></title> <title>
<programlisting role="JAVA"><![CDATA[package org.hibernate.tutorial.native; <filename>EventManager.java</filename>
</title>
import org.hibernate.cfg.Configuration; <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>
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>
</example> </example>
<para> <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 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>
<para> <para>
The <classname>org.hibernate.cfg.Configuration</classname> is then used to create the The <classname>org.hibernate.cfg.Configuration</classname> is then used to create the
<interfacename>org.hibernate.SessionFactory</interfacename> which is a <interfacename>org.hibernate.SessionFactory</interfacename> which is a thread-safe object that is
thread-safe object that is instantiated once to serve the entire application. instantiated once to serve the entire application.
</para> </para>
<para> <para>
The <interfacename>org.hibernate.SessionFactory</interfacename> acts as a factory for The <interfacename>org.hibernate.SessionFactory</interfacename> acts as a factory for
<interfacename>org.hibernate.Session</interfacename> instances as can be seen in the <interfacename>org.hibernate.Session</interfacename> instances as can be seen in the
<methodname>createAndStoreEvent</methodname> and <methodname>listEvents</methodname> methods of 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 --> should be thought of as a corollary to a "unit of work". <!-- todo : reference to a discussion in dev guide -->
</para> </para>
<para> <para>
<methodname>createAndStoreEvent</methodname> creates a new <classname>Event</classname> object <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. perform an <literal>INSERT</literal> on the database.
</para> </para>
<para> <para>
<methodname>listEvents</methodname> illustrates use of the Hibernate Query Language (HQL) to load all <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 appropriate <literal>SELECT</literal> SQL, send it to the database and populate
<classname>Event</classname> objects with the result set data. <classname>Event</classname> objects with the result set data.
</para> </para>
@ -386,25 +275,7 @@ public class EventManager {
<step id="hibernate-gsg-tutorial-native-compile"> <step id="hibernate-gsg-tutorial-native-compile">
<title>Compile the source</title> <title>Compile the source</title>
<screen> <screen><xi:include href="extras/examples/hbm/compile-output.txt" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></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>
</step> </step>
<step id="hibernate-gsg-tutorial-native-running"> <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 You should see Hibernate starting up and, depending on your configuration, lots of log output. Towards
the end, the following line will be displayed: the end, the following line will be displayed:
<screen>[java] Hibernate: insert into EVENTS (EVENT_DATE, title, EVENT_ID) values (?, ?, ?)</screen> <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>
<para> <para>
To perform a list: 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> </para>
<note> <note>
<para> <para>
Currently nothing will ever be output when performing the list because the database is recreated 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> </para>
</note> </note>
</step> </step>
</procedure> </procedure>
<para> <para>
Take it further! Try the following: Take it further! Try the following:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
@ -442,8 +313,8 @@ public class EventManager {
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
With help of the Developer Guide, add an association to the <classname>Event</classname> entity With help of the Developer Guide, add an association to the <classname>Event</classname>
to model a message thread. entity to model a message thread.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>