Details | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
33 | PointedEar | 1 | /* |
2 | * Hibernate, Relational Persistence for Idiomatic Java |
||
3 | * |
||
4 | * Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as |
||
5 | * indicated by the @author tags or express copyright attribution |
||
6 | * statements applied by the authors. All third-party contributions are |
||
7 | * distributed under license by Red Hat Middleware LLC. |
||
8 | * |
||
9 | * This copyrighted material is made available to anyone wishing to use, modify, |
||
10 | * copy, or redistribute it subject to the terms and conditions of the GNU |
||
11 | * Lesser General Public License, as published by the Free Software Foundation. |
||
12 | * |
||
13 | * This program is distributed in the hope that it will be useful, |
||
14 | * but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY |
||
15 | * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License |
||
16 | * for more details. |
||
17 | * |
||
18 | * You should have received a copy of the GNU Lesser General Public License |
||
19 | * along with this distribution; if not, write to: |
||
20 | * Free Software Foundation, Inc. |
||
21 | * 51 Franklin Street, Fifth Floor |
||
22 | * Boston, MA 02110-1301 USA |
||
23 | * |
||
24 | */ |
||
25 | package org.hibernate; |
||
26 | |||
27 | import java.io.Serializable; |
||
28 | import java.math.BigDecimal; |
||
29 | import java.math.BigInteger; |
||
30 | import java.util.Calendar; |
||
31 | import java.util.Collection; |
||
32 | import java.util.Date; |
||
33 | import java.util.Iterator; |
||
34 | import java.util.List; |
||
35 | import java.util.Locale; |
||
36 | import java.util.Map; |
||
37 | |||
38 | import org.hibernate.transform.ResultTransformer; |
||
39 | import org.hibernate.type.Type; |
||
40 | |||
41 | /** |
||
42 | * An object-oriented representation of a Hibernate query. A <tt>Query</tt> |
||
43 | * instance is obtained by calling <tt>Session.createQuery()</tt>. This |
||
44 | * interface exposes some extra functionality beyond that provided by |
||
45 | * <tt>Session.iterate()</tt> and <tt>Session.find()</tt>: |
||
46 | * <ul> |
||
47 | * <li>a particular page of the result set may be selected by calling <tt> |
||
48 | * setMaxResults(), setFirstResult()</tt> |
||
49 | * <li>named query parameters may be used |
||
50 | * <li>the results may be returned as an instance of <tt>ScrollableResults</tt> |
||
51 | * </ul> |
||
52 | * <br> |
||
53 | * Named query parameters are tokens of the form <tt>:name</tt> in the |
||
54 | * query string. A value is bound to the <tt>integer</tt> parameter |
||
55 | * <tt>:foo</tt> by calling<br> |
||
56 | * <br> |
||
57 | * <tt>setParameter("foo", foo, Hibernate.INTEGER);</tt><br> |
||
58 | * <br> |
||
59 | * for example. A name may appear multiple times in the query string.<br> |
||
60 | * <br> |
||
61 | * JDBC-style <tt>?</tt> parameters are also supported. To bind a |
||
62 | * value to a JDBC-style parameter use a set method that accepts an |
||
63 | * <tt>int</tt> positional argument (numbered from zero, contrary |
||
64 | * to JDBC).<br> |
||
65 | * <br> |
||
66 | * You may not mix and match JDBC-style parameters and named parameters |
||
67 | * in the same query.<br> |
||
68 | * <br> |
||
69 | * Queries are executed by calling <tt>list()</tt>, <tt>scroll()</tt> or |
||
70 | * <tt>iterate()</tt>. A query may be re-executed by subsequent invocations. |
||
71 | * Its lifespan is, however, bounded by the lifespan of the <tt>Session</tt> |
||
72 | * that created it.<br> |
||
73 | * <br> |
||
74 | * Implementors are not intended to be threadsafe. |
||
75 | * |
||
76 | * @see org.hibernate.Session#createQuery(java.lang.String) |
||
77 | * @see org.hibernate.ScrollableResults |
||
78 | * @author Gavin King |
||
79 | */ |
||
80 | public interface Query { |
||
81 | /** |
||
82 | * Get the query string. |
||
83 | * |
||
84 | * @return the query string |
||
85 | */ |
||
86 | public String getQueryString(); |
||
87 | /** |
||
88 | * Return the Hibernate types of the query result set. |
||
89 | * @return an array of types |
||
90 | */ |
||
91 | public Type[] getReturnTypes() throws HibernateException; |
||
92 | /** |
||
93 | * Return the HQL select clause aliases (if any) |
||
94 | * @return an array of aliases as strings |
||
95 | */ |
||
96 | public String[] getReturnAliases() throws HibernateException; |
||
97 | /** |
||
98 | * Return the names of all named parameters of the query. |
||
99 | * @return the parameter names, in no particular order |
||
100 | */ |
||
101 | public String[] getNamedParameters() throws HibernateException; |
||
102 | /** |
||
103 | * Return the query results as an <tt>Iterator</tt>. If the query |
||
104 | * contains multiple results pre row, the results are returned in |
||
105 | * an instance of <tt>Object[]</tt>.<br> |
||
106 | * <br> |
||
107 | * Entities returned as results are initialized on demand. The first |
||
108 | * SQL query returns identifiers only.<br> |
||
109 | * |
||
110 | * @return the result iterator |
||
111 | * @throws HibernateException |
||
112 | */ |
||
113 | public Iterator iterate() throws HibernateException; |
||
114 | /** |
||
115 | * Return the query results as <tt>ScrollableResults</tt>. The |
||
116 | * scrollability of the returned results depends upon JDBC driver |
||
117 | * support for scrollable <tt>ResultSet</tt>s.<br> |
||
118 | * |
||
119 | * @see ScrollableResults |
||
120 | * @return the result iterator |
||
121 | * @throws HibernateException |
||
122 | */ |
||
123 | public ScrollableResults scroll() throws HibernateException; |
||
124 | /** |
||
125 | * Return the query results as <tt>ScrollableResults</tt>. The |
||
126 | * scrollability of the returned results depends upon JDBC driver |
||
127 | * support for scrollable <tt>ResultSet</tt>s.<br> |
||
128 | * |
||
129 | * @see ScrollableResults |
||
130 | * @see ScrollMode |
||
131 | * @return the result iterator |
||
132 | * @throws HibernateException |
||
133 | */ |
||
134 | public ScrollableResults scroll(ScrollMode scrollMode) throws HibernateException; |
||
135 | /** |
||
136 | * Return the query results as a <tt>List</tt>. If the query contains |
||
137 | * multiple results pre row, the results are returned in an instance |
||
138 | * of <tt>Object[]</tt>. |
||
139 | * |
||
140 | * @return the result list |
||
141 | * @throws HibernateException |
||
142 | */ |
||
143 | public List list() throws HibernateException; |
||
144 | /** |
||
145 | * Convenience method to return a single instance that matches |
||
146 | * the query, or null if the query returns no results. |
||
147 | * |
||
148 | * @return the single result or <tt>null</tt> |
||
149 | * @throws NonUniqueResultException if there is more than one matching result |
||
150 | */ |
||
151 | public Object uniqueResult() throws HibernateException; |
||
152 | |||
153 | /** |
||
154 | * Execute the update or delete statement. |
||
155 | * </p> |
||
156 | * The semantics are compliant with the ejb3 Query.executeUpdate() |
||
157 | * method. |
||
158 | * |
||
159 | * @return The number of entities updated or deleted. |
||
160 | * @throws HibernateException |
||
161 | */ |
||
162 | public int executeUpdate() throws HibernateException; |
||
163 | |||
164 | /** |
||
165 | * Set the maximum number of rows to retrieve. If not set, |
||
166 | * there is no limit to the number of rows retrieved. |
||
167 | * @param maxResults the maximum number of rows |
||
168 | */ |
||
169 | public Query setMaxResults(int maxResults); |
||
170 | /** |
||
171 | * Set the first row to retrieve. If not set, rows will be |
||
172 | * retrieved beginnning from row <tt>0</tt>. |
||
173 | * @param firstResult a row number, numbered from <tt>0</tt> |
||
174 | */ |
||
175 | public Query setFirstResult(int firstResult); |
||
176 | |||
177 | /** |
||
178 | * Entities retrieved by this query will be loaded in |
||
179 | * a read-only mode where Hibernate will never dirty-check |
||
180 | * them or make changes persistent. |
||
181 | * |
||
182 | */ |
||
183 | public Query setReadOnly(boolean readOnly); |
||
184 | |||
185 | /** |
||
186 | * Enable caching of this query result set. |
||
187 | * @param cacheable Should the query results be cacheable? |
||
188 | */ |
||
189 | public Query setCacheable(boolean cacheable); |
||
190 | |||
191 | /** |
||
192 | * Set the name of the cache region. |
||
193 | * @param cacheRegion the name of a query cache region, or <tt>null</tt> |
||
194 | * for the default query cache |
||
195 | */ |
||
196 | public Query setCacheRegion(String cacheRegion); |
||
197 | |||
198 | /** |
||
199 | * Set a timeout for the underlying JDBC query. |
||
200 | * @param timeout the timeout in seconds |
||
201 | */ |
||
202 | public Query setTimeout(int timeout); |
||
203 | /** |
||
204 | * Set a fetch size for the underlying JDBC query. |
||
205 | * @param fetchSize the fetch size |
||
206 | */ |
||
207 | public Query setFetchSize(int fetchSize); |
||
208 | |||
209 | /** |
||
210 | * Set the lockmode for the objects idententified by the |
||
211 | * given alias that appears in the <tt>FROM</tt> clause. |
||
212 | * @param alias a query alias, or <tt>this</tt> for a collection filter |
||
213 | */ |
||
214 | public Query setLockMode(String alias, LockMode lockMode); |
||
215 | |||
216 | /** |
||
217 | * Add a comment to the generated SQL. |
||
218 | * @param comment a human-readable string |
||
219 | */ |
||
220 | public Query setComment(String comment); |
||
221 | |||
222 | /** |
||
223 | * Override the current session flush mode, just for |
||
224 | * this query. |
||
225 | * @see org.hibernate.FlushMode |
||
226 | */ |
||
227 | public Query setFlushMode(FlushMode flushMode); |
||
228 | |||
229 | /** |
||
230 | * Override the current session cache mode, just for |
||
231 | * this query. |
||
232 | * @see org.hibernate.CacheMode |
||
233 | */ |
||
234 | public Query setCacheMode(CacheMode cacheMode); |
||
235 | |||
236 | /** |
||
237 | * Bind a value to a JDBC-style query parameter. |
||
238 | * @param position the position of the parameter in the query |
||
239 | * string, numbered from <tt>0</tt>. |
||
240 | * @param val the possibly-null parameter value |
||
241 | * @param type the Hibernate type |
||
242 | */ |
||
243 | public Query setParameter(int position, Object val, Type type); |
||
244 | /** |
||
245 | * Bind a value to a named query parameter. |
||
246 | * @param name the name of the parameter |
||
247 | * @param val the possibly-null parameter value |
||
248 | * @param type the Hibernate type |
||
249 | */ |
||
250 | public Query setParameter(String name, Object val, Type type); |
||
251 | |||
252 | /** |
||
253 | * Bind a value to a JDBC-style query parameter. The Hibernate type of the parameter is |
||
254 | * first detected via the usage/position in the query and if not sufficient secondly |
||
255 | * guessed from the class of the given object. |
||
256 | * @param position the position of the parameter in the query |
||
257 | * string, numbered from <tt>0</tt>. |
||
258 | * @param val the non-null parameter value |
||
259 | * @throws org.hibernate.HibernateException if no type could be determined |
||
260 | */ |
||
261 | public Query setParameter(int position, Object val) throws HibernateException; |
||
262 | /** |
||
263 | * Bind a value to a named query parameter. The Hibernate type of the parameter is |
||
264 | * first detected via the usage/position in the query and if not sufficient secondly |
||
265 | * guessed from the class of the given object. |
||
266 | * @param name the name of the parameter |
||
267 | * @param val the non-null parameter value |
||
268 | * @throws org.hibernate.HibernateException if no type could be determined |
||
269 | */ |
||
270 | public Query setParameter(String name, Object val) throws HibernateException; |
||
271 | |||
272 | /** |
||
273 | * Bind values and types to positional parameters. |
||
274 | */ |
||
275 | public Query setParameters(Object[] values, Type[] types) throws HibernateException; |
||
276 | |||
277 | /** |
||
278 | * Bind multiple values to a named query parameter. This is useful for binding |
||
279 | * a list of values to an expression such as <tt>foo.bar in (:value_list)</tt>. |
||
280 | * @param name the name of the parameter |
||
281 | * @param vals a collection of values to list |
||
282 | * @param type the Hibernate type of the values |
||
283 | */ |
||
284 | public Query setParameterList(String name, Collection vals, Type type) throws HibernateException; |
||
285 | |||
286 | /** |
||
287 | * Bind multiple values to a named query parameter. The Hibernate type of the parameter is |
||
288 | * first detected via the usage/position in the query and if not sufficient secondly |
||
289 | * guessed from the class of the first object in the collection. This is useful for binding a list of values |
||
290 | * to an expression such as <tt>foo.bar in (:value_list)</tt>. |
||
291 | * @param name the name of the parameter |
||
292 | * @param vals a collection of values to list |
||
293 | */ |
||
294 | public Query setParameterList(String name, Collection vals) throws HibernateException; |
||
295 | |||
296 | /** |
||
297 | * Bind multiple values to a named query parameter. This is useful for binding |
||
298 | * a list of values to an expression such as <tt>foo.bar in (:value_list)</tt>. |
||
299 | * @param name the name of the parameter |
||
300 | * @param vals a collection of values to list |
||
301 | * @param type the Hibernate type of the values |
||
302 | */ |
||
303 | public Query setParameterList(String name, Object[] vals, Type type) throws HibernateException; |
||
304 | |||
305 | /** |
||
306 | * Bind multiple values to a named query parameter. The Hibernate type of the parameter is |
||
307 | * first detected via the usage/position in the query and if not sufficient secondly |
||
308 | * guessed from the class of the first object in the array. This is useful for binding a list of values |
||
309 | * to an expression such as <tt>foo.bar in (:value_list)</tt>. |
||
310 | * @param name the name of the parameter |
||
311 | * @param vals a collection of values to list |
||
312 | */ |
||
313 | public Query setParameterList(String name, Object[] vals) throws HibernateException; |
||
314 | |||
315 | /** |
||
316 | * Bind the property values of the given bean to named parameters of the query, |
||
317 | * matching property names with parameter names and mapping property types to |
||
318 | * Hibernate types using hueristics. |
||
319 | * @param bean any JavaBean or POJO |
||
320 | */ |
||
321 | public Query setProperties(Object bean) throws HibernateException; |
||
322 | |||
323 | /** |
||
324 | * Bind the values of the given Map for each named parameters of the query, |
||
325 | * matching key names with parameter names and mapping value types to |
||
326 | * Hibernate types using hueristics. |
||
327 | * @param bean a java.util.Map |
||
328 | */ |
||
329 | public Query setProperties(Map bean) throws HibernateException; |
||
330 | |||
331 | public Query setString(int position, String val); |
||
332 | public Query setCharacter(int position, char val); |
||
333 | public Query setBoolean(int position, boolean val); |
||
334 | public Query setByte(int position, byte val); |
||
335 | public Query setShort(int position, short val); |
||
336 | public Query setInteger(int position, int val); |
||
337 | public Query setLong(int position, long val); |
||
338 | public Query setFloat(int position, float val); |
||
339 | public Query setDouble(int position, double val); |
||
340 | public Query setBinary(int position, byte[] val); |
||
341 | public Query setText(int position, String val); |
||
342 | public Query setSerializable(int position, Serializable val); |
||
343 | public Query setLocale(int position, Locale locale); |
||
344 | public Query setBigDecimal(int position, BigDecimal number); |
||
345 | public Query setBigInteger(int position, BigInteger number); |
||
346 | |||
347 | public Query setDate(int position, Date date); |
||
348 | public Query setTime(int position, Date date); |
||
349 | public Query setTimestamp(int position, Date date); |
||
350 | |||
351 | public Query setCalendar(int position, Calendar calendar); |
||
352 | public Query setCalendarDate(int position, Calendar calendar); |
||
353 | |||
354 | public Query setString(String name, String val); |
||
355 | public Query setCharacter(String name, char val); |
||
356 | public Query setBoolean(String name, boolean val); |
||
357 | public Query setByte(String name, byte val); |
||
358 | public Query setShort(String name, short val); |
||
359 | public Query setInteger(String name, int val); |
||
360 | public Query setLong(String name, long val); |
||
361 | public Query setFloat(String name, float val); |
||
362 | public Query setDouble(String name, double val); |
||
363 | public Query setBinary(String name, byte[] val); |
||
364 | public Query setText(String name, String val); |
||
365 | public Query setSerializable(String name, Serializable val); |
||
366 | public Query setLocale(String name, Locale locale); |
||
367 | public Query setBigDecimal(String name, BigDecimal number); |
||
368 | public Query setBigInteger(String name, BigInteger number); |
||
369 | |||
370 | public Query setDate(String name, Date date); |
||
371 | public Query setTime(String name, Date date); |
||
372 | public Query setTimestamp(String name, Date date); |
||
373 | |||
374 | public Query setCalendar(String name, Calendar calendar); |
||
375 | public Query setCalendarDate(String name, Calendar calendar); |
||
376 | |||
377 | /** |
||
378 | * Bind an instance of a mapped persistent class to a JDBC-style query parameter. |
||
379 | * @param position the position of the parameter in the query |
||
380 | * string, numbered from <tt>0</tt>. |
||
381 | * @param val a non-null instance of a persistent class |
||
382 | */ |
||
383 | public Query setEntity(int position, Object val); // use setParameter for null values |
||
384 | |||
385 | /** |
||
386 | * Bind an instance of a mapped persistent class to a named query parameter. |
||
387 | * @param name the name of the parameter |
||
388 | * @param val a non-null instance of a persistent class |
||
389 | */ |
||
390 | public Query setEntity(String name, Object val); // use setParameter for null values |
||
391 | |||
392 | |||
393 | /** |
||
394 | * Set a strategy for handling the query results. This can be used to change |
||
395 | * "shape" of the query result. |
||
396 | * |
||
397 | * @param transformer The transformer to apply |
||
398 | * @return this (for method chaining) |
||
399 | */ |
||
400 | public Query setResultTransformer(ResultTransformer transformer); |
||
401 | |||
402 | } |
||
403 | |||
404 | |||
405 | |||
406 | |||
407 | |||
408 | |||
409 |