[hibernate-commits] Hibernate SVN: r20151 - in core/trunk/documentation/quickstart: src/main/docbook/en-US and 8 other directories.

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>