站内搜索: 请输入搜索关键词
当前页面: 在线文档首页 > Hibernate 2.1.8 正式版 API 英文文档

Query (Hibernate API Documentation) - Hibernate 2.1.8 正式版 API 英文文档

Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

net.sf.hibernate
Interface Query

All Known Implementing Classes:
AbstractQueryImpl
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():


Use of setFirstResult() requires that the JDBC driver implement scrollable result sets.

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
 String[] getNamedParameters()
          Return the names of all named parameters of the query.
 String getQueryString()
          Get the query string.
 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 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 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 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 setEnum(int position, Object val)
          Deprecated. Support for PersistentEnums will be removed in 2.2
 Query setEnum(String name, Object val)
          Deprecated. Support for PersistentEnums will be removed in 2.2
 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 setForceCacheRefresh(boolean forceCacheRefresh)
          Should the query force a refresh of the specified query cache region? This is particularly useful in cases where underlying data may have been updated via a seperate process (i.e., not modified through Hibernate) and allows the application to selectively refresh the query cache regions based on its knowledge of those events.
 Query setInteger(int position, int val)
           
 Query setInteger(String name, int val)
           
 Query setLocale(int position, Locale locale)
           
 Query setLocale(String name, Locale locale)
           
 void 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, guessing the Hibernate type from the class of the given object.
 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, guessing the Hibernate type from the class of the given object.
 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, guessing the Hibernate type from the class of the first object in the collection.
 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, guessing the Hibernate type from the class of the first object in the array.
 Query setParameterList(String name, Object[] vals, Type type)
          Bind multiple values to a named query parameter.
 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 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

public String getQueryString()
Get the query string.

Returns:
the query string

getReturnTypes

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

Returns:
an array of types
Throws:
HibernateException

getNamedParameters

public 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

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
Throws:
HibernateException

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.

Entities returned as results are initialized on demand. The first SQL query returns identifier only.

Returns:
the result iterator
Throws:
HibernateException
See Also:
ScrollableResults

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
Throws:
HibernateException
See Also:
ScrollableResults, ScrollMode

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
Throws:
HibernateException

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
Throws:
HibernateException - if there is more than one matching result

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

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

setCacheable

public Query setCacheable(boolean cacheable)
Enable caching of this query result set.

Parameters:
cacheable - Should the query results be cacheable?

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

setForceCacheRefresh

public Query setForceCacheRefresh(boolean forceCacheRefresh)
Should the query force a refresh of the specified query cache region? This is particularly useful in cases where underlying data may have been updated via a seperate process (i.e., not modified through Hibernate) and allows the application to selectively refresh the query cache regions based on its knowledge of those events.

Parameters:
forceCacheRefresh - Should the query result in a forceable refresh of the query cache?

setTimeout

public Query setTimeout(int timeout)
Set a timeout for the underlying JDBC query.

Parameters:
timeout - the timeout in seconds

setFetchSize

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

Parameters:
fetchSize - the fetch size

setLockMode

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

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

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, guessing the Hibernate type 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(String name,
                          Object val)
                   throws HibernateException
Bind a value to a named query parameter, guessing the Hibernate type 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

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
Throws:
HibernateException

setParameterList

public Query setParameterList(String name,
                              Collection vals)
                       throws HibernateException
Bind multiple values to a named query parameter, guessing the Hibernate type 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

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
Throws:
HibernateException

setParameterList

public Query setParameterList(String name,
                              Object[] vals)
                       throws HibernateException
Bind multiple values to a named query parameter, guessing the Hibernate type 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

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
Throws:
HibernateException

setString

public Query setString(int position,
                       String val)

setCharacter

public Query setCharacter(int position,
                          char val)

setBoolean

public Query setBoolean(int position,
                        boolean val)

setByte

public Query setByte(int position,
                     byte val)

setShort

public Query setShort(int position,
                      short val)

setInteger

public Query setInteger(int position,
                        int val)

setLong

public Query setLong(int position,
                     long val)

setFloat

public Query setFloat(int position,
                      float val)

setDouble

public Query setDouble(int position,
                       double val)

setBinary

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

setText

public Query setText(int position,
                     String val)

setSerializable

public Query setSerializable(int position,
                             Serializable val)

setLocale

public Query setLocale(int position,
                       Locale locale)

setBigDecimal

public Query setBigDecimal(int position,
                           BigDecimal number)

setDate

public Query setDate(int position,
                     Date date)

setTime

public Query setTime(int position,
                     Date date)

setTimestamp

public Query setTimestamp(int position,
                          Date date)

setCalendar

public Query setCalendar(int position,
                         Calendar calendar)

setCalendarDate

public Query setCalendarDate(int position,
                             Calendar calendar)

setString

public Query setString(String name,
                       String val)

setCharacter

public Query setCharacter(String name,
                          char val)

setBoolean

public Query setBoolean(String name,
                        boolean val)

setByte

public Query setByte(String name,
                     byte val)

setShort

public Query setShort(String name,
                      short val)

setInteger

public Query setInteger(String name,
                        int val)

setLong

public Query setLong(String name,
                     long val)

setFloat

public Query setFloat(String name,
                      float val)

setDouble

public Query setDouble(String name,
                       double val)

setBinary

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

setText

public Query setText(String name,
                     String val)

setSerializable

public Query setSerializable(String name,
                             Serializable val)

setLocale

public Query setLocale(String name,
                       Locale locale)

setBigDecimal

public Query setBigDecimal(String name,
                           BigDecimal number)

setDate

public Query setDate(String name,
                     Date date)

setTime

public Query setTime(String name,
                     Date date)

setTimestamp

public Query setTimestamp(String name,
                          Date date)

setCalendar

public Query setCalendar(String name,
                         Calendar calendar)

setCalendarDate

public Query setCalendarDate(String name,
                             Calendar calendar)

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

setEnum

public Query setEnum(int position,
                     Object val)
              throws MappingException
Deprecated. Support for PersistentEnums will be removed in 2.2

Bind an instance of a persistent enumeration 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 enumeration
Throws:
MappingException

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

setEnum

public Query setEnum(String name,
                     Object val)
              throws MappingException
Deprecated. Support for PersistentEnums will be removed in 2.2

Bind an instance of a mapped persistent enumeration class to a named query parameter.

Parameters:
name - the name of the parameter
val - a non-null instance of a persistent enumeration
Throws:
MappingException
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD