Author: steve.ebersole(a)jboss.com
Date: 2010-08-16 14:42:39 -0400 (Mon, 16 Aug 2010)
New Revision: 20151
Added:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/compile-output.txt
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/hibernate.cfg.xml
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/Event.hbm.xml
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/Event.java
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/hbm/pom.xml
Removed:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/example-Event.hbm.xml
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/example-entity.java
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/example-pom.xml
Modified:
core/trunk/documentation/quickstart/pom.xml
core/trunk/documentation/quickstart/src/main/docbook/en-US/Book_Info.xml
core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml
Log:
HHH-5441 - Create "Getting Started Guide"
Modified: core/trunk/documentation/quickstart/pom.xml
===================================================================
--- core/trunk/documentation/quickstart/pom.xml 2010-08-16 06:43:06 UTC (rev 20150)
+++ core/trunk/documentation/quickstart/pom.xml 2010-08-16 18:42:39 UTC (rev 20151)
@@ -117,4 +117,22 @@
</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>
\ No newline at end of file
Modified: core/trunk/documentation/quickstart/src/main/docbook/en-US/Book_Info.xml
===================================================================
--- core/trunk/documentation/quickstart/src/main/docbook/en-US/Book_Info.xml 2010-08-16
06:43:06 UTC (rev 20150)
+++ core/trunk/documentation/quickstart/src/main/docbook/en-US/Book_Info.xml 2010-08-16
18:42:39 UTC (rev 20151)
@@ -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>
Modified:
core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml
===================================================================
---
core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml 2010-08-16
06:43:06 UTC (rev 20150)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml 2010-08-16
18:42:39 UTC (rev 20151)
@@ -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" />
Deleted:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/example-Event.hbm.xml
===================================================================
---
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/example-Event.hbm.xml 2010-08-16
06:43:06 UTC (rev 20150)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/example-Event.hbm.xml 2010-08-16
18:42:39 UTC (rev 20151)
@@ -1,13 +0,0 @@
-<![CDATA[
-<hibernate-mapping package="org.hibernate.tutorial.native">
-
- <class name="Event" table="EVENTS">
- <id name="id" column="EVENT_ID">
- <generator class="enhanced-sequence"/>
- </id>
- <property name="date" type="timestamp"
column="EVENT_DATE"/>
- <property name="title"/>
- </class>
-
-</hibernate-mapping>
-]]>
Deleted:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/example-entity.java
===================================================================
---
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/example-entity.java 2010-08-16
06:43:06 UTC (rev 20150)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/example-entity.java 2010-08-16
18:42:39 UTC (rev 20151)
@@ -1,36 +0,0 @@
-package org.hibernate.tutorial.native;
-
-import java.util.Date;
-
-public class Event {
- private Long id;
-
- private String title;
- private Date date;
-
- public Event() {}
-
- public Long getId() {
- return id;
- }
-
- private void setId(Long id) {
- this.id = id;
- }
-
- public Date getDate() {
- return date;
- }
-
- public void setDate(Date date) {
- this.date = date;
- }
-
- public String getTitle() {
- return title;
- }
-
- public void setTitle(String title) {
- this.title = title;
- }
-}
\ No newline at end of file
Deleted:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/example-pom.xml
===================================================================
---
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/example-pom.xml 2010-08-16
06:43:06 UTC (rev 20150)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/example-pom.xml 2010-08-16
18:42:39 UTC (rev 20151)
@@ -1,50 +0,0 @@
-<![CDATA[
-<project
xmlns="http://maven.apache.org/POM/4.0.0"
-xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd">
-
-<modelVersion>4.0.0</modelVersion>
-
-<groupId>org.hibernate.tutorials</groupId>
-<artifactId>hibernate-tutorial-native</artifactId>
-<version>1.0.0-SNAPSHOT</version>
-<name>Hibernate Native Tutorial</name>
-
-<build>
- <!-- we dont want the version to be part of the generated war file name -->
- <finalName>${artifactId}</finalName>
-</build>
-
-<dependencies>
- <dependency>
- <groupId>org.hibernate</groupId>
- <artifactId>hibernate-core</artifactId>
- </dependency>
-
- <!-- Because this is a web app, we also have a dependency on the servlet api.
-->
- <dependency>
- <groupId>javax.servlet</groupId>
- <artifactId>servlet-api</artifactId>
- </dependency>
-
- <!-- Hibernate uses slf4j for logging, for our purposes here use the simple backend
-->
- <dependency>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-simple</artifactId>
- </dependency>
-
- <!-- Hibernate gives you a choice of bytecode providers between cglib and javassist
-->
- <dependency>
- <groupId>javassist</groupId>
- <artifactId>javassist</artifactId>
- </dependency>
-
- <!-- The tutorial uses the H2 in-memory database -->
- <dependency>
- <groupId>com.h2database</groupId>
- <artifactId>h2</artifactId>
- </dependency>
-</dependencies>
-
-</project>
-]]>
\ No newline at end of file
Added:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/compile-output.txt
===================================================================
---
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/compile-output.txt
(rev 0)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/compile-output.txt 2010-08-16
18:42:39 UTC (rev 20151)
@@ -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] ------------------------------------------------------------------------
Added:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/hibernate.cfg.xml
===================================================================
---
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/hibernate.cfg.xml
(rev 0)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/hibernate.cfg.xml 2010-08-16
18:42:39 UTC (rev 20151)
@@ -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>
\ No newline at end of file
Copied:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/Event.hbm.xml
(from rev 20150,
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/example-Event.hbm.xml)
===================================================================
---
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/Event.hbm.xml
(rev 0)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/Event.hbm.xml 2010-08-16
18:42:39 UTC (rev 20151)
@@ -0,0 +1,13 @@
+<![CDATA[
+<hibernate-mapping package="org.hibernate.tutorial.hbm">
+
+ <class name="Event" table="EVENTS">
+ <id name="id" column="EVENT_ID">
+ <generator class="enhanced-sequence"/>
+ </id>
+ <property name="date" type="timestamp"
column="EVENT_DATE"/>
+ <property name="title"/>
+ </class>
+
+</hibernate-mapping>
+]]>
Copied:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/Event.java
(from rev 20150,
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/example-entity.java)
===================================================================
---
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/Event.java
(rev 0)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/Event.java 2010-08-16
18:42:39 UTC (rev 20151)
@@ -0,0 +1,36 @@
+package org.hibernate.tutorial.hbm;
+
+import java.util.Date;
+
+public class Event {
+ private Long id;
+
+ private String title;
+ private Date date;
+
+ public Event() {}
+
+ public Long getId() {
+ return id;
+ }
+
+ private void setId(Long id) {
+ this.id = id;
+ }
+
+ public Date getDate() {
+ return date;
+ }
+
+ public void setDate(Date date) {
+ this.date = date;
+ }
+
+ public String getTitle() {
+ return title;
+ }
+
+ public void setTitle(String title) {
+ this.title = title;
+ }
+}
\ No newline at end of file
Added:
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/hbm/org/hibernate/tutorial/hbm/EventManager.java
(rev 0)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/EventManager.java 2010-08-16
18:42:39 UTC (rev 20151)
@@ -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;
+ }
+}
\ No newline at end of file
Added:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/pom.xml
===================================================================
---
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/pom.xml
(rev 0)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/pom.xml 2010-08-16
18:42:39 UTC (rev 20151)
@@ -0,0 +1,50 @@
+<![CDATA[
+<project
xmlns="http://maven.apache.org/POM/4.0.0"
+xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+<modelVersion>4.0.0</modelVersion>
+
+<groupId>org.hibernate.tutorials</groupId>
+<artifactId>hibernate-tutorial-native</artifactId>
+<version>1.0.0-SNAPSHOT</version>
+<name>Hibernate Native Tutorial</name>
+
+<build>
+ <!-- we dont want the version to be part of the generated war file name -->
+ <finalName>${artifactId}</finalName>
+</build>
+
+<dependencies>
+ <dependency>
+ <groupId>org.hibernate</groupId>
+ <artifactId>hibernate-core</artifactId>
+ </dependency>
+
+ <!-- Because this is a web app, we also have a dependency on the servlet api.
-->
+ <dependency>
+ <groupId>javax.servlet</groupId>
+ <artifactId>servlet-api</artifactId>
+ </dependency>
+
+ <!-- Hibernate uses slf4j for logging, for our purposes here use the simple backend
-->
+ <dependency>
+ <groupId>org.slf4j</groupId>
+ <artifactId>slf4j-simple</artifactId>
+ </dependency>
+
+ <!-- Hibernate gives you a choice of bytecode providers between cglib and javassist
-->
+ <dependency>
+ <groupId>javassist</groupId>
+ <artifactId>javassist</artifactId>
+ </dependency>
+
+ <!-- The tutorial uses the H2 in-memory database -->
+ <dependency>
+ <groupId>com.h2database</groupId>
+ <artifactId>h2</artifactId>
+ </dependency>
+</dependencies>
+
+</project>
+]]>
\ 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-16
06:43:06 UTC (rev 20150)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml 2010-08-16
18:42:39 UTC (rev 20151)
@@ -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...;.
+ This tutorial uses the
+ <phrase>standard layout</phrase>
+ described in
+ <ulink
url="http://maven.apache.org/guides/introduction/introduction-to-the...;.
</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 @@
<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 @@
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 @@
</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>