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  ;
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  
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   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  [] 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  [] 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   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   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   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   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   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   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   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   name, Object   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   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   name, Object   val) throws HibernateException;
245     
246     /**
247      * Bind values and types to positional parameters.
248      */
249     public Query setParameters(Object  [] 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   name, Collection   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   name, Collection   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   name, Object  [] 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   name, Object  [] 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   bean) throws HibernateException;
294 
295     public Query setString(int position, String   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   val);
306     public Query setSerializable(int position, Serializable   val);
307     public Query setLocale(int position, Locale   locale);
308     public Query setBigDecimal(int position, BigDecimal   number);
309     public Query setBigInteger(int position, BigInteger   number);
310 
311     public Query setDate(int position, Date   date);
312     public Query setTime(int position, Date   date);
313     public Query setTimestamp(int position, Date   date);
314 
315     public Query setCalendar(int position, Calendar   calendar);
316     public Query setCalendarDate(int position, Calendar   calendar);
317 
318     public Query setString(String   name, String   val);
319     public Query setCharacter(String   name, char val);
320     public Query setBoolean(String   name, boolean val);
321     public Query setByte(String   name, byte val);
322     public Query setShort(String   name, short val);
323     public Query setInteger(String   name, int val);
324     public Query setLong(String   name, long val);
325     public Query setFloat(String   name, float val);
326     public Query setDouble(String   name, double val);
327     public Query setBinary(String   name, byte[] val);
328     public Query setText(String   name, String   val);
329     public Query setSerializable(String   name, Serializable   val);
330     public Query setLocale(String   name, Locale   locale);
331     public Query setBigDecimal(String   name, BigDecimal   number);
332     public Query setBigInteger(String   name, BigInteger   number);
333 
334     public Query setDate(String   name, Date   date);
335     public Query setTime(String   name, Date   date);
336     public Query setTimestamp(String   name, Date   date);
337 
338     public Query setCalendar(String   name, Calendar   calendar);
339     public Query setCalendarDate(String   name, Calendar   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   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   name, Object   val); // use setParameter for null values
355 
356 }
357 
358 
359 
360 
361 
362 
363 
364
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags