Summary: Methods | [Expand All]
public interface

Query

org.hibernate.Query
Known Indirect Subclasses

Class Overview

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.

See Also

Summary

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

Public Methods

public abstract int executeUpdate ()

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

public abstract String[] getNamedParameters ()

Return the names of all named parameters of the query.

Returns
  • the parameter names, in no particular order
Throws
HibernateException

public abstract String getQueryString ()

Get the query string.

Returns
  • the query string

public abstract String[] getReturnAliases ()

Return the HQL select clause aliases (if any)

Returns
  • an array of aliases as strings
Throws
HibernateException

public abstract Type[] getReturnTypes ()

Return the Hibernate types of the query result set.

Returns
  • an array of types
Throws
HibernateException

public abstract boolean isReadOnly ()

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.

Returns
  • true, entities and proxies loaded by the query will be put in read-only mode false, entities and proxies loaded by the query will be put in modifiable mode
See Also

public abstract Iterator iterate ()

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

public abstract List list ()

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

public abstract ScrollableResults scroll (ScrollMode scrollMode)

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

public abstract ScrollableResults scroll ()

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

public abstract Query setBigDecimal (int position, BigDecimal number)

public abstract Query setBigDecimal (String name, BigDecimal number)

public abstract Query setBigInteger (String name, BigInteger number)

public abstract Query setBigInteger (int position, BigInteger number)

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

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

public abstract Query setBoolean (String name, boolean val)

public abstract Query setBoolean (int position, boolean val)

public abstract Query setByte (String name, byte val)

public abstract Query setByte (int position, byte val)

public abstract Query setCacheMode (CacheMode cacheMode)

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

See Also

public abstract 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

public abstract Query setCacheable (boolean cacheable)

Enable caching of this query result set.

Parameters
cacheable Should the query results be cacheable?

public abstract Query setCalendar (int position, Calendar calendar)

public abstract Query setCalendar (String name, Calendar calendar)

public abstract Query setCalendarDate (int position, Calendar calendar)

public abstract Query setCalendarDate (String name, Calendar calendar)

public abstract Query setCharacter (int position, char val)

public abstract Query setCharacter (String name, char val)

public abstract Query setComment (String comment)

Add a comment to the generated SQL.

Parameters
comment a human-readable string

public abstract Query setDate (String name, Date date)

public abstract Query setDate (int position, Date date)

public abstract Query setDouble (String name, double val)

public abstract Query setDouble (int position, double val)

public abstract 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

public abstract 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

public abstract Query setFetchSize (int fetchSize)

Set a fetch size for the underlying JDBC query.

Parameters
fetchSize the fetch size

public abstract 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

public abstract Query setFloat (int position, float val)

public abstract Query setFloat (String name, float val)

public abstract Query setFlushMode (FlushMode flushMode)

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

See Also

public abstract Query setInteger (String name, int val)

public abstract Query setInteger (int position, int val)

public abstract Query setLocale (String name, Locale locale)

public abstract Query setLocale (int position, Locale locale)

public abstract 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

public abstract Query setLockOptions (LockOptions lockOptions)

Set the lock options for the objects idententified by the given alias that appears in the FROM clause.

public abstract Query setLong (int position, long val)

public abstract Query setLong (String name, long val)

public abstract 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

public abstract 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

public abstract 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

public abstract Query setParameter (int position, Object val)

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

public abstract Query setParameter (String name, Object val)

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

public abstract Query setParameterList (String name, Collection vals)

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

public abstract Query setParameterList (String name, Collection vals, 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).

Parameters
name the name of the parameter
vals a collection of values to list
type the Hibernate type of the values
Throws
HibernateException

public abstract Query setParameterList (String name, Object[] vals)

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

public abstract Query setParameterList (String name, Object[] vals, 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).

Parameters
name the name of the parameter
vals a collection of values to list
type the Hibernate type of the values
Throws
HibernateException

public abstract Query setParameters (Object[] values, Type[] types)

Bind values and types to positional parameters.

Throws
HibernateException

public abstract 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.

Parameters
bean a java.util.Map
Throws
HibernateException

public abstract 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.

Parameters
bean any JavaBean or POJO
Throws
HibernateException

public abstract Query setReadOnly (boolean readOnly)

Set the read-only/modifiable mode for entities and proxies loaded by this Query. This setting overrides the default setting for the persistence context.

Parameters
readOnly true, entities and proxies loaded by the query will be put in read-only mode false, entities and proxies loaded by the query will be put in modifiable mode
See Also

public abstract 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)

public abstract Query setSerializable (int position, Serializable val)

public abstract Query setSerializable (String name, Serializable val)

public abstract Query setShort (int position, short val)

public abstract Query setShort (String name, short val)

public abstract Query setString (String name, String val)

public abstract Query setString (int position, String val)

public abstract Query setText (int position, String val)

public abstract Query setText (String name, String val)

public abstract Query setTime (int position, Date date)

public abstract Query setTime (String name, Date date)

public abstract Query setTimeout (int timeout)

Set a timeout for the underlying JDBC query.

Parameters
timeout the timeout in seconds

public abstract Query setTimestamp (String name, Date date)

public abstract Query setTimestamp (int position, Date date)

public abstract Object uniqueResult ()

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