HHH-19350 improve interpretation logic in PhysicalConnectionHandlingMode

and properly document inter-mode compatibility in jdoc

Author: gavinking

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

@@ -18,14 +18,15 @@ public enum ConnectionAcquisitionMode {
 	/**
 	 * The {@code Connection} will be acquired as soon as a session is opened.
 	 * <p>
-	 * This circumvents the {@link ConnectionReleaseMode}, as the {@code Connection}
-	 * will then be held until the session is closed.
+	 * In this acquisition mode, {@link ConnectionReleaseMode#ON_CLOSE} must be used.
 	 */
 	IMMEDIATELY,
 	/**
 	 * A {@code Connection} is acquired only when (and if) it's actually needed.
 	 * <p>
 	 * This is the default (and legacy) behavior.
+	 * <p>
+	 * In this acquisition mode, any {@link ConnectionReleaseMode} must be used.
 	 */
 	AS_NEEDED;
 

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

@@ -88,6 +88,9 @@ public interface SessionBuilder {
 
 	/**
 	 * Specifies the connection handling modes for the session.
+	 * <p>
+	 * Note that if {@link ConnectionAcquisitionMode#IMMEDIATELY} is specified,
+	 * then the release mode must be {@link ConnectionReleaseMode#ON_CLOSE}.
 	 *
 	 * @return {@code this}, for method chaining
 	 *

hibernate-core/src/main/java/org/hibernate/resource/jdbc/spi/PhysicalConnectionHandlingMode.java

@@ -9,12 +9,14 @@
 import org.hibernate.ConnectionAcquisitionMode;
 import org.hibernate.ConnectionReleaseMode;
 
+import static java.util.Objects.requireNonNull;
 import static org.hibernate.ConnectionAcquisitionMode.AS_NEEDED;
 import static org.hibernate.ConnectionAcquisitionMode.IMMEDIATELY;
 import static org.hibernate.ConnectionReleaseMode.AFTER_STATEMENT;
 import static org.hibernate.ConnectionReleaseMode.AFTER_TRANSACTION;
 import static org.hibernate.ConnectionReleaseMode.BEFORE_TRANSACTION_COMPLETION;
 import static org.hibernate.ConnectionReleaseMode.ON_CLOSE;
+import static org.hibernate.internal.util.StringHelper.isBlank;
 
 /**
  * Enumerates valid combinations of {@link ConnectionAcquisitionMode} and
@@ -72,42 +74,39 @@ public ConnectionReleaseMode getReleaseMode() {
 	}
 
 	public static PhysicalConnectionHandlingMode interpret(Object setting) {
-		if ( setting == null ) {
-			return null;
+		if ( setting instanceof PhysicalConnectionHandlingMode mode ) {
+			return mode;
 		}
+		else if ( setting instanceof String string ) {
+			return isBlank( string ) ? null
+					: valueOf( string.trim().toUpperCase( Locale.ROOT ) );
 
-		if ( setting instanceof PhysicalConnectionHandlingMode physicalConnectionHandlingMode ) {
-			return physicalConnectionHandlingMode;
 		}
-
-		final String value = setting.toString().trim();
-		if ( value.isEmpty() ) {
+		else {
 			return null;
 		}
-
-		return valueOf( value.toUpperCase( Locale.ROOT ) );
 	}
 
 	public static PhysicalConnectionHandlingMode interpret(
 			ConnectionAcquisitionMode acquisitionMode,
 			ConnectionReleaseMode releaseMode) {
-		if ( acquisitionMode == IMMEDIATELY ) {
-			if ( releaseMode != null && releaseMode != ON_CLOSE ) {
-				throw new IllegalArgumentException(
+		requireNonNull( acquisitionMode, "ConnectionAcquisitionMode must be specified" );
+		requireNonNull( acquisitionMode, "ConnectionReleaseMode must be specified" );
+		return switch ( acquisitionMode ) {
+			case AS_NEEDED -> switch ( releaseMode ) {
+				case ON_CLOSE -> DELAYED_ACQUISITION_AND_HOLD;
+				case AFTER_STATEMENT -> DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT;
+				case BEFORE_TRANSACTION_COMPLETION -> DELAYED_ACQUISITION_AND_RELEASE_BEFORE_TRANSACTION_COMPLETION;
+				case AFTER_TRANSACTION -> DELAYED_ACQUISITION_AND_RELEASE_AFTER_TRANSACTION;
+			};
+			case IMMEDIATELY -> switch ( releaseMode ) {
+				case ON_CLOSE -> IMMEDIATE_ACQUISITION_AND_HOLD;
+				default -> throw new IllegalArgumentException(
 						"Only ConnectionReleaseMode.ON_CLOSE can be used in combination with "
 						+ "ConnectionAcquisitionMode.IMMEDIATELY; but ConnectionReleaseMode."
 						+ releaseMode.name() + " was specified."
 				);
-			}
-			return IMMEDIATE_ACQUISITION_AND_HOLD;
-		}
-		else {
-			return switch ( releaseMode ) {
-				case AFTER_STATEMENT -> DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT;
-				case BEFORE_TRANSACTION_COMPLETION -> DELAYED_ACQUISITION_AND_RELEASE_BEFORE_TRANSACTION_COMPLETION;
-				case AFTER_TRANSACTION -> DELAYED_ACQUISITION_AND_RELEASE_AFTER_TRANSACTION;
-				default -> DELAYED_ACQUISITION_AND_HOLD;
 			};
-		}
+		};
 	}
 }