| org.hibernate.Query
All known Subclasses: org.hibernate.impl.AbstractQueryImpl,
| Query | | public interface Query (Code) | | 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: org.hibernate.Session.createQuery(java.lang.String)
See Also: org.hibernate.ScrollableResults
author:
Gavin King |
| Method Summary | |
| public int | executeUpdate()
Execute the update or delete statement. | | public String[] | getNamedParameters()
Return the names of all named parameters of the query. | | public String | getQueryString()
Get the query string. | | public String[] | getReturnAliases()
| | public Type[] | getReturnTypes()
Return the Hibernate types of the query result set. | | public Iterator | iterate()
Return the query results as an Iterator. | | public List | list()
Return the query results as a List. | | public ScrollableResults | scroll()
Return the query results as ScrollableResults. | | public ScrollableResults | scroll(ScrollMode scrollMode)
Return the query results as ScrollableResults. | | public Query | setBigDecimal(int position, BigDecimal number)
| | public Query | setBigDecimal(String name, BigDecimal number)
| | public Query | setBigInteger(int position, BigInteger number)
| | public Query | setBigInteger(String name, BigInteger number)
| | public Query | setBinary(int position, byte[] val)
| | public Query | setBinary(String name, byte[] val)
| | public Query | setBoolean(int position, boolean val)
| | public Query | setBoolean(String name, boolean val)
| | public Query | setByte(int position, byte val)
| | public Query | setByte(String name, byte val)
| | public Query | setCacheMode(CacheMode cacheMode)
Override the current session cache mode, just for
this query. | | public Query | setCacheRegion(String cacheRegion)
Set the name of the cache region. | | public Query | setCacheable(boolean cacheable)
Enable caching of this query result set. | | public Query | setCalendar(int position, Calendar calendar)
| | public Query | setCalendar(String name, Calendar calendar)
| | public Query | setCalendarDate(int position, Calendar calendar)
| | public Query | setCalendarDate(String name, Calendar calendar)
| | public Query | setCharacter(int position, char val)
| | public Query | setCharacter(String name, char val)
| | public Query | setComment(String comment)
Add a comment to the generated SQL. | | public Query | setDate(int position, Date date)
| | public Query | setDate(String name, Date date)
| | public Query | setDouble(int position, double val)
| | public Query | setDouble(String name, double val)
| | public Query | setEntity(int position, Object val)
Bind an instance of a mapped persistent class to a JDBC-style query parameter. | | public Query | setEntity(String name, Object val)
Bind an instance of a mapped persistent class to a named query parameter. | | public Query | setFetchSize(int fetchSize)
Set a fetch size for the underlying JDBC query. | | public Query | setFirstResult(int firstResult)
Set the first row to retrieve. | | public Query | setFloat(int position, float val)
| | public Query | setFloat(String name, float val)
| | public Query | setFlushMode(FlushMode flushMode)
Override the current session flush mode, just for
this query. | | public Query | setInteger(int position, int val)
| | public Query | setInteger(String name, int val)
| | public Query | setLocale(int position, Locale locale)
| | public Query | setLocale(String name, Locale locale)
| | public Query | setLockMode(String alias, LockMode lockMode)
Set the lockmode for the objects idententified by the
given alias that appears in the FROM clause. | | public Query | setLong(int position, long val)
| | public Query | setLong(String name, long val)
| | public Query | setMaxResults(int maxResults)
Set the maximum number of rows to retrieve. | | public Query | setParameter(int position, Object val, Type type)
Bind a value to a JDBC-style query parameter. | | public Query | setParameter(String name, Object val, Type type)
Bind a value to a named query parameter. | | public Query | setParameter(int position, Object val)
Bind a value to a JDBC-style query parameter. | | public Query | setParameter(String name, Object val)
Bind a value to a named query parameter. | | public Query | setParameterList(String name, Collection vals, Type type)
Bind multiple values to a named query parameter. | | public Query | setParameterList(String name, Collection vals)
Bind multiple values to a named query parameter. | | public Query | setParameterList(String name, Object[] vals, Type type)
Bind multiple values to a named query parameter. | | public Query | setParameterList(String name, Object[] vals)
Bind multiple values to a named query parameter. | | public Query | setParameters(Object[] values, Type[] types)
Bind values and types to positional parameters. | | public 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. | | public 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. | | 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. | | public Query | setResultTransformer(ResultTransformer transformer)
Set a strategy for handling the query results. | | public Query | setSerializable(int position, Serializable val)
| | public Query | setSerializable(String name, Serializable val)
| | public Query | setShort(int position, short val)
| | public Query | setShort(String name, short val)
| | public Query | setString(int position, String val)
| | public Query | setString(String name, String val)
| | public Query | setText(int position, String val)
| | public Query | setText(String name, String val)
| | public Query | setTime(int position, Date date)
| | public Query | setTime(String name, Date date)
| | public Query | setTimeout(int timeout)
Set a timeout for the underlying JDBC query. | | public Query | setTimestamp(int position, Date date)
| | public Query | setTimestamp(String name, Date date)
| | public Object | uniqueResult()
Convenience method to return a single instance that matches
the query, or null if the query returns no results. |
| executeUpdate | | public int executeUpdate() throws HibernateException(Code) | | Execute the update or delete statement.
The semantics are compliant with the ejb3 Query.executeUpdate()
method.
The number of entities updated or deleted.
throws:
HibernateException - |
| getNamedParameters | | public String[] getNamedParameters() throws HibernateException(Code) | | Return the names of all named parameters of the query.
the parameter names, in no particular order |
| getQueryString | | public String getQueryString()(Code) | | Get the query string.
the query string |
| getReturnAliases | | public String[] getReturnAliases() throws HibernateException(Code) | | Return the HQL select clause aliases (if any)
an array of aliases as strings |
| getReturnTypes | | public Type[] getReturnTypes() throws HibernateException(Code) | | Return the Hibernate types of the query result set.
an array of types |
| iterate | | public Iterator iterate() throws HibernateException(Code) | | 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.
the result iterator
throws:
HibernateException - |
| list | | public List list() throws HibernateException(Code) | | Return the query results as a List. If the query contains
multiple results pre row, the results are returned in an instance
of Object[].
the result list
throws:
HibernateException - |
| setBinary | | public Query setBinary(int position, byte[] val)(Code) | | |
| setBoolean | | public Query setBoolean(int position, boolean val)(Code) | | |
| setByte | | public Query setByte(int position, byte val)(Code) | | |
| setCacheRegion | | public Query setCacheRegion(String cacheRegion)(Code) | | Set the name of the cache region.
Parameters:
cacheRegion - the name of a query cache region, or nullfor the default query cache |
| setCacheable | | public Query setCacheable(boolean cacheable)(Code) | | Enable caching of this query result set.
Parameters:
cacheable - Should the query results be cacheable? |
| setCharacter | | public Query setCharacter(int position, char val)(Code) | | |
| setComment | | public Query setComment(String comment)(Code) | | Add a comment to the generated SQL.
Parameters:
comment - a human-readable string |
| setDouble | | public Query setDouble(int position, double val)(Code) | | |
| setEntity | | public Query setEntity(int position, Object val)(Code) | | Bind an instance of a mapped persistent class to a JDBC-style query parameter.
Parameters:
position - the position of the parameter in the querystring, numbered from 0.
Parameters:
val - a non-null instance of a persistent class |
| setEntity | | public Query setEntity(String name, Object val)(Code) | | Bind an instance of a mapped persistent class to a named query parameter.
Parameters:
name - the name of the parameter
Parameters:
val - a non-null instance of a persistent class |
| setFetchSize | | public Query setFetchSize(int fetchSize)(Code) | | Set a fetch size for the underlying JDBC query.
Parameters:
fetchSize - the fetch size |
| setFirstResult | | public Query setFirstResult(int firstResult)(Code) | | 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(int position, float val)(Code) | | |
| setInteger | | public Query setInteger(int position, int val)(Code) | | |
| setLockMode | | public Query setLockMode(String alias, LockMode lockMode)(Code) | | 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(int position, long val)(Code) | | |
| setMaxResults | | public Query setMaxResults(int maxResults)(Code) | | 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(int position, Object val, Type type)(Code) | | Bind a value to a JDBC-style query parameter.
Parameters:
position - the position of the parameter in the querystring, numbered from 0.
Parameters:
val - the possibly-null parameter value
Parameters:
type - the Hibernate type |
| setParameter | | public Query setParameter(String name, Object val, Type type)(Code) | | Bind a value to a named query parameter.
Parameters:
name - the name of the parameter
Parameters:
val - the possibly-null parameter value
Parameters:
type - the Hibernate type |
| setParameter | | public Query setParameter(int position, Object val) throws HibernateException(Code) | | 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 querystring, numbered from 0.
Parameters:
val - the non-null parameter value
throws:
org.hibernate.HibernateException - if no type could be determined |
| setParameter | | public Query setParameter(String name, Object val) throws HibernateException(Code) | | 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
Parameters:
val - the non-null parameter value
throws:
org.hibernate.HibernateException - if no type could be determined |
| setParameterList | | public Query setParameterList(String name, Collection vals, Type type) throws HibernateException(Code) | | 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
Parameters:
vals - a collection of values to list
Parameters:
type - the Hibernate type of the values |
| setParameterList | | public Query setParameterList(String name, Collection vals) throws HibernateException(Code) | | 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
Parameters:
vals - a collection of values to list |
| setParameterList | | public Query setParameterList(String name, Object[] vals, Type type) throws HibernateException(Code) | | 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
Parameters:
vals - a collection of values to list
Parameters:
type - the Hibernate type of the values |
| setParameterList | | public Query setParameterList(String name, Object[] vals) throws HibernateException(Code) | | 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
Parameters:
vals - a collection of values to list |
| setProperties | | public Query setProperties(Object bean) throws HibernateException(Code) | | 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 |
| setProperties | | public Query setProperties(Map bean) throws HibernateException(Code) | | 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 |
| setReadOnly | | public Query setReadOnly(boolean readOnly)(Code) | | 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)(Code) | | 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 this (for method chaining) |
| setShort | | public Query setShort(int position, short val)(Code) | | |
| setTimeout | | public Query setTimeout(int timeout)(Code) | | Set a timeout for the underlying JDBC query.
Parameters:
timeout - the timeout in seconds |
| uniqueResult | | public Object uniqueResult() throws HibernateException(Code) | | Convenience method to return a single instance that matches
the query, or null if the query returns no results.
the single result or null
throws:
NonUniqueResultException - if there is more than one matching result |
|
|