KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > hibernate > Query


1 //$Id: Query.java,v 1.17 2005/06/19 22:03:57 oneovthafew Exp $
2
package org.hibernate;
3
4 import java.io.Serializable JavaDoc;
5 import java.math.BigDecimal JavaDoc;
6 import java.math.BigInteger JavaDoc;
7 import java.util.Calendar JavaDoc;
8 import java.util.Collection JavaDoc;
9 import java.util.Date JavaDoc;
10 import java.util.Iterator JavaDoc;
11 import java.util.List JavaDoc;
12 import java.util.Locale JavaDoc;
13
14 import org.hibernate.type.Type;
15
16 /**
17  * An object-oriented representation of a Hibernate query. A <tt>Query</tt>
18  * instance is obtained by calling <tt>Session.createQuery()</tt>. This
19  * interface exposes some extra functionality beyond that provided by
20  * <tt>Session.iterate()</tt> and <tt>Session.find()</tt>:
21  * <ul>
22  * <li>a particular page of the result set may be selected by calling <tt>
23  * setMaxResults(), setFirstResult()</tt>
24  * <li>named query parameters may be used
25  * <li>the results may be returned as an instance of <tt>ScrollableResults</tt>
26  * </ul>
27  * <br>
28  * Named query parameters are tokens of the form <tt>:name</tt> in the
29  * query string. A value is bound to the <tt>integer</tt> parameter
30  * <tt>:foo</tt> by calling<br>
31  * <br>
32  * <tt>setParameter("foo", foo, Hibernate.INTEGER);</tt><br>
33  * <br>
34  * for example. A name may appear multiple times in the query string.<br>
35  * <br>
36  * JDBC-style <tt>?</tt> parameters are also supported. To bind a
37  * value to a JDBC-style parameter use a set method that accepts an
38  * <tt>int</tt> positional argument (numbered from zero, contrary
39  * to JDBC).<br>
40  * <br>
41  * You may not mix and match JDBC-style parameters and named parameters
42  * in the same query.<br>
43  * <br>
44  * Queries are executed by calling <tt>list()</tt>, <tt>scroll()</tt> or
45  * <tt>iterate()</tt>. A query may be re-executed by subsequent invocations.
46  * Its lifespan is, however, bounded by the lifespan of the <tt>Session</tt>
47  * that created it.<br>
48  * <br>
49  * Implementors are not intended to be threadsafe.
50  *
51  * @see org.hibernate.Session#createQuery(java.lang.String)
52  * @see org.hibernate.ScrollableResults
53  * @author Gavin King
54  */

55 public interface Query {
56     /**
57      * Get the query string.
58      *
59      * @return the query string
60      */

61     public String JavaDoc getQueryString();
62     /**
63      * Return the Hibernate types of the query result set.
64      * @return an array of types
65      */

66     public Type[] getReturnTypes() throws HibernateException;
67     /**
68      * Return the HQL select clause aliases (if any)
69      * @return an array of aliases as strings
70      */

71     public String JavaDoc[] getReturnAliases() throws HibernateException;
72     /**
73      * Return the names of all named parameters of the query.
74      * @return the parameter names, in no particular order
75      */

76     public String JavaDoc[] getNamedParameters() throws HibernateException;
77     /**
78      * Return the query results as an <tt>Iterator</tt>. If the query
79      * contains multiple results pre row, the results are returned in
80      * an instance of <tt>Object[]</tt>.<br>
81      * <br>
82      * Entities returned as results are initialized on demand. The first
83      * SQL query returns identifiers only.<br>
84      *
85      * @return the result iterator
86      * @throws HibernateException
87      */

88     public Iterator JavaDoc iterate() throws HibernateException;
89     /**
90      * Return the query results as <tt>ScrollableResults</tt>. The
91      * scrollability of the returned results depends upon JDBC driver
92      * support for scrollable <tt>ResultSet</tt>s.<br>
93      *
94      * @see ScrollableResults
95      * @return the result iterator
96      * @throws HibernateException
97      */

98     public ScrollableResults scroll() throws HibernateException;
99     /**
100      * Return the query results as <tt>ScrollableResults</tt>. The
101      * scrollability of the returned results depends upon JDBC driver
102      * support for scrollable <tt>ResultSet</tt>s.<br>
103      *
104      * @see ScrollableResults
105      * @see ScrollMode
106      * @return the result iterator
107      * @throws HibernateException
108      */

109     public ScrollableResults scroll(ScrollMode scrollMode) throws HibernateException;
110     /**
111      * Return the query results as a <tt>List</tt>. If the query contains
112      * multiple results pre row, the results are returned in an instance
113      * of <tt>Object[]</tt>.
114      *
115      * @return the result list
116      * @throws HibernateException
117      */

118     public List JavaDoc list() throws HibernateException;
119     /**
120      * Convenience method to return a single instance that matches
121      * the query, or null if the query returns no results.
122      *
123      * @return the single result or <tt>null</tt>
124      * @throws HibernateException if there is more than one matching result
125      */

126     public Object JavaDoc uniqueResult() throws HibernateException;
127
128     /**
129      * Execute the update or delete statement.
130      * </p>
131      * The semantics are compliant with the ejb3 Query.executeUpdate()
132      * method.
133      *
134      * @return The number of entities updated or deleted.
135      * @throws HibernateException
136      */

137     public int executeUpdate() throws HibernateException;
138
139     /**
140      * Set the maximum number of rows to retrieve. If not set,
141      * there is no limit to the number of rows retrieved.
142      * @param maxResults the maximum number of rows
143      */

144     public Query setMaxResults(int maxResults);
145     /**
146      * Set the first row to retrieve. If not set, rows will be
147      * retrieved beginnning from row <tt>0</tt>.
148      * @param firstResult a row number, numbered from <tt>0</tt>
149      */

150     public Query setFirstResult(int firstResult);
151     
152     /**
153      * Entities retrieved by this query will be loaded in
154      * a read-only mode where Hibernate will never dirty-check
155      * them or make changes persistent.
156      *
157      * @see Session.setReadOnly(Object, boolean)
158      */

159     public Query setReadOnly(boolean readOnly);
160
161     /**
162      * Enable caching of this query result set.
163      * @param cacheable Should the query results be cacheable?
164      */

165     public Query setCacheable(boolean cacheable);
166
167     /**
168      * Set the name of the cache region.
169      * @param cacheRegion the name of a query cache region, or <tt>null</tt>
170      * for the default query cache
171      */

172     public Query setCacheRegion(String JavaDoc cacheRegion);
173
174     /**
175      * Set a timeout for the underlying JDBC query.
176      * @param timeout the timeout in seconds
177      */

178     public Query setTimeout(int timeout);
179     /**
180      * Set a fetch size for the underlying JDBC query.
181      * @param fetchSize the fetch size
182      */

183     public Query setFetchSize(int fetchSize);
184
185     /**
186      * Set the lockmode for the objects idententified by the
187      * given alias that appears in the <tt>FROM</tt> clause.
188      * @param alias a query alias, or <tt>this</tt> for a collection filter
189      */

190     public Query setLockMode(String JavaDoc alias, LockMode lockMode);
191
192     /**
193      * Add a comment to the generated SQL.
194      * @param comment a human-readable string
195      */

196     public Query setComment(String JavaDoc comment);
197     
198     /**
199      * Override the current session flush mode, just for
200      * this query.
201      * @see org.hibernate.FlushMode
202      */

203     public Query setFlushMode(FlushMode flushMode);
204
205     /**
206      * Override the current session cache mode, just for
207      * this query.
208      * @see org.hibernate.CacheMode
209      */

210     public Query setCacheMode(CacheMode cacheMode);
211
212     /**
213      * Bind a value to a JDBC-style query parameter.
214      * @param position the position of the parameter in the query
215      * string, numbered from <tt>0</tt>.
216      * @param val the possibly-null parameter value
217      * @param type the Hibernate type
218      */

219     public Query setParameter(int position, Object JavaDoc val, Type type);
220     /**
221      * Bind a value to a named query parameter.
222      * @param name the name of the parameter
223      * @param val the possibly-null parameter value
224      * @param type the Hibernate type
225      */

226     public Query setParameter(String JavaDoc name, Object JavaDoc val, Type type);
227
228     /**
229      * Bind a value to a JDBC-style query parameter, guessing the
230      * Hibernate type from the class of the given object.
231      * @param position the position of the parameter in the query
232      * string, numbered from <tt>0</tt>.
233      * @param val the non-null parameter value
234      * @throws org.hibernate.HibernateException if no type could be determined
235      */

236     public Query setParameter(int position, Object JavaDoc val) throws HibernateException;
237     /**
238      * Bind a value to a named query parameter, guessing the Hibernate
239      * type from the class of the given object.
240      * @param name the name of the parameter
241      * @param val the non-null parameter value
242      * @throws org.hibernate.HibernateException if no type could be determined
243      */

244     public Query setParameter(String JavaDoc name, Object JavaDoc val) throws HibernateException;
245     
246     /**
247      * Bind values and types to positional parameters.
248      */

249     public Query setParameters(Object JavaDoc[] values, Type[] types) throws HibernateException;
250
251     /**
252      * Bind multiple values to a named query parameter. This is useful for binding
253      * a list of values to an expression such as <tt>foo.bar in (:value_list)</tt>.
254      * @param name the name of the parameter
255      * @param vals a collection of values to list
256      * @param type the Hibernate type of the values
257      */

258     public Query setParameterList(String JavaDoc name, Collection JavaDoc vals, Type type) throws HibernateException;
259
260     /**
261      * Bind multiple values to a named query parameter, guessing the Hibernate type from the
262      * class of the first object in the collection. This is useful for binding a list of values
263      * to an expression such as <tt>foo.bar in (:value_list)</tt>.
264      * @param name the name of the parameter
265      * @param vals a collection of values to list
266      */

267     public Query setParameterList(String JavaDoc name, Collection JavaDoc vals) throws HibernateException;
268
269     /**
270      * Bind multiple values to a named query parameter. This is useful for binding
271      * a list of values to an expression such as <tt>foo.bar in (:value_list)</tt>.
272      * @param name the name of the parameter
273      * @param vals a collection of values to list
274      * @param type the Hibernate type of the values
275      */

276     public Query setParameterList(String JavaDoc name, Object JavaDoc[] vals, Type type) throws HibernateException;
277
278     /**
279      * Bind multiple values to a named query parameter, guessing the Hibernate type from the
280      * class of the first object in the array. This is useful for binding a list of values
281      * to an expression such as <tt>foo.bar in (:value_list)</tt>.
282      * @param name the name of the parameter
283      * @param vals a collection of values to list
284      */

285     public Query setParameterList(String JavaDoc name, Object JavaDoc[] vals) throws HibernateException;
286
287     /**
288      * Bind the property values of the given bean to named parameters of the query,
289      * matching property names with parameter names and mapping property types to
290      * Hibernate types using hueristics.
291      * @param bean any JavaBean or POJO
292      */

293     public Query setProperties(Object JavaDoc bean) throws HibernateException;
294
295     public Query setString(int position, String JavaDoc val);
296     public Query setCharacter(int position, char val);
297     public Query setBoolean(int position, boolean val);
298     public Query setByte(int position, byte val);
299     public Query setShort(int position, short val);
300     public Query setInteger(int position, int val);
301     public Query setLong(int position, long val);
302     public Query setFloat(int position, float val);
303     public Query setDouble(int position, double val);
304     public Query setBinary(int position, byte[] val);
305     public Query setText(int position, String JavaDoc val);
306     public Query setSerializable(int position, Serializable JavaDoc val);
307     public Query setLocale(int position, Locale JavaDoc locale);
308     public Query setBigDecimal(int position, BigDecimal JavaDoc number);
309     public Query setBigInteger(int position, BigInteger JavaDoc number);
310
311     public Query setDate(int position, Date JavaDoc date);
312     public Query setTime(int position, Date JavaDoc date);
313     public Query setTimestamp(int position, Date JavaDoc date);
314
315     public Query setCalendar(int position, Calendar JavaDoc calendar);
316     public Query setCalendarDate(int position, Calendar JavaDoc calendar);
317
318     public Query setString(String JavaDoc name, String JavaDoc val);
319     public Query setCharacter(String JavaDoc name, char val);
320     public Query setBoolean(String JavaDoc name, boolean val);
321     public Query setByte(String JavaDoc name, byte val);
322     public Query setShort(String JavaDoc name, short val);
323     public Query setInteger(String JavaDoc name, int val);
324     public Query setLong(String JavaDoc name, long val);
325     public Query setFloat(String JavaDoc name, float val);
326     public Query setDouble(String JavaDoc name, double val);
327     public Query setBinary(String JavaDoc name, byte[] val);
328     public Query setText(String JavaDoc name, String JavaDoc val);
329     public Query setSerializable(String JavaDoc name, Serializable JavaDoc val);
330     public Query setLocale(String JavaDoc name, Locale JavaDoc locale);
331     public Query setBigDecimal(String JavaDoc name, BigDecimal JavaDoc number);
332     public Query setBigInteger(String JavaDoc name, BigInteger JavaDoc number);
333
334     public Query setDate(String JavaDoc name, Date JavaDoc date);
335     public Query setTime(String JavaDoc name, Date JavaDoc date);
336     public Query setTimestamp(String JavaDoc name, Date JavaDoc date);
337
338     public Query setCalendar(String JavaDoc name, Calendar JavaDoc calendar);
339     public Query setCalendarDate(String JavaDoc name, Calendar JavaDoc calendar);
340
341     /**
342      * Bind an instance of a mapped persistent class to a JDBC-style query parameter.
343      * @param position the position of the parameter in the query
344      * string, numbered from <tt>0</tt>.
345      * @param val a non-null instance of a persistent class
346      */

347     public Query setEntity(int position, Object JavaDoc val); // use setParameter for null values
348

349     /**
350      * Bind an instance of a mapped persistent class to a named query parameter.
351      * @param name the name of the parameter
352      * @param val a non-null instance of a persistent class
353      */

354     public Query setEntity(String JavaDoc name, Object JavaDoc val); // use setParameter for null values
355

356 }
357
358
359
360
361
362
363
364
Popular Tags