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

Add example to demonstrate the audit log query difference for ValidityAuditStrategy

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

@@ -367,6 +367,23 @@ include::{extrasdir}/envers-audited-validity-mapping-example.sql[]
 
 As you can see, the `REVEND` column is added as well as its Foreign key to the `REVINFO` table.
 
+When rerunning thee previous `Customer` audit log queries against the `ValidityAuditStrategy`,
+we get the following results:
+
+[[envers-audited-validity-rev1-example]]
+.Getting the first revision for the `Customer` entity
+====
+[source, SQL, indent=0]
+----
+include::{extrasdir}/envers-audited-validity-rev1-example.sql[]
+----
+====
+
+[NOTE]
+====
+Compared to the default strategy, the `ValidityAuditStrategy` generates simpler queries that can render better execution plans.
+====
+
 [[envers-revisionlog]]
 === Revision Log
 

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

@@ -0,0 +1,21 @@
+select
+    c.id as id1_1_,
+    c.REV as REV2_1_,
+    c.REVTYPE as REVTYPE3_1_,
+    c.REVEND as REVEND4_1_,
+    c.created_on as created_5_1_,
+    c.firstName as firstNam6_1_,
+    c.lastName as lastName7_1_
+from
+    Customer_AUD c
+where
+    c.REV <= ?
+    and c.REVTYPE <> ?
+    and (
+        c.REVEND > ?
+        or c.REVEND is null
+    )
+        
+-- binding parameter [1] as [INTEGER] - [1]
+-- binding parameter [2] as [INTEGER] - [2]
+-- binding parameter [3] as [INTEGER] - [1]

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

@@ -56,63 +56,50 @@ public class ValidityStrategyAuditTest extends BaseEntityManagerFunctionalTestCa
 	@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-revisions-example[]
 		List<Number> revisions = doInJPA( this::entityManagerFactory, entityManager -> {
 			 return AuditReaderFactory.get( entityManager ).getRevisions(
 				Customer.class,
 				1L
 			);
 		} );
-		//end::envers-audited-revisions-example[]
 
 		doInJPA( this::entityManagerFactory, entityManager -> {
-			//tag::envers-audited-rev1-example[]
 			Customer customer = (Customer) AuditReaderFactory.get( entityManager )
 				.createQuery()
 				.forEntitiesAtRevision( Customer.class, revisions.get( 0 ) )
 				.getSingleResult();
 
 			assertEquals("Doe", customer.getLastName());
-			//end::envers-audited-rev1-example[]
 		} );
 
 		doInJPA( this::entityManagerFactory, entityManager -> {
-			//tag::envers-audited-rev2-example[]
 			Customer customer = (Customer) AuditReaderFactory.get( entityManager )
 				.createQuery()
 				.forEntitiesAtRevision( Customer.class, revisions.get( 1 ) )
 				.getSingleResult();
 
 			assertEquals("Doe Jr.", customer.getLastName());
-			//end::envers-audited-rev2-example[]
 		} );
 
 		doInJPA( this::entityManagerFactory, entityManager -> {
-			//tag::envers-audited-rev3-example[]
 			try {
 				Customer customer = (Customer) AuditReaderFactory.get( entityManager )
 					.createQuery()
@@ -123,11 +110,9 @@ public class ValidityStrategyAuditTest extends BaseEntityManagerFunctionalTestCa
 			}
 			catch (NoResultException expected) {
 			}
-			//end::envers-audited-rev3-example[]
 		} );
 
 		doInJPA( this::entityManagerFactory, entityManager -> {
-			//tag::envers-audited-rev4-example[]
 			Customer customer = (Customer) AuditReaderFactory.get( entityManager )
 				.createQuery()
 				.forEntitiesAtRevision(
@@ -141,11 +126,9 @@ public class ValidityStrategyAuditTest extends BaseEntityManagerFunctionalTestCa
 			assertNull( customer.getFirstName() );
 			assertNull( customer.getLastName() );
 			assertNull( customer.getCreatedOn() );
-			//end::envers-audited-rev4-example[]
 		} );
 	}
 
-	//tag::envers-audited-mapping-example[]
 	@Audited
 	@Entity(name = "Customer")
 	public static class Customer {
@@ -162,9 +145,6 @@ public class ValidityStrategyAuditTest extends BaseEntityManagerFunctionalTestCa
 		@CreationTimestamp
 		private Date createdOn;
 
-		//Getters and setters are omitted for brevity
-
-	//end::envers-audited-mapping-example[]
 		public Long getId() {
 			return id;
 		}
@@ -196,7 +176,5 @@ public class ValidityStrategyAuditTest extends BaseEntityManagerFunctionalTestCa
 		public void setCreatedOn(Date createdOn) {
 			this.createdOn = createdOn;
 		}
-	//tag::envers-audited-mapping-example[]
 	}
-	//end::envers-audited-mapping-example[]
 }