add an @APinote to LockAcquisitionException and LockTimeoutException

Author: gavinking

hibernate-core/src/main/java/org/hibernate/exception/LockAcquisitionException.java

@@ -13,6 +13,13 @@
  * A {@link JDBCException} indicating a problem acquiring a lock
  * on the database.
  *
+ * @apiNote Some databases make it quite hard to for a client to
+ * distinguish a {@linkplain LockTimeoutException lock timeout}
+ * from other sorts of rejected lock acquisitions, and so
+ * application programs should not over-interpret the distinction
+ * made between {@code LockAcquisitionException} and its subclass
+ * {@link LockTimeoutException} on such platforms.
+ *
  * @author Steve Ebersole
  */
 public class LockAcquisitionException extends PessimisticLockException {

hibernate-core/src/main/java/org/hibernate/exception/LockTimeoutException.java

@@ -12,6 +12,13 @@
  * A {@link JDBCException} indicating that a {@linkplain org.hibernate.LockMode lock}
  * request timed out on the database.
  *
+ * @apiNote Some databases make it quite hard to for a client
+ * to distinguish a lock timeout from other sorts of rejected
+ * lock acquisitions, and so application programs should avoid
+ * over-interpreting the distinction made between
+ * {@code LockTimeoutException} and its superclass
+ * {@link LockAcquisitionException} on such platforms.
+ *
  * @author Steve Ebersole
  *
  * @see org.hibernate.LockOptions#getTimeOut