Package 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.
See Also:

  • Method Details

    • 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 ResultSets.
      Returns:
      the result iterator
      Throws:
      HibernateException
      See Also:

    • 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 ResultSets.
      Returns:
      the result iterator
      Throws:
      HibernateException
      See Also:

    • 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

      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:

    • 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:

    • setCacheMode

      Query setCacheMode(CacheMode cacheMode)
      Override the current session cache mode, just for this query.
      See Also:

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