[hibernate-commits] Hibernate SVN: r20131 - in core/trunk/documentation: quickstart and 2 other directories.

Author: steve.ebersole(a)jboss.com Date: 2010-08-10 16:57:50 -0400 (Tue, 10 Aug 2010) New Revision: 20131 Added: core/trunk/documentation/quickstart/src/main/docbook/en-US/Author_Group.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.ent core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml core/trunk/documentation/quickstart/src/main/docbook/en-US/content/ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/community.xml core/trunk/documentation/quickstart/src/main/docbook/en-US/content/obtaining.xml core/trunk/documentation/quickstart/src/main/docbook/en-US/content/preface.xml core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml Removed: core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_QuickStart_Guide.ent core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_QuickStart_Guide.xml Modified: core/trunk/documentation/manual/src/main/docbook/en-US/content/preface.xml core/trunk/documentation/quickstart/pom.xml Log: HHH-5442 - Create a "quick start" guide Modified: core/trunk/documentation/manual/src/main/docbook/en-US/content/preface.xml =================================================================== --- core/trunk/documentation/manual/src/main/docbook/en-US/content/preface.xml 2010-08-09 19:56:25 UTC (rev 20130) +++ core/trunk/documentation/manual/src/main/docbook/en-US/content/preface.xml 2010-08-10 20:57:50 UTC (rev 20131) @@ -23,7 +23,7 @@ ~ Boston, MA 02110-1301 USA --> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent"> %BOOK_ENTITIES; @@ -36,10 +36,9 @@ Working with both Object-Oriented software and Relational Databases can be cumbersome and time consuming. Development costs are significantly higher due to a paradigm mismatch between how data is represented in objects versus relational databases. Hibernate is an Object/Relational Mapping solution for Java environments. - The term Object/Relational Mapping refers to the technique of mapping a data representation from an object model - to a relational data model with a SQL-based schema; - see <ulink url="http://en.wikipedia.org/wiki/Object-relational_mapping">... - for a discussion. + The term Object/Relational Mapping refers to the technique of mapping data from an object model representation + to a relational data model representation (and visa versa). See <ulink url="http://en.wikipedia.org/wiki/Object-relational_mapping"/> + for a good high-level discussion. </para> <note> @@ -65,27 +64,23 @@ <para> Hibernate not only takes care of the mapping from Java classes to database tables (and from Java data types to - SQL data types), but also provides data query and retrieval facilities. It can also significantly reduce - development time otherwise spent with manual data handling in SQL and JDBC. + SQL data types), but also provides data query and retrieval facilities. It can significantly reduce + development time otherwise spent with manual data handling in SQL and JDBC. Hibernate’s design goal is to + relieve the developer from 95% of common data persistence-related programming tasks by eliminating the need for + manual, hand-crafted data processing using SQL and JDBC. However, unlike many other persistence solutions, + Hibernate does not hide the power of SQL from you and guarantees that your investment in relational technology + and knowledge is as valid as always. </para> <para> - Hibernate’s design goal is to relieve the developer from 95% of common data persistence-related programming - tasks by eliminating the need for manual, hand-crafted data processing using SQL and JDBC. However, unlike - many other persistence solutions, Hibernate does not hide the power of SQL from you and guarantees that your - investment in relational technology and knowledge is as valid as always. + Hibernate may not be the best solution for data-centric applications that only use stored-procedures to + implement the business logic in the database, it is most useful with object-oriented domain models and business + logic in the Java-based middle-tier. However, Hibernate can certainly help you to remove or encapsulate + vendor-specific SQL code and will help with the common task of result set translation from a tabular + representation to a graph of objects. </para> <para> - Hibernate may not be the best solution for data-centric - applications that only use stored-procedures to implement the business logic in the - database, it is most useful with object-oriented domain models and business logic in - the Java-based middle-tier. However, Hibernate can certainly help you to remove or - encapsulate vendor-specific SQL code and will help with the common task of result set - translation from a tabular representation to a graph of objects. - </para> - - <para> If you are new to Hibernate and Object/Relational Mapping or even Java, please follow these steps: </para> Modified: core/trunk/documentation/quickstart/pom.xml =================================================================== --- core/trunk/documentation/quickstart/pom.xml 2010-08-09 19:56:25 UTC (rev 20130) +++ core/trunk/documentation/quickstart/pom.xml 2010-08-10 20:57:50 UTC (rev 20131) @@ -67,7 +67,7 @@ </executions> <configuration> - <sourceDocumentName>Hibernate_QuickStart_Guide.xml</sourceDocumentName> + <sourceDocumentName>Hibernate_Getting_Started_Guide.xml</sourceDocumentName> <masterTranslation>en-US</masterTranslation> <translations> <translation>de-DE</translation> Added: core/trunk/documentation/quickstart/src/main/docbook/en-US/Author_Group.xml =================================================================== --- core/trunk/documentation/quickstart/src/main/docbook/en-US/Author_Group.xml (rev 0) +++ core/trunk/documentation/quickstart/src/main/docbook/en-US/Author_Group.xml 2010-08-10 20:57:50 UTC (rev 20131) @@ -0,0 +1,42 @@ +<?xml version='1.0' encoding='UTF-8' ?> +<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Hibernate_Getting_Started_Guide.ent"> +%BOOK_ENTITIES; +]> + +<authorgroup> + + <author> + <firstname>Gavin</firstname> + <surname>King</surname> + </author> + <author> + <firstname>Christian</firstname> + <surname>Bauer</surname> + </author> + <author> + <firstname>Emmanuel</firstname> + <surname>Bernard</surname> + </author> + <author> + <firstname>Steve</firstname> + <surname>Ebersole</surname> + </author> + + <othercredit> + <firstname>James</firstname> + <surname>Cobb</surname> + <affiliation> + <shortaffil>Graphic Design</shortaffil> + </affiliation> + </othercredit> + + <othercredit> + <firstname>Cheyenne</firstname> + <surname>Weaver</surname> + <affiliation> + <shortaffil>Graphic Design</shortaffil> + </affiliation> + </othercredit> + +</authorgroup> \ No newline at end of file Added: core/trunk/documentation/quickstart/src/main/docbook/en-US/Book_Info.xml =================================================================== --- core/trunk/documentation/quickstart/src/main/docbook/en-US/Book_Info.xml (rev 0) +++ core/trunk/documentation/quickstart/src/main/docbook/en-US/Book_Info.xml 2010-08-10 20:57:50 UTC (rev 20131) @@ -0,0 +1,31 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Hibernate_Getting_Started_Guide.ent"> +%BOOK_ENTITIES; +]> + +<bookinfo id="Hibernate_Getting_Started_Guide"> + <title>Hibernate Getting Started Guide</title> + <releaseinfo>&version;</releaseinfo> + <edition>1.0</edition> + <pubsnumber>1</pubsnumber> + <productname>JBoss Hibernate Core</productname> + <productnumber>&version;</productnumber> + <pubdate>&today;</pubdate> + <issuenum>1</issuenum> + <mediaobject> + <imageobject role="fo"> + <imagedata fileref="images/hibernate_logo_a.png" align="center" /> + </imageobject> + <imageobject role="html"> + <imagedata fileref="images/hibernate_logo_a.png" depth="3cm" /> + </imageobject> + </mediaobject> + <copyright> + <year>&copyrightYear;</year> + <holder>&copyrightHolder;</holder> + </copyright> + + <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + +</bookinfo> Copied: core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.ent (from rev 20118, core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_QuickStart_Guide.ent) =================================================================== --- core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.ent (rev 0) +++ core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.ent 2010-08-10 20:57:50 UTC (rev 20131) @@ -0,0 +1,5 @@ +<!ENTITY version "WORKING"> +<!ENTITY today "TODAY"> +<!ENTITY copyrightYear "2004"> +<!ENTITY copyrightHolder "Red Hat, Inc."> +<!ENTITY semi ";"> Copied: core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml (from rev 20118, core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_QuickStart_Guide.xml) =================================================================== --- core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml (rev 0) +++ core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml 2010-08-10 20:57:50 UTC (rev 20131) @@ -0,0 +1,18 @@ +<?xml version='1.0' encoding='UTF-8' ?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ + <!ENTITY % BOOK_ENTITIES SYSTEM "Hibernate_Getting_Started_Guide.ent"> + %BOOK_ENTITIES; +]> + +<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" /> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/community.xml" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/obtaining.xml" /> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/tutorial_native.xml" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/tutorial_annotations.xml" /> + + +</book> \ No newline at end of file Deleted: core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_QuickStart_Guide.ent =================================================================== --- core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_QuickStart_Guide.ent 2010-08-09 19:56:25 UTC (rev 20130) +++ core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_QuickStart_Guide.ent 2010-08-10 20:57:50 UTC (rev 20131) @@ -1,5 +0,0 @@ -<!ENTITY version "WORKING"> -<!ENTITY today "TODAY"> -<!ENTITY copyrightYear "2004"> -<!ENTITY copyrightHolder "Red Hat, Inc."> -<!ENTITY semi ";"> Deleted: core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_QuickStart_Guide.xml =================================================================== --- core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_QuickStart_Guide.xml 2010-08-09 19:56:25 UTC (rev 20130) +++ core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_QuickStart_Guide.xml 2010-08-10 20:57:50 UTC (rev 20131) @@ -1,253 +0,0 @@ -<?xml version='1.0' encoding='UTF-8' ?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ - <!ENTITY % BOOK_ENTITIES SYSTEM "Hibernate_QuickStart_Guide.ent"> - %BOOK_ENTITIES; -]> - -<book> - <bookinfo id="Hibernate_QuickStart_Guide"> - <title>Hibernate QuickStart Guide</title> - <releaseinfo>&version;</releaseinfo> - <edition>1.0</edition> - <pubsnumber>1</pubsnumber> - <productname>JBoss Hibernate Core</productname> - <productnumber>&version;</productnumber> - <pubdate>&today;</pubdate> - <issuenum>1</issuenum> - <mediaobject> - <imageobject role="fo"> - <imagedata fileref="images/hibernate_logo_a.png" align="center" /> - </imageobject> - <imageobject role="html"> - <imagedata fileref="images/hibernate_logo_a.png" depth="3cm" /> - </imageobject> - </mediaobject> - <copyright> - <year>&copyrightYear;</year> - <holder>&copyrightHolder;</holder> - </copyright> - </bookinfo> - - <!-- todo : preface --> - - <chapter id="hibernate-qs-setup"> - <title>Obtaining Hibernate</title> - - <para> - There are 2 very different ways to "obtain" Hibernate... - </para> - - <section id="hibernate-qs-setup-releaseBundle"> - <title>Release Bundle Downloads</title> - <para> - The Hibernate team provides release bundles hosted on the SourceForge File Release System, which contain - jars, documentation, source code, etc. To obtain the release bundles go to - <ulink url="http://sourceforge.net/projects/hibernate/files/hibernate3/&quo...;, - navigate to the release in which you are interested and select whichever format you prefer. - </para> - <itemizedlist> - <listitem> - <para> - <filename>hibernate3.jar</filename> is an aggregation of all the Hibernate Core classes. - This would need to be part of your project classpath. - </para> - </listitem> - <listitem> - <para> - The <filename>lib/required</filename> directory contains jars that are - <emphasis>required</emphasis> for Hibernate to run. All the jars in this directory would need - to be part of your project classpath as well. - </para> - <important> - <para> - The slf4j jar is special in that you still need further jar file(s) for it to work correctly. - Which jar(s) depends on which logging back-end you want to use. See the - <ulink url="http://slf4j.org/">slf4j site</ulink> for details. - </para> - </important> - </listitem> - <listitem> - <para> - The <filename>/lib/jpa</filename> directory contains the - <ulink url="http://jcp.org/en/jsr/detail?id=317">JPA</ulink> API jar. If you want to use the - JPA APIs or JPA annotations, this jar will need to be part of your project classpath too. - </para> - </listitem> - <listitem> - <para> - The <filename>/lib/optional</filename> directory contains jar files needed when utilizing various - (optional) integrations with Hibernate. These are beyond the scope of this guide, but are - mentioned for completeness. If you were to use any of these features the appropriate jars from here - would need to also be part of your project's classpath (though generally speaking these are only needed - for runtime, not compile-time). - </para> - </listitem> - </itemizedlist> - </section> - - <section id="hibernate-qs-setup-mavenRepoArtifacts"> - <title>Maven Repository Artifacts</title> - <important> - <para> - The authoritative repository for Hibernate artifacts is the JBoss - Maven repository. The team responsible for the JBoss Maven repository maintains a number of wiki - pages that contain important information: - <itemizedlist> - <listitem> - <para> - <ulink url="http://community.jboss.org/docs/DOC-14900">http://commu... - - contains general information about the repository - </para> - </listitem> - <listitem> - <para> - <ulink url="http://community.jboss.org/docs/DOC-15170">http://commu... - - contains information about setting up access to the repository for <emphasis>developers</emphasis> - (aka, developers working on Hibernate or JBoss projects). - </para> - </listitem> - <listitem> - <para> - <ulink url="http://community.jboss.org/docs/DOC-15169">http://commu... - - contains information about setting up access to the repository for <emphasis>users</emphasis> - (aka, consumers of Hibernate or JBoss projects). - </para> - </listitem> - </itemizedlist> - </para> - </important> - <para> - Hibernate produces a number of artifacts (all under the org.hibernate groupId): - <itemizedlist> - <listitem> - <para> - <emphasis>hibernate-core</emphasis> - This is the main artifact. It contains all the - Hibernate classes (<package>org.hibernate</package>) needed to build applications using - the native Hibernate APIs. It includes capabilities for using native Hibernate mapping - (<filename>hbm.xml</filename>) files as well as annotations. - </para> - </listitem> - <listitem> - <para> - <emphasis>hibernate-entitymanager</emphasis> - Hibernate provides an implementation of - <ulink url="http://jcp.org/en/jsr/detail?id=317">JPA</ulink>;. This is the artifact that - represents this JPA implementation. - </para> - <para> - This artifact depends on <emphasis>hibernate-core</emphasis>. - </para> - </listitem> - <listitem> - <para> - <emphasis>hibernate-envers</emphasis> - Envers is an optional module that - provides historical auditing of changes to your entities. - </para> - <para> - This artifact depends on both <emphasis>hibernate-core</emphasis> and - <emphasis>hibernate-entitymanager</emphasis>. - </para> - </listitem> - <listitem> - <para> - <emphasis>hibernate-c3p0</emphasis> - Represents the integration between Hibernate - and the <ulink url="http://sourceforge.net/projects/c3p0/">C3P0</ulink> connection pool - library. - </para> - <para> - This artifact depends on <emphasis>hibernate-core</emphasis>; however it would generally - be included in a project as a runtime dependency (rarely would you need to bind against - these classes at compile time). It also pulls in the C3P0 dependencies. - be - </para> - </listitem> - <listitem> - <para> - <emphasis>hibernate-proxool</emphasis> - Represents the integration between Hibernate - and the <ulink url="http://proxool.sourceforge.net/">Proxool</ulink> connection pool - library. - </para> - <para> - This artifact depends on <emphasis>hibernate-core</emphasis>; however it would generally - be included in a project as a runtime dependency (rarely would you need to bind against - these classes at compile time). It also pulls in the Proxool dependencies. - </para> - </listitem> - <listitem> - <para> - <emphasis>hibernate-ehcache</emphasis> - Represents the integration between Hibernate - and <ulink url="http://ehcache.sourceforge.net/">EhCache</ulink> as a second level cache - implementation. - </para> - <para> - This artifact depends on <emphasis>hibernate-core</emphasis>; however it would generally - be included in a project as a runtime dependency (rarely would you need to bind against - these classes at compile time). It also pulls in the Ehcache dependencies. - </para> - </listitem> - <listitem> - <para> - <emphasis>hibernate-infinispan</emphasis> - Represents the integration between Hibernate - and <ulink url="http://jboss.org/infinispan">Infinispan</ulink> as a second level cache - implementation. - </para> - <para> - This artifact depends on <emphasis>hibernate-core</emphasis>; however it would generally - be included in a project as a runtime dependency (rarely would you need to bind against - these classes at compile time). It also pulls in the Infinispan dependencies. - </para> - </listitem> - <listitem> - <para> - <emphasis>hibernate-jbosscache</emphasis> - Represents the integration between Hibernate - and <ulink url="http://jboss.org/jbosscache">JBossCache</ulink> as a second level cache - implementation. - </para> - <para> - This artifact depends on <emphasis>hibernate-core</emphasis>; however it would generally - be included in a project as a runtime dependency (rarely would you need to bind against - these classes at compile time). It also pulls in the JBossCache dependencies - </para> - </listitem> - <listitem> - <para> - <emphasis>hibernate-oscache</emphasis> - Represents the integration between Hibernate - and <ulink url="http://www.opensymphony.com/oscache/">OSCache</ulink... as a second level cache - implementation. - </para> - <para> - This artifact depends on <emphasis>hibernate-core</emphasis>; however it would generally - be included in a project as a runtime dependency (rarely would you need to bind against - these classes at compile time). It also pulls in the OSCache dependencies. - </para> - </listitem> - <listitem> - <para> - <emphasis>hibernate-swarmcache</emphasis> - Represents the integration between Hibernate - and <ulink url="http://swarmcache.sourceforge.net/">SwarmCache</ulin... as a second level cache - implementation. - </para> - <para> - This artifact depends on <emphasis>hibernate-core</emphasis>; however it would generally - be included in a project as a runtime dependency (rarely would you need to bind against - these classes at compile time). It also pulls in the SwarmCache dependencies. - </para> - </listitem> - </itemizedlist> - </para> - </section> - </chapter> - - <chapter id="hibernate-qs-keyConcepts"> - <title>Key Concepts</title> - <para> - Discuss some key concepts such as Configuration, SessionFactory, Session (?and Transaction?). - </para> - </chapter> - - <chapter id="hibernate-qs-nextSteps"> - <title>Next Steps</title> - <para> - go on to tutorials; community links - </para> - </chapter> -</book> \ No newline at end of file Added: core/trunk/documentation/quickstart/src/main/docbook/en-US/content/community.xml =================================================================== --- core/trunk/documentation/quickstart/src/main/docbook/en-US/content/community.xml (rev 0) +++ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/community.xml 2010-08-10 20:57:50 UTC (rev 20131) @@ -0,0 +1,42 @@ +<?xml version='1.0' encoding='UTF-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> + +<chapter id="hibernate-gsg-community"> + <title>Hibernate Community</title> + + <para> + There are a number of ways to become involved in the Hibernate community, including + <itemizedlist> + <listitem> + <para> + Trying stuff out and reporting bugs. See <ulink url="http://hibernate.org/issuetracker.html"/> for + details. + </para> + </listitem> + <listitem> + <para> + Trying your hand at fixing some bugs or implementing enhancements. Again, see + <ulink url="http://hibernate.org/issuetracker.html"/>;. + </para> + </listitem> + <listitem> + <para> + <ulink url="http://hibernate.org/community.html"/> lists a number of ways to engage in the community + including mailing lists, forums, IRC and others. + </para> + </listitem> + <listitem> + <para> + Helping improve or translate this documentation. Contact us on the developer mailing list + if you have interest. + </para> + </listitem> + <listitem> + <para> + Evangelizing Hibernate within your organization. + </para> + </listitem> + </itemizedlist> + </para> + +</chapter> Added: core/trunk/documentation/quickstart/src/main/docbook/en-US/content/obtaining.xml =================================================================== --- core/trunk/documentation/quickstart/src/main/docbook/en-US/content/obtaining.xml (rev 0) +++ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/obtaining.xml 2010-08-10 20:57:50 UTC (rev 20131) @@ -0,0 +1,204 @@ +<?xml version='1.0' encoding='UTF-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> + + +<chapter id="hibernate-gsg-obtain"> + <title>Obtaining Hibernate</title> + + <para> + You obtain Hibernate in one of two anticipated ways. + </para> + + <section id="hibernate-gsg-setup-releaseBundle"> + <title>Release Bundle Downloads</title> + <para> + The Hibernate team provides release bundles hosted on the SourceForge File Release System, both in + <literal>ZIP</literal> and <literal>TGZ</literal> formats. A release bundle contains <literal>JARs</literal>, + documentation, source code, and other information. + </para> + <para> + Navigate to <ulink url="http://sourceforge.net/projects/hibernate/files/hibernate3/&quo... and download the + desired release from the list, in your format of choice. + </para> + <itemizedlist> + <listitem> + <para> + <filename>hibernate3.jar</filename> is an aggregation of all the Hibernate Core classes. + This would need to be part of your project classpath. + </para> + </listitem> + <listitem> + <para> + The <filename>lib/required</filename> directory contains jars that are + <emphasis>required</emphasis> for Hibernate to run. All the jars in this directory would need + to be part of your project classpath as well. + </para> + <important> + <para> + The slf4j jar is special in that you still need further jar file(s) for it to work correctly. + Which jar(s) depends on which logging back-end you want to use. See the + <ulink url="http://slf4j.org/">slf4j site</ulink> for details. + </para> + </important> + </listitem> + <listitem> + <para> + The <filename>/lib/jpa</filename> directory contains the + <ulink url="http://jcp.org/en/jsr/detail?id=317">JPA</ulink> API jar. If you want to use the + JPA APIs or JPA annotations, this jar will need to be part of your project classpath too. + </para> + </listitem> + </itemizedlist> + </section> + + <section id="hibernate-gsg-setup-mavenRepoArtifacts"> + <title>Maven Repository Artifacts</title> + <important> + <para> + The authoritative repository for Hibernate artifacts is the JBoss + Maven repository. The team responsible for the JBoss Maven repository maintains a number of wiki + pages that contain important information: + <itemizedlist> + <listitem> + <para> + <ulink url="http://community.jboss.org/docs/DOC-14900">http://commu... - + contains general information about the repository + </para> + </listitem> + <listitem> + <para> + <ulink url="http://community.jboss.org/docs/DOC-15170">http://commu... - + contains information about setting up access to the repository for <emphasis>developers</emphasis> + (aka, developers working on Hibernate or JBoss projects). + </para> + </listitem> + <listitem> + <para> + <ulink url="http://community.jboss.org/docs/DOC-15169">http://commu... - + contains information about setting up access to the repository for <emphasis>users</emphasis> + (aka, consumers of Hibernate or JBoss projects). + </para> + </listitem> + </itemizedlist> + </para> + </important> + <para> + Hibernate produces a number of artifacts (all under the org.hibernate groupId): + <itemizedlist> + <listitem> + <para> + <emphasis>hibernate-core</emphasis> - This is the main artifact. It contains all the + Hibernate classes (<package>org.hibernate</package>) needed to build applications using + the native Hibernate APIs. It includes capabilities for using native Hibernate mapping + (<filename>hbm.xml</filename>) files as well as annotations. + </para> + </listitem> + <listitem> + <para> + <emphasis>hibernate-entitymanager</emphasis> - Hibernate provides an implementation of + <ulink url="http://jcp.org/en/jsr/detail?id=317">JPA</ulink>;. This is the artifact that + represents this JPA implementation. + </para> + <para> + This artifact depends on <emphasis>hibernate-core</emphasis>. + </para> + </listitem> + <listitem> + <para> + <emphasis>hibernate-envers</emphasis> - Envers is an optional module that + provides historical auditing of changes to your entities. + </para> + <para> + This artifact depends on both <emphasis>hibernate-core</emphasis> and + <emphasis>hibernate-entitymanager</emphasis>. + </para> + </listitem> + <listitem> + <para> + <emphasis>hibernate-c3p0</emphasis> - Represents the integration between Hibernate + and the <ulink url="http://sourceforge.net/projects/c3p0/">C3P0</ulink> connection pool + library. + </para> + <para> + This artifact depends on <emphasis>hibernate-core</emphasis>; however it would generally + be included in a project as a runtime dependency (rarely would you need to bind against + these classes at compile time). It also pulls in the C3P0 dependencies. + be + </para> + </listitem> + <listitem> + <para> + <emphasis>hibernate-proxool</emphasis> - Represents the integration between Hibernate + and the <ulink url="http://proxool.sourceforge.net/">Proxool</ulink> connection pool + library. + </para> + <para> + This artifact depends on <emphasis>hibernate-core</emphasis>; however it would generally + be included in a project as a runtime dependency (rarely would you need to bind against + these classes at compile time). It also pulls in the Proxool dependencies. + </para> + </listitem> + <listitem> + <para> + <emphasis>hibernate-ehcache</emphasis> - Represents the integration between Hibernate + and <ulink url="http://ehcache.sourceforge.net/">EhCache</ulink> as a second level cache + implementation. + </para> + <para> + This artifact depends on <emphasis>hibernate-core</emphasis>; however it would generally + be included in a project as a runtime dependency (rarely would you need to bind against + these classes at compile time). It also pulls in the Ehcache dependencies. + </para> + </listitem> + <listitem> + <para> + <emphasis>hibernate-infinispan</emphasis> - Represents the integration between Hibernate + and <ulink url="http://jboss.org/infinispan">Infinispan</ulink> as a second level cache + implementation. + </para> + <para> + This artifact depends on <emphasis>hibernate-core</emphasis>; however it would generally + be included in a project as a runtime dependency (rarely would you need to bind against + these classes at compile time). It also pulls in the Infinispan dependencies. + </para> + </listitem> + <listitem> + <para> + <emphasis>hibernate-jbosscache</emphasis> - Represents the integration between Hibernate + and <ulink url="http://jboss.org/jbosscache">JBossCache</ulink> as a second level cache + implementation. + </para> + <para> + This artifact depends on <emphasis>hibernate-core</emphasis>; however it would generally + be included in a project as a runtime dependency (rarely would you need to bind against + these classes at compile time). It also pulls in the JBossCache dependencies + </para> + </listitem> + <listitem> + <para> + <emphasis>hibernate-oscache</emphasis> - Represents the integration between Hibernate + and <ulink url="http://www.opensymphony.com/oscache/">OSCache</ulink... as a second level cache + implementation. + </para> + <para> + This artifact depends on <emphasis>hibernate-core</emphasis>; however it would generally + be included in a project as a runtime dependency (rarely would you need to bind against + these classes at compile time). It also pulls in the OSCache dependencies. + </para> + </listitem> + <listitem> + <para> + <emphasis>hibernate-swarmcache</emphasis> - Represents the integration between Hibernate + and <ulink url="http://swarmcache.sourceforge.net/">SwarmCache</ulin... as a second level cache + implementation. + </para> + <para> + This artifact depends on <emphasis>hibernate-core</emphasis>; however it would generally + be included in a project as a runtime dependency (rarely would you need to bind against + these classes at compile time). It also pulls in the SwarmCache dependencies. + </para> + </listitem> + </itemizedlist> + </para> + </section> +</chapter> \ No newline at end of file Added: core/trunk/documentation/quickstart/src/main/docbook/en-US/content/preface.xml =================================================================== --- core/trunk/documentation/quickstart/src/main/docbook/en-US/content/preface.xml (rev 0) +++ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/preface.xml 2010-08-10 20:57:50 UTC (rev 20131) @@ -0,0 +1,88 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Hibernate, Relational Persistence for Idiomatic Java + ~ + ~ Copyright (c) 2010, Red Hat Inc. or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Inc. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program is distributed in the hope that it will be useful, + ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License + ~ for more details. + ~ + ~ You should have received a copy of the GNU Lesser General Public License + ~ along with this distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> + +<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "../Hibernate_Getting_Started_Guide.ent"> +%BOOK_ENTITIES; + +]> + +<preface id="hibernate-gsg-preface"> + <title>Preface</title> + + <!-- + NOTE : This duplicates a lot of the information in the manual preface. This is a great example of where the + "content reuse" capabilities of DITA could be leveraged. + --> + + <para> + Working with both Object-Oriented software and Relational Databases can be cumbersome and time consuming. + Development costs are significantly higher due to a paradigm mismatch between how data is represented in + objects versus relational databases. Hibernate is an Object/Relational Mapping solution for Java environments. + The term Object/Relational Mapping refers to the technique of mapping data from an object model representation + to a relational data model representation (and visa versa). See + <ulink url="http://en.wikipedia.org/wiki/Object-relational_mapping"/> for a good high-level discussion. + </para> + + <note> + <para> + While having a strong background in SQL is not required to use Hibernate, having a basic understanding of + the concepts can greatly help you understand Hibernate more fully and quickly. Probably the single + best background is an understanding of data modeling principles. You might want to consider these resources + as a good starting point: + <itemizedlist> + <listitem> + <para> + <ulink url="http://www.agiledata.org/essays/dataModeling101.html"/> + </para> + </listitem> + <listitem> + <para> + <ulink url="http://en.wikipedia.org/wiki/Data_modeling"/> + </para> + </listitem> + </itemizedlist> + </para> + </note> + + <para> + Hibernate not only takes care of the mapping from Java classes to database tables (and from Java data types to + SQL data types), but also provides data query and retrieval facilities. It can significantly reduce + development time otherwise spent with manual data handling in SQL and JDBC. Hibernate’s design goal is to + relieve the developer from 95% of common data persistence-related programming tasks by eliminating the need for + manual, hand-crafted data processing using SQL and JDBC. However, unlike many other persistence solutions, + Hibernate does not hide the power of SQL from you and guarantees that your investment in relational technology + and knowledge is as valid as always. + </para> + + <para> + Hibernate may not be the best solution for data-centric applications that only use stored-procedures to + implement the business logic in the database, it is most useful with object-oriented domain models and business + logic in the Java-based middle-tier. However, Hibernate can certainly help you to remove or encapsulate + vendor-specific SQL code and will help with the common task of result set translation from a tabular + representation to a graph of objects. + </para> + +</preface> Added: core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml =================================================================== --- core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml (rev 0) +++ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml 2010-08-10 20:57:50 UTC (rev 20131) @@ -0,0 +1,17 @@ +<?xml version='1.0' encoding='UTF-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> + +<chapter id="hibernate-gsg-tutorial-annotations"> + <title>Tutorial Using Native Hibernate APIs and annotations</title> + + <para> + This tutorial introduces some key concepts of the native Hibernate API. + </para> + <itemizedlist> + <listitem> + <para> + + </para> + </listitem> + </itemizedlist> +</chapter> \ No newline at end of file Added: 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 (rev 0) +++ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml 2010-08-10 20:57:50 UTC (rev 20131) @@ -0,0 +1,519 @@ +<?xml version='1.0' encoding='UTF-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> + +<chapter id="hibernate-gsg-tutorial-native"> + <title>Tutorial Using Native Hibernate APIs and <filename>hbm.xml</filename> mappings</title> + + <note> + <para> + This tutorial will use the "standard layout" advocated by many build tools and best practices. + <ulink url="http://maven.apache.org/guides/introduction/introduction-to-the... + provides a good description of the "standard layout" if you are unfamiliar. + </para> + </note> + + <tip> + <para> + The tutorials in this guide utilize Maven, taking advantage of its transitive dependency management + capabilities as well as the ability of many IDEs to automatically set up a project based on the Maven + descriptor. Just be aware that it is not a requirement to use Maven as your build tool in order to use + Hibernate. + </para> + </tip> + + <procedure> + <title>Steps</title> + + <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 with the + following contents + </para> + <example id="hibernate-gsg-tutorial-native-pom-ex1"> + <title><filename>pom.xml</filename></title> + <programlisting role="XML"><![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>]]></programlisting> + </example> + </step> + + <step id="hibernate-gsg-tutorial-native-entity"> + <title>Write the entity Java class</title> + + <para> + Create a file named <filename>src/main/java/org/hibernate/tutorial/native/Event.java</filename> + with the following contents: + </para> + + <example id="hibernate-gsg-tutorial-native-entity-ex1"> + <title><filename>Entity.java</filename></title> + <programlisting role="JAVA"><![CDATA[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; + } + }]]></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>" --> + A few things to notice about the entity + <itemizedlist> + <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 the + recommended design, it is not required. + </para> + </listitem> + <listitem> + <para> + The no-argument constructor (also a JavaBean convention) is a requirement for all + persistent classes. Hibernate has to create objects for you, using Java Reflection. The + constructor could be private, however package or public visibility is required for runtime + proxy generation and efficient data retrieval without bytecode instrumentation. + </para> + </listitem> + </itemizedlist> + </para> + </step> + + <step id="hibernate-gsg-tutorial-native-mapping"> + <title>Write the entity mapping file</title> + + <para> + Create a file named <filename>src/main/resources/org/hibernate/tutorial/native/Event.hbm.xml</filename> + with the following contents: + </para> + + <example> + <title><filename>Event.hbm.xml</filename></title> + <programlisting role="XML"><![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>]]></programlisting> + </example> + + <para> + Hibernate needs to know how to load and store objects of the persistent class. This is where the + "mapping metadata" comes into play. The Hibernate mapping file is one choice for providing Hibernate + with this metadata. + </para> + + <para> + The <literal>class</literal> element here is doing 2 things. + <orderedlist> + <listitem> + <para> + The <literal>class</literal> attribute (here combined with the <literal>package</literal> + attribute from the containing <literal>hibernate-mapping</literal> element) names the FQN + of the class we 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> + <para> + Instances of <classname>Event</classname> are now "mapped" to rows in the <literal>EVENTS</literal> table. + But an assumption there is that Hibernate knows how to uniquely identify rows in the table. This is the + purpose of the <literal>id</literal> element. It names the column(s) which uniquely identify each row. + </para> + <note> + <para> + It is not strictly necessary that the <literal>id</literal> element map to the table's + actual primary key column(s); however that is the normal convention. Nor is it strictly + necessary that tables mapped in Hibernate even define primary keys, the Hibernate team + <emphasis>highly</emphasis> recommends all schemas define proper referential integrity. + Therefore <literal>id</literal> and primary key are used interchangeably throughout Hibernate + documentation. + </para> + </note> + <para> + The <literal>id</literal> element here identifies the <literal>EVENT_ID</literal> column as the primary + key of the <literal>EVENTS</literal> table. Further, it names the <literal>id</literal> property of + the <classname>Event</classname> class is the property to hold the identifier value. + </para> + <para> + In regards to the <literal>generator</literal> element nested inside the <literal>id</literal> element, + for now just be aware that it tells Hibernate the strategy used to generated primary key values for + this entity. Here we are telling it to use a sequence-like value generation. + </para> + <para> + The 2 <literal>property</literal> elements are declaring the remaining 2 properties of the + <classname>Event</classname> class: <literal>date</literal> and <literal>title</literal>. Notice + that the <literal>date</literal> property mapping include the <literal>column</literal> + attribute, but the <literal>title</literal> does not. Without the <literal>column</literal> + attribute, Hibernate by default uses the property name as the column name. This works for + <literal>title</literal>, however, <literal>date</literal> is a reserved keyword in most databases + so you will need to explicitly tell Hibernate the column name in this case. + </para> + <para> + The <literal>title</literal> mapping also lacks a <literal>type</literal> attribute. The + types declared and used in the mapping files are not Java data types; they are not SQL + database types either. These types are called <emphasis>Hibernate mapping types</emphasis>, + converters which can translate from Java to SQL data types and vice versa. Hibernate will try to + determine the correct conversion and mapping type itself 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. In some cases this automatic detection might not + have the default you expect or need. This is the case 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 with 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, so if startup performance is important + you should consider explicitly defining the type to use. + </para> + </tip> + + </step> + + <step id="hibernate-gsg-tutorial-native-config"> + <title>Create a Hibernate configuration file</title> + + <para> + 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> + </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 + to pool. + </para> + + <caution> + <para> + 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> + + <para> + The <literal>dialect</literal> option specifies the particular SQL variant Hibernate should generate. + </para> + + <tip> + <para> + 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. + </para> + <para> + Finally, add the mapping file(s) for persistent classes to the configuration. + </para> + </step> + + <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> + 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> + </example> + + <para> + 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"/>. + </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. + </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> + 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 + 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 + appropriate <literal>SELECT</literal> SQL, send it to the database and populate + <classname>Event</classname> objects with the result set data. + </para> + </step> + + <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> + </step> + + <step id="hibernate-gsg-tutorial-native-running"> + <title>Running the code</title> + <para> + To perform a store (leveraging the maven exec plugin): + <command>mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.native.EventManager" -Dexec.args="store"</command> + 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. + </para> + + <para> + To perform a list: + <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 + </para> + </note> + </step> + </procedure> + + <para> + Take it further! Try the following: + <itemizedlist> + <listitem> + <para> + Reconfigure the examples to connect to your own persistent relational database. + </para> + </listitem> + <listitem> + <para> + With help of the Developer Guide, add an association to the <classname>Event</classname> entity + to model a message thread. + </para> + </listitem> + </itemizedlist> + </para> + +</chapter> \ No newline at end of file