HHH-18545 - Document "characteristics" of settings

(cherry picked from commit 4f9035e)

Author: sebersole

documentation/documentation.gradle

@@ -573,7 +573,7 @@ settingsDocumentation {
 		}
 		transaction {
 			explicitPosition = 6
-			summary = "Proxool Connection Pool Settings"
+			summary = "Transaction Environment Settings"
 			description = "Settings which control how Hibernate interacts with and manages transactions"
 			settingsClassName "org.hibernate.cfg.TransactionSettings"
 		}

hibernate-core/src/main/java/org/hibernate/cfg/Compatibility.java

@@ -0,0 +1,23 @@
+/*
+ * SPDX-License-Identifier: LGPL-2.1-or-later
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.cfg;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import java.lang.annotation.Retention;
+
+/**
+ * Denotes that a setting is intended to allow applications to upgrade
+ * versions of Hibernate and maintain backwards compatibility with the
+ * older version in some specific behavior. Such settings are almost always
+ * considered temporary and are usually also {@linkplain Deprecated deprecated}.
+ */
+@Target(ElementType.FIELD)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+public @interface Compatibility {
+}

hibernate-core/src/main/java/org/hibernate/cfg/QuerySettings.java

@@ -23,6 +23,8 @@ public interface QuerySettings {
 	 * databases. By default, integer division in HQL can produce a non-integer
 	 * on Oracle, MySQL, or MariaDB.
 	 *
+	 * @settingDefault {@code false}
+	 *
 	 * @since 6.5
 	 */
 	String PORTABLE_INTEGER_DIVISION = "hibernate.query.hql.portable_integer_division";
@@ -53,10 +55,10 @@ public interface QuerySettings {
 	/**
 	 * When enabled, specifies that named queries be checked during startup.
 	 * <p>
-	 * By default, named queries are checked at startup.
-	 * <p>
 	 * Mainly intended for use in test environments.
 	 *
+	 * @settingDefault {@code true} (enabled) - named queries are checked at startup.
+	 *
 	 * @see org.hibernate.boot.SessionFactoryBuilder#applyNamedQueryCheckingOnStartup(boolean)
 	 */
 	String QUERY_STARTUP_CHECKING = "hibernate.query.startup_check";
@@ -85,8 +87,8 @@ public interface QuerySettings {
 	 *     {@link jakarta.persistence.Query#setParameter(jakarta.persistence.Parameter,Object)}
 	 *     to specify its argument are passed to JDBC using a bind parameter.
 	 * </ul>
-	 * <p>
-	 * The default mode is {@link org.hibernate.query.criteria.ValueHandlingMode#BIND}.
+	 *
+	 * @settingDefault {@link org.hibernate.query.criteria.ValueHandlingMode#BIND}.
 	 *
 	 * @since 6.0.0
 	 *
@@ -101,8 +103,8 @@ public interface QuerySettings {
 	 * Specifies the default {@linkplain NullPrecedence precedence of null values} in the
 	 * HQL {@code ORDER BY} clause, either {@code none}, {@code first}, or {@code last},
 	 * or an instance of {@link NullPrecedence}.
-	 * <p>
-	 * The default is {@code none}.
+	 *
+	 * @settingDefault {@code none}.
 	 *
 	 * @see NullPrecedence
 	 * @see org.hibernate.boot.SessionFactoryBuilder#applyDefaultNullPrecedence(NullPrecedence)
@@ -135,10 +137,10 @@ public interface QuerySettings {
 	String CRITERIA_COPY_TREE = "hibernate.criteria.copy_tree";
 
 	/**
-	 * When set to true, indicates that ordinal parameters (represented by the '?' placeholder) in native queries will be ignored.
-	 * <p>
-	 * By default, this is set to false, i.e. native queries will be checked for ordinal placeholders.
-	 * <p>
+	 * When enabled, ordinal parameters (represented by the {@code ?} placeholder) in
+	 * native queries will be ignored.
+	 *
+	 * @settingDefault {@code false} (disabled) - native queries are checked for ordinal placeholders.
 	 *
 	 * @see SessionFactoryOptions#getNativeJdbcParametersIgnored()
 	 */
@@ -152,9 +154,9 @@ public interface QuerySettings {
 	 * <p>
 	 * When enabled, this setting specifies that an exception should be thrown for any
 	 * query which would result in the limit being applied in-memory.
-	 * <p>
-	 * By default, the exception is <em>disabled</em>, and the possibility of terrible
-	 * performance is left as a problem for the client to avoid.
+	 *
+	 * @settingDefault {@code false} (disabled) - no exception is thrown and the
+	 * possibility of terrible performance is left as a problem for the client to avoid.
 	 *
 	 * @since 5.2.13
 	 */
@@ -172,8 +174,8 @@ public interface QuerySettings {
 	 *     <li>{@link org.hibernate.query.ImmutableEntityUpdateQueryHandlingMode#EXCEPTION "exception"}
 	 *     specifies that a {@link org.hibernate.HibernateException} should be thrown.
 	 * </ul>
-	 * <p>
-	 * By default, a warning is logged.
+	 *
+	 * @settingDefault {@link org.hibernate.query.ImmutableEntityUpdateQueryHandlingMode#WARNING "warning"}
 	 *
 	 * @since 5.2.17
 	 *

hibernate-core/src/main/java/org/hibernate/cfg/TransactionSettings.java

@@ -6,6 +6,7 @@
  */
 package org.hibernate.cfg;
 
+
 import jakarta.persistence.spi.PersistenceUnitInfo;
 
 /**
@@ -129,6 +130,26 @@ public interface TransactionSettings {
 	 */
 	String ALLOW_JTA_TRANSACTION_ACCESS = "hibernate.jta.allowTransactionAccess";
 
+	/**
+	 * When enabled, specifies that the {@link org.hibernate.Session} should be
+	 * closed automatically at the end of each transaction.
+	 *
+	 * @settingDefault {@code false}
+	 *
+	 * @see org.hibernate.boot.SessionFactoryBuilder#applyAutoClosing(boolean)
+	 */
+	String AUTO_CLOSE_SESSION = "hibernate.transaction.auto_close_session";
+
+	/**
+	 * When enabled, specifies that automatic flushing should occur during the JTA
+	 * {@link jakarta.transaction.Synchronization#beforeCompletion()} callback.
+	 *
+	 * @settingDefault {@code true} unless using JPA bootstrap
+	 *
+	 * @see org.hibernate.boot.SessionFactoryBuilder#applyAutoFlushing(boolean)
+	 */
+	String FLUSH_BEFORE_COMPLETION = "hibernate.transaction.flush_before_completion";
+
 	/**
 	 * Allows a detached proxy or lazy collection to be fetched even when not
 	 * associated with an open persistence context, by creating a temporary
@@ -138,8 +159,11 @@ public interface TransactionSettings {
 	 *
 	 * @settingDefault {@code false} (disabled)
 	 *
+	 * @apiNote Generally speaking, all access to transactional data should be done in a transaction.
+	 *
 	 * @see org.hibernate.boot.SessionFactoryBuilder#applyLazyInitializationOutsideTransaction(boolean)
 	 */
+	@Unsafe
 	String ENABLE_LAZY_LOAD_NO_TRANS = "hibernate.enable_lazy_load_no_trans";
 
 	/**
@@ -153,29 +177,15 @@ public interface TransactionSettings {
 	 * <p>
 	 * The default behavior is to disallow update operations outside a transaction.
 	 *
+	 * @settingDefault {@code false} (disabled)
+	 *
+	 * @apiNote Generally speaking, all access to transactional data should be done in a transaction.
+	 * Combining this with second-level caching, e.g., will cause problems.
+	 *
 	 * @see org.hibernate.boot.SessionFactoryBuilder#allowOutOfTransactionUpdateOperations(boolean)
 	 *
 	 * @since 5.2
 	 */
+	@Unsafe
 	String ALLOW_UPDATE_OUTSIDE_TRANSACTION = "hibernate.allow_update_outside_transaction";
-
-	/**
-	 * When enabled, specifies that the {@link org.hibernate.Session} should be
-	 * closed automatically at the end of each transaction.
-	 *
-	 * @settingDefault {@code false}
-	 *
-	 * @see org.hibernate.boot.SessionFactoryBuilder#applyAutoClosing(boolean)
-	 */
-	String AUTO_CLOSE_SESSION = "hibernate.transaction.auto_close_session";
-
-	/**
-	 * When enabled, specifies that automatic flushing should occur during the JTA
-	 * {@link jakarta.transaction.Synchronization#beforeCompletion()} callback.
-	 *
-	 * @settingDefault {@code true} unless using JPA bootstrap
-	 *
-	 * @see org.hibernate.boot.SessionFactoryBuilder#applyAutoFlushing(boolean)
-	 */
-	String FLUSH_BEFORE_COMPLETION = "hibernate.transaction.flush_before_completion";
 }

hibernate-core/src/main/java/org/hibernate/cfg/Unsafe.java

@@ -0,0 +1,22 @@
+/*
+ * SPDX-License-Identifier: LGPL-2.1-or-later
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.cfg;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import java.lang.annotation.Retention;
+
+/**
+ * Denotes that a setting is considered unsafe.  Generally these are settings
+ * added for temporary use during porting of applications.  Unsafe settings
+ * are largely considered unsupported.
+ */
+@Target(ElementType.FIELD)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+public @interface Unsafe {
+}

local-build-plugins/src/main/java/org/hibernate/orm/properties/AsciiDocWriter.java

@@ -109,6 +109,12 @@ private static void writeMetadata(SettingDescriptor settingDescriptor, FileWrite
 		if ( lifecycleDetails.isDeprecated() ) {
 			writer.write( "WARNING: *_This setting is considered deprecated_*\n\n" );
 		}
+		if ( settingDescriptor.isUnsafe() ) {
+			writer.write( "WARNING: *_This setting is considered unsafe_*\n\n" );
+		}
+		if ( settingDescriptor.isCompatibility() ) {
+			writer.write( "INFO: *_This setting manages a certain backwards compatibility_*\n\n" );
+		}
 
 		if ( lifecycleDetails.getSince() != null ) {
 			writer.write( "*_Since:_* _" + lifecycleDetails.getSince() + "_\n\n" );

local-build-plugins/src/main/java/org/hibernate/orm/properties/SettingDescriptor.java

@@ -18,6 +18,8 @@ public class SettingDescriptor {
 	private final String defaultValue;
 	private final String apiNote;
 	private final LifecycleDetails lifecycleDetails;
+	private final boolean unsafe;
+	private final boolean compatibility;
 
 	public SettingDescriptor(
 			String name,
@@ -27,6 +29,8 @@ public SettingDescriptor(
 			String comment,
 			String defaultValue,
 			String apiNote,
+			boolean unsafe,
+			boolean compatibility,
 			LifecycleDetails lifecycleDetails) {
 		this.name = name;
 		this.settingsClassName = settingsClassName;
@@ -35,6 +39,8 @@ public SettingDescriptor(
 		this.publishedJavadocLink = publishedJavadocLink;
 		this.defaultValue = defaultValue;
 		this.apiNote = apiNote;
+		this.unsafe = unsafe;
+		this.compatibility = compatibility;
 		this.lifecycleDetails = lifecycleDetails;
 	}
 
@@ -48,14 +54,18 @@ public SettingDescriptor(
 			String apiNote,
 			String since,
 			boolean deprecated,
-			boolean incubating) {
+			boolean incubating,
+			boolean unsafe,
+			boolean compatibility) {
 		this(
 				name,
 				settingsClassName,
 				settingFieldName,
 				publishedJavadocLink, comment,
 				defaultValue,
 				apiNote,
+				unsafe,
+				compatibility,
 				new LifecycleDetails( since, deprecated, incubating )
 		);
 	}
@@ -100,6 +110,14 @@ public String getSettingFieldName() {
 		return settingFieldName;
 	}
 
+	public boolean isUnsafe() {
+		return unsafe;
+	}
+
+	public boolean isCompatibility() {
+		return compatibility;
+	}
+
 	public LifecycleDetails getLifecycleDetails() {
 		return lifecycleDetails;
 	}

local-build-plugins/src/main/java/org/hibernate/orm/properties/SettingWorkingDetails.java

@@ -23,6 +23,8 @@ public class SettingWorkingDetails {
 	private String since;
 	private boolean deprecated;
 	private boolean incubating;
+	private boolean unsafe;
+	private boolean compatibility;
 	private List<String> relatedSettingNames;
 
 	public SettingWorkingDetails(
@@ -92,6 +94,22 @@ public void setIncubating(boolean incubating) {
 		this.incubating = incubating;
 	}
 
+	public boolean isUnsafe() {
+		return unsafe;
+	}
+
+	public void setUnsafe(boolean unsafe) {
+		this.unsafe = unsafe;
+	}
+
+	public boolean isCompatibility() {
+		return compatibility;
+	}
+
+	public void setCompatibility(boolean compatibility) {
+		this.compatibility = compatibility;
+	}
+
 	public List<String> getRelatedSettingNames() {
 		return relatedSettingNames;
 	}
@@ -134,7 +152,9 @@ public SettingDescriptor buildDescriptor(String asciidoc) {
 				apiNote,
 				since,
 				deprecated,
-				incubating
+				incubating,
+				unsafe,
+				compatibility
 		);
 	}
 }

local-build-plugins/src/main/java/org/hibernate/orm/properties/Utils.java

@@ -14,6 +14,8 @@
 import java.util.TreeMap;
 import java.util.TreeSet;
 
+import org.jsoup.nodes.Element;
+
 /**
  * @author Steve Ebersole
  */
@@ -39,4 +41,39 @@ public static Map<SettingsDocSection, SortedSet<SettingDescriptor>> createResult
 		} );
 		return map;
 	}
+
+	public static boolean containsHref(Element fieldJavadocElement, String target) {
+		final String cssQuery = "a[href$=" + target + "]";
+		final Element incubatingMarkerElement = fieldJavadocElement.selectFirst( cssQuery );
+		return incubatingMarkerElement != null;
+
+	}
+
+	public static boolean interpretIncubation(Element fieldJavadocElement) {
+		return containsHref( fieldJavadocElement, "Incubating.html" );
+	}
+
+	public static boolean interpretUnsafe(Element fieldJavadocElement) {
+		return containsHref( fieldJavadocElement, "Unsafe.html" );
+	}
+
+	public static boolean interpretCompatibility(Element fieldJavadocElement) {
+		return containsHref( fieldJavadocElement, "Compatibility.html" );
+	}
+
+	public static boolean interpretDeprecation(Element fieldJavadocElement) {
+		// A setting is considered deprecated with either `@Deprecated`
+		final Element deprecationDiv = fieldJavadocElement.selectFirst( ".deprecationBlock" );
+		// presence of this <div/> indicates the member is deprecated
+		if ( deprecationDiv != null ) {
+			return true;
+		}
+
+		// or `@Remove`
+		if ( containsHref( fieldJavadocElement, "Remove.html" ) ) {
+			return true;
+		}
+
+		return false;
+	}
 }