org.hibernate

Interface Query

Known Subinterfaces:
SQLQuery
Known Implementing Classes:
AbstractQueryImpl, CollectionFilterImpl, QueryImpl, SQLQueryImpl

public interface Query

An object-oriented representation of a Hibernate query. A Query instance is obtained by calling Session.createQuery(). This interface exposes some extra functionality beyond that provided by Session.iterate() and Session.find():
Named query parameters are tokens of the form :name in the query string. A value is bound to the integer parameter :foo by calling

setParameter("foo", foo, Hibernate.INTEGER);

for example. A name may appear multiple times in the query string.

JDBC-style ? parameters are also supported. To bind a value to a JDBC-style parameter use a set method that accepts an int positional argument (numbered from zero, contrary to JDBC).

You may not mix and match JDBC-style parameters and named parameters in the same query.

Queries are executed by calling list(), scroll() or iterate(). A query may be re-executed by subsequent invocations. Its lifespan is, however, bounded by the lifespan of the Session that created it.

Implementors are not intended to be threadsafe.
Author:
Gavin King
See Also:
org.hibernate.Session.createQuery(java.lang.String), ScrollableResults

Method Summary

int
executeUpdate()
Execute the update or delete statement.
String[]
getNamedParameters()
Return the names of all named parameters of the query.
String
getQueryString()
Get the query string.
String[]
getReturnAliases()
Return the HQL select clause aliases (if any)
Type[]
getReturnTypes()
Return the Hibernate types of the query result set.
Iterator
iterate()
Return the query results as an Iterator.
List
list()
Return the query results as a List.
ScrollableResults
scroll()
Return the query results as ScrollableResults.
ScrollableResults
scroll(ScrollMode scrollMode)
Return the query results as ScrollableResults.
Query
setBigDecimal(String name, BigDecimal number)
Query
setBigDecimal(int position, BigDecimal number)
Query
setBigInteger(String name, BigInteger number)
Query
setBigInteger(int position, BigInteger number)
Query
setBinary(String name, byte[] val)
Query
setBinary(int position, byte[] val)
Query
setBoolean(String name, boolean val)
Query
setBoolean(int position, boolean val)
Query
setByte(String name, byte val)
Query
setByte(int position, byte val)
Query
setCacheMode(CacheMode cacheMode)
Override the current session cache mode, just for this query.
Query
setCacheRegion(String cacheRegion)
Set the name of the cache region.
Query
setCacheable(boolean cacheable)
Enable caching of this query result set.
Query
setCalendar(String name, Calendar calendar)
Query
setCalendar(int position, Calendar calendar)
Query
setCalendarDate(String name, Calendar calendar)
Query
setCalendarDate(int position, Calendar calendar)
Query
setCharacter(String name, char val)
Query
setCharacter(int position, char val)
Query
setComment(String comment)
Add a comment to the generated SQL.
Query
setDate(String name, Date date)
Query
setDate(int position, Date date)
Query
setDouble(String name, double val)
Query
setDouble(int position, double val)
Query
setEntity(String name, Object val)
Bind an instance of a mapped persistent class to a named query parameter.
Query
setEntity(int position, Object val)
Bind an instance of a mapped persistent class to a JDBC-style query parameter.
Query
setFetchSize(int fetchSize)
Set a fetch size for the underlying JDBC query.
Query
setFirstResult(int firstResult)
Set the first row to retrieve.
Query
setFloat(String name, float val)
Query
setFloat(int position, float val)
Query
setFlushMode(FlushMode flushMode)
Override the current session flush mode, just for this query.
Query
setInteger(String name, int val)
Query
setInteger(int position, int val)
Query
setLocale(String name, Locale locale)
Query
setLocale(int position, Locale locale)
Query
setLockMode(String alias, LockMode lockMode)
Set the lockmode for the objects idententified by the given alias that appears in the FROM clause.
Query
setLong(String name, long val)
Query
setLong(int position, long val)
Query
setMaxResults(int maxResults)
Set the maximum number of rows to retrieve.
Query
setParameter(String name, Object val)
Bind a value to a named query parameter.
Query
setParameter(String name, Object val, Type type)
Bind a value to a named query parameter.
Query
setParameter(int position, Object val)
Bind a value to a JDBC-style query parameter.
Query
setParameter(int position, Object val, Type type)
Bind a value to a JDBC-style query parameter.
Query
setParameterList(String name, Collection vals)
Bind multiple values to a named query parameter.
Query
setParameterList(String name, Collection vals, Type type)
Bind multiple values to a named query parameter.
Query
setParameterList(String name, Object[] vals)
Bind multiple values to a named query parameter.
Query
setParameterList(String name, Object[] vals, Type type)
Bind multiple values to a named query parameter.
Query
setParameters(Object[] values, Type[] types)
Bind values and types to positional parameters.
Query
setProperties(Map 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 hueristics.
Query
setProperties(Object bean)
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 hueristics.
Query
setReadOnly(boolean readOnly)
Entities retrieved by this query will be loaded in a read-only mode where Hibernate will never dirty-check them or make changes persistent.
Query
setResultTransformer(ResultTransformer transformer)
Set a strategy for handling the query results.
Query
setSerializable(String name, Serializable val)
Query
setSerializable(int position, Serializable val)
Query
setShort(String name, short val)
Query
setShort(int position, short val)
Query
setString(String name, String val)
Query
setString(int position, String val)
Query
setText(String name, String val)
Query
setText(int position, String val)
Query
setTime(String name, Date date)
Query
setTime(int position, Date date)
Query
setTimeout(int timeout)
Set a timeout for the underlying JDBC query.
Query
setTimestamp(String name, Date date)
Query
setTimestamp(int position, Date date)
Object
uniqueResult()
Convenience method to return a single instance that matches the query, or null if the query returns no results.

Method Details

executeUpdate

public int executeUpdate()
            throws HibernateException
Execute the update or delete statement. The semantics are compliant with the ejb3 Query.executeUpdate() method.
Returns:
The number of entities updated or deleted.

getNamedParameters

public String[] getNamedParameters()
            throws HibernateException
Return the names of all named parameters of the query.
Returns:
the parameter names, in no particular order

getQueryString

public String getQueryString()
Get the query string.
Returns:
the query string

getReturnAliases

public String[] getReturnAliases()
            throws HibernateException
Return the HQL select clause aliases (if any)
Returns:
an array of aliases as strings

getReturnTypes

public Type[] getReturnTypes()
            throws HibernateException
Return the Hibernate types of the query result set.
Returns:
an array of types

iterate

public Iterator iterate()
            throws HibernateException
Return the query results as an Iterator. If the query contains multiple results pre 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

list

public List list()
            throws HibernateException
Return the query results as a List. If the query contains multiple results pre row, the results are returned in an instance of Object[].
Returns:
the result list

scroll

public ScrollableResults scroll()
            throws HibernateException
Return the query results as ScrollableResults. The scrollability of the returned results depends upon JDBC driver support for scrollable ResultSets.
Returns:
the result iterator

scroll

public ScrollableResults scroll(ScrollMode scrollMode)
            throws HibernateException
Return the query results as ScrollableResults. The scrollability of the returned results depends upon JDBC driver support for scrollable ResultSets.
Returns:
the result iterator

setBigDecimal

public Query setBigDecimal(String name,
                           BigDecimal number)

setBigDecimal

public Query setBigDecimal(int position,
                           BigDecimal number)

setBigInteger

public Query setBigInteger(String name,
                           BigInteger number)

setBigInteger

public Query setBigInteger(int position,
                           BigInteger number)

setBinary

public Query setBinary(String name,
                       byte[] val)

setBinary

public Query setBinary(int position,
                       byte[] val)

setBoolean

public Query setBoolean(String name,
                        boolean val)

setBoolean

public Query setBoolean(int position,
                        boolean val)

setByte

public Query setByte(String name,
                     byte val)

setByte

public Query setByte(int position,
                     byte val)

setCacheMode

public Query setCacheMode(CacheMode cacheMode)
Override the current session cache mode, just for this query.
See Also:
CacheMode

setCacheRegion

public Query setCacheRegion(String cacheRegion)
Set the name of the cache region.
Parameters:
cacheRegion - the name of a query cache region, or null for the default query cache

setCacheable

public Query setCacheable(boolean cacheable)
Enable caching of this query result set.
Parameters:
cacheable - Should the query results be cacheable?

setCalendar

public Query setCalendar(String name,
                         Calendar calendar)

setCalendar

public Query setCalendar(int position,
                         Calendar calendar)

setCalendarDate

public Query setCalendarDate(String name,
                             Calendar calendar)

setCalendarDate

public Query setCalendarDate(int position,
                             Calendar calendar)

setCharacter

public Query setCharacter(String name,
                          char val)

setCharacter

public Query setCharacter(int position,
                          char val)

setComment

public Query setComment(String comment)
Add a comment to the generated SQL.
Parameters:
comment - a human-readable string

setDate

public Query setDate(String name,
                     Date date)

setDate

public Query setDate(int position,
                     Date date)

setDouble

public Query setDouble(String name,
                       double val)

setDouble

public Query setDouble(int position,
                       double val)

setEntity

public Query setEntity(String name,
                       Object val)
Bind an instance of a mapped persistent class to a named query parameter.
Parameters:
name - the name of the parameter
val - a non-null instance of a persistent class

setEntity

public Query setEntity(int position,
                       Object val)
Bind an instance of a mapped persistent class to a JDBC-style query parameter.
Parameters:
position - the position of the parameter in the query string, numbered from 0.
val - a non-null instance of a persistent class

setFetchSize

public Query setFetchSize(int fetchSize)
Set a fetch size for the underlying JDBC query.
Parameters:
fetchSize - the fetch size

setFirstResult

public Query setFirstResult(int firstResult)
Set the first row to retrieve. If not set, rows will be retrieved beginnning from row 0.
Parameters:
firstResult - a row number, numbered from 0

setFloat

public Query setFloat(String name,
                      float val)

setFloat

public Query setFloat(int position,
                      float val)

setFlushMode

public Query setFlushMode(FlushMode flushMode)
Override the current session flush mode, just for this query.
See Also:
FlushMode

setInteger

public Query setInteger(String name,
                        int val)

setInteger

public Query setInteger(int position,
                        int val)

setLocale

public Query setLocale(String name,
                       Locale locale)

setLocale

public Query setLocale(int position,
                       Locale locale)

setLockMode

public Query setLockMode(String alias,
                         LockMode lockMode)
Set the lockmode for the objects idententified by the given alias that appears in the FROM clause.
Parameters:
alias - a query alias, or this for a collection filter

setLong

public Query setLong(String name,
                     long val)

setLong

public Query setLong(int position,
                     long val)

setMaxResults

public Query setMaxResults(int maxResults)
Set the maximum number of rows to retrieve. If not set, there is no limit to the number of rows retrieved.
Parameters:
maxResults - the maximum number of rows

setParameter

public Query setParameter(String name,
                          Object val)
            throws HibernateException
Bind a value 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 given object.
Parameters:
name - the name of the parameter
val - the non-null parameter value
Throws:
HibernateException - if no type could be determined

setParameter

public Query setParameter(String name,
                          Object val,
                          Type type)
Bind a value to a named query parameter.
Parameters:
name - the name of the parameter
val - the possibly-null parameter value
type - the Hibernate type

setParameter

public Query setParameter(int position,
                          Object val)
            throws HibernateException
Bind a value to a JDBC-style 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 given object.
Parameters:
position - the position of the parameter in the query string, numbered from 0.
val - the non-null parameter value
Throws:
HibernateException - if no type could be determined

setParameter

public Query setParameter(int position,
                          Object val,
                          Type type)
Bind a value to a JDBC-style query parameter.
Parameters:
position - the position of the parameter in the query string, numbered from 0.
val - the possibly-null parameter value
type - the Hibernate type

setParameterList

public Query setParameterList(String name,
                              Collection vals)
            throws HibernateException
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).
Parameters:
name - the name of the parameter
vals - a collection of values to list

setParameterList

public Query setParameterList(String name,
                              Collection vals,
                              Type type)
            throws HibernateException
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).
Parameters:
name - the name of the parameter
vals - a collection of values to list
type - the Hibernate type of the values

setParameterList

public Query setParameterList(String name,
                              Object[] vals)
            throws HibernateException
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).
Parameters:
name - the name of the parameter
vals - a collection of values to list

setParameterList

public Query setParameterList(String name,
                              Object[] vals,
                              Type type)
            throws HibernateException
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).
Parameters:
name - the name of the parameter
vals - a collection of values to list
type - the Hibernate type of the values

setParameters

public Query setParameters(Object[] values,
                           Type[] types)
            throws HibernateException
Bind values and types to positional parameters.

setProperties

public Query setProperties(Map bean)
            throws HibernateException
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 hueristics.
Parameters:
bean - a java.util.Map

setProperties

public Query setProperties(Object bean)
            throws HibernateException
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 hueristics.
Parameters:
bean - any JavaBean or POJO

setReadOnly

public Query setReadOnly(boolean readOnly)
Entities retrieved by this query will be loaded in a read-only mode where Hibernate will never dirty-check them or make changes persistent.

setResultTransformer

public Query setResultTransformer(ResultTransformer transformer)
Set a strategy for handling the query results. This can be used to change "shape" of the query result.
Parameters:
transformer - The transformer to apply
Returns:
this (for method chaining)

setSerializable

public Query setSerializable(String name,
                             Serializable val)

setSerializable

public Query setSerializable(int position,
                             Serializable val)

setShort

public Query setShort(String name,
                      short val)

setShort

public Query setShort(int position,
                      short val)

setString

public Query setString(String name,
                       String val)

setString

public Query setString(int position,
                       String val)

setText

public Query setText(String name,
                     String val)

setText

public Query setText(int position,
                     String val)

setTime

public Query setTime(String name,
                     Date date)

setTime

public Query setTime(int position,
                     Date date)

setTimeout

public Query setTimeout(int timeout)
Set a timeout for the underlying JDBC query.
Parameters:
timeout - the timeout in seconds

setTimestamp

public Query setTimestamp(String name,
                          Date date)

setTimestamp

public Query setTimestamp(int position,
                          Date date)

uniqueResult

public Object uniqueResult()
            throws HibernateException
Convenience method to return a single instance that matches the query, or null if the query returns no results.
Returns:
the single result or null