001: /*
002: * Copyright 2002-2005 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.springframework.jdbc.core.simple;
018:
019: import org.springframework.dao.DataAccessException;
020: import org.springframework.jdbc.core.JdbcOperations;
021: import org.springframework.jdbc.core.namedparam.NamedParameterJdbcOperations;
022: import org.springframework.jdbc.core.namedparam.SqlParameterSource;
023:
024: import java.util.List;
025: import java.util.Map;
026:
027: /**
028: * JDBC operations interface usable on Java 5 and above, exposing a
029: * set of common JDBC operations, whose interface is simplified
030: * through the use of varargs and autoboxing.
031: *
032: * @author Rod Johnson
033: * @author Rob Harrop
034: * @author Thomas Risberg
035: * @since 2.0
036: * @see org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate
037: * @see SimpleJdbcTemplate
038: * @see org.springframework.jdbc.core.JdbcOperations
039: */
040: public interface SimpleJdbcOperations {
041:
042: /**
043: * Expose the classic Spring JdbcTemplate to allow invocation of less
044: * commonly used methods.
045: */
046: JdbcOperations getJdbcOperations();
047:
048: /**
049: * Expose the Spring NamedParameterJdbcTemplate to allow invocation of less
050: * commonly used methods.
051: */
052: NamedParameterJdbcOperations getNamedParameterJdbcOperations();
053:
054: /**
055: * Query for an <code>int</code> passing in a SQL query
056: * using the named parameter support provided by the
057: * {@link org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate}
058: * and a map containing the arguments.
059: * @param sql the SQL query to run.
060: * @param args the map containing the arguments for the query.
061: */
062: int queryForInt(String sql, Map args) throws DataAccessException;
063:
064: /**
065: * Query for an <code>int</code> passing in a SQL query
066: * using the named parameter support provided by the
067: * {@link org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate}
068: * and a <code>SqlParameterSource</code> containing the arguments.
069: * @param sql the SQL query to run.
070: * @param args the <code>SqlParameterSource</code> containing the arguments for the query.
071: */
072: int queryForInt(String sql, SqlParameterSource args)
073: throws DataAccessException;
074:
075: /**
076: * Query for an <code>int</code> passing in a SQL query
077: * using the standard '?' placeholders for parameters
078: * and a variable number of arguments.
079: * @param sql the SQL query to run.
080: * @param args the variable number of arguments for the query.
081: */
082: int queryForInt(String sql, Object... args)
083: throws DataAccessException;
084:
085: /**
086: * Query for an <code>long</code> passing in a SQL query
087: * using the named parameter support provided by the
088: * {@link org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate}
089: * and a map containing the arguments.
090: * @param sql the SQL query to run.
091: * @param args the map containing the arguments for the query.
092: */
093: long queryForLong(String sql, Map args) throws DataAccessException;
094:
095: /**
096: * Query for an <code>long</code> passing in a SQL query
097: * using the named parameter support provided by the
098: * {@link org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate}
099: * and a <code>SqlParameterSource</code> containing the arguments.
100: * @param sql the SQL query to run.
101: * @param args the <code>SqlParameterSource</code> containing the arguments for the query.
102: */
103: long queryForLong(String sql, SqlParameterSource args)
104: throws DataAccessException;
105:
106: /**
107: * Query for an <code>long</code> passing in a SQL query
108: * using the standard '?' placeholders for parameters
109: * and a variable number of arguments.
110: * @param sql the SQL query to run.
111: * @param args the variable number of arguments for the query.
112: */
113: long queryForLong(String sql, Object... args)
114: throws DataAccessException;
115:
116: /**
117: * Query for an object of type <code>T</code> identified by the supplied @{@link Class}.
118: * Uses sql with the named parameter support provided by the
119: * {@link org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate}
120: * @param sql the SQL query to run.
121: * @param requiredType the required type of the return value.
122: * @param args the map containing the arguments for the query.
123: * @see JdbcOperations#queryForObject(String, Class)
124: * @see JdbcOperations#queryForObject(String, Object[], Class)
125: */
126: <T> T queryForObject(String sql, Class<T> requiredType, Map args)
127: throws DataAccessException;
128:
129: /**
130: * Query for an object of type <code>T</code> identified by the supplied @{@link Class}.
131: * Uses sql with the named parameter support provided by the
132: * {@link org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate}
133: * @param sql the SQL query to run.
134: * @param requiredType the required type of the return value.
135: * @param args the <code>SqlParameterSource</code> containing the arguments for the query.
136: * @see JdbcOperations#queryForObject(String, Class)
137: * @see JdbcOperations#queryForObject(String, Object[], Class)
138: */
139: <T> T queryForObject(String sql, Class<T> requiredType,
140: SqlParameterSource args) throws DataAccessException;
141:
142: /**
143: * Query for an object of type <code>T</code> identified by the supplied @{@link Class}.
144: * Uses sql with the standard '?' placeholders for parameters
145: * @param sql the SQL query to run.
146: * @param requiredType the required type of the return value.
147: * @param args the variable number of arguments for the query.
148: * @see JdbcOperations#queryForObject(String, Class)
149: * @see JdbcOperations#queryForObject(String, Object[], Class)
150: */
151: <T> T queryForObject(String sql, Class<T> requiredType,
152: Object... args) throws DataAccessException;
153:
154: /**
155: * Query for an object of type <code>T</code> using the supplied
156: * {@link ParameterizedRowMapper} to the query results to the object.
157: * Uses sql with the named parameter support provided by the
158: * {@link org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate}
159: * @param sql the SQL query to run.
160: * @param rm the @{@link ParameterizedRowMapper} to use for result mapping
161: * @param args the map containing the arguments for the query.
162: * @see JdbcOperations#queryForObject(String, org.springframework.jdbc.core.RowMapper)
163: * @see JdbcOperations#queryForObject(String, Object[], org.springframework.jdbc.core.RowMapper)
164: */
165: <T> T queryForObject(String sql, ParameterizedRowMapper<T> rm,
166: Map args) throws DataAccessException;
167:
168: /**
169: * Query for an object of type <code>T</code> using the supplied
170: * {@link ParameterizedRowMapper} to the query results to the object.
171: * Uses sql with the named parameter support provided by the
172: * {@link org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate}
173: * @param sql the SQL query to run.
174: * @param rm the @{@link ParameterizedRowMapper} to use for result mapping
175: * @param args the <code>SqlParameterSource</code> containing the arguments for the query.
176: * @see JdbcOperations#queryForObject(String, org.springframework.jdbc.core.RowMapper)
177: * @see JdbcOperations#queryForObject(String, Object[], org.springframework.jdbc.core.RowMapper)
178: */
179: <T> T queryForObject(String sql, ParameterizedRowMapper<T> rm,
180: SqlParameterSource args) throws DataAccessException;
181:
182: /**
183: * Query for an object of type <code>T</code> using the supplied
184: * {@link ParameterizedRowMapper} to the query results to the object.
185: * Uses sql with the standard '?' placeholders for parameters
186: * @param sql the SQL query to run.
187: * @param rm the @{@link ParameterizedRowMapper} to use for result mapping
188: * @param args the variable number of arguments for the query.
189: * @see JdbcOperations#queryForObject(String, org.springframework.jdbc.core.RowMapper)
190: * @see JdbcOperations#queryForObject(String, Object[], org.springframework.jdbc.core.RowMapper)
191: */
192: <T> T queryForObject(String sql, ParameterizedRowMapper<T> rm,
193: Object... args) throws DataAccessException;
194:
195: /**
196: * Query for a {@link List} of <code>Objects</code> of type <code>T</code> using
197: * the supplied {@link ParameterizedRowMapper} to the query results to the object.
198: * Uses sql with the named parameter support provided by the
199: * {@link org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate}
200: * @param sql the SQL query to run.
201: * @param rm the @{@link ParameterizedRowMapper} to use for result mapping
202: * @param args the map containing the arguments for the query.
203: * @see JdbcOperations#queryForObject(String, org.springframework.jdbc.core.RowMapper)
204: * @see JdbcOperations#queryForObject(String, Object[], org.springframework.jdbc.core.RowMapper)
205: */
206: <T> List<T> query(String sql, ParameterizedRowMapper<T> rm, Map args)
207: throws DataAccessException;
208:
209: /**
210: * Query for a {@link List} of <code>Objects</code> of type <code>T</code> using
211: * the supplied {@link ParameterizedRowMapper} to the query results to the object.
212: * Uses sql with the named parameter support provided by the
213: * {@link org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate}
214: * @param sql the SQL query to run.
215: * @param rm the @{@link ParameterizedRowMapper} to use for result mapping
216: * @param args the <code>SqlParameterSource</code> containing the arguments for the query.
217: * @see JdbcOperations#queryForObject(String, org.springframework.jdbc.core.RowMapper)
218: * @see JdbcOperations#queryForObject(String, Object[], org.springframework.jdbc.core.RowMapper)
219: */
220: <T> List<T> query(String sql, ParameterizedRowMapper<T> rm,
221: SqlParameterSource args) throws DataAccessException;
222:
223: /**
224: * Query for a {@link List} of <code>Objects</code> of type <code>T</code> using
225: * the supplied {@link ParameterizedRowMapper} to the query results to the object.
226: * Uses sql with the standard '?' placeholders for parameters
227: * @param sql the SQL query to run.
228: * @param rm the @{@link ParameterizedRowMapper} to use for result mapping
229: * @param args the variable number of arguments for the query.
230: * @see JdbcOperations#queryForObject(String, org.springframework.jdbc.core.RowMapper)
231: * @see JdbcOperations#queryForObject(String, Object[], org.springframework.jdbc.core.RowMapper)
232: */
233: <T> List<T> query(String sql, ParameterizedRowMapper<T> rm,
234: Object... args) throws DataAccessException;
235:
236: /**
237: * Execute the supplied query with the supplied arguments.
238: * <p>The query is expected to be a single row query; the result row will be
239: * mapped to a Map (one entry for each column, using the column name as the key).
240: * Uses sql with the named parameter support provided by the
241: * {@link org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate}
242: * @param sql the SQL query to run.
243: * @param args the map containing the arguments for the query.
244: * @see JdbcOperations#queryForMap(String)
245: * @see JdbcOperations#queryForMap(String, Object[])
246: */
247: Map<String, Object> queryForMap(String sql, Map args)
248: throws DataAccessException;
249:
250: /**
251: * Execute the supplied query with the supplied arguments.
252: * <p>The query is expected to be a single row query; the result row will be
253: * mapped to a Map (one entry for each column, using the column name as the key).
254: * Uses sql with the named parameter support provided by the
255: * {@link org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate}
256: * @param sql the SQL query to run.
257: * @param args the <code>SqlParameterSource</code> containing the arguments for the query.
258: * @see JdbcOperations#queryForMap(String)
259: * @see JdbcOperations#queryForMap(String, Object[])
260: */
261: Map<String, Object> queryForMap(String sql, SqlParameterSource args)
262: throws DataAccessException;
263:
264: /**
265: * Execute the supplied query with the (optional) supplied arguments.
266: * <p>The query is expected to be a single row query; the result row will be
267: * mapped to a Map (one entry for each column, using the column name as the key).
268: * Uses sql with the standard '?' placeholders for parameters
269: * @param sql the SQL query to run.
270: * @param args the variable number of arguments for the query.
271: * @see JdbcOperations#queryForMap(String)
272: * @see JdbcOperations#queryForMap(String, Object[])
273: */
274: Map<String, Object> queryForMap(String sql, Object... args)
275: throws DataAccessException;
276:
277: /**
278: * Execute the supplied query with the supplied arguments.
279: * <p>Each element in the returned {@link List} is constructed as a {@link Map}
280: * as described in {@link #queryForMap}
281: * Uses sql with the named parameter support provided by the
282: * {@link org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate}
283: * @param sql the SQL query to run.
284: * @param args the map containing the arguments for the query.
285: * @see JdbcOperations#queryForList(String)
286: * @see JdbcOperations#queryForList(String, Object[])
287: */
288: List<Map<String, Object>> queryForList(String sql, Map args)
289: throws DataAccessException;
290:
291: /**
292: * Execute the supplied query with the supplied arguments.
293: * <p>Each element in the returned {@link List} is constructed as a {@link Map}
294: * as described in {@link #queryForMap}
295: * Uses sql with the named parameter support provided by the
296: * {@link org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate}
297: * @param sql the SQL query to run.
298: * @param args the <code>SqlParameterSource</code> containing the arguments for the query.
299: * @see JdbcOperations#queryForList(String)
300: * @see JdbcOperations#queryForList(String, Object[])
301: */
302: List<Map<String, Object>> queryForList(String sql,
303: SqlParameterSource args) throws DataAccessException;
304:
305: /**
306: * Execute the supplied query with the (optional) supplied arguments.
307: * <p>Each element in the returned {@link List} is constructed as a {@link Map}
308: * as described in {@link #queryForMap}
309: * Uses sql with the standard '?' placeholders for parameters
310: * @param sql the SQL query to run.
311: * @param args the variable number of arguments for the query.
312: * @see JdbcOperations#queryForList(String)
313: * @see JdbcOperations#queryForList(String, Object[])
314: */
315: List<Map<String, Object>> queryForList(String sql, Object... args)
316: throws DataAccessException;
317:
318: /**
319: * Executes the supplied SQL statement with (optional) supplied arguments.
320: * Uses sql with the named parameter support provided by the
321: * {@link org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate}
322: * @param sql the SQL statement to execute.
323: * @param args the map containing the arguments for the query.
324: * @return the numbers of rows affected by the update.
325: * @see NamedParameterJdbcOperations#update(String, Map)
326: */
327: int update(String sql, Map args) throws DataAccessException;
328:
329: /**
330: * Executes the supplied SQL statement with supplied arguments.
331: * Uses sql with the named parameter support provided by the
332: * {@link org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate}
333: * @param sql the SQL statement to execute.
334: * @param args the <code>SqlParameterSource</code> containing the arguments for the statement.
335: * @return the numbers of rows affected by the update.
336: * @see NamedParameterJdbcOperations#update(String, SqlParameterSource)
337: */
338: int update(String sql, SqlParameterSource args)
339: throws DataAccessException;
340:
341: /**
342: * Executes the supplied SQL statement with supplied arguments.
343: * Uses sql with the standard '?' placeholders for parameters
344: * @param sql the SQL statement to execute.
345: * @param args the variable number of arguments for the query.
346: * @return the numbers of rows affected by the update.
347: * @see JdbcOperations#update(String)
348: * @see JdbcOperations#update(String, Object[])
349: */
350: int update(String sql, Object... args) throws DataAccessException;
351:
352: /**
353: * Executes a batch using the supplied SQL statement with the batch of supplied arguments.
354: * Uses sql with the named parameter support.
355: * @param sql the SQL statement to execute.
356: * @param batchValues the array of Maps containing the batch of arguments for the query.
357: * @return an array containing the numbers of rows affected by each update in the batch.
358: */
359: public int[] batchUpdate(String sql, Map[] batchValues);
360:
361: /**
362: * Executes a batch using the supplied SQL statement with the batch of supplied arguments.
363: * Uses sql with the named parameter support.
364: * @param sql the SQL statement to execute.
365: * @param batchArgs the array of {@link SqlParameterSource} containing the batch of arguments for the query.
366: * @return an array containing the numbers of rows affected by each update in the batch.
367: */
368: public int[] batchUpdate(String sql, SqlParameterSource[] batchArgs);
369:
370: /**
371: * Executes a batch using the supplied SQL statement with the batch of supplied arguments.
372: * Uses sql with the standard '?' placeholders for parameters
373: * @param sql the SQL statement to execute.
374: * @param batchArgs the List of Object arrays containing the batch of arguments for the query.
375: * @return an array containing the numbers of rows affected by each update in the batch.
376: */
377: public int[] batchUpdate(String sql, List<Object[]> batchArgs);
378:
379: /**
380: * Executes a batch using the supplied SQL statement with the batch of supplied arguments.
381: * Uses sql with the standard '?' placeholders for parameters
382: * @param sql the SQL statement to execute.
383: * @param batchArgs the List of Object arrays containing the batch of arguments for the query.
384: * @param argTypes SQL types of the arguments
385: * (constants from <code>java.sql.Types</code>)
386: * @return an array containing the numbers of rows affected by each update in the batch.
387: */
388: public int[] batchUpdate(String sql, List<Object[]> batchArgs,
389: int[] argTypes);
390:
391: }
|