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

Edits to the Getting Started Guide 

git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@20307 1b8cb986-b30d-0410-93ca-fae66ebed9b2
This commit is contained in:
misty 2010-09-03 06:55:53 +00:00
parent dbcced88aa
commit 6299d0845b
3 changed files with 237 additions and 195 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml
View File

@ -11,10 +11,13 @@
<part label="I"> <part label="I">
<title>Basic Information</title> <title>Basic Information</title>
<partintro> <partintro>
<!-- Don't refer to things by Part #, because things could be re-ordered later
<para> <para>
The sections in Part I present basic information you will The sections in Part I present basic information you will
likely need to get started utilizing Hibernate likely need to get started utilizing Hibernate
</para> </para>
-->
<para>Set up and begin using Hibernate.</para>
</partintro> </partintro>
<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/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/obtaining.xml" />
@ -23,11 +26,16 @@
<part label="II"> <part label="II">
<title>Tutorials</title> <title>Tutorials</title>
<partintro> <partintro>
<!--
<para> <para>
The sections in Part II dive into illustrative examples of using Hibernate in various The sections in Part II dive into illustrative examples of using Hibernate in various
ways. The referenced projects and code are available for download at ways. The referenced projects and code are available for download at
<ulink url="http://sourceforge.net/projects/hibernate/files/hibernate/&version;"/> <ulink url="http://sourceforge.net/projects/hibernate/files/hibernate/&version;"/>
</para> </para>
-->
<para>
Learn by doing, with guided tutorials. The referenced projects and code are available for download at <ulink url="http://sourceforge.net/projects/hibernate/files/hibernate/&version;"/>.
</para>
</partintro> </partintro>
<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_native.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/tutorial_annotations.xml" /> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/tutorial_annotations.xml" />

69
documentation/quickstart/src/main/docbook/en-US/content/community.xml
View File

@ -4,39 +4,38 @@
<chapter id="hibernate-gsg-community"> <chapter id="hibernate-gsg-community">
<title>Hibernate Community</title> <title>Hibernate Community</title>
<para> <!-- I removed the para and titled the list instead. I changed gerunds to imperative verbs (Use instead of Using). -->
There are a number of ways to become involved in the Hibernate community, including <itemizedlist>
<itemizedlist> <title>Get Involved</title>
<listitem> <listitem>
<para> <para>
Trying stuff out and reporting bugs. See <ulink url="http://hibernate.org/issuetracker.html"/> for Use Hibernate and report any bugs or issues you find. See
details. <ulink url="http://hibernate.org/issuetracker.html"/> for
</para> details.
</listitem> </para>
<listitem> </listitem>
<para> <listitem>
Trying your hand at fixing some bugs or implementing enhancements. Again, see <para>
<ulink url="http://hibernate.org/issuetracker.html"/>. Try your hand at fixing some bugs or implementing
</para> enhancements. Again, see <ulink
</listitem> url="http://hibernate.org/issuetracker.html"/>.
<listitem> </para>
<para> </listitem>
<ulink url="http://hibernate.org/community.html"/> lists a number of ways to engage in the community <listitem>
including mailing lists, forums, IRC and others. <para>
</para> Engage with the community using mailing lists, forums, IRC, or other ways listed at <ulink url="http://hibernate.org/community.html"/>.
</listitem> </para>
<listitem> </listitem>
<para> <listitem>
Helping improve or translate this documentation. Contact us on the developer mailing list <para>
if you have interest. Help improve or translate this documentation. Contact us on
</para> the developer mailing list if you have interest.
</listitem> </para>
<listitem> </listitem>
<para> <listitem>
Evangelizing Hibernate within your organization. <para>
</para> Spread the word. Let the rest of your organization know about the benefits of Hibernate.<!-- I didn't like 'evangelize'. Too many religious overtones. I'd like something stronger than this though. I'll have a think. -->
</listitem> </para>
</itemizedlist> </listitem>
</para> </itemizedlist>
</chapter> </chapter>

355
documentation/quickstart/src/main/docbook/en-US/content/obtaining.xml
View File

@ -8,40 +8,39 @@
<section id="hibernate-gsg-setup-releaseBundle"> <section id="hibernate-gsg-setup-releaseBundle">
<title>Release Bundle Downloads</title> <title>Release Bundle Downloads</title>
<para> <para>
The Hibernate team provides release bundles hosted on the SourceForge File Release System, both in The Hibernate team provides release bundles hosted on the SourceForge File Release System, in
<literal>ZIP</literal> and <literal>TGZ</literal> formats. A release bundle contains <literal>JARs</literal>, <literal>ZIP</literal> and <literal>TGZ</literal> formats. Each release bundle contains <literal>JARs</literal>,
documentation, source code, and other information. documentation, source code, and other information.
</para> </para>
<para> <para>
Navigate to <ulink url="http://sourceforge.net/projects/hibernate/files/hibernate3/"/> and download the You can download releases of Hibernate, in your chosen format, from the list at <ulink url="http://sourceforge.net/projects/hibernate/files/hibernate3/"/>.
desired release from the list, in your format of choice.
</para> </para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
<filename>hibernate3.jar</filename> is an aggregation of all the Hibernate Core classes. <filename>hibernate3.jar</filename> is an aggregation of all the Hibernate Core classes.
This would need to be part of your project classpath. This must be included in your project's classpath.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
The <filename>lib/required</filename> directory contains jars that are The <filename>lib/required/</filename> directory contains JARs Hibernate requires. All the jars in this directory must also be included in your project's classpath as well.
<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> </para>
<important> <important>
<para> <para>
The slf4j jar is special in that you still need further jar file(s) for it to work correctly. The <filename>slf4j</filename> JAR has additional
Which jar(s) depends on which logging back-end you want to use. See the requirements for it to function properly. The exact
<ulink url="http://slf4j.org/">slf4j site</ulink> for details. requirements depend on your logging back-end. See <ulink
url="http://slf4j.org/">slf4j site</ulink> for details.
</para> </para>
</important> </important>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
The <filename>/lib/jpa</filename> directory contains the 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 <ulink url="http://jcp.org/en/jsr/detail?id=317">JPA</ulink>
JPA APIs or JPA annotations, this jar will need to be part of your project classpath too. API JAR. This JAR needs to be in your project's classpath if
you want to use the JPA APIs or JPA annotations.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -49,152 +48,188 @@
<section id="hibernate-gsg-setup-mavenRepoArtifacts"> <section id="hibernate-gsg-setup-mavenRepoArtifacts">
<title>Maven Repository Artifacts</title> <title>Maven Repository Artifacts</title>
<important> <para>
<para> The authoritative repository for Hibernate artifacts is the
The authoritative repository for Hibernate artifacts is the JBoss JBoss Maven repository. The team responsible for the JBoss
Maven repository. The team responsible for the JBoss Maven repository maintains a number of wiki Maven repository maintains a number of Wiki pages that contain
pages that contain important information: important information.
<itemizedlist> </para>
<listitem> <!-- lists inside <para> don't work in Publican, and you don't lose
<para> anything by putting them outside the para. -->
<ulink url="http://community.jboss.org/docs/DOC-14900">http://community.jboss.org/docs/DOC-14900</ulink> - <variablelist>
contains general information about the repository <title>Maven Repository Wiki Pages</title>
</para> <varlistentry>
</listitem> <term><ulink url="http://community.jboss.org/docs/DOC-14900">http://community.jboss.org/docs/DOC-14900</ulink></term>
<listitem> <listitem>
<para> <para>
<ulink url="http://community.jboss.org/docs/DOC-15170">http://community.jboss.org/docs/DOC-15170</ulink> - General information about the repository.
contains information about setting up access to the repository for <emphasis>developers</emphasis> </para>
(aka, developers working on Hibernate or JBoss projects). </listitem>
</para> </varlistentry>
</listitem> <varlistentry>
<listitem> <term><ulink url="http://community.jboss.org/docs/DOC-15170">http://community.jboss.org/docs/DOC-15170</ulink></term>
<para> <listitem>
<ulink url="http://community.jboss.org/docs/DOC-15169">http://community.jboss.org/docs/DOC-15169</ulink> - <para>
contains information about setting up access to the repository for <emphasis>users</emphasis> Information about setting up the JBoss repositories in order to do development work on JBoss projects themselves.
(aka, consumers of Hibernate or JBoss projects). </para>
</para> </listitem>
</listitem> </varlistentry>
</itemizedlist> <varlistentry>
</para> <term><ulink url="http://community.jboss.org/docs/DOC-15169">http://community.jboss.org/docs/DOC-15169</ulink></term>
</important> <listitem>
<para>
Information about setting up access to the repository to use JBoss projects as part of your own software.
</para>
</listitem>
</varlistentry>
</variablelist>
<para> <para>
Hibernate produces a number of artifacts (all under the org.hibernate groupId): Hibernate produces a number of artifacts (all under the org.hibernate groupId):
<itemizedlist> </para>
<listitem> <variablelist>
<para> <title>Hibernate Artifacts under groupId<systemitem>org.hibernate</systemitem></title>
<emphasis>hibernate-core</emphasis> - This is the main artifact. It contains all the <varlistentry>
Hibernate classes (<package>org.hibernate</package>) needed to build applications using <term>hibernate-core</term>
the native Hibernate APIs. It includes capabilities for using native Hibernate mapping <listitem>
(<filename>hbm.xml</filename>) files as well as annotations. <para>
</para> The main artifact, which contains all the Hibernate classes, in
</listitem> package <package>org.hibernate</package>. You need these to
<listitem> build applications using the native Hibernate APIs. It includes
<para> capabilities for using native Hibernate mapping in
<emphasis>hibernate-entitymanager</emphasis> - Hibernate provides an implementation of <filename>hbm.xml</filename> files, as well as annotations.
<ulink url="http://jcp.org/en/jsr/detail?id=317">JPA</ulink>. This is the artifact that </para>
represents this JPA implementation. </listitem>
</para> </varlistentry>
<para> <varlistentry>
This artifact depends on <emphasis>hibernate-core</emphasis>. <term>hibernate-entitymanager</term>
</para> <listitem>
</listitem> <para>
<listitem> Represents Hibernate's implementation of
<para> <application>JPA</application>, as specified at<ulink
<emphasis>hibernate-envers</emphasis> - Envers is an optional module that url="http://jcp.org/en/jsr/detail?id=317" />.
provides historical auditing of changes to your entities. </para>
</para> <para>
<para> This artifact depends on <systemitem>hibernate-core</systemitem>
This artifact depends on both <emphasis>hibernate-core</emphasis> and </para>
<emphasis>hibernate-entitymanager</emphasis>. </listitem>
</para> </varlistentry>
</listitem> <varlistentry>
<listitem> <term>hibernate-envers</term>
<para> <listitem>
<emphasis>hibernate-c3p0</emphasis> - Represents the integration between Hibernate <para>
and the <ulink url="http://sourceforge.net/projects/c3p0/">C3P0</ulink> connection pool An optional module that provides historical auditing of changes
library. to your entities.
</para> </para>
<para> <para>
This artifact depends on <emphasis>hibernate-core</emphasis>; however it would generally This artifact depends on both
be included in a project as a runtime dependency (rarely would you need to bind against <systemitem>hibernate-core</systemitem> and
these classes at compile time). It also pulls in the C3P0 dependencies. <systemitem>hibernate-entitymanager</systemitem>.
be </para>
</para> </listitem>
</listitem> </varlistentry>
<listitem> <varlistentry>
<para> <term>hibernate-c3p0</term>
<emphasis>hibernate-proxool</emphasis> - Represents the integration between Hibernate <listitem>
and the <ulink url="http://proxool.sourceforge.net/">Proxool</ulink> connection pool <para>
library. Provides integration between Hibernate and the
</para> <application>C3P0</application> connection pool library. See
<para> <ulink url="http://sourceforge.net/projects/c3p0/" /> for
This artifact depends on <emphasis>hibernate-core</emphasis>; however it would generally information about <application>C3P0</application>.
be included in a project as a runtime dependency (rarely would you need to bind against </para>
these classes at compile time). It also pulls in the Proxool dependencies. <para>
</para> This artifact depends on <systemitem>hibernate-core</systemitem>, but is generally included in a project as a runtime dependency. It pulls in the <application>C3P0</application> dependencies automatically.
</listitem> </para>
<listitem> </listitem>
<para> </varlistentry>
<emphasis>hibernate-ehcache</emphasis> - Represents the integration between Hibernate <varlistentry>
and <ulink url="http://ehcache.sourceforge.net/">EhCache</ulink> as a second level cache <term>hibernate-proxool</term>
implementation. <listitem>
</para> <para>
<para> Provides integration between Hibernate and the
This artifact depends on <emphasis>hibernate-core</emphasis>; however it would generally <application>Proxool</application> connection pool library. See
be included in a project as a runtime dependency (rarely would you need to bind against <ulink url="http://proxool.sourceforge.net/" /> for more
these classes at compile time). It also pulls in the Ehcache dependencies. information about this library. library.
</para> </para>
</listitem> <para>
<listitem> This artifact depends on
<para> <systemitem>hibernate-core</systemitem>, but is generally
<emphasis>hibernate-infinispan</emphasis> - Represents the integration between Hibernate included in a project as a runtime dependency. It pulls in the
and <ulink url="http://jboss.org/infinispan">Infinispan</ulink> as a second level cache <application>Proxool</application> dependencies automatically..
implementation. </para>
</para> </listitem>
<para> </varlistentry>
This artifact depends on <emphasis>hibernate-core</emphasis>; however it would generally <varlistentry>
be included in a project as a runtime dependency (rarely would you need to bind against <term>hibernate-ehcache</term>
these classes at compile time). It also pulls in the Infinispan dependencies. <listitem>
</para> <para>
</listitem> Privides integration between Hibernate and
<listitem> <application>EhCache</application>, as a second-level cache. See
<para> <ulink url="http://ehcache.sourceforge.net/" /> for more
<emphasis>hibernate-jbosscache</emphasis> - Represents the integration between Hibernate information about <application>EhCache</application>.
and <ulink url="http://jboss.org/jbosscache">JBossCache</ulink> as a second level cache </para>
implementation. <para>
</para> This artifact depends on
<para> <systemitem>hibernate-core</systemitem>, but is generally
This artifact depends on <emphasis>hibernate-core</emphasis>; however it would generally included in a project as a runtime dependency. It pulls in the
be included in a project as a runtime dependency (rarely would you need to bind against <application>Ehcache</application> dependencies automatically.
these classes at compile time). It also pulls in the JBossCache dependencies </para>
</para> </listitem>
</listitem> </varlistentry>
<listitem> <varlistentry>
<para> <term>hibernate-infinispan</term>
<emphasis>hibernate-oscache</emphasis> - Represents the integration between Hibernate <listitem>
and <ulink url="http://www.opensymphony.com/oscache/">OSCache</ulink> as a second level cache <para>
implementation. Provides integration between Hibernate
</para> and <application>Infinispan</application>, as a second-level cache. See <ulink url="http://jboss.org/infinispan" /> for more information about <application>Infinispan</application>.
<para> </para>
This artifact depends on <emphasis>hibernate-core</emphasis>; however it would generally <para>
be included in a project as a runtime dependency (rarely would you need to bind against This artifact depends on <systemitem>hibernate-core</systemitem>, but is generally included in a project as a runtime
these classes at compile time). It also pulls in the OSCache dependencies. dependency. It pulls in the <application>Infinispan</application> dependencies automatically.
</para> </para>
</listitem> </listitem>
<listitem> </varlistentry>
<para> <varlistentry>
<emphasis>hibernate-swarmcache</emphasis> - Represents the integration between Hibernate <term>hibernate-jbosscache</term>
and <ulink url="http://swarmcache.sourceforge.net/">SwarmCache</ulink> as a second level cache <listitem>
implementation. <para>
</para> Provides integration between Hibernate
<para> and <application>JBossCache</application>, as a second-level cache. See <ulink url="http://jboss.org/jbosscache" /> for information about <application>JBossCache</application>.
This artifact depends on <emphasis>hibernate-core</emphasis>; however it would generally </para>
be included in a project as a runtime dependency (rarely would you need to bind against <para>
these classes at compile time). It also pulls in the SwarmCache dependencies. This artifact depends on <systemitem>hibernate-core</systemitem>,
</para> but is generally included in a project as a runtime dependency.
</listitem> It pulls in the <application>JBossCache</application>
</itemizedlist> dependencies automatically.
</para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>hibernate-oscache</term>
<listitem>
<para>
Provides integration between Hibernate
and <application>OSCache</application> as a second-level cache. See <ulink url="http://www.opensymphony.com/oscache/" /> for information about <application>OSCache</application>.
</para>
<para>
This artifact depends on <systemitem>hibernate-core</systemitem>,
but is generally included in a project as a runtime dependency.
It pulls in the OSCache dependencies automatically.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>hibernate-swarmcache</term>
<listitem>
<para>
Provides integration between Hibernate
and <application>SwarmCache</application>, as a second-level cache. See <ulink url="http://swarmcache.sourceforge.net/" /> for more information about <application>SwarmCache</application>.
</para>
<para>
This artifact depends on <systemitem>hibernate-core</systemitem>, but is generally included in a project as a runtime dependency. It pulls in the <application>SwarmCache</application> dependencies automatically.
</para>
</listitem>
</varlistentry>
</variablelist>
</section> </section>
</chapter> </chapter>