/*
* 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.engine.spi.
RowSelection;
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
* @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.
*
* @return the query string
*/
String getQueryString();
/**
* "QueryOptions" is a better name, I think, than "RowSelection" -> 6.0
*
* @todo 6.0 rename RowSelection to QueryOptions
*
* @return Return the encapsulation of this query's options, which includes access to
* firstRow, maxRows, timeout and fetchSize. Important because this gives access to
* those values in their Integer form rather than the primitive form (int) required by JPA.
*/
RowSelection getQueryOptions();
/**
* The position of the first query result to be retrieved, previously set by
* {@link #setFirstResult(int)} or {@link #setHibernateFirstResult(int)}.
* <p/>
* If the value was not initialized by {@link #setFirstResult(int)} or
* {@link #setHibernateFirstResult(int)}, then {@code null} is returned, resulting
* in pagination starting from position 0.
* <p/>
* If {@link #setHibernateFirstResult(int)} was called with a negative value, then 0
* is returned.
*
* @return the position of the first query result, or {@code null} if uninitialized.
*
* @see #setFirstResult(int)
* @see #setHibernateFirstResult(int)
*
* @deprecated {@link #getFirstResult()} should be used instead.
*/
@
Deprecated
default
Integer getHibernateFirstResult() {
return
getQueryOptions().
getFirstRow();
}
/**
* Set the position of the first query result to be retrieved. A negative value will
* result in pagination starting from position 0.
*
* @param firstRow - the position of the first query result
* @return {@code this}, for method chaining
*
* @deprecated {@link #setFirstResult(int)} should be used instead.
*/
@
Deprecated
default
Query setHibernateFirstResult(int
firstRow) {
if (
firstRow < 0 ) {
getQueryOptions().
setFirstRow( 0 );
}
else {
getQueryOptions().
setFirstRow(
firstRow );
}
return this;
}
/**
* The maximum number of query results to be retrieved, previously set by
* {@link #setMaxResults(int)} or {@link #setHibernateMaxResults(int)}.
* <p/>
* If the value was not initialized by {@link #setMaxResults(int)} or
* {@link #setHibernateMaxResults(int)}, then {@code null} is returned
* <p/>
* If {@link #setHibernateMaxResults(int)} was called with a value less than
* or equal to 0, the value is considered to be uninitialized, and {@code null}
* is returned, resulting in no limit on the number of results.
*
* @return the maximum number of query results, or {@code null} if uninitialized.
*
* @see #setMaxResults(int) (int)
* @see #setHibernateMaxResults(int) (int)
*
* @deprecated {@link #getMaxResults()} should be used instead.
*/
@
Deprecated
default
Integer getHibernateMaxResults() {
return
getQueryOptions().
getMaxRows();
}
/**
* Set the maximum number of query results to be retrieved. A value less than
* or equal to 0 is considered uninitialized, resulting in no limit on the number
* of results.
*
* @param maxResults - the maximum number of query results
* @return {@code this}, for method chaining
*
* @deprecated {@link #setMaxResults(int)} should be used instead.
*/
@
Deprecated
default
Query setHibernateMaxResults(int
maxResults) {
// maxResults <= 0 is the same as uninitialized (with no limit),
if (
maxResults <= 0 ) {
// treat zero and negatives specifically as meaning no limit...
getQueryOptions().
setMaxRows( null );
}
else {
getQueryOptions().
setMaxRows(
maxResults );
}
return this;
}
/**
* 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.
*
* @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.
*
* @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 {@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.
*
* @return The query CacheMode.
*
* @see Session#getCacheMode()
* @see CacheMode
*/
CacheMode getCacheMode();
/**
* (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 {@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.
*
* @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 {@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).
*
* @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 <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 <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 {@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.
*
* @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 #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.
* @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.
*
* @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.
*
* @return The LockOptions
*
* @see LockOptions
*/
LockOptions getLockOptions();
/**
* 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 <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 {@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.
*
* @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 {@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 <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 <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.
*
* <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 <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 {@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.
*
* @return information about query parameters.
*/
ParameterMetadata getParameterMetadata();
/**
* 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 {@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 {@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 {@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
*
* @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
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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 <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 <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 <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 <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 <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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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.
*
* @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 {@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
* {@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
Type determineProperBooleanType(int
position,
Object value,
Type defaultType);
/**
* @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.
*
* @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 {@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,
*
* @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;
}
}