Clover Coverage Report - SmartWeb
Coverage timestamp: Sun Jun 8 2008 21:20:12 CEST
Overview   Package   File
    FRAMES   NO FRAMES     
0   396   0   -
0   91   -   0
0     -  
1    
 
  Query       Line # 57 0 0 - -1.0
 
No Tests
 
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   
 
CloverReport generated by Clover Code Coverage v2.3.1
Sun Jun 8 2008 21:21:42 CEST.		   Clover: Open Source License registered to SmartWeb.