[hibernate-commits] Hibernate SVN: r15502 - in core/trunk/documentation/envers/src/main/docbook/en-US: content and 1 other directory.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Tue Nov 4 13:11:28 EST 2008
Author: adamw
Date: 2008-11-04 13:11:28 -0500 (Tue, 04 Nov 2008)
New Revision: 15502
Added:
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/schema.xml
core/trunk/documentation/envers/src/main/docbook/en-US/content/source.xml
core/trunk/documentation/envers/src/main/docbook/en-US/content/tables.xml
Modified:
core/trunk/documentation/envers/src/main/docbook/en-US/Envers_Reference.xml
Log:
HHH-3556: Envers documentation partially migrated
Modified: core/trunk/documentation/envers/src/main/docbook/en-US/Envers_Reference.xml
===================================================================
--- core/trunk/documentation/envers/src/main/docbook/en-US/Envers_Reference.xml 2008-11-04 17:44:43 UTC (rev 15501)
+++ core/trunk/documentation/envers/src/main/docbook/en-US/Envers_Reference.xml 2008-11-04 18:11:28 UTC (rev 15502)
@@ -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>
Copied: core/trunk/documentation/envers/src/main/docbook/en-US/content/links.xml (from rev 15501, core/trunk/documentation/envers/src/main/docbook/en-US/content/exceptions.xml)
===================================================================
--- core/trunk/documentation/envers/src/main/docbook/en-US/content/links.xml (rev 0)
+++ core/trunk/documentation/envers/src/main/docbook/en-US/content/links.xml 2008-11-04 18:11:28 UTC (rev 15502)
@@ -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>
Property changes on: core/trunk/documentation/envers/src/main/docbook/en-US/content/links.xml
___________________________________________________________________
Name: svn:mergeinfo
+
Added: core/trunk/documentation/envers/src/main/docbook/en-US/content/migration.xml
===================================================================
--- core/trunk/documentation/envers/src/main/docbook/en-US/content/migration.xml (rev 0)
+++ core/trunk/documentation/envers/src/main/docbook/en-US/content/migration.xml 2008-11-04 18:11:28 UTC (rev 15502)
@@ -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>
Copied: core/trunk/documentation/envers/src/main/docbook/en-US/content/schema.xml (from rev 15501, core/trunk/documentation/envers/src/main/docbook/en-US/content/exceptions.xml)
===================================================================
--- core/trunk/documentation/envers/src/main/docbook/en-US/content/schema.xml (rev 0)
+++ core/trunk/documentation/envers/src/main/docbook/en-US/content/schema.xml 2008-11-04 18:11:28 UTC (rev 15502)
@@ -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>
Added: core/trunk/documentation/envers/src/main/docbook/en-US/content/source.xml
===================================================================
--- core/trunk/documentation/envers/src/main/docbook/en-US/content/source.xml (rev 0)
+++ core/trunk/documentation/envers/src/main/docbook/en-US/content/source.xml 2008-11-04 18:11:28 UTC (rev 15502)
@@ -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>
+
Copied: core/trunk/documentation/envers/src/main/docbook/en-US/content/tables.xml (from rev 15501, core/trunk/documentation/envers/src/main/docbook/en-US/content/quickstart.xml)
===================================================================
--- core/trunk/documentation/envers/src/main/docbook/en-US/content/tables.xml (rev 0)
+++ core/trunk/documentation/envers/src/main/docbook/en-US/content/tables.xml 2008-11-04 18:11:28 UTC (rev 15502)
@@ -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>
+
More information about the hibernate-commits
mailing list