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 @@ &lt;!-- other hibernate properties --&gt; &lt;property name="hibernate.ejb.event.post-insert" - value="org.hibernate.envers.event.VersionsEventListener" /&gt; + value="org.hibernate.envers.event.AuditEventListener" /&gt; &lt;property name="hibernate.ejb.event.post-update" - value="org.hibernate.envers.event.VersionsEventListener" /&gt; + value="org.hibernate.envers.event.AuditEventListener" /&gt; &lt;property name="hibernate.ejb.event.post-delete" - value="org.hibernate.envers.event.VersionsEventListener" /&gt; + value="org.hibernate.envers.event.AuditEventListener" /&gt; &lt;property name="hibernate.ejb.event.pre-collection-update" - value="org.hibernate.envers.event.VersionsEventListener" /&gt; + value="org.hibernate.envers.event.AuditEventListener" /&gt; &lt;property name="hibernate.ejb.event.pre-collection-remove" - value="org.hibernate.envers.event.VersionsEventListener" /&gt; + value="org.hibernate.envers.event.AuditEventListener" /&gt; &lt;property name="hibernate.ejb.event.post-collection-recreate" - value="org.hibernate.envers.event.VersionsEventListener" /&gt; + value="org.hibernate.envers.event.AuditEventListener" /&gt; &lt;property name="org.hibernate.envers.versionsTableSuffix" value="_V" /&gt; &lt;property name="org.hibernate.envers.revisionFieldName" value="ver_rev" /&gt; 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&amp;op=viewforum&... + </para> + </listitem> + <listitem> + <para> + <ulink url="http://anonsvn.jboss.org/repos/hibernate/core/trunk/envers/&quo... SVN</ulink> + </para> + </listitem> + <listitem> + <para> + <ulink url="http://opensource.atlassian.com/projects/hibernate/browse/HHH&q... 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>&lt;persistence-unit ...&gt; +&lt;provider&gt;org.hibernate.ejb.HibernatePersistence&lt;/provider&gt; +&lt;class&gt;...&lt;/class&gt; +&lt;properties&gt; + &lt;property name="hibernate.dialect" ... /&gt; + &lt;!-- other hibernate properties --&gt; + + &lt;!-- Envers listeners --&gt; + + &lt;property name="org.hibernate.envers.versionsTableSuffix" value="_versions" /&gt; + &lt;property name="org.hibernate.envers.revisionFieldName" value="_revision" /&gt; + &lt;property name="org.hibernate.envers.revisionTypeFieldName" value="_rev_type" /&gt; + &lt;!-- other envers properties --&gt; +&lt;/properties&gt; +&lt;/persistence-unit&gt;</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; + +@Entity +@RevisionEntity +@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 @@ &lt;!-- other hibernate properties --&gt; &lt;property name="hibernate.ejb.event.post-insert" - value="org.hibernate.envers.event.VersionsEventListener" /&gt; + value="org.hibernate.envers.event.AuditEventListener" /&gt; &lt;property name="hibernate.ejb.event.post-update" - value="org.hibernate.envers.event.VersionsEventListener" /&gt; + value="org.hibernate.envers.event.AuditEventListener" /&gt; &lt;property name="hibernate.ejb.event.post-delete" - value="org.hibernate.envers.event.VersionsEventListener" /&gt; + value="org.hibernate.envers.event.AuditEventListener" /&gt; &lt;property name="hibernate.ejb.event.pre-collection-update" - value="org.hibernate.envers.event.VersionsEventListener" /&gt; + value="org.hibernate.envers.event.AuditEventListener" /&gt; &lt;property name="hibernate.ejb.event.pre-collection-remove" - value="org.hibernate.envers.event.VersionsEventListener" /&gt; + value="org.hibernate.envers.event.AuditEventListener" /&gt; &lt;property name="hibernate.ejb.event.post-collection-recreate" - value="org.hibernate.envers.event.VersionsEventListener" /&gt; + value="org.hibernate.envers.event.AuditEventListener" /&gt; &lt;/properties&gt; &lt;/persistence-unit&gt;</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.