clarify the semantics of hibernate.criteria.value_handling_mode

This commit is contained in:
Gavin King 2023-07-24 18:31:05 +02:00
parent ec9747983d
commit 05de3e487b
1 changed files with 24 additions and 6 deletions

View File

@ -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";