org.hibernate
Interface Query

All Known Subinterfaces:

SQLQuery

All 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():

• a particular page of the result set may be selected by calling setMaxResults(), setFirstResult()
• named query parameters may be used
• the results may be returned as an instance of ScrollableResults

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:

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(int position, BigDecimal number)
Query	setBigDecimal(String name, BigDecimal number)
Query	setBigInteger(int position, BigInteger number)
Query	setBigInteger(String name, BigInteger number)
Query	setBinary(int position, byte[] val)
Query	setBinary(String name, byte[] val)
Query	setBoolean(int position, boolean val)
Query	setBoolean(String name, boolean val)
Query	setByte(int position, byte val)
Query	setByte(String name, byte val)
Query	setCacheable(boolean cacheable) Enable caching of this query result set.
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	setCalendar(int position, Calendar calendar)
Query	setCalendar(String name, Calendar calendar)
Query	setCalendarDate(int position, Calendar calendar)
Query	setCalendarDate(String name, Calendar calendar)
Query	setCharacter(int position, char val)
Query	setCharacter(String name, char val)
Query	setComment(String comment) Add a comment to the generated SQL.
Query	setDate(int position, Date date)
Query	setDate(String name, Date date)
Query	setDouble(int position, double val)
Query	setDouble(String name, double val)
Query	setEntity(int position, Object val) Bind an instance of a mapped persistent class to a JDBC-style query parameter.
Query	setEntity(String name, Object val) Bind an instance of a mapped persistent class to a named 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(int position, float val)
Query	setFloat(String name, float val)
Query	setFlushMode(FlushMode flushMode) Override the current session flush mode, just for this query.
Query	setInteger(int position, int val)
Query	setInteger(String name, int val)
Query	setLocale(int position, Locale locale)
Query	setLocale(String name, 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(int position, long val)
Query	setLong(String name, long val)
Query	setMaxResults(int maxResults) Set the maximum number of rows to retrieve.
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	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	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(int position, Serializable val)
Query	setSerializable(String name, Serializable val)
Query	setShort(int position, short val)
Query	setShort(String name, short val)
Query	setString(int position, String val)
Query	setString(String name, String val)
Query	setText(int position, String val)
Query	setText(String name, String val)
Query	setTime(int position, Date date)
Query	setTime(String name, Date date)
Query	setTimeout(int timeout) Set a timeout for the underlying JDBC query.
Query	setTimestamp(int position, Date date)
Query	setTimestamp(String name, Date date)
Object	uniqueResult() Convenience method to return a single instance that matches the query, or null if the query returns no results.

Method Detail

getQueryString

String getQueryString()

Get the query string.

Returns:

the query string

getReturnTypes

Type[] getReturnTypes()
                      throws HibernateException

Return the Hibernate types of the query result set.

Returns:

an array of types

Throws:

HibernateException

getReturnAliases

String[] getReturnAliases()
                          throws HibernateException

Return the HQL select clause aliases (if any)

Returns:

an array of aliases as strings

Throws:

HibernateException

getNamedParameters

String[] getNamedParameters()
                            throws HibernateException

Return the names of all named parameters of the query.

Returns:

the parameter names, in no particular order

Throws:

HibernateException

iterate

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

Throws:

HibernateException

scroll

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

Throws:

HibernateException

See Also:

ScrollableResults

scroll

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

Throws:

HibernateException

See Also:

ScrollableResults, ScrollMode

list

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

Throws:

HibernateException

uniqueResult

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

Throws:

NonUniqueResultException - if there is more than one matching result

HibernateException

executeUpdate

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.

Throws:

HibernateException

setMaxResults

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

setFirstResult

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

setReadOnly

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.

setCacheable

Query setCacheable(boolean cacheable)

Enable caching of this query result set.

Parameters:

cacheable - Should the query results be cacheable?

setCacheRegion

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

setTimeout

Query setTimeout(int timeout)

Set a timeout for the underlying JDBC query.

Parameters:

timeout - the timeout in seconds

setFetchSize

Query setFetchSize(int fetchSize)

Set a fetch size for the underlying JDBC query.

Parameters:

fetchSize - the fetch size

setLockMode

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

setComment

Query setComment(String comment)

Add a comment to the generated SQL.

Parameters:

comment - a human-readable string

setFlushMode

Query setFlushMode(FlushMode flushMode)

Override the current session flush mode, just for this query.

See Also:

FlushMode

setCacheMode

Query setCacheMode(CacheMode cacheMode)

Override the current session cache mode, just for this query.

See Also:

CacheMode

setParameter

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

setParameter

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

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

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

setParameters

Query setParameters(Object[] values,
                    Type[] types)
                    throws HibernateException

Bind values and types to positional parameters.

Throws:

HibernateException

setParameterList

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

Throws:

HibernateException

setParameterList

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

Throws:

HibernateException

setParameterList

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

Throws:

HibernateException

setParameterList

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

Throws:

HibernateException

setProperties

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

Throws:

HibernateException

setProperties

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

Throws:

HibernateException

setString

Query setString(int position,
                String val)

setCharacter

Query setCharacter(int position,
                   char val)

setBoolean

Query setBoolean(int position,
                 boolean val)

setByte

Query setByte(int position,
              byte val)

setShort

Query setShort(int position,
               short val)

setInteger

Query setInteger(int position,
                 int val)

setLong

Query setLong(int position,
              long val)

setFloat

Query setFloat(int position,
               float val)

setDouble

Query setDouble(int position,
                double val)

setBinary

Query setBinary(int position,
                byte[] val)

setText

Query setText(int position,
              String val)

setSerializable

Query setSerializable(int position,
                      Serializable val)

setLocale

Query setLocale(int position,
                Locale locale)

setBigDecimal

Query setBigDecimal(int position,
                    BigDecimal number)

setBigInteger

Query setBigInteger(int position,
                    BigInteger number)

setDate

Query setDate(int position,
              Date date)

setTime

Query setTime(int position,
              Date date)

setTimestamp

Query setTimestamp(int position,
                   Date date)

setCalendar

Query setCalendar(int position,
                  Calendar calendar)

setCalendarDate

Query setCalendarDate(int position,
                      Calendar calendar)

setString

Query setString(String name,
                String val)

setCharacter

Query setCharacter(String name,
                   char val)

setBoolean

Query setBoolean(String name,
                 boolean val)

setByte

Query setByte(String name,
              byte val)

setShort

Query setShort(String name,
               short val)

setInteger

Query setInteger(String name,
                 int val)

setLong

Query setLong(String name,
              long val)

setFloat

Query setFloat(String name,
               float val)

setDouble

Query setDouble(String name,
                double val)

setBinary

Query setBinary(String name,
                byte[] val)

setText

Query setText(String name,
              String val)

setSerializable

Query setSerializable(String name,
                      Serializable val)

setLocale

Query setLocale(String name,
                Locale locale)

setBigDecimal

Query setBigDecimal(String name,
                    BigDecimal number)

setBigInteger

Query setBigInteger(String name,
                    BigInteger number)

setDate

Query setDate(String name,
              Date date)

setTime

Query setTime(String name,
              Date date)

setTimestamp

Query setTimestamp(String name,
                   Date date)

setCalendar

Query setCalendar(String name,
                  Calendar calendar)

setCalendarDate

Query setCalendarDate(String name,
                      Calendar calendar)

setEntity

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

setEntity

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

setResultTransformer

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)