[hibernate-commits] Hibernate SVN: r15516 - core/trunk/documentation/envers/src/main/docbook/en-US/content.

Author: adamw Date: 2008-11-05 03:59:14 -0500 (Wed, 05 Nov 2008) New Revision: 15516 Modified: core/trunk/documentation/envers/src/main/docbook/en-US/content/configuration.xml core/trunk/documentation/envers/src/main/docbook/en-US/content/migration.xml core/trunk/documentation/envers/src/main/docbook/en-US/content/preface.xml core/trunk/documentation/envers/src/main/docbook/en-US/content/quickstart.xml Log: HHH-3556: minor corrections 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:42:01 UTC (rev 15515) +++ core/trunk/documentation/envers/src/main/docbook/en-US/content/configuration.xml 2008-11-05 08:59:14 UTC (rev 15516) @@ -35,8 +35,8 @@ </para> <para> - However, as Envers generates some tables, it is possible to set the prefix and suffix - that is added to the entity name to create a versions table for an entity, as well + However, as Envers generates some entities, and maps them to tables, it is possible to set the prefix and suffix + that is added to the entity name to create an audit table for an entity, as well as set the names of the fields that are generated. </para> @@ -81,7 +81,7 @@ String that will be appended to the name of an audited entity to create the name of the entity, that will hold audit information. If you audit an entity with a table name Person, in the default setting Envers - will generate a <literal>Person_audit</literal> table to store historical data. + will generate a <literal>Person_AUD</literal> table to store historical data. </entry> </row> <row> @@ -103,7 +103,7 @@ REVTYPE </entry> <entry> - Name of a field in the aduit entity that will hold the type of the + Name of a field in the audit entity that will hold the type of the revision (currently, this can be: add, mod, del). </entry> </row> @@ -176,13 +176,13 @@ &lt;/persistence-unit&gt;</programlisting> <para> - You can also set the name of the versions table on a per-entity basis, using the - <literal>@AuditTable</literal> annotation (see also in the javadoc). It may be tedious to add this + You can also set the name of the audit table on a per-entity basis, using the + <literal>@AuditTable</literal> annotation. It may be tedious to add this annotation to every audited entity, so if possible, it's better to use a prefix/suffix. </para> <para> - If you have a mapping with secondary tables, version tables for them will be generated in + If you have a mapping with secondary tables, audit tables for them will be generated in the same way (by adding the prefix and suffix). If you wish to overwrite this behaviour, you can use the <literal>@SecondaryAuditTable</literal> and <literal>@SecondaryAuditTables</literal> annotations. 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:42:01 UTC (rev 15515) +++ core/trunk/documentation/envers/src/main/docbook/en-US/content/migration.xml 2008-11-05 08:59:14 UTC (rev 15516) @@ -39,6 +39,18 @@ with Oracle and other databases, which don't allow tables and field names to start with "_". </para> + <sect1 id="migrations-code"> + + <title>Changes to code</title> + + <para> + Public API changes involve changing "versioning" to "auditing". So, <literal>@Versioned</literal> + became <literal>@Audited</literal>; <literal>@VersionsTable</literal> became <literal>@AuditTable</literal> + and so on. + </para> + + </sect1> + <sect1 id="migrations-configuration"> <title>Changes to configuration</title> @@ -85,6 +97,9 @@ 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. + Also, the <literal>org.hibernate.envers.warnOnUnsupportedTypes</literal> configuraiton + option was removed. In case you are using some unsupported types, use the <literal>@NotAudited</literal> + annotation. </para> <para> @@ -136,16 +151,4 @@ }]]></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/preface.xml =================================================================== --- core/trunk/documentation/envers/src/main/docbook/en-US/content/preface.xml 2008-11-05 08:42:01 UTC (rev 15515) +++ core/trunk/documentation/envers/src/main/docbook/en-US/content/preface.xml 2008-11-05 08:59:14 UTC (rev 15516) @@ -46,7 +46,7 @@ </para> <para> - The library works with Hibernate and Hibernate Annotations or Entity Manager. + The library works with Hibernate and requires Hibernate Annotations or Entity Manager. For the auditing to work properly, the entities must have immutable unique identifiers (primary keys). You can use Envers wherever Hibernate works: standalone, inside JBoss AS, with JBoss Seam or Spring. @@ -59,15 +59,15 @@ <orderedlist> <listitem> <para> - versioning of all mappings defined by the JPA specification, except joined and + auditing of all mappings defined by the JPA specification, except joined and table-per-class inheritance </para> </listitem> <listitem> <para> - versioning of some Hibernate mappings, which extend JPA, like custom types and + auditing of Hibernate mappings, which extend JPA, like custom types and collections/maps of "simple" types (Strings, Integers, etc.) - (see <xref linkend="exceptions"/> for one exception) + (see also <xref linkend="exceptions"/>) </para> </listitem> <listitem> 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:42:01 UTC (rev 15515) +++ core/trunk/documentation/envers/src/main/docbook/en-US/content/quickstart.xml 2008-11-05 08:59:14 UTC (rev 15516) @@ -29,7 +29,8 @@ <title>Quickstart</title> <para> - When configuring your persistence unit (the persistence.xml file), add the following event + When configuring your Hibernate (<literal>persistence.xml</literal> if you are using JPA, + <literal>hibernate.cfg.xml</literal> or other if you are using Hibernate directly), add the following event listeners: (this will allow Envers to check if any audited entities were modified) </para> @@ -57,7 +58,7 @@ <para> Then, annotate your persistent class with <literal>@Audited</literal> - this will make all - properties versioned. For example: + properties audited. For example: </para> <programlisting>import org.hibernate.envers.Audited; @@ -112,7 +113,7 @@ And that's it! You create, modify and delete the entites as always. If you look at the generated schema, you will notice that it is unchanged by adding auditing for the Address and Person entities. Also, the data they hold is the same. There are, - however, two new tables - <literal>Address_audit</literal> and <literal>Person_audit</literal>, + however, two new tables - <literal>Address_AUD</literal> and <literal>Person_AUD</literal>, which store the historical data, whenever you commit a transaction. </para> @@ -123,8 +124,8 @@ </para> <para> - You can access the audit of an entity using the <literal>AuditReader</literal> interface, which you - can obtain when having an open EntityManager. See also the javadocs. + You can access the audit (history) of an entity using the <literal>AuditReader</literal> interface, which you + can obtain when having an open EntityManager. </para> <programlisting>AuditReader reader = AuditReaderFactory.get(entityManager);