001: /*
002: * Copyright 2004 Clinton Begin
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: package com.ibatis.sqlmap.client;
017:
018: import com.ibatis.common.util.PaginatedList;
019: import com.ibatis.sqlmap.client.event.RowHandler;
020: import com.ibatis.sqlmap.engine.execution.BatchException;
021:
022: import java.sql.SQLException;
023: import java.util.List;
024: import java.util.Map;
025:
026: /**
027: * This interface declares all methods involved with executing statements
028: * and batches for an SQL Map.
029: *
030: * @see SqlMapSession
031: * @see SqlMapClient
032: */
033: public interface SqlMapExecutor {
034:
035: /**
036: * Executes a mapped SQL INSERT statement.
037: * Insert is a bit different from other update methods, as it
038: * provides facilities for returning the primary key of the
039: * newly inserted row (rather than the effected rows). This
040: * functionality is of course optional.
041: * <p/>
042: * The parameter object is generally used to supply the input
043: * data for the INSERT values.
044: *
045: * @param id The name of the statement to execute.
046: * @param parameterObject The parameter object (e.g. JavaBean, Map, XML etc.).
047: * @return The primary key of the newly inserted row. This might be automatically
048: * generated by the RDBMS, or selected from a sequence table or other source.
049: * @throws java.sql.SQLException If an error occurs.
050: */
051: Object insert(String id, Object parameterObject)
052: throws SQLException;
053:
054: /**
055: * Executes a mapped SQL INSERT statement.
056: * Insert is a bit different from other update methods, as it
057: * provides facilities for returning the primary key of the
058: * newly inserted row (rather than the effected rows). This
059: * functionality is of course optional.
060: * <p/>
061: * This overload assumes no parameter is needed.
062: *
063: * @param id The name of the statement to execute.
064: * @return The primary key of the newly inserted row. This might be automatically
065: * generated by the RDBMS, or selected from a sequence table or other source.
066: * @throws java.sql.SQLException If an error occurs.
067: */
068: Object insert(String id) throws SQLException;
069:
070: /**
071: * Executes a mapped SQL UPDATE statement.
072: * Update can also be used for any other update statement type,
073: * such as inserts and deletes. Update returns the number of
074: * rows effected.
075: * <p/>
076: * The parameter object is generally used to supply the input
077: * data for the UPDATE values as well as the WHERE clause parameter(s).
078: *
079: * @param id The name of the statement to execute.
080: * @param parameterObject The parameter object (e.g. JavaBean, Map, XML etc.).
081: * @return The number of rows effected.
082: * @throws java.sql.SQLException If an error occurs.
083: */
084: int update(String id, Object parameterObject) throws SQLException;
085:
086: /**
087: * Executes a mapped SQL UPDATE statement.
088: * Update can also be used for any other update statement type,
089: * such as inserts and deletes. Update returns the number of
090: * rows effected.
091: * <p/>
092: * This overload assumes no parameter is needed.
093: *
094: * @param id The name of the statement to execute.
095: * @return The number of rows effected.
096: * @throws java.sql.SQLException If an error occurs.
097: */
098: int update(String id) throws SQLException;
099:
100: /**
101: * Executes a mapped SQL DELETE statement.
102: * Delete returns the number of rows effected.
103: * <p/>
104: * The parameter object is generally used to supply the input
105: * data for the WHERE clause parameter(s) of the DELETE statement.
106: *
107: * @param id The name of the statement to execute.
108: * @param parameterObject The parameter object (e.g. JavaBean, Map, XML etc.).
109: * @return The number of rows effected.
110: * @throws java.sql.SQLException If an error occurs.
111: */
112: int delete(String id, Object parameterObject) throws SQLException;
113:
114: /**
115: * Executes a mapped SQL DELETE statement.
116: * Delete returns the number of rows effected.
117: * <p/>
118: * This overload assumes no parameter is needed.
119: *
120: * @param id The name of the statement to execute.
121: * @return The number of rows effected.
122: * @throws java.sql.SQLException If an error occurs.
123: */
124: int delete(String id) throws SQLException;
125:
126: /**
127: * Executes a mapped SQL SELECT statement that returns data to populate
128: * a single object instance.
129: * <p/>
130: * The parameter object is generally used to supply the input
131: * data for the WHERE clause parameter(s) of the SELECT statement.
132: *
133: * @param id The name of the statement to execute.
134: * @param parameterObject The parameter object (e.g. JavaBean, Map, XML etc.).
135: * @return The single result object populated with the result set data,
136: * or null if no result was found
137: * @throws java.sql.SQLException If more than one result was found, or if any other error occurs.
138: */
139: Object queryForObject(String id, Object parameterObject)
140: throws SQLException;
141:
142: /**
143: * Executes a mapped SQL SELECT statement that returns data to populate
144: * a single object instance.
145: * <p/>
146: * This overload assumes no parameter is needed.
147: *
148: * @param id The name of the statement to execute.
149: * @return The single result object populated with the result set data,
150: * or null if no result was found
151: * @throws java.sql.SQLException If more than one result was found, or if any other error occurs.
152: */
153: Object queryForObject(String id) throws SQLException;
154:
155: /**
156: * Executes a mapped SQL SELECT statement that returns data to populate
157: * the supplied result object.
158: * <p/>
159: * The parameter object is generally used to supply the input
160: * data for the WHERE clause parameter(s) of the SELECT statement.
161: *
162: * @param id The name of the statement to execute.
163: * @param parameterObject The parameter object (e.g. JavaBean, Map, XML etc.).
164: * @param resultObject The result object instance that should be populated with result data.
165: * @return The single result object as supplied by the resultObject parameter, populated with the result set data,
166: * or null if no result was found
167: * @throws java.sql.SQLException If more than one result was found, or if any other error occurs.
168: */
169: Object queryForObject(String id, Object parameterObject,
170: Object resultObject) throws SQLException;
171:
172: /**
173: * Executes a mapped SQL SELECT statement that returns data to populate
174: * a number of result objects.
175: * <p/>
176: * The parameter object is generally used to supply the input
177: * data for the WHERE clause parameter(s) of the SELECT statement.
178: *
179: * @param id The name of the statement to execute.
180: * @param parameterObject The parameter object (e.g. JavaBean, Map, XML etc.).
181: * @return A List of result objects.
182: * @throws java.sql.SQLException If an error occurs.
183: */
184: List queryForList(String id, Object parameterObject)
185: throws SQLException;
186:
187: /**
188: * Executes a mapped SQL SELECT statement that returns data to populate
189: * a number of result objects.
190: * <p/>
191: * This overload assumes no parameter is needed.
192: *
193: * @param id The name of the statement to execute.
194: * @return A List of result objects.
195: * @throws java.sql.SQLException If an error occurs.
196: */
197: List queryForList(String id) throws SQLException;
198:
199: /**
200: * Executes a mapped SQL SELECT statement that returns data to populate
201: * a number of result objects within a certain range.
202: * <p/>
203: * The parameter object is generally used to supply the input
204: * data for the WHERE clause parameter(s) of the SELECT statement.
205: *
206: * @param id The name of the statement to execute.
207: * @param parameterObject The parameter object (e.g. JavaBean, Map, XML etc.).
208: * @param skip The number of results to ignore.
209: * @param max The maximum number of results to return.
210: * @return A List of result objects.
211: * @throws java.sql.SQLException If an error occurs.
212: */
213: List queryForList(String id, Object parameterObject, int skip,
214: int max) throws SQLException;
215:
216: /**
217: * Executes a mapped SQL SELECT statement that returns data to populate
218: * a number of result objects within a certain range.
219: * <p/>
220: * This overload assumes no parameter is needed.
221: *
222: * @param id The name of the statement to execute.
223: * @param skip The number of results to ignore.
224: * @param max The maximum number of results to return.
225: * @return A List of result objects.
226: * @throws java.sql.SQLException If an error occurs.
227: */
228: List queryForList(String id, int skip, int max) throws SQLException;
229:
230: /**
231: * Executes a mapped SQL SELECT statement that returns a number of
232: * result objects that will be handled one at a time by a
233: * RowHandler.
234: * <p/>
235: * This is generally a good approach to take when dealing with large sets
236: * of records (i.e. hundreds, thousands...) that need to be processed without
237: * eating up all of the system resources.
238: * <p/>
239: * The parameter object is generally used to supply the input
240: * data for the WHERE clause parameter(s) of the SELECT statement.
241: *
242: * @param id The name of the statement to execute.
243: * @param parameterObject The parameter object (e.g. JavaBean, Map, XML etc.).
244: * @param rowHandler A RowHandler instance
245: * @throws java.sql.SQLException If an error occurs.
246: */
247: void queryWithRowHandler(String id, Object parameterObject,
248: RowHandler rowHandler) throws SQLException;
249:
250: /**
251: * Executes a mapped SQL SELECT statement that returns a number of
252: * result objects that will be handled one at a time by a
253: * RowHandler.
254: * <p/>
255: * This is generally a good approach to take when dealing with large sets
256: * of records (i.e. hundreds, thousands...) that need to be processed without
257: * eating up all of the system resources.
258: * <p/>
259: * This overload assumes no parameter is needed.
260: *
261: * @param id The name of the statement to execute.
262: * @param rowHandler A RowHandler instance
263: * @throws java.sql.SQLException If an error occurs.
264: */
265: void queryWithRowHandler(String id, RowHandler rowHandler)
266: throws SQLException;
267:
268: /**
269: * Executes a mapped SQL SELECT statement that returns data to populate
270: * a number of result objects a page at a time.
271: * <p/>
272: * The parameter object is generally used to supply the input
273: * data for the WHERE clause parameter(s) of the SELECT statement.
274: *
275: * @param id The name of the statement to execute.
276: * @param parameterObject The parameter object (e.g. JavaBean, Map, XML etc.).
277: * @param pageSize The maximum number of result objects each page can hold.
278: * @return A PaginatedList of result objects.
279: * @throws java.sql.SQLException If an error occurs.
280: * @deprecated All paginated list features have been deprecated
281: */
282: PaginatedList queryForPaginatedList(String id,
283: Object parameterObject, int pageSize) throws SQLException;
284:
285: /**
286: * Executes a mapped SQL SELECT statement that returns data to populate
287: * a number of result objects a page at a time.
288: * <p/>
289: * This overload assumes no parameter is needed.
290: *
291: * @param id The name of the statement to execute.
292: * @param pageSize The maximum number of result objects each page can hold.
293: * @return A PaginatedList of result objects.
294: * @throws java.sql.SQLException If an error occurs.
295: * @deprecated All paginated list features have been deprecated
296: */
297: PaginatedList queryForPaginatedList(String id, int pageSize)
298: throws SQLException;
299:
300: /**
301: * Executes a mapped SQL SELECT statement that returns data to populate
302: * a number of result objects that will be keyed into a Map.
303: * <p/>
304: * The parameter object is generally used to supply the input
305: * data for the WHERE clause parameter(s) of the SELECT statement.
306: *
307: * @param id The name of the statement to execute.
308: * @param parameterObject The parameter object (e.g. JavaBean, Map, XML etc.).
309: * @param keyProp The property to be used as the key in the Map.
310: * @return A Map keyed by keyProp with values being the result object instance.
311: * @throws java.sql.SQLException If an error occurs.
312: */
313: Map queryForMap(String id, Object parameterObject, String keyProp)
314: throws SQLException;
315:
316: /**
317: * Executes a mapped SQL SELECT statement that returns data to populate
318: * a number of result objects from which one property will be keyed into a Map.
319: * <p/>
320: * The parameter object is generally used to supply the input
321: * data for the WHERE clause parameter(s) of the SELECT statement.
322: *
323: * @param id The name of the statement to execute.
324: * @param parameterObject The parameter object (e.g. JavaBean, Map, XML etc.).
325: * @param keyProp The property to be used as the key in the Map.
326: * @param valueProp The property to be used as the value in the Map.
327: * @return A Map keyed by keyProp with values of valueProp.
328: * @throws java.sql.SQLException If an error occurs.
329: */
330: Map queryForMap(String id, Object parameterObject, String keyProp,
331: String valueProp) throws SQLException;
332:
333: /**
334: * Starts a batch in which update statements will be cached before being sent to
335: * the database all at once. This can improve overall performance of updates update
336: * when dealing with numerous updates (e.g. inserting 1:M related data).
337: *
338: * @throws java.sql.SQLException If the batch could not be started.
339: */
340: void startBatch() throws SQLException;
341:
342: /**
343: * Executes (flushes) all statements currently batched.
344: *
345: * @return the number of rows updated in the batch
346: * @throws java.sql.SQLException If the batch could not be executed or if any of the statements
347: * fails.
348: */
349: int executeBatch() throws SQLException;
350:
351: /**
352: * Executes (flushes) all statements currently batched.
353: *
354: * @return a List of BatchResult objects. There will be one element in the
355: * list for each sub-batch executed. A sub-batch is created by adding a statement
356: * to the batch that does not equal the prior statement.
357: * @throws SQLException if a database access error occurs, or the drive
358: * does not support batch statements
359: * @throws BatchException if the driver throws BatchUpdateException
360: * @see com.ibatis.sqlmap.engine.execution.BatchException
361: */
362: List executeBatchDetailed() throws SQLException, BatchException;
363: }
|