/*
 * Hibernate, Relational Persistence for Idiomatic Java
 *
 * 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>.
 */
package org.hibernate;

import java.io.Serializable;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.util.Calendar;
import java.util.Collection;
import java.util.Date;
import java.util.Iterator;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import javax.persistence.FlushModeType;
import javax.persistence.LockModeType;
import javax.persistence.Parameter;
import javax.persistence.TemporalType;
import javax.persistence.TypedQuery;

import org.hibernate.query.CommonQueryContract;
import org.hibernate.query.ParameterMetadata;
import org.hibernate.query.QueryParameter;
import org.hibernate.transform.ResultTransformer;
import org.hibernate.type.BigDecimalType;
import org.hibernate.type.BigIntegerType;
import org.hibernate.type.BinaryType;
import org.hibernate.type.BooleanType;
import org.hibernate.type.ByteType;
import org.hibernate.type.CharacterType;
import org.hibernate.type.DateType;
import org.hibernate.type.DoubleType;
import org.hibernate.type.FloatType;
import org.hibernate.type.IntegerType;
import org.hibernate.type.LocaleType;
import org.hibernate.type.LongType;
import org.hibernate.type.ShortType;
import org.hibernate.type.StringType;
import org.hibernate.type.TextType;
import org.hibernate.type.TimeType;
import org.hibernate.type.TimestampType;
import org.hibernate.type.Type;

Represents an HQL/JPQL query or a compiled Criteria query
Author:
Gavin King, Steve Ebersole
Deprecated:
(since 5.2) use Query instead/**
 * Represents an HQL/JPQL query or a compiled Criteria query
 *
 * @author Gavin King
 * @author Steve Ebersole
 *
 * @deprecated (since 5.2) use {@link org.hibernate.query.Query} instead
 */
@Deprecated
@SuppressWarnings("UnusedDeclaration")
public interface Query<R> extends TypedQuery<R>, CommonQueryContract {

	
Get the query string.
Returns:
the query string/**
	 * Get the query string.
	 *
	 * @return the query string
	 */
	String getQueryString();

	
Obtain the FlushMode in effect for this query.  By default, the query inherits the FlushMode of the Session
from which it originates.
See Also:
FlushMode
Returns:
The query FlushMode./**
	 * Obtain the FlushMode in effect for this query.  By default, the query inherits the FlushMode of the Session
	 * from which it originates.
	 *
	 * @return The query FlushMode.
	 *
	 * @see FlushMode
	 */
	FlushMode getHibernateFlushMode();

	
(Re)set the current FlushMode in effect for this query.
Params:
flushMode – The new FlushMode to use.
See Also:
getHibernateFlushMode()
Returns:
this, for method chaining/**
	 * (Re)set the current FlushMode in effect for this query.
	 *
	 * @param flushMode The new FlushMode to use.
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @see #getHibernateFlushMode()
	 */
	@SuppressWarnings("unchecked")
	default Query<R> setHibernateFlushMode(FlushMode flushMode) {
		setFlushMode( flushMode );
		return this;
	}

	
(Re)set the current FlushMode in effect for this query.
Params:
flushMode – The new FlushMode to use.
See Also:
getHibernateFlushMode()
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setHibernateFlushMode instead/**
	 * (Re)set the current FlushMode in effect for this query.
	 *
	 * @param flushMode The new FlushMode to use.
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @see #getHibernateFlushMode()
	 *
	 * @deprecated (since 5.2) use {@link #setHibernateFlushMode} instead
	 */
	@Deprecated
	Query<R> setFlushMode(FlushMode flushMode);

	
For users of the Hibernate native APIs, we've had to rename this method as defined by Hibernate historically because the JPA contract defines a method of the same name, but returning the JPA FlushModeType rather than Hibernate's FlushMode. For the former behavior, use Query.getHibernateFlushMode() instead. 
Returns:
The FlushModeType in effect for this query./**
	 * For users of the Hibernate native APIs, we've had to rename this method
	 * as defined by Hibernate historically because the JPA contract defines a method of the same
	 * name, but returning the JPA {@link FlushModeType} rather than Hibernate's {@link FlushMode}.  For
	 * the former behavior, use {@link org.hibernate.query.Query#getHibernateFlushMode()} instead.
	 *
	 * @return The FlushModeType in effect for this query.
	 */
	FlushModeType getFlushMode();

	
Obtain the CacheMode in effect for this query.  By default, the query inherits the CacheMode of the Session
from which is originates.
NOTE: The CacheMode here only effects reading/writing of the query cache, not the
entity/collection caches.
See Also:
Session.getCacheMode()
CacheMode
Returns:
The query CacheMode./**
	 * Obtain the CacheMode in effect for this query.  By default, the query inherits the CacheMode of the Session
	 * from which is originates.
	 *
	 * NOTE: The CacheMode here only effects reading/writing of the query cache, not the
	 * entity/collection caches.
	 *
	 * @return The query CacheMode.
	 *
	 * @see Session#getCacheMode()
	 * @see CacheMode
	 */
	CacheMode getCacheMode();

	
(Re)set the current CacheMode in effect for this query.
Params:
cacheMode – The new CacheMode to use.
See Also:
getCacheMode()
Returns:
this, for method chaining/**
	 * (Re)set the current CacheMode in effect for this query.
	 *
	 * @param cacheMode The new CacheMode to use.
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @see #getCacheMode()
	 */
	Query<R> setCacheMode(CacheMode cacheMode);

	
Are the results of this query eligible for second level query caching? This is different that second level caching of any returned entities and collections. NOTE: the query being "eligible" for caching does not necessarily mean its results will be cached. Second level query caching still has to be enabled on the SessionFactory for this to happen. Usually that is controlled by the hibernate.cache.use_query_cache configuration setting. 
See Also:
AvailableSettings.USE_QUERY_CACHE
Returns:
true if the query results are eligible for caching, false otherwise./**
	 * Are the results of this query eligible for second level query caching?  This is different that second level
	 * caching of any returned entities and collections.
	 *
	 * NOTE: the query being "eligible" for caching does not necessarily mean its results will be cached.  Second level
	 * query caching still has to be enabled on the {@link SessionFactory} for this to happen.  Usually that is
	 * controlled by the {@code hibernate.cache.use_query_cache} configuration setting.
	 *
	 * @return {@code true} if the query results are eligible for caching, {@code false} otherwise.
	 *
	 * @see org.hibernate.cfg.AvailableSettings#USE_QUERY_CACHE
	 */
	boolean isCacheable();

	
Enable/disable second level query (result) caching for this query.
Params:
cacheable – Should the query results be cacheable?
See Also:
isCacheable
Returns:
this, for method chaining/**
	 * Enable/disable second level query (result) caching for this query.
	 *
	 * @param cacheable Should the query results be cacheable?
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @see #isCacheable
	 */
	Query<R> setCacheable(boolean cacheable);

	
Obtain the name of the second level query cache region in which query results will be stored (if they are cached, see the discussion on isCacheable() for more information). null indicates that the default region should be used. 
Returns:
The specified cache region name into which query results should be placed; null indicates the default region./**
	 * Obtain the name of the second level query cache region in which query results will be stored (if they are
	 * cached, see the discussion on {@link #isCacheable()} for more information).  {@code null} indicates that the
	 * default region should be used.
	 *
	 * @return The specified cache region name into which query results should be placed; {@code null} indicates
	 * the default region.
	 */
	String getCacheRegion();

	
Set the name of the cache region where query results should be cached (if cached at all).
Params:
cacheRegion – the name of a query cache region, or null to indicate that the default region should be used.
See Also:
getCacheRegion()
Returns:
this, for method chaining/**
	 * Set the name of the cache region where query results should be cached (if cached at all).
	 *
	 * @param cacheRegion the name of a query cache region, or {@code null} to indicate that the default region
	 * should be used.
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @see #getCacheRegion()
	 */
	Query<R> setCacheRegion(String cacheRegion);

	
Obtain the query timeout in seconds. This value is eventually passed along to the JDBC query via Statement.setQueryTimeout(int). Zero indicates no timeout. 
See Also:
Statement.getQueryTimeout()
Statement.setQueryTimeout(int)
Returns:
The timeout in seconds/**
	 * Obtain the query timeout <b>in seconds</b>.  This value is eventually passed along to the JDBC query via
	 * {@link java.sql.Statement#setQueryTimeout(int)}.  Zero indicates no timeout.
	 *
	 * @return The timeout <b>in seconds</b>
	 *
	 * @see java.sql.Statement#getQueryTimeout()
	 * @see java.sql.Statement#setQueryTimeout(int)
	 */
	Integer getTimeout();

	
Set the query timeout in seconds.
NOTE it is important to understand that any value set here is eventually passed directly through to the JDBC
Statement which expressly disallows negative values.  So negative values should be avoided as a general rule.
Params:
timeout – the timeout in seconds
See Also:
getTimeout()
Returns:
this, for method chaining/**
	 * Set the query timeout <b>in seconds</b>.
	 *
	 * NOTE it is important to understand that any value set here is eventually passed directly through to the JDBC
	 * 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
	 *
	 * @see #getTimeout()
	 */
	Query<R> setTimeout(int timeout);

	
Obtain the JDBC fetch size hint in effect for this query. This value is eventually passed along to the JDBC query via Statement.setFetchSize(int). As defined b y JDBC, this value is a hint to the driver to indicate how many rows to fetch from the database when more rows are needed. NOTE : JDBC expressly defines this value as a hint. It may or may not have any effect on the actual query execution and ResultSet processing depending on the driver. 
See Also:
Statement.getFetchSize()
Statement.setFetchSize(int)
Returns:
The timeout in seconds/**
	 * Obtain the JDBC fetch size hint in effect for this query.  This value is eventually passed along to the JDBC
	 * query via {@link java.sql.Statement#setFetchSize(int)}.  As defined b y JDBC, this value is a hint to the
	 * driver to indicate how many rows to fetch from the database when more rows are needed.
	 *
	 * NOTE : JDBC expressly defines this value as a hint.  It may or may not have any effect on the actual
	 * query execution and ResultSet processing depending on the driver.
	 *
	 * @return The timeout <b>in seconds</b>
	 *
	 * @see java.sql.Statement#getFetchSize()
	 * @see java.sql.Statement#setFetchSize(int)
	 */
	Integer getFetchSize();

	
Sets a JDBC fetch size hint for the query.
Params:
fetchSize – the fetch size hint
See Also:
getFetchSize()
Returns:
this, for method chaining/**
	 * Sets a JDBC fetch size hint for the query.
	 *
	 * @param fetchSize the fetch size hint
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @see #getFetchSize()
	 */
	Query<R> setFetchSize(int fetchSize);

	
Should entities and proxies loaded by this Query be put in read-only mode? If the
read-only/modifiable setting was not initialized, then the default
read-only/modifiable setting for the persistence context is returned instead.
See Also:
setReadOnly(boolean)

The read-only/modifiable setting has no impact on entities/proxies returned by the
query that existed in the session before the query was executed.
Returns:
true if the entities and proxies loaded by the query will be put in read-only mode; false otherwise (they will be modifiable)/**
	 * Should entities and proxies loaded by this Query be put in read-only mode? If the
	 * read-only/modifiable setting was not initialized, then the default
	 * read-only/modifiable setting for the persistence context is returned instead.
	 *
	 * @see #setReadOnly(boolean)
	 * @see org.hibernate.engine.spi.PersistenceContext#isDefaultReadOnly()
	 *
	 * The read-only/modifiable setting has no impact on entities/proxies returned by the
	 * query that existed in the session before the query was executed.
	 *
	 * @return {@code true} if the entities and proxies loaded by the query will be put
	 * in read-only mode; {@code false} otherwise (they will be modifiable)
	 */
	boolean isReadOnly();

	
Set the read-only/modifiable mode for entities and proxies
loaded by this Query. This setting overrides the default setting
for the persistence context.
Params:
readOnly – true indicates that entities and proxies loaded by the query are to be put in read-only mode; false indicates that entities and proxies loaded by the query will be put in modifiable mode
See Also:

To set the default read-only/modifiable setting used for
entities and proxies that are loaded into the session:
PersistenceContext.setDefaultReadOnly(boolean)

Read-only entities are not dirty-checked and snapshots of persistent
state are not maintained. Read-only entities can be modified, but
changes are not persisted.
When a proxy is initialized, the loaded entity will have the same
read-only/modifiable setting as the uninitialized
proxy has, regardless of the session's current setting.
The read-only/modifiable setting has no impact on entities/proxies
returned by the query that existed in the session before the query was executed.
Returns:
this, for method chaining/**
	 * Set the read-only/modifiable mode for entities and proxies
	 * loaded by this Query. This setting overrides the default setting
	 * for the persistence context.
	 * @see org.hibernate.engine.spi.PersistenceContext#isDefaultReadOnly()
	 *
	 * To set the default read-only/modifiable setting used for
	 * entities and proxies that are loaded into the session:
	 * @see org.hibernate.engine.spi.PersistenceContext#setDefaultReadOnly(boolean)
	 * @see Session#setDefaultReadOnly(boolean)
	 *
	 * Read-only entities are not dirty-checked and snapshots of persistent
	 * state are not maintained. Read-only entities can be modified, but
	 * changes are not persisted.
	 *
	 * When a proxy is initialized, the loaded entity will have the same
	 * read-only/modifiable setting as the uninitialized
	 * proxy has, regardless of the session's current setting.
	 *
	 * The read-only/modifiable setting has no impact on entities/proxies
	 * returned by the query that existed in the session before the query was executed.
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @param readOnly {@code true} indicates that entities and proxies loaded by the query
	 * are to be put in read-only mode; {@code false} indicates that entities and proxies
	 * loaded by the query will be put in modifiable mode
	 */
	Query<R> setReadOnly(boolean readOnly);

	
Return the Hibernate types of the query results.
Returns:
an array of types
Deprecated:
(since 5.2) with no replacement; to be removed in 6.0/**
	 * Return the Hibernate types of the query results.
	 *
	 * @return an array of types
	 *
	 * @deprecated (since 5.2) with no replacement; to be removed in 6.0
	 */
	@Deprecated
	Type[] getReturnTypes();

	
Obtains the LockOptions in effect for this query.
See Also:
LockOptions
Returns:
The LockOptions/**
	 * Obtains the LockOptions in effect for this query.
	 *
	 * @return The LockOptions
	 *
	 * @see LockOptions
	 */
	LockOptions getLockOptions();

	
Set the lock options for the query.  Specifically only the following are taken into consideration:

    
LockOptions.getLockMode()
    
LockOptions.getScope()
    
LockOptions.getTimeOut()
 For alias-specific locking, use setLockMode(String, LockMode). 
Params:
lockOptions – The lock options to apply to the query.
See Also:
getLockOptions()
Returns:
this, for method chaining/**
	 * Set the lock options for the query.  Specifically only the following are taken into consideration:<ol>
	 *     <li>{@link LockOptions#getLockMode()}</li>
	 *     <li>{@link LockOptions#getScope()}</li>
	 *     <li>{@link LockOptions#getTimeOut()}</li>
	 * </ol>
	 * For alias-specific locking, use {@link #setLockMode(String, LockMode)}.
	 *
	 * @param lockOptions The lock options to apply to the query.
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @see #getLockOptions()
	 */
	Query<R> setLockOptions(LockOptions lockOptions);

	
Set the LockMode to use for specific alias (as defined in the query's FROM clause). The alias-specific lock modes specified here are added to the query's internal LockOptions. The effect of these alias-specific LockModes is somewhat dependent on the driver/database in use. Generally speaking, for maximum portability, this method should only be used to mark that the rows corresponding to the given alias should be included in pessimistic locking (LockMode.PESSIMISTIC_WRITE). 
Params:
alias – a query alias, or "this" for a collection filter
lockMode – The lock mode to apply.
See Also:
getLockOptions()
Returns:
this, for method chaining/**
	 * Set the LockMode to use for specific alias (as defined in the query's <tt>FROM</tt> clause).
	 *
	 * The alias-specific lock modes specified here are added to the query's internal
	 * {@link #getLockOptions() LockOptions}.
	 *
	 * The effect of these alias-specific LockModes is somewhat dependent on the driver/database in use.  Generally
	 * speaking, for maximum portability, this method should only be used to mark that the rows corresponding to
	 * the given alias should be included in pessimistic locking ({@link LockMode#PESSIMISTIC_WRITE}).
	 *
	 * @param alias a query alias, or {@code "this"} for a collection filter
	 * @param lockMode The lock mode to apply.
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @see #getLockOptions()
	 */
	Query<R> setLockMode(String alias, LockMode lockMode);

	
Obtain the comment currently associated with this query. Provided SQL commenting is enabled (generally by enabling the hibernate.use_sql_comments config setting), this comment will also be added to the SQL query sent to the database. Often useful for identifying the source of troublesome queries on the database side. 
Returns:
The comment./**
	 * Obtain the comment currently associated with this query.  Provided SQL commenting is enabled
	 * (generally by enabling the {@code hibernate.use_sql_comments} config setting), this comment will also be added
	 * to the SQL query sent to the database.  Often useful for identifying the source of troublesome queries on the
	 * database side.
	 *
	 * @return The comment.
	 */
	String getComment();

	
Set the comment for this query.
Params:
comment – The human-readable comment
See Also:
getComment()
Returns:
this, for method chaining/**
	 * Set the comment for this query.
	 *
	 * @param comment The human-readable comment
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @see #getComment()
	 */
	Query<R> setComment(String comment);

	
Add a DB query hint to the SQL. These differ from JPA's QueryHint, which is specific to the JPA implementation and ignores DB vendor-specific hints. Instead, these are intended solely for the vendor-specific hints, such as Oracle's optimizers. Multiple query hints are supported; the Dialect will determine concatenation and placement. 
Params:
hint – The database specific query hint to add./**
	 * Add a DB query hint to the SQL.  These differ from JPA's {@link javax.persistence.QueryHint}, which is specific
	 * to the JPA implementation and ignores DB vendor-specific hints.  Instead, these are intended solely for the
	 * vendor-specific hints, such as Oracle's optimizers.  Multiple query hints are supported; the Dialect will
	 * determine concatenation and placement.
	 *
	 * @param hint The database specific query hint to add.
	 */
	Query<R> addQueryHint(String hint);

	
Return the query results as an Iterator. If the query
contains multiple results per row, the results are returned in
an instance of Object[].



Entities returned as results are initialized on demand. The first
SQL query returns identifiers only.

Returns:
the result iterator/**
	 * Return the query results as an <tt>Iterator</tt>. If the query
	 * contains multiple results per row, the results are returned in
	 * an instance of <tt>Object[]</tt>.<br>
	 * <br>
	 * Entities returned as results are initialized on demand. The first
	 * SQL query returns identifiers only.<br>
	 *
	 * @return the result iterator
	 */
	Iterator<R> iterate();

	
Return the query results as ScrollableResults. The
scrollability of the returned results depends upon JDBC driver
support for scrollable ResultSets.
 You should call ScrollableResults.close() after processing the ScrollableResults
so that the underlying resources are deallocated right away.
See Also:
ScrollableResults
Returns:
the result iterator/**
	 * Return the query results as <tt>ScrollableResults</tt>. The
	 * scrollability of the returned results depends upon JDBC driver
	 * support for scrollable <tt>ResultSet</tt>s.
	 *
	 * <p>
	 *
	 * You should call {@link ScrollableResults#close()} after processing the <tt>ScrollableResults</tt>
	 * so that the underlying resources are deallocated right away.
	 *
	 * @see ScrollableResults
	 *
	 * @return the result iterator
	 */
	ScrollableResults scroll();

	
Return the query results as ScrollableResults. The scrollability of the returned results
depends upon JDBC driver support for scrollable ResultSets.
 You should call ScrollableResults.close() after processing the ScrollableResults
so that the underlying resources are deallocated right away.
Params:
scrollMode – The scroll mode
See Also:
ScrollableResults
ScrollMode
Returns:
the result iterator/**
	 * Return the query results as ScrollableResults. The scrollability of the returned results
	 * depends upon JDBC driver support for scrollable ResultSets.
	 *
	 * <p>
	 *
	 * You should call {@link ScrollableResults#close()} after processing the <tt>ScrollableResults</tt>
	 * so that the underlying resources are deallocated right away.
	 *
	 * @param scrollMode The scroll mode
	 *
	 * @return the result iterator
	 *
	 * @see ScrollableResults
	 * @see ScrollMode
	 *
	 */
	ScrollableResults scroll(ScrollMode scrollMode);

	
Return the query results as a List. If the query contains
multiple results per row, the results are returned in an instance
of Object[].
Returns:
the result list/**
	 * Return the query results as a <tt>List</tt>. If the query contains
	 * multiple results per row, the results are returned in an instance
	 * of <tt>Object[]</tt>.
	 *
	 * @return the result list
	 */
	List<R> list();

	
Convenience method to return a single instance that matches the query, or null if the query returns no results. 
Throws:
NonUniqueResultException – if there is more than one matching result
Returns:
the single result or null/**
	 * Convenience method to return a single instance that matches
	 * the query, or {@code null} if the query returns no results.
	 *
	 * @return the single result or <tt>null</tt>
	 *
	 * @throws NonUniqueResultException if there is more than one matching result
	 */
	R uniqueResult();

	
Access to information about query parameters.
Returns:
information about query parameters./**
	 * Access to information about query parameters.
	 *
	 * @return information about query parameters.
	 */
	ParameterMetadata getParameterMetadata();

	
Return the names of all named parameters of the query.
Returns:
the parameter names, in no particular order
Deprecated:
(since 5.2) use ParameterMetadata.getNamedParameterNames()/**
	 * Return the names of all named parameters of the query.
	 *
	 * @return the parameter names, in no particular order
	 *
	 * @deprecated (since 5.2) use {@link ParameterMetadata#getNamedParameterNames()}
	 */
	@Deprecated
	String[] getNamedParameters();

	
Bind a query parameter using its inferred Type. If the parameter is defined in such a way that the Type cannot be inferred from its usage context then use of this form of binding is not allowed, and setParameter(QueryParameter, Object, Type) should be used instead 
Params:
parameter – The query parameter memento
val – the possibly-null parameter value
Returns:
this, for method chaining/**
	 * Bind a query parameter using its inferred Type.  If the parameter is
	 * defined in such a way that the Type cannot be inferred from its usage context then
	 * use of this form of binding is not allowed, and {@link #setParameter(QueryParameter, Object, Type)}
	 * should be used instead
	 *
	 * @param parameter The query parameter memento
	 * @param val the possibly-null parameter value
	 *
	 * @return {@code this}, for method chaining
	 */
	<T> Query<R> setParameter(QueryParameter<T> parameter, T val);

	<T> Query<R> setParameter(Parameter<T> param, T value);

	
Bind a named query parameter using its inferred Type. If the parameter is defined in such a way that the Type cannot be inferred from its usage context then use of this form of binding is not allowed, and setParameter(String, Object, Type) should be used instead 
Params:
name – the parameter name
val – the (possibly-null) parameter value
Returns:
this, for method chaining/**
	 * Bind a named query parameter using its inferred Type.  If the parameter is
	 * defined in such a way that the Type cannot be inferred from its usage context then
	 * use of this form of binding is not allowed, and {@link #setParameter(String, Object, Type)}
	 * should be used instead
	 *
	 * @param name the parameter name
	 * @param val the (possibly-null) parameter value
	 *
	 * @return {@code this}, for method chaining
	 */
	@SuppressWarnings("unchecked")
	Query<R> setParameter(String name, Object val);

	
Bind a positional query parameter using its inferred Type. If the parameter is defined in such a way that the Type cannot be inferred from its usage context then use of this form of binding is not allowed, and setParameter(int, Object, Type) should be used instead 
Params:
position – the position of the parameter in the query
string, numbered from 0.
val – the possibly-null parameter value
Returns:
this, for method chaining/**
	 * Bind a positional query parameter using its inferred Type.  If the parameter is
	 * defined in such a way that the Type cannot be inferred from its usage context then
	 * use of this form of binding is not allowed, and {@link #setParameter(int, Object, Type)}
	 * should be used instead
	 *
	 * @param position the position of the parameter in the query
	 * string, numbered from <tt>0</tt>.
	 * @param val the possibly-null parameter value
	 *
	 * @return {@code this}, for method chaining
	 */
	@SuppressWarnings("unchecked")
	Query<R> setParameter(int position, Object val);

	
Bind a query parameter using the supplied Type
Params:
parameter – The query parameter memento
val – the possibly-null parameter value
type – the Hibernate type
Returns:
this, for method chaining/**
	 * Bind a query parameter using the supplied Type
	 *
	 * @param parameter The query parameter memento
	 * @param val the possibly-null parameter value
	 * @param type the Hibernate type
	 *
	 * @return {@code this}, for method chaining
	 */
	<P> Query<R> setParameter(QueryParameter<P> parameter, P val, Type type);

	
Bind a named query parameter using the supplied Type
Params:
name – the name of the parameter
val – the possibly-null parameter value
type – the Hibernate type
Returns:
this, for method chaining/**
	 * Bind a named query parameter using the supplied Type
	 *
	 * @param name the name of the parameter
	 * @param val the possibly-null parameter value
	 * @param type the Hibernate type
	 *
	 * @return {@code this}, for method chaining
	 */
	Query<R> setParameter(String name, Object val, Type type);

	
Bind a value to a JDBC-style query parameter.
Params:
position – the position of the parameter in the query
string, numbered from 0.
val – the possibly-null parameter value
type – the Hibernate type
Returns:
this, for method chaining/**
	 * Bind a value to a JDBC-style query parameter.
	 *
	 * @param position the position of the parameter in the query
	 * string, numbered from <tt>0</tt>.
	 * @param val the possibly-null parameter value
	 * @param type the Hibernate type
	 *
	 * @return {@code this}, for method chaining
	 */
	Query<R> setParameter(int position, Object val, Type type);

	
Bind a query parameter as some form of date/time using the indicated
temporal-type.
Params:
parameter – The query parameter memento
val – the possibly-null parameter value
temporalType – the temporal-type to use in binding the date/time
Returns:
this, for method chaining/**
	 * Bind a query parameter as some form of date/time using the indicated
	 * temporal-type.
	 *
	 * @param parameter The query parameter memento
	 * @param val the possibly-null parameter value
	 * @param temporalType the temporal-type to use in binding the date/time
	 *
	 * @return {@code this}, for method chaining
	 */
	<P> Query<R> setParameter(QueryParameter<P> parameter, P val, TemporalType temporalType);

	
Bind a named query parameter as some form of date/time using
the indicated temporal-type.
Params:
name – the parameter name
val – the possibly-null parameter value
temporalType – the temporal-type to use in binding the date/time
Returns:
this, for method chaining/**
	 * Bind a named query parameter as some form of date/time using
	 * the indicated temporal-type.
	 *
	 * @param name the parameter name
	 * @param val the possibly-null parameter value
	 * @param temporalType the temporal-type to use in binding the date/time
	 *
	 * @return {@code this}, for method chaining
	 */
	<P> Query<R> setParameter(String name, P val, TemporalType temporalType);

	
Bind a positional query parameter as some form of date/time using
the indicated temporal-type.
Params:
position – the position of the parameter in the query
string, numbered from 0.
val – the possibly-null parameter value
temporalType – the temporal-type to use in binding the date/time
Returns:
this, for method chaining/**
	 * Bind a positional query parameter as some form of date/time using
	 * the indicated temporal-type.
	 *
	 * @param position the position of the parameter in the query
	 * string, numbered from <tt>0</tt>.
	 * @param val the possibly-null parameter value
	 * @param temporalType the temporal-type to use in binding the date/time
	 *
	 * @return {@code this}, for method chaining
	 */
	<P> Query<R> setParameter(int position, P val, TemporalType temporalType);





	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// todo: consider for deprecation
	//
	//		The major concern with parameter lists is "expansion" which is where we need
	// 		to dynamically adjust the query string to include a JDBC parameter placeholder
	// 		for each list value
	//
	//		For the rest, its a question of slimming-down the API

	
Bind multiple values to a query parameter using its inferred Type. The Hibernate type of the parameter values is
first detected via the usage/position in the query and if not sufficient secondly
guessed from the class of the first object in the collection. This is useful for binding a list of values
to an expression such as foo.bar in (:value_list).
Params:
parameter – the parameter memento
values – a collection of values to list
Returns:
this, for method chaining/**
	 * Bind multiple values to a query parameter using its inferred Type. The Hibernate type of the parameter values is
	 * first detected via the usage/position in the query and if not sufficient secondly
	 * guessed from the class of the first object in the collection. This is useful for binding a list of values
	 * to an expression such as <tt>foo.bar in (:value_list)</tt>.
	 *
	 * @param parameter the parameter memento
	 * @param values a collection of values to list
	 *
	 * @return {@code this}, for method chaining
	 */
	<P> Query<R> setParameterList(QueryParameter<P> parameter, Collection<P> values);

	
Bind multiple values to a named query parameter. The Hibernate type of the parameter is
first detected via the usage/position in the query and if not sufficient secondly
guessed from the class of the first object in the collection. This is useful for binding a list of values
to an expression such as foo.bar in (:value_list).
Params:
name – the name of the parameter
values – a collection of values to list
Returns:
this, for method chaining/**
	 * Bind multiple values to a named query parameter. The Hibernate type of the parameter is
	 * first detected via the usage/position in the query and if not sufficient secondly
	 * guessed from the class of the first object in the collection. This is useful for binding a list of values
	 * to an expression such as <tt>foo.bar in (:value_list)</tt>.
	 *
	 * @param name the name of the parameter
	 * @param values a collection of values to list
	 *
	 * @return {@code this}, for method chaining
	 */
	Query<R> setParameterList(String name, Collection values);
	Query<R> setParameterList(int position, Collection values);

	
Bind multiple values to a named query parameter. This is useful for binding
a list of values to an expression such as foo.bar in (:value_list).
Params:
name – the name of the parameter
values – a collection of values to list
type – the Hibernate type of the values
Returns:
this, for method chaining/**
	 * Bind multiple values to a named query parameter. This is useful for binding
	 * a list of values to an expression such as <tt>foo.bar in (:value_list)</tt>.
	 *
	 * @param name the name of the parameter
	 * @param values a collection of values to list
	 * @param type the Hibernate type of the values
	 *
	 * @return {@code this}, for method chaining
	 */
	Query<R> setParameterList(String name, Collection values, Type type);
	Query<R> setParameterList(int position, Collection values, Type type);

	
Bind multiple values to a named query parameter. This is useful for binding
a list of values to an expression such as foo.bar in (:value_list).
Params:
name – the name of the parameter
values – a collection of values to list
type – the Hibernate type of the values
Returns:
this, for method chaining/**
	 * Bind multiple values to a named query parameter. This is useful for binding
	 * a list of values to an expression such as <tt>foo.bar in (:value_list)</tt>.
	 *
	 * @param name the name of the parameter
	 * @param values a collection of values to list
	 * @param type the Hibernate type of the values
	 *
	 * @return {@code this}, for method chaining
	 */
	Query<R> setParameterList(String name, Object[] values, Type type);
	Query<R> setParameterList(int position, Object[] values, Type type);

	
Bind multiple values to a named query parameter. The Hibernate type of the parameter is
first detected via the usage/position in the query and if not sufficient secondly
guessed from the class of the first object in the array. This is useful for binding a list of values
to an expression such as foo.bar in (:value_list).
Params:
name – the name of the parameter
values – a collection of values to list
Returns:
this, for method chaining/**
	 * Bind multiple values to a named query parameter. The Hibernate type of the parameter is
	 * first detected via the usage/position in the query and if not sufficient secondly
	 * guessed from the class of the first object in the array. This is useful for binding a list of values
	 * to an expression such as <tt>foo.bar in (:value_list)</tt>.
	 *
	 * @param name the name of the parameter
	 * @param values a collection of values to list
	 *
	 * @return {@code this}, for method chaining
	 */
	Query<R> setParameterList(String name, Object[] values);
	Query<R> setParameterList(int position, Object[] values);

	
Bind the property values of the given bean to named parameters of the query,
matching property names with parameter names and mapping property types to
Hibernate types using heuristics.
Params:
bean – any JavaBean or POJO
Returns:
this, for method chaining/**
	 * Bind the property values of the given bean to named parameters of the query,
	 * matching property names with parameter names and mapping property types to
	 * Hibernate types using heuristics.
	 *
	 * @param bean any JavaBean or POJO
	 *
	 * @return {@code this}, for method chaining
	 */
	Query<R> setProperties(Object bean);

	
Bind the values of the given Map for each named parameters of the query,
matching key names with parameter names and mapping value types to
Hibernate types using heuristics.
Params:
bean – a java.util.Map
Returns:
this, for method chaining/**
	 * Bind the values of the given Map for each named parameters of the query,
	 * matching key names with parameter names and mapping value types to
	 * Hibernate types using heuristics.
	 *
	 * @param bean a java.util.Map
	 *
	 * @return {@code this}, for method chaining
	 */
	Query<R> setProperties(Map bean);


	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// covariant overrides

	@Override
	Query<R> setMaxResults(int maxResult);

	@Override
	Query<R> setFirstResult(int startPosition);

	@Override
	Query<R> setHint(String hintName, Object value);

	@Override
	Query<R> setParameter(Parameter<Calendar> param, Calendar value, TemporalType temporalType);

	@Override
	Query<R> setParameter(Parameter<Date> param, Date value, TemporalType temporalType);

	@Override
	Query<R> setParameter(String name, Calendar value, TemporalType temporalType);

	@Override
	Query<R> setParameter(String name, Date value, TemporalType temporalType);

	@Override
	Query<R> setParameter(int position, Calendar value, TemporalType temporalType);

	@Override
	Query<R> setParameter(int position, Date value, TemporalType temporalType);

	@Override
	Query<R> setFlushMode(FlushModeType flushMode);

	@Override
	Query<R> setLockMode(LockModeType lockMode);


	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// proposed deprecations

	
Bind a positional String-valued parameter.
Params:
position – The parameter position
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a positional String-valued parameter.
	 *
	 * @param position The parameter position
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setString(int position, String val) {
		setParameter( position, val, StringType.INSTANCE );
		return this;
	}

	
Bind a positional char-valued parameter.
Params:
position – The parameter position
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a positional char-valued parameter.
	 *
	 * @param position The parameter position
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setCharacter(int position, char val) {
		setParameter( position, val, CharacterType.INSTANCE );
		return this;
	}

	
Bind a positional boolean-valued parameter.
Params:
position – The parameter position
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a positional boolean-valued parameter.
	 *
	 * @param position The parameter position
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setBoolean(int position, boolean val) {
		setParameter( position, val, determineProperBooleanType( position, val, BooleanType.INSTANCE ) );
		return this;
	}

	
Bind a positional byte-valued parameter.
Params:
position – The parameter position
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a positional byte-valued parameter.
	 *
	 * @param position The parameter position
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setByte(int position, byte val) {
		setParameter( position, val, ByteType.INSTANCE );
		return this;
	}

	
Bind a positional short-valued parameter.
Params:
position – The parameter position
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a positional short-valued parameter.
	 *
	 * @param position The parameter position
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setShort(int position, short val) {
		setParameter( position, val, ShortType.INSTANCE );
		return this;
	}

	
Bind a positional int-valued parameter.
Params:
position – The parameter position
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a positional int-valued parameter.
	 *
	 * @param position The parameter position
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setInteger(int position, int val) {
		setParameter( position, val, IntegerType.INSTANCE );
		return this;
	}

	
Bind a positional long-valued parameter.
Params:
position – The parameter position
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a positional long-valued parameter.
	 *
	 * @param position The parameter position
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setLong(int position, long val) {
		setParameter( position, val, LongType.INSTANCE );
		return this;
	}

	
Bind a positional float-valued parameter.
Params:
position – The parameter position
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a positional float-valued parameter.
	 *
	 * @param position The parameter position
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setFloat(int position, float val) {
		setParameter( position, val, FloatType.INSTANCE );
		return this;
	}

	
Bind a positional double-valued parameter.
Params:
position – The parameter position
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a positional double-valued parameter.
	 *
	 * @param position The parameter position
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setDouble(int position, double val) {
		setParameter( position, val, DoubleType.INSTANCE );
		return this;
	}

	
Bind a positional binary-valued parameter.
Params:
position – The parameter position
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a positional binary-valued parameter.
	 *
	 * @param position The parameter position
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setBinary(int position, byte[] val) {
		setParameter( position, val, BinaryType.INSTANCE );
		return this;
	}

	
Bind a positional String-valued parameter using streaming.
Params:
position – The parameter position
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a positional String-valued parameter using streaming.
	 *
	 * @param position The parameter position
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setText(int position, String val) {
		setParameter( position, val, TextType.INSTANCE );
		return this;
	}

	
Bind a positional binary-valued parameter using serialization.
Params:
position – The parameter position
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a positional binary-valued parameter using serialization.
	 *
	 * @param position The parameter position
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setSerializable(int position, Serializable val) {
		setParameter( position, val );
		return this;
	}

	
Bind a positional Locale-valued parameter.
Params:
position – The parameter position
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a positional Locale-valued parameter.
	 *
	 * @param position The parameter position
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setLocale(int position, Locale val) {
		setParameter( position, val, LocaleType.INSTANCE );
		return this;
	}

	
Bind a positional BigDecimal-valued parameter.
Params:
position – The parameter position
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a positional BigDecimal-valued parameter.
	 *
	 * @param position The parameter position
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setBigDecimal(int position, BigDecimal val) {
		setParameter( position, val, BigDecimalType.INSTANCE );
		return this;
	}

	
Bind a positional BigDecimal-valued parameter.
Params:
position – The parameter position
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a positional BigDecimal-valued parameter.
	 *
	 * @param position The parameter position
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setBigInteger(int position, BigInteger val) {
		setParameter( position, val, BigIntegerType.INSTANCE );
		return this;
	}

	
Bind a positional Date-valued parameter using just the Date portion.
Params:
position – The parameter position
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a positional Date-valued parameter using just the Date portion.
	 *
	 * @param position The parameter position
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setDate(int position, Date val) {
		setParameter( position, val, DateType.INSTANCE );
		return this;
	}

	
Bind a positional Date-valued parameter using just the Time portion.
Params:
position – The parameter position
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a positional Date-valued parameter using just the Time portion.
	 *
	 * @param position The parameter position
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setTime(int position, Date val) {
		setParameter( position, val, TimeType.INSTANCE );
		return this;
	}

	
Bind a positional Date-valued parameter using the full Timestamp.
Params:
position – The parameter position
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a positional Date-valued parameter using the full Timestamp.
	 *
	 * @param position The parameter position
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setTimestamp(int position, Date val) {
		setParameter( position, val, TimestampType.INSTANCE );
		return this;
	}

	
Bind a positional Calendar-valued parameter using the full Timestamp portion.
Params:
position – The parameter position
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a positional Calendar-valued parameter using the full Timestamp portion.
	 *
	 * @param position The parameter position
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setCalendar(int position, Calendar val) {
		setParameter( position, val, TimestampType.INSTANCE );
		return this;
	}

	
Bind a positional Calendar-valued parameter using just the Date portion.
Params:
position – The parameter position
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a positional Calendar-valued parameter using just the Date portion.
	 *
	 * @param position The parameter position
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setCalendarDate(int position, Calendar val) {
		setParameter( position, val, DateType.INSTANCE );
		return this;
	}

	
Bind a named String-valued parameter.
Params:
name – The parameter name
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a named String-valued parameter.
	 *
	 * @param name The parameter name
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setString(String name, String val) {
		setParameter( name, val, StringType.INSTANCE );
		return this;
	}

	
Bind a named char-valued parameter.
Params:
name – The parameter name
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a named char-valued parameter.
	 *
	 * @param name The parameter name
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setCharacter(String name, char val) {
		setParameter( name, val, CharacterType.INSTANCE );
		return this;
	}

	
Bind a named boolean-valued parameter.
Params:
name – The parameter name
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a named boolean-valued parameter.
	 *
	 * @param name The parameter name
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setBoolean(String name, boolean val) {
		setParameter( name, val, determineProperBooleanType( name, val, BooleanType.INSTANCE ) );
		return this;
	}

	
Bind a named byte-valued parameter.
Params:
name – The parameter name
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a named byte-valued parameter.
	 *
	 * @param name The parameter name
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setByte(String name, byte val) {
		setParameter( name, val, ByteType.INSTANCE );
		return this;
	}

	
Bind a named short-valued parameter.
Params:
name – The parameter name
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a named short-valued parameter.
	 *
	 * @param name The parameter name
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setShort(String name, short val) {
		setParameter( name, val, ShortType.INSTANCE );
		return this;
	}

	
Bind a named int-valued parameter.
Params:
name – The parameter name
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a named int-valued parameter.
	 *
	 * @param name The parameter name
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setInteger(String name, int val) {
		setParameter( name, val, IntegerType.INSTANCE );
		return this;
	}

	
Bind a named long-valued parameter.
Params:
name – The parameter name
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a named long-valued parameter.
	 *
	 * @param name The parameter name
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setLong(String name, long val) {
		setParameter( name, val, LongType.INSTANCE );
		return this;
	}

	
Bind a named float-valued parameter.
Params:
name – The parameter name
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a named float-valued parameter.
	 *
	 * @param name The parameter name
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setFloat(String name, float val) {
		setParameter( name, val, FloatType.INSTANCE );
		return this;
	}

	
Bind a named double-valued parameter.
Params:
name – The parameter name
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a named double-valued parameter.
	 *
	 * @param name The parameter name
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setDouble(String name, double val) {
		setParameter( name, val, DoubleType.INSTANCE );
		return this;
	}

	
Bind a named binary-valued parameter.
Params:
name – The parameter name
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a named binary-valued parameter.
	 *
	 * @param name The parameter name
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setBinary(String name, byte[] val) {
		setParameter( name, val, BinaryType.INSTANCE );
		return this;
	}

	
Bind a named String-valued parameter using streaming.
Params:
name – The parameter name
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a named String-valued parameter using streaming.
	 *
	 * @param name The parameter name
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setText(String name, String val) {
		setParameter( name, val, TextType.INSTANCE );
		return this;
	}

	
Bind a named binary-valued parameter using serialization.
Params:
name – The parameter name
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a named binary-valued parameter using serialization.
	 *
	 * @param name The parameter name
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setSerializable(String name, Serializable val) {
		setParameter( name, val );
		return this;
	}

	
Bind a named Locale-valued parameter.
Params:
name – The parameter name
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a named Locale-valued parameter.
	 *
	 * @param name The parameter name
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setLocale(String name, Locale val) {
		setParameter( name, val, TextType.INSTANCE );
		return this;
	}

	
Bind a named BigDecimal-valued parameter.
Params:
name – The parameter name
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a named BigDecimal-valued parameter.
	 *
	 * @param name The parameter name
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setBigDecimal(String name, BigDecimal val) {
		setParameter( name, val, BigDecimalType.INSTANCE );
		return this;
	}

	
Bind a named BigInteger-valued parameter.
Params:
name – The parameter name
val – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a named BigInteger-valued parameter.
	 *
	 * @param name The parameter name
	 * @param val The bind value
	 *
	 * @return {@code this}, for method chaining
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setBigInteger(String name, BigInteger val) {
		setParameter( name, val, BigIntegerType.INSTANCE );
		return this;
	}

	
Bind the val (time is truncated) of a given Date object to a named query parameter.
Params:
name – The name of the parameter
val – The val object
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind the val (time is truncated) of a given Date object to a named query parameter.
	 *
	 * @param name The name of the parameter
	 * @param val The val object
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setDate(String name, Date val) {
		setParameter( name, val, DateType.INSTANCE );
		return this;
	}

	
Bind the time (val is truncated) of a given Date object to a named query parameter.
Params:
name – The name of the parameter
val – The val object
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind the time (val is truncated) of a given Date object to a named query parameter.
	 *
	 * @param name The name of the parameter
	 * @param val The val object
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setTime(String name, Date val) {
		setParameter( name, val, TimeType.INSTANCE );
		return this;
	}

	
Bind the value and the time of a given Date object to a named query parameter.
Params:
name – The name of the parameter
value – The value object
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind the value and the time of a given Date object to a named query parameter.
	 *
	 * @param name The name of the parameter
	 * @param value The value object
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setTimestamp(String name, Date value) {
		setParameter( name, value, TimestampType.INSTANCE );
		return this;
	}

	
Bind a named Calendar-valued parameter using the full Timestamp.
Params:
name – The parameter name
value – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a named Calendar-valued parameter using the full Timestamp.
	 *
	 * @param name The parameter name
	 * @param value The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setCalendar(String name, Calendar value) {
		setParameter( name, value, TimestampType.INSTANCE );
		return this;
	}

	
Bind a named Calendar-valued parameter using just the Date portion.
Params:
name – The parameter name
value – The bind value
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind a named Calendar-valued parameter using just the Date portion.
	 *
	 * @param name The parameter name
	 * @param value The bind value
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setCalendarDate(String name, Calendar value) {
		setParameter( name, value, DateType.INSTANCE );
		return this;
	}

	
Bind an instance of a mapped persistent class to a JDBC-style query parameter. Use setParameter(int, Object) for null values. 
Params:
position – the position of the parameter in the query
string, numbered from 0.
val – a non-null instance of a persistent class
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind an instance of a mapped persistent class to a JDBC-style query parameter.
	 * Use {@link #setParameter(int, Object)} for null values.
	 *
	 * @param position the position of the parameter in the query
	 * string, numbered from <tt>0</tt>.
	 * @param val a non-null instance of a persistent class
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	Query<R> setEntity(int position, Object val);

	
Bind an instance of a mapped persistent class to a named query parameter. Use setParameter(String, Object) for null values. 
Params:
name – the name of the parameter
val – a non-null instance of a persistent class
Returns:
this, for method chaining
Deprecated:
(since 5.2) use setParameter(int, Object) or setParameter(int, Object, Type) instead/**
	 * Bind an instance of a mapped persistent class to a named query parameter.  Use
	 * {@link #setParameter(String, Object)} for null values.
	 *
	 * @param name the name of the parameter
	 * @param val a non-null instance of a persistent class
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) use {@link #setParameter(int, Object)} or {@link #setParameter(int, Object, Type)}
	 * instead
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	Query<R> setEntity(String name, Object val);

	
Deprecated:
added only to allow default method definition for deprecated methods here./**
	 * @deprecated added only to allow default method definition for deprecated methods here.
	 */
	@Deprecated
	Type determineProperBooleanType(int position, Object value, Type defaultType);

	
Deprecated:
added only to allow default method definition for deprecated methods here./**
	 * @deprecated added only to allow default method definition for deprecated methods here.
	 */
	@Deprecated
	Type determineProperBooleanType(String name, Object value, Type defaultType);


	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// deprecations

	
Set a strategy for handling the query results. This can be used to change
"shape" of the query result.
Params:
transformer – The transformer to apply
Returns:
this (for method chaining)
Deprecated:
(since 5.2)
@todo
develop a new approach to result transformers/**
	 * Set a strategy for handling the query results. This can be used to change
	 * "shape" of the query result.
	 *
	 * @param transformer The transformer to apply
	 *
	 * @return this (for method chaining)
	 *
	 * @deprecated (since 5.2)
	 * @todo develop a new approach to result transformers
	 */
	@Deprecated
	Query<R> setResultTransformer(ResultTransformer transformer);

	
Deprecated:
(since 5.2) use Tuple if you need access to "result variables"./**
	 * @deprecated (since 5.2) use {@link javax.persistence.Tuple} if you need access to "result variables".
	 */
	@Deprecated
	String[] getReturnAliases();

	
Bind values and types to positional parameters.  Allows binding more than one at a time; no real performance
impact.
The number of elements in each array should match.  That is, element number-0 in types array corresponds to
element-0 in the values array, etc,
Params:
types – The types
values – The values
Returns:
this, for method chaining
Deprecated:
(since 5.2) Bind values individually/**
	 * Bind values and types to positional parameters.  Allows binding more than one at a time; no real performance
	 * impact.
	 *
	 * The number of elements in each array should match.  That is, element number-0 in types array corresponds to
	 * element-0 in the values array, etc,
	 *
	 * @param types The types
	 * @param values The values
	 *
	 * @return {@code this}, for method chaining
	 *
	 * @deprecated (since 5.2) Bind values individually
	 */
	@Deprecated
	@SuppressWarnings("unchecked")
	default Query<R> setParameters(Object[] values, Type[] types) {
		assert values.length == types.length;
		for ( int i = 0; i < values.length; i++ ) {
			setParameter( i, values[i], types[i] );
		}

		return this;
	}
}