warn people in javadoc that inSession() and friends don't flush!

Author: gavinking

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) {