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@20118 1b8cb986-b30d-0410-93ca-fae66ebed9b2
This commit is contained in:
Steve Ebersole 2010-08-06 21:34:44 +00:00
parent 8329e0e3c5
commit 99b111d613
5 changed files with 351 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
documentation/pom.xml
View File

@ -20,7 +20,8 @@
<modules>
<module>manual</module>
<module>envers</module>
<!--
<module>quickstart</module>
<!--
<module>jbosscache2</module>
-->
</modules>

91
documentation/quickstart/pom.xml Normal file
View File

@ -0,0 +1,91 @@
<?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
-->
<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>
<parent>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-parent</artifactId>
<version>3.6.0-SNAPSHOT</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<artifactId>hibernate-quickstart</artifactId>
<packaging>jdocbook</packaging>
<name>Hibernate QuickStart Guide</name>
<description>A QuickStart guide for getting up and started quickly using Hibernate</description>
<build>
<plugins>
<plugin>
<groupId>org.jboss.maven.plugins</groupId>
<artifactId>maven-jdocbook-plugin</artifactId>
<executions>
<execution>
<!--
here we are attaching the translate goal so that the translations are processed
before compilation so that the transated XML is also transformed during
generation
-->
<phase>process-resources</phase>
<goals>
<goal>translate</goal>
</goals>
</execution>
</executions>
<configuration>
<sourceDocumentName>Hibernate_QuickStart_Guide.xml</sourceDocumentName>
<masterTranslation>en-US</masterTranslation>
<translations>
<translation>de-DE</translation>
<translation>es-ES</translation>
<translation>fr-FR</translation>
<translation>ja-JP</translation>
<!-- <translation>ko-KR</translation> -->
<translation>pt-BR</translation>
<translation>zh-CN</translation>
</translations>
<imageResource>
<directory>${basedir}/src/main/docbook/en-US</directory>
<excludes>
<exclude>*.xml</exclude>
<exclude>**/*.xml</exclude>
<exclude>*.zargo</exclude>
<exclude>**/*.zargo</exclude>
</excludes>
</imageResource>
</configuration>
</plugin>
</plugins>
</build>
</project>

5
documentation/quickstart/src/main/docbook/en-US/Hibernate_QuickStart_Guide.ent Normal file
View File

@ -0,0 +1,5 @@
<!ENTITY version "WORKING">
<!ENTITY today "TODAY">
<!ENTITY copyrightYear "2004">
<!ENTITY copyrightHolder "Red Hat, Inc.">
<!ENTITY semi ";">

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

@ -0,0 +1,253 @@
<?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>

BIN
documentation/quickstart/src/main/docbook/en-US/images/hibernate_logo_a.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 31 KiB