Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

javadoc revision to CommonQueryContract 

and fix the package info for org.hibernate.persister.walking.spi
This commit is contained in:
Gavin King 2022-01-27 01:05:45 +01:00
parent be49444822
commit d3c38f2a8e
3 changed files with 171 additions and 139 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
hibernate-core/src/main/java/org/hibernate/persister/entity/AbstractEntityPersister.java
View File

@ -19,7 +19,6 @@ import java.util.Comparator;
import java.util.HashMap; import java.util.HashMap;
import java.util.HashSet; import java.util.HashSet;
import java.util.IdentityHashMap; import java.util.IdentityHashMap;
import java.util.Iterator;
import java.util.LinkedHashMap; import java.util.LinkedHashMap;
import java.util.List; import java.util.List;
import java.util.Map; import java.util.Map;

9
hibernate-core/src/main/java/org/hibernate/persister/walking/spi/package-info.java
View File

@ -4,9 +4,12 @@
* License: GNU Lesser General Public License (LGPL), version 2.1 or later. * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
* See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>. * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
*/ */
package org.hibernate.persister.walking.spi;
/** /**
* Package for "walking" associations through metadata definition. Ultimately want {@link org.hibernate.persister.walking.spi.AttributeDefinition} and * Package for "walking" associations through metadata definition. Ultimately
* {@link AttributeSource} etc to become part of the persister model. * want {@link org.hibernate.persister.walking.spi.AttributeDefinition} and
* {@link org.hibernate.persister.walking.spi.AttributeSource} etc to become
* part of the persister model.
*/ */
package org.hibernate.persister.walking.spi;

300
hibernate-core/src/main/java/org/hibernate/query/CommonQueryContract.java
View File

@ -20,8 +20,10 @@ import jakarta.persistence.Parameter;
import jakarta.persistence.TemporalType; import jakarta.persistence.TemporalType;
/** /**
* Defines the aspects of query definition that apply to all forms of * Defines the aspects of query execution and parameter binding that apply to all
* querying - HQL, Criteria and ProcedureCall * forms of querying - HQL, {@linkplain jakarta.persistence.criteria.CriteriaBuilder
* criteria queries} and {@link org.hibernate.procedure.ProcedureCall stored
* procedure calls}.
* *
* @author Steve Ebersole * @author Steve Ebersole
* @author Gavin King * @author Gavin King
@ -29,8 +31,9 @@ import jakarta.persistence.TemporalType;
public interface CommonQueryContract { public interface CommonQueryContract {
/** /**
* The FlushModeType in effect for this query. By default, the query * The JPA {@link FlushModeType} in effect for this query. By default, the
* inherits the FlushMode of the Session from which it originates. * query inherits the {@link FlushMode} of the {@link Session} from which
* it originates.
* *
* @see #getHibernateFlushMode * @see #getHibernateFlushMode
* @see Session#getHibernateFlushMode * @see Session#getHibernateFlushMode
@ -38,7 +41,7 @@ public interface CommonQueryContract {
FlushModeType getFlushMode(); FlushModeType getFlushMode();
/** /**
* Set the FlushMode in to use for this query. * Set the {@link FlushMode} in to use for this query.
* *
* @implNote Setting to {@code null} ultimately indicates to use the * @implNote Setting to {@code null} ultimately indicates to use the
* FlushMode of the Session. Use {@link #setHibernateFlushMode} passing * FlushMode of the Session. Use {@link #setHibernateFlushMode} passing
@ -51,19 +54,20 @@ public interface CommonQueryContract {
CommonQueryContract setFlushMode(FlushModeType flushMode); CommonQueryContract setFlushMode(FlushModeType flushMode);
/** /**
* The FlushMode in effect for this query. By default, the query * The {@link FlushMode} in effect for this query. By default, the query
* inherits the FlushMode of the Session from which it originates. * inherits the {@code FlushMode} of the {@link Session} from which it
* originates.
* *
* @see Session#getHibernateFlushMode * @see Session#getHibernateFlushMode
*/ */
FlushMode getHibernateFlushMode(); FlushMode getHibernateFlushMode();
/** /**
* Set the current FlushMode in effect for this query. * Set the current {@link FlushMode} in effect for this query.
* *
* @implNote Setting to {@code null} ultimately indicates to use the * @implNote Setting to {@code null} ultimately indicates to use the
* FlushMode of the Session. Use {@link FlushMode#MANUAL} instead to * {@link FlushMode} of the Session. Use {@link FlushMode#MANUAL}
* indicate that no automatic flushing should occur * instead to indicate that no automatic flushing should occur.
* *
* @see #getHibernateFlushMode() * @see #getHibernateFlushMode()
* @see Session#getHibernateFlushMode() * @see Session#getHibernateFlushMode()
@ -71,8 +75,12 @@ public interface CommonQueryContract {
CommonQueryContract setHibernateFlushMode(FlushMode flushMode); CommonQueryContract setHibernateFlushMode(FlushMode flushMode);
/** /**
* Obtain the query timeout <b>in seconds</b>. This value is eventually passed along to the JDBC query via * Obtain the query timeout <em>in seconds</em>.
* {@link java.sql.Statement#setQueryTimeout(int)}. Zero indicates no timeout. * <p>
* This value is eventually passed along to the JDBC statement via
* {@link java.sql.Statement#setQueryTimeout(int)}.
* <p>
* A value of zero indicates no timeout.
* *
* @see java.sql.Statement#getQueryTimeout() * @see java.sql.Statement#getQueryTimeout()
* @see java.sql.Statement#setQueryTimeout(int) * @see java.sql.Statement#setQueryTimeout(int)
@ -80,12 +88,16 @@ public interface CommonQueryContract {
Integer getTimeout(); Integer getTimeout();
/** /**
* Set the query timeout <b>in seconds</b>. * Set the query timeout <em>in seconds</em>.
* <p>
* Any value set here is eventually passed directly along to the
* {@linkplain java.sql.Statement#setQueryTimeout(int) JDBC
* statement}, which expressly disallows negative values. So
* negative values should be avoided as a general rule.
* <p>
* A value of zero indicates no timeout.
* *
* NOTE it is important to understand that any value set here is eventually passed directly through to the JDBC * @param timeout the timeout <em>in seconds</em>
* Statement which expressly disallows negative values. So negative values should be avoided as a general rule.
*
* @param timeout the timeout <b>in seconds</b>
* *
* @return {@code this}, for method chaining * @return {@code this}, for method chaining
* *
@ -93,36 +105,44 @@ public interface CommonQueryContract {
*/ */
CommonQueryContract setTimeout(int timeout); CommonQueryContract setTimeout(int timeout);
/**
* Get the comment that has been set for this query, if any.
*/
String getComment(); String getComment();
/**
* Set a comment for this query.
*
* @see Query#setComment(String)
*/
CommonQueryContract setComment(String comment); CommonQueryContract setComment(String comment);
/** /**
* Apply hints to the query * Apply hints to the query.
*/ */
CommonQueryContract setHint(String hintName, Object value); CommonQueryContract setHint(String hintName, Object value);
/** /**
* Bind the given argument to a named query parameter * Bind the given argument to a named query parameter.
* <p> * <p>
* If the type of the parameter cannot be inferred from the context in which * If the type of the parameter cannot be inferred from the context in
* it occurs, use one of the forms accept a "type". * which it occurs, use one of the forms which accepts a "type".
* *
* @see #setParameter(String, Object, Class) * @see #setParameter(String, Object, Class)
* @see #setParameter(String, Object, BindableType) * @see #setParameter(String, Object, BindableType)
*/ */
CommonQueryContract setParameter(String name, Object value); CommonQueryContract setParameter(String parameter, Object value);
/** /**
* Bind the given argument to a named query parameter using the given * Bind the given argument to a named query parameter using the given
* Class reference to attempt to determine the {@link BindableType} * {@link Class} reference to attempt to infer the {@link BindableType}.
* to use. If unable to determine an appropriate {@link BindableType}, * If unable to infer an appropriate {@link BindableType}, fall back to
* {@link #setParameter(String, Object)} is used * {@link #setParameter(String, Object)}.
* *
* @see BindableType#parameterType(Class) * @see BindableType#parameterType(Class)
* @see #setParameter(String, Object, BindableType) * @see #setParameter(String, Object, BindableType)
*/ */
<P> CommonQueryContract setParameter(String name, P value, Class<P> type); <P> CommonQueryContract setParameter(String parameter, P value, Class<P> type);
/** /**
* Bind the given argument to a named query parameter using the given * Bind the given argument to a named query parameter using the given
@ -130,76 +150,76 @@ public interface CommonQueryContract {
* *
* @see BindableType#parameterType * @see BindableType#parameterType
*/ */
<P> CommonQueryContract setParameter(String name, P value, BindableType<P> type); <P> CommonQueryContract setParameter(String parameter, P value, BindableType<P> type);
/** /**
* Bind an {@link Instant} value to the named query parameter using just the portion * Bind an {@link Instant} to the named query parameter using just the
* indicated by the given {@link TemporalType}. * portion indicated by the given {@link TemporalType}.
*/ */
CommonQueryContract setParameter(String name, Instant value, TemporalType temporalType); CommonQueryContract setParameter(String parameter, Instant value, TemporalType temporalType);
/** /**
* {@link jakarta.persistence.Query} override * @see jakarta.persistence.Query#setParameter(String, Calendar, TemporalType)
*/ */
CommonQueryContract setParameter(String name, Calendar value, TemporalType temporalType); CommonQueryContract setParameter(String parameter, Calendar value, TemporalType temporalType);
/** /**
* {@link jakarta.persistence.Query} override * @see jakarta.persistence.Query#setParameter(String, Date, TemporalType)
*/ */
CommonQueryContract setParameter(String name, Date value, TemporalType temporalType); CommonQueryContract setParameter(String parameter, Date value, TemporalType temporalType);
/** /**
* Bind the given argument to a positional query parameter. * Bind the given argument to an ordinal query parameter.
* <p> * <p>
* If the type of the parameter cannot be inferred from the context in which * If the type of the parameter cannot be inferred from the context in which
* it occurs, use one of the forms accept a "type". * it occurs, use one of the forms which accepts a "type".
* *
* @see #setParameter(int, Object, Class) * @see #setParameter(int, Object, Class)
* @see #setParameter(int, Object, BindableType) * @see #setParameter(int, Object, BindableType)
*/ */
CommonQueryContract setParameter(int position, Object value); CommonQueryContract setParameter(int parameter, Object value);
/** /**
* Bind the given argument to a positional query parameter using the given * Bind the given argument to an ordinal query parameter using the given
* Class reference to attempt to determine the {@link BindableType} * {@link Class} reference to attempt to infer the {@link BindableType}.
* to use. If unable to determine an appropriate {@link BindableType}, * If unable to infer an appropriate {@link BindableType}, fall back to
* {@link #setParameter(int, Object)} is used * {@link #setParameter(int, Object)}.
* *
* @see BindableType#parameterType(Class) * @see BindableType#parameterType(Class)
* @see #setParameter(int, Object, BindableType) * @see #setParameter(int, Object, BindableType)
*/ */
<P> CommonQueryContract setParameter(int position, P value, Class<P> type); <P> CommonQueryContract setParameter(int parameter, P value, Class<P> type);
/** /**
* Bind the given argument to a positional query parameter using the given * Bind the given argument to an ordinal query parameter using the given
* {@link BindableType}. * {@link BindableType}.
* *
* @see BindableType#parameterType * @see BindableType#parameterType
*/ */
<P> CommonQueryContract setParameter(int position, P value, BindableType<P> type); <P> CommonQueryContract setParameter(int parameter, P value, BindableType<P> type);
/** /**
* Bind an {@link Instant} value to the positional query parameter using just the portion * Bind an {@link Instant} to an ordinal query parameter using just the
* indicated by the given {@link TemporalType}. * portion indicated by the given {@link TemporalType}.
*/ */
CommonQueryContract setParameter(int position, Instant value, TemporalType temporalType); CommonQueryContract setParameter(int parameter, Instant value, TemporalType temporalType);
/** /**
* {@link jakarta.persistence.Query} override * @see jakarta.persistence.Query#setParameter(int, Date, TemporalType)
*/ */
CommonQueryContract setParameter(int position, Date value, TemporalType temporalType); CommonQueryContract setParameter(int parameter, Date value, TemporalType temporalType);
/** /**
* {@link jakarta.persistence.Query} override * @see jakarta.persistence.Query#setParameter(int, Calendar, TemporalType)
*/ */
CommonQueryContract setParameter(int position, Calendar value, TemporalType temporalType); CommonQueryContract setParameter(int parameter, Calendar value, TemporalType temporalType);
/** /**
* Bind an argument to the query parameter represented by the given * Bind an argument to the query parameter represented by the given
* {@link QueryParameter}. * {@link QueryParameter}.
* <p> * <p>
* If the type of the parameter cannot be inferred from the context in which * If the type of the parameter cannot be inferred from the context in which
* it occurs, use on of the forms accept a "type". * it occurs, use one of the forms which accepts a "type".
* *
* @see #setParameter(QueryParameter, Object, BindableType) * @see #setParameter(QueryParameter, Object, BindableType)
* *
@ -212,9 +232,9 @@ public interface CommonQueryContract {
/** /**
* Bind an argument to the query parameter represented by the given * Bind an argument to the query parameter represented by the given
* {@link QueryParameter} using the given Class reference to attempt to * {@link QueryParameter}, using the given {@link Class} reference to attempt
* determine the {@link BindableType} to use. If unable to determine * to infer the {@link BindableType} to use. If unable to infer an appropriate
* an appropriate {@link BindableType}, {@link #setParameter(QueryParameter, Object)} is used * {@link BindableType}, fall back to {@link #setParameter(QueryParameter, Object)}.
* *
* @param parameter the query parameter memento * @param parameter the query parameter memento
* @param value the argument, which might be null * @param value the argument, which might be null
@ -229,28 +249,28 @@ public interface CommonQueryContract {
/** /**
* Bind an argument to the query parameter represented by the given * Bind an argument to the query parameter represented by the given
* {@link QueryParameter} using the given {@link BindableType}. * {@link QueryParameter}, using the given {@link BindableType}.
* *
* @param parameter the query parameter memento * @param parameter the query parameter memento
* @param val the argument, which might be null * @param val the argument, which might be null
* @param type an {@link BindableType} representing the type of the parameter * @param type a {@link BindableType} representing the type of the parameter
* *
* @return {@code this}, for method chaining * @return {@code this}, for method chaining
*/ */
<P> CommonQueryContract setParameter(QueryParameter<P> parameter, P val, BindableType<P> type); <P> CommonQueryContract setParameter(QueryParameter<P> parameter, P val, BindableType<P> type);
/** /**
* {@link jakarta.persistence.Query} override * @see jakarta.persistence.Query#setParameter(Parameter, Object)
*/ */
<T> CommonQueryContract setParameter(Parameter<T> param, T value); <T> CommonQueryContract setParameter(Parameter<T> param, T value);
/** /**
* {@link jakarta.persistence.Query} override * @see jakarta.persistence.Query#setParameter(Parameter, Calendar, TemporalType)
*/ */
CommonQueryContract setParameter(Parameter<Calendar> param, Calendar value, TemporalType temporalType); CommonQueryContract setParameter(Parameter<Calendar> param, Calendar value, TemporalType temporalType);
/** /**
* {@link jakarta.persistence.Query} override * @see jakarta.persistence.Query#setParameter(Parameter, Date, TemporalType)
*/ */
CommonQueryContract setParameter(Parameter<Date> param, Date value, TemporalType temporalType); CommonQueryContract setParameter(Parameter<Date> param, Date value, TemporalType temporalType);
@ -258,39 +278,43 @@ public interface CommonQueryContract {
* Bind multiple arguments to a named query parameter. * Bind multiple arguments to a named query parameter.
* <p/> * <p/>
* The "type mapping" for the binding is inferred from the type of * The "type mapping" for the binding is inferred from the type of
* the first collection element * the first collection element.
* *
* @see #setParameterList(java.lang.String, java.util.Collection, BindableType) * @see #setParameterList(java.lang.String, java.util.Collection, BindableType)
* *
* @apiNote This is used for binding a list of values to an expression such as {@code entity.field in (:values)}. * @apiNote This is used for binding a list of values to an expression
* such as {@code entity.field in (:values)}.
* *
* @return {@code this}, for method chaining * @return {@code this}, for method chaining
*/ */
CommonQueryContract setParameterList(String name, @SuppressWarnings("rawtypes") Collection values); CommonQueryContract setParameterList(String parameter, @SuppressWarnings("rawtypes") Collection values);
/** /**
* Bind multiple arguments to a named query parameter using the given * Bind multiple arguments to a named query parameter using the given
* Class reference to attempt to determine the {@link BindableType} * {@link Class} reference to attempt to infer the {@link BindableType}
* to use. If unable to determine an appropriate {@link BindableType}, * If unable to infer an appropriate {@link BindableType}, fall back to
* {@link #setParameterList(String, Collection)} is used * {@link #setParameterList(String, Collection)}.
* *
* @see BindableType#parameterType(Class) * @see BindableType#parameterType(Class)
* @see #setParameterList(java.lang.String, java.util.Collection, BindableType) * @see #setParameterList(java.lang.String, java.util.Collection, BindableType)
* *
* @apiNote This is used for binding a list of values to an expression such as {@code entity.field in (:values)}. * @apiNote This is used for binding a list of values to an expression
* such as {@code entity.field in (:values)}.
* *
* @return {@code this}, for method chaining * @return {@code this}, for method chaining
*/ */
<P> CommonQueryContract setParameterList(String name, Collection<? extends P> values, Class<P> javaType); <P> CommonQueryContract setParameterList(String parameter, Collection<? extends P> values, Class<P> javaType);
/** /**
* Bind multiple arguments to a named query parameter using the passed type-mapping. * Bind multiple arguments to a named query parameter using the given
* {@link BindableType}.
* *
* @apiNote This is used for binding a list of values to an expression such as {@code entity.field in (:values)}. * @apiNote This is used for binding a list of values to an expression
* such as {@code entity.field in (:values)}.
* *
* @return {@code this}, for method chaining * @return {@code this}, for method chaining
*/ */
<P> CommonQueryContract setParameterList(String name, Collection<? extends P> values, BindableType<P> type); <P> CommonQueryContract setParameterList(String parameter, Collection<? extends P> values, BindableType<P> type);
/** /**
@ -299,11 +323,12 @@ public interface CommonQueryContract {
* The "type mapping" for the binding is inferred from the type of * The "type mapping" for the binding is inferred from the type of
* the first collection element * the first collection element
* *
* @apiNote This is used for binding a list of values to an expression such as {@code entity.field in (:values)}. * @apiNote This is used for binding a list of values to an expression
* such as {@code entity.field in (:values)}.
* *
* @return {@code this}, for method chaining * @return {@code this}, for method chaining
*/ */
CommonQueryContract setParameterList(String name, Object[] values); CommonQueryContract setParameterList(String parameter, Object[] values);
/** /**
* Bind multiple arguments to a named query parameter using the given * Bind multiple arguments to a named query parameter using the given
@ -314,93 +339,104 @@ public interface CommonQueryContract {
* @see BindableType#parameterType(Class) * @see BindableType#parameterType(Class)
* @see #setParameterList(java.lang.String, Object[], BindableType) * @see #setParameterList(java.lang.String, Object[], BindableType)
* *
* @apiNote This is used for binding a list of values to an expression such as {@code entity.field in (:values)}. * @apiNote This is used for binding a list of values to an expression
* such as {@code entity.field in (:values)}.
* *
* @return {@code this}, for method chaining * @return {@code this}, for method chaining
*/ */
<P> CommonQueryContract setParameterList(String name, P[] values, Class<P> javaType); <P> CommonQueryContract setParameterList(String parameter, P[] values, Class<P> javaType);
/** /**
* Bind multiple arguments to a named query parameter using the passed type-mapping. * Bind multiple arguments to a named query parameter using the given
* {@link BindableType}.
* *
* @apiNote This is used for binding a list of values to an expression such as {@code entity.field in (:values)}. * @apiNote This is used for binding a list of values to an expression
* such as {@code entity.field in (:values)}.
* *
* @return {@code this}, for method chaining * @return {@code this}, for method chaining
*/ */
<P> CommonQueryContract setParameterList(String name, P[] values, BindableType<P> type); <P> CommonQueryContract setParameterList(String parameter, P[] values, BindableType<P> type);
/** /**
* Bind multiple arguments to a positional query parameter. * Bind multiple arguments to an ordinal query parameter.
* <p/> * <p/>
* The "type mapping" for the binding is inferred from the type of * The "type mapping" for the binding is inferred from the type of
* the first collection element * the first collection element
* *
* @apiNote This is used for binding a list of values to an expression such as {@code entity.field in (:values)}. * @apiNote This is used for binding a list of values to an expression
* such as {@code entity.field in (:values)}.
* *
* @return {@code this}, for method chaining * @return {@code this}, for method chaining
*/ */
CommonQueryContract setParameterList(int position, @SuppressWarnings("rawtypes") Collection values); CommonQueryContract setParameterList(int parameter, @SuppressWarnings("rawtypes") Collection values);
/** /**
* Bind multiple arguments to a positional query parameter using the given * Bind multiple arguments to an ordinal query parameter using the given
* Class reference to attempt to determine the {@link BindableType} * {@link Class} reference to attempt to infer the {@link BindableType}.
* to use. If unable to determine an appropriate {@link BindableType}, * If unable to infer an appropriate {@link BindableType}, fall back to
* {@link #setParameterList(String, Collection)} is used * {@link #setParameterList(String, Collection)}.
* *
* @see BindableType#parameterType(Class) * @see BindableType#parameterType(Class)
* @see #setParameterList(int, Collection, BindableType) * @see #setParameterList(int, Collection, BindableType)
* *
* @apiNote This is used for binding a list of values to an expression such as {@code entity.field in (:values)}. * @apiNote This is used for binding a list of values to an expression
* such as {@code entity.field in (:values)}.
* *
* @return {@code this}, for method chaining * @return {@code this}, for method chaining
*/ */
<P> CommonQueryContract setParameterList(int position, Collection<? extends P> values, Class<P> javaType); <P> CommonQueryContract setParameterList(int parameter, Collection<? extends P> values, Class<P> javaType);
/** /**
* Bind multiple arguments to a positional query parameter using the passed type-mapping. * Bind multiple arguments to an ordinal query parameter using the given
* {@link BindableType}.
* *
* @apiNote This is used for binding a list of values to an expression such as {@code entity.field in (:values)}. * @apiNote This is used for binding a list of values to an expression
* such as {@code entity.field in (:values)}.
* *
* @return {@code this}, for method chaining * @return {@code this}, for method chaining
*/ */
<P> CommonQueryContract setParameterList(int position, Collection<? extends P> values, BindableType<P> type); <P> CommonQueryContract setParameterList(int parameter, Collection<? extends P> values, BindableType<P> type);
/** /**
* Bind multiple arguments to a positional query parameter. * Bind multiple arguments to an ordinal query parameter.
* <p/> * <p/>
* The "type mapping" for the binding is inferred from the type of * The "type mapping" for the binding is inferred from the type of
* the first collection element * the first collection element
* *
* @apiNote This is used for binding a list of values to an expression such as {@code entity.field in (:values)}. * @apiNote This is used for binding a list of values to an expression
* such as {@code entity.field in (:values)}.
* *
* @return {@code this}, for method chaining * @return {@code this}, for method chaining
*/ */
CommonQueryContract setParameterList(int position, Object[] values); CommonQueryContract setParameterList(int parameter, Object[] values);
/** /**
* Bind multiple arguments to a positional query parameter using the given * Bind multiple arguments to an ordinal query parameter using the given
* Class reference to attempt to determine the {@link BindableType} * {@link Class} reference to attempt to infer the {@link BindableType}.
* to use. If unable to determine an appropriate {@link BindableType}, * If unable to infer an appropriate {@link BindableType}, fall back to
* {@link #setParameterList(String, Collection)} is used * {@link #setParameterList(String, Collection)}.
* *
* @see BindableType#parameterType(Class) * @see BindableType#parameterType(Class)
* @see #setParameterList(int, Object[], BindableType) * @see #setParameterList(int, Object[], BindableType)
* *
* @apiNote This is used for binding a list of values to an expression such as {@code entity.field in (:values)}. * @apiNote This is used for binding a list of values to an expression
* such as {@code entity.field in (:values)}.
* *
* @return {@code this}, for method chaining * @return {@code this}, for method chaining
*/ */
<P> CommonQueryContract setParameterList(int position, P[] values, Class<P> javaType); <P> CommonQueryContract setParameterList(int parameter, P[] values, Class<P> javaType);
/** /**
* Bind multiple arguments to a positional query parameter using the passed type-mapping. * Bind multiple arguments to an ordinal query parameter using the given
* {@link BindableType}.
* *
* @apiNote This is used for binding a list of values to an expression such as {@code entity.field in (:values)}. * @apiNote This is used for binding a list of values to an expression
* such as {@code entity.field in (:values)}.
* *
* @return {@code this}, for method chaining * @return {@code this}, for method chaining
*/ */
<P> CommonQueryContract setParameterList(int position, P[] values, BindableType<P> type); <P> CommonQueryContract setParameterList(int parameter, P[] values, BindableType<P> type);
/** /**
* Bind multiple arguments to the query parameter represented by the * Bind multiple arguments to the query parameter represented by the
@ -418,15 +454,16 @@ public interface CommonQueryContract {
/** /**
* Bind multiple arguments to the query parameter represented by the * Bind multiple arguments to the query parameter represented by the
* given {@link QueryParameter} using the given Class reference to attempt * given {@link QueryParameter} using the given {@link Class} reference
* to determine the {@link BindableType} to use. If unable to * to attempt to infer the {@link BindableType} to use. If unable to
* determine an appropriate {@link BindableType}, * infer an appropriate {@link BindableType}, fall back to using
* {@link #setParameterList(String, Collection)} is used * {@link #setParameterList(String, Collection)}.
* *
* @see BindableType#parameterType(Class) * @see BindableType#parameterType(Class)
* @see #setParameterList(QueryParameter, java.util.Collection, BindableType) * @see #setParameterList(QueryParameter, java.util.Collection, BindableType)
* *
* @apiNote This is used for binding a list of values to an expression such as {@code entity.field in (:values)}. * @apiNote This is used for binding a list of values to an expression
* such as {@code entity.field in (:values)}.
* *
* @return {@code this}, for method chaining * @return {@code this}, for method chaining
*/ */
@ -434,14 +471,10 @@ public interface CommonQueryContract {
/** /**
* Bind multiple arguments to the query parameter represented by the * Bind multiple arguments to the query parameter represented by the
* given {@link QueryParameter}, inferring the {@link BindableType}. * given {@link QueryParameter}, using the given {@link BindableType}.
* *
* Bind multiple arguments to a named query parameter. * @apiNote This is used for binding a list of values to an expression
* <p/> * such as {@code entity.field in (:values)}.
* The "type mapping" for the binding is inferred from the type of
* the first collection element
*
* @apiNote This is used for binding a list of values to an expression such as {@code entity.field in (:values)}.
* *
* @return {@code this}, for method chaining * @return {@code this}, for method chaining
*/ */
@ -449,11 +482,11 @@ public interface CommonQueryContract {
/** /**
* Bind multiple arguments to the query parameter represented by the * Bind multiple arguments to the query parameter represented by the
* given {@link QueryParameter} * given {@link QueryParameter}.
* <p> * <p>
* The type of the parameter is inferred between the context in which it * The type of the parameter is inferred between the context in which it
* occurs, the type associated with the QueryParameter and the type of * occurs, the type associated with the {@code QueryParameter} and the
* the first given argument. * type of the first given argument.
* *
* @param parameter the parameter memento * @param parameter the parameter memento
* @param values a collection of arguments * @param values a collection of arguments
@ -464,15 +497,16 @@ public interface CommonQueryContract {
/** /**
* Bind multiple arguments to the query parameter represented by the * Bind multiple arguments to the query parameter represented by the
* given {@link QueryParameter} using the given Class reference to attempt * given {@link QueryParameter} using the given {@link Class} reference
* to determine the {@link BindableType} to use. If unable to * to attempt to infer the {@link BindableType} to use. If unable to
* determine an appropriate {@link BindableType}, * infer an appropriate {@link BindableType}, fall back to using
* {@link #setParameterList(String, Collection)} is used * {@link #setParameterList(String, Collection)}.
* *
* @see BindableType#parameterType(Class) * @see BindableType#parameterType(Class)
* @see #setParameterList(QueryParameter, Object[], BindableType) * @see #setParameterList(QueryParameter, Object[], BindableType)
* *
* @apiNote This is used for binding a list of values to an expression such as {@code entity.field in (:values)}. * @apiNote This is used for binding a list of values to an expression
* such as {@code entity.field in (:values)}.
* *
* @return {@code this}, for method chaining * @return {@code this}, for method chaining
*/ */
@ -480,23 +514,19 @@ public interface CommonQueryContract {
/** /**
* Bind multiple arguments to the query parameter represented by the * Bind multiple arguments to the query parameter represented by the
* given {@link QueryParameter}, inferring the {@link BindableType}. * given {@link QueryParameter}, using the given the {@link BindableType}.
* *
* Bind multiple arguments to a named query parameter. * @apiNote This is used for binding a list of values to an expression
* <p/> * such as {@code entity.field in (:values)}.
* The "type mapping" for the binding is inferred from the type of
* the first collection element
*
* @apiNote This is used for binding a list of values to an expression such as {@code entity.field in (:values)}.
* *
* @return {@code this}, for method chaining * @return {@code this}, for method chaining
*/ */
<P> CommonQueryContract setParameterList(QueryParameter<P> parameter, P[] values, BindableType<P> type); <P> CommonQueryContract setParameterList(QueryParameter<P> parameter, P[] values, BindableType<P> type);
/** /**
* Bind the property values of the given bean to named parameters of the query, * Bind the property values of the given bean to named parameters of
* matching property names with parameter names and mapping property types to * the query, matching property names with parameter names and mapping
* Hibernate types using heuristics. * property types to Hibernate types using heuristics.
* *
* @param bean any JavaBean or POJO * @param bean any JavaBean or POJO
* *
@ -505,9 +535,9 @@ public interface CommonQueryContract {
CommonQueryContract setProperties(Object bean); CommonQueryContract setProperties(Object bean);
/** /**
* Bind the values of the given {@code Map} to named parameters of the query, * Bind the values of the given {@code Map} to named parameters of the
* matching key names with parameter names and mapping value types to Hibernate * query, matching key names with parameter names and mapping value types
* types using heuristics. * to Hibernate types using heuristics.
* *
* @param bean a {@link Map} of names to arguments * @param bean a {@link Map} of names to arguments
* *