001: //$Id: Query.java 10590 2006-10-17 08:57:22Z max.andersen@jboss.com $
002: package org.hibernate;
003:
004: import java.io.Serializable;
005: import java.math.BigDecimal;
006: import java.math.BigInteger;
007: import java.util.Calendar;
008: import java.util.Collection;
009: import java.util.Date;
010: import java.util.Iterator;
011: import java.util.List;
012: import java.util.Locale;
013: import java.util.Map;
014:
015: import org.hibernate.transform.ResultTransformer;
016: import org.hibernate.type.Type;
017:
018: /**
019: * An object-oriented representation of a Hibernate query. A <tt>Query</tt>
020: * instance is obtained by calling <tt>Session.createQuery()</tt>. This
021: * interface exposes some extra functionality beyond that provided by
022: * <tt>Session.iterate()</tt> and <tt>Session.find()</tt>:
023: * <ul>
024: * <li>a particular page of the result set may be selected by calling <tt>
025: * setMaxResults(), setFirstResult()</tt>
026: * <li>named query parameters may be used
027: * <li>the results may be returned as an instance of <tt>ScrollableResults</tt>
028: * </ul>
029: * <br>
030: * Named query parameters are tokens of the form <tt>:name</tt> in the
031: * query string. A value is bound to the <tt>integer</tt> parameter
032: * <tt>:foo</tt> by calling<br>
033: * <br>
034: * <tt>setParameter("foo", foo, Hibernate.INTEGER);</tt><br>
035: * <br>
036: * for example. A name may appear multiple times in the query string.<br>
037: * <br>
038: * JDBC-style <tt>?</tt> parameters are also supported. To bind a
039: * value to a JDBC-style parameter use a set method that accepts an
040: * <tt>int</tt> positional argument (numbered from zero, contrary
041: * to JDBC).<br>
042: * <br>
043: * You may not mix and match JDBC-style parameters and named parameters
044: * in the same query.<br>
045: * <br>
046: * Queries are executed by calling <tt>list()</tt>, <tt>scroll()</tt> or
047: * <tt>iterate()</tt>. A query may be re-executed by subsequent invocations.
048: * Its lifespan is, however, bounded by the lifespan of the <tt>Session</tt>
049: * that created it.<br>
050: * <br>
051: * Implementors are not intended to be threadsafe.
052: *
053: * @see org.hibernate.Session#createQuery(java.lang.String)
054: * @see org.hibernate.ScrollableResults
055: * @author Gavin King
056: */
057: public interface Query {
058: /**
059: * Get the query string.
060: *
061: * @return the query string
062: */
063: public String getQueryString();
064:
065: /**
066: * Return the Hibernate types of the query result set.
067: * @return an array of types
068: */
069: public Type[] getReturnTypes() throws HibernateException;
070:
071: /**
072: * Return the HQL select clause aliases (if any)
073: * @return an array of aliases as strings
074: */
075: public String[] getReturnAliases() throws HibernateException;
076:
077: /**
078: * Return the names of all named parameters of the query.
079: * @return the parameter names, in no particular order
080: */
081: public String[] getNamedParameters() throws HibernateException;
082:
083: /**
084: * Return the query results as an <tt>Iterator</tt>. If the query
085: * contains multiple results pre row, the results are returned in
086: * an instance of <tt>Object[]</tt>.<br>
087: * <br>
088: * Entities returned as results are initialized on demand. The first
089: * SQL query returns identifiers only.<br>
090: *
091: * @return the result iterator
092: * @throws HibernateException
093: */
094: public Iterator iterate() throws HibernateException;
095:
096: /**
097: * Return the query results as <tt>ScrollableResults</tt>. The
098: * scrollability of the returned results depends upon JDBC driver
099: * support for scrollable <tt>ResultSet</tt>s.<br>
100: *
101: * @see ScrollableResults
102: * @return the result iterator
103: * @throws HibernateException
104: */
105: public ScrollableResults scroll() throws HibernateException;
106:
107: /**
108: * Return the query results as <tt>ScrollableResults</tt>. The
109: * scrollability of the returned results depends upon JDBC driver
110: * support for scrollable <tt>ResultSet</tt>s.<br>
111: *
112: * @see ScrollableResults
113: * @see ScrollMode
114: * @return the result iterator
115: * @throws HibernateException
116: */
117: public ScrollableResults scroll(ScrollMode scrollMode)
118: throws HibernateException;
119:
120: /**
121: * Return the query results as a <tt>List</tt>. If the query contains
122: * multiple results pre row, the results are returned in an instance
123: * of <tt>Object[]</tt>.
124: *
125: * @return the result list
126: * @throws HibernateException
127: */
128: public List list() throws HibernateException;
129:
130: /**
131: * Convenience method to return a single instance that matches
132: * the query, or null if the query returns no results.
133: *
134: * @return the single result or <tt>null</tt>
135: * @throws NonUniqueResultException if there is more than one matching result
136: */
137: public Object uniqueResult() throws HibernateException;
138:
139: /**
140: * Execute the update or delete statement.
141: * </p>
142: * The semantics are compliant with the ejb3 Query.executeUpdate()
143: * method.
144: *
145: * @return The number of entities updated or deleted.
146: * @throws HibernateException
147: */
148: public int executeUpdate() throws HibernateException;
149:
150: /**
151: * Set the maximum number of rows to retrieve. If not set,
152: * there is no limit to the number of rows retrieved.
153: * @param maxResults the maximum number of rows
154: */
155: public Query setMaxResults(int maxResults);
156:
157: /**
158: * Set the first row to retrieve. If not set, rows will be
159: * retrieved beginnning from row <tt>0</tt>.
160: * @param firstResult a row number, numbered from <tt>0</tt>
161: */
162: public Query setFirstResult(int firstResult);
163:
164: /**
165: * Entities retrieved by this query will be loaded in
166: * a read-only mode where Hibernate will never dirty-check
167: * them or make changes persistent.
168: *
169: */
170: public Query setReadOnly(boolean readOnly);
171:
172: /**
173: * Enable caching of this query result set.
174: * @param cacheable Should the query results be cacheable?
175: */
176: public Query setCacheable(boolean cacheable);
177:
178: /**
179: * Set the name of the cache region.
180: * @param cacheRegion the name of a query cache region, or <tt>null</tt>
181: * for the default query cache
182: */
183: public Query setCacheRegion(String cacheRegion);
184:
185: /**
186: * Set a timeout for the underlying JDBC query.
187: * @param timeout the timeout in seconds
188: */
189: public Query setTimeout(int timeout);
190:
191: /**
192: * Set a fetch size for the underlying JDBC query.
193: * @param fetchSize the fetch size
194: */
195: public Query setFetchSize(int fetchSize);
196:
197: /**
198: * Set the lockmode for the objects idententified by the
199: * given alias that appears in the <tt>FROM</tt> clause.
200: * @param alias a query alias, or <tt>this</tt> for a collection filter
201: */
202: public Query setLockMode(String alias, LockMode lockMode);
203:
204: /**
205: * Add a comment to the generated SQL.
206: * @param comment a human-readable string
207: */
208: public Query setComment(String comment);
209:
210: /**
211: * Override the current session flush mode, just for
212: * this query.
213: * @see org.hibernate.FlushMode
214: */
215: public Query setFlushMode(FlushMode flushMode);
216:
217: /**
218: * Override the current session cache mode, just for
219: * this query.
220: * @see org.hibernate.CacheMode
221: */
222: public Query setCacheMode(CacheMode cacheMode);
223:
224: /**
225: * Bind a value to a JDBC-style query parameter.
226: * @param position the position of the parameter in the query
227: * string, numbered from <tt>0</tt>.
228: * @param val the possibly-null parameter value
229: * @param type the Hibernate type
230: */
231: public Query setParameter(int position, Object val, Type type);
232:
233: /**
234: * Bind a value to a named query parameter.
235: * @param name the name of the parameter
236: * @param val the possibly-null parameter value
237: * @param type the Hibernate type
238: */
239: public Query setParameter(String name, Object val, Type type);
240:
241: /**
242: * Bind a value to a JDBC-style query parameter. The Hibernate type of the parameter is
243: * first detected via the usage/position in the query and if not sufficient secondly
244: * guessed from the class of the given object.
245: * @param position the position of the parameter in the query
246: * string, numbered from <tt>0</tt>.
247: * @param val the non-null parameter value
248: * @throws org.hibernate.HibernateException if no type could be determined
249: */
250: public Query setParameter(int position, Object val)
251: throws HibernateException;
252:
253: /**
254: * Bind a value to a named query parameter. The Hibernate type of the parameter is
255: * first detected via the usage/position in the query and if not sufficient secondly
256: * guessed from the class of the given object.
257: * @param name the name of the parameter
258: * @param val the non-null parameter value
259: * @throws org.hibernate.HibernateException if no type could be determined
260: */
261: public Query setParameter(String name, Object val)
262: throws HibernateException;
263:
264: /**
265: * Bind values and types to positional parameters.
266: */
267: public Query setParameters(Object[] values, Type[] types)
268: throws HibernateException;
269:
270: /**
271: * Bind multiple values to a named query parameter. This is useful for binding
272: * a list of values to an expression such as <tt>foo.bar in (:value_list)</tt>.
273: * @param name the name of the parameter
274: * @param vals a collection of values to list
275: * @param type the Hibernate type of the values
276: */
277: public Query setParameterList(String name, Collection vals,
278: Type type) throws HibernateException;
279:
280: /**
281: * Bind multiple values to a named query parameter. The Hibernate type of the parameter is
282: * first detected via the usage/position in the query and if not sufficient secondly
283: * guessed from the class of the first object in the collection. This is useful for binding a list of values
284: * to an expression such as <tt>foo.bar in (:value_list)</tt>.
285: * @param name the name of the parameter
286: * @param vals a collection of values to list
287: */
288: public Query setParameterList(String name, Collection vals)
289: throws HibernateException;
290:
291: /**
292: * Bind multiple values to a named query parameter. This is useful for binding
293: * a list of values to an expression such as <tt>foo.bar in (:value_list)</tt>.
294: * @param name the name of the parameter
295: * @param vals a collection of values to list
296: * @param type the Hibernate type of the values
297: */
298: public Query setParameterList(String name, Object[] vals, Type type)
299: throws HibernateException;
300:
301: /**
302: * Bind multiple values to a named query parameter. The Hibernate type of the parameter is
303: * first detected via the usage/position in the query and if not sufficient secondly
304: * guessed from the class of the first object in the array. This is useful for binding a list of values
305: * to an expression such as <tt>foo.bar in (:value_list)</tt>.
306: * @param name the name of the parameter
307: * @param vals a collection of values to list
308: */
309: public Query setParameterList(String name, Object[] vals)
310: throws HibernateException;
311:
312: /**
313: * Bind the property values of the given bean to named parameters of the query,
314: * matching property names with parameter names and mapping property types to
315: * Hibernate types using hueristics.
316: * @param bean any JavaBean or POJO
317: */
318: public Query setProperties(Object bean) throws HibernateException;
319:
320: /**
321: * Bind the values of the given Map for each named parameters of the query,
322: * matching key names with parameter names and mapping value types to
323: * Hibernate types using hueristics.
324: * @param bean a java.util.Map
325: */
326: public Query setProperties(Map bean) throws HibernateException;
327:
328: public Query setString(int position, String val);
329:
330: public Query setCharacter(int position, char val);
331:
332: public Query setBoolean(int position, boolean val);
333:
334: public Query setByte(int position, byte val);
335:
336: public Query setShort(int position, short val);
337:
338: public Query setInteger(int position, int val);
339:
340: public Query setLong(int position, long val);
341:
342: public Query setFloat(int position, float val);
343:
344: public Query setDouble(int position, double val);
345:
346: public Query setBinary(int position, byte[] val);
347:
348: public Query setText(int position, String val);
349:
350: public Query setSerializable(int position, Serializable val);
351:
352: public Query setLocale(int position, Locale locale);
353:
354: public Query setBigDecimal(int position, BigDecimal number);
355:
356: public Query setBigInteger(int position, BigInteger number);
357:
358: public Query setDate(int position, Date date);
359:
360: public Query setTime(int position, Date date);
361:
362: public Query setTimestamp(int position, Date date);
363:
364: public Query setCalendar(int position, Calendar calendar);
365:
366: public Query setCalendarDate(int position, Calendar calendar);
367:
368: public Query setString(String name, String val);
369:
370: public Query setCharacter(String name, char val);
371:
372: public Query setBoolean(String name, boolean val);
373:
374: public Query setByte(String name, byte val);
375:
376: public Query setShort(String name, short val);
377:
378: public Query setInteger(String name, int val);
379:
380: public Query setLong(String name, long val);
381:
382: public Query setFloat(String name, float val);
383:
384: public Query setDouble(String name, double val);
385:
386: public Query setBinary(String name, byte[] val);
387:
388: public Query setText(String name, String val);
389:
390: public Query setSerializable(String name, Serializable val);
391:
392: public Query setLocale(String name, Locale locale);
393:
394: public Query setBigDecimal(String name, BigDecimal number);
395:
396: public Query setBigInteger(String name, BigInteger number);
397:
398: public Query setDate(String name, Date date);
399:
400: public Query setTime(String name, Date date);
401:
402: public Query setTimestamp(String name, Date date);
403:
404: public Query setCalendar(String name, Calendar calendar);
405:
406: public Query setCalendarDate(String name, Calendar calendar);
407:
408: /**
409: * Bind an instance of a mapped persistent class to a JDBC-style query parameter.
410: * @param position the position of the parameter in the query
411: * string, numbered from <tt>0</tt>.
412: * @param val a non-null instance of a persistent class
413: */
414: public Query setEntity(int position, Object val); // use setParameter for null values
415:
416: /**
417: * Bind an instance of a mapped persistent class to a named query parameter.
418: * @param name the name of the parameter
419: * @param val a non-null instance of a persistent class
420: */
421: public Query setEntity(String name, Object val); // use setParameter for null values
422:
423: /**
424: * Set a strategy for handling the query results. This can be used to change
425: * "shape" of the query result.
426: *
427: * @param transformer The transformer to apply
428: * @return this (for method chaining)
429: */
430: public Query setResultTransformer(ResultTransformer transformer);
431:
432: }
|