org.hibernate.Query Maven / Gradle / Ivy
//$Id: Query.java 10590 2006-10-17 08:57:22Z [email protected] $
package org.hibernate;
import java.io.Serializable;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.util.Calendar;
import java.util.Collection;
import java.util.Date;
import java.util.Iterator;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import org.hibernate.transform.ResultTransformer;
import org.hibernate.type.Type;
/**
* 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 org.hibernate.Session#createQuery(java.lang.String)
* @see org.hibernate.ScrollableResults
* @author gperrone
*/
public interface Query {
/**
* Get the query string.
*
* @return the query string
*/
public String getQueryString();
/**
* Return the Hibernate types of the query result set.
* @return an array of types
*/
public Type[] getReturnTypes() throws HibernateException;
/**
* Return the HQL select clause aliases (if any)
* @return an array of aliases as strings
*/
public String[] getReturnAliases() throws HibernateException;
/**
* Return the names of all named parameters of the query.
* @return the parameter names, in no particular order
*/
public String[] getNamedParameters() 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.
*
* @return the result iterator
* @throws HibernateException
*/
public Iterator iterate() throws HibernateException;
/**
* Return the query results as ScrollableResults. The
* scrollability of the returned results depends upon JDBC driver
* support for scrollable ResultSets.
*
* @see ScrollableResults
* @return the result iterator
* @throws HibernateException
*/
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.
*
* @see ScrollableResults
* @see ScrollMode
* @return the result iterator
* @throws HibernateException
*/
public ScrollableResults scroll(ScrollMode scrollMode) 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[].
*
* @return the result list
* @throws HibernateException
*/
public List list() throws HibernateException;
/**
* Return the query results count without extracting it. It works executing
* a select count(*) on the given query criteria filter
*
* @return the query filtered row count
* @throws HibernateException
*/
public int count() throws HibernateException;
/**
* Convenience method to return a single instance that matches
* the query, or null if the query returns no results.
*
* @return the single result or null
* @throws NonUniqueResultException if there is more than one matching result
*/
public Object uniqueResult() throws HibernateException;
/**
* Execute the update or delete statement.
*
* The semantics are compliant with the ejb3 Query.executeUpdate()
* method.
*
* @return The number of entities updated or deleted.
* @throws HibernateException
*/
public int executeUpdate() throws HibernateException;
/**
* Set the maximum number of rows to retrieve. If not set,
* there is no limit to the number of rows retrieved.
* @param maxResults the maximum number of rows
*/
public Query setMaxResults(int maxResults);
/**
* Set the first row to retrieve. If not set, rows will be
* retrieved beginnning from row 0.
* @param firstResult a row number, numbered from 0
*/
public Query setFirstResult(int firstResult);
/**
* 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 setReadOnly(boolean readOnly);
/**
* Enable caching of this query result set.
* @param cacheable Should the query results be cacheable?
*/
public Query setCacheable(boolean cacheable);
/**
* Set the name of the cache region.
* @param cacheRegion the name of a query cache region, or null
* for the default query cache
*/
public Query setCacheRegion(String cacheRegion);
/**
* Set a timeout for the underlying JDBC query.
* @param timeout the timeout in seconds
*/
public Query setTimeout(int timeout);
/**
* Set a fetch size for the underlying JDBC query.
* @param fetchSize the fetch size
*/
public Query setFetchSize(int fetchSize);
/**
* Set the lockmode for the objects idententified by the
* given alias that appears in the FROM clause.
* @param alias a query alias, or this for a collection filter
*/
public Query setLockMode(String alias, LockMode lockMode);
/**
* Add a comment to the generated SQL.
* @param comment a human-readable string
*/
public Query setComment(String comment);
/**
* Override the current session flush mode, just for
* this query.
* @see org.hibernate.FlushMode
*/
public Query setFlushMode(FlushMode flushMode);
/**
* Override the current session cache mode, just for
* this query.
* @see org.hibernate.CacheMode
*/
public Query setCacheMode(CacheMode cacheMode);
/**
* Bind a value to a JDBC-style query parameter.
* @param position the position of the parameter in the query
* string, numbered from 0.
* @param val the possibly-null parameter value
* @param type the Hibernate type
*/
public Query setParameter(int position, Object val, Type type);
/**
* Bind a value to a named query parameter.
* @param name the name of the parameter
* @param val the possibly-null parameter value
* @param type the Hibernate type
*/
public Query setParameter(String name, Object val, Type type);
/**
* 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.
* @param position the position of the parameter in the query
* string, numbered from 0.
* @param val the non-null parameter value
* @throws org.hibernate.HibernateException if no type could be determined
*/
public Query setParameter(int position, 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.
* @param name the name of the parameter
* @param val the non-null parameter value
* @throws org.hibernate.HibernateException if no type could be determined
*/
public Query setParameter(String name, Object val) throws HibernateException;
/**
* Bind values and types to positional parameters.
*/
public Query setParameters(Object[] values, Type[] types) 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).
* @param name the name of the parameter
* @param vals a collection of values to list
* @param type the Hibernate type of the values
*/
public Query setParameterList(String name, Collection vals, Type type) 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).
* @param name the name of the parameter
* @param vals a collection of values to list
*/
public Query setParameterList(String name, Collection vals) 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).
* @param name the name of the parameter
* @param vals a collection of values to list
* @param type the Hibernate type of the values
*/
public Query setParameterList(String name, Object[] vals, Type type) 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).
* @param name the name of the parameter
* @param vals a collection of values to list
*/
public Query setParameterList(String name, Object[] vals) 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.
* @param bean any JavaBean or POJO
*/
public Query setProperties(Object 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.
* @param bean a java.util.Map
*/
public Query setProperties(Map bean) throws HibernateException;
public Query setString(int position, String val);
public Query setCharacter(int position, char val);
public Query setBoolean(int position, boolean val);
public Query setByte(int position, byte val);
public Query setShort(int position, short val);
public Query setInteger(int position, int val);
public Query setLong(int position, long val);
public Query setFloat(int position, float val);
public Query setDouble(int position, double val);
public Query setBinary(int position, byte[] val);
public Query setText(int position, String val);
public Query setSerializable(int position, Serializable val);
public Query setLocale(int position, Locale locale);
public Query setBigDecimal(int position, BigDecimal number);
public Query setBigInteger(int position, BigInteger number);
public Query setDate(int position, Date date);
public Query setTime(int position, Date date);
public Query setTimestamp(int position, Date date);
public Query setCalendar(int position, Calendar calendar);
public Query setCalendarDate(int position, Calendar calendar);
public Query setString(String name, String val);
public Query setCharacter(String name, char val);
public Query setBoolean(String name, boolean val);
public Query setByte(String name, byte val);
public Query setShort(String name, short val);
public Query setInteger(String name, int val);
public Query setLong(String name, long val);
public Query setFloat(String name, float val);
public Query setDouble(String name, double val);
public Query setBinary(String name, byte[] val);
public Query setText(String name, String val);
public Query setSerializable(String name, Serializable val);
public Query setLocale(String name, Locale locale);
public Query setBigDecimal(String name, BigDecimal number);
public Query setBigInteger(String name, BigInteger number);
public Query setDate(String name, Date date);
public Query setTime(String name, Date date);
public Query setTimestamp(String name, Date date);
public Query setCalendar(String name, Calendar calendar);
public Query setCalendarDate(String name, Calendar calendar);
/**
* Bind an instance of a mapped persistent class to a JDBC-style query parameter.
* @param position the position of the parameter in the query
* string, numbered from 0.
* @param val a non-null instance of a persistent class
*/
public Query setEntity(int position, Object val); // use setParameter for null values
/**
* Bind an instance of a mapped persistent class to a named query parameter.
* @param name the name of the parameter
* @param val a non-null instance of a persistent class
*/
public Query setEntity(String name, Object val); // use setParameter for null values
/**
* Set a strategy for handling the query results. This can be used to change
* "shape" of the query result.
*
* @param transformer The transformer to apply
* @return this (for method chaining)
*/
public Query setResultTransformer(ResultTransformer transformer);
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy