HHH-11186 - Add examples for all Hibernate annotations

Document more annotations:

- @GeneratorType

documentation/src/main/asciidoc/userguide/appendices/Annotations.adoc

@@ -831,6 +831,8 @@ See the <<chapters/domain/basic_types.adoc#mapping-generated-Generated,`@Generat
 The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/GeneratorType.html[`@GeneratorType`] annotation is used to provide a https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/tuple/ValueGenerator.html[`ValueGenerator`]
 and a https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/GenerationTime.html[`GenerationTime`] for the current annotated generated attribute.
 
+See the <<chapters/domain/basic_types.adoc#mapping-generated-GeneratorType-example,`@GeneratorType` mapping>> section for more info.
+
 [[annotations-hibernate-genericgenerator]]
 ==== `@GenericGenerator`
 

documentation/src/main/asciidoc/userguide/chapters/domain/basic_types.adoc

@@ -1258,6 +1258,59 @@ include::{extrasdir}/basic/mapping-generated-Generated-update-example.sql[]
 ----
 ====
 
+[[mapping-generated-GeneratorType]]
+===== `@GeneratorType` annotation
+
+The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/GeneratorType.html[`@GeneratorType`] annotation is used so that
+you can provide a custom generator to ste the value of the currently annotated property.
+
+For this reason, the `@GeneratorType` annotation accepts a https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/GenerationTime.html[`GenerationTime`] enum value
+and a custom https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/ValueGenerator.html[`ValueGenerator`] class type.
+
+Considering the following entity:
+
+[[mapping-generated-GeneratorType-example]]
+.`@GeneratorType` mapping example
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/generated/GeneratorTypeTest.java[tags=mapping-generated-GeneratorType-example]
+----
+====
+
+When the `Person` entity is persisted, Hibernate is going to populate the `createdBy` column with the currently logged user.
+
+[[mapping-generated-GeneratorType-persist-example]]
+.`@Generated` persist example
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/generated/GeneratorTypeTest.java[tags=mapping-generated-GeneratorType-persist-example]
+----
+
+[source, SQL, indent=0]
+----
+include::{extrasdir}/basic/mapping-generated-GeneratorType-persist-example.sql[]
+----
+====
+
+The same goes when the `Person` entity is updated.
+Hibernate is going to populate the `updatedBy` column with the currently logged user.
+
+[[mapping-generated-GeneratorType-update-example]]
+.`@Generated` update example
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/generated/GeneratorTypeTest.java[tags=mapping-generated-GeneratorType-update-example]
+----
+
+[source, SQL, indent=0]
+----
+include::{extrasdir}/basic/mapping-generated-GeneratorType-update-example.sql[]
+----
+====
+
 [[mapping-generated-CreationTimestamp]]
 ===== `@CreationTimestamp` annotation
 

documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/mapping-generated-GeneratorType-persist-example.sql

@@ -0,0 +1,16 @@
+INSERT INTO Person
+(
+    createdBy,
+    firstName,
+    lastName,
+    updatedBy,
+    id
+)
+VALUES
+(?, ?, ?, ?, ?)
+
+-- binding parameter [1] as [VARCHAR] - [Alice]
+-- binding parameter [2] as [VARCHAR] - [John]
+-- binding parameter [3] as [VARCHAR] - [Doe]
+-- binding parameter [4] as [VARCHAR] - [Alice]
+-- binding parameter [5] as [BIGINT]  - [1]

documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/mapping-generated-GeneratorType-update-example.sql

@@ -0,0 +1,14 @@
+UPDATE Person 
+SET
+    createdBy = ?,
+    firstName = ?,
+    lastName = ?,
+    updatedBy = ? 
+WHERE
+    id = ?
+
+-- binding parameter [1] as [VARCHAR] - [Alice]
+-- binding parameter [2] as [VARCHAR] - [Mr. John]
+-- binding parameter [3] as [VARCHAR] - [Doe]
+-- binding parameter [4] as [VARCHAR] - [Bob]
+-- binding parameter [5] as [BIGINT]  - [1]

documentation/src/test/java/org/hibernate/userguide/hql/HQLTest.java

@@ -1513,6 +1513,21 @@ public class HQLTest extends BaseEntityManagerFunctionalTestCase {
 		});
 	}
 
+	@Test
+	public void test_hql_collection_expressions_example_10() {
+		doInJPA( this::entityManagerFactory, entityManager -> {
+			//tag::hql-collection-expressions-example[]
+
+			List<Person> persons = entityManager.createQuery(
+				"select p " +
+				"from Person p " +
+				"where size( p.phones ) = 2", Person.class )
+			.getResultList();
+			//end::hql-collection-expressions-example[]
+			assertEquals(1, persons.size());
+		});
+	}
+
 	@Test
 	public void test_collection_index_operator_example_1() {
 		doInJPA( this::entityManagerFactory, entityManager -> {

documentation/src/test/java/org/hibernate/userguide/mapping/generated/GeneratorTypeTest.java

@@ -0,0 +1,147 @@
+/*
+ * 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.mapping.generated;
+
+import javax.persistence.Entity;
+import javax.persistence.Id;
+
+import org.hibernate.Session;
+import org.hibernate.annotations.GenerationTime;
+import org.hibernate.annotations.GeneratorType;
+import org.hibernate.jpa.test.BaseEntityManagerFunctionalTestCase;
+import org.hibernate.tuple.ValueGenerator;
+
+import org.junit.Test;
+
+import static org.hibernate.testing.transaction.TransactionUtil.doInJPA;
+
+/**
+ * @author Vlad Mihalcea
+ */
+public class GeneratorTypeTest extends BaseEntityManagerFunctionalTestCase {
+
+	@Override
+	protected Class<?>[] getAnnotatedClasses() {
+		return new Class<?>[] {
+			Person.class
+		};
+	}
+
+	@Test
+	public void test() {
+		//tag::mapping-generated-GeneratorType-persist-example[]
+		CurrentUser.INSTANCE.logIn( "Alice" );
+
+		doInJPA( this::entityManagerFactory, entityManager -> {
+
+			Person person = new Person();
+			person.setId( 1L );
+			person.setFirstName( "John" );
+			person.setLastName( "Doe" );
+
+			entityManager.persist( person );
+		} );
+
+		CurrentUser.INSTANCE.logOut();
+		//end::mapping-generated-GeneratorType-persist-example[]
+
+		//tag::mapping-generated-GeneratorType-update-example[]
+		CurrentUser.INSTANCE.logIn( "Bob" );
+
+		doInJPA( this::entityManagerFactory, entityManager -> {
+			Person person = entityManager.find( Person.class, 1L );
+			person.setFirstName( "Mr. John" );
+		} );
+
+		CurrentUser.INSTANCE.logOut();
+		//end::mapping-generated-GeneratorType-update-example[]
+	}
+
+	//tag::mapping-generated-GeneratorType-example[]
+	public static class CurrentUser {
+
+		public static final CurrentUser INSTANCE = new CurrentUser();
+
+		private static final ThreadLocal<String> storage = new ThreadLocal<>();
+
+		public void logIn(String user) {
+			storage.set( user );
+		}
+
+		public void logOut() {
+			storage.remove();
+		}
+
+		public String get() {
+			return storage.get();
+		}
+	}
+
+	public static class LoggedUserGenerator implements ValueGenerator<String> {
+		
+		@Override
+		public String generateValue(
+				Session session, Object owner) {
+			return CurrentUser.INSTANCE.get();
+		}
+	}
+	
+	@Entity(name = "Person")
+	public static class Person {
+
+		@Id
+		private Long id;
+
+		private String firstName;
+
+		private String lastName;
+
+		@GeneratorType( type = LoggedUserGenerator.class, when = GenerationTime.INSERT)
+		private String createdBy;
+
+		@GeneratorType( type = LoggedUserGenerator.class, when = GenerationTime.ALWAYS)
+		private String updatedBy;
+
+	//end::mapping-generated-GeneratorType-example[]
+		public Person() {}
+
+		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 String getCreatedBy() {
+			return createdBy;
+		}
+
+		public String getUpdatedBy() {
+			return updatedBy;
+		}
+
+		//tag::mapping-generated-GeneratorType-example[]
+	}
+	//end::mapping-generated-GeneratorType-example[]
+}