[hibernate-commits] Hibernate SVN: r20131 - in core/trunk/documentation: quickstart and 2 other directories.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Tue Aug 10 16:57:51 EDT 2010
Author: steve.ebersole at 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">http://en.wikipedia.org/wiki/Object-relational_mapping</ulink>
- 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>©rightYear;</year>
+ <holder>©rightHolder;</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>©rightYear;</year>
- <holder>©rightHolder;</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/">http://sourceforge.net/projects/hibernate/files/hibernate3/</ulink>,
- 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://community.jboss.org/docs/DOC-14900</ulink> -
- contains general information about the repository
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="http://community.jboss.org/docs/DOC-15170">http://community.jboss.org/docs/DOC-15170</ulink> -
- 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://community.jboss.org/docs/DOC-15169</ulink> -
- 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</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 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/"/> 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://community.jboss.org/docs/DOC-14900</ulink> -
+ contains general information about the repository
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://community.jboss.org/docs/DOC-15170">http://community.jboss.org/docs/DOC-15170</ulink> -
+ 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://community.jboss.org/docs/DOC-15169</ulink> -
+ 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</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 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-standard-directory-layout.html"/>
+ 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
More information about the hibernate-commits
mailing list