HHH-11886 - Elaborate Envers documentation and switch to actual source code examples

documentation/documentation.gradle

@@ -57,6 +57,7 @@ dependencies {
 	testCompile( 'org.apache.commons:commons-lang3:3.4' )
 
 	testCompile( project(':hibernate-ehcache') )
+	testCompile( project(':hibernate-envers') )
 	testCompile( project(':hibernate-spatial') )
 	testCompile( project(path: ':hibernate-core', configuration: 'tests') )
 

documentation/src/main/asciidoc/userguide/chapters/envers/Envers.adoc

@@ -1,6 +1,7 @@
 [[envers]]
 == Envers
-:sourcedir: extras
+:sourcedir: ../../../../../test/java/org/hibernate/userguide/envers
+:extrasdir: extras
 
 === Basics
 
@@ -27,9 +28,83 @@ Envers automatically creates audit tables if `hibernate.hbm2ddl.auto` option is
 Appropriate DDL statements can also be generated with an Ant task in <<envers-generateschema>>.
 ====
 
+Considering we have a `Customer` entity, when annotating it with the `Audited` annotation,
+Hibernate is going to generate the following tables using the `hibernate.hbm2ddl.auto` schema tool:
+
+[[envers-audited-mapping-example]]
+.Basic Envers entity mapping
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/AuditTest.java[tags=envers-audited-mapping-example]
+----
+
+[source, SQL, indent=0]
+----
+include::{extrasdir}/envers-audited-mapping-example.sql[]
+----
+====
+
 Instead of annotating the whole class and auditing all properties, you can annotate only some persistent properties with `@Audited`.
 This will cause only these properties to be audited.
 
+Now, considering the previous `Customer` entity,
+let's see how Envers auditing works when inserting, updating, and deleting the entity in question.
+
+[[envers-audited-insert-example]]
+.Auditing the entity `INSERT` operation
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/AuditTest.java[tags=envers-audited-insert-example]
+----
+
+[source, SQL, indent=0]
+----
+include::{extrasdir}/envers-audited-insert-example.sql[]
+----
+====
+
+[[envers-audited-update-example]]
+.Auditing the entity `UPDATE` operation
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/AuditTest.java[tags=envers-audited-update-example]
+----
+
+[source, SQL, indent=0]
+----
+include::{extrasdir}/envers-audited-update-example.sql[]
+----
+====
+
+[[envers-audited-delete-example]]
+.Auditing the entity `DELETE` operation
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/AuditTest.java[tags=envers-audited-delete-example]
+----
+
+[source, SQL, indent=0]
+----
+include::{extrasdir}/envers-audited-delete-example.sql[]
+----
+====
+
+The `REVTYPE` column value is taken from the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/envers/RevisionType.html[`RevisionType`] Enum.
+
+[[envers-revtype-column]]
+.`REVTYPE` column values
+[width="100%",cols="20%,20%,60%",]
+|=================================
+|Database column value |Associated `RevisionType` Enum value |Description
+|0 | `ADD` |A database table row was inserted.
+|1 | `MOD` |A database table row was updated.
+|1 | `DEL` |A database table row was deleted.
+|=================================
+
 The audit (history) of an entity can be accessed using the `AuditReader` interface, which can be obtained having an open `EntityManager` or `Session` via the `AuditReaderFactory`.
 See the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/envers/AuditReaderFactory.html[Javadocs] for these classes for details on the functionality offered.
 

documentation/src/main/asciidoc/userguide/chapters/envers/extras/envers-audited-delete-example.sql

@@ -0,0 +1,30 @@
+delete
+from
+    Customer
+where
+    id = ?
+
+-- binding parameter [1] as [BIGINT]    - [1]
+
+insert
+into
+    REVINFO
+    (REV, REVTSTMP)
+values
+    (null, ?)
+
+-- binding parameter [1] as [BIGINT]    - [1500906092876]
+
+insert
+into
+    Customer_AUD
+    (REVTYPE, created_on, firstName, lastName, id, REV)
+values
+    (?, ?, ?, ?, ?, ?)
+
+-- binding parameter [1] as [INTEGER]   - [2]
+-- binding parameter [2] as [TIMESTAMP] - [null]
+-- binding parameter [3] as [VARCHAR]   - [null]
+-- binding parameter [4] as [VARCHAR]   - [null]
+-- binding parameter [5] as [BIGINT]    - [1]
+-- binding parameter [6] as [INTEGER]   - [3]

documentation/src/main/asciidoc/userguide/chapters/envers/extras/envers-audited-insert-example.sql

@@ -0,0 +1,34 @@
+insert
+into
+    Customer
+    (created_on, firstName, lastName, id)
+values
+    (?, ?, ?, ?)
+
+-- binding parameter [1] as [TIMESTAMP] - [Mon Jul 24 17:21:32 EEST 2017]
+-- binding parameter [2] as [VARCHAR]   - [John]
+-- binding parameter [3] as [VARCHAR]   - [Doe]
+-- binding parameter [4] as [BIGINT]    - [1]
+
+insert
+into
+    REVINFO
+    (REV, REVTSTMP)
+values
+    (null, ?)
+
+-- binding parameter [1] as [BIGINT]    - [1500906092803]
+
+insert
+into
+    Customer_AUD
+    (REVTYPE, created_on, firstName, lastName, id, REV)
+values
+    (?, ?, ?, ?, ?, ?)
+
+-- binding parameter [1] as [INTEGER]   - [0]
+-- binding parameter [2] as [TIMESTAMP] - [Mon Jul 24 17:21:32 EEST 2017]
+-- binding parameter [3] as [VARCHAR]   - [John]
+-- binding parameter [4] as [VARCHAR]   - [Doe]
+-- binding parameter [5] as [BIGINT]    - [1]
+-- binding parameter [6] as [INTEGER]   - [1]

documentation/src/main/asciidoc/userguide/chapters/envers/extras/envers-audited-mapping-example.sql

@@ -0,0 +1,28 @@
+create table Customer (
+    id bigint not null,
+    created_on timestamp,
+    firstName varchar(255),
+    lastName varchar(255),
+    primary key (id)
+)
+
+create table Customer_AUD (
+    id bigint not null,
+    REV integer not null,
+    REVTYPE tinyint,
+    created_on timestamp,
+    firstName varchar(255),
+    lastName varchar(255),
+    primary key (id, REV)
+)
+
+create table REVINFO (
+    REV integer generated by default as identity,
+    REVTSTMP bigint,
+    primary key (REV)
+)
+
+alter table Customer_AUD
+   add constraint FK5ecvi1a0ykunrriib7j28vpdj
+   foreign key (REV)
+   references REVINFO

documentation/src/main/asciidoc/userguide/chapters/envers/extras/envers-audited-update-example.sql

@@ -0,0 +1,36 @@
+update
+    Customer
+set
+    created_on=?,
+    firstName=?,
+    lastName=?
+where
+    id=?
+
+-- binding parameter [1] as [TIMESTAMP] - [2017-07-24 17:21:32.757]
+-- binding parameter [2] as [VARCHAR]   - [John]
+-- binding parameter [3] as [VARCHAR]   - [Doe Jr.]
+-- binding parameter [4] as [BIGINT]    - [1]
+
+insert
+into
+    REVINFO
+    (REV, REVTSTMP)
+values
+    (null, ?)
+
+-- binding parameter [1] as [BIGINT]    - [1500906092853]
+
+insert
+into
+    Customer_AUD
+    (REVTYPE, created_on, firstName, lastName, id, REV)
+values
+    (?, ?, ?, ?, ?, ?)
+
+-- binding parameter [1] as [INTEGER]   - [1]
+-- binding parameter [2] as [TIMESTAMP] - [2017-07-24 17:21:32.757]
+-- binding parameter [3] as [VARCHAR]   - [John]
+-- binding parameter [4] as [VARCHAR]   - [Doe Jr.]
+-- binding parameter [5] as [BIGINT]    - [1]
+-- binding parameter [6] as [INTEGER]   - [2]

documentation/src/test/java/org/hibernate/userguide/envers/AuditTest.java

@@ -0,0 +1,118 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
+ * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
+ */
+package org.hibernate.userguide.envers;
+
+import java.util.Date;
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.Id;
+import javax.persistence.Temporal;
+import javax.persistence.TemporalType;
+
+import org.hibernate.annotations.CreationTimestamp;
+import org.hibernate.envers.Audited;
+import org.hibernate.jpa.test.BaseEntityManagerFunctionalTestCase;
+
+import org.junit.Test;
+
+import static org.hibernate.testing.transaction.TransactionUtil.doInJPA;
+
+/**
+ * @author Vlad Mihalcea
+ */
+public class AuditTest extends BaseEntityManagerFunctionalTestCase {
+
+	@Override
+	protected Class<?>[] getAnnotatedClasses() {
+		return new Class<?>[] {
+			Customer.class
+		};
+	}
+
+	@Test
+	public void test() {
+		doInJPA( this::entityManagerFactory, entityManager -> {
+			//tag::envers-audited-insert-example[]
+			Customer customer = new Customer();
+			customer.setId( 1L );
+			customer.setFirstName( "John" );
+			customer.setLastName( "Doe" );
+
+			entityManager.persist( customer );
+			//end::envers-audited-insert-example[]
+		} );
+
+		doInJPA( this::entityManagerFactory, entityManager -> {
+			//tag::envers-audited-update-example[]
+			Customer customer = entityManager.find( Customer.class, 1L );
+			customer.setLastName( "Doe Jr." );
+			//end::envers-audited-update-example[]
+		} );
+
+		doInJPA( this::entityManagerFactory, entityManager -> {
+			//tag::envers-audited-delete-example[]
+			Customer customer = entityManager.getReference( Customer.class, 1L );
+			entityManager.remove( customer );
+			//end::envers-audited-delete-example[]
+		} );
+	}
+
+	//tag::envers-audited-mapping-example[]
+	@Audited
+	@Entity(name = "Customer")
+	public static class Customer {
+
+		@Id
+		private Long id;
+
+		private String firstName;
+
+		private String lastName;
+
+		@Temporal( TemporalType.TIMESTAMP )
+		@Column(name = "created_on")
+		@CreationTimestamp
+		private Date createdOn;
+
+		//Getters and setters are omitted for brevity
+
+	//end::envers-audited-mapping-example[]
+		public Long getId() {
+			return id;
+		}
+
+		public void setId(Long id) {
+			this.id = id;
+		}
+
+		public String getFirstName() {
+			return firstName;
+		}
+
+		public void setFirstName(String firstName) {
+			this.firstName = firstName;
+		}
+
+		public String getLastName() {
+			return lastName;
+		}
+
+		public void setLastName(String lastName) {
+			this.lastName = lastName;
+		}
+
+		public Date getCreatedOn() {
+			return createdOn;
+		}
+
+		public void setCreatedOn(Date createdOn) {
+			this.createdOn = createdOn;
+		}
+	//tag::envers-audited-mapping-example[]
+	}
+	//end::envers-audited-mapping-example[]
+}