add some documentation about date/time config settings

and also add some links

Author: gavinking

documentation/src/main/asciidoc/introduction/Configuration.adoc

@@ -481,10 +481,10 @@ The following properties are very useful for minimizing the amount of informatio
 |===
 | Configuration property name           | Purpose
 
-| `hibernate.default_schema`            | A default schema name for entities which do not explicitly declare one
-| `hibernate.default_catalog`           | A default catalog name for entities which do not explicitly declare one
-| `hibernate.physical_naming_strategy`  | A `PhysicalNamingStrategy` implementing your database naming standards
-| `hibernate.implicit_naming_strategy`  | An `ImplicitNamingStrategy` which specifies how "logical" names of relational objects should be inferred when no name is specified in annotations
+| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#DEFAULT_SCHEMA[`hibernate.default_schema`]            | A default schema name for entities which do not explicitly declare one
+| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#DEFAULT_CATALOG[`hibernate.default_catalog`]           | A default catalog name for entities which do not explicitly declare one
+| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#PHYSICAL_NAMING_STRATEGY[`hibernate.physical_naming_strategy`]  | A `PhysicalNamingStrategy` implementing your database naming standards
+| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#IMPLICIT_NAMING_STRATEGY[`hibernate.implicit_naming_strategy`]  | An `ImplicitNamingStrategy` which specifies how "logical" names of relational objects should be inferred when no name is specified in annotations
 |===
 
 [TIP]
@@ -507,8 +507,8 @@ The following settings enable automatic quoting:
 |===
 | Configuration property name           | Purpose
 
-| `hibernate.auto_quote_keyword`          | Automatically quote any identifier which is a SQL keyword
-| `hibernate.globally_quoted_identifiers` | Automatically quote every identifier
+| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#KEYWORD_AUTO_QUOTING_ENABLED[`hibernate.auto_quote_keyword`]          | Automatically quote any identifier which is a SQL keyword
+| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#GLOBALLY_QUOTED_IDENTIFIERS[`hibernate.globally_quoted_identifiers`] | Automatically quote every identifier
 |===
 
 Note that `hibernate.globally_quoted_identifiers` is a synonym for `<delimited-identifiers/>` in <<configuration-jpa,`persistence.xml`>>.
@@ -532,7 +532,7 @@ So, if you're working with SQL Server, you might need to force Hibernate to use
 |===
 | Configuration property name                 | Purpose
 
-| `hibernate.use_nationalized_character_data` | Use `nchar` and `nvarchar` instead of `char` and `varchar`
+| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#USE_NATIONALIZED_CHARACTER_DATA[`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 link:{doc-javadoc-url}org/hibernate/annotations/Nationalized.html[`@Nationalized`] annotation to indicate fields of your entities which map these columns.
@@ -543,3 +543,31 @@ On the other hand, if only _some_ columns store nationalized data, use the link:
 Alternatively, you can configure SQL Server to use the UTF-8 enabled collation `_UTF8`.
 ====
 
+[[datetime-jdbc]]
+=== Date and time types and JDBC
+
+By default, Hibernate handles date and time types defined by `java.time` by:
+
+- converting `java.time` types to JDBC date/time types defined in `java.sql` when sending data to the database, and
+- reading `java.sql` types from JDBC and then converting them to `java.time` types when retrieving data from the database.
+
+This works best when the database server time zone agrees with JVM system time zone.
+
+TIP: We therefore recommend setting things up so that the database server and the JVM agree on the same time zone. **Hint:** when in doubt, UTC quite a nice time zone.
+
+There are two system configuration properties which influence this behavior:
+
+.Settings for JDBC date/time handling
+[%breakable,cols="35,~"]
+|===
+| Configuration property name           | Purpose
+
+| link:{doc-javadoc-url}org/hibernate/cfg/JdbcSettings.html#JDBC_TIME_ZONE[`hibernate.jdbc.time_zone`]          | Use an explicit time zone when interacting with JDBC
+| link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#JAVA_TIME_USE_DIRECT_JDBC[`hibernate.type.java_time_use_direct_jdbc`] | Read and write `java.time` types directly to and from JDBC
+|===
+
+You may set `hibernate.jdbc.time_zone` to the time zone of the database server if for some reason the JVM needs to operate in a different time zone.
+We do not recommend this approach.
+
+On the other hand, we would love to recommend the use of `hibernate.type.java_time_use_direct_jdbc`, but this option is still experimental for now, and does result in some subtle differences in behavior which might affect legacy programs using Hibernate.
+