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.
executeUpdate
public int executeUpdate()
throws HibernateException
Execute the update or delete statement.
The semantics are compliant with the ejb3 Query.executeUpdate()
method.
- The number of entities updated or deleted.
getNamedParameters
public String[] getNamedParameters()
throws HibernateException
Return the names of all named parameters of the query.
- the parameter names, in no particular order
getQueryString
public String getQueryString()
Get the query string.
getReturnAliases
public String[] getReturnAliases()
throws HibernateException
Return the HQL select clause aliases (if any)
- an array of aliases as strings
getReturnTypes
public Type[] getReturnTypes()
throws HibernateException
Return the Hibernate types of the query result set.
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.
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[].
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.
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.
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.
setCacheRegion
public Query setCacheRegion(String cacheRegion)
Set the name of the cache region.
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.
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.
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.
name
- the name of the parameterval
- 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.
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.
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.
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.
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.
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.
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.
name
- the name of the parameterval
- the non-null parameter value
setParameter
public Query setParameter(String name,
Object val,
Type type)
Bind a value to a named query parameter.
name
- the name of the parameterval
- the possibly-null parameter valuetype
- 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.
position
- the position of the parameter in the query
string, numbered from 0.val
- the non-null parameter value
setParameter
public Query setParameter(int position,
Object val,
Type type)
Bind a value to a JDBC-style query parameter.
position
- the position of the parameter in the query
string, numbered from 0.val
- the possibly-null parameter valuetype
- 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).
name
- the name of the parametervals
- 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).
name
- the name of the parametervals
- a collection of values to listtype
- 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).
name
- the name of the parametervals
- 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).
name
- the name of the parametervals
- a collection of values to listtype
- 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.
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.
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.
transformer
- The transformer to apply
- 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.
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.
- the single result or null