clarify the semantics of hibernate.criteria.value_handling_mode

Author: gavinking

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

@@ -2395,20 +2395,38 @@ public interface AvailableSettings {
 	String MERGE_ENTITY_COPY_OBSERVER = "hibernate.event.merge.entity_copy_observer";
 
 	/**
-	 * By default, {@linkplain jakarta.persistence.criteria.CriteriaBuilder criteria}
-	 * queries use bind parameters for any value passed via the JPA Criteria API.
+	 * By default, a {@linkplain jakarta.persistence.criteria.CriteriaBuilder criteria
+	 * query} produces SQL with a JDBC bind parameter for any value specified via the
+	 * criteria query API, except when the value is passed via
+	 * {@link jakarta.persistence.criteria.CriteriaBuilder#literal(Object)}, in which
+	 * case the value is "inlined" as a SQL literal.
+	 * <p>
+	 * This setting may be used to override this default behavior:
 	 * <ul>
-	 *     <li>The {@link org.hibernate.query.criteria.ValueHandlingMode#BIND "bind"}
-	 *     mode uses bind variables for any literal value.
-	 *     <li>The {@link org.hibernate.query.criteria.ValueHandlingMode#INLINE "inline"}
+	 *     <li>the {@link org.hibernate.query.criteria.ValueHandlingMode#BIND "bind"}
+	 *     mode uses bind parameters to pass such values to JDBC, but
+	 *     <li>the {@link org.hibernate.query.criteria.ValueHandlingMode#INLINE "inline"}
 	 *     mode inlines values as SQL literals.
 	 * </ul>
 	 * <p>
-	 * The default value is {@link org.hibernate.query.criteria.ValueHandlingMode#BIND}.
+	 * In both modes:
+	 * <ul>
+	 * <li>values specified using {@code literal()} are inlined, and
+	 * <li>values specified using
+	 *     {@link jakarta.persistence.criteria.CriteriaBuilder#parameter(Class)} to create a
+	 *     {@link jakarta.persistence.criteria.ParameterExpression criteria parameter} and
+	 *     {@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}.
 	 *
 	 * @since 6.0.0
 	 *
 	 * @see org.hibernate.query.criteria.ValueHandlingMode
+	 * @see jakarta.persistence.criteria.CriteriaBuilder#literal(Object)
+	 * @see jakarta.persistence.criteria.CriteriaBuilder#parameter(Class)
+	 * @see org.hibernate.query.criteria.HibernateCriteriaBuilder#value(Object)
 	 */
 	String CRITERIA_VALUE_HANDLING_MODE = "hibernate.criteria.value_handling_mode";