Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

HHH-5442 - Create a "quick start" guide 

git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@20131 1b8cb986-b30d-0410-93ca-fae66ebed9b2
This commit is contained in:
Steve Ebersole 2010-08-10 20:57:50 +00:00
parent 609a8d15c2
commit 8c9c64b1eb
12 changed files with 977 additions and 274 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
documentation/manual/src/main/docbook/en-US/content/preface.xml
View File

@ -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,24 +64,20 @@
<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.
</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.
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>

2
documentation/quickstart/pom.xml
View File

@ -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>

42
documentation/quickstart/src/main/docbook/en-US/Author_Group.xml Normal file
View File

@ -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>

31
documentation/quickstart/src/main/docbook/en-US/Book_Info.xml Normal file
View File

@ -0,0 +1,31 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Hibernate_Getting_Started_Guide.ent">
%BOOK_ENTITIES;
]>
<bookinfo id="Hibernate_Getting_Started_Guide">
<title>Hibernate Getting Started Guide</title>
<releaseinfo>&version;</releaseinfo>
<edition>1.0</edition>
<pubsnumber>1</pubsnumber>
<productname>JBoss Hibernate Core</productname>
<productnumber>&version;</productnumber>
<pubdate>&today;</pubdate>
<issuenum>1</issuenum>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="images/hibernate_logo_a.png" align="center" />
</imageobject>
<imageobject role="html">
<imagedata fileref="images/hibernate_logo_a.png" depth="3cm" />
</imageobject>
</mediaobject>
<copyright>
<year>&copyrightYear;</year>
<holder>&copyrightHolder;</holder>
</copyright>
<xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</bookinfo>

0
documentation/quickstart/src/main/docbook/en-US/Hibernate_QuickStart_Guide.ent → documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.ent
View File

18
documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml Normal file
View File

@ -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>

253
documentation/quickstart/src/main/docbook/en-US/Hibernate_QuickStart_Guide.xml
View File

@ -1,253 +0,0 @@
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Hibernate_QuickStart_Guide.ent">
%BOOK_ENTITIES;
]>
<book>
<bookinfo id="Hibernate_QuickStart_Guide">
<title>Hibernate QuickStart Guide</title>
<releaseinfo>&version;</releaseinfo>
<edition>1.0</edition>
<pubsnumber>1</pubsnumber>
<productname>JBoss Hibernate Core</productname>
<productnumber>&version;</productnumber>
<pubdate>&today;</pubdate>
<issuenum>1</issuenum>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="images/hibernate_logo_a.png" align="center" />
</imageobject>
<imageobject role="html">
<imagedata fileref="images/hibernate_logo_a.png" depth="3cm" />
</imageobject>
</mediaobject>
<copyright>
<year>&copyrightYear;</year>
<holder>&copyrightHolder;</holder>
</copyright>
</bookinfo>
<!-- todo : preface -->
<chapter id="hibernate-qs-setup">
<title>Obtaining Hibernate</title>
<para>
There are 2 very different ways to "obtain" Hibernate...
</para>
<section id="hibernate-qs-setup-releaseBundle">
<title>Release Bundle Downloads</title>
<para>
The Hibernate team provides release bundles hosted on the SourceForge File Release System, which contain
jars, documentation, source code, etc. To obtain the release bundles go to
<ulink url="http://sourceforge.net/projects/hibernate/files/hibernate3/">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>

42
documentation/quickstart/src/main/docbook/en-US/content/community.xml Normal file
View File

@ -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>

204
documentation/quickstart/src/main/docbook/en-US/content/obtaining.xml Normal file
View File

@ -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>

88
documentation/quickstart/src/main/docbook/en-US/content/preface.xml Normal file
View File

@ -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>

17
documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml Normal file
View File

@ -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>

519
documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml Normal file
View File

@ -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>