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>©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/&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