Merge branch 'hibernate:main' into HHH-18891

Author: peter1123581321

documentation/src/main/asciidoc/introduction/Advanced.adoc

@@ -1148,7 +1148,15 @@ session.enableFetchProfile(Book_.PROFILE_EAGER_BOOK);
 Book eagerBook = session.find(Book.class, bookId);
 ----
 
-Alternatively, an instance of link:{doc-javadoc-url}org/hibernate/EnabledFetchProfile.html[`EnabledFetchProfile`] may be obtained in a type safe way from the static metamodel, and used as a `FindOption`:
+Alternatively, an instance of link:{doc-javadoc-url}org/hibernate/EnabledFetchProfile.html[`EnabledFetchProfile`] may be obtained in a type safe way from the static metamodel, and applied to the session:
+
+[source,java]
+----
+Book_._EagerBook.enable(session);
+Book eagerBook = session.find(Book.class, bookId);
+----
+
+Even better, the `EnabledFetchProfile` may be passed as a `FindOption`:
 
 [source,java]
 ----

documentation/src/main/asciidoc/introduction/Interacting.adoc

@@ -395,7 +395,7 @@ _Orphan removal_ indicates that an `Item` should be automatically deleted if it
 Our data model is a set of interconnected entities, and in Java our whole dataset would be represented as an enormous interconnected graph of objects.
 It's possible that this graph is disconnected, but more likely it's connected, or composed of a relatively small number of connected subgraphs.
 
-Therefore, when we retrieve on object belonging to this graph from the database and instantiate it in memory, we simply can't recursively retrieve and instantiate all its associated entities.
+Therefore, when we retrieve an object belonging to this graph from the database and instantiate it in memory, we simply can't recursively retrieve and instantiate all its associated entities.
 Quite aside from the waste of memory on the VM side, this process would involve a huge number of round trips to the database server, or a massive multidimensional cartesian product of tables, or both.
 Instead, we're forced to cut the graph somewhere.
 

documentation/src/main/asciidoc/introduction/Introduction.adoc

@@ -531,7 +531,7 @@ You don't have to use stateful sessions, and you're not doing anything wrong if
 As of Hibernate 7, a key decision for any new project is which of these programming models to take as a baseline.
 Fortunately, the two models aren't mutually exclusive.
 This is a friendly competition, where the two APIs are designed to complement each other.
-Even if we decide to use `StatefulSession` most of the time, we can still use a `StatelessSession` wherever it's more convenient.
+Even if we decide to use stateful ``Session``s most of the time, we can still use a `StatelessSession` wherever it's more convenient.
 
 NOTE: On the other hand, if you decide to adopt Jakarta Data, the decision is made for you: repositories in Jakarta Data 1.0 are always stateless, and in https://hibernate.org/repositories/[Hibernate Data Repositories] a repository is backed by a `StatelessSession`.
 

documentation/src/main/asciidoc/introduction/Tuning.adoc

@@ -1175,7 +1175,7 @@ It's much more typesafe to use one of the first two options.
 === Reactive programming with Hibernate
 
 :hr: https://hibernate.org/reactive/
-:hr-guide: https://hibernate.org/reactive/documentation/2.0/reference/html_single/
+:hr-guide: https://hibernate.org/reactive/documentation/3.0/reference/html_single/
 
 Finally, many systems which require high scalability now make use of reactive programming and reactive streams.
 {hr}[Hibernate Reactive] brings O/R mapping to the world of reactive programming.

hibernate-core/src/main/java/org/hibernate/EnabledFetchProfile.java

@@ -5,16 +5,15 @@
 package org.hibernate;
 
 import jakarta.persistence.FindOption;
+import org.hibernate.query.SelectionQuery;
 
 /**
  * A {@link jakarta.persistence.FindOption} which requests a named
  * {@linkplain org.hibernate.annotations.FetchProfile fetch profile}.
  * <p>
  * An instance of this class may be obtained in a type safe way
  * from the static metamodel for the class annotated
- * {@link org.hibernate.annotations.FetchProfile @FetchProfile}
- * and passed as an option to
- * {@link Session#find(Class, Object, FindOption...) find()}.
+ * {@link org.hibernate.annotations.FetchProfile @FetchProfile}.
  * <p>
  * For example, this class defines a fetch profile:
  * <pre>
@@ -28,11 +27,20 @@
  *     Set&lt;Author&gt; authors;
  * }
  * </pre>
- * The fetch profile may be requested like this:
+ * <p>
+ * An {@code EnabledFetchProfile} may be obtained from the static
+ * metamodel for the entity {@code Book} and passed as an option to
+ * {@link Session#find(Class, Object, FindOption...) find()}.
  * <pre>
  * Book bookWithAuthors =
  *         session.find(Book.class, isbn, Book_._WithAuthors)
  * </pre>
+ * Alternatively, it may be {@linkplain #enable(Session) applied}
+ * to a {@code Session} or {@code Query}.
+ * <pre>
+ * Book_._WithAuthors.enable(session);
+ * Book bookWithAuthors = session.find(Book.class, isbn);
+ * </pre>
  * <p>
  * When the static metamodel is not used, an {@code EnabledFetchProfile}
  * may be instantiated directly, passing the name of the fetch profile
@@ -54,4 +62,20 @@
  */
 public record EnabledFetchProfile(String profileName)
 		implements FindOption {
+
+	/**
+	 * Enable the fetch profile represented by this
+	 * object in the given session.
+	 */
+	public void enable(Session session) {
+		session.enableFetchProfile(profileName);
+	}
+
+	/**
+	 * Enable the fetch profile represented by this
+	 * object during execution of the given query.
+	 */
+	public void enable(SelectionQuery<?> query) {
+		query.enableFetchProfile(profileName);
+	}
 }

hibernate-core/src/main/java/org/hibernate/LockMode.java

@@ -52,7 +52,7 @@ public enum LockMode implements FindOption, RefreshOption {
 	 * rather than pull it from a cache.
 	 * <p>
 	 * This is the "default" lock mode, the mode requested by calling
-	 * {@link Session#get(Class, Object)} without passing an explicit
+	 * {@link Session#find(Class, Object)} without passing an explicit
 	 * mode. It permits the state of an object to be retrieved from
 	 * the cache without the cost of database access.
 	 *

hibernate-core/src/main/java/org/hibernate/Session.java

@@ -825,19 +825,32 @@ public interface Session extends SharedSessionContract, EntityManager {
 	void remove(Object object);
 
 	/**
-	 * Determine the current {@link LockMode} of the given managed instance associated
-	 * with this session.
+	 * Determine the current {@linkplain LockMode lock mode} held on the given
+	 * managed instance associated with this session.
+	 * <p>
+	 * Unlike the JPA-standard {@link #getLockMode}, this operation may be
+	 * called when no transaction is active, in which case it should return
+	 * {@link LockMode#NONE}, indicating that no pessimistic lock is held on
+	 * the given entity.
 	 *
 	 * @param object a persistent instance associated with this session
 	 *
-	 * @return the current lock mode
+	 * @return the lock mode currently held on the given entity
+	 *
+	 * @throws IllegalStateException if the given instance is not associated
+	 *                               with this persistence context
+	 * @throws ObjectDeletedException if the given instance was already
+	 *                                {@linkplain #remove removed}
 	 */
 	LockMode getCurrentLockMode(Object object);
 
 	/**
-	 * Completely clear the session. Evict all loaded instances and cancel all pending
-	 * saves, updates and deletions. Do not close open iterators or instances of
-	 * {@link ScrollableResults}.
+	 * Completely clear the persistence context. Evict all loaded instances,
+	 * causing every managed entity currently associated with this session to
+	 * transition to the detached state, and cancel all pending insertions,
+	 * updates, and deletions.
+	 * <p>
+	 * Does not close open iterators or instances of {@link ScrollableResults}.
 	 */
 	@Override
 	void clear();

hibernate-core/src/main/java/org/hibernate/SessionFactory.java

@@ -227,7 +227,19 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser
 	StatelessSession openStatelessSession(Connection connection);
 
 	/**
-	 * Open a {@link Session} and use it to perform an action.
+	 * Open a {@link Session} and use it to perform the given action.
+	 *
+	 * @apiNote This method does not begin a transaction, and so
+	 * the session is not automatically flushed before the method
+	 * returns unless either:
+	 * <ul>
+	 * <li>the given action calls {@link Session#flush() flush()}
+	 *     explicitly, or
+	 * <li>a transaction is initiated by the given action, using
+	 *     {@link Session#inTransaction}, for example.
+	 * </ul>
+	 *
+	 * @see #inTransaction(Consumer)
 	 */
 	default void inSession(Consumer<? super Session> action) {
 		try ( Session session = openSession() ) {
@@ -236,7 +248,20 @@ default void inSession(Consumer<? super Session> action) {
 	}
 
 	/**
-	 * Open a {@link StatelessSession} and use it to perform an action.
+	 * Open a {@link StatelessSession} and use it to perform the
+	 * given action.
+	 *
+	 * @apiNote This method does not begin a transaction, and so
+	 * the session is not automatically flushed before the method
+	 * returns unless either:
+	 * <ul>
+	 * <li>the given action calls {@link Session#flush() flush()}
+	 *     explicitly, or
+	 * <li>a transaction is initiated by the given action, using
+	 *     {@link Session#inTransaction}, for example.
+	 * </ul>
+	 *
+	 * @see #inStatelessTransaction(Consumer)
 	 *
 	 * @since 6.3
 	 */
@@ -247,7 +272,7 @@ default void inStatelessSession(Consumer<? super StatelessSession> action) {
 	}
 
 	/**
-	 * Open a {@link Session} and use it to perform an action
+	 * Open a {@link Session} and use it to perform the given action
 	 * within the bounds of a transaction.
 	 *
 	 * @apiNote This method competes with the JPA-defined method
@@ -269,6 +294,18 @@ default void inStatelessTransaction(Consumer<? super StatelessSession> action) {
 
 	/**
 	 * Open a {@link Session} and use it to obtain a value.
+	 *
+	 * @apiNote This method does not begin a transaction, and so
+	 * the session is not automatically flushed before the method
+	 * returns unless either:
+	 * <ul>
+	 * <li>the given action calls {@link Session#flush() flush()}
+	 *     explicitly, or
+	 * <li>a transaction is initiated by the given action, using
+	 *     {@link Session#inTransaction}, for example.
+	 * </ul>
+	 *
+	 * @see #fromTransaction(Function)
 	 */
 	default <R> R fromSession(Function<? super Session,R> action) {
 		try ( Session session = openSession() ) {
@@ -279,6 +316,18 @@ default <R> R fromSession(Function<? super Session,R> action) {
 	/**
 	 * Open a {@link StatelessSession} and use it to obtain a value.
 	 *
+	 * @apiNote This method does not begin a transaction, and so
+	 * the session is not automatically flushed before the method
+	 * returns unless either:
+	 * <ul>
+	 * <li>the given action calls {@link Session#flush() flush()}
+	 *     explicitly, or
+	 * <li>a transaction is initiated by the given action, using
+	 *     {@link Session#inTransaction}, for example.
+	 * </ul>
+	 *
+	 * @see #fromStatelessTransaction(Function)
+	 *
 	 * @since 6.3
 	 */
 	default <R> R fromStatelessSession(Function<? super StatelessSession,R> action) {

hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java

@@ -1941,7 +1941,7 @@ protected void secondPassCompileForeignKeys(Table table, Set<ForeignKey> done, M
 		table.createForeignKeys( buildingContext );
 
 		final Dialect dialect = getDatabase().getJdbcEnvironment().getDialect();
-		for ( ForeignKey foreignKey : table.getForeignKeys().values() ) {
+		for ( ForeignKey foreignKey : table.getForeignKeyCollection() ) {
 			if ( !done.contains( foreignKey ) ) {
 				done.add( foreignKey );
 				final PersistentClass referencedClass = foreignKey.resolveReferencedClass(this);

hibernate-core/src/main/java/org/hibernate/boot/internal/MetadataImpl.java

@@ -408,7 +408,7 @@ private void handleUDT(UserDefinedType userDefinedType, ColumnOrderingStrategy c
 	}
 
 	private void handleForeignKeys(Table table, ColumnOrderingStrategy columnOrderingStrategy) {
-		for ( ForeignKey foreignKey : table.getForeignKeys().values() ) {
+		for ( ForeignKey foreignKey : table.getForeignKeyCollection() ) {
 			final List<Column> columns = foreignKey.getColumns();
 			if ( columns.size() > 1 ) {
 				if ( foreignKey.getReferencedColumns().isEmpty() ) {