Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

This commit is contained in:
Vlad Mihalcea 2016-03-03 18:07:22 +02:00
parent e99b60cbb6
commit b44af7cf16
16 changed files with 72 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
documentation/src/main/asciidoc/userguide/chapters/domain/basic_types.adoc
View File

@ -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());
entityManager.persist(dateEvent);
include::{sourcedir}/basic/DateWithTemporalDateTest.java[tags=basic-datetime-temporal-date-persist-example]
----
====
@ -879,21 +881,20 @@ Hibernate generates the following INSERT statement:
====
[source, sql, indent=0]
----
INSERT INTO DateEvent
( timestamp, id )
VALUES ( '2015-12-29', 1 )
include::{extrasdir}/basic/basic-datetime-temporal-date-persist-example.sql[]
----
====
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)
private Date timestamp;
include::{sourcedir}/basic/DateWithTemporalTimeTest.java[tags=basic-datetime-temporal-time-example]
----
====
@ -902,30 +903,27 @@ Hibernate will issue an INSERT statement containing the hour, minutes and second
====
[source, sql, indent=0]
----
INSERT INTO DateEvent
( timestamp, id )
VALUES ( '16:51:58', 1 )
include::{extrasdir}/basic/basic-datetime-temporal-time-persist-example.sql[]
----
====
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)
private Date timestamp;
include::{sourcedir}/basic/DateWithTemporalTimestampTest.java[tags=basic-datetime-temporal-timestamp-example]
----
====
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
( timestamp, id )
VALUES ( '2015-12-29 16:54:04.544', 1 )
include::{extrasdir}/basic/basic-datetime-temporal-timestamp-persist-example.sql[]
----
====
@ -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[]
----
====

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

@ -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;
}
}

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

@ -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;
}
}

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

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

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

@ -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);
}
}

2
documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/basic-datetime-temporal-date-persist-example.sql Normal file
View File

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

2
documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/basic-datetime-temporal-time-persist-example.sql Normal file
View File

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

2
documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/basic-datetime-temporal-timestamp-persist-example.sql Normal file
View File

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

2
documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/basic-jpa-convert-period-string-converter-sql-example.sql Normal file
View File

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

2
documentation/src/test/java/org/hibernate/userguide/mapping/CalendarWithTemporalTimestampTest.java → documentation/src/test/java/org/hibernate/userguide/mapping/basic/CalendarWithTemporalTimestampTest.java
View File

@ -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;

10
documentation/src/test/java/org/hibernate/userguide/mapping/DateWithTemporalDateTest.java → documentation/src/test/java/org/hibernate/userguide/mapping/basic/DateWithTemporalDateTest.java
View File

@ -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[]
}

4
documentation/src/test/java/org/hibernate/userguide/mapping/DateWithTemporalTimeTest.java → documentation/src/test/java/org/hibernate/userguide/mapping/basic/DateWithTemporalTimeTest.java
View File

@ -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() {
}

4
documentation/src/test/java/org/hibernate/userguide/mapping/DateWithTemporalTimestampTest.java → documentation/src/test/java/org/hibernate/userguide/mapping/basic/DateWithTemporalTimestampTest.java
View File

@ -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() {
}

2
documentation/src/test/java/org/hibernate/userguide/mapping/LocalDateTimeWithTemporalTimeTest.java → documentation/src/test/java/org/hibernate/userguide/mapping/basic/LocalDateTimeWithTemporalTimeTest.java
View File

@ -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;

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

@ -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
public String convertToDatabaseColumn(Period attribute) {
return attribute.toString();
}
@Override
public String convertToDatabaseColumn(Period attribute) {
return attribute.toString();
}
@Override
public Period convertToEntityAttribute(String dbData) {
return Period.parse( dbData );
}
@Override
public Period convertToEntityAttribute(String dbData) {
return Period.parse( dbData );
}
}
//end::basic-jpa-convert-period-string-converter-example[]

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

@ -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[]
}