HHH-18545 - Document "characteristics" of settings

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

@@ -18,7 +18,8 @@
 public interface QuerySettings {
 	/**
 	 * Boolean setting to control if the use of tech preview JSON functions in HQL is enabled.
-	 * By default, this is {@code false} i.e. disabled since the functions are still incubating.
+	 *
+	 * @settingDefault {@code false} (disabled) since the functions are still incubating.
 	 *
 	 * @since 7.0
 	 */
@@ -27,7 +28,8 @@ public interface QuerySettings {
 
 	/**
 	 * Boolean setting to control if the use of tech preview XML functions in HQL is enabled.
-	 * By default, this is {@code false} i.e. disabled since the functions are still incubating.
+	 *
+	 * @settingDefault {@code false} (disabled) since the functions are still incubating.
 	 *
 	 * @since 7.0
 	 */
@@ -39,6 +41,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";
@@ -70,10 +74,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";
@@ -102,8 +106,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
 	 *
@@ -119,8 +123,8 @@ public interface QuerySettings {
 	 * of null values} sorted via the HQL {@code ORDER BY} clause, either {@code none},
 	 * {@code first}, or {@code last}, or an instance of the enumeration
 	 * {@link jakarta.persistence.criteria.Nulls}.
-	 * <p>
-	 * The default is {@code none}.
+	 *
+	 * @settingDefault {@code none}.
 	 *
 	 * @see jakarta.persistence.criteria.Nulls
 	 * @see org.hibernate.boot.SessionFactoryBuilder#applyDefaultNullPrecedence(jakarta.persistence.criteria.Nulls)
@@ -155,8 +159,8 @@ public interface QuerySettings {
 	/**
 	 * When enabled, ordinal parameters (represented by the {@code ?} placeholder) in
 	 * native queries will be ignored.
-	 * <p>
-	 * By default, native queries are checked for ordinal placeholders.
+	 *
+	 * @settingDefault {@code false} (disabled) - native queries are checked for ordinal placeholders.
 	 *
 	 * @see SessionFactoryOptions#getNativeJdbcParametersIgnored()
 	 */
@@ -167,12 +171,14 @@ public interface QuerySettings {
 	 * {@link java.sql.Time}, and {@link java.sql.Timestamp} instead of the
 	 * datetime types from {@link java.time}, recovering the behavior of
 	 * native queries in Hibernate 6 and earlier.
-	 * <p>
-	 * By default, native queries return {@link java.time.LocalDate},
-	 * {@link java.time.LocalTime}, and {@link java.time.LocalDateTime}.
+	 *
+	 * @settingDefault {@code false} (disabled) - native queries return
+	 * {@link java.time.LocalDate}, {@link java.time.LocalTime}, and
+	 * {@link java.time.LocalDateTime}.
 	 *
 	 * @since 7.0
 	 */
+	@Compatibility
 	String NATIVE_PREFER_JDBC_DATETIME_TYPES = "hibernate.query.native.prefer_jdbc_datetime_types";
 
 	/**
@@ -183,9 +189,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
 	 */
@@ -203,8 +209,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

@@ -4,6 +4,7 @@
  */
 package org.hibernate.cfg;
 
+
 import jakarta.persistence.spi.PersistenceUnitInfo;
 
 /**
@@ -127,6 +128,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
@@ -136,8 +157,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";
 
 	/**
@@ -151,29 +175,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
 		);
 	}
 }