From b4bab0d2a3ca96b8655313bca09e5ec3136601c7 Mon Sep 17 00:00:00 2001 From: Gavin Date: Sat, 10 Jun 2023 00:41:44 +0200 Subject: [PATCH] document new features for typesafety --- .../src/main/asciidoc/introduction/Advanced.adoc | 7 ++----- .../main/asciidoc/introduction/Configuration.adoc | 13 +++++++++---- .../src/main/asciidoc/introduction/Interacting.adoc | 6 ++++-- .../main/asciidoc/introduction/Introduction.adoc | 4 ++++ 4 files changed, 19 insertions(+), 11 deletions(-) diff --git a/documentation/src/main/asciidoc/introduction/Advanced.adoc b/documentation/src/main/asciidoc/introduction/Advanced.adoc index a341b4f469..db28b95d28 100644 --- a/documentation/src/main/asciidoc/introduction/Advanced.adoc +++ b/documentation/src/main/asciidoc/introduction/Advanced.adoc @@ -875,14 +875,11 @@ A fetch profile must be explicitly enabled for a given session: [source,java] ---- -session.enableFetchProfile("EagerBook"); +session.enableFetchProfile(Book_.PROFILE_EAGER_BOOK); Book eagerBook = session.find(Book.class, bookId); ---- -[TIP] -==== -To make this a bit typesafe, it's a good idea to put the name of the fetch profile in a `static final` constant. -==== +Here, once again, `BookQueries_.PROFILE_EAGER_BOOK` is generated by the Metamodel Generator, and is just a constant with the value `"EagerBook"`. So why or when might we prefer named fetch profiles to entity graphs? Well, it's really hard to say. diff --git a/documentation/src/main/asciidoc/introduction/Configuration.adoc b/documentation/src/main/asciidoc/introduction/Configuration.adoc index ac3b61c5c6..f7870dd4f9 100644 --- a/documentation/src/main/asciidoc/introduction/Configuration.adoc +++ b/documentation/src/main/asciidoc/introduction/Configuration.adoc @@ -86,6 +86,8 @@ Where `{version}` is the latest version of the JDBC driver for your databse. :infinispan: https://infinispan.org :generator: https://hibernate.org/orm/tooling/ :caffeine: https://github.com/ben-manes/caffeine/ +:bean-validation: https://beanvalidation.org +:query-validator: https://github.com/hibernate/query-validator/ Optionally, you might also add any of the following additional features: @@ -101,7 +103,8 @@ or `org.slf4j:slf4j-jdk14` `org.hibernate.orm:hibernate-agroal` + and `io.agroal:agroal-pool` | The {generator}[Hibernate Metamodel Generator], especially if you're using the JPA criteria query API | `org.hibernate.orm:hibernate-jpamodelgen` -| {validator}[Hibernate Validator] | +| The {query-validator}[Query Validator], for compile-time checking of HQL | `org.hibernate:query-validator` +| {validator}[Hibernate Validator], an implementation of {bean-validation}[Bean Validation] | `org.hibernate.validator:hibernate-validator` + and `org.glassfish:jakarta.el` | Local second-level cache support via JCache and {ehcache}[EHCache] | `org.hibernate.orm:hibernate-jcache` + @@ -443,7 +446,9 @@ We'll have more to say about them in <>. [[nationalized-chars]] === Nationalized character data in SQL Server -_By default,_ SQL Server's `char` and `varchar` types don't accommodate Unicode data. But a Java string may contain any Unicode character. So, if you're working with SQL Server, you might need to force Hibernate to use the `nchar` and `nvarchar` column types. +_By default,_ SQL Server's `char` and `varchar` types don't accommodate Unicode data. +But a Java string may contain any Unicode character. +So, if you're working with SQL Server, you might need to force Hibernate to use the `nchar` and `nvarchar` column types. .Setting the use of nationalized character data [%breakable,cols="40,~"] @@ -453,11 +458,11 @@ _By default,_ SQL Server's `char` and `varchar` types don't accommodate Unicode | `hibernate.use_nationalized_character_data` | Use `nchar` and `nvarchar` instead of `char` and `varchar` |=== +On the other hand, if only _some_ columns store nationalized data, use the `@Nationalized` annotation to indicate fields of your entities which map these columns. + [TIP] // .Configuring SQL Server to use UTF-8 by default ==== Alternatively, you can configure SQL Server to use the UTF-8 enabled collation `_UTF8`. ==== -On the other hand, if only _some_ columns store nationalized data, use the `@Nationalized` annotation to indicate fields of your entities which map these columns. - diff --git a/documentation/src/main/asciidoc/introduction/Interacting.adoc b/documentation/src/main/asciidoc/introduction/Interacting.adoc index 741e167849..f0a28dbdc5 100644 --- a/documentation/src/main/asciidoc/introduction/Interacting.adoc +++ b/documentation/src/main/asciidoc/introduction/Interacting.adoc @@ -904,7 +904,7 @@ var resultList = session.createSelectionQuery(query).getResultList(); for (var result: resultList) { String title = result.get(bookTitle); String isbn = result.get(bookIsbn); - BigDecimal price = result.get(bookPrice); + BigDecimal price = result.get(bookPrice); ... } ---- @@ -947,11 +947,13 @@ We execute our named query as follows: [source,java] ---- List books = - entityManager.createNamedQuery("10BooksByTitle") + entityManager.createNamedQuery(BookQueries_.QUERY_10_BOOKS_BY_TITLE) .setParameter("titlePattern", titlePattern) .getResultList() ---- +Here, `BookQueries_.QUERY_10_BOOKS_BY_TITLE` is generated by the Metamodel Generator, and is just a constant with the value `"10BooksByTitle"`. + Note that the code which executes the named query is not aware of whether the query was written in HQL or in native SQL, making it slightly easier to change and optimize the query later. [[load-access]] diff --git a/documentation/src/main/asciidoc/introduction/Introduction.adoc b/documentation/src/main/asciidoc/introduction/Introduction.adoc index 16833f7227..0dd0dc80e1 100644 --- a/documentation/src/main/asciidoc/introduction/Introduction.adoc +++ b/documentation/src/main/asciidoc/introduction/Introduction.adoc @@ -234,6 +234,10 @@ dependencies { // JPA metamodel generator (for criteria queries) annotationProcessor 'org.hibernate.orm:hibernate-jpamodelgen:6.2.2.Final' + // Compile-time checking for HQL + //implementation 'org.hibernate:query-validator:2.0-SNAPSHOT' + //annotationProcessor 'org.hibernate:query-validator:2.0-SNAPSHOT' + // H2 database runtimeOnly 'com.h2database:h2:2.1.214' }