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</...;. + </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> +