Notes about HibernateJpaVendorAdapter settings vs native Hibernate rules

Issue: SPR-16428

(cherry picked from commit e1fa65a)

spring-orm/src/main/java/org/springframework/orm/jpa/vendor/AbstractJpaVendorAdapter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -47,6 +47,10 @@ public abstract class AbstractJpaVendorAdapter implements JpaVendorAdapter {
 	/**
 	 * Specify the target database to operate on, as a value of the {@code Database} enum:
 	 * DB2, DERBY, H2, HSQL, INFORMIX, MYSQL, ORACLE, POSTGRESQL, SQL_SERVER, SYBASE
+	 * <p><b>NOTE:</b> This setting will override your JPA provider's default algorithm.
+	 * Custom vendor properties may still fine-tune the database dialect. However,
+	 * there may nevertheless be conflicts: For example, specify either this setting
+	 * or Hibernate's "hibernate.dialect_resolvers" property, not both.
 	 */
 	public void setDatabase(Database database) {
 		this.database = database;

spring-orm/src/main/java/org/springframework/orm/jpa/vendor/HibernateJpaVendorAdapter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -54,6 +54,14 @@ import org.hibernate.dialect.SQLServer2008Dialect;
  * we're exposing the correct, non-deprecated variant depending on the Hibernate
  * version encountered at runtime, in order to avoid deprecation log entries.
  *
+ * <p><b>A note about {@code HibernateJpaVendorAdapter} vs native Hibernate settings:</b>
+ * Some settings on this adapter may conflict with native Hibernate configuration rules
+ * or custom Hibernate properties. For example, specify either {@link #setDatabase} or
+ * Hibernate's "hibernate.dialect_resolvers" property, not both. Also, be careful about
+ * Hibernate's connection release mode: This adapter prefers {@code ON_CLOSE} behavior,
+ * aligned with {@link HibernateJpaDialect#setPrepareConnection}, at least for non-JTA
+ * scenarios; you may override this through corresponding native Hibernate properties.
+ *
  * @author Juergen Hoeller
  * @author Rod Johnson
  * @since 2.0