Java > Open Source Codes > org > springframework > jdbc > object > SqlQuery


1 /*
2  * Copyright 2002-2006 the original author or authors.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 package org.springframework.jdbc.object;
18
19 import java.util.List ;
20 import java.util.Map ;
21
22 import javax.sql.DataSource ;
23
24 import org.springframework.dao.DataAccessException;
25 import org.springframework.dao.support.DataAccessUtils;
26 import org.springframework.jdbc.core.RowMapper;
27 import org.springframework.jdbc.core.namedparam.MapSqlParameterSource;
28 import org.springframework.jdbc.core.namedparam.NamedParameterUtils;
29
30 /**
31  * Reusable object to represent a SQL query.
32  *
33  * <p>Subclasses must implement the {@link #newRowMapper} method to provide
34  * an object that can extract the results of iterating over the
35  * <code>ResultSet</code> created during the execution of the query.
36  *
37  * <p>This class provides a number of public <code>execute</code> methods that are
38  * analogous to the different convenient JDO query execute methods. Subclasses
39  * can either rely on one of these inherited methods, or can add their own
40  * custom execution methods, with meaningful names and typed parameters
41  * (definitely a best practice). Each custom query method will invoke one of
42  * this class's untyped query methods.
43  *
44  * <p>Like all <code>RdbmsOperation</code> classes that ship with the Spring
45  * Framework, <code>SqlQuery</code> instances are threadsafe after their
46  * initialization is complete. That is, after they are constructed and configured
47  * via their setter methods, they can be used safely from multiple threads.
48  *
49  * @author Rod Johnson
50  * @author Juergen Hoeller
51  * @author Thomas Risberg
52  * @author Jean-Pierre Pawlak
53  */
54 public abstract class SqlQuery extends SqlOperation {
55
56     /** The number of rows to expect; if 0, unknown. */
57     private int rowsExpected = 0;
58
59
60     /**
61      * Constructor to allow use as a JavaBean.
62      * <p>The <code>DataSource</code> and SQL must be supplied before
63      * compilation and use.
64      */
65     public SqlQuery() {
66     }
67
68     /**
69      * Convenient constructor with a <code>DataSource</code> and SQL string.
70      * @param ds the <code>DataSource</code> to use to get connections
71      * @param sql the SQL to execute; SQL can also be supplied at runtime
72      * by overriding the {@link #getSql()} method.
73      */
74     public SqlQuery(DataSource ds, String sql) {
75         setDataSource(ds);
76         setSql(sql);
77     }
78
79
80     /**
81      * Set the number of rows expected.
82      * <p>This can be used to ensure efficient storage of results. The
83      * default behavior is not to expect any specific number of rows.
84      */
85     public void setRowsExpected(int rowsExpected) {
86         this.rowsExpected = rowsExpected;
87     }
88
89     /**
90      * Get the number of rows expected.
91      */
92     public int getRowsExpected() {
93         return rowsExpected;
94     }
95
96
97     /**
98      * Central execution method. All un-named parameter execution goes through this method.
99      * @param params parameters, similar to JDO query parameters.
100      * Primitive parameters must be represented by their Object wrapper type.
101      * The ordering of parameters is significant.
102      * @param context contextual information passed to the <code>mapRow</code>
103      * callback method. The JDBC operation itself doesn't rely on this parameter,
104      * but it can be useful for creating the objects of the result list.
105      * @return a List of objects, one per row of the ResultSet. Normally all these
106      * will be of the same class, although it is possible to use different types.
107      */
108     public List execute(Object [] params, Map context) throws DataAccessException {
109         validateParameters(params);
110         RowMapper rowMapper = newRowMapper(params, context);
111         return getJdbcTemplate().query(newPreparedStatementCreator(params), rowMapper);
112     }
113
114     /**
115      * Convenient method to execute without context.
116      * @param params parameters for the query. Primitive parameters must
117      * be represented by their Object wrapper type. The ordering of parameters is
118      * significant.
119      */
120     public List execute(Object [] params) throws DataAccessException {
121         return execute(params, null);
122     }
123
124     /**
125      * Convenient method to execute without parameters.
126      * @param context the contextual information for object creation
127      */
128     public List execute(Map context) throws DataAccessException {
129         return execute((Object []) null, context);
130     }
131
132     /**
133      * Convenient method to execute without parameters nor context.
134      */
135     public List execute() throws DataAccessException {
136         return execute((Object []) null);
137     }
138
139     /**
140      * Convenient method to execute with a single int parameter and context.
141      * @param p1 single int parameter
142      * @param context the contextual information for object creation
143      */
144     public List execute(int p1, Map context) throws DataAccessException {
145         return execute(new Object [] {new Integer (p1)}, context);
146     }
147
148     /**
149      * Convenient method to execute with a single int parameter.
150      * @param p1 single int parameter
151      */
152     public List execute(int p1) throws DataAccessException {
153         return execute(p1, null);
154     }
155
156     /**
157      * Convenient method to execute with two int parameters and context.
158      * @param p1 first int parameter
159      * @param p2 second int parameter
160      * @param context the contextual information for object creation
161      */
162     public List execute(int p1, int p2, Map context) throws DataAccessException {
163         return execute(new Object [] {new Integer (p1), new Integer (p2)}, context);
164     }
165
166     /**
167      * Convenient method to execute with two int parameters.
168      * @param p1 first int parameter
169      * @param p2 second int parameter
170      */
171     public List execute(int p1, int p2) throws DataAccessException {
172         return execute(p1, p2, null);
173     }
174
175     /**
176      * Convenient method to execute with a single long parameter and context.
177      * @param p1 single long parameter
178      * @param context the contextual information for object creation
179      */
180     public List execute(long p1, Map context) throws DataAccessException {
181         return execute(new Object [] {new Long (p1)}, context);
182     }
183
184     /**
185      * Convenient method to execute with a single long parameter.
186      * @param p1 single long parameter
187      */
188     public List execute(long p1) throws DataAccessException {
189         return execute(p1, null);
190     }
191
192     /**
193      * Convenient method to execute with a single String parameter and context.
194      * @param p1 single String parameter
195      * @param context the contextual information for object creation
196      */
197     public List execute(String p1, Map context) throws DataAccessException {
198         return execute(new Object [] {p1}, context);
199     }
200
201     /**
202      * Convenient method to execute with a single String parameter.
203      * @param p1 single String parameter
204      */
205     public List execute(String p1) throws DataAccessException {
206         return execute(p1, null);
207     }
208
209     /**
210      * Central execution method. All named parameter execution goes through this method.
211      * @param paramMap parameters associated with the name specified while declaring
212      * the SqlParameters. Primitive parameters must be represented by their Object wrapper
213      * type. The ordering of parameters is not significant since they are supplied in a
214      * SqlParameterMap which is an implementation of the Map interface.
215      * @param context contextual information passed to the <code>mapRow</code>
216      * callback method. The JDBC operation itself doesn't rely on this parameter,
217      * but it can be useful for creating the objects of the result list.
218      * @return a List of objects, one per row of the ResultSet. Normally all these
219      * will be of the same class, although it is possible to use different types.
220      */
221     public List executeByNamedParam(Map paramMap, Map context) throws DataAccessException {
222         validateNamedParameters(paramMap);
223         Object [] parameters = NamedParameterUtils.buildValueArray(getSql(), paramMap);
224         RowMapper rowMapper = newRowMapper(parameters, context);
225         String sqlToUse = NamedParameterUtils.substituteNamedParameters(getSql(), new MapSqlParameterSource(paramMap));
226         return getJdbcTemplate().query(newPreparedStatementCreator(sqlToUse, parameters), rowMapper);
227     }
228
229     /**
230      * Convenient method to execute without context.
231      * @param paramMap parameters associated with the name specified while declaring
232      * the SqlParameters. Primitive parameters must be represented by their Object wrapper
233      * type. The ordering of parameters is not significant.
234      */
235     public List executeByNamedParam(Map paramMap) throws DataAccessException {
236         return executeByNamedParam(paramMap, null);
237     }
238
239
240     /**
241      * Generic object finder method, used by all other <code>findObject</code> methods.
242      * Object finder methods are like EJB entity bean finders, in that it is
243      * considered an error if they return more than one result.
244      * @return the result object, or <code>null</code> if not found. Subclasses may
245      * choose to treat this as an error and throw an exception.
246      * @see org.springframework.dao.support.DataAccessUtils#singleResult
247      */
248     public Object findObject(Object [] params, Map context) throws DataAccessException {
249         List results = execute(params, context);
250         return DataAccessUtils.singleResult(results);
251     }
252
253     /**
254      * Convenient method to find a single object without context.
255      */
256     public Object findObject(Object [] params) throws DataAccessException {
257         return findObject(params, null);
258     }
259
260     /**
261      * Convenient method to find a single object given a single int parameter
262      * and a context.
263      */
264     public Object findObject(int p1, Map context) throws DataAccessException {
265         return findObject(new Object [] {new Integer (p1)}, context);
266     }
267
268     /**
269      * Convenient method to find a single object given a single int parameter.
270      */
271     public Object findObject(int p1) throws DataAccessException {
272         return findObject(p1, null);
273     }
274
275     /**
276      * Convenient method to find a single object given two int parameters
277      * and a context.
278      */
279     public Object findObject(int p1, int p2, Map context) throws DataAccessException {
280         return findObject(new Object [] {new Integer (p1), new Integer (p2)}, context);
281     }
282
283     /**
284      * Convenient method to find a single object given two int parameters.
285      */
286     public Object findObject(int p1, int p2) throws DataAccessException {
287         return findObject(p1, p2, null);
288     }
289
290     /**
291      * Convenient method to find a single object given a single long parameter
292      * and a context.
293      */
294     public Object findObject(long p1, Map context) throws DataAccessException {
295         return findObject(new Object [] {new Long (p1)}, context);
296     }
297
298     /**
299      * Convenient method to find a single object given a single long parameter.
300      */
301     public Object findObject(long p1) throws DataAccessException {
302         return findObject(p1, null);
303     }
304
305     /**
306      * Convenient method to find a single object given a single String parameter
307      * and a context.
308      */
309     public Object findObject(String p1, Map context) throws DataAccessException {
310         return findObject(new Object [] {p1}, context);
311     }
312
313     /**
314      * Convenient method to find a single object given a single String parameter.
315      */
316     public Object findObject(String p1) throws DataAccessException {
317         return findObject(p1, null);
318     }
319
320     /**
321      * Generic object finder method for named parameters.
322      * @param paramMap Map of parameter name to parameter object,
323      * matching named parameters specified in the SQL statement.
324      * Ordering is not significant.
325      * @param context contextual information passed to the <code>mapRow</code>
326      * callback method. The JDBC operation itself doesn't rely on this parameter,
327      * but it can be useful for creating the objects of the result list.
328      * @return a List of objects, one per row of the ResultSet. Normally all these
329      * will be of the same class, although it is possible to use different types.
330      */
331     public Object findObjectByNamedParam(Map paramMap, Map context) throws DataAccessException {
332         List results = executeByNamedParam(paramMap, context);
333         return DataAccessUtils.singleResult(results);
334     }
335
336     /**
337      * Convenient method to execute without context.
338      * @param paramMap Map of parameter name to parameter object,
339      * matching named parameters specified in the SQL statement.
340      * Ordering is not significant.
341      */
342     public Object findObjectByNamedParam(Map paramMap) throws DataAccessException {
343         return findObjectByNamedParam(paramMap, null);
344     }
345
346
347     /**
348      * Subclasses must implement this method to extract an object per row, to be
349      * returned by the <cod>execute</code> method as an aggregated {@link List}.
350      * @param parameters the parameters to the <code>execute()</code> method,
351      * in case subclass is interested; may be <code>null</code> if there
352      * were no parameters.
353      * @param context contextual information passed to the <code>mapRow</code>
354      * callback method. The JDBC operation itself doesn't rely on this parameter,
355      * but it can be useful for creating the objects of the result list.
356      * @see #execute
357      */
358     protected abstract RowMapper newRowMapper(Object [] parameters, Map context);
359
360 }
361

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags