[hibernate-commits] Hibernate SVN: r20345 - in core/trunk/documentation/quickstart: src/main/docbook/en-US/content and 14 other directories.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Fri Sep 10 16:19:36 EDT 2010
Author: steve.ebersole at jboss.com
Date: 2010-09-10 16:19:35 -0400 (Fri, 10 Sep 2010)
New Revision: 20345
Added:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_envers.xml
core/trunk/documentation/quickstart/tutorials/envers/
core/trunk/documentation/quickstart/tutorials/envers/pom.xml
core/trunk/documentation/quickstart/tutorials/envers/src/
core/trunk/documentation/quickstart/tutorials/envers/src/test/
core/trunk/documentation/quickstart/tutorials/envers/src/test/java/
core/trunk/documentation/quickstart/tutorials/envers/src/test/java/org/
core/trunk/documentation/quickstart/tutorials/envers/src/test/java/org/hibernate/
core/trunk/documentation/quickstart/tutorials/envers/src/test/java/org/hibernate/tutorial/
core/trunk/documentation/quickstart/tutorials/envers/src/test/java/org/hibernate/tutorial/envers/
core/trunk/documentation/quickstart/tutorials/envers/src/test/java/org/hibernate/tutorial/envers/EnversIllustrationTest.java
core/trunk/documentation/quickstart/tutorials/envers/src/test/java/org/hibernate/tutorial/envers/Event.java
core/trunk/documentation/quickstart/tutorials/envers/src/test/resources/
core/trunk/documentation/quickstart/tutorials/envers/src/test/resources/META-INF/
core/trunk/documentation/quickstart/tutorials/envers/src/test/resources/META-INF/persistence.xml
Removed:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/community.xml
Modified:
core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.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_native.xml
core/trunk/documentation/quickstart/tutorials/annotations/src/test/java/org/hibernate/tutorial/annotations/AnnotationsIllustrationTest.java
core/trunk/documentation/quickstart/tutorials/basic/src/test/java/org/hibernate/tutorial/hbm/NativeApiIllustrationTest.java
core/trunk/documentation/quickstart/tutorials/entitymanager/src/test/java/org/hibernate/tutorial/em/EntityManagerIllustrationTest.java
core/trunk/documentation/quickstart/tutorials/pom.xml
Log:
HHH-5446 - Write an envers tutorial guide
Modified: core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml
===================================================================
--- core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml 2010-09-10 08:40:12 UTC (rev 20344)
+++ core/trunk/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml 2010-09-10 20:19:35 UTC (rev 20345)
@@ -8,38 +8,11 @@
<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" />
- <part label="I">
- <title>Basic Information</title>
- <partintro>
- <!-- Don't refer to things by Part #, because things could be re-ordered later
- <para>
- The sections in Part I present basic information you will
- likely need to get started utilizing Hibernate
- </para>
- -->
- <para>Set up and begin using Hibernate.</para>
- </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/obtaining.xml" />
- </part>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/obtaining.xml" />
- <part label="II">
- <title>Tutorials</title>
- <partintro>
- <!--
- <para>
- 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
- <ulink url="http://sourceforge.net/projects/hibernate/files/hibernate/&version;"/>
- </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>
- <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_jpa.xml" />
- </part>
+ <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_jpa.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/tutorial_envers.xml" />
</book>
\ No newline at end of file
Deleted: core/trunk/documentation/quickstart/src/main/docbook/en-US/content/community.xml
===================================================================
--- core/trunk/documentation/quickstart/src/main/docbook/en-US/content/community.xml 2010-09-10 08:40:12 UTC (rev 20344)
+++ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/community.xml 2010-09-10 20:19:35 UTC (rev 20345)
@@ -1,41 +0,0 @@
-<?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>
-
- <!-- I removed the para and titled the list instead. I changed gerunds to imperative verbs (Use instead of Using). -->
- <itemizedlist>
- <title>Get Involved</title>
- <listitem>
- <para>
- Use Hibernate and report any bugs or issues you find. See
- <ulink url="http://hibernate.org/issuetracker.html"/> for
- details.
- </para>
- </listitem>
- <listitem>
- <para>
- Try your hand at fixing some bugs or implementing
- enhancements. Again, see <ulink
- url="http://hibernate.org/issuetracker.html"/>.
- </para>
- </listitem>
- <listitem>
- <para>
- Engage with the community using mailing lists, forums, IRC, or other ways listed at <ulink url="http://hibernate.org/community.html"/>.
- </para>
- </listitem>
- <listitem>
- <para>
- Help improve or translate this documentation. Contact us on
- the developer mailing list if you have interest.
- </para>
- </listitem>
- <listitem>
- <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. -->
- </para>
- </listitem>
- </itemizedlist>
-</chapter>
Modified: core/trunk/documentation/quickstart/src/main/docbook/en-US/content/obtaining.xml
===================================================================
--- core/trunk/documentation/quickstart/src/main/docbook/en-US/content/obtaining.xml 2010-09-10 08:40:12 UTC (rev 20344)
+++ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/obtaining.xml 2010-09-10 20:19:35 UTC (rev 20345)
@@ -9,38 +9,53 @@
<title>Release Bundle Downloads</title>
<para>
The Hibernate team provides release bundles hosted on the SourceForge File Release System, in
- <literal>ZIP</literal> and <literal>TGZ</literal> formats. Each 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.
</para>
<para>
- You can download releases of Hibernate, in your chosen format, from the list at <ulink url="http://sourceforge.net/projects/hibernate/files/hibernate3/"/>.
+ You can download releases of Hibernate, in your chosen format, from the list at
+ <ulink url="http://sourceforge.net/projects/hibernate/files/hibernate3/"/>.
</para>
<itemizedlist>
<listitem>
<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 must be included in your project's classpath.
</para>
</listitem>
<listitem>
<para>
- 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.
+ 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.
</para>
<important>
<para>
- The <filename>slf4j</filename> JAR has additional
- requirements for it to function properly. The exact
- requirements depend on your logging back-end. See <ulink
- url="http://slf4j.org/">slf4j site</ulink> for details.
+ The
+ <filename>slf4j</filename>
+ JAR has additional
+ requirements for it to function properly. The exact
+ requirements depend on your logging back-end. See
+ <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. This JAR needs to be in your project's classpath if
- you want to use the JPA APIs or JPA annotations.
+ The
+ <filename>/lib/jpa/</filename>
+ directory contains the
+ <ulink url="http://jcp.org/en/jsr/detail?id=317">JPA</ulink>
+ API JAR. This JAR needs to be in your project's classpath if
+ you want to use the JPA APIs or JPA annotations.
</para>
</listitem>
</itemizedlist>
@@ -48,188 +63,187 @@
<section id="hibernate-gsg-setup-mavenRepoArtifacts">
<title>Maven Repository Artifacts</title>
- <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.
- </para>
- <!-- lists inside <para> don't work in Publican, and you don't lose
- anything by putting them outside the para. -->
- <variablelist>
- <title>Maven Repository Wiki Pages</title>
- <varlistentry>
- <term><ulink url="http://community.jboss.org/docs/DOC-14900">http://community.jboss.org/docs/DOC-14900</ulink></term>
- <listitem>
- <para>
- General information about the repository.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><ulink url="http://community.jboss.org/docs/DOC-15170">http://community.jboss.org/docs/DOC-15170</ulink></term>
- <listitem>
- <para>
- Information about setting up the JBoss repositories in order to do development work on JBoss projects themselves.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><ulink url="http://community.jboss.org/docs/DOC-15169">http://community.jboss.org/docs/DOC-15169</ulink></term>
- <listitem>
- <para>
- Information about setting up access to the repository to use JBoss projects as part of your own software.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
+ <note>
+ <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.
+ </para>
+ <itemizedlist>
+ <title>Maven Repository Wiki Pages</title>
+ <listitem>
+ <para>
+ <ulink url="http://community.jboss.org/docs/DOC-14900"/> -
+ General information about the repository.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://community.jboss.org/docs/DOC-15170"/> -
+ Information about setting up the JBoss repositories in
+ order to do development work on JBoss projects themselves.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://community.jboss.org/docs/DOC-15169"/> -
+ Information about setting up access to the repository to
+ use JBoss projects as part of your own software.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </note>
+
<para>
- Hibernate produces a number of artifacts (all under the org.hibernate groupId):
- </para>
- <variablelist>
- <title>Hibernate Artifacts under groupId<systemitem>org.hibernate</systemitem></title>
- <varlistentry>
- <term>hibernate-core</term>
- <listitem>
- <para>
- The main artifact, which contains all the Hibernate classes, in
- package <package>org.hibernate</package>. You need these to
- build applications using the native Hibernate APIs. It includes
- capabilities for using native Hibernate mapping in
- <filename>hbm.xml</filename> files, as well as annotations.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>hibernate-entitymanager</term>
- <listitem>
- <para>
- Represents Hibernate's implementation of
- <application>JPA</application>, as specified at<ulink
- url="http://jcp.org/en/jsr/detail?id=317" />.
- </para>
- <para>
- This artifact depends on <systemitem>hibernate-core</systemitem>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>hibernate-envers</term>
- <listitem>
- <para>
- An optional module that provides historical auditing of changes
- to your entities.
- </para>
- <para>
- This artifact depends on both
- <systemitem>hibernate-core</systemitem> and
- <systemitem>hibernate-entitymanager</systemitem>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>hibernate-c3p0</term>
- <listitem>
- <para>
- Provides integration between Hibernate and the
- <application>C3P0</application> connection pool library. See
- <ulink url="http://sourceforge.net/projects/c3p0/" /> for
- information about <application>C3P0</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>C3P0</application> dependencies automatically.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>hibernate-proxool</term>
- <listitem>
- <para>
- Provides integration between Hibernate and the
- <application>Proxool</application> connection pool library. See
- <ulink url="http://proxool.sourceforge.net/" /> for more
- information about this library. library.
- </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>Proxool</application> dependencies automatically..
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>hibernate-ehcache</term>
- <listitem>
- <para>
- Privides integration between Hibernate and
- <application>EhCache</application>, as a second-level cache. See
- <ulink url="http://ehcache.sourceforge.net/" /> for more
- information about <application>EhCache</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>Ehcache</application> dependencies automatically.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>hibernate-infinispan</term>
- <listitem>
- <para>
- Provides integration between Hibernate
- 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 <systemitem>hibernate-core</systemitem>, but is generally included in a project as a runtime
- dependency. It pulls in the <application>Infinispan</application> dependencies automatically.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>hibernate-jbosscache</term>
- <listitem>
- <para>
- Provides integration between Hibernate
- and <application>JBossCache</application>, as a second-level cache. See <ulink url="http://jboss.org/jbosscache" /> for information about <application>JBossCache</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>JBossCache</application>
- dependencies automatically.
- </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>
+ Hibernate produces a number of artifacts (all under the org.hibernate groupId):
+ </para>
+ <variablelist>
+ <title>Hibernate Artifacts under groupId <systemitem>org.hibernate</systemitem>
+ </title>
+ <varlistentry>
+ <term>hibernate-core</term>
+ <listitem>
+ <para>
+ The main artifact, which contains all the Hibernate classes, in
+ package<package>org.hibernate</package>. You need these to
+ build applications using the native Hibernate APIs. It includes
+ capabilities for using native Hibernate mapping in
+ <filename>hbm.xml</filename>
+ files, as well as annotations.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>hibernate-entitymanager</term>
+ <listitem>
+ <para>
+ Represents Hibernate's implementation of <phrase>JPA</phrase>, as specified at
+ <ulink url="http://jcp.org/en/jsr/detail?id=317"/>.
+ </para>
+ <para>
+ This artifact depends on <systemitem>hibernate-core</systemitem>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>hibernate-envers</term>
+ <listitem>
+ <para>
+ An optional module that provides historical auditing of changes
+ to your entities.
+ </para>
+ <para>
+ This artifact depends on both <systemitem>hibernate-core</systemitem>
+ and <systemitem>hibernate-entitymanager</systemitem>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>hibernate-c3p0</term>
+ <listitem>
+ <para>
+ Provides integration between Hibernate and the <application>C3P0</application> connection
+ pool library. See <ulink url="http://sourceforge.net/projects/c3p0/"/> for information
+ about <application>C3P0</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>C3P0</application>
+ dependencies automatically.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>hibernate-proxool</term>
+ <listitem>
+ <para>
+ Provides integration between Hibernate and the <application>Proxool</application> connection
+ pool library. See <ulink url="http://proxool.sourceforge.net/"/> for more information about
+ this library.
+ </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>Proxool</application>
+ dependencies automatically..
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>hibernate-ehcache</term>
+ <listitem>
+ <para>
+ Privides integration between Hibernate and <application>EhCache</application>, as a
+ second-level cache. See <ulink url="http://ehcache.sourceforge.net/"/> for more
+ information about<application>EhCache</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>Ehcache</application>
+ dependencies automatically.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>hibernate-infinispan</term>
+ <listitem>
+ <para>
+ Provides integration between Hibernate 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 <systemitem>hibernate-core</systemitem>, but is generally included
+ in a project as a runtime dependency. It pulls in the <application>Infinispan</application>
+ dependencies automatically.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>hibernate-jbosscache</term>
+ <listitem>
+ <para>
+ Provides integration between Hibernate and <application>JBossCache</application>, as a
+ second-level cache. See <ulink url="http://jboss.org/jbosscache"/> for information about
+ <application>JBossCache</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>JBossCache</application>
+ dependencies automatically.
+ </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 <application>OSCache</application>
+ 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>
</chapter>
\ No newline at end of file
Modified: core/trunk/documentation/quickstart/src/main/docbook/en-US/content/preface.xml
===================================================================
--- core/trunk/documentation/quickstart/src/main/docbook/en-US/content/preface.xml 2010-09-10 08:40:12 UTC (rev 20344)
+++ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/preface.xml 2010-09-10 20:19:35 UTC (rev 20345)
@@ -85,4 +85,47 @@
representation to a graph of objects.
</para>
+ <section>
+ <title>Get Involved</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Use Hibernate and report any bugs or issues you find. See
+ <ulink url="http://hibernate.org/issuetracker.html"/> for details.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Try your hand at fixing some bugs or implementing enhancements. Again, see
+ <ulink url="http://hibernate.org/issuetracker.html"/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Engage with the community using mailing lists, forums, IRC, or other ways listed at
+ <ulink url="http://hibernate.org/community.html"/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Help improve or translate this documentation. Contact us on
+ the developer mailing list if you have interest.
+ </para>
+ </listitem>
+ <listitem>
+ <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. -->
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Tutorial code</title>
+ <para>
+ The referenced projects and code for the tutorials in this guide are available at
+ <ulink url="files/hibernate-tutorials.zip"/>.
+ </para>
+ </section>
</preface>
Added: core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_envers.xml
===================================================================
--- core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_envers.xml (rev 0)
+++ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_envers.xml 2010-09-10 20:19:35 UTC (rev 20345)
@@ -0,0 +1,72 @@
+<?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-envers">
+ <title>Tutorial Using Envers</title>
+
+ <para>
+ This tutorial is located within the download bundle under <filename>envers</filename> and illustrates
+ <itemizedlist>
+ <listitem>
+ <para>
+ configuring Envers
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ using the Envers APIs to look back through history
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <section id="hibernate-gsg-tutorial-envers-config">
+ <title><filename>persistence.xml</filename></title>
+ <para>
+ This file was discussed in the <phrase>JPA</phrase> tutorial, and is largely the same here. The major
+ difference is the set of properties defining <firstterm><phrase>listeners</phrase></firstterm>.
+ Essentially this enables envers to recieve notfications from Hibernate processing of certain
+ <firstterm><phrase>events</phrase></firstterm> such as an entity being saved or updated.
+ </para>
+ </section>
+
+ <section id="hibernate-gsg-tutorial-envers-entity">
+ <title>The annotated entity Java class</title>
+ <para>
+ Again, the entity is largely the same as seen in the <phrase>JPA</phrase> tutorial. The major
+ difference to notice is the addition of the <interfacename>@org.hibernate.envers.Audited</interfacename>
+ annotation which tells Envers to automatically track changes to this entity.
+ </para>
+ </section>
+
+ <section id="hibernate-gsg-tutorial-envers-test">
+ <title>Example code</title>
+ <para>
+ Again, this tutorial makes use of the <phrase>JPA</phrase> APIs. However, the code also makes a
+ revision to one of the entites and then uses the Envers API to pull back the initial revision
+ as well as the updated revision.
+ </para>
+ <example id="hibernate-gsg-tutorial-envers-test-api">
+ <title>Using the <interfacename>org.hibernate.envers.AuditReader</interfacename></title>
+ <programlisting role="JAVA">public void testBasicUsage() {
+ ...
+ AuditReader reader = AuditReaderFactory.get( entityManager );
+ Event firstRevision = reader.find( Event.class, 2L, 1 );
+ ...
+ Event secondRevision = reader.find( Event.class, 2L, 2 );
+ ...
+}</programlisting>
+ </example>
+ <para>
+ First an <interfacename>org.hibernate.envers.AuditReader</interfacename> is obtained
+ from the <classname>org.hibernate.envers.AuditReaderFactory</classname> wrapping the
+ <interfacename>javax.persistence.EntityManager</interfacename>.
+ </para>
+ <para>
+ Then the <methodname>find</methodname> methid is used to retrieve specific revisions of the entity. The
+ first call reads "find revision number 1 of Event with id 2". The second call reads "find revision
+ number 2 of Event with id 2".
+ </para>
+ </section>
+
+</chapter>
\ No newline at end of file
Modified: 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 2010-09-10 08:40:12 UTC (rev 20344)
+++ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml 2010-09-10 20:19:35 UTC (rev 20345)
@@ -40,9 +40,7 @@
<important>
<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. See the section
- <citetitle pubwork="section">JDBC Connections</citetitle> in the
- <citetitle pubwork="chapter">Database Access</citetitle> chapter of the
+ lacks several features found on any decent connection pool. See the section discussion in
<citetitle pubwork="book">Hibernate Developer Guide</citetitle> for further information.
</para>
</important>
@@ -55,10 +53,8 @@
<tip>
<para>
In most cases, Hibernate is able to properly determine which dialect to use which is invaluable if
- your application targets multiple databases. See the section
- <citetitle pubwork="section">Database Dialects</citetitle> in the
- <citetitle pubwork="chapter">Database Access</citetitle> chapter of the
- <citetitle pubwork="book">Hibernate Developer Guide</citetitle> for further information.
+ your application targets multiple databases. This is discussed in detail in the
+ <citetitle pubwork="book">Hibernate Developer Guide</citetitle>
</para>
</tip>
@@ -162,6 +158,7 @@
</para>
<important>
+ <!-- Again, perhaps more sense moving this to the Dev Guide -->
<para>
It is not strictly necessary for the <literal>id</literal> element to map to the table's actual
primary key column(s), but it is the normal convention. Tables mapped in Hibernate do not even
@@ -217,6 +214,7 @@
</para>
<tip>
+ <!-- This tip probably makes more sense in the Dev Guide -->
<para>
Hibernate makes this mapping type determination using reflection when the mapping files are
processed. This process can take time and resources. If startup performance is important, consider
Modified: core/trunk/documentation/quickstart/tutorials/annotations/src/test/java/org/hibernate/tutorial/annotations/AnnotationsIllustrationTest.java
===================================================================
--- core/trunk/documentation/quickstart/tutorials/annotations/src/test/java/org/hibernate/tutorial/annotations/AnnotationsIllustrationTest.java 2010-09-10 08:40:12 UTC (rev 20344)
+++ core/trunk/documentation/quickstart/tutorials/annotations/src/test/java/org/hibernate/tutorial/annotations/AnnotationsIllustrationTest.java 2010-09-10 20:19:35 UTC (rev 20345)
@@ -33,7 +33,8 @@
import org.hibernate.cfg.Configuration;
/**
- * TODO : javadoc
+ * Illustrates the use of Hibernate native APIs. The code here is unchanged from the {@code basic} example, the
+ * only difference being the use of annotations to supply the metadata instead of Hibernate mapping files.
*
* @author Steve Ebersole
*/
@@ -55,6 +56,7 @@
}
}
+ @SuppressWarnings({ "unchecked" })
public void testBasicUsage() {
// create a couple of events...
Session session = sessionFactory.openSession();
Modified: core/trunk/documentation/quickstart/tutorials/basic/src/test/java/org/hibernate/tutorial/hbm/NativeApiIllustrationTest.java
===================================================================
--- core/trunk/documentation/quickstart/tutorials/basic/src/test/java/org/hibernate/tutorial/hbm/NativeApiIllustrationTest.java 2010-09-10 08:40:12 UTC (rev 20344)
+++ core/trunk/documentation/quickstart/tutorials/basic/src/test/java/org/hibernate/tutorial/hbm/NativeApiIllustrationTest.java 2010-09-10 20:19:35 UTC (rev 20345)
@@ -33,7 +33,7 @@
import org.hibernate.cfg.Configuration;
/**
- * TODO : javadoc
+ * Illustrates use of Hibernate native APIs.
*
* @author Steve Ebersole
*/
Modified: core/trunk/documentation/quickstart/tutorials/entitymanager/src/test/java/org/hibernate/tutorial/em/EntityManagerIllustrationTest.java
===================================================================
--- core/trunk/documentation/quickstart/tutorials/entitymanager/src/test/java/org/hibernate/tutorial/em/EntityManagerIllustrationTest.java 2010-09-10 08:40:12 UTC (rev 20344)
+++ core/trunk/documentation/quickstart/tutorials/entitymanager/src/test/java/org/hibernate/tutorial/em/EntityManagerIllustrationTest.java 2010-09-10 20:19:35 UTC (rev 20345)
@@ -32,7 +32,7 @@
import junit.framework.TestCase;
/**
- * TODO : javadoc
+ * Illustrates basic use of Hibernate as a JPA provider.
*
* @author Steve Ebersole
*/
Added: core/trunk/documentation/quickstart/tutorials/envers/pom.xml
===================================================================
--- core/trunk/documentation/quickstart/tutorials/envers/pom.xml (rev 0)
+++ core/trunk/documentation/quickstart/tutorials/envers/pom.xml 2010-09-10 20:19:35 UTC (rev 20345)
@@ -0,0 +1,59 @@
+<?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>
+ <artifactId>hibernate-tutorials</artifactId>
+ <groupId>org.hibernate.tutorials</groupId>
+ <version>3.6.0-SNAPSHOT</version>
+ </parent>
+
+ <artifactId>hibernate-tutorial-envers</artifactId>
+ <name>Hibernate Envers Tutorial</name>
+ <description>Hibernate tutorial illustrating basic set up and use of Envers</description>
+
+ <properties>
+ <!-- Skip artifact deployment -->
+ <maven.deploy.skip>true</maven.deploy.skip>
+ </properties>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.hibernate</groupId>
+ <artifactId>hibernate-entitymanager</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.hibernate</groupId>
+ <artifactId>hibernate-envers</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ </dependencies>
+
+</project>
\ No newline at end of file
Added: core/trunk/documentation/quickstart/tutorials/envers/src/test/java/org/hibernate/tutorial/envers/EnversIllustrationTest.java
===================================================================
--- core/trunk/documentation/quickstart/tutorials/envers/src/test/java/org/hibernate/tutorial/envers/EnversIllustrationTest.java (rev 0)
+++ core/trunk/documentation/quickstart/tutorials/envers/src/test/java/org/hibernate/tutorial/envers/EnversIllustrationTest.java 2010-09-10 20:19:35 UTC (rev 20345)
@@ -0,0 +1,105 @@
+/*
+ * 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
+ */
+package org.hibernate.tutorial.envers;
+
+import java.util.Date;
+import java.util.List;
+import javax.persistence.EntityManager;
+import javax.persistence.EntityManagerFactory;
+import javax.persistence.Persistence;
+
+import junit.framework.TestCase;
+
+import org.hibernate.envers.AuditReader;
+import org.hibernate.envers.AuditReaderFactory;
+
+/**
+ * Illustrates the set up and use of Envers.
+ * <p>
+ * This example is different from the others in that we really need to save multiple revisions to the entity in
+ * order to get a good look at Envers in action.
+ *
+ * @author Steve Ebersole
+ */
+public class EnversIllustrationTest extends TestCase {
+ private EntityManagerFactory entityManagerFactory;
+
+ @Override
+ protected void setUp() throws Exception {
+ // like discussed with regards to SessionFactory, an EntityManagerFactory is set up once for an application
+ // IMPORTANT: notice how the name here matches the name we gave the persistence-unit in persistence.xml!
+ entityManagerFactory = Persistence.createEntityManagerFactory( "org.hibernate.tutorial.envers" );
+ }
+
+ @Override
+ protected void tearDown() throws Exception {
+ entityManagerFactory.close();
+ }
+
+ public void testBasicUsage() {
+ // create a couple of events
+ EntityManager entityManager = entityManagerFactory.createEntityManager();
+ entityManager.getTransaction().begin();
+ entityManager.persist( new Event( "Our very first event!", new Date() ) );
+ entityManager.persist( new Event( "A follow up event", new Date() ) );
+ entityManager.getTransaction().commit();
+ entityManager.close();
+
+ // now lets pull events from the database and list them
+ entityManager = entityManagerFactory.createEntityManager();
+ entityManager.getTransaction().begin();
+ List<Event> result = entityManager.createQuery( "from Event", Event.class ).getResultList();
+ for ( Event event : result ) {
+ System.out.println( "Event (" + event.getDate() + ") : " + event.getTitle() );
+ }
+ entityManager.getTransaction().commit();
+ entityManager.close();
+
+ // so far the code is the same as we have seen in previous tutorials. Now lets leverage Envers...
+
+ // first lets create some revisions
+ entityManager = entityManagerFactory.createEntityManager();
+ entityManager.getTransaction().begin();
+ Event myEvent = entityManager.find( Event.class, 2L ); // we are using the increment generator, so we know 2 is a valid id
+ myEvent.setDate( new Date() );
+ myEvent.setTitle( myEvent.getTitle() + " (rescheduled)" );
+ entityManager.getTransaction().commit();
+ entityManager.close();
+
+ // and then use an AuditReader to look back through history
+ entityManager = entityManagerFactory.createEntityManager();
+ entityManager.getTransaction().begin();
+ myEvent = entityManager.find( Event.class, 2L );
+ assertEquals( "A follow up event (rescheduled)", myEvent.getTitle() );
+ AuditReader reader = AuditReaderFactory.get( entityManager );
+ Event firstRevision = reader.find( Event.class, 2L, 1 );
+ assertFalse( firstRevision.getTitle().equals( myEvent.getTitle() ) );
+ assertFalse( firstRevision.getDate().equals( myEvent.getDate() ) );
+ Event secondRevision = reader.find( Event.class, 2L, 2 );
+ assertTrue( secondRevision.getTitle().equals( myEvent.getTitle() ) );
+ assertTrue( secondRevision.getDate().equals( myEvent.getDate() ) );
+ entityManager.getTransaction().commit();
+ entityManager.close();
+ }
+}
Copied: core/trunk/documentation/quickstart/tutorials/envers/src/test/java/org/hibernate/tutorial/envers/Event.java (from rev 20298, core/trunk/documentation/quickstart/tutorials/entitymanager/src/test/java/org/hibernate/tutorial/em/Event.java)
===================================================================
--- core/trunk/documentation/quickstart/tutorials/envers/src/test/java/org/hibernate/tutorial/envers/Event.java (rev 0)
+++ core/trunk/documentation/quickstart/tutorials/envers/src/test/java/org/hibernate/tutorial/envers/Event.java 2010-09-10 20:19:35 UTC (rev 20345)
@@ -0,0 +1,92 @@
+/*
+ * 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
+ */
+package org.hibernate.tutorial.envers;
+
+import java.util.Date;
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.GeneratedValue;
+import javax.persistence.Id;
+import javax.persistence.Table;
+import javax.persistence.Temporal;
+import javax.persistence.TemporalType;
+
+import org.hibernate.annotations.GenericGenerator;
+import org.hibernate.envers.Audited;
+
+ at Entity
+ at Table( name = "EVENTS" )
+ at Audited // <--- this tell Envers to audit (track changes to) this entity
+public class Event {
+ private Long id;
+
+ private String title;
+ private Date date;
+
+ public Event() {
+ // this form used by Hibernate
+ }
+
+ public Event(String title, Date date) {
+ // for application use, to create new events
+ this.title = title;
+ this.date = date;
+ }
+
+ @Id
+ @GeneratedValue(generator="increment")
+ @GenericGenerator(name="increment", strategy = "increment")
+ public Long getId() {
+ return id;
+ }
+
+ private void setId(Long id) {
+ this.id = id;
+ }
+
+ @Temporal(TemporalType.TIMESTAMP)
+ @Column(name = "EVENT_DATE")
+ 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;
+ }
+
+ @Override
+ public int hashCode() {
+ int result = title.hashCode();
+ result = 31 * result + date.hashCode();
+ return result;
+ }
+}
\ No newline at end of file
Copied: core/trunk/documentation/quickstart/tutorials/envers/src/test/resources/META-INF/persistence.xml (from rev 20298, core/trunk/documentation/quickstart/tutorials/entitymanager/src/test/resources/META-INF/persistence.xml)
===================================================================
--- core/trunk/documentation/quickstart/tutorials/envers/src/test/resources/META-INF/persistence.xml (rev 0)
+++ core/trunk/documentation/quickstart/tutorials/envers/src/test/resources/META-INF/persistence.xml 2010-09-10 20:19:35 UTC (rev 20345)
@@ -0,0 +1,64 @@
+<!--
+ ~ 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
+ -->
+<persistence xmlns="http://java.sun.com/xml/ns/persistence"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
+ version="2.0">
+
+ <persistence-unit name="org.hibernate.tutorial.envers">
+ <description>
+ Persistence unit for the Envers tutorial of the Hibernate Getting Started Guide
+ </description>
+
+ <class>org.hibernate.tutorial.envers.Event</class>
+
+ <properties>
+ <property name="javax.persistence.jdbc.driver" value="org.h2.Driver" />
+ <property name="javax.persistence.jdbc.url" value="jdbc:h2:mem:db1;DB_CLOSE_DELAY=-1;MVCC=TRUE" />
+ <property name="javax.persistence.jdbc.user" value="sa" />
+ <property name="javax.persistence.jdbc.password" value="" />
+
+ <property name="hibernate.show_sql" value="true" />
+ <property name="hibernate.hbm2ddl.auto" value="create" />
+
+ <!-- These entries needed to enable Envers -->
+ <!-- todo : ?? http://opensource.atlassian.com/projects/hibernate/browse/HHH-5551 ?? -->
+ <property name="hibernate.ejb.event.post-insert"
+ value="org.hibernate.ejb.event.EJB3PostInsertEventListener,org.hibernate.envers.event.AuditEventListener" />
+ <property name="hibernate.ejb.event.post-update"
+ value="org.hibernate.ejb.event.EJB3PostUpdateEventListener,org.hibernate.envers.event.AuditEventListener" />
+ <property name="hibernate.ejb.event.post-delete"
+ value="org.hibernate.ejb.event.EJB3PostDeleteEventListener,org.hibernate.envers.event.AuditEventListener" />
+ <property name="hibernate.ejb.event.pre-collection-update"
+ value="org.hibernate.envers.event.AuditEventListener" />
+ <property name="hibernate.ejb.event.pre-collection-remove"
+ value="org.hibernate.envers.event.AuditEventListener" />
+ <property name="hibernate.ejb.event.post-collection-recreate"
+ value="org.hibernate.envers.event.AuditEventListener" />
+
+ </properties>
+
+ </persistence-unit>
+
+</persistence>
Modified: core/trunk/documentation/quickstart/tutorials/pom.xml
===================================================================
--- core/trunk/documentation/quickstart/tutorials/pom.xml 2010-09-10 08:40:12 UTC (rev 20344)
+++ core/trunk/documentation/quickstart/tutorials/pom.xml 2010-09-10 20:19:35 UTC (rev 20345)
@@ -43,6 +43,7 @@
<module>basic</module>
<module>annotations</module>
<module>entitymanager</module>
+ <module>envers</module>
</modules>
<dependencies>
More information about the hibernate-commits
mailing list