Notes about HibernateJpaVendorAdapter settings vs native Hibernate rules

Issue: SPR-16428

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.
@@ -49,6 +49,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.
@@ -51,6 +51,14 @@ import org.springframework.lang.Nullable;
  * along with Spring-driven entity scanning which requires no {@code persistence.xml}
  * ({@link org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean#setPackagesToScan}).
  *
+ * <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