HHH-11290 - Migrate all documentation snippets that derive the source code from extras instead of actual Unit Tests

Fixed in the Locking chapter

documentation/src/main/asciidoc/userguide/chapters/locking/Locking.adoc

@@ -53,17 +53,17 @@ According to JPA, the valid types for these attributes are limited to:
 ====
 [source,java]
 ----
-include::{extrasdir}/entity/Version.java[]
+include::{sourcedir}/OptimisticLockingTest.java[tags=locking-optimistic-entity-mapping-example,indent=0]
 ----
 
 [source,java]
 ----
-include::{extrasdir}/entity/Timestamp.java[]
+include::{sourcedir}/OptimisticLockingTimestampTest.java[tags=locking-optimistic-entity-mapping-example,indent=0]
 ----
 
 [source,java]
 ----
-include::{extrasdir}/entity/Instant.java[]
+include::{sourcedir}/OptimisticLockingInstantTest.java[tags=locking-optimistic-entity-mapping-example,indent=0]
 ----
 ====
 
@@ -75,9 +75,9 @@ The version number mechanism for optimistic locking is provided through a `@Vers
 [[locking-optimistic-version-number-example]]
 .@Version annotation
 ====
-[source, JAVA, indent=0]
+[source, JAVA,indent=0]
 ----
-include::{sourcedir}/OptimisticLockingTest.java[tags=locking-optimistic-version-number-example]
+include::{sourcedir}/OptimisticLockingTest.java[tags=locking-optimistic-version-number-example,indent=0]
 ----
 ====
 
@@ -104,9 +104,9 @@ Timestamping is automatically used if you the `@Version` annotation on a `Date`
 [[locking-optimistic-version-timestamp-example]]
 .Using timestamps for optimistic locking
 ====
-[source, JAVA, indent=0]
+[source, JAVA,indent=0]
 ----
-include::{sourcedir}/OptimisticLockingTest.java[tags=locking-optimistic-version-timestamp-example]
+include::{sourcedir}/OptimisticLockingTest.java[tags=locking-optimistic-version-timestamp-example,indent=0]
 ----
 ====
 
@@ -120,9 +120,9 @@ if you use the `@org.hibernate.annotations.Generated(GenerationTime.ALWAYS)` or
 [[locking-optimistic-version-timestamp-source-mapping-example]]
 .Database-generated version timestamp mapping
 ====
-[source, JAVA, indent=0]
+[source, JAVA,indent=0]
 ----
-include::{sourcedir}/VersionSourceTest.java[tags=locking-optimistic-version-timestamp-source-mapping-example]
+include::{sourcedir}/VersionSourceTest.java[tags=locking-optimistic-version-timestamp-source-mapping-example,indent=0]
 ----
 ====
 
@@ -131,12 +131,12 @@ Now, when persisting a `Person` entity, Hibernate calls the database-specific cu
 [[locking-optimistic-version-timestamp-source-persist-example]]
 .Database-generated version timestamp example
 ====
-[source, JAVA, indent=0]
+[source, JAVA,indent=0]
 ----
-include::{sourcedir}/VersionSourceTest.java[tags=locking-optimistic-version-timestamp-source-persist-example]
+include::{sourcedir}/VersionSourceTest.java[tags=locking-optimistic-version-timestamp-source-persist-example,indent=0]
 ----
 
-[source, SQL, indent=0]
+[source, SQL,indent=0]
 ----
 include::{extrasdir}/locking-optimistic-version-timestamp-source-persist-example.sql[]
 ----
@@ -153,9 +153,9 @@ as illustrated in the following example.
 [[locking-optimistic-exclude-attribute-mapping-example]]
 .@OptimisticLock mapping example
 ====
-[source, JAVA, indent=0]
+[source, JAVA,indent=0]
 ----
-include::{sourcedir}/OptimisticLockTest.java[tags=locking-optimistic-exclude-attribute-mapping-example]
+include::{sourcedir}/OptimisticLockTest.java[tags=locking-optimistic-exclude-attribute-mapping-example,indent=0]
 ----
 ====
 
@@ -165,12 +165,12 @@ the two concurrent transactions are not going to conflict as illustrated by the
 [[locking-optimistic-exclude-attribute-example]]
 .@OptimisticLock exlude attribute example
 ====
-[source, JAVA, indent=0]
+[source, JAVA,indent=0]
 ----
-include::{sourcedir}/OptimisticLockTest.java[tags=locking-optimistic-exclude-attribute-example]
+include::{sourcedir}/OptimisticLockTest.java[tags=locking-optimistic-exclude-attribute-example,indent=0]
 ----
 
-[source, SQL, indent=0]
+[source, SQL,indent=0]
 ----
 include::{extrasdir}/locking-optimistic-exclude-attribute-example.sql[]
 ----
@@ -355,12 +355,12 @@ The scope can either be `NORMAL` (default value) or `EXTENDED`. The `EXTENDED` s
 [[locking-jpa-query-hints-timeout-example]]
 .`javax.persistence.lock.timeout` example
 ====
-[source, JAVA, indent=0]
+[source, JAVA,indent=0]
 ----
-include::{sourcedir}/ExplicitLockingTest.java[tags=locking-jpa-query-hints-timeout-example]
+include::{sourcedir}/ExplicitLockingTest.java[tags=locking-jpa-query-hints-timeout-example,indent=0]
 ----
 
-[source, SQL, indent=0]
+[source, SQL,indent=0]
 ----
 include::{extrasdir}/locking-jpa-query-hints-timeout-example.sql[]
 ----
@@ -388,12 +388,12 @@ The following example shows how to obtain shared database lock without waiting f
 [[locking-buildLockRequest-example]]
 .`buildLockRequest` example
 ====
-[source, JAVA, indent=0]
+[source, JAVA,indent=0]
 ----
-include::{sourcedir}/ExplicitLockingTest.java[tags=locking-buildLockRequest-example]
+include::{sourcedir}/ExplicitLockingTest.java[tags=locking-buildLockRequest-example,indent=0]
 ----
 
-[source, SQL, indent=0]
+[source, SQL,indent=0]
 ----
 include::{extrasdir}/locking-buildLockRequest-example.sql[]
 ----
@@ -414,12 +414,12 @@ For this reason, Hibernate uses secondary selects to lock the previously fetched
 [[locking-follow-on-example]]
 .Follow-on-locking example
 ====
-[source, JAVA, indent=0]
+[source, JAVA,indent=0]
 ----
-include::{sourcedir}/ExplicitLockingTest.java[tags=locking-follow-on-example]
+include::{sourcedir}/ExplicitLockingTest.java[tags=locking-follow-on-example,indent=0]
 ----
 
-[source, SQL, indent=0]
+[source, SQL,indent=0]
 ----
 include::{extrasdir}/locking-follow-on-example.sql[]
 ----
@@ -433,12 +433,12 @@ To avoid the N+1 query problem, a separate query can be used to apply the lock u
 [[locking-follow-on-secondary-query-example]]
 .Secondary query entity locking
 ====
-[source, JAVA, indent=0]
+[source, JAVA,indent=0]
 ----
-include::{sourcedir}/ExplicitLockingTest.java[tags=locking-follow-on-secondary-query-example]
+include::{sourcedir}/ExplicitLockingTest.java[tags=locking-follow-on-secondary-query-example,indent=0]
 ----
 
-[source, SQL, indent=0]
+[source, SQL,indent=0]
 ----
 include::{extrasdir}/locking-follow-on-secondary-query-example.sql[]
 ----
@@ -454,12 +454,12 @@ Even more important is that you can overrule the default follow-on-locking detec
 [[locking-follow-on-explicit-example]]
 .Disabling the follow-on-locking mechanism explicitly
 ====
-[source, JAVA, indent=0]
+[source, JAVA,indent=0]
 ----
-include::{sourcedir}/ExplicitLockingTest.java[tags=locking-follow-on-explicit-example]
+include::{sourcedir}/ExplicitLockingTest.java[tags=locking-follow-on-explicit-example,indent=0]
 ----
 
-[source, SQL, indent=0]
+[source, SQL,indent=0]
 ----
 include::{extrasdir}/locking-follow-on-explicit-example.sql[]
 ----

documentation/src/main/asciidoc/userguide/chapters/locking/extras/entity/Instant.java

@@ -1,10 +0,0 @@
-@Entity
-public class Thing2 {
-
-    @Id
-    private Integer id;
-
-    @Version
-    private Instant ts;
-    ...
-}

documentation/src/main/asciidoc/userguide/chapters/locking/extras/entity/Timestamp.java

@@ -1,11 +0,0 @@
-@Entity
-public class Thing {
-
-    @Id
-    private Integer id;
-
-    @Version
-    private Timestamp ts;
-
-    ...
-}

documentation/src/main/asciidoc/userguide/chapters/locking/extras/entity/Version.java

@@ -1,10 +0,0 @@
-@Entity
-public class Course {
-
-    @Id
-    private Integer id;
-
-    @Version
-    private Integer version;
-    ...
-}

documentation/src/test/java/org/hibernate/userguide/locking/OptimisticLockingInstantTest.java

@@ -0,0 +1,91 @@
+/*
+ * 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.locking;
+
+import java.sql.Timestamp;
+import java.time.Instant;
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.GeneratedValue;
+import javax.persistence.Id;
+import javax.persistence.Version;
+
+import org.hibernate.jpa.test.BaseEntityManagerFunctionalTestCase;
+
+import org.junit.Test;
+
+import static org.hibernate.testing.transaction.TransactionUtil.doInJPA;
+
+/**
+ * @author Vlad Mihalcea
+ */
+public class OptimisticLockingInstantTest extends BaseEntityManagerFunctionalTestCase {
+
+	@Override
+	protected Class<?>[] getAnnotatedClasses() {
+		return new Class<?>[] {
+			Person.class
+		};
+	}
+
+	@Test
+	public void test() {
+		Person _person = doInJPA( this::entityManagerFactory, entityManager -> {
+			Person person = new Person(  );
+			person.setName( "John Doe" );
+			entityManager.persist( person );
+
+			return person;
+		} );
+		doInJPA( this::entityManagerFactory, entityManager -> {
+			Person person = entityManager.find( Person.class, _person.getId() );
+			person.setName( person.getName().toUpperCase() );
+		} );
+	}
+
+	//tag::locking-optimistic-entity-mapping-example[]
+	@Entity(name = "Person")
+	public static class Person {
+
+		@Id
+		@GeneratedValue
+		private Long id;
+
+		@Column(name = "`name`")
+		private String name;
+
+		//tag::locking-optimistic-version-number-example[]
+		@Version
+		private Instant version;
+		//end::locking-optimistic-version-number-example[]
+
+		//Getters and setters are omitted for brevity
+
+		//end::locking-optimistic-entity-mapping-example[]
+		public Long getId() {
+			return id;
+		}
+
+		public void setId(Long id) {
+			this.id = id;
+		}
+
+		public String getName() {
+			return name;
+		}
+
+		public void setName(String name) {
+			this.name = name;
+		}
+
+		public Instant getVersion() {
+			return version;
+		}
+	//tag::locking-optimistic-entity-mapping-example[]
+	}
+	//end::locking-optimistic-entity-mapping-example[]
+}

documentation/src/test/java/org/hibernate/userguide/locking/OptimisticLockingTest.java

@@ -60,6 +60,7 @@ public class OptimisticLockingTest extends BaseEntityManagerFunctionalTestCase {
 		} );
 	}
 
+	//tag::locking-optimistic-entity-mapping-example[]
 	@Entity(name = "Person")
 	public static class Person {
 
@@ -75,6 +76,9 @@ public class OptimisticLockingTest extends BaseEntityManagerFunctionalTestCase {
 		private long version;
 		//end::locking-optimistic-version-number-example[]
 
+		//Getters and setters are omitted for brevity
+
+		//end::locking-optimistic-entity-mapping-example[]
 		public Long getId() {
 			return id;
 		}
@@ -98,7 +102,9 @@ public class OptimisticLockingTest extends BaseEntityManagerFunctionalTestCase {
 		public void setVersion(long version) {
 			this.version = version;
 		}
+	//tag::locking-optimistic-entity-mapping-example[]
 	}
+	//end::locking-optimistic-entity-mapping-example[]
 
 	@Entity(name = "Phone")
 	public static class Phone {
@@ -145,9 +151,5 @@ public class OptimisticLockingTest extends BaseEntityManagerFunctionalTestCase {
 		public Date getVersion() {
 			return version;
 		}
-
-		public void setVersion(Date version) {
-			this.version = version;
-		}
 	}
 }

documentation/src/test/java/org/hibernate/userguide/locking/OptimisticLockingTimestampTest.java

@@ -0,0 +1,90 @@
+/*
+ * 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.locking;
+
+import java.sql.Timestamp;
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.GeneratedValue;
+import javax.persistence.Id;
+import javax.persistence.Version;
+
+import org.hibernate.jpa.test.BaseEntityManagerFunctionalTestCase;
+
+import org.junit.Test;
+
+import static org.hibernate.testing.transaction.TransactionUtil.doInJPA;
+
+/**
+ * @author Vlad Mihalcea
+ */
+public class OptimisticLockingTimestampTest extends BaseEntityManagerFunctionalTestCase {
+
+	@Override
+	protected Class<?>[] getAnnotatedClasses() {
+		return new Class<?>[] {
+			Person.class
+		};
+	}
+
+	@Test
+	public void test() {
+		Person _person = doInJPA( this::entityManagerFactory, entityManager -> {
+			Person person = new Person(  );
+			person.setName( "John Doe" );
+			entityManager.persist( person );
+
+			return person;
+		} );
+		doInJPA( this::entityManagerFactory, entityManager -> {
+			Person person = entityManager.find( Person.class, _person.getId() );
+			person.setName( person.getName().toUpperCase() );
+		} );
+	}
+
+	//tag::locking-optimistic-entity-mapping-example[]
+	@Entity(name = "Person")
+	public static class Person {
+
+		@Id
+		@GeneratedValue
+		private Long id;
+
+		@Column(name = "`name`")
+		private String name;
+
+		//tag::locking-optimistic-version-number-example[]
+		@Version
+		private Timestamp version;
+		//end::locking-optimistic-version-number-example[]
+
+		//Getters and setters are omitted for brevity
+
+		//end::locking-optimistic-entity-mapping-example[]
+		public Long getId() {
+			return id;
+		}
+
+		public void setId(Long id) {
+			this.id = id;
+		}
+
+		public String getName() {
+			return name;
+		}
+
+		public void setName(String name) {
+			this.name = name;
+		}
+
+		public Timestamp getVersion() {
+			return version;
+		}
+	//tag::locking-optimistic-entity-mapping-example[]
+	}
+	//end::locking-optimistic-entity-mapping-example[]
+}