Java > Open Source Codes > com > ibatis > sqlmap > client > SqlMapExecutor


1 /*
2  * Copyright 2004 Clinton Begin
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 package com.ibatis.sqlmap.client;
17
18 import com.ibatis.common.util.PaginatedList;
19 import com.ibatis.sqlmap.client.event.RowHandler;
20
21 import java.sql.SQLException ;
22 import java.util.List ;
23 import java.util.Map ;
24
25 /**
26  * This interface declares all methods involved with executing statements
27  * and batches for an SQL Map.
28  *
29  * @see SqlMapSession
30  * @see SqlMapClient
31  */
32 public interface SqlMapExecutor {
33
34   /**
35    * Executes a mapped SQL INSERT statement.
36    * Insert is a bit different from other update methods, as it
37    * provides facilities for returning the primary key of the
38    * newly inserted row (rather than the effected rows). This
39    * functionality is of course optional.
40    * <p/>
41    * The parameter object is generally used to supply the input
42    * data for the INSERT values.
43    *
44    * @param id The name of the statement to execute.
45    * @param parameterObject The parameter object (e.g. JavaBean, Map, XML etc.).
46    * @return The primary key of the newly inserted row. This might be automatically
47    * generated by the RDBMS, or selected from a sequence table or other source.
48    * @throws java.sql.SQLException If an error occurs.
49    */
50   Object insert(String id, Object parameterObject) throws SQLException ;
51
52   /**
53    * Executes a mapped SQL UPDATE statement.
54    * Update can also be used for any other update statement type,
55    * such as inserts and deletes. Update returns the number of
56    * rows effected.
57    * <p/>
58    * The parameter object is generally used to supply the input
59    * data for the UPDATE values as well as the WHERE clause parameter(s).
60    *
61    * @param id The name of the statement to execute.
62    * @param parameterObject The parameter object (e.g. JavaBean, Map, XML etc.).
63    * @return The number of rows effected.
64    * @throws java.sql.SQLException If an error occurs.
65    */
66   int update(String id, Object parameterObject) throws SQLException ;
67
68   /**
69    * Executes a mapped SQL DELETE statement.
70    * Delete returns the number of rows effected.
71    * <p/>
72    * The parameter object is generally used to supply the input
73    * data for the WHERE clause parameter(s) of the DELETE statement.
74    *
75    * @param id The name of the statement to execute.
76    * @param parameterObject The parameter object (e.g. JavaBean, Map, XML etc.).
77    * @return The number of rows effected.
78    * @throws java.sql.SQLException If an error occurs.
79    */
80   int delete(String id, Object parameterObject) throws SQLException ;
81
82   /**
83    * Executes a mapped SQL SELECT statement that returns data to populate
84    * a single object instance.
85    * <p/>
86    * The parameter object is generally used to supply the input
87    * data for the WHERE clause parameter(s) of the SELECT statement.
88    *
89    * @param id The name of the statement to execute.
90    * @param parameterObject The parameter object (e.g. JavaBean, Map, XML etc.).
91    * @return The single result object populated with the result set data,
92    * or null if no result was found
93    * @throws java.sql.SQLException If more than one result was found, or if any other error occurs.
94    */
95   Object queryForObject(String id, Object parameterObject) throws SQLException ;
96
97   /**
98    * Executes a mapped SQL SELECT statement that returns data to populate
99    * the supplied result object.
100    * <p/>
101    * The parameter object is generally used to supply the input
102    * data for the WHERE clause parameter(s) of the SELECT statement.
103    *
104    * @param id The name of the statement to execute.
105    * @param parameterObject The parameter object (e.g. JavaBean, Map, XML etc.).
106    * @param resultObject The result object instance that should be populated with result data.
107    * @return The single result object as supplied by the resultObject parameter, populated with the result set data,
108    * or null if no result was found
109    * @throws java.sql.SQLException If more than one result was found, or if any other error occurs.
110    */
111   Object queryForObject(String id, Object parameterObject, Object resultObject) throws SQLException ;
112
113   /**
114    * Executes a mapped SQL SELECT statement that returns data to populate
115    * a number of result objects.
116    * <p/>
117    * The parameter object is generally used to supply the input
118    * data for the WHERE clause parameter(s) of the SELECT statement.
119    *
120    * @param id The name of the statement to execute.
121    * @param parameterObject The parameter object (e.g. JavaBean, Map, XML etc.).
122    * @return A List of result objects.
123    * @throws java.sql.SQLException If an error occurs.
124    */
125   List queryForList(String id, Object parameterObject) throws SQLException ;
126
127   /**
128    * Executes a mapped SQL SELECT statement that returns data to populate
129    * a number of result objects within a certain range.
130    * <p/>
131    * The parameter object is generally used to supply the input
132    * data for the WHERE clause parameter(s) of the SELECT statement.
133    *
134    * @param id The name of the statement to execute.
135    * @param parameterObject The parameter object (e.g. JavaBean, Map, XML etc.).
136    * @param skip The number of results to ignore.
137    * @param max The maximum number of results to return.
138    * @return A List of result objects.
139    * @throws java.sql.SQLException If an error occurs.
140    */
141   List queryForList(String id, Object parameterObject, int skip, int max) throws SQLException ;
142
143   /**
144    * Executes a mapped SQL SELECT statement that returns a number of
145    * result objects that will be handled one at a time by a
146    * RowHandler.
147    * <p/>
148    * This is generally a good approach to take when dealing with large sets
149    * of records (i.e. hundreds, thousands...) that need to be processed without
150    * eating up all of the system resources.
151    * <p/>
152    * The parameter object is generally used to supply the input
153    * data for the WHERE clause parameter(s) of the SELECT statement.
154    *
155    * @param id The name of the statement to execute.
156    * @param parameterObject The parameter object (e.g. JavaBean, Map, XML etc.).
157    * @param rowHandler A RowHandler instance
158    * @throws java.sql.SQLException If an error occurs.
159    */
160   void queryWithRowHandler(String id, Object parameterObject, RowHandler rowHandler) throws SQLException ;
161
162   /**
163    * Executes a mapped SQL SELECT statement that returns data to populate
164    * a number of result objects a page at a time.
165    * <p/>
166    * The parameter object is generally used to supply the input
167    * data for the WHERE clause parameter(s) of the SELECT statement.
168    *
169    * @param id The name of the statement to execute.
170    * @param parameterObject The parameter object (e.g. JavaBean, Map, XML etc.).
171    * @param pageSize The maximum number of result objects each page can hold.
172    * @return A PaginatedList of result objects.
173    * @throws java.sql.SQLException If an error occurs.
174    */
175   PaginatedList queryForPaginatedList(String id, Object parameterObject, int pageSize) throws SQLException ;
176
177   /**
178    * Executes a mapped SQL SELECT statement that returns data to populate
179    * a number of result objects that will be keyed into a Map.
180    * <p/>
181    * The parameter object is generally used to supply the input
182    * data for the WHERE clause parameter(s) of the SELECT statement.
183    *
184    * @param id The name of the statement to execute.
185    * @param parameterObject The parameter object (e.g. JavaBean, Map, XML etc.).
186    * @param keyProp The property to be used as the key in the Map.
187    * @return A Map keyed by keyProp with values being the result object instance.
188    * @throws java.sql.SQLException If an error occurs.
189    */
190   Map queryForMap(String id, Object parameterObject, String keyProp) throws SQLException ;
191
192   /**
193    * Executes a mapped SQL SELECT statement that returns data to populate
194    * a number of result objects from which one property will be keyed into a Map.
195    * <p/>
196    * The parameter object is generally used to supply the input
197    * data for the WHERE clause parameter(s) of the SELECT statement.
198    *
199    * @param id The name of the statement to execute.
200    * @param parameterObject The parameter object (e.g. JavaBean, Map, XML etc.).
201    * @param keyProp The property to be used as the key in the Map.
202    * @param valueProp The property to be used as the value in the Map.
203    * @return A Map keyed by keyProp with values of valueProp.
204    * @throws java.sql.SQLException If an error occurs.
205    */
206   Map queryForMap(String id, Object parameterObject, String keyProp, String valueProp) throws SQLException ;
207
208   /**
209    * Starts a batch in which update statements will be cached before being sent to
210    * the database all at once. This can improve overall performance of updates update
211    * when dealing with numerous updates (e.g. inserting 1:M related data).
212    *
213    * @throws java.sql.SQLException If the batch could not be started.
214    */
215   void startBatch() throws SQLException ;
216
217   /**
218    * Executes (flushes) all statements currently batched.
219    *
220    * @return the number of rows updated in the batch
221    * @throws java.sql.SQLException If the batch could not be executed or if any of the statements
222    * fails.
223    */
224   int executeBatch() throws SQLException ;
225 }
226

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags