HHH-11186 - Add examples for all Hibernate annotations

Document more annotations:

- @ColumnDefault
- @CreationTimestamp

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

@@ -672,6 +672,8 @@ The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibern
 
 The same behavior can be achieved using the `definition` attribute of the JPA <<annotations-jpa-column>> annotation.
 
+See the <<chapters/schema/Schema.adoc#schema-generation-column-default-value,Default value for database column>> chapter for more info.
+
 [[annotations-hibernate-columns]]
 ==== `@Columns`
 
@@ -696,13 +698,7 @@ The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibern
 
 The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/CreationTimestamp.html[`@CreationTimestamp`] annotation is used to specify that the current annotated temporal type must be initialized with the current JVM timestamp value.
 
-Supported attribute types:
-
-- `java.util.Date`
-- `java.util.Calendar`
-- `java.sql.Date`
-- `java.sql.Time`
-- `java.sql.Timestamp`
+See the <<chapters/domain/basic_types.adoc#mapping-generated-CreationTimestamp,`@CreationTimestamp` mapping>> section for more info.
 
 [[annotations-hibernate-discriminatorformula]]
 ==== `@DiscriminatorFormula`

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

@@ -1207,8 +1207,47 @@ Only `@Version` and `@Basic` types can be marked as generated.
 
 To mark a property as generated, use The Hibernate specific `@Generated` annotation.
 
+[[mapping-generated-CreationTimestamp]]
+===== `@CreationTimestamp` annotation
+
+The `@CreationTimestamp` annotation instructs Hibernate to set the annotated entity attribute with the current timestamp value of the JVM
+when the entity is being persisted.
+
+The supported property types are:
+
+- `java.util.Date`
+- `java.util.Calendar`
+- `java.sql.Date`
+- `java.sql.Time`
+- `java.sql.Timestamp`
+
+[[mapping-generated-CreationTimestamp-example]]
+.`@CreationTimestamp` mapping example
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/generated/CreationTimestampTest.java[tags=mapping-generated-CreationTimestamp-example]
+----
+====
+
+When the `Event` entity is persisted, Hibernate is going to populate the underlying `timestamp` column with the current JVM timestamp value:
+
+[[mapping-generated-CreationTimestamp-persist-example]]
+.`@CreationTimestamp` persist example
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/generated/CreationTimestampTest.java[tags=mapping-generated-CreationTimestamp-persist-example]
+----
+
+[source, SQL, indent=0]
+----
+include::{extrasdir}/basic/mapping-generated-CreationTimestamp-persist-example.sql[]
+----
+====
+
 [[mapping-generated-ValueGenerationType]]
-===== @ValueGenerationType meta-annotation
+===== `@ValueGenerationType` meta-annotation
 
 Hibernate 4.3 introduced the `@ValueGenerationType` meta-annotation, which is a new approach to declaring generated attributes or customizing generators.
 

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

@@ -0,0 +1,5 @@
+INSERT INTO Event("timestamp", id)
+VALUES (?, ?)
+
+-- binding parameter [1] as [TIMESTAMP] - [Tue Nov 15 16:24:20 EET 2016]
+-- binding parameter [2] as [BIGINT]    - [1]

documentation/src/main/asciidoc/userguide/chapters/schema/Schema.adoc

@@ -118,7 +118,44 @@ include::{extrasdir}/schema-generation-database-checks-persist-example.sql[]
 ----
 ====
 
+[[schema-generation-column-default-value]]
+=== Default value for database column
 
+With Hibernate, you can specify a default value for a given database column using the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/ColumnDefault.html[`@ColumnDefault`] annotation.
 
+[[schema-generation-column-default-value-mapping-example]]
+.`@ColumnDefault` mapping example
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/ColumnDefaultTest.java[tag=schema-generation-column-default-value-mapping-example]
+----
 
+[source, SQL, indent=0]
+----
+include::{extrasdir}/schema-generation-column-default-value-mapping-example.sql[]
+----
+====
 
+In the mapping above, both the `name` and `clientId` table columns are going to use a `DEFAULT` value.
+
+[NOTE]
+====
+The entity is annotated with the `@DynamicInsert` annotation so that the `INSERT` statement does not include the entity attribute that have not been set.
+====
+
+This way, when omitting the `name` and the `clientId` attribute, the database is going to set them according to their default values.
+
+[[schema-generation-column-default-value-persist-example]]
+.`@ColumnDefault` mapping example
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/ColumnDefaultTest.java[tag=schema-generation-column-default-value-persist-example]
+----
+
+[source, SQL, indent=0]
+----
+include::{extrasdir}/schema-generation-column-default-value-persist-example.sql[]
+----
+====

documentation/src/main/asciidoc/userguide/chapters/schema/extras/schema-generation-column-default-value-mapping-example.sql

@@ -0,0 +1,6 @@
+CREATE TABLE Person (
+  id BIGINT NOT NULL,
+  clientId BIGINT DEFAULT -1,
+  name VARCHAR(255) DEFAULT 'N/A',
+  PRIMARY KEY (id)
+)

documentation/src/main/asciidoc/userguide/chapters/schema/extras/schema-generation-column-default-value-persist-example.sql

@@ -0,0 +1 @@
+INSERT INTO Person (id) VALUES (?)

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

@@ -0,0 +1,67 @@
+/*
+ * 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 java.util.Date;
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.GeneratedValue;
+import javax.persistence.Id;
+
+import org.hibernate.annotations.CreationTimestamp;
+import org.hibernate.jpa.test.BaseEntityManagerFunctionalTestCase;
+
+import org.junit.Test;
+
+import static org.hibernate.testing.transaction.TransactionUtil.doInJPA;
+
+/**
+ * @author Vlad Mihalcea
+ */
+public class CreationTimestampTest extends BaseEntityManagerFunctionalTestCase {
+
+	@Override
+	protected Class<?>[] getAnnotatedClasses() {
+		return new Class<?>[] {
+			Event.class
+		};
+	}
+
+	@Test
+	public void test() {
+		doInJPA( this::entityManagerFactory, entityManager -> {
+			//tag::mapping-generated-CreationTimestamp-persist-example[]
+			Event dateEvent = new Event( );
+			entityManager.persist( dateEvent );
+			//end::mapping-generated-CreationTimestamp-persist-example[]
+		} );
+	}
+
+	//tag::mapping-generated-CreationTimestamp-example[]
+	@Entity(name = "Event")
+	public static class Event {
+
+		@Id
+		@GeneratedValue
+		private Long id;
+
+		@Column(name = "`timestamp`")
+		@CreationTimestamp
+		private Date timestamp;
+
+		public Event() {}
+
+		public Long getId() {
+			return id;
+		}
+
+		public Date getTimestamp() {
+			return timestamp;
+		}
+	}
+	//end::mapping-generated-CreationTimestamp-example[]
+}

documentation/src/test/java/org/hibernate/userguide/schema/ColumnDefaultTest.java

@@ -0,0 +1,93 @@
+/*
+ * 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.schema;
+
+import javax.persistence.Entity;
+import javax.persistence.Id;
+
+import org.hibernate.annotations.ColumnDefault;
+import org.hibernate.annotations.DynamicInsert;
+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
+ */
+public class ColumnDefaultTest extends BaseEntityManagerFunctionalTestCase {
+
+    @Override
+    protected Class<?>[] getAnnotatedClasses() {
+        return new Class<?>[] {
+            Person.class,
+        };
+    }
+
+    @Test
+    public void test() {
+		//tag::schema-generation-column-default-value-persist-example[]
+        doInJPA( this::entityManagerFactory, entityManager -> {
+            Person person = new Person();
+            person.setId( 1L );
+            entityManager.persist( person );
+        } );
+        doInJPA( this::entityManagerFactory, entityManager -> {
+            Person person = entityManager.find( Person.class, 1L );
+            assertEquals( "N/A", person.getName() );
+            assertEquals( Long.valueOf( -1L ), person.getClientId() );
+        } );
+		//end::schema-generation-column-default-value-persist-example[]
+    }
+
+    //tag::schema-generation-column-default-value-mapping-example[]
+    @Entity(name = "Person")
+    @DynamicInsert
+    public static class Person {
+
+        @Id
+        private Long id;
+
+        @ColumnDefault("'N/A'")
+        private String name;
+
+        @ColumnDefault("-1")
+        private Long clientId;
+
+        //Getter and setters omitted for brevity
+
+    //end::schema-generation-column-default-value-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 Long getClientId() {
+            return clientId;
+        }
+
+        public void setClientId(Long clientId) {
+            this.clientId = clientId;
+        }
+    //tag::schema-generation-column-default-value-mapping-example[]
+    }
+    //end::schema-generation-column-default-value-mapping-example[]
+}