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. +

Mapping annotations

diff --git a/release/src/release/javadoc/overview.html b/release/src/release/javadoc/overview.html index eb6ed96692..543e1b6175 100644 --- a/release/src/release/javadoc/overview.html +++ b/release/src/release/javadoc/overview.html @@ -59,6 +59,17 @@ 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. +

+

Mapping annotations