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

Migrate getCrossTypeRevisionChangesReader example to Junit tests

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

@@ -927,16 +927,23 @@ include::{extrasdir}/envers-tracking-properties-changes-queries-at-revision-exam
 ====
 
 [[envers-tracking-modified-entities-queries]]
-=== Querying for entities modified in a given revision
+=== Querying for entity types modified in a given revision
 
-The basic query allows retrieving entity names and corresponding Java classes changed in a specified revision:
+[NOTE]
+====
+The methods described below can be used only when the default mechanism of tracking changed entity types is enabled (see <<envers-tracking-modified-entities-revchanges>>).
+====
 
-[source,java]
+This basic query allows retrieving entity names and corresponding Java classes changed in a specified revision:
+
+[[envers-tracking-modified-entities-queries-example]]
+.Retrieving entity names and corresponding Java classes changed in a specified revision
+====
+[source, JAVA, indent=0]
 ----
-modifiedEntityTypes = getAuditReader()
+include::{sourcedir}/EntityTypeChangeAuditTest.java[tags=envers-tracking-modified-entities-queries-example]
-	.getCrossTypeRevisionChangesReader()
-	.findEntityTypes( revisionNumber );
 ----
+====
 
 Other queries (also accessible from `org.hibernate.envers.CrossTypeRevisionChangesReader`):
 
@@ -952,8 +959,6 @@ Other queries (also accessible from `org.hibernate.envers.CrossTypeRevisionChang
   Returns a map containing lists of entity snapshots grouped by modification operation (e.g. addition, update and removal).
   Executes `3N+1` SQL queries, where `N` is a number of different entity classes modified within specified revision.
 
-Note that methods described above can be legally used only when the default mechanism of tracking changed entity names is enabled (see <<envers-tracking-modified-entities-revchanges>>).
-
 [[envers-querying-entity-relation-jobs]]
 === Querying for entities using entity relation joins
 

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

@@ -9,6 +9,7 @@ package org.hibernate.userguide.envers;
 import java.util.Arrays;
 import java.util.Date;
 import java.util.HashSet;
+import java.util.List;
 import java.util.Map;
 import java.util.Set;
 import javax.persistence.Column;
@@ -25,16 +26,19 @@ import javax.persistence.TemporalType;
 import org.hibernate.annotations.CreationTimestamp;
 import org.hibernate.cfg.AvailableSettings;
 import org.hibernate.engine.spi.SessionFactoryImplementor;
+import org.hibernate.envers.AuditReaderFactory;
 import org.hibernate.envers.Audited;
 import org.hibernate.envers.DefaultRevisionEntity;
 import org.hibernate.envers.ModifiedEntityNames;
 import org.hibernate.envers.RevisionEntity;
+import org.hibernate.envers.tools.Pair;
 import org.hibernate.jpa.boot.spi.Bootstrap;
 import org.hibernate.jpa.test.BaseEntityManagerFunctionalTestCase;
 
 import org.junit.Test;
 
 import static org.hibernate.testing.transaction.TransactionUtil.doInJPA;
+import static org.junit.Assert.assertEquals;
 
 /**
  * @author Vlad Mihalcea
@@ -50,7 +54,7 @@ public class EntityTypeChangeAuditTest extends BaseEntityManagerFunctionalTestCa
 	}
 
 	@Test
-	public void testLifecycle() {
+	public void test() {
 
 		doInJPA( this::entityManagerFactory, entityManager -> {
 			Customer customer = new Customer();
@@ -68,6 +72,7 @@ public class EntityTypeChangeAuditTest extends BaseEntityManagerFunctionalTestCa
 				org.hibernate.jpa.AvailableSettings.LOADED_CLASSES,
 				Arrays.asList(
 					ApplicationCustomer.class,
+					Customer.class,
 					CustomTrackingRevisionEntity.class
 				)
 			);
@@ -83,12 +88,32 @@ public class EntityTypeChangeAuditTest extends BaseEntityManagerFunctionalTestCa
 			final EntityManagerFactory emf = entityManagerFactory;
 
 			doInJPA( () -> emf, entityManager -> {
-				ApplicationCustomer customer = new ApplicationCustomer();
+				ApplicationCustomer customer = entityManager.find( ApplicationCustomer.class, 1L );
-				customer.setId( 2L );
-				customer.setFirstName( "John" );
 				customer.setLastName( "Doe Jr." );
+			} );
 
-				entityManager.persist( customer );
+			doInJPA( () -> emf, entityManager -> {
+				//tag::envers-tracking-modified-entities-queries-example[]
+				assertEquals(
+					"org.hibernate.userguide.envers.EntityTypeChangeAuditTest$Customer",
+					AuditReaderFactory
+					.get( entityManager )
+					.getCrossTypeRevisionChangesReader()
+					.findEntityTypes( 1 )
+					.iterator().next()
+					.getFirst()
+				);
+
+				assertEquals(
+					"org.hibernate.userguide.envers.EntityTypeChangeAuditTest$ApplicationCustomer",
+					AuditReaderFactory
+					.get( entityManager )
+					.getCrossTypeRevisionChangesReader()
+					.findEntityTypes( 2 )
+					.iterator().next()
+					.getFirst()
+				);
+				//end::envers-tracking-modified-entities-queries-example[]
 			} );
 		}
 		finally {

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

@@ -9,7 +9,6 @@ package org.hibernate.userguide.envers;
 import java.sql.Timestamp;
 import java.time.LocalDateTime;
 import java.time.ZoneOffset;
-import java.util.Arrays;
 import java.util.Date;
 import java.util.List;
 import java.util.Map;
@@ -18,7 +17,6 @@ import javax.persistence.Entity;
 import javax.persistence.FetchType;
 import javax.persistence.Id;
 import javax.persistence.ManyToOne;
-import javax.persistence.NoResultException;
 import javax.persistence.Temporal;
 import javax.persistence.TemporalType;
 
@@ -35,8 +33,6 @@ import org.junit.Test;
 
 import static org.hibernate.testing.transaction.TransactionUtil.doInJPA;
 import static org.junit.Assert.assertEquals;
-import static org.junit.Assert.assertNull;
-import static org.junit.Assert.fail;
 
 /**
  * @author Vlad Mihalcea

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

@@ -6,9 +6,6 @@
  */
 package org.hibernate.userguide.envers;
 
-import java.sql.Timestamp;
-import java.time.LocalDateTime;
-import java.time.ZoneOffset;
 import java.util.Date;
 import java.util.List;
 import java.util.Map;
@@ -25,7 +22,6 @@ import org.hibernate.envers.AuditReaderFactory;
 import org.hibernate.envers.Audited;
 import org.hibernate.envers.configuration.EnversSettings;
 import org.hibernate.envers.query.AuditEntity;
-import org.hibernate.envers.query.AuditQuery;
 import org.hibernate.envers.strategy.ValidityAuditStrategy;
 import org.hibernate.jpa.test.BaseEntityManagerFunctionalTestCase;
 
@@ -86,13 +82,6 @@ public class QueryAuditWithModifiedFlagTest extends BaseEntityManagerFunctionalT
 			entityManager.remove( customer );
 		} );
 
-		List<Number> revisions = doInJPA( this::entityManagerFactory, entityManager -> {
-			 return AuditReaderFactory.get( entityManager ).getRevisions(
-				Customer.class,
-				1L
-			);
-		} );
-
 		doInJPA( this::entityManagerFactory, entityManager -> {
 			//tag::envers-tracking-properties-changes-queries-hasChanged-example[]
 			List<Customer> customers = AuditReaderFactory