HHH-3556: migration docs
git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@15515 1b8cb986-b30d-0410-93ca-fae66ebed9b2
This commit is contained in:
Adam Warski
parent
843d3c648f
commit
e3611638b5
|
|
@ -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
|
||||
|
|
@ -120,17 +120,6 @@
|
|||
using "mappedBy" attribute in a one-to-one relation).
|
||||
</entry>
|
||||
</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>
|
||||
|
|
@ -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" />
|
||||
|
|
|
|||
|
|
@ -31,10 +31,37 @@
|
|||
<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>
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
||||
@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>
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue