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

HHH-3556: Envers documentation partially migrated 

git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@15502 1b8cb986-b30d-0410-93ca-fae66ebed9b2
This commit is contained in:
Adam Warski 2008-11-04 18:11:28 +00:00
parent 137585b17f
commit 46b1ca8267
6 changed files with 386 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
documentation/envers/src/main/docbook/en-US/Envers_Reference.xml
View File

@ -51,7 +51,12 @@
<xi:include href="content/example.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/revisionlog.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/schema.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/tables.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/source.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/exceptions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/migration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/links.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</book>

42
documentation/envers/src/main/docbook/en-US/content/links.xml Normal file
View File

@ -0,0 +1,42 @@
<?xml version='1.0' encoding="UTF-8"?>
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
~ Copyright (c) 2008, Red Hat Middleware LLC 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 Middleware LLC.
~
~ 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
-->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="links">
<title>Links</title>
<para>
Some useful links:
</para>
<orderedlist>
<listitem>
<para>
</para>
</listitem>
</orderedlist>
</chapter>

32
documentation/envers/src/main/docbook/en-US/content/migration.xml Normal file
View File

@ -0,0 +1,32 @@
<?xml version='1.0' encoding="UTF-8"?>
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
~ Copyright (c) 2008, Red Hat Middleware LLC 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 Middleware LLC.
~
~ 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
-->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="migration">
<title>Migration from Envers standalone</title>
</chapter>

120
documentation/envers/src/main/docbook/en-US/content/schema.xml Normal file
View File

@ -0,0 +1,120 @@
<?xml version='1.0' encoding="UTF-8"?>
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
~ Copyright (c) 2008, Red Hat Middleware LLC 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 Middleware LLC.
~
~ 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
-->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="schema">
<title>Generating schema with Ant</title>
<para>
If you'd like to generate the database schema file with the Hibernate Tools Ant task,
you'll probably notice that the generated file doesn't contain definitions of audit
tables. To generate also the audit tables, you simply need to use
<literal>org.hibernate.tool.ant.EnversHibernateToolTask</literal> instead of the usual
<literal>org.hibernate.tool.ant.HibernateToolTask</literal>. The former class extends
the latter, and only adds generation of the version entities. So you can use the task
just as you used to.
</para>
<para>
For example:
</para>
<programlisting><![CDATA[<target name="schemaexport" depends="build-demo"
description="Exports a generated schema to DB and file">
<taskdef name="hibernatetool"
classname="org.hibernate.tool.ant.EnversHibernateToolTask"
classpathref="build.demo.classpath"/>
<hibernatetool destdir=".">
<classpath>
<fileset refid="lib.hibernate" />
<path location="${build.demo.dir}" />
<path location="${build.main.dir}" />
</classpath>
<jpaconfiguration persistenceunit="ConsolePU" />
<hbm2ddl
drop="false"
create="true"
export="false"
outputfilename="versioning-ddl.sql"
delimiter=";"
format="true"/>
</hibernatetool>
</target>]]></programlisting>
<para>
Will generate the following schema:
</para>
<programlisting><![CDATA[
create table Address (
id integer generated by default as identity (start with 1),
flatNumber integer,
houseNumber integer,
streetName varchar(255),
primary key (id)
);
create table Address_audit (
id integer not null,
REV integer not null,
flatNumber integer,
houseNumber integer,
streetName varchar(255),
REVTYPE tinyint,
primary key (id, REV)
);
create table Person (
id integer generated by default as identity (start with 1),
name varchar(255),
surname varchar(255),
address_id integer,
primary key (id)
);
create table Person_audit (
id integer not null,
REV integer not null,
name varchar(255),
surname varchar(255),
REVTYPE tinyint,
address_id integer,
primary key (id, REV)
);
create table REVINFO (
REVID integer generated by default as identity (start with 1),
REVTMSTMP bigint,
primary key (REVID)
);
alter table Person
add constraint FK8E488775E4C3EA63
foreign key (address_id)
references Address;
]]></programlisting>
</chapter>

76
documentation/envers/src/main/docbook/en-US/content/source.xml Normal file
View File

@ -0,0 +1,76 @@
<?xml version='1.0' encoding="UTF-8"?>
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
~ Copyright (c) 2008, Red Hat Middleware LLC 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 Middleware LLC.
~
~ 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
-->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="source">
<title>Building from source and testing</title>
<para>
Envers, as a module of Hibernate, uses a standard Maven2 build. So all the usual
build targets (compile, test, install) will work.
</para>
<para>
You can check out the source code
<ulink url="http://anonsvn.jboss.org/repos/hibernate/core/trunk/">from SVN</ulink>,
or browse it using
<ulink url="http://fisheye.jboss.org/browse/Hibernate">FishEye</ulink>.
</para>
<para>
The tests use, by default, use a H2 in-memory database. The configuration
file can be found in <literal>src/test/resources/hibernate.test.cfg.xml</literal>.
</para>
<para>
The tests use TestNG, and can be found in the
<literal>org.hibernate.envers.test.integration</literal> package
(or rather, in subpackages of this package).
The tests aren't unit tests, as they don't test individual classes, but the behaviour
and interaction of many classes, hence the name of package.
</para>
<para>
A test normally consists of an entity (or two entities) that will be audited and extends the
<literal>AbstractEntityTest</literal> class, which has one abstract method:
<literal>configure(Ejb3Configuration)</literal>. The role of this method is to add the entities
that will be used in the test to the configuration.
</para>
<para>
The test data is in most cases created in the "initData" method (which is called once before
the tests from this class are executed), which normally creates a couple of revisions,
by persisting and updating entities. The tests first check if the revisions, in which
entities where modified are correct (the testRevisionCounts method), and if the historic
data is correct (the testHistoryOfXxx methods).
</para>
<para>
The results of the tests can be found in the "doc/report" directory.
</para>
</chapter>

111
documentation/envers/src/main/docbook/en-US/content/tables.xml Normal file
View File

@ -0,0 +1,111 @@
<?xml version='1.0' encoding="UTF-8"?>
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
~ Copyright (c) 2008, Red Hat Middleware LLC 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 Middleware LLC.
~
~ 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
-->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="tables">
<title>Generated tables and their content</title>
<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
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.
</para>
<para>
The audit table has the following fields:
</para>
<orderedlist>
<listitem>
<para>
id of the original entity (this can be more then one column, if using an embedded or multiple id)
</para>
</listitem>
<listitem>
<para>
revision number - an integer
</para>
</listitem>
<listitem>
<para>
revision type - a small integer
</para>
</listitem>
<listitem>
<para>
audited fields from the original entity
</para>
</listitem>
</orderedlist>
<para>
The primary key of the audit table is the combination of the original id of the
entity and the revision number - there can be at most one historic entry for a given
entity instance at a given revision.
</para>
<para>
The current entity data is stored in the original table and in the audit table.
This is a duplication of data, however as this solution makes the query system much more
powerful, and as memory is cheap, hopefully this won't be a major drawback for the users.
A row in the audit table with entity id ID, revision N and data D means:
entity with id ID has data D from revision N upwards. Hence, if we want to find an
entity at revision M, we have to search for a row in the audit table, which has the
revision number smaller or equal to M, but as large as possible. If no such row is
found, or a row with a "deleted" marker is found, it means that the entity didn't
exist at that revision.
</para>
<para>
The "revision type" field can currently have three values: 0, 1, 2, which means,
respectively, ADD, MOD and DEL. A row with a revision of type DEL will only contain the
id of the entity and no data (all fields NULL), as it only serves as a marker saying
"this entity was deleted at that revision".
</para>
<para>
Additionaly, there is a "REVINFO" table generated, which contains only two fields:
the revision id and revision timestamp. A row is inserted into this table on each
new revision, that is, on each commit of a transaction, which changes audited data.
The name of this table can be configured, as well as additional content stored,
using the <literal>@RevisionEntity</literal> annotation, see <xref linkend="revisionlog"/>.
</para>
<para>
While global revisions are a good way to provide correct auditing of relations,
some people have pointed out that this may be a bottleneck in systems, where data
is very often modified. One viable solution is to introduce an option to have an
entity "locally revisioned", that is revisions would be created for it independently.
This wouldn't enable correct versioning of relations, but wouldn't also require the
"REVINFO" table. Another possibility if to have "revisioning groups", that is groups
of entities which share revision numbering. Each such group would have to consist
of one or more strongly connected component of the graph induced by relations between
entities. Your opinions on the subject are very welcome on the forum! :)
</para>
</chapter>