Migrate Date/Time and AttributeConverter User Guide examples to unit tests

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

@@ -811,13 +811,13 @@ To switch the default mapping, simply call `MetadataBuilder.applyBasicType( UUID
 ==== UUID as binary
 
 As mentioned, the default mapping for UUID attributes.
-Maps the UUID to a `byte[]` using `java.util.UUID#getMostSignificantBits` and `java.util.UUID#getLeastSignificantBits` and stores that as BINARY data.
+Maps the UUID to a `byte[]` using `java.util.UUID#getMostSignificantBits` and `java.util.UUID#getLeastSignificantBits` and stores that as `BINARY` data.
 
 Chosen as the default simply because it is generally more efficient from storage perspective.
 
 ==== UUID as (var)char
 
-Maps the UUID to a String using `java.util.UUID#toString` and `java.util.UUID#fromString` and stores that as CHAR or VARCHAR data.
+Maps the UUID to a String using `java.util.UUID#toString` and `java.util.UUID#fromString` and stores that as `CHAR` or `VARCHAR` data.
 
 ==== PostgeSQL-specific UUID
 
@@ -828,7 +828,7 @@ When using one of the PostgreSQL Dialects, this becomes the default UUID mapping
 
 Maps the UUID using PostgreSQL's specific UUID data type.
 The PostgreSQL JDBC driver chooses to map its UUID type to the `OTHER` code.
-Note that this can cause difficulty as the driver chooses to map many different data types to OTHER.
+Note that this can cause difficulty as the driver chooses to map many different data types to `OTHER`.
 
 ==== UUID as identifier
 
@@ -856,21 +856,23 @@ This way, a `java.util.Date` or a `java.util.Calendar` cn be mapped to either an
 
 Considering the following entity:
 
-.`java.util.Date` mapping
+[[basic-datetime-temporal-date-example]]
+.`java.util.Date` mapped as `DATE`
 ====
 [source, JAVA, indent=0]
 ----
-include::{extrasdir}/basic/DateTemporal.java[]
+include::{sourcedir}/basic/DateWithTemporalDateTest.java[tags=basic-datetime-temporal-date-example]
 ----
 ====
 
 When persisting such entity:
 
+[[basic-datetime-temporal-date-persist-example]]
+.Persisting a `java.util.Date` mapping
 ====
 [source, JAVA, indent=0]
 ----
-DateEvent dateEvent = new DateEvent(new Date());
+include::{sourcedir}/basic/DateWithTemporalDateTest.java[tags=basic-datetime-temporal-date-persist-example]
-entityManager.persist(dateEvent);
 ----
 ====
 
@@ -879,21 +881,20 @@ Hibernate generates the following INSERT statement:
 ====
 [source, sql, indent=0]
 ----
-INSERT INTO DateEvent
+include::{extrasdir}/basic/basic-datetime-temporal-date-persist-example.sql[]
-       ( timestamp, id )
-VALUES ( '2015-12-29', 1 )
 ----
 ====
 
 Only the year, month and the day field were saved into the the database.
 
-If we change the `@Temporal` type to TIME:
+If we change the `@Temporal` type to `TIME`:
 
+[[basic-datetime-temporal-time-example]]
+.`java.util.Date` mapped as `TIME`
 ====
 [source, JAVA, indent=0]
 ----
-@Temporal(TemporalType.TIME)
+include::{sourcedir}/basic/DateWithTemporalTimeTest.java[tags=basic-datetime-temporal-time-example]
-private Date timestamp;
 ----
 ====
 
@@ -902,30 +903,27 @@ Hibernate will issue an INSERT statement containing the hour, minutes and second
 ====
 [source, sql, indent=0]
 ----
-INSERT INTO DateEvent
+include::{extrasdir}/basic/basic-datetime-temporal-time-persist-example.sql[]
-       ( timestamp, id )
-VALUES ( '16:51:58', 1 )
 ----
 ====
 
-When the the `@Temporal` type is set to TIMESTAMP:
+When the the `@Temporal` type is set to `TIMESTAMP`:
 
+[[basic-datetime-temporal-timestamp-example]]
+.`java.util.Date` mapped as `TIMESTAMP`
 ====
 [source, JAVA, indent=0]
 ----
-@Temporal(TemporalType.TIMESTAMP)
+include::{sourcedir}/basic/DateWithTemporalTimestampTest.java[tags=basic-datetime-temporal-timestamp-example]
-private Date timestamp;
 ----
 ====
 
-Hibernate will include both the DATE, the TIME and the nanoseconds in the INSERT statement:
+Hibernate will include both the `DATE`, the `TIME` and the nanoseconds in the INSERT statement:
 
 ====
 [source, sql, indent=0]
 ----
-INSERT INTO DateEvent
+include::{extrasdir}/basic/basic-datetime-temporal-timestamp-persist-example.sql[]
-       ( timestamp, id )
-VALUES ( '2015-12-29 16:54:04.544', 1 )
 ----
 ====
 
@@ -979,31 +977,34 @@ With a custom `AttributeConverter`, the application developer can map a given JD
 
 In the following example, the `java.util.Period` is going to be mapped to a `VARCHAR` database column.
 
+[[basic-jpa-convert-period-string-converter-example]]
 .`java.util.Period` custom `AttributeConverter`
 ====
 [source, JAVA, indent=0]
 ----
-include::{extrasdir}/basic/PeriodStringConverter.java[]
+include::{sourcedir}/converter/PeriodStringConverter.java[tags=basic-jpa-convert-period-string-converter-example]
 ----
 ====
 
 To make use of this custom converter, the `@Convert` annotation must decorate the entity attribute.
 
-.Entity using the custom `AttributeConverter`
+[[basic-jpa-convert-period-string-converter-mapping-example]]
+.Entity using the custom `java.util.Period` `AttributeConverter` mapping
 ====
 [source, JAVA, indent=0]
 ----
-include::{extrasdir}/basic/PeriodStringConvert.java[]
+include::{sourcedir}/converter/PeriodStringTest.java[tags=basic-jpa-convert-period-string-converter-mapping-example]
 ----
 ====
 
 When persisting such entity, Hibernate will do the type conversion based on the `AttributeConverter` logic:
 
+[[basic-jpa-convert-period-string-converter-sql-example]]
 .Persisting entity using the custom `AttributeConverter`
 ====
 [source, sql, indent=0]
 ----
-include::{extrasdir}/basic/PeriodStringConvert.sql[]
+include::{extrasdir}/basic/basic-jpa-convert-period-string-converter-sql-example.sql[]
 ----
 ====
 

documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/DateTemporal.java

@@ -1,24 +0,0 @@
-@Entity
-public class DateEvent  {
-
-    @Id
-    @GeneratedValue
-    private Long id;
-
-    @Temporal(TemporalType.DATE)
-    private Date timestamp;
-
-    public DateEvent() {}
-
-    public DateEvent(Date timestamp) {
-        this.timestamp = timestamp;
-    }
-
-    public Long getId() {
-        return id;
-    }
-
-    public Date getTimestamp() {
-        return timestamp;
-    }
-}

documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/PeriodStringConvert.java

@@ -1,24 +0,0 @@
-@Entity
-public class Event  {
-
-    @Id
-    @GeneratedValue
-    private Long id;
-
-    @Convert(converter = PeriodStringConverter.class)
-    private Period span;
-
-    public Event() {}
-
-    public Event(Period span) {
-        this.span = span;
-    }
-
-    public Long getId() {
-        return id;
-    }
-
-    public Period getSpan() {
-        return span;
-    }
-}

documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/PeriodStringConvert.sql

@@ -1,3 +0,0 @@
-INSERT INTO Event
-       ( span, id )
-VALUES ( 'P1Y2M3D', 1 )

documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/PeriodStringConverter.java

@@ -1,13 +0,0 @@
-@Converter
-public class PeriodStringConverter implements AttributeConverter<Period, String> {
-
-    @Override
-    public String convertToDatabaseColumn(Period attribute) {
-        return attribute.toString();
-    }
-
-    @Override
-    public Period convertToEntityAttribute(String dbData) {
-        return Period.parse(dbData);
-    }
-}

documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/basic-datetime-temporal-date-persist-example.sql

@@ -0,0 +1,2 @@
+INSERT INTO DateEvent ( timestamp, id )
+VALUES ( '2015-12-29', 1 )

documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/basic-datetime-temporal-time-persist-example.sql

@@ -0,0 +1,2 @@
+INSERT INTO DateEvent ( timestamp, id )
+VALUES ( '16:51:58', 1 )

documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/basic-datetime-temporal-timestamp-persist-example.sql

@@ -0,0 +1,2 @@
+INSERT INTO DateEvent ( timestamp, id )
+VALUES ( '2015-12-29 16:54:04.544', 1 )

documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/basic-jpa-convert-period-string-converter-sql-example.sql

@@ -0,0 +1,2 @@
+INSERT INTO Event ( span, id )
+VALUES ( 'P1Y2M3D', 1 )

documentation/src/test/java/org/hibernate/userguide/mapping/basic/CalendarWithTemporalTimestampTest.java

@@ -4,7 +4,7 @@
  * 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;
+package org.hibernate.userguide.mapping.basic;
 
 import java.util.Calendar;
 import java.util.GregorianCalendar;

documentation/src/test/java/org/hibernate/userguide/mapping/basic/DateWithTemporalDateTest.java

@@ -4,7 +4,7 @@
  * 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;
+package org.hibernate.userguide.mapping.basic;
 
 import java.util.Date;
 import javax.persistence.Column;
@@ -35,11 +35,14 @@ public class DateWithTemporalDateTest extends BaseEntityManagerFunctionalTestCas
 	@Test
 	public void testLifecycle() {
 		doInJPA( this::entityManagerFactory, entityManager -> {
+			//tag::basic-datetime-temporal-date-persist-example[]
 			DateEvent dateEvent = new DateEvent( new Date() );
 			entityManager.persist( dateEvent );
+			//end::basic-datetime-temporal-date-persist-example[]
 		} );
 	}
 
+	//tag::basic-datetime-temporal-date-example[]
 	@Entity(name = "DateEvent")
 	public static class DateEvent {
 
@@ -51,6 +54,9 @@ public class DateWithTemporalDateTest extends BaseEntityManagerFunctionalTestCas
 		@Temporal(TemporalType.DATE)
 		private Date timestamp;
 
+		//Getters and setters are omitted for brevity
+
+	//end::basic-datetime-temporal-date-example[]
 		public DateEvent() {
 		}
 
@@ -65,5 +71,7 @@ public class DateWithTemporalDateTest extends BaseEntityManagerFunctionalTestCas
 		public Date getTimestamp() {
 			return timestamp;
 		}
+	//tag::basic-datetime-temporal-date-example[]
 	}
+	//end::basic-datetime-temporal-date-example[]
 }

documentation/src/test/java/org/hibernate/userguide/mapping/basic/DateWithTemporalTimeTest.java

@@ -4,7 +4,7 @@
  * 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;
+package org.hibernate.userguide.mapping.basic;
 
 import java.util.Date;
 import javax.persistence.Column;
@@ -47,9 +47,11 @@ public class DateWithTemporalTimeTest extends BaseEntityManagerFunctionalTestCas
 		@GeneratedValue
 		private Long id;
 
+		//tag::basic-datetime-temporal-time-example[]
 		@Column(name = "`timestamp`")
 		@Temporal(TemporalType.TIME)
 		private Date timestamp;
+		//end::basic-datetime-temporal-time-example[]
 
 		public DateEvent() {
 		}

documentation/src/test/java/org/hibernate/userguide/mapping/basic/DateWithTemporalTimestampTest.java

@@ -4,7 +4,7 @@
  * 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;
+package org.hibernate.userguide.mapping.basic;
 
 import java.util.Date;
 import javax.persistence.Column;
@@ -47,9 +47,11 @@ public class DateWithTemporalTimestampTest extends BaseEntityManagerFunctionalTe
 		@GeneratedValue
 		private Long id;
 
+		//tag::basic-datetime-temporal-timestamp-example[]
 		@Column(name = "`timestamp`")
 		@Temporal(TemporalType.TIMESTAMP)
 		private Date timestamp;
+		//end::basic-datetime-temporal-timestamp-example[]
 
 		public DateEvent() {
 		}

documentation/src/test/java/org/hibernate/userguide/mapping/basic/LocalDateTimeWithTemporalTimeTest.java

@@ -4,7 +4,7 @@
  * 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;
+package org.hibernate.userguide.mapping.basic;
 
 import java.time.LocalDateTime;
 import javax.persistence.Column;

documentation/src/test/java/org/hibernate/userguide/mapping/converter/PeriodStringConverter.java

@@ -13,16 +13,19 @@ import javax.persistence.Converter;
 /**
  * @author Vlad Mihalcea
  */
+//tag::basic-jpa-convert-period-string-converter-example[]
 @Converter
-public class PeriodStringConverter implements AttributeConverter<Period, String> {
+public class PeriodStringConverter
+        implements AttributeConverter<Period, String> {
 
-	@Override
+    @Override
-	public String convertToDatabaseColumn(Period attribute) {
+    public String convertToDatabaseColumn(Period attribute) {
-		return attribute.toString();
+        return attribute.toString();
-	}
+    }
 
-	@Override
+    @Override
-	public Period convertToEntityAttribute(String dbData) {
+    public Period convertToEntityAttribute(String dbData) {
-		return Period.parse( dbData );
+        return Period.parse( dbData );
-	}
+    }
 }
+//end::basic-jpa-convert-period-string-converter-example[]

documentation/src/test/java/org/hibernate/userguide/mapping/converter/PeriodStringTest.java

@@ -46,6 +46,7 @@ public class PeriodStringTest extends BaseEntityManagerFunctionalTestCase {
 		} );
 	}
 
+	//tag::basic-jpa-convert-period-string-converter-mapping-example[]
 	@Entity(name = "Event")
 	public static class Event {
 
@@ -57,6 +58,10 @@ public class PeriodStringTest extends BaseEntityManagerFunctionalTestCase {
 		@Column(columnDefinition = "")
 		private Period span;
 
+		//Getters and setters are omitted for brevity
+
+	//end::basic-jpa-convert-period-string-converter-mapping-example[]
+
 		public Event() {
 		}
 
@@ -71,5 +76,7 @@ public class PeriodStringTest extends BaseEntityManagerFunctionalTestCase {
 		public Period getSpan() {
 			return span;
 		}
+	//tag::basic-jpa-convert-period-string-converter-mapping-example[]
 	}
+	//end::basic-jpa-convert-period-string-converter-mapping-example[]
 }