## 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.
`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.
`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` `setLockOptions(LockOptions lockOptions)` Set the lock options 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)` Set the read-only/modifiable mode for entities and proxies loaded by this Query.
`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 `ResultSet`s.

  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 `ResultSet`s.

  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`

### isReadOnly

    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:
    `setReadOnly(boolean)`, `The read-only/modifiable setting has no impact on entities/proxies returned by the query that existed in the session before the query was executed.`

### setReadOnly

    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:
    `To set the default read-only/modifiable setting used for entities and proxies that are loaded into the session:`, `PersistenceContext.setDefaultReadOnly(boolean)`, `Read-only entities are not dirty-checked and snapshots of persistent state are not maintained. Read-only entities can be modified, but changes are not persisted. When a proxy is initialized, the loaded entity will have the same read-only/modifiable setting as the uninitialized proxy has, regardless of the session's current setting. The read-only/modifiable setting has no impact on entities/proxies returned by the query that existed in the session before the query was executed.`

### 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

### setLockOptions

    Query setLockOptions(LockOptions lockOptions)

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

### 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)

Copyright © 2001-2010 Red Hat, Inc. All Rights Reserved.