[hibernate-commits] Hibernate SVN: r15515 - core/trunk/documentation/envers/src/main/docbook/en-US/content.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Wed Nov 5 03:42:01 EST 2008
Author: adamw
Date: 2008-11-05 03:42:01 -0500 (Wed, 05 Nov 2008)
New Revision: 15515
Modified:
core/trunk/documentation/envers/src/main/docbook/en-US/content/configuration.xml
core/trunk/documentation/envers/src/main/docbook/en-US/content/links.xml
core/trunk/documentation/envers/src/main/docbook/en-US/content/migration.xml
core/trunk/documentation/envers/src/main/docbook/en-US/content/quickstart.xml
core/trunk/documentation/envers/src/main/docbook/en-US/content/schema.xml
core/trunk/documentation/envers/src/main/docbook/en-US/content/tables.xml
Log:
HHH-3556: migration docs
Modified: core/trunk/documentation/envers/src/main/docbook/en-US/content/configuration.xml
===================================================================
--- core/trunk/documentation/envers/src/main/docbook/en-US/content/configuration.xml 2008-11-05 08:41:14 UTC (rev 15514)
+++ core/trunk/documentation/envers/src/main/docbook/en-US/content/configuration.xml 2008-11-05 08:42:01 UTC (rev 15515)
@@ -75,7 +75,7 @@
<property>org.hibernate.envers.auditTableSuffix</property>
</entry>
<entry>
- _audit
+ _AUD
</entry>
<entry>
String that will be appended to the name of an audited entity to create
@@ -122,17 +122,6 @@
</row>
<row>
<entry>
- <property>org.hibernate.envers.warnOnUnsupportedTypes</property>
- </entry>
- <entry>
- false
- </entry>
- <entry>
- TODO: remove
- </entry>
- </row>
- <row>
- <entry>
<property>org.hibernate.envers.doNotAuditOptimisticLockingField</property>
</entry>
<entry>
@@ -168,17 +157,17 @@
<!-- other hibernate properties -->
<property name="hibernate.ejb.event.post-insert"
- value="org.hibernate.envers.event.VersionsEventListener" />
+ value="org.hibernate.envers.event.AuditEventListener" />
<property name="hibernate.ejb.event.post-update"
- value="org.hibernate.envers.event.VersionsEventListener" />
+ value="org.hibernate.envers.event.AuditEventListener" />
<property name="hibernate.ejb.event.post-delete"
- value="org.hibernate.envers.event.VersionsEventListener" />
+ value="org.hibernate.envers.event.AuditEventListener" />
<property name="hibernate.ejb.event.pre-collection-update"
- value="org.hibernate.envers.event.VersionsEventListener" />
+ value="org.hibernate.envers.event.AuditEventListener" />
<property name="hibernate.ejb.event.pre-collection-remove"
- value="org.hibernate.envers.event.VersionsEventListener" />
+ value="org.hibernate.envers.event.AuditEventListener" />
<property name="hibernate.ejb.event.post-collection-recreate"
- value="org.hibernate.envers.event.VersionsEventListener" />
+ value="org.hibernate.envers.event.AuditEventListener" />
<property name="org.hibernate.envers.versionsTableSuffix" value="_V" />
<property name="org.hibernate.envers.revisionFieldName" value="ver_rev" />
Modified: core/trunk/documentation/envers/src/main/docbook/en-US/content/links.xml
===================================================================
--- core/trunk/documentation/envers/src/main/docbook/en-US/content/links.xml 2008-11-05 08:41:14 UTC (rev 15514)
+++ core/trunk/documentation/envers/src/main/docbook/en-US/content/links.xml 2008-11-05 08:42:01 UTC (rev 15515)
@@ -31,12 +31,39 @@
<para>
Some useful links:
</para>
+
<orderedlist>
<listitem>
<para>
-
+ <ulink url="http://hibernate.org">Hibernate</ulink>
</para>
</listitem>
+ <listitem>
+ <para>
+ <ulink url="http://www.jboss.com/index.html?module=bb&op=viewforum&f=283">Forum</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://anonsvn.jboss.org/repos/hibernate/core/trunk/envers/">Anonymous SVN</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://opensource.atlassian.com/projects/hibernate/browse/HHH">JIRA issue tracker</ulink>
+ (when adding issues concerning Envers, be sure to select the "envers" component!)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="irc://irc.freenode.net:6667/envers">IRC channel</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://www.jboss.org/feeds/view/envers">Blog</ulink>
+ </para>
+ </listitem>
</orderedlist>
</chapter>
Modified: core/trunk/documentation/envers/src/main/docbook/en-US/content/migration.xml
===================================================================
--- core/trunk/documentation/envers/src/main/docbook/en-US/content/migration.xml 2008-11-05 08:41:14 UTC (rev 15514)
+++ core/trunk/documentation/envers/src/main/docbook/en-US/content/migration.xml 2008-11-05 08:42:01 UTC (rev 15515)
@@ -28,5 +28,124 @@
<chapter id="migration">
<title>Migration from Envers standalone</title>
+ <para>
+ With the inclusion of Envers as a Hibernate module, some of the public API and configuration defaults
+ changed. In general, "versioning" is renamed to "auditing" (to avoid confusion with the annotation used
+ for indicating an optimistic locking field - <literal>@Version</literal>).
+ </para>
+ <para>
+ Because of changing some configuration defaults, there should be no more problems using Envers out-of-the-box
+ with Oracle and other databases, which don't allow tables and field names to start with "_".
+ </para>
+
+ <sect1 id="migrations-configuration">
+
+ <title>Changes to configuration</title>
+
+ <para>
+ First of all, the name of the event listener changed. It is now named
+ <literal>org.hibernate.envers.event.AuditEventListener</literal>, instead of
+ <literal>org.jboss.envers.event.VersionsEventListener</literal>. So to make Envers
+ work, you will have to change these settings in your <literal>persistence.xml</literal>
+ or Hibernate configuration.
+ </para>
+
+ <para>
+ Secondly, the names of the audit (versions) tables and additional auditing (versioning) fields
+ changed. The default suffix added to the table name is now <literal>_AUD</literal>, instead of
+ <literal>_versions</literal>. The name of the field that holds the revision number, and which
+ is added to each audit (versions) table, is now <literal>REV</literal>, instead of
+ <literal>_revision</literal>. Finally, the name of the field that holds the type of the revision,
+ is now <literal>REVTYPE</literal>, instead of <literal>_rev_type</literal>.
+ </para>
+
+ <para>
+ If you have a schema generated with the old version of Envers, you will
+ have to set those properties, to use the new version of Envers without problems:
+ </para>
+
+ <programlisting><persistence-unit ...>
+<provider>org.hibernate.ejb.HibernatePersistence</provider>
+<class>...</class>
+<properties>
+ <property name="hibernate.dialect" ... />
+ <!-- other hibernate properties -->
+
+ <!-- Envers listeners -->
+
+ <property name="org.hibernate.envers.versionsTableSuffix" value="_versions" />
+ <property name="org.hibernate.envers.revisionFieldName" value="_revision" />
+ <property name="org.hibernate.envers.revisionTypeFieldName" value="_rev_type" />
+ <!-- other envers properties -->
+</properties>
+</persistence-unit></programlisting>
+
+ <para>
+ The <literal>org.hibernate.envers.doNotAuditOptimisticLockingField</literal> property is
+ now by default <literal>true</literal>, instead of <literal>false</literal>. You probably
+ never would want to audit the optimistic locking field.
+ </para>
+
+ <para>
+ See <xref linkend="configuration"/> for details on the configuration and a description of the
+ configuration options.
+ </para>
+ </sect1>
+
+ <sect1 id="migrations-revisionlog">
+
+ <title>Changes to the revision entity</title>
+
+ <para>
+ This section applies only if you don't have a custom revision entity.
+ The name of the revision entity generated by default changed, so if you used the default one, you'll
+ have to add a custom revision entity, and map it to the old table. Here's the class
+ that you have to create:
+ </para>
+
+ <programlisting><![CDATA[package org.hibernate.envers.example;
+
+import org.hibernate.envers.RevisionNumber;
+import org.hibernate.envers.RevisionTimestamp;
+import org.hibernate.envers.RevisionEntity;
+
+import javax.persistence.Id;
+import javax.persistence.GeneratedValue;
+import javax.persistence.Entity;
+import javax.persistence.Column;
+import javax.persistence.Table;
+
+ at Entity
+ at RevisionEntity
+ at Table(name="_revisions_info")
+public class ExampleRevEntity {
+ @Id
+ @GeneratedValue
+ @RevisionNumber
+ @Column(name="revision_id")
+ private int id;
+
+ @RevisionTimestamp
+ @Column(name="revision_timestamp")
+ private long timestamp;
+
+ private String username;
+
+ // Getters, setters, equals, hashCode ...
+}]]></programlisting>
+
+ </sect1>
+
+ <sect1 id="migrations-code">
+
+ <title>Changes to code</title>
+
+ <para>
+ Public API changes involve only changing "versioning" to "auditing". So, <literal>@Versioned</literal>
+ became <literal>@Audited</literal>; <literal>@VersionsTable</literal> became <literal>@AuditTable</literal>
+ and so on.
+ </para>
+
+ </sect1>
</chapter>
Modified: core/trunk/documentation/envers/src/main/docbook/en-US/content/quickstart.xml
===================================================================
--- core/trunk/documentation/envers/src/main/docbook/en-US/content/quickstart.xml 2008-11-05 08:41:14 UTC (rev 15514)
+++ core/trunk/documentation/envers/src/main/docbook/en-US/content/quickstart.xml 2008-11-05 08:42:01 UTC (rev 15515)
@@ -41,17 +41,17 @@
<!-- other hibernate properties -->
<property name="hibernate.ejb.event.post-insert"
- value="org.hibernate.envers.event.VersionsEventListener" />
+ value="org.hibernate.envers.event.AuditEventListener" />
<property name="hibernate.ejb.event.post-update"
- value="org.hibernate.envers.event.VersionsEventListener" />
+ value="org.hibernate.envers.event.AuditEventListener" />
<property name="hibernate.ejb.event.post-delete"
- value="org.hibernate.envers.event.VersionsEventListener" />
+ value="org.hibernate.envers.event.AuditEventListener" />
<property name="hibernate.ejb.event.pre-collection-update"
- value="org.hibernate.envers.event.VersionsEventListener" />
+ value="org.hibernate.envers.event.AuditEventListener" />
<property name="hibernate.ejb.event.pre-collection-remove"
- value="org.hibernate.envers.event.VersionsEventListener" />
+ value="org.hibernate.envers.event.AuditEventListener" />
<property name="hibernate.ejb.event.post-collection-recreate"
- value="org.hibernate.envers.event.VersionsEventListener" />
+ value="org.hibernate.envers.event.AuditEventListener" />
</properties>
</persistence-unit></programlisting>
Modified: core/trunk/documentation/envers/src/main/docbook/en-US/content/schema.xml
===================================================================
--- core/trunk/documentation/envers/src/main/docbook/en-US/content/schema.xml 2008-11-05 08:41:14 UTC (rev 15514)
+++ core/trunk/documentation/envers/src/main/docbook/en-US/content/schema.xml 2008-11-05 08:42:01 UTC (rev 15515)
@@ -78,7 +78,7 @@
primary key (id)
);
- create table Address_audit (
+ create table Address_AUD (
id integer not null,
REV integer not null,
flatNumber integer,
@@ -96,7 +96,7 @@
primary key (id)
);
- create table Person_audit (
+ create table Person_AUD (
id integer not null,
REV integer not null,
name varchar(255),
@@ -107,9 +107,9 @@
);
create table REVINFO (
- REVID integer generated by default as identity (start with 1),
- REVTMSTMP bigint,
- primary key (REVID)
+ REV integer generated by default as identity (start with 1),
+ REVTSTMP bigint,
+ primary key (REV)
);
alter table Person
Modified: core/trunk/documentation/envers/src/main/docbook/en-US/content/tables.xml
===================================================================
--- core/trunk/documentation/envers/src/main/docbook/en-US/content/tables.xml 2008-11-05 08:41:14 UTC (rev 15514)
+++ core/trunk/documentation/envers/src/main/docbook/en-US/content/tables.xml 2008-11-05 08:42:01 UTC (rev 15515)
@@ -30,7 +30,7 @@
<para>
For each audited entity (that is, for each entity containing at least one audited field), an audit
- table is created. By default, the audit table's name is created by adding a "_audit" suffix to
+ table is created. By default, the audit table's name is created by adding a "_AUD" suffix to
the original name, but this can be overriden by specifing a different suffix/prefix
(see <xref linkend="configuration"/>) or on a per-entity basis using the
<literal>@AuditTable</literal> annotation.
More information about the hibernate-commits
mailing list