diff --git a/hibernate-core/src/main/java/org/hibernate/jpa/HibernateHints.java b/hibernate-core/src/main/java/org/hibernate/jpa/HibernateHints.java
index 6ec0e027ce..c6948bf8ec 100644
--- a/hibernate-core/src/main/java/org/hibernate/jpa/HibernateHints.java
+++ b/hibernate-core/src/main/java/org/hibernate/jpa/HibernateHints.java
@@ -13,6 +13,11 @@ package org.hibernate.jpa;
* Some hints are only effective in certain scenarios, which is noted
* on each constant's documentation.
*
+ * @apiNote The stringly-typed hints defined here correspond to
+ * typesafe operations of Hibernate's native APIs, and
+ * should not be used unless portability between JPA
+ * implementations is of very great importance.
+ *
* @author Steve Ebersole
*/
public interface HibernateHints {
diff --git a/hibernate-core/src/main/javadoc/overview.html b/hibernate-core/src/main/javadoc/overview.html
index 8415146b4c..a1cd269ca3 100644
--- a/hibernate-core/src/main/javadoc/overview.html
+++ b/hibernate-core/src/main/javadoc/overview.html
@@ -59,6 +59,16 @@
For example, SessionFactory
extends EntityManagerFactory
, and
Session
extends EntityManager
.
+ It's always possible to fall back from JPA interfaces to native APIs, by calling + {@link jakarta.persistence.EntityManager#unwrap entityManager.unwrap(Session.class)}, + {@link jakarta.persistence.EntityManagerFactory#unwrap entityManagerFactory.unwrap(SessionFactory.class)}, + or {@link jakarta.persistence.Query#unwrap query.unwrap(Query.class)}. In certain cases + it's also possible to access native functionality by passing a + {@linkplain org.hibernate.jpa.SpecHints JPA-defined} or + {@linkplain org.hibernate.jpa.HibernateHints Hibernate-defined} hint, at the cost of a + loss of type-safety. +
SessionFactory
extends EntityManagerFactory
, and
Session
extends EntityManager
.
++ It's always possible to fall back from JPA interfaces to native APIs, by calling + {@link jakarta.persistence.EntityManager#unwrap entityManager.unwrap(Session.class)}, + {@link jakarta.persistence.EntityManagerFactory#unwrap entityManagerFactory.unwrap(SessionFactory.class)}, + or {@link jakarta.persistence.Query#unwrap query.unwrap(Query.class)}. In certain cases + it's also possible to access native functionality by passing a + {@linkplain org.hibernate.jpa.SpecHints JPA-defined} or + {@linkplain org.hibernate.jpa.HibernateHints Hibernate-defined} hint, at the cost of a + loss of type-safety. +
+