1 //$Id: Query.java 10590 2006-10-17 08:57:22Z max.andersen@jboss.com $
2 package org.hibernate;
3
4 import java.io.Serializable;
5 import java.math.BigDecimal;
6 import java.math.BigInteger;
7 import java.util.Calendar;
8 import java.util.Collection;
9 import java.util.Date;
10 import java.util.Iterator;
11 import java.util.List;
12 import java.util.Locale;
13 import java.util.Map;
14
15 import org.hibernate.transform.ResultTransformer;
16 import org.hibernate.type.Type;
17
18 /**
19 * An object-oriented representation of a Hibernate query. A <tt>Query</tt>
20 * instance is obtained by calling <tt>Session.createQuery()</tt>. This
21 * interface exposes some extra functionality beyond that provided by
22 * <tt>Session.iterate()</tt> and <tt>Session.find()</tt>:
23 * <ul>
24 * <li>a particular page of the result set may be selected by calling <tt>
25 * setMaxResults(), setFirstResult()</tt>
26 * <li>named query parameters may be used
27 * <li>the results may be returned as an instance of <tt>ScrollableResults</tt>
28 * </ul>
29 * <br>
30 * Named query parameters are tokens of the form <tt>:name</tt> in the
31 * query string. A value is bound to the <tt>integer</tt> parameter
32 * <tt>:foo</tt> by calling<br>
33 * <br>
34 * <tt>setParameter("foo", foo, Hibernate.INTEGER);</tt><br>
35 * <br>
36 * for example. A name may appear multiple times in the query string.<br>
37 * <br>
38 * JDBC-style <tt>?</tt> parameters are also supported. To bind a
39 * value to a JDBC-style parameter use a set method that accepts an
40 * <tt>int</tt> positional argument (numbered from zero, contrary
41 * to JDBC).<br>
42 * <br>
43 * You may not mix and match JDBC-style parameters and named parameters
44 * in the same query.<br>
45 * <br>
46 * Queries are executed by calling <tt>list()</tt>, <tt>scroll()</tt> or
47 * <tt>iterate()</tt>. A query may be re-executed by subsequent invocations.
48 * Its lifespan is, however, bounded by the lifespan of the <tt>Session</tt>
49 * that created it.<br>
50 * <br>
51 * Implementors are not intended to be threadsafe.
52 *
53 * @see org.hibernate.Session#createQuery(java.lang.String)
54 * @see org.hibernate.ScrollableResults
55 * @author gperrone
56 */
57 public interface Query {
58 /**
59 * Get the query string.
60 *
61 * @return the query string
62 */
63 public String getQueryString();
64 /**
65 * Return the Hibernate types of the query result set.
66 * @return an array of types
67 */
68 public Type[] getReturnTypes() throws HibernateException;
69 /**
70 * Return the HQL select clause aliases (if any)
71 * @return an array of aliases as strings
72 */
73 public String[] getReturnAliases() throws HibernateException;
74 /**
75 * Return the names of all named parameters of the query.
76 * @return the parameter names, in no particular order
77 */
78 public String[] getNamedParameters() throws HibernateException;
79 /**
80 * Return the query results as an <tt>Iterator</tt>. If the query
81 * contains multiple results pre row, the results are returned in
82 * an instance of <tt>Object[]</tt>.<br>
83 * <br>
84 * Entities returned as results are initialized on demand. The first
85 * SQL query returns identifiers only.<br>
86 *
87 * @return the result iterator
88 * @throws HibernateException
89 */
90 public Iterator iterate() throws HibernateException;
91 /**
92 * Return the query results as <tt>ScrollableResults</tt>. The
93 * scrollability of the returned results depends upon JDBC driver
94 * support for scrollable <tt>ResultSet</tt>s.<br>
95 *
96 * @see ScrollableResults
97 * @return the result iterator
98 * @throws HibernateException
99 */
100 public ScrollableResults scroll() throws HibernateException;
101 /**
102 * Return the query results as <tt>ScrollableResults</tt>. The
103 * scrollability of the returned results depends upon JDBC driver
104 * support for scrollable <tt>ResultSet</tt>s.<br>
105 *
106 * @see ScrollableResults
107 * @see ScrollMode
108 * @return the result iterator
109 * @throws HibernateException
110 */
111 public ScrollableResults scroll(ScrollMode scrollMode) throws HibernateException;
112 /**
113 * Return the query results as a <tt>List</tt>. If the query contains
114 * multiple results pre row, the results are returned in an instance
115 * of <tt>Object[]</tt>.
116 *
117 * @return the result list
118 * @throws HibernateException
119 */
120 public List list() throws HibernateException;
121
122 /**
123 * Return the query results count without extracting it. It works executing
124 * a select count(*) on the given query criteria filter
125 *
126 * @return the query filtered row count
127 * @throws HibernateException
128 */
129 public int count() throws HibernateException;
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 * Set the first row to retrieve. If not set, rows will be
158 * retrieved beginnning from row <tt>0</tt>.
159 * @param firstResult a row number, numbered from <tt>0</tt>
160 */
161 public Query setFirstResult(int firstResult);
162
163 /**
164 * Entities retrieved by this query will be loaded in
165 * a read-only mode where Hibernate will never dirty-check
166 * them or make changes persistent.
167 *
168 */
169 public Query setReadOnly(boolean readOnly);
170
171 /**
172 * Enable caching of this query result set.
173 * @param cacheable Should the query results be cacheable?
174 */
175 public Query setCacheable(boolean cacheable);
176
177 /**
178 * Set the name of the cache region.
179 * @param cacheRegion the name of a query cache region, or <tt>null</tt>
180 * for the default query cache
181 */
182 public Query setCacheRegion(String cacheRegion);
183
184 /**
185 * Set a timeout for the underlying JDBC query.
186 * @param timeout the timeout in seconds
187 */
188 public Query setTimeout(int timeout);
189 /**
190 * Set a fetch size for the underlying JDBC query.
191 * @param fetchSize the fetch size
192 */
193 public Query setFetchSize(int fetchSize);
194
195 /**
196 * Set the lockmode for the objects idententified by the
197 * given alias that appears in the <tt>FROM</tt> clause.
198 * @param alias a query alias, or <tt>this</tt> for a collection filter
199 */
200 public Query setLockMode(String alias, LockMode lockMode);
201
202 /**
203 * Add a comment to the generated SQL.
204 * @param comment a human-readable string
205 */
206 public Query setComment(String comment);
207
208 /**
209 * Override the current session flush mode, just for
210 * this query.
211 * @see org.hibernate.FlushMode
212 */
213 public Query setFlushMode(FlushMode flushMode);
214
215 /**
216 * Override the current session cache mode, just for
217 * this query.
218 * @see org.hibernate.CacheMode
219 */
220 public Query setCacheMode(CacheMode cacheMode);
221
222 /**
223 * Bind a value to a JDBC-style query parameter.
224 * @param position the position of the parameter in the query
225 * string, numbered from <tt>0</tt>.
226 * @param val the possibly-null parameter value
227 * @param type the Hibernate type
228 */
229 public Query setParameter(int position, Object val, Type type);
230 /**
231 * Bind a value to a named query parameter.
232 * @param name the name of the parameter
233 * @param val the possibly-null parameter value
234 * @param type the Hibernate type
235 */
236 public Query setParameter(String name, Object val, Type type);
237
238 /**
239 * Bind a value to a JDBC-style query parameter. The Hibernate type of the parameter is
240 * first detected via the usage/position in the query and if not sufficient secondly
241 * guessed from the class of the given object.
242 * @param position the position of the parameter in the query
243 * string, numbered from <tt>0</tt>.
244 * @param val the non-null parameter value
245 * @throws org.hibernate.HibernateException if no type could be determined
246 */
247 public Query setParameter(int position, Object val) throws HibernateException;
248 /**
249 * Bind a value to a named query parameter. The Hibernate type of the parameter is
250 * first detected via the usage/position in the query and if not sufficient secondly
251 * guessed from the class of the given object.
252 * @param name the name of the parameter
253 * @param val the non-null parameter value
254 * @throws org.hibernate.HibernateException if no type could be determined
255 */
256 public Query setParameter(String name, Object val) throws HibernateException;
257
258 /**
259 * Bind values and types to positional parameters.
260 */
261 public Query setParameters(Object[] values, Type[] types) throws HibernateException;
262
263 /**
264 * Bind multiple values to a named query parameter. This is useful for binding
265 * a list of values to an expression such as <tt>foo.bar in (:value_list)</tt>.
266 * @param name the name of the parameter
267 * @param vals a collection of values to list
268 * @param type the Hibernate type of the values
269 */
270 public Query setParameterList(String name, Collection vals, Type type) throws HibernateException;
271
272 /**
273 * Bind multiple values to a named query parameter. The Hibernate type of the parameter is
274 * first detected via the usage/position in the query and if not sufficient secondly
275 * guessed from the class of the first object in the collection. This is useful for binding a list of values
276 * to an expression such as <tt>foo.bar in (:value_list)</tt>.
277 * @param name the name of the parameter
278 * @param vals a collection of values to list
279 */
280 public Query setParameterList(String name, Collection vals) throws HibernateException;
281
282 /**
283 * Bind multiple values to a named query parameter. This is useful for binding
284 * a list of values 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 * @param type the Hibernate type of the values
288 */
289 public Query setParameterList(String name, Object[] vals, Type type) throws HibernateException;
290
291 /**
292 * Bind multiple values to a named query parameter. The Hibernate type of the parameter is
293 * first detected via the usage/position in the query and if not sufficient secondly
294 * guessed from the class of the first object in the array. This is useful for binding a list of values
295 * to an expression such as <tt>foo.bar in (:value_list)</tt>.
296 * @param name the name of the parameter
297 * @param vals a collection of values to list
298 */
299 public Query setParameterList(String name, Object[] vals) throws HibernateException;
300
301 /**
302 * Bind the property values of the given bean to named parameters of the query,
303 * matching property names with parameter names and mapping property types to
304 * Hibernate types using hueristics.
305 * @param bean any JavaBean or POJO
306 */
307 public Query setProperties(Object bean) throws HibernateException;
308
309 /**
310 * Bind the values of the given Map for each named parameters of the query,
311 * matching key names with parameter names and mapping value types to
312 * Hibernate types using hueristics.
313 * @param bean a java.util.Map
314 */
315 public Query setProperties(Map bean) throws HibernateException;
316
317
318 public Query setString(int position, String val);
319 public Query setCharacter(int position, char val);
320 public Query setBoolean(int position, boolean val);
321 public Query setByte(int position, byte val);
322 public Query setShort(int position, short val);
323 public Query setInteger(int position, int val);
324 public Query setLong(int position, long val);
325 public Query setFloat(int position, float val);
326 public Query setDouble(int position, double val);
327 public Query setBinary(int position, byte[] val);
328 public Query setText(int position, String val);
329 public Query setSerializable(int position, Serializable val);
330 public Query setLocale(int position, Locale locale);
331 public Query setBigDecimal(int position, BigDecimal number);
332 public Query setBigInteger(int position, BigInteger number);
333
334 public Query setDate(int position, Date date);
335 public Query setTime(int position, Date date);
336 public Query setTimestamp(int position, Date date);
337
338 public Query setCalendar(int position, Calendar calendar);
339 public Query setCalendarDate(int position, Calendar calendar);
340
341 public Query setString(String name, String val);
342 public Query setCharacter(String name, char val);
343 public Query setBoolean(String name, boolean val);
344 public Query setByte(String name, byte val);
345 public Query setShort(String name, short val);
346 public Query setInteger(String name, int val);
347 public Query setLong(String name, long val);
348 public Query setFloat(String name, float val);
349 public Query setDouble(String name, double val);
350 public Query setBinary(String name, byte[] val);
351 public Query setText(String name, String val);
352 public Query setSerializable(String name, Serializable val);
353 public Query setLocale(String name, Locale locale);
354 public Query setBigDecimal(String name, BigDecimal number);
355 public Query setBigInteger(String name, BigInteger number);
356
357 public Query setDate(String name, Date date);
358 public Query setTime(String name, Date date);
359 public Query setTimestamp(String name, Date date);
360
361 public Query setCalendar(String name, Calendar calendar);
362 public Query setCalendarDate(String name, Calendar calendar);
363
364 /**
365 * Bind an instance of a mapped persistent class to a JDBC-style query parameter.
366 * @param position the position of the parameter in the query
367 * string, numbered from <tt>0</tt>.
368 * @param val a non-null instance of a persistent class
369 */
370 public Query setEntity(int position, Object val); // use setParameter for null values
371
372 /**
373 * Bind an instance of a mapped persistent class to a named query parameter.
374 * @param name the name of the parameter
375 * @param val a non-null instance of a persistent class
376 */
377 public Query setEntity(String name, Object val); // use setParameter for null values
378
379
380 /**
381 * Set a strategy for handling the query results. This can be used to change
382 * "shape" of the query result.
383 *
384 * @param transformer The transformer to apply
385 * @return this (for method chaining)
386 */
387 public Query setResultTransformer(ResultTransformer transformer);
388
389 }
390
391
392
393
394
395
396