Clover coverage report - JFox Service-Oriented Application Framework - 1.0-RC3 Coverage timestamp: 星期三 二月 15 2006 18:10:22 CST FRAMES NO FRAMES |
file stats: | LOC: | 3,573 |  | Methods: | 0
| NCLOC: | 184 |  | Classes: | 1
30 day Evaluation Version distributed via the Maven Jar Repository. Clover is not free. You have 30 days to evaluate it. Please visit http://www.thecortex.net/clover to obtain a licensed version of Clover
Source file | Conditionals | Statements | Methods | TOTAL
MrPersisterService.java | - | - | - | - |

1 |  |
     /**
2 |  |
      * @(#)MrPersisterService.java
3 |  |
      *
4 |  |
      * JFoxSOAF, Service-Oriented Application Framework
5 |  |
      *
6 |  |
      * Copyright(c) JFoxSOAF Team
7 |  |
      *
8 |  |
      * Licensed under the GNU LGPL, Version 2.1 (the "License");
9 |  |
      * you may not use this file except in compliance with the License.
10 |  |
      * You may obtain a copy of the License at
11 |  |
      *
12 |  |
      * http://www.gnu.org/copyleft/lesser.html
13 |  |
      *
14 |  |
      * Unless required by applicable law or agreed to in writing, software
15 |  |
      * distributed under the License is distributed on an "AS IS" BASIS,
16 |  |
      * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17 |  |
      * See the License for the specific language governing permissions and
18 |  |
      * limitations under the License.
19 |  |
      *
20 |  |
      * For more information, please visit:
21 |  |
      * http://www.jfox.cn/confluence/display/JFoxSOAF/Home
22 |  |
      * http://www.huihoo.org/jfox/jfoxsoaf
23 |  |
      */
24 |  |
25 |  |
     package org.huihoo.jfox.soaf.services.persistence;
26 |  |
27 |  |
     import java.sql.Connection;
28 |  |
     import java.sql.PreparedStatement;
29 |  |
     import java.sql.ResultSet;
30 |  |
     import java.sql.Statement;
31 |  |
     import java.util.Collection;
32 |  |
     import java.util.List;
33 |  |
34 |  |
     import javax.sql.DataSource;
35 |  |
36 |  |
     import org.huihoo.jfox.soaf.exception.DAOException;
37 |  |
38 |  |
     import com.jenkov.mrpersister.itf.IReadFilter;
39 |  |
     import com.jenkov.mrpersister.itf.PersistenceException;
40 |  |
41 |  |
     /**
42 |  |
      * <p>
43 |  |
      * MrPersister persistence service wrapper.
44 |  |
      * </p>
45 |  |
      *
46 |  |
      * @author <a href="mailto:founder_chen@yahoo.com.cn">Peter Cheng </a>
47 |  |
      * @version $Revision: 1.1 $ $Date: 2006/02/15 08:45:45 $
48 |  |
      * @version Revision: 1.0
49 |  |
      */
50 |  |
51 |  |
     public interface MrPersisterService {
52 |  |
53 |  |
         /**
54 |  |
          * Set DataSource
55 |  |
          *
56 |  |
          * @param dataSource
57 |  |
          */
58 |  |
         void setDataSource(DataSource dataSource);
59 |  |
60 |  |
         /**
61 |  |
          * Reads a single object from the database using the object mapping stored
62 |  |
          * by the given object mapping key, and the given primary key to identify
63 |  |
          * the record in the database that coresponds to the object to be read. If
64 |  |
          * no record/object was found by the given primary key, null is returned.
65 |  |
          *
66 |  |
          * <br/><br/>A connection to the database will be obtained from the
67 |  |
          * getConnection() method of this instance.
68 |  |
          *
69 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
70 |  |
          * key, a new object mapping will be attempted generated and stored by that
71 |  |
          * object mapping key. An object mapping can only be generated automatically
72 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
73 |  |
          * com.jenkov.mrpersister.impl.ObjectMappingKey</code> instance with a
74 |  |
          * <code>Class</code> instance set (calling ObjectMappingKey's
75 |  |
          * setObjectClass(Class theClass) method).
76 |  |
          *
77 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
78 |  |
          * object to be read, meaning if you want to read an object of class <code>
79 |  |
          * Employee</code> the <code>Class</code> instance should be that found
80 |  |
          * at <code>Employee.class</code>.
81 |  |
          *
82 |  |
          * @param objectMappingKey
83 |  |
          *            The object mapping key by which the object mapping to be used
84 |  |
          *            is stored in the object mapping cache, in the persistence
85 |  |
          *            configuration used by this instance of the DAO class.
86 |  |
          * @param primaryKey
87 |  |
          *            The primary key value identifying the record to be read into
88 |  |
          *            an object.
89 |  |
          * @return The object coresponding to the given primary key, read according
90 |  |
          *         to the given object mapping. If no record/object was found by the
91 |  |
          *         given primary key, null is returned.
92 |  |
          * @throws PersistenceException
93 |  |
          *             If anything goes wrong during the read, if no persistence
94 |  |
          *             configuration is set, if the persistence configuration
95 |  |
          *             contains no object reader, or if no object mapping could be
96 |  |
          *             found nor generated from the given object mapping key.
97 |  |
          * @throws DAOException
98 |  |
          */
99 |  |
         Object readByPrimaryKey(Object objectMappingKey, Object primaryKey)
100 |  |
                 throws PersistenceException, DAOException;
101 |  |
102 |  |
         /**
103 |  |
          * Reads a single object from the database using the object mapping stored
104 |  |
          * by the given object mapping key, and the given primary key to identify
105 |  |
          * the record in the database that coresponds to the object to be read. If
106 |  |
          * no record/object was found by the given primary key, null is returned.
107 |  |
          *
108 |  |
          * <br/><br/>A connection to the database will be obtained from the
109 |  |
          * getConnection() method of this instance.
110 |  |
          *
111 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
112 |  |
          * key, a new object mapping will be attempted generated and stored by that
113 |  |
          * object mapping key. An object mapping can only be generated automatically
114 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
115 |  |
          * com.jenkov.mrpersister.impl.ObjectMappingKey</code> instance with a
116 |  |
          * <code>Class</code> instance set (calling ObjectMappingKey's
117 |  |
          * setObjectClass(Class theClass) method).
118 |  |
          *
119 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
120 |  |
          * object to be read, meaning if you want to read an object of class <code>
121 |  |
          * Employee</code> the <code>Class</code> instance should be that found
122 |  |
          * at <code>Employee.class</code>.
123 |  |
          *
124 |  |
          * @param conn
125 |  |
          *            JDBC Connection.
126 |  |
          * @param objectMappingKey
127 |  |
          *            The object mapping key by which the object mapping to be used
128 |  |
          *            is stored in the object mapping cache, in the persistence
129 |  |
          *            configuration used by this instance of the DAO class.
130 |  |
          * @param primaryKey
131 |  |
          *            The primary key value identifying the record to be read into
132 |  |
          *            an object.
133 |  |
          * @return The object coresponding to the given primary key, read according
134 |  |
          *         to the given object mapping. If no record/object was found by the
135 |  |
          *         given primary key, null is returned.
136 |  |
          * @throws PersistenceException
137 |  |
          *             If anything goes wrong during the read, if no persistence
138 |  |
          *             configuration is set, if the persistence configuration
139 |  |
          *             contains no object reader, or if no object mapping could be
140 |  |
          *             found nor generated from the given object mapping key.
141 |  |
          * @throws DAOException
142 |  |
          */
143 |  |
         Object readByPrimaryKey(Connection conn, Object objectMappingKey,
144 |  |
                 Object primaryKey) throws PersistenceException, DAOException;
145 |  |
146 |  |
         /**
147 |  |
          * Reads a single object from the database using the object mapping stored
148 |  |
          * by the given object mapping key, and the given SQL string. If the SQL
149 |  |
          * string results in more than one record in the <code>ResultSet</code>
150 |  |
          * generated by it, only the first record in the <code>ResultSet</code>
151 |  |
          * will be read into an object and returned.
152 |  |
          *
153 |  |
          * <br/><br/>A connection to the database will be obtained from the
154 |  |
          * getConnection() method of this instance.
155 |  |
          *
156 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
157 |  |
          * key, a new object mapping will be attempted generated and stored by that
158 |  |
          * object mapping key. An object mapping can only be generated automatically
159 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
160 |  |
          * com.jenkov.mrpersister.impl.ObjectMappingKey</code> instance with a
161 |  |
          * <code>Class</code> instance set (calling ObjectMappingKey's
162 |  |
          * setObjectClass(Class theClass) method).
163 |  |
          *
164 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
165 |  |
          * object to be read, meaning if you want to read an object of class <code>
166 |  |
          * Employee</code> the <code>Class</code> instance should be that found
167 |  |
          * at <code>Employee.class</code>.
168 |  |
          *
169 |  |
          * @param objectMappingKey
170 |  |
          *            The object mapping key by which the object mapping to be used
171 |  |
          *            is stored in the object mapping cache, in the persistence
172 |  |
          *            configuration used by this instance of the DAO class.
173 |  |
          * @param sql
174 |  |
          *            The SQL string locating the record to be read into an object.
175 |  |
          * @return The object read using the given SQL string and object mapping
176 |  |
          *         stored by the given object mapping key.
177 |  |
          * @throws PersistenceException
178 |  |
          *             If anything goes wrong during the read, if no persistence
179 |  |
          *             configuration is set, if the persistence configuration
180 |  |
          *             contains no object reader, or if no object mapping could be
181 |  |
          *             found nor generated from the given object mapping key.
182 |  |
          * @throws DAOException
183 |  |
          */
184 |  |
         Object read(Object objectMappingKey, String sql)
185 |  |
                 throws PersistenceException, DAOException;
186 |  |
187 |  |
         /**
188 |  |
          * Reads a single object from the database using the object mapping stored
189 |  |
          * by the given object mapping key, and the given SQL string. If the SQL
190 |  |
          * string results in more than one record in the <code>ResultSet</code>
191 |  |
          * generated by it, only the first record in the <code>ResultSet</code>
192 |  |
          * will be read into an object and returned.
193 |  |
          *
194 |  |
          * <br/><br/>A connection to the database will be obtained from the
195 |  |
          * getConnection() method of this instance.
196 |  |
          *
197 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
198 |  |
          * key, a new object mapping will be attempted generated and stored by that
199 |  |
          * object mapping key. An object mapping can only be generated automatically
200 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
201 |  |
          * com.jenkov.mrpersister.impl.ObjectMappingKey</code> instance with a
202 |  |
          * <code>Class</code> instance set (calling ObjectMappingKey's
203 |  |
          * setObjectClass(Class theClass) method).
204 |  |
          *
205 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
206 |  |
          * object to be read, meaning if you want to read an object of class <code>
207 |  |
          * Employee</code> the <code>Class</code> instance should be that found
208 |  |
          * at <code>Employee.class</code>.
209 |  |
          *
210 |  |
          * @param conn
211 |  |
          *            JDBC Connection.
212 |  |
          * @param objectMappingKey
213 |  |
          *            The object mapping key by which the object mapping to be used
214 |  |
          *            is stored in the object mapping cache, in the persistence
215 |  |
          *            configuration used by this instance of the DAO class.
216 |  |
          * @param sql
217 |  |
          *            The SQL string locating the record to be read into an object.
218 |  |
          * @return The object read using the given SQL string and object mapping
219 |  |
          *         stored by the given object mapping key.
220 |  |
          * @throws PersistenceException
221 |  |
          *             If anything goes wrong during the read, if no persistence
222 |  |
          *             configuration is set, if the persistence configuration
223 |  |
          *             contains no object reader, or if no object mapping could be
224 |  |
          *             found nor generated from the given object mapping key.
225 |  |
          * @throws DAOException
226 |  |
          */
227 |  |
         Object read(Connection conn, Object objectMappingKey, String sql)
228 |  |
                 throws PersistenceException, DAOException;
229 |  |
230 |  |
         /**
231 |  |
          * Reads a single object from the given <code>ResultSet</code> using the
232 |  |
          * object mapping stored by the given object mapping key. If the
233 |  |
          * <code>ResultSet</code> contains more than one record, only the first
234 |  |
          * record in the <code>ResultSet</code> will be read into an object and
235 |  |
          * returned.
236 |  |
          *
237 |  |
          * <br/><br/>No database connection will be opened. The object will be read
238 |  |
          * from the provided <code>ResultSet</code>. You must remember to close
239 |  |
          * the <code>ResultSet</code> yourself when you are done with it.
240 |  |
          *
241 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
242 |  |
          * key, a new object mapping will be attempted generated and stored by that
243 |  |
          * object mapping key. An object mapping can only be generated automatically
244 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
245 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
246 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
247 |  |
          * setObjectClass(Class theClass) method).
248 |  |
          *
249 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
250 |  |
          * object to be read, meaning if you want to read an object of class <code>
251 |  |
          * Employee</code> the <code>Class</code> instance should be that found
252 |  |
          * at <code>Employee.class</code>.
253 |  |
          *
254 |  |
          * @param objectMappingKey
255 |  |
          *            The object mapping key by which the object mapping to be used
256 |  |
          *            is stored in the object mapping cache, in the persistence
257 |  |
          *            configuration used by this instance of the DAO class.
258 |  |
          * @param result
259 |  |
          *            The <code>ResultSet</code> to read the object from.
260 |  |
          * @return The object read from the <code>ResultSet</code> using the
261 |  |
          *         object mapping stored by the given object mapping key.
262 |  |
          * @throws PersistenceException
263 |  |
          *             If anything goes wrong during the read, if no persistence
264 |  |
          *             configuration is set, if the persistence configuration
265 |  |
          *             contains no object reader, or if no object mapping could be
266 |  |
          *             found nor generated from the given object mapping key.
267 |  |
          * @throws DAOException.
268 |  |
          */
269 |  |
         Object read(Object objectMappingKey, ResultSet result)
270 |  |
                 throws PersistenceException, DAOException;
271 |  |
272 |  |
         /**
273 |  |
          * Reads a single object from the given <code>ResultSet</code> using the
274 |  |
          * object mapping stored by the given object mapping key. If the
275 |  |
          * <code>ResultSet</code> contains more than one record, only the first
276 |  |
          * record in the <code>ResultSet</code> will be read into an object and
277 |  |
          * returned.
278 |  |
          *
279 |  |
          * <br/><br/>No database connection will be opened. The object will be read
280 |  |
          * from the provided <code>ResultSet</code>. You must remember to close
281 |  |
          * the <code>ResultSet</code> yourself when you are done with it.
282 |  |
          *
283 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
284 |  |
          * key, a new object mapping will be attempted generated and stored by that
285 |  |
          * object mapping key. An object mapping can only be generated automatically
286 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
287 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
288 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
289 |  |
          * setObjectClass(Class theClass) method).
290 |  |
          *
291 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
292 |  |
          * object to be read, meaning if you want to read an object of class <code>
293 |  |
          * Employee</code> the <code>Class</code> instance should be that found
294 |  |
          * at <code>Employee.class</code>.
295 |  |
          *
296 |  |
          * @param conn
297 |  |
          *            JDBC Connection.
298 |  |
          * @param objectMappingKey
299 |  |
          *            The object mapping key by which the object mapping to be used
300 |  |
          *            is stored in the object mapping cache, in the persistence
301 |  |
          *            configuration used by this instance of the DAO class.
302 |  |
          * @param result
303 |  |
          *            The <code>ResultSet</code> to read the object from.
304 |  |
          * @return The object read from the <code>ResultSet</code> using the
305 |  |
          *         object mapping stored by the given object mapping key.
306 |  |
          * @throws PersistenceException
307 |  |
          *             If anything goes wrong during the read, if no persistence
308 |  |
          *             configuration is set, if the persistence configuration
309 |  |
          *             contains no object reader, or if no object mapping could be
310 |  |
          *             found nor generated from the given object mapping key.
311 |  |
          * @throws DAOException.
312 |  |
          */
313 |  |
         Object read(Connection conn, Object objectMappingKey, ResultSet result)
314 |  |
                 throws PersistenceException, DAOException;
315 |  |
316 |  |
         /**
317 |  |
          * Reads a single object from the database using the given
318 |  |
          * <code>Statement</code> instance, the given SQL string, and the object
319 |  |
          * mapping stored by the given object mapping key. If the
320 |  |
          * <code>ResultSet</code> generated by the <code>Statement</code>
321 |  |
          * instance when executing the SQL string contains more than one record,
322 |  |
          * only the first record in the <code>ResultSet</code> will be read into
323 |  |
          * an object and returned.
324 |  |
          *
325 |  |
          * <br/><br/>Use this method if you need to use a special/customized
326 |  |
          * <code>Statement</code> instance. If you don't need a special/customized
327 |  |
          * <code>Statement</code> instance, the other <code>read</code> methods
328 |  |
          * will be easier to use.
329 |  |
          *
330 |  |
          * <br/><br/>No database connection will be opened. The object will be read
331 |  |
          * using the provided <code>Statement</code> instance. You must remember
332 |  |
          * to close the <code>Statement</code> yourself when you are done with it.
333 |  |
          *
334 |  |
          *
335 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
336 |  |
          * key, a new object mapping will be attempted generated and stored by that
337 |  |
          * object mapping key. An object mapping can only be generated automatically
338 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
339 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
340 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
341 |  |
          * setObjectClass(Class theClass) method).
342 |  |
          *
343 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
344 |  |
          * object to be read, meaning if you want to read an object of class <code>
345 |  |
          * Employee</code> the <code>Class</code> instance should be that found
346 |  |
          * at <code>Employee.class</code>.
347 |  |
          *
348 |  |
          * @param objectMappingKey
349 |  |
          *            The object mapping key by which the object mapping to be used
350 |  |
          *            is stored in the object mapping cache, in the persistence
351 |  |
          *            configuration used by this instance of the DAO class.
352 |  |
          * @param statement
353 |  |
          *            The <code>Statement</code> instance to use to execute the
354 |  |
          *            SQL string.
355 |  |
          * @param sql
356 |  |
          *            The SQL string to be executed by the <code>Statement</code>
357 |  |
          *            instance.
358 |  |
          * @return
359 |  |
          * @throws PersistenceException
360 |  |
          *             If anything goes wrong during the read, if no persistence
361 |  |
          *             configuration is set, if the persistence configuration
362 |  |
          *             contains no object reader, or if no object mapping could be
363 |  |
          *             found nor generated from the given object mapping key.
364 |  |
          * @throws DAOException.
365 |  |
          */
366 |  |
         Object read(Object objectMappingKey, Statement statement, String sql)
367 |  |
                 throws PersistenceException, DAOException;
368 |  |
369 |  |
         /**
370 |  |
          * Reads a single object from the database using the given
371 |  |
          * <code>Statement</code> instance, the given SQL string, and the object
372 |  |
          * mapping stored by the given object mapping key. If the
373 |  |
          * <code>ResultSet</code> generated by the <code>Statement</code>
374 |  |
          * instance when executing the SQL string contains more than one record,
375 |  |
          * only the first record in the <code>ResultSet</code> will be read into
376 |  |
          * an object and returned.
377 |  |
          *
378 |  |
          * <br/><br/>Use this method if you need to use a special/customized
379 |  |
          * <code>Statement</code> instance. If you don't need a special/customized
380 |  |
          * <code>Statement</code> instance, the other <code>read</code> methods
381 |  |
          * will be easier to use.
382 |  |
          *
383 |  |
          * <br/><br/>No database connection will be opened. The object will be read
384 |  |
          * using the provided <code>Statement</code> instance. You must remember
385 |  |
          * to close the <code>Statement</code> yourself when you are done with it.
386 |  |
          *
387 |  |
          *
388 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
389 |  |
          * key, a new object mapping will be attempted generated and stored by that
390 |  |
          * object mapping key. An object mapping can only be generated automatically
391 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
392 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
393 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
394 |  |
          * setObjectClass(Class theClass) method).
395 |  |
          *
396 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
397 |  |
          * object to be read, meaning if you want to read an object of class <code>
398 |  |
          * Employee</code> the <code>Class</code> instance should be that found
399 |  |
          * at <code>Employee.class</code>.
400 |  |
          *
401 |  |
          * @param conn
402 |  |
          *            JDBC Connection.
403 |  |
          * @param objectMappingKey
404 |  |
          *            The object mapping key by which the object mapping to be used
405 |  |
          *            is stored in the object mapping cache, in the persistence
406 |  |
          *            configuration used by this instance of the DAO class.
407 |  |
          * @param statement
408 |  |
          *            The <code>Statement</code> instance to use to execute the
409 |  |
          *            SQL string.
410 |  |
          * @param sql
411 |  |
          *            The SQL string to be executed by the <code>Statement</code>
412 |  |
          *            instance.
413 |  |
          * @return
414 |  |
          * @throws PersistenceException
415 |  |
          *             If anything goes wrong during the read, if no persistence
416 |  |
          *             configuration is set, if the persistence configuration
417 |  |
          *             contains no object reader, or if no object mapping could be
418 |  |
          *             found nor generated from the given object mapping key.
419 |  |
          * @throws DAOException.
420 |  |
          */
421 |  |
         Object read(Connection conn, Object objectMappingKey, Statement statement,
422 |  |
                 String sql) throws PersistenceException, DAOException;
423 |  |
424 |  |
         /**
425 |  |
          * Reads a single object from the database using the given
426 |  |
          * <code>PreparedStatement</code> instance, and the object mapping stored
427 |  |
          * by the given object mapping key. The <code>PreparedStatement</code>
428 |  |
          * instance must have all parameters set before calling this method (using
429 |  |
          * the PreparedStatement.setXXX(index, value) methods). If the
430 |  |
          * <code>ResultSet</code> generated by the <code>PreparedStatement</code>
431 |  |
          * instance contains more than one record, only the first record in the
432 |  |
          * <code>ResultSet</code> will be read into an object and returned.
433 |  |
          *
434 |  |
          * <br/><br/>No database connection will be opened. The object will be read
435 |  |
          * using the <code>PreparedStatement</code> passed as parameter. You must
436 |  |
          * remember to close the <code>PreparedStatement</code> yourself when you
437 |  |
          * are done with it.
438 |  |
          *
439 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
440 |  |
          * key, a new object mapping will be attempted generated and stored by that
441 |  |
          * object mapping key. An object mapping can only be generated automatically
442 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
443 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
444 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
445 |  |
          * setObjectClass(Class theClass) method).
446 |  |
          *
447 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
448 |  |
          * object to be read, meaning if you want to read an object of class <code>
449 |  |
          * Employee</code> the <code>Class</code> instance should be that found
450 |  |
          * at <code>Employee.class</code>.
451 |  |
          *
452 |  |
          * @param objectMappingKey
453 |  |
          *            The object mapping key by which the object mapping to be used
454 |  |
          *            is stored in the object mapping cache, in the persistence
455 |  |
          *            configuration used by this instance of the DAO class.
456 |  |
          * @param statement
457 |  |
          *            The <code>PreparedStatement</code> instance locating the
458 |  |
          *            object to read.
459 |  |
          * @return The object read from the <code>ResultSet</code> generated by
460 |  |
          *         the given <code>PreparedStatement</code>, according to the
461 |  |
          *         object mapping located or generated by the given object mapping
462 |  |
          *         key.
463 |  |
          * @throws PersistenceException
464 |  |
          *             If anything goes wrong during the read, if no persistence
465 |  |
          *             configuration is set, if the persistence configuration
466 |  |
          *             contains no object reader, or if no object mapping could be
467 |  |
          *             found nor generated from the given object mapping key.
468 |  |
          * @throws DAOException
469 |  |
          */
470 |  |
         Object read(Object objectMappingKey, PreparedStatement statement)
471 |  |
                 throws PersistenceException, DAOException;
472 |  |
473 |  |
         /**
474 |  |
          * Reads a single object from the database using the given
475 |  |
          * <code>PreparedStatement</code> instance, and the object mapping stored
476 |  |
          * by the given object mapping key. The <code>PreparedStatement</code>
477 |  |
          * instance must have all parameters set before calling this method (using
478 |  |
          * the PreparedStatement.setXXX(index, value) methods). If the
479 |  |
          * <code>ResultSet</code> generated by the <code>PreparedStatement</code>
480 |  |
          * instance contains more than one record, only the first record in the
481 |  |
          * <code>ResultSet</code> will be read into an object and returned.
482 |  |
          *
483 |  |
          * <br/><br/>No database connection will be opened. The object will be read
484 |  |
          * using the <code>PreparedStatement</code> passed as parameter. You must
485 |  |
          * remember to close the <code>PreparedStatement</code> yourself when you
486 |  |
          * are done with it.
487 |  |
          *
488 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
489 |  |
          * key, a new object mapping will be attempted generated and stored by that
490 |  |
          * object mapping key. An object mapping can only be generated automatically
491 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
492 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
493 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
494 |  |
          * setObjectClass(Class theClass) method).
495 |  |
          *
496 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
497 |  |
          * object to be read, meaning if you want to read an object of class <code>
498 |  |
          * Employee</code> the <code>Class</code> instance should be that found
499 |  |
          * at <code>Employee.class</code>.
500 |  |
          *
501 |  |
          * @param conn
502 |  |
          *            JDBC Connection.
503 |  |
          * @param objectMappingKey
504 |  |
          *            The object mapping key by which the object mapping to be used
505 |  |
          *            is stored in the object mapping cache, in the persistence
506 |  |
          *            configuration used by this instance of the DAO class.
507 |  |
          * @param statement
508 |  |
          *            The <code>PreparedStatement</code> instance locating the
509 |  |
          *            object to read.
510 |  |
          * @return The object read from the <code>ResultSet</code> generated by
511 |  |
          *         the given <code>PreparedStatement</code>, according to the
512 |  |
          *         object mapping located or generated by the given object mapping
513 |  |
          *         key.
514 |  |
          * @throws PersistenceException
515 |  |
          *             If anything goes wrong during the read, if no persistence
516 |  |
          *             configuration is set, if the persistence configuration
517 |  |
          *             contains no object reader, or if no object mapping could be
518 |  |
          *             found nor generated from the given object mapping key.
519 |  |
          */
520 |  |
         Object read(Connection conn, Object objectMappingKey,
521 |  |
                 PreparedStatement statement) throws PersistenceException,
522 |  |
                 DAOException;
523 |  |
524 |  |
         /**
525 |  |
          * Reads a single object from the database using the given SQL string, the
526 |  |
          * parameters, and the object mapping stored by the given object mapping
527 |  |
          * key.
528 |  |
          *
529 |  |
          * <br/><br/>A <code>PreparedStatement</code> instance will be created
530 |  |
          * using the given SQL string, and the parameters collection will be
531 |  |
          * inserted into it. Therefore the SQL string should have the same format as
532 |  |
          * those used with a <code>PreparedStatement</code>. The parameters will
533 |  |
          * be inserted in the sequence returned by the parameter collection's
534 |  |
          * iterator.
535 |  |
          *
536 |  |
          * <br/><br/>If the <code>ResultSet</code> generated by the
537 |  |
          * <code>PreparedStatement</code> instance contains more than one record,
538 |  |
          * only the first record in the <code>ResultSet</code> will be read into
539 |  |
          * an object and returned.
540 |  |
          *
541 |  |
          * <br/><br/>A connection to the database will be obtained from the
542 |  |
          * getConnection() method of this instance.
543 |  |
          *
544 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
545 |  |
          * key, a new object mapping will be attempted generated and stored by that
546 |  |
          * object mapping key. An object mapping can only be generated automatically
547 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
548 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
549 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
550 |  |
          * setObjectClass(Class theClass) method).
551 |  |
          *
552 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
553 |  |
          * object to be read, meaning if you want to read an object of class <code>
554 |  |
          * Employee</code> the <code>Class</code> instance should be that found
555 |  |
          * at <code>Employee.class</code>.
556 |  |
          *
557 |  |
          * @param objectMappingKey
558 |  |
          *            The object mapping key by which the object mapping to be used
559 |  |
          *            is stored in the object mapping cache, in the persistence
560 |  |
          *            configuration used by this instance of the DAO class.
561 |  |
          * @return The object read from the <code>ResultSet</code> generated by
562 |  |
          *         the given <code>PreparedStatement</code>, according to the
563 |  |
          *         object mapping located or generated by the given object mapping
564 |  |
          *         key.
565 |  |
          * @throws PersistenceException
566 |  |
          *             If anything goes wrong during the read, if no persistence
567 |  |
          *             configuration is set, if the persistence configuration
568 |  |
          *             contains no object reader, or if no object mapping could be
569 |  |
          *             found nor generated from the given object mapping key.
570 |  |
          * @throws DAOException
571 |  |
          */
572 |  |
         Object read(Object objectMappingKey, String sql, Collection parameters)
573 |  |
                 throws PersistenceException, DAOException;
574 |  |
575 |  |
         /**
576 |  |
          * Reads a single object from the database using the given SQL string, the
577 |  |
          * parameters, and the object mapping stored by the given object mapping
578 |  |
          * key.
579 |  |
          *
580 |  |
          * <br/><br/>A <code>PreparedStatement</code> instance will be created
581 |  |
          * using the given SQL string, and the parameters collection will be
582 |  |
          * inserted into it. Therefore the SQL string should have the same format as
583 |  |
          * those used with a <code>PreparedStatement</code>. The parameters will
584 |  |
          * be inserted in the sequence returned by the parameter collection's
585 |  |
          * iterator.
586 |  |
          *
587 |  |
          * <br/><br/>If the <code>ResultSet</code> generated by the
588 |  |
          * <code>PreparedStatement</code> instance contains more than one record,
589 |  |
          * only the first record in the <code>ResultSet</code> will be read into
590 |  |
          * an object and returned.
591 |  |
          *
592 |  |
          * <br/><br/>A connection to the database will be obtained from the
593 |  |
          * getConnection() method of this instance.
594 |  |
          *
595 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
596 |  |
          * key, a new object mapping will be attempted generated and stored by that
597 |  |
          * object mapping key. An object mapping can only be generated automatically
598 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
599 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
600 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
601 |  |
          * setObjectClass(Class theClass) method).
602 |  |
          *
603 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
604 |  |
          * object to be read, meaning if you want to read an object of class <code>
605 |  |
          * Employee</code> the <code>Class</code> instance should be that found
606 |  |
          * at <code>Employee.class</code>.
607 |  |
          *
608 |  |
          * @param objectMappingKey
609 |  |
          *            The object mapping key by which the object mapping to be used
610 |  |
          *            is stored in the object mapping cache, in the persistence
611 |  |
          *            configuration used by this instance of the DAO class.
612 |  |
          * @return The object read from the <code>ResultSet</code> generated by
613 |  |
          *         the given <code>PreparedStatement</code>, according to the
614 |  |
          *         object mapping located or generated by the given object mapping
615 |  |
          *         key.
616 |  |
          * @throws PersistenceException
617 |  |
          *             If anything goes wrong during the read, if no persistence
618 |  |
          *             configuration is set, if the persistence configuration
619 |  |
          *             contains no object reader, or if no object mapping could be
620 |  |
          *             found nor generated from the given object mapping key.
621 |  |
          * @throws DAOException
622 |  |
          */
623 |  |
         Object read(Connection conn, Object objectMappingKey, String sql,
624 |  |
                 Collection parameters) throws PersistenceException, DAOException;
625 |  |
626 |  |
         /**
627 |  |
          * Reads a single object from the database using the given SQL string, the
628 |  |
          * parameters, and the object mapping stored by the given object mapping
629 |  |
          * key.
630 |  |
          *
631 |  |
          * <br/><br/>A <code>PreparedStatement</code> instance will be created
632 |  |
          * using the given SQL string, and the parameters collection will be
633 |  |
          * inserted into it. Therefore the SQL string should have the same format as
634 |  |
          * those used with a <code>PreparedStatement</code>. The parameters will
635 |  |
          * be inserted in the sequence returned by the parameter collection's
636 |  |
          * iterator.
637 |  |
          *
638 |  |
          * <br/><br/>If the <code>ResultSet</code> generated by the
639 |  |
          * <code>PreparedStatement</code> instance contains more than one record,
640 |  |
          * only the first record in the <code>ResultSet</code> will be read into
641 |  |
          * an object and returned.
642 |  |
          *
643 |  |
          * <br/><br/>A connection to the database will be obtained from the
644 |  |
          * getConnection() method of this instance.
645 |  |
          *
646 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
647 |  |
          * key, a new object mapping will be attempted generated and stored by that
648 |  |
          * object mapping key. An object mapping can only be generated automatically
649 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
650 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
651 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
652 |  |
          * setObjectClass(Class theClass) method).
653 |  |
          *
654 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
655 |  |
          * object to be read, meaning if you want to read an object of class <code>
656 |  |
          * Employee</code> the <code>Class</code> instance should be that found
657 |  |
          * at <code>Employee.class</code>.
658 |  |
          *
659 |  |
          * @param objectMappingKey
660 |  |
          *            The object mapping key by which the object mapping to be used
661 |  |
          *            is stored in the object mapping cache, in the persistence
662 |  |
          *            configuration used by this instance of the DAO class.
663 |  |
          * @return The object read from the <code>ResultSet</code> generated by
664 |  |
          *         the given <code>PreparedStatement</code>, according to the
665 |  |
          *         object mapping located or generated by the given object mapping
666 |  |
          *         key.
667 |  |
          * @throws PersistenceException
668 |  |
          *             If anything goes wrong during the read, if no persistence
669 |  |
          *             configuration is set, if the persistence configuration
670 |  |
          *             contains no object reader, or if no object mapping could be
671 |  |
          *             found nor generated from the given object mapping key.
672 |  |
          * @throws DAOException
673 |  |
          */
674 |  |
         Object read(Object objectMappingKey, String sql, Object[] parameters)
675 |  |
                 throws PersistenceException, DAOException;
676 |  |
677 |  |
         /**
678 |  |
          * Reads a single object from the database using the given SQL string, the
679 |  |
          * parameters, and the object mapping stored by the given object mapping
680 |  |
          * key.
681 |  |
          *
682 |  |
          * <br/><br/>A <code>PreparedStatement</code> instance will be created
683 |  |
          * using the given SQL string, and the parameters collection will be
684 |  |
          * inserted into it. Therefore the SQL string should have the same format as
685 |  |
          * those used with a <code>PreparedStatement</code>. The parameters will
686 |  |
          * be inserted in the sequence returned by the parameter collection's
687 |  |
          * iterator.
688 |  |
          *
689 |  |
          * <br/><br/>If the <code>ResultSet</code> generated by the
690 |  |
          * <code>PreparedStatement</code> instance contains more than one record,
691 |  |
          * only the first record in the <code>ResultSet</code> will be read into
692 |  |
          * an object and returned.
693 |  |
          *
694 |  |
          * <br/><br/>A connection to the database will be obtained from the
695 |  |
          * getConnection() method of this instance.
696 |  |
          *
697 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
698 |  |
          * key, a new object mapping will be attempted generated and stored by that
699 |  |
          * object mapping key. An object mapping can only be generated automatically
700 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
701 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
702 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
703 |  |
          * setObjectClass(Class theClass) method).
704 |  |
          *
705 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
706 |  |
          * object to be read, meaning if you want to read an object of class <code>
707 |  |
          * Employee</code> the <code>Class</code> instance should be that found
708 |  |
          * at <code>Employee.class</code>.
709 |  |
          *
710 |  |
          * @param conn
711 |  |
          *            JDBC Connection.
712 |  |
          * @param objectMappingKey
713 |  |
          *            The object mapping key by which the object mapping to be used
714 |  |
          *            is stored in the object mapping cache, in the persistence
715 |  |
          *            configuration used by this instance of the DAO class.
716 |  |
          * @return The object read from the <code>ResultSet</code> generated by
717 |  |
          *         the given <code>PreparedStatement</code>, according to the
718 |  |
          *         object mapping located or generated by the given object mapping
719 |  |
          *         key.
720 |  |
          * @throws PersistenceException
721 |  |
          *             If anything goes wrong during the read, if no persistence
722 |  |
          *             configuration is set, if the persistence configuration
723 |  |
          *             contains no object reader, or if no object mapping could be
724 |  |
          *             found nor generated from the given object mapping key.
725 |  |
          * @throws DAOException
726 |  |
          */
727 |  |
         Object read(Connection conn, Object objectMappingKey, String sql,
728 |  |
                 Object[] parameters) throws PersistenceException, DAOException;
729 |  |
730 |  |
         /**
731 |  |
          * Reads a list of objects from the database using the object mapping stored
732 |  |
          * by the given object mapping key, and the given primary keys to identify
733 |  |
          * the records in the database that coresponds to the objects to be read. If
734 |  |
          * no records/objects were found by the given primary keys, an empty list is
735 |  |
          * returned. An empty list is also returned if the collection of primary
736 |  |
          * keys passed to this method is empty.
737 |  |
          *
738 |  |
          * <br/><br/>A connection to the database will be obtained from the
739 |  |
          * getConnection() method of this instance.
740 |  |
          *
741 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
742 |  |
          * key, a new object mapping will be attempted generated and stored by that
743 |  |
          * object mapping key. An object mapping can only be generated automatically
744 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
745 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
746 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
747 |  |
          * setObjectClass(Class theClass) method).
748 |  |
          *
749 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
750 |  |
          * objects to be read, meaning if you want to read objects of class <code>
751 |  |
          * Employee</code> the <code>Class</code> instance should be that found
752 |  |
          * at <code>Employee.class</code>.
753 |  |
          *
754 |  |
          * @param objectMappingKey
755 |  |
          *            The object mapping key by which the object mapping to be used
756 |  |
          *            is stored in the object mapping cache, in the persistence
757 |  |
          *            configuration used by this instance of the DAO class.
758 |  |
          * @param primaryKeys
759 |  |
          *            The primary key values identifying the records to be read into
760 |  |
          *            objects.
761 |  |
          * @return The list of objects coresponding to the given primary keys, read
762 |  |
          *         according to the given object mapping. If no records/objects were
763 |  |
          *         found by the given primary keys, an empty list is returned. An
764 |  |
          *         empty list is also returned if the collection of primary keys
765 |  |
          *         passed to this method is empty.
766 |  |
          * @throws PersistenceException
767 |  |
          *             If anything goes wrong during the read, if no persistence
768 |  |
          *             configuration is set, if the persistence configuration
769 |  |
          *             contains no object reader, or if no object mapping could be
770 |  |
          *             found nor generated from the given object mapping key.
771 |  |
          * @throws DAOException
772 |  |
          */
773 |  |
         List readListByPrimaryKeys(Object objectMappingKey, Collection primaryKeys)
774 |  |
                 throws PersistenceException, DAOException;
775 |  |
776 |  |
         /**
777 |  |
          * Reads a list of objects from the database using the object mapping stored
778 |  |
          * by the given object mapping key, and the given primary keys to identify
779 |  |
          * the records in the database that coresponds to the objects to be read. If
780 |  |
          * no records/objects were found by the given primary keys, an empty list is
781 |  |
          * returned. An empty list is also returned if the collection of primary
782 |  |
          * keys passed to this method is empty.
783 |  |
          *
784 |  |
          * <br/><br/>A connection to the database will be obtained from the
785 |  |
          * getConnection() method of this instance.
786 |  |
          *
787 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
788 |  |
          * key, a new object mapping will be attempted generated and stored by that
789 |  |
          * object mapping key. An object mapping can only be generated automatically
790 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
791 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
792 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
793 |  |
          * setObjectClass(Class theClass) method).
794 |  |
          *
795 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
796 |  |
          * objects to be read, meaning if you want to read objects of class <code>
797 |  |
          * Employee</code> the <code>Class</code> instance should be that found
798 |  |
          * at <code>Employee.class</code>.
799 |  |
          *
800 |  |
          * @param conn
801 |  |
          *            JDBC Connection.
802 |  |
          * @param objectMappingKey
803 |  |
          *            The object mapping key by which the object mapping to be used
804 |  |
          *            is stored in the object mapping cache, in the persistence
805 |  |
          *            configuration used by this instance of the DAO class.
806 |  |
          * @param primaryKeys
807 |  |
          *            The primary key values identifying the records to be read into
808 |  |
          *            objects.
809 |  |
          * @return The list of objects coresponding to the given primary keys, read
810 |  |
          *         according to the given object mapping. If no records/objects were
811 |  |
          *         found by the given primary keys, an empty list is returned. An
812 |  |
          *         empty list is also returned if the collection of primary keys
813 |  |
          *         passed to this method is empty.
814 |  |
          * @throws PersistenceException
815 |  |
          *             If anything goes wrong during the read, if no persistence
816 |  |
          *             configuration is set, if the persistence configuration
817 |  |
          *             contains no object reader, or if no object mapping could be
818 |  |
          *             found nor generated from the given object mapping key.
819 |  |
          * @throws DAOException
820 |  |
          */
821 |  |
         List readListByPrimaryKeys(Connection conn, Object objectMappingKey,
822 |  |
                 Collection primaryKeys) throws PersistenceException, DAOException;
823 |  |
824 |  |
         /**
825 |  |
          * Reads a list of objects from the database using the object mapping stored
826 |  |
          * or generated by the given object mapping key, and the given SQL string.
827 |  |
          * The objects will appear in the list in the same order their coresponding
828 |  |
          * records appear in the <code>ResultSet</code> generated by the SQL
829 |  |
          * string.
830 |  |
          *
831 |  |
          * <br/><br/>A connection to the database will be obtained from the
832 |  |
          * getConnection() method of this instance.
833 |  |
          *
834 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
835 |  |
          * key, a new object mapping will be attempted generated and stored by that
836 |  |
          * object mapping key. An object mapping can only be generated automatically
837 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
838 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
839 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
840 |  |
          * setObjectClass(Class theClass) method).
841 |  |
          *
842 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
843 |  |
          * objects to be read, meaning if you want to read objects of class <code>
844 |  |
          * Employee</code> the <code>Class</code> instance should be that found
845 |  |
          * at <code>Employee.class</code>.
846 |  |
          *
847 |  |
          * @param objectMappingKey
848 |  |
          *            The object mapping key by which the object mapping to be used
849 |  |
          *            is stored in the object mapping cache, in the persistence
850 |  |
          *            configuration used by this instance of the DAO class.
851 |  |
          * @param sql
852 |  |
          *            The String string locating the records to be read into
853 |  |
          *            objects.
854 |  |
          * @return A <code>List</code> of objects read from the database.
855 |  |
          * @throws PersistenceException
856 |  |
          *             If anything goes wrong during the read, if no persistence
857 |  |
          *             configuration is set, if the persistence configuration
858 |  |
          *             contains no object reader, or if no object mapping could be
859 |  |
          *             found nor generated from the given object mapping key.
860 |  |
          * @throws DAOException
861 |  |
          */
862 |  |
         List readList(Object objectMappingKey, String sql)
863 |  |
                 throws PersistenceException, DAOException;
864 |  |
865 |  |
         /**
866 |  |
          * Reads a list of objects from the database using the object mapping stored
867 |  |
          * or generated by the given object mapping key, and the given SQL string.
868 |  |
          * The objects will appear in the list in the same order their coresponding
869 |  |
          * records appear in the <code>ResultSet</code> generated by the SQL
870 |  |
          * string.
871 |  |
          *
872 |  |
          * <br/><br/>A connection to the database will be obtained from the
873 |  |
          * getConnection() method of this instance.
874 |  |
          *
875 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
876 |  |
          * key, a new object mapping will be attempted generated and stored by that
877 |  |
          * object mapping key. An object mapping can only be generated automatically
878 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
879 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
880 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
881 |  |
          * setObjectClass(Class theClass) method).
882 |  |
          *
883 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
884 |  |
          * objects to be read, meaning if you want to read objects of class <code>
885 |  |
          * Employee</code> the <code>Class</code> instance should be that found
886 |  |
          * at <code>Employee.class</code>.
887 |  |
          *
888 |  |
          * @param conn
889 |  |
          *            JDBC Connection.
890 |  |
          * @param objectMappingKey
891 |  |
          *            The object mapping key by which the object mapping to be used
892 |  |
          *            is stored in the object mapping cache, in the persistence
893 |  |
          *            configuration used by this instance of the DAO class.
894 |  |
          * @param sql
895 |  |
          *            The String string locating the records to be read into
896 |  |
          *            objects.
897 |  |
          * @return A <code>List</code> of objects read from the database.
898 |  |
          * @throws PersistenceException
899 |  |
          *             If anything goes wrong during the read, if no persistence
900 |  |
          *             configuration is set, if the persistence configuration
901 |  |
          *             contains no object reader, or if no object mapping could be
902 |  |
          *             found nor generated from the given object mapping key.
903 |  |
          * @throws DAOException
904 |  |
          */
905 |  |
         List readList(Connection conn, Object objectMappingKey, String sql)
906 |  |
                 throws PersistenceException, DAOException;
907 |  |
908 |  |
         /**
909 |  |
          * Reads a list of objects from the given <code>ResultSet</code> using the
910 |  |
          * object mapping stored or generated by the given object mapping key. The
911 |  |
          * objects will appear in the list in the same order their coresponding
912 |  |
          * records appear in the <code>ResultSet</code>.
913 |  |
          *
914 |  |
          * <br/><br/>No database connection will be opened. The object will be read
915 |  |
          * from the provided <code>ResultSet</code>. You must remember to close
916 |  |
          * the <code>ResultSet</code> yourself when you are done with it.
917 |  |
          *
918 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
919 |  |
          * key, a new object mapping will be attempted generated and stored by that
920 |  |
          * object mapping key. An object mapping can only be generated automatically
921 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
922 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
923 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
924 |  |
          * setObjectClass(Class theClass) method).
925 |  |
          *
926 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
927 |  |
          * objects to be read, meaning if you want to read objects of class <code>
928 |  |
          * Employee</code> the <code>Class</code> instance should be that found
929 |  |
          * at <code>Employee.class</code>.
930 |  |
          *
931 |  |
          * @param objectMappingKey
932 |  |
          *            The object mapping key by which the object mapping to be used
933 |  |
          *            is stored in the object mapping cache, in the persistence
934 |  |
          *            configuration used by this instance of the DAO class.
935 |  |
          * @param result
936 |  |
          *            The <code>ResultSet</code> to read the list of objects from.
937 |  |
          * @return A <code>List</code> of objects read from the database.
938 |  |
          * @throws PersistenceException
939 |  |
          *             If anything goes wrong during the read, if no persistence
940 |  |
          *             configuration is set, if the persistence configuration
941 |  |
          *             contains no object reader, or if no object mapping could be
942 |  |
          *             found nor generated from the given object mapping key.
943 |  |
          * @throws DAOException
944 |  |
          */
945 |  |
         List readList(Object objectMappingKey, ResultSet result)
946 |  |
                 throws PersistenceException, DAOException;
947 |  |
948 |  |
         /**
949 |  |
          * Reads a list of objects from the given <code>ResultSet</code> using the
950 |  |
          * object mapping stored or generated by the given object mapping key. The
951 |  |
          * objects will appear in the list in the same order their coresponding
952 |  |
          * records appear in the <code>ResultSet</code>.
953 |  |
          *
954 |  |
          * <br/><br/>No database connection will be opened. The object will be read
955 |  |
          * from the provided <code>ResultSet</code>. You must remember to close
956 |  |
          * the <code>ResultSet</code> yourself when you are done with it.
957 |  |
          *
958 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
959 |  |
          * key, a new object mapping will be attempted generated and stored by that
960 |  |
          * object mapping key. An object mapping can only be generated automatically
961 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
962 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
963 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
964 |  |
          * setObjectClass(Class theClass) method).
965 |  |
          *
966 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
967 |  |
          * objects to be read, meaning if you want to read objects of class <code>
968 |  |
          * Employee</code> the <code>Class</code> instance should be that found
969 |  |
          * at <code>Employee.class</code>.
970 |  |
          *
971 |  |
          * @param conn
972 |  |
          *            JDBC Connection.
973 |  |
          * @param objectMappingKey
974 |  |
          *            The object mapping key by which the object mapping to be used
975 |  |
          *            is stored in the object mapping cache, in the persistence
976 |  |
          *            configuration used by this instance of the DAO class.
977 |  |
          * @param result
978 |  |
          *            The <code>ResultSet</code> to read the list of objects from.
979 |  |
          * @return A <code>List</code> of objects read from the database.
980 |  |
          * @throws PersistenceException
981 |  |
          *             If anything goes wrong during the read, if no persistence
982 |  |
          *             configuration is set, if the persistence configuration
983 |  |
          *             contains no object reader, or if no object mapping could be
984 |  |
          *             found nor generated from the given object mapping key.
985 |  |
          * @throws DAOException
986 |  |
          */
987 |  |
         List readList(Connection conn, Object objectMappingKey, ResultSet result)
988 |  |
                 throws PersistenceException, DAOException;
989 |  |
990 |  |
         /**
991 |  |
          * Reads a list of objects from the database using the given
992 |  |
          * <code>Statement</code> instance, the given SQL string and the object
993 |  |
          * mapping stored or generated by the given object mapping key. The objects
994 |  |
          * will appear in the list in the same order their coresponding records
995 |  |
          * appear in the <code>ResultSet</code> generated by the
996 |  |
          * <code>Statement</code>'s execution of the SQL string.
997 |  |
          *
998 |  |
          * <br/><br/>Use this method if you need to use a special/customized
999 |  |
          * <code>Statement</code> instance. If you don't need a special/customized
1000 |  |
          * <code>Statement</code> instance, the other <code>read</code> methods
1001 |  |
          * will be easier to use.
1002 |  |
          *
1003 |  |
          * No database connections will be opened. The objects will be read from the
1004 |  |
          * provided <code>Statement</code>. You must remember to close the
1005 |  |
          * <code>Statement</code> after your are dont with it.
1006 |  |
          *
1007 |  |
          *
1008 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
1009 |  |
          * key, a new object mapping will be attempted generated and stored by that
1010 |  |
          * object mapping key. An object mapping can only be generated automatically
1011 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
1012 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
1013 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
1014 |  |
          * setObjectClass(Class theClass) method). The <code>Class</code> instance
1015 |  |
          * should be the class of the object to be stored, meaning if you want to
1016 |  |
          * store an object of class <code>Employee</code> the <code>Class</code>
1017 |  |
          * instance should be that found at <code>Employee.class</code>.
1018 |  |
          *
1019 |  |
          * @param objectMappingKey
1020 |  |
          *            The object mapping key by which the object mapping to be used
1021 |  |
          *            is stored in the object mapping cache, in the persistence
1022 |  |
          *            configuration used by this instance of the DAO class.
1023 |  |
          * @param statement
1024 |  |
          *            The <code>Statement</code> instance to be used to execute
1025 |  |
          *            the SQL string.
1026 |  |
          * @param sql
1027 |  |
          *            The SQL string to be executed by the <code>Statement</code>
1028 |  |
          *            instance.
1029 |  |
          * @return A <code>List</code> of objects read from the database.
1030 |  |
          * @throws PersistenceException
1031 |  |
          *             If anything goes wrong during the read, if no persistence
1032 |  |
          *             configuration is set, if the persistence configuration
1033 |  |
          *             contains no object reader, or if no object mapping could be
1034 |  |
          *             found nor generated from the given object mapping key.
1035 |  |
          * @throws DAOException
1036 |  |
          */
1037 |  |
         List readList(Object objectMappingKey, Statement statement, String sql)
1038 |  |
                 throws PersistenceException, DAOException;
1039 |  |
1040 |  |
         /**
1041 |  |
          * Reads a list of objects from the database using the given
1042 |  |
          * <code>Statement</code> instance, the given SQL string and the object
1043 |  |
          * mapping stored or generated by the given object mapping key. The objects
1044 |  |
          * will appear in the list in the same order their coresponding records
1045 |  |
          * appear in the <code>ResultSet</code> generated by the
1046 |  |
          * <code>Statement</code>'s execution of the SQL string.
1047 |  |
          *
1048 |  |
          * <br/><br/>Use this method if you need to use a special/customized
1049 |  |
          * <code>Statement</code> instance. If you don't need a special/customized
1050 |  |
          * <code>Statement</code> instance, the other <code>read</code> methods
1051 |  |
          * will be easier to use.
1052 |  |
          *
1053 |  |
          * No database connections will be opened. The objects will be read from the
1054 |  |
          * provided <code>Statement</code>. You must remember to close the
1055 |  |
          * <code>Statement</code> after your are dont with it.
1056 |  |
          *
1057 |  |
          *
1058 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
1059 |  |
          * key, a new object mapping will be attempted generated and stored by that
1060 |  |
          * object mapping key. An object mapping can only be generated automatically
1061 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
1062 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
1063 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
1064 |  |
          * setObjectClass(Class theClass) method). The <code>Class</code> instance
1065 |  |
          * should be the class of the object to be stored, meaning if you want to
1066 |  |
          * store an object of class <code>Employee</code> the <code>Class</code>
1067 |  |
          * instance should be that found at <code>Employee.class</code>.
1068 |  |
          *
1069 |  |
          * @param conn
1070 |  |
          *            JDBC Connection.
1071 |  |
          * @param objectMappingKey
1072 |  |
          *            The object mapping key by which the object mapping to be used
1073 |  |
          *            is stored in the object mapping cache, in the persistence
1074 |  |
          *            configuration used by this instance of the DAO class.
1075 |  |
          * @param statement
1076 |  |
          *            The <code>Statement</code> instance to be used to execute
1077 |  |
          *            the SQL string.
1078 |  |
          * @param sql
1079 |  |
          *            The SQL string to be executed by the <code>Statement</code>
1080 |  |
          *            instance.
1081 |  |
          * @return A <code>List</code> of objects read from the database.
1082 |  |
          * @throws PersistenceException
1083 |  |
          *             If anything goes wrong during the read, if no persistence
1084 |  |
          *             configuration is set, if the persistence configuration
1085 |  |
          *             contains no object reader, or if no object mapping could be
1086 |  |
          *             found nor generated from the given object mapping key.
1087 |  |
          * @throws DAOException
1088 |  |
          */
1089 |  |
         List readList(Connection conn, Object objectMappingKey,
1090 |  |
                 Statement statement, String sql) throws PersistenceException,
1091 |  |
                 DAOException;
1092 |  |
1093 |  |
         /**
1094 |  |
          * Reads a list of objects using the object mapping stored or generated by
1095 |  |
          * the given object mapping key and <code>PreparedStatement</code>
1096 |  |
          * instance. The <code>PreparedStatement</code> instance must have all
1097 |  |
          * parameters set before calling this method (using the
1098 |  |
          * PreparedStatement.setXXX(index, value) methods). The objects will appear
1099 |  |
          * in the list in the same order their coresponding records appear in the
1100 |  |
          * <code>ResultSet</code> generated by the <code>PreparedStatement</code>
1101 |  |
          * instance.
1102 |  |
          *
1103 |  |
          * <br/><br/>No database connection will be opened. The object will be read
1104 |  |
          * using the <code>PreparedStatement</code> passed as parameter. You must
1105 |  |
          * remember to close the <code>PreparedStatement</code> yourself when you
1106 |  |
          * are done with it.
1107 |  |
          *
1108 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
1109 |  |
          * key, a new object mapping will be attempted generated and stored by that
1110 |  |
          * object mapping key. An object mapping can only be generated automatically
1111 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
1112 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
1113 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
1114 |  |
          * setObjectClass(Class theClass) method).
1115 |  |
          *
1116 |  |
          * The <code>Class</code> instance should be the class of the objects to
1117 |  |
          * be read, meaning if you want to read objects of class <code>Employee
1118 |  |
          * </code> the <code>Class</code> instance should be that found at <code>
1119 |  |
          * Employee.class</code>.
1120 |  |
          *
1121 |  |
          * @param objectMappingKey
1122 |  |
          *            The object mapping key by which the object mapping to be used
1123 |  |
          *            is stored in the object mapping cache, in the persistence
1124 |  |
          *            configuration used by this instance of the DAO class.
1125 |  |
          * @param statement
1126 |  |
          *            The <code>PreparedStatement</code> instance locating the
1127 |  |
          *            list of objects to read.
1128 |  |
          * @return A <code>List</code> of objects read from the database.
1129 |  |
          * @throws PersistenceException
1130 |  |
          *             If anything goes wrong during the read, if no persistence
1131 |  |
          *             configuration is set, if the persistence configuration
1132 |  |
          *             contains no object reader, or if no object mapping could be
1133 |  |
          *             found nor generated from the given object mapping key.
1134 |  |
          * @throws DAOException
1135 |  |
          */
1136 |  |
         List readList(Object objectMappingKey, PreparedStatement statement)
1137 |  |
                 throws PersistenceException, DAOException;
1138 |  |
1139 |  |
         /**
1140 |  |
          * Reads a list of objects using the object mapping stored or generated by
1141 |  |
          * the given object mapping key and <code>PreparedStatement</code>
1142 |  |
          * instance. The <code>PreparedStatement</code> instance must have all
1143 |  |
          * parameters set before calling this method (using the
1144 |  |
          * PreparedStatement.setXXX(index, value) methods). The objects will appear
1145 |  |
          * in the list in the same order their coresponding records appear in the
1146 |  |
          * <code>ResultSet</code> generated by the <code>PreparedStatement</code>
1147 |  |
          * instance.
1148 |  |
          *
1149 |  |
          * <br/><br/>No database connection will be opened. The object will be read
1150 |  |
          * using the <code>PreparedStatement</code> passed as parameter. You must
1151 |  |
          * remember to close the <code>PreparedStatement</code> yourself when you
1152 |  |
          * are done with it.
1153 |  |
          *
1154 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
1155 |  |
          * key, a new object mapping will be attempted generated and stored by that
1156 |  |
          * object mapping key. An object mapping can only be generated automatically
1157 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
1158 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
1159 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
1160 |  |
          * setObjectClass(Class theClass) method).
1161 |  |
          *
1162 |  |
          * The <code>Class</code> instance should be the class of the objects to
1163 |  |
          * be read, meaning if you want to read objects of class <code>Employee
1164 |  |
          * </code> the <code>Class</code> instance should be that found at <code>
1165 |  |
          * Employee.class</code>.
1166 |  |
          *
1167 |  |
          * @param conn
1168 |  |
          *            JDBC Connection.
1169 |  |
          * @param objectMappingKey
1170 |  |
          *            The object mapping key by which the object mapping to be used
1171 |  |
          *            is stored in the object mapping cache, in the persistence
1172 |  |
          *            configuration used by this instance of the DAO class.
1173 |  |
          * @param statement
1174 |  |
          *            The <code>PreparedStatement</code> instance locating the
1175 |  |
          *            list of objects to read.
1176 |  |
          * @return A <code>List</code> of objects read from the database.
1177 |  |
          * @throws PersistenceException
1178 |  |
          *             If anything goes wrong during the read, if no persistence
1179 |  |
          *             configuration is set, if the persistence configuration
1180 |  |
          *             contains no object reader, or if no object mapping could be
1181 |  |
          *             found nor generated from the given object mapping key.
1182 |  |
          * @throws DAOException
1183 |  |
          */
1184 |  |
         List readList(Connection conn, Object objectMappingKey,
1185 |  |
                 PreparedStatement statement) throws PersistenceException,
1186 |  |
                 DAOException;
1187 |  |
1188 |  |
         /**
1189 |  |
          * Reads a list of objects using the object mapping stored or generated by
1190 |  |
          * the given object mapping key, and a <code>PreparedStatement</code>
1191 |  |
          * instance created from the sql parameter, and the parameter collection. A
1192 |  |
          * <code>PreparedStatement</code> instance will be generated using the
1193 |  |
          * connection obtained by calling getConnection(), and calling it's
1194 |  |
          * prepareStatement(sql), where sql is the sql parameter passed in here as
1195 |  |
          * parameter. Hence the sql parameter must match the format used with
1196 |  |
          * prepared statements (? - mark for parameters)
1197 |  |
          *
1198 |  |
          * <br/><br/>The objects will appear in the list in the same order their
1199 |  |
          * coresponding records appear in the <code>ResultSet</code> generated by
1200 |  |
          * the <code>PreparedStatement</code> instance.
1201 |  |
          *
1202 |  |
          * <br/><br/>A connection to the database will be obtained from the
1203 |  |
          * getConnection() method of this instance.
1204 |  |
          *
1205 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
1206 |  |
          * key, a new object mapping will be attempted generated and stored by that
1207 |  |
          * object mapping key. An object mapping can only be generated automatically
1208 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
1209 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
1210 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
1211 |  |
          * setObjectClass(Class theClass) method).
1212 |  |
          *
1213 |  |
          * The <code>Class</code> instance should be the class of the objects to
1214 |  |
          * be read, meaning if you want to read objects of class <code>Employee
1215 |  |
          * </code> the <code>Class</code> instance should be that found at <code>
1216 |  |
          * Employee.class</code>.
1217 |  |
          *
1218 |  |
          * @param objectMappingKey
1219 |  |
          *            The object mapping key by which the object mapping to be used
1220 |  |
          *            is stored in the object mapping cache, in the persistence
1221 |  |
          *            configuration used by this instance of the DAO class.
1222 |  |
          * @param sql
1223 |  |
          *            The SQL string to use to prepare a <code>PreparedStatement
1224 |  |
          *            </code>.
1225 |  |
          * @param parameters
1226 |  |
          *            The parameters to insert into the <code>PreparedStatement
1227 |  |
          *            </code>.
1228 |  |
          * @return A <code>List</code> of objects read from the database.
1229 |  |
          * @throws PersistenceException
1230 |  |
          *             If anything goes wrong during the read, if no persistence
1231 |  |
          *             configuration is set, if the persistence configuration
1232 |  |
          *             contains no object reader, or if no object mapping could be
1233 |  |
          *             found nor generated from the given object mapping key.
1234 |  |
          * @throws DAOException
1235 |  |
          */
1236 |  |
         List readList(Object objectMappingKey, String sql, Collection parameters)
1237 |  |
                 throws PersistenceException, DAOException;
1238 |  |
1239 |  |
         /**
1240 |  |
          * Reads a list of objects using the object mapping stored or generated by
1241 |  |
          * the given object mapping key, and a <code>PreparedStatement</code>
1242 |  |
          * instance created from the sql parameter, and the parameter collection. A
1243 |  |
          * <code>PreparedStatement</code> instance will be generated using the
1244 |  |
          * connection obtained by calling getConnection(), and calling it's
1245 |  |
          * prepareStatement(sql), where sql is the sql parameter passed in here as
1246 |  |
          * parameter. Hence the sql parameter must match the format used with
1247 |  |
          * prepared statements (? - mark for parameters)
1248 |  |
          *
1249 |  |
          * <br/><br/>The objects will appear in the list in the same order their
1250 |  |
          * coresponding records appear in the <code>ResultSet</code> generated by
1251 |  |
          * the <code>PreparedStatement</code> instance.
1252 |  |
          *
1253 |  |
          * <br/><br/>A connection to the database will be obtained from the
1254 |  |
          * getConnection() method of this instance.
1255 |  |
          *
1256 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
1257 |  |
          * key, a new object mapping will be attempted generated and stored by that
1258 |  |
          * object mapping key. An object mapping can only be generated automatically
1259 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
1260 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
1261 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
1262 |  |
          * setObjectClass(Class theClass) method).
1263 |  |
          *
1264 |  |
          * The <code>Class</code> instance should be the class of the objects to
1265 |  |
          * be read, meaning if you want to read objects of class <code>Employee
1266 |  |
          * </code> the <code>Class</code> instance should be that found at <code>
1267 |  |
          * Employee.class</code>.
1268 |  |
          *
1269 |  |
          * @param conn
1270 |  |
          *            JDBC Connection.
1271 |  |
          * @param objectMappingKey
1272 |  |
          *            The object mapping key by which the object mapping to be used
1273 |  |
          *            is stored in the object mapping cache, in the persistence
1274 |  |
          *            configuration used by this instance of the DAO class.
1275 |  |
          * @param sql
1276 |  |
          *            The SQL string to use to prepare a <code>PreparedStatement
1277 |  |
          *            </code>.
1278 |  |
          * @param parameters
1279 |  |
          *            The parameters to insert into the <code>PreparedStatement
1280 |  |
          *            </code>.
1281 |  |
          * @return A <code>List</code> of objects read from the database.
1282 |  |
          * @throws PersistenceException
1283 |  |
          *             If anything goes wrong during the read, if no persistence
1284 |  |
          *             configuration is set, if the persistence configuration
1285 |  |
          *             contains no object reader, or if no object mapping could be
1286 |  |
          *             found nor generated from the given object mapping key.
1287 |  |
          * @throws DAOException
1288 |  |
          */
1289 |  |
         List readList(Connection conn, Object objectMappingKey, String sql,
1290 |  |
                 Collection parameters) throws PersistenceException, DAOException;
1291 |  |
1292 |  |
         /**
1293 |  |
          * Reads a list of objects using the object mapping stored or generated by
1294 |  |
          * the given object mapping key, and a <code>PreparedStatement</code>
1295 |  |
          * instance created from the sql parameter, and the parameter array. A
1296 |  |
          * <code>PreparedStatement</code> instance will be generated using the
1297 |  |
          * connection obtained by calling getConnection(), and calling it's
1298 |  |
          * prepareStatement(sql), where sql is the sql parameter passed in here as
1299 |  |
          * parameter. Hence the sql parameter must match the format used with
1300 |  |
          * prepared statements (? - mark for parameters)
1301 |  |
          *
1302 |  |
          * <br/><br/>The objects will appear in the list in the same order their
1303 |  |
          * coresponding records appear in the <code>ResultSet</code> generated by
1304 |  |
          * the <code>PreparedStatement</code> instance.
1305 |  |
          *
1306 |  |
          * <br/><br/>A connection to the database will be obtained from the
1307 |  |
          * getConnection() method of this instance.
1308 |  |
          *
1309 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
1310 |  |
          * key, a new object mapping will be attempted generated and stored by that
1311 |  |
          * object mapping key. An object mapping can only be generated automatically
1312 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
1313 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
1314 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
1315 |  |
          * setObjectClass(Class theClass) method).
1316 |  |
          *
1317 |  |
          * The <code>Class</code> instance should be the class of the objects to
1318 |  |
          * be read, meaning if you want to read objects of class <code>Employee
1319 |  |
          * </code> the <code>Class</code> instance should be that found at <code>
1320 |  |
          * Employee.class</code>.
1321 |  |
          *
1322 |  |
          * @param objectMappingKey
1323 |  |
          *            The object mapping key by which the object mapping to be used
1324 |  |
          *            is stored in the object mapping cache, in the persistence
1325 |  |
          *            configuration used by this instance of the DAO class.
1326 |  |
          * @param sql
1327 |  |
          *            The SQL string to use to prepare a <code>PreparedStatement
1328 |  |
          *            </code>.
1329 |  |
          * @param parameters
1330 |  |
          *            The parameters to insert into the <code>PreparedStatement
1331 |  |
          *            </code>.
1332 |  |
          * @return A <code>List</code> of objects read from the database.
1333 |  |
          * @throws PersistenceException
1334 |  |
          *             If anything goes wrong during the read, if no persistence
1335 |  |
          *             configuration is set, if the persistence configuration
1336 |  |
          *             contains no object reader, or if no object mapping could be
1337 |  |
          *             found nor generated from the given object mapping key.
1338 |  |
          * @throws DAOException
1339 |  |
          */
1340 |  |
         List readList(Object objectMappingKey, String sql, Object[] parameters)
1341 |  |
                 throws PersistenceException, DAOException;
1342 |  |
1343 |  |
         /**
1344 |  |
          * Reads a list of objects using the object mapping stored or generated by
1345 |  |
          * the given object mapping key, and a <code>PreparedStatement</code>
1346 |  |
          * instance created from the sql parameter, and the parameter array. A
1347 |  |
          * <code>PreparedStatement</code> instance will be generated using the
1348 |  |
          * connection obtained by calling getConnection(), and calling it's
1349 |  |
          * prepareStatement(sql), where sql is the sql parameter passed in here as
1350 |  |
          * parameter. Hence the sql parameter must match the format used with
1351 |  |
          * prepared statements (? - mark for parameters)
1352 |  |
          *
1353 |  |
          * <br/><br/>The objects will appear in the list in the same order their
1354 |  |
          * coresponding records appear in the <code>ResultSet</code> generated by
1355 |  |
          * the <code>PreparedStatement</code> instance.
1356 |  |
          *
1357 |  |
          * <br/><br/>A connection to the database will be obtained from the
1358 |  |
          * getConnection() method of this instance.
1359 |  |
          *
1360 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
1361 |  |
          * key, a new object mapping will be attempted generated and stored by that
1362 |  |
          * object mapping key. An object mapping can only be generated automatically
1363 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
1364 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
1365 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
1366 |  |
          * setObjectClass(Class theClass) method).
1367 |  |
          *
1368 |  |
          * The <code>Class</code> instance should be the class of the objects to
1369 |  |
          * be read, meaning if you want to read objects of class <code>Employee
1370 |  |
          * </code> the <code>Class</code> instance should be that found at <code>
1371 |  |
          * Employee.class</code>.
1372 |  |
          *
1373 |  |
          * @param conn
1374 |  |
          *            JDBC Connection.
1375 |  |
          * @param objectMappingKey
1376 |  |
          *            The object mapping key by which the object mapping to be used
1377 |  |
          *            is stored in the object mapping cache, in the persistence
1378 |  |
          *            configuration used by this instance of the DAO class.
1379 |  |
          * @param sql
1380 |  |
          *            The SQL string to use to prepare a <code>PreparedStatement
1381 |  |
          *            </code>.
1382 |  |
          * @param parameters
1383 |  |
          *            The parameters to insert into the <code>PreparedStatement
1384 |  |
          *            </code>.
1385 |  |
          * @return A <code>List</code> of objects read from the database.
1386 |  |
          * @throws PersistenceException
1387 |  |
          *             If anything goes wrong during the read, if no persistence
1388 |  |
          *             configuration is set, if the persistence configuration
1389 |  |
          *             contains no object reader, or if no object mapping could be
1390 |  |
          *             found nor generated from the given object mapping key.
1391 |  |
          * @throws DAOException
1392 |  |
          */
1393 |  |
         List readList(Connection conn, Object objectMappingKey, String sql,
1394 |  |
                 Object[] parameters) throws PersistenceException, DAOException;
1395 |  |
1396 |  |
         /**
1397 |  |
          * Reads a list of objects from the database using the object mapping stored
1398 |  |
          * or generated by the given object mapping key, and the given SQL string.
1399 |  |
          * The objects will appear in the list in the same order their coresponding
1400 |  |
          * records appear in the <code>ResultSet</code> generated by the SQL
1401 |  |
          * string.
1402 |  |
          *
1403 |  |
          * <br/><br/>The filter passed as parameter can include or exclude the
1404 |  |
          * records as they are iterated. If a filter excludes a record it will not
1405 |  |
          * be included in the list of objects read. A filter can also end the
1406 |  |
          * reading by signalling that it will not accept anymore records. No more
1407 |  |
          * records will then be iterated, and the objects read so far will be
1408 |  |
          * returned. If null is passed in the filter parameter no filtering will
1409 |  |
          * occur, and all records located by the SQL string will be included in the
1410 |  |
          * returned list.
1411 |  |
          *
1412 |  |
          * <br/><br/>A connection to the database will be obtained from the
1413 |  |
          * getConnection() method of this instance.
1414 |  |
          *
1415 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
1416 |  |
          * key, a new object mapping will be attempted generated and stored by that
1417 |  |
          * object mapping key. An object mapping can only be generated automatically
1418 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
1419 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
1420 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
1421 |  |
          * setObjectClass(Class theClass) method).
1422 |  |
          *
1423 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
1424 |  |
          * objects to be read, meaning if you want to read objects of class <code>
1425 |  |
          * Employee</code> the <code>Class</code> instance should be that found
1426 |  |
          * at <code>Employee.class</code>.
1427 |  |
          *
1428 |  |
          * @param objectMappingKey
1429 |  |
          *            The object mapping key by which the object mapping to be used
1430 |  |
          *            is stored in the object mapping cache, in the persistence
1431 |  |
          *            configuration used by this instance of the DAO class.
1432 |  |
          * @param sql
1433 |  |
          *            The SQL string locating the records to read into objects.
1434 |  |
          * @param filter
1435 |  |
          *            A filter that can include or exclude individual records.
1436 |  |
          * @return A <code>List</code> of objects read from the database.
1437 |  |
          * @throws PersistenceException
1438 |  |
          *             If anything goes wrong during the read, if no persistence
1439 |  |
          *             configuration is set, if the persistence configuration
1440 |  |
          *             contains no object reader, or if no object mapping could be
1441 |  |
          *             found nor generated from the given object mapping key.
1442 |  |
          * @throws DAOException
1443 |  |
          */
1444 |  |
         List readList(Object objectMappingKey, String sql, IReadFilter filter)
1445 |  |
                 throws PersistenceException, DAOException;
1446 |  |
1447 |  |
         /**
1448 |  |
          * Reads a list of objects from the database using the object mapping stored
1449 |  |
          * or generated by the given object mapping key, and the given SQL string.
1450 |  |
          * The objects will appear in the list in the same order their coresponding
1451 |  |
          * records appear in the <code>ResultSet</code> generated by the SQL
1452 |  |
          * string.
1453 |  |
          *
1454 |  |
          * <br/><br/>The filter passed as parameter can include or exclude the
1455 |  |
          * records as they are iterated. If a filter excludes a record it will not
1456 |  |
          * be included in the list of objects read. A filter can also end the
1457 |  |
          * reading by signalling that it will not accept anymore records. No more
1458 |  |
          * records will then be iterated, and the objects read so far will be
1459 |  |
          * returned. If null is passed in the filter parameter no filtering will
1460 |  |
          * occur, and all records located by the SQL string will be included in the
1461 |  |
          * returned list.
1462 |  |
          *
1463 |  |
          * <br/><br/>A connection to the database will be obtained from the
1464 |  |
          * getConnection() method of this instance.
1465 |  |
          *
1466 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
1467 |  |
          * key, a new object mapping will be attempted generated and stored by that
1468 |  |
          * object mapping key. An object mapping can only be generated automatically
1469 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
1470 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
1471 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
1472 |  |
          * setObjectClass(Class theClass) method).
1473 |  |
          *
1474 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
1475 |  |
          * objects to be read, meaning if you want to read objects of class <code>
1476 |  |
          * Employee</code> the <code>Class</code> instance should be that found
1477 |  |
          * at <code>Employee.class</code>.
1478 |  |
          *
1479 |  |
          * @param conn
1480 |  |
          *            JDBC Connection.
1481 |  |
          * @param objectMappingKey
1482 |  |
          *            The object mapping key by which the object mapping to be used
1483 |  |
          *            is stored in the object mapping cache, in the persistence
1484 |  |
          *            configuration used by this instance of the DAO class.
1485 |  |
          * @param sql
1486 |  |
          *            The SQL string locating the records to read into objects.
1487 |  |
          * @param filter
1488 |  |
          *            A filter that can include or exclude individual records.
1489 |  |
          * @return A <code>List</code> of objects read from the database.
1490 |  |
          * @throws PersistenceException
1491 |  |
          *             If anything goes wrong during the read, if no persistence
1492 |  |
          *             configuration is set, if the persistence configuration
1493 |  |
          *             contains no object reader, or if no object mapping could be
1494 |  |
          *             found nor generated from the given object mapping key.
1495 |  |
          * @throws DAOException
1496 |  |
          */
1497 |  |
         List readList(Connection conn, Object objectMappingKey, String sql,
1498 |  |
                 IReadFilter filter) throws PersistenceException, DAOException;
1499 |  |
1500 |  |
         /**
1501 |  |
          * Reads a list of objects from the given <code>ResultSet</code> using the
1502 |  |
          * object mapping stored or generated by the given object mapping key. The
1503 |  |
          * objects will appear in the list in the same order their coresponding
1504 |  |
          * records appear in the <code>ResultSet</code>.
1505 |  |
          *
1506 |  |
          * <br/><br/>The filter passed as parameter can include or exclude the
1507 |  |
          * records as they are iterated. If a filter excludes a record it will not
1508 |  |
          * be included in the list of objects read. A filter can also end the
1509 |  |
          * reading by signalling that it will not accept anymore records. No more
1510 |  |
          * records will then be iterated, and the objects read so far will be
1511 |  |
          * returned. If null is passed in the filter parameter no filtering will
1512 |  |
          * occur, and all records in the <code>ResultSet</code> will be included
1513 |  |
          * in the returned list.
1514 |  |
          *
1515 |  |
          * <br/><br/>No database connection will be opened. The object will be read
1516 |  |
          * from the provided <code>ResultSet</code>. You must remember to close
1517 |  |
          * the <code>ResultSet</code> yourself when you are done with it.
1518 |  |
          *
1519 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
1520 |  |
          * key, a new object mapping will be attempted generated and stored by that
1521 |  |
          * object mapping key. An object mapping can only be generated automatically
1522 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
1523 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
1524 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
1525 |  |
          * setObjectClass(Class theClass) method).
1526 |  |
          *
1527 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
1528 |  |
          * objects to be read, meaning if you want to read objects of class <code>
1529 |  |
          * Employee</code> the <code>Class</code> instance should be that found
1530 |  |
          * at <code>Employee.class</code>.
1531 |  |
          *
1532 |  |
          * @param objectMappingKey
1533 |  |
          *            The object mapping key by which the object mapping to be used
1534 |  |
          *            is stored in the object mapping cache, in the persistence
1535 |  |
          *            configuration used by this instance of the DAO class.
1536 |  |
          * @param result
1537 |  |
          *            The <code>ResultSet</code> to read the list of objects from.
1538 |  |
          * @param filter
1539 |  |
          *            A filter that can include or exclude individual records.
1540 |  |
          * @return A <code>List</code> of objects read from the database.
1541 |  |
          * @throws PersistenceException
1542 |  |
          *             If anything goes wrong during the read, if no persistence
1543 |  |
          *             configuration is set, if the persistence configuration
1544 |  |
          *             contains no object reader, or if no object mapping could be
1545 |  |
          *             found nor generated from the given object mapping key.
1546 |  |
          * @throws DAOException
1547 |  |
          */
1548 |  |
         List readList(Object objectMappingKey, ResultSet result, IReadFilter filter)
1549 |  |
                 throws PersistenceException, DAOException;
1550 |  |
1551 |  |
         /**
1552 |  |
          * Reads a list of objects from the given <code>ResultSet</code> using the
1553 |  |
          * object mapping stored or generated by the given object mapping key. The
1554 |  |
          * objects will appear in the list in the same order their coresponding
1555 |  |
          * records appear in the <code>ResultSet</code>.
1556 |  |
          *
1557 |  |
          * <br/><br/>The filter passed as parameter can include or exclude the
1558 |  |
          * records as they are iterated. If a filter excludes a record it will not
1559 |  |
          * be included in the list of objects read. A filter can also end the
1560 |  |
          * reading by signalling that it will not accept anymore records. No more
1561 |  |
          * records will then be iterated, and the objects read so far will be
1562 |  |
          * returned. If null is passed in the filter parameter no filtering will
1563 |  |
          * occur, and all records in the <code>ResultSet</code> will be included
1564 |  |
          * in the returned list.
1565 |  |
          *
1566 |  |
          * <br/><br/>No database connection will be opened. The object will be read
1567 |  |
          * from the provided <code>ResultSet</code>. You must remember to close
1568 |  |
          * the <code>ResultSet</code> yourself when you are done with it.
1569 |  |
          *
1570 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
1571 |  |
          * key, a new object mapping will be attempted generated and stored by that
1572 |  |
          * object mapping key. An object mapping can only be generated automatically
1573 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
1574 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
1575 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
1576 |  |
          * setObjectClass(Class theClass) method).
1577 |  |
          *
1578 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
1579 |  |
          * objects to be read, meaning if you want to read objects of class <code>
1580 |  |
          * Employee</code> the <code>Class</code> instance should be that found
1581 |  |
          * at <code>Employee.class</code>.
1582 |  |
          *
1583 |  |
          * @param conn
1584 |  |
          *            JDBC Connection.
1585 |  |
          * @param objectMappingKey
1586 |  |
          *            The object mapping key by which the object mapping to be used
1587 |  |
          *            is stored in the object mapping cache, in the persistence
1588 |  |
          *            configuration used by this instance of the DAO class.
1589 |  |
          * @param result
1590 |  |
          *            The <code>ResultSet</code> to read the list of objects from.
1591 |  |
          * @param filter
1592 |  |
          *            A filter that can include or exclude individual records.
1593 |  |
          * @return A <code>List</code> of objects read from the database.
1594 |  |
          * @throws PersistenceException
1595 |  |
          *             If anything goes wrong during the read, if no persistence
1596 |  |
          *             configuration is set, if the persistence configuration
1597 |  |
          *             contains no object reader, or if no object mapping could be
1598 |  |
          *             found nor generated from the given object mapping key.
1599 |  |
          * @throws DAOException
1600 |  |
          */
1601 |  |
         List readList(Connection conn, Object objectMappingKey, ResultSet result,
1602 |  |
                 IReadFilter filter) throws PersistenceException, DAOException;
1603 |  |
1604 |  |
         /**
1605 |  |
          * Reads a list of objects from the database using the given
1606 |  |
          * <code>Statement</code> instance, the given SQL string and the object
1607 |  |
          * mapping stored or generated by the given object mapping key. The objects
1608 |  |
          * will appear in the list in the same order their coresponding records
1609 |  |
          * appear in the <code>ResultSet</code> generated by the
1610 |  |
          * <code>Statement</code>'s execution of the SQL string.
1611 |  |
          *
1612 |  |
          * <br/><br/>The filter passed as parameter can include or exclude the
1613 |  |
          * records as they are iterated. If a filter excludes a record it will not
1614 |  |
          * be included in the list of objects read. A filter can also end the
1615 |  |
          * reading by signalling that it will not accept anymore records. No more
1616 |  |
          * records will then be iterated, and the objects read so far will be
1617 |  |
          * returned. If null is passed in the filter parameter no filtering will
1618 |  |
          * occur, and all records in the <code>ResultSet</code> will be included
1619 |  |
          * in the returned list.
1620 |  |
          *
1621 |  |
          * <br/><br/>Use this method if you need to use a special/customized
1622 |  |
          * <code>Statement</code> instance. If you don't need a special/customized
1623 |  |
          * <code>Statement</code> instance, the other <code>read</code> methods
1624 |  |
          * will be easier to use.
1625 |  |
          *
1626 |  |
          * <br/><br/>No database connection will be opened. The object will be read
1627 |  |
          * from the provided <code>Statement</code>. You must remember to close
1628 |  |
          * the <code>Statement</code> yourself when you are done with it.
1629 |  |
          *
1630 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
1631 |  |
          * key, a new object mapping will be attempted generated and stored by that
1632 |  |
          * object mapping key. An object mapping can only be generated automatically
1633 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
1634 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
1635 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
1636 |  |
          * setObjectClass(Class theClass) method).
1637 |  |
          *
1638 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
1639 |  |
          * objects to be read, meaning if you want to read objects of class <code>
1640 |  |
          * Employee</code> the <code>Class</code> instance should be that found
1641 |  |
          * at <code>Employee.class</code>.
1642 |  |
          *
1643 |  |
          * @param objectMappingKey
1644 |  |
          *            The object mapping key by which the object mapping to be used
1645 |  |
          *            is stored in the object mapping cache, in the persistence
1646 |  |
          *            configuration used by this instance of the DAO class.
1647 |  |
          * @param statement
1648 |  |
          *            The <code>Statement</code> instance to be used to execute
1649 |  |
          *            the SQL string.
1650 |  |
          * @param sql
1651 |  |
          *            The SQL string to be executed by the <code>Statement</code>
1652 |  |
          *            instance.
1653 |  |
          * @param filter
1654 |  |
          *            A filter that can include or exclude individual records.
1655 |  |
          * @return A <code>List</code> of objects read from the database.
1656 |  |
          * @throws PersistenceException
1657 |  |
          *             If anything goes wrong during the read, if no persistence
1658 |  |
          *             configuration is set, if the persistence configuration
1659 |  |
          *             contains no object reader, or if no object mapping could be
1660 |  |
          *             found nor generated from the given object mapping key.
1661 |  |
          * @throws DAOException
1662 |  |
          */
1663 |  |
         List readList(Object objectMappingKey, Statement statement, String sql,
1664 |  |
                 IReadFilter filter) throws PersistenceException, DAOException;
1665 |  |
1666 |  |
         /**
1667 |  |
          * Reads a list of objects from the database using the given
1668 |  |
          * <code>Statement</code> instance, the given SQL string and the object
1669 |  |
          * mapping stored or generated by the given object mapping key. The objects
1670 |  |
          * will appear in the list in the same order their coresponding records
1671 |  |
          * appear in the <code>ResultSet</code> generated by the
1672 |  |
          * <code>Statement</code>'s execution of the SQL string.
1673 |  |
          *
1674 |  |
          * <br/><br/>The filter passed as parameter can include or exclude the
1675 |  |
          * records as they are iterated. If a filter excludes a record it will not
1676 |  |
          * be included in the list of objects read. A filter can also end the
1677 |  |
          * reading by signalling that it will not accept anymore records. No more
1678 |  |
          * records will then be iterated, and the objects read so far will be
1679 |  |
          * returned. If null is passed in the filter parameter no filtering will
1680 |  |
          * occur, and all records in the <code>ResultSet</code> will be included
1681 |  |
          * in the returned list.
1682 |  |
          *
1683 |  |
          * <br/><br/>Use this method if you need to use a special/customized
1684 |  |
          * <code>Statement</code> instance. If you don't need a special/customized
1685 |  |
          * <code>Statement</code> instance, the other <code>read</code> methods
1686 |  |
          * will be easier to use.
1687 |  |
          *
1688 |  |
          * <br/><br/>No database connection will be opened. The object will be read
1689 |  |
          * from the provided <code>Statement</code>. You must remember to close
1690 |  |
          * the <code>Statement</code> yourself when you are done with it.
1691 |  |
          *
1692 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
1693 |  |
          * key, a new object mapping will be attempted generated and stored by that
1694 |  |
          * object mapping key. An object mapping can only be generated automatically
1695 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
1696 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
1697 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
1698 |  |
          * setObjectClass(Class theClass) method).
1699 |  |
          *
1700 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
1701 |  |
          * objects to be read, meaning if you want to read objects of class <code>
1702 |  |
          * Employee</code> the <code>Class</code> instance should be that found
1703 |  |
          * at <code>Employee.class</code>.
1704 |  |
          *
1705 |  |
          * @param conn
1706 |  |
          *            JDBC Connection.
1707 |  |
          * @param objectMappingKey
1708 |  |
          *            The object mapping key by which the object mapping to be used
1709 |  |
          *            is stored in the object mapping cache, in the persistence
1710 |  |
          *            configuration used by this instance of the DAO class.
1711 |  |
          * @param statement
1712 |  |
          *            The <code>Statement</code> instance to be used to execute
1713 |  |
          *            the SQL string.
1714 |  |
          * @param sql
1715 |  |
          *            The SQL string to be executed by the <code>Statement</code>
1716 |  |
          *            instance.
1717 |  |
          * @param filter
1718 |  |
          *            A filter that can include or exclude individual records.
1719 |  |
          * @return A <code>List</code> of objects read from the database.
1720 |  |
          * @throws PersistenceException
1721 |  |
          *             If anything goes wrong during the read, if no persistence
1722 |  |
          *             configuration is set, if the persistence configuration
1723 |  |
          *             contains no object reader, or if no object mapping could be
1724 |  |
          *             found nor generated from the given object mapping key.
1725 |  |
          * @throws DAOException
1726 |  |
          */
1727 |  |
         List readList(Connection conn, Object objectMappingKey,
1728 |  |
                 Statement statement, String sql, IReadFilter filter)
1729 |  |
                 throws PersistenceException, DAOException;
1730 |  |
1731 |  |
         /**
1732 |  |
          * Reads a list of objects using the object mapping stored or generated by
1733 |  |
          * the given object mapping key and <code>PreparedStatement</code>
1734 |  |
          * instance. The <code>PreparedStatement</code> instance must have all
1735 |  |
          * parameters set before calling this method (using the
1736 |  |
          * PreparedStatement.setXXX(index, value) methods). The objects will appear
1737 |  |
          * in the list in the same order their coresponding records appear in the
1738 |  |
          * <code>ResultSet</code> generated by the <code>PreparedStatement</code>
1739 |  |
          * instance.
1740 |  |
          *
1741 |  |
          * <br/><br/>The filter passed as parameter can include or exclude the
1742 |  |
          * records as they are iterated. If a filter excludes a record it will not
1743 |  |
          * be included in the list of objects read. A filter can also end the
1744 |  |
          * reading by signalling that it will not accept anymore records. No more
1745 |  |
          * records will then be iterated, and the objects read so far will be
1746 |  |
          * returned. If null is passed in the filter parameter no filtering will
1747 |  |
          * occur, and all records in the <code>ResultSet</code> will be included
1748 |  |
          * in the returned list.
1749 |  |
          *
1750 |  |
          * <br/><br/>No database connection will be opened. The object will be read
1751 |  |
          * from the provided <code>PreparedStatement</code>. You must remember to
1752 |  |
          * close the <code>PreparedStatement</code> yourself when you are done
1753 |  |
          * with it.
1754 |  |
          *
1755 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
1756 |  |
          * key, a new object mapping will be attempted generated and stored by that
1757 |  |
          * object mapping key. An object mapping can only be generated automatically
1758 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
1759 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
1760 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
1761 |  |
          * setObjectClass(Class theClass) method).
1762 |  |
          *
1763 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
1764 |  |
          * object to be , meaning if you want to store an object of class <code>
1765 |  |
          * Employee</code> the <code>Class</code> instance should be that found
1766 |  |
          * at <code>Employee.class</code>.
1767 |  |
          *
1768 |  |
          * @param objectMappingKey
1769 |  |
          *            The object mapping key by which the object mapping to be used
1770 |  |
          *            is stored in the object mapping cache, in the persistence
1771 |  |
          *            configuration used by this instance of the DAO class.
1772 |  |
          * @param statement
1773 |  |
          *            The <code>PreparedStatement</code> instance locating the
1774 |  |
          *            list of objects to read.
1775 |  |
          * @param filter
1776 |  |
          *            A filter that can include or exclude individual records.
1777 |  |
          * @return A <code>List</code> of objects read from the database.
1778 |  |
          * @throws PersistenceException
1779 |  |
          *             If anything goes wrong during the read, if no persistence
1780 |  |
          *             configuration is set, if the persistence configuration
1781 |  |
          *             contains no object reader, or if no object mapping could be
1782 |  |
          *             found nor generated from the given object mapping key.
1783 |  |
          * @throws DAOException
1784 |  |
          */
1785 |  |
         List readList(Object objectMappingKey, PreparedStatement statement,
1786 |  |
                 IReadFilter filter) throws PersistenceException, DAOException;
1787 |  |
1788 |  |
         /**
1789 |  |
          * Reads a list of objects using the object mapping stored or generated by
1790 |  |
          * the given object mapping key and <code>PreparedStatement</code>
1791 |  |
          * instance. The <code>PreparedStatement</code> instance must have all
1792 |  |
          * parameters set before calling this method (using the
1793 |  |
          * PreparedStatement.setXXX(index, value) methods). The objects will appear
1794 |  |
          * in the list in the same order their coresponding records appear in the
1795 |  |
          * <code>ResultSet</code> generated by the <code>PreparedStatement</code>
1796 |  |
          * instance.
1797 |  |
          *
1798 |  |
          * <br/><br/>The filter passed as parameter can include or exclude the
1799 |  |
          * records as they are iterated. If a filter excludes a record it will not
1800 |  |
          * be included in the list of objects read. A filter can also end the
1801 |  |
          * reading by signalling that it will not accept anymore records. No more
1802 |  |
          * records will then be iterated, and the objects read so far will be
1803 |  |
          * returned. If null is passed in the filter parameter no filtering will
1804 |  |
          * occur, and all records in the <code>ResultSet</code> will be included
1805 |  |
          * in the returned list.
1806 |  |
          *
1807 |  |
          * <br/><br/>No database connection will be opened. The object will be read
1808 |  |
          * from the provided <code>PreparedStatement</code>. You must remember to
1809 |  |
          * close the <code>PreparedStatement</code> yourself when you are done
1810 |  |
          * with it.
1811 |  |
          *
1812 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
1813 |  |
          * key, a new object mapping will be attempted generated and stored by that
1814 |  |
          * object mapping key. An object mapping can only be generated automatically
1815 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
1816 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
1817 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
1818 |  |
          * setObjectClass(Class theClass) method).
1819 |  |
          *
1820 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
1821 |  |
          * object to be , meaning if you want to store an object of class <code>
1822 |  |
          * Employee</code> the <code>Class</code> instance should be that found
1823 |  |
          * at <code>Employee.class</code>.
1824 |  |
          *
1825 |  |
          * @param conn
1826 |  |
          *            JDBC Connection.
1827 |  |
          * @param objectMappingKey
1828 |  |
          *            The object mapping key by which the object mapping to be used
1829 |  |
          *            is stored in the object mapping cache, in the persistence
1830 |  |
          *            configuration used by this instance of the DAO class.
1831 |  |
          * @param statement
1832 |  |
          *            The <code>PreparedStatement</code> instance locating the
1833 |  |
          *            list of objects to read.
1834 |  |
          * @param filter
1835 |  |
          *            A filter that can include or exclude individual records.
1836 |  |
          * @return A <code>List</code> of objects read from the database.
1837 |  |
          * @throws PersistenceException
1838 |  |
          *             If anything goes wrong during the read, if no persistence
1839 |  |
          *             configuration is set, if the persistence configuration
1840 |  |
          *             contains no object reader, or if no object mapping could be
1841 |  |
          *             found nor generated from the given object mapping key.
1842 |  |
          * @throws DAOException
1843 |  |
          */
1844 |  |
         List readList(Connection conn, Object objectMappingKey,
1845 |  |
                 PreparedStatement statement, IReadFilter filter)
1846 |  |
                 throws PersistenceException, DAOException;
1847 |  |
1848 |  |
         /**
1849 |  |
          * Reads a list of objects using the object mapping stored or generated by
1850 |  |
          * the given object mapping key, and a <code>PreparedStatement</code>
1851 |  |
          * instance created from the sql parameter, and the parameter array. A
1852 |  |
          * <code>PreparedStatement</code> instance will be generated using the
1853 |  |
          * connection obtained by calling getConnection(), and calling it's
1854 |  |
          * prepareStatement(sql), where sql is the sql parameter passed in here as
1855 |  |
          * parameter. Hence the sql parameter must match the format used with
1856 |  |
          * prepared statements (? - mark for parameters)
1857 |  |
          *
1858 |  |
          * <br/><br/>The objects will appear in the list in the same order their
1859 |  |
          * coresponding records appear in the <code>ResultSet</code> generated by
1860 |  |
          * the <code>PreparedStatement</code> instance.
1861 |  |
          *
1862 |  |
          * <br/><br/>A connection to the database will be obtained from the
1863 |  |
          * getConnection() method of this instance.
1864 |  |
          *
1865 |  |
          * <br/><br/>The filter passed as parameter can include or exclude the
1866 |  |
          * records as they are iterated. If a filter excludes a record it will not
1867 |  |
          * be included in the list of objects read. A filter can also end the
1868 |  |
          * reading by signalling that it will not accept anymore records. No more
1869 |  |
          * records will then be iterated, and the objects read so far will be
1870 |  |
          * returned. If null is passed in the filter parameter no filtering will
1871 |  |
          * occur, and all records in the <code>ResultSet</code> will be included
1872 |  |
          * in the returned list.
1873 |  |
          *
1874 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
1875 |  |
          * key, a new object mapping will be attempted generated and stored by that
1876 |  |
          * object mapping key. An object mapping can only be generated automatically
1877 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
1878 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
1879 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
1880 |  |
          * setObjectClass(Class theClass) method).
1881 |  |
          *
1882 |  |
          * The <code>Class</code> instance should be the class of the objects to
1883 |  |
          * be read, meaning if you want to read objects of class <code>Employee
1884 |  |
          * </code> the <code>Class</code> instance should be that found at <code>
1885 |  |
          * Employee.class</code>.
1886 |  |
          *
1887 |  |
          *
1888 |  |
          * @param objectMappingKey
1889 |  |
          *            The object mapping key by which the object mapping to be used
1890 |  |
          *            is stored in the object mapping cache, in the persistence
1891 |  |
          *            configuration used by this instance of the DAO class.
1892 |  |
          * @param sql
1893 |  |
          *            The SQL string to use to prepare a <code>PreparedStatement
1894 |  |
          *            </code>.
1895 |  |
          * @param parameters
1896 |  |
          *            The parameters to insert into the <code>PreparedStatement
1897 |  |
          *            </code>.
1898 |  |
          * @param filter
1899 |  |
          *            A filter that can include or exclude individual records.
1900 |  |
          * @return A <code>List</code> of objects read from the database.
1901 |  |
          * @throws PersistenceException
1902 |  |
          *             If anything goes wrong during the read, if no persistence
1903 |  |
          *             configuration is set, if the persistence configuration
1904 |  |
          *             contains no object reader, or if no object mapping could be
1905 |  |
          *             found nor generated from the given object mapping key.
1906 |  |
          * @throws DAOException
1907 |  |
          */
1908 |  |
         List readList(Object objectMappingKey, String sql, Collection parameters,
1909 |  |
                 IReadFilter filter) throws PersistenceException, DAOException;
1910 |  |
1911 |  |
         /**
1912 |  |
          * Reads a list of objects using the object mapping stored or generated by
1913 |  |
          * the given object mapping key, and a <code>PreparedStatement</code>
1914 |  |
          * instance created from the sql parameter, and the parameter array. A
1915 |  |
          * <code>PreparedStatement</code> instance will be generated using the
1916 |  |
          * connection obtained by calling getConnection(), and calling it's
1917 |  |
          * prepareStatement(sql), where sql is the sql parameter passed in here as
1918 |  |
          * parameter. Hence the sql parameter must match the format used with
1919 |  |
          * prepared statements (? - mark for parameters)
1920 |  |
          *
1921 |  |
          * <br/><br/>The objects will appear in the list in the same order their
1922 |  |
          * coresponding records appear in the <code>ResultSet</code> generated by
1923 |  |
          * the <code>PreparedStatement</code> instance.
1924 |  |
          *
1925 |  |
          * <br/><br/>A connection to the database will be obtained from the
1926 |  |
          * getConnection() method of this instance.
1927 |  |
          *
1928 |  |
          * <br/><br/>The filter passed as parameter can include or exclude the
1929 |  |
          * records as they are iterated. If a filter excludes a record it will not
1930 |  |
          * be included in the list of objects read. A filter can also end the
1931 |  |
          * reading by signalling that it will not accept anymore records. No more
1932 |  |
          * records will then be iterated, and the objects read so far will be
1933 |  |
          * returned. If null is passed in the filter parameter no filtering will
1934 |  |
          * occur, and all records in the <code>ResultSet</code> will be included
1935 |  |
          * in the returned list.
1936 |  |
          *
1937 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
1938 |  |
          * key, a new object mapping will be attempted generated and stored by that
1939 |  |
          * object mapping key. An object mapping can only be generated automatically
1940 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
1941 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
1942 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
1943 |  |
          * setObjectClass(Class theClass) method).
1944 |  |
          *
1945 |  |
          * The <code>Class</code> instance should be the class of the objects to
1946 |  |
          * be read, meaning if you want to read objects of class <code>Employee
1947 |  |
          * </code> the <code>Class</code> instance should be that found at <code>
1948 |  |
          * Employee.class</code>.
1949 |  |
          *
1950 |  |
          * @param conn
1951 |  |
          *            JDBC Connection.
1952 |  |
          * @param objectMappingKey
1953 |  |
          *            The object mapping key by which the object mapping to be used
1954 |  |
          *            is stored in the object mapping cache, in the persistence
1955 |  |
          *            configuration used by this instance of the DAO class.
1956 |  |
          * @param sql
1957 |  |
          *            The SQL string to use to prepare a <code>PreparedStatement
1958 |  |
          *            </code>.
1959 |  |
          * @param parameters
1960 |  |
          *            The parameters to insert into the <code>PreparedStatement
1961 |  |
          *            </code>.
1962 |  |
          * @param filter
1963 |  |
          *            A filter that can include or exclude individual records.
1964 |  |
          * @return A <code>List</code> of objects read from the database.
1965 |  |
          * @throws PersistenceException
1966 |  |
          *             If anything goes wrong during the read, if no persistence
1967 |  |
          *             configuration is set, if the persistence configuration
1968 |  |
          *             contains no object reader, or if no object mapping could be
1969 |  |
          *             found nor generated from the given object mapping key.
1970 |  |
          * @throws DAOException
1971 |  |
          */
1972 |  |
         List readList(Connection conn, Object objectMappingKey, String sql,
1973 |  |
                 Collection parameters, IReadFilter filter)
1974 |  |
                 throws PersistenceException, DAOException;
1975 |  |
1976 |  |
         /**
1977 |  |
          * Reads a list of objects using the object mapping stored or generated by
1978 |  |
          * the given object mapping key, and a <code>PreparedStatement</code>
1979 |  |
          * instance created from the sql parameter, and the parameter array. A
1980 |  |
          * <code>PreparedStatement</code> instance will be generated using the
1981 |  |
          * connection obtained by calling getConnection(), and calling it's
1982 |  |
          * prepareStatement(sql), where sql is the sql parameter passed in here as
1983 |  |
          * parameter. Hence the sql parameter must match the format used with
1984 |  |
          * prepared statements (? - mark for parameters)
1985 |  |
          *
1986 |  |
          * <br/><br/>The objects will appear in the list in the same order their
1987 |  |
          * coresponding records appear in the <code>ResultSet</code> generated by
1988 |  |
          * the <code>PreparedStatement</code> instance.
1989 |  |
          *
1990 |  |
          * <br/><br/>A connection to the database will be obtained from the
1991 |  |
          * getConnection() method of this instance.
1992 |  |
          *
1993 |  |
          * <br/><br/>The filter passed as parameter can include or exclude the
1994 |  |
          * records as they are iterated. If a filter excludes a record it will not
1995 |  |
          * be included in the list of objects read. A filter can also end the
1996 |  |
          * reading by signalling that it will not accept anymore records. No more
1997 |  |
          * records will then be iterated, and the objects read so far will be
1998 |  |
          * returned. If null is passed in the filter parameter no filtering will
1999 |  |
          * occur, and all records in the <code>ResultSet</code> will be included
2000 |  |
          * in the returned list.
2001 |  |
          *
2002 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
2003 |  |
          * key, a new object mapping will be attempted generated and stored by that
2004 |  |
          * object mapping key. An object mapping can only be generated automatically
2005 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
2006 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
2007 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
2008 |  |
          * setObjectClass(Class theClass) method).
2009 |  |
          *
2010 |  |
          * The <code>Class</code> instance should be the class of the objects to
2011 |  |
          * be read, meaning if you want to read objects of class <code>Employee
2012 |  |
          * </code> the <code>Class</code> instance should be that found at <code>
2013 |  |
          * Employee.class</code>.
2014 |  |
          *
2015 |  |
          *
2016 |  |
          * @param objectMappingKey
2017 |  |
          *            The object mapping key by which the object mapping to be used
2018 |  |
          *            is stored in the object mapping cache, in the persistence
2019 |  |
          *            configuration used by this instance of the DAO class.
2020 |  |
          * @param sql
2021 |  |
          *            The SQL string to use to prepare a <code>PreparedStatement
2022 |  |
          *            </code>.
2023 |  |
          * @param parameters
2024 |  |
          *            The parameters to insert into the <code>PreparedStatement
2025 |  |
          *            </code>.
2026 |  |
          * @param filter
2027 |  |
          *            A filter that can include or exclude individual records.
2028 |  |
          * @return A <code>List</code> of objects read from the database.
2029 |  |
          * @throws PersistenceException
2030 |  |
          *             If anything goes wrong during the read, if no persistence
2031 |  |
          *             configuration is set, if the persistence configuration
2032 |  |
          *             contains no object reader, or if no object mapping could be
2033 |  |
          *             found nor generated from the given object mapping key.
2034 |  |
          * @throws DAOException
2035 |  |
          */
2036 |  |
         List readList(Object objectMappingKey, String sql, Object[] parameters,
2037 |  |
                 IReadFilter filter) throws PersistenceException, DAOException;
2038 |  |
2039 |  |
         /**
2040 |  |
          * Reads a list of objects using the object mapping stored or generated by
2041 |  |
          * the given object mapping key, and a <code>PreparedStatement</code>
2042 |  |
          * instance created from the sql parameter, and the parameter array. A
2043 |  |
          * <code>PreparedStatement</code> instance will be generated using the
2044 |  |
          * connection obtained by calling getConnection(), and calling it's
2045 |  |
          * prepareStatement(sql), where sql is the sql parameter passed in here as
2046 |  |
          * parameter. Hence the sql parameter must match the format used with
2047 |  |
          * prepared statements (? - mark for parameters)
2048 |  |
          *
2049 |  |
          * <br/><br/>The objects will appear in the list in the same order their
2050 |  |
          * coresponding records appear in the <code>ResultSet</code> generated by
2051 |  |
          * the <code>PreparedStatement</code> instance.
2052 |  |
          *
2053 |  |
          * <br/><br/>A connection to the database will be obtained from the
2054 |  |
          * getConnection() method of this instance.
2055 |  |
          *
2056 |  |
          * <br/><br/>The filter passed as parameter can include or exclude the
2057 |  |
          * records as they are iterated. If a filter excludes a record it will not
2058 |  |
          * be included in the list of objects read. A filter can also end the
2059 |  |
          * reading by signalling that it will not accept anymore records. No more
2060 |  |
          * records will then be iterated, and the objects read so far will be
2061 |  |
          * returned. If null is passed in the filter parameter no filtering will
2062 |  |
          * occur, and all records in the <code>ResultSet</code> will be included
2063 |  |
          * in the returned list.
2064 |  |
          *
2065 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
2066 |  |
          * key, a new object mapping will be attempted generated and stored by that
2067 |  |
          * object mapping key. An object mapping can only be generated automatically
2068 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
2069 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
2070 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
2071 |  |
          * setObjectClass(Class theClass) method).
2072 |  |
          *
2073 |  |
          * The <code>Class</code> instance should be the class of the objects to
2074 |  |
          * be read, meaning if you want to read objects of class <code>Employee
2075 |  |
          * </code> the <code>Class</code> instance should be that found at <code>
2076 |  |
          * Employee.class</code>.
2077 |  |
          *
2078 |  |
          * @param conn
2079 |  |
          *            JDBC Connection.
2080 |  |
          * @param objectMappingKey
2081 |  |
          *            The object mapping key by which the object mapping to be used
2082 |  |
          *            is stored in the object mapping cache, in the persistence
2083 |  |
          *            configuration used by this instance of the DAO class.
2084 |  |
          * @param sql
2085 |  |
          *            The SQL string to use to prepare a <code>PreparedStatement
2086 |  |
          *            </code>.
2087 |  |
          * @param parameters
2088 |  |
          *            The parameters to insert into the <code>PreparedStatement
2089 |  |
          *            </code>.
2090 |  |
          * @param filter
2091 |  |
          *            A filter that can include or exclude individual records.
2092 |  |
          * @return A <code>List</code> of objects read from the database.
2093 |  |
          * @throws PersistenceException
2094 |  |
          *             If anything goes wrong during the read, if no persistence
2095 |  |
          *             configuration is set, if the persistence configuration
2096 |  |
          *             contains no object reader, or if no object mapping could be
2097 |  |
          *             found nor generated from the given object mapping key.
2098 |  |
          * @throws DAOException
2099 |  |
          */
2100 |  |
         List readList(Connection conn, Object objectMappingKey, String sql,
2101 |  |
                 Object[] parameters, IReadFilter filter)
2102 |  |
                 throws PersistenceException, DAOException;
2103 |  |
2104 |  |
         /**
2105 |  |
          * Same as <code>insert(Object objectMappingKey, Object object)</code>,
2106 |  |
          * but uses object.getClass() as the object mapping key.
2107 |  |
          *
2108 |  |
          * @param object
2109 |  |
          *            The object containing the values to be inserted into the new
2110 |  |
          *            record.
2111 |  |
          * @return The number of records affected by this insert action, as returned
2112 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
2113 |  |
          * @throws PersistenceException
2114 |  |
          *             If anything goes wrong during the insert, if no persistence
2115 |  |
          *             configuration is set, if the persistence configuration
2116 |  |
          *             contains no object writer, or if no object mapping could be
2117 |  |
          *             found nor generated from the given object mapping key.
2118 |  |
          */
2119 |  |
         int insert(Object object) throws PersistenceException, DAOException;
2120 |  |
2121 |  |
         /**
2122 |  |
          * Same as <code>insert(Object objectMappingKey, Object object)</code>,
2123 |  |
          * but uses object.getClass() as the object mapping key.
2124 |  |
          *
2125 |  |
          * @param conn
2126 |  |
          *            JDBC Connection.
2127 |  |
          * @param object
2128 |  |
          *            The object containing the values to be inserted into the new
2129 |  |
          *            record.
2130 |  |
          * @return The number of records affected by this insert action, as returned
2131 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
2132 |  |
          * @throws PersistenceException
2133 |  |
          *             If anything goes wrong during the insert, if no persistence
2134 |  |
          *             configuration is set, if the persistence configuration
2135 |  |
          *             contains no object writer, or if no object mapping could be
2136 |  |
          *             found nor generated from the given object mapping key.
2137 |  |
          * @throws DAOException.
2138 |  |
          */
2139 |  |
         int insert(Connection conn, Object object) throws PersistenceException,
2140 |  |
                 DAOException;
2141 |  |
2142 |  |
         /**
2143 |  |
          * Inserts a record in the database with the values from the given object
2144 |  |
          * according to the object mapping stored or generated by the given object
2145 |  |
          * mapping key.
2146 |  |
          *
2147 |  |
          * <br/><br/>A connection to the database will be obtained from the
2148 |  |
          * getConnection() method of this instance.
2149 |  |
          *
2150 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
2151 |  |
          * key, a new object mapping will be attempted generated and stored by that
2152 |  |
          * object mapping key. An object mapping can only be generated automatically
2153 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
2154 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
2155 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
2156 |  |
          * setObjectClass(Class theClass) method).
2157 |  |
          *
2158 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
2159 |  |
          * object to be inserted, meaning if you want to insert an object of class
2160 |  |
          * <code>Employee</code> the <code>Class</code> instance should be that
2161 |  |
          * found at <code>Employee.class</code>.
2162 |  |
          *
2163 |  |
          * <br/><br/>The SQL needed to insert the record will be generated
2164 |  |
          * automatically based on the object mapping, and executed using a <code>
2165 |  |
          * PreparedStatement</code>. The SQL string contains "?" characters for
2166 |  |
          * the values will be cached for later use to avoid the SQL generation
2167 |  |
          * overhead.
2168 |  |
          *
2169 |  |
          * @param objectMappingKey
2170 |  |
          *            The object mapping key by which the object mapping to be used
2171 |  |
          *            is stored in the object mapping cache, in the persistence
2172 |  |
          *            configuration used by this instance of the DAO class.
2173 |  |
          * @param object
2174 |  |
          *            The object containing the values to be inserted into the new
2175 |  |
          *            record.
2176 |  |
          * @return The number of records affected by this insert action, as returned
2177 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
2178 |  |
          * @throws PersistenceException
2179 |  |
          *             If anything goes wrong during the insert, if no persistence
2180 |  |
          *             configuration is set, if the persistence configuration
2181 |  |
          *             contains no object writer, or if no object mapping could be
2182 |  |
          *             found nor generated from the given object mapping key.
2183 |  |
          * @throws DAOException.
2184 |  |
          */
2185 |  |
         int insert(Object objectMappingKey, Object object)
2186 |  |
                 throws PersistenceException, DAOException;
2187 |  |
2188 |  |
         /**
2189 |  |
          * Inserts a record in the database with the values from the given object
2190 |  |
          * according to the object mapping stored or generated by the given object
2191 |  |
          * mapping key.
2192 |  |
          *
2193 |  |
          * <br/><br/>A connection to the database will be obtained from the
2194 |  |
          * getConnection() method of this instance.
2195 |  |
          *
2196 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
2197 |  |
          * key, a new object mapping will be attempted generated and stored by that
2198 |  |
          * object mapping key. An object mapping can only be generated automatically
2199 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
2200 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
2201 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
2202 |  |
          * setObjectClass(Class theClass) method).
2203 |  |
          *
2204 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
2205 |  |
          * object to be inserted, meaning if you want to insert an object of class
2206 |  |
          * <code>Employee</code> the <code>Class</code> instance should be that
2207 |  |
          * found at <code>Employee.class</code>.
2208 |  |
          *
2209 |  |
          * <br/><br/>The SQL needed to insert the record will be generated
2210 |  |
          * automatically based on the object mapping, and executed using a <code>
2211 |  |
          * PreparedStatement</code>. The SQL string contains "?" characters for
2212 |  |
          * the values will be cached for later use to avoid the SQL generation
2213 |  |
          * overhead.
2214 |  |
          *
2215 |  |
          * @param conn
2216 |  |
          *            JDBC Connection.
2217 |  |
          * @param objectMappingKey
2218 |  |
          *            The object mapping key by which the object mapping to be used
2219 |  |
          *            is stored in the object mapping cache, in the persistence
2220 |  |
          *            configuration used by this instance of the DAO class.
2221 |  |
          * @param object
2222 |  |
          *            The object containing the values to be inserted into the new
2223 |  |
          *            record.
2224 |  |
          * @return The number of records affected by this insert action, as returned
2225 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
2226 |  |
          * @throws PersistenceException
2227 |  |
          *             If anything goes wrong during the insert, if no persistence
2228 |  |
          *             configuration is set, if the persistence configuration
2229 |  |
          *             contains no object writer, or if no object mapping could be
2230 |  |
          *             found nor generated from the given object mapping key.
2231 |  |
          * @throws DAOException.
2232 |  |
          */
2233 |  |
         int insert(Connection conn, Object objectMappingKey, Object object)
2234 |  |
                 throws PersistenceException, DAOException;
2235 |  |
2236 |  |
         /**
2237 |  |
          * Same as
2238 |  |
          * <code>insertBatch(Object objectMappingKey, Collection objects)</code>
2239 |  |
          * but uses the class returned by the getClass() of the first element in the
2240 |  |
          * collection as the object mapping key. The first element is extracted
2241 |  |
          * using a standard Iterator.
2242 |  |
          *
2243 |  |
          * @param objects
2244 |  |
          *            The object containing the values to be inserted into the new
2245 |  |
          *            record.
2246 |  |
          * @return The number of records affected by this insert action, as returned
2247 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
2248 |  |
          * @throws PersistenceException
2249 |  |
          *             If anything goes wrong during the insert, if no persistence
2250 |  |
          *             configuration is set, if the persistence configuration
2251 |  |
          *             contains no object writer, or if no object mapping could be
2252 |  |
          *             found nor generated from the given object mapping key.
2253 |  |
          */
2254 |  |
         int[] insertBatch(Collection objects) throws PersistenceException,
2255 |  |
                 DAOException;
2256 |  |
2257 |  |
         /**
2258 |  |
          * Same as
2259 |  |
          * <code>insertBatch(Object objectMappingKey, Collection objects)</code>
2260 |  |
          * but uses the class returned by the getClass() of the first element in the
2261 |  |
          * collection as the object mapping key. The first element is extracted
2262 |  |
          * using a standard Iterator.
2263 |  |
          *
2264 |  |
          * @param objects
2265 |  |
          *            The object containing the values to be inserted into the new
2266 |  |
          *            record.
2267 |  |
          * @return The number of records affected by this insert action, as returned
2268 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
2269 |  |
          * @throws PersistenceException
2270 |  |
          *             If anything goes wrong during the insert, if no persistence
2271 |  |
          *             configuration is set, if the persistence configuration
2272 |  |
          *             contains no object writer, or if no object mapping could be
2273 |  |
          *             found nor generated from the given object mapping key.
2274 |  |
          */
2275 |  |
         int[] insertBatch(Connection conn, Collection objects)
2276 |  |
                 throws PersistenceException, DAOException;
2277 |  |
2278 |  |
         /**
2279 |  |
          * Inserts several records into the database with the values from the given
2280 |  |
          * objects according to the object mapping stored or generated by the given
2281 |  |
          * object mapping key.
2282 |  |
          *
2283 |  |
          * <br/><br/>A connection to the database will be obtained from the
2284 |  |
          * getConnection() method of this instance.
2285 |  |
          *
2286 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
2287 |  |
          * key, a new object mapping will be attempted generated and stored by that
2288 |  |
          * object mapping key. An object mapping can only be generated automatically
2289 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
2290 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
2291 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
2292 |  |
          * setObjectClass(Class theClass) method).
2293 |  |
          *
2294 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
2295 |  |
          * objects to be inserted, meaning if you want to insert objects of class
2296 |  |
          * <code>Employee</code> the <code>Class</code> instance should be that
2297 |  |
          * found at <code>Employee.class</code>.
2298 |  |
          *
2299 |  |
          * <br/><br/>The SQL needed to insert the record will be generated
2300 |  |
          * automatically based on the object mapping, and executed using a <code>
2301 |  |
          * PreparedStatement</code>. The SQL string contains "?" characters for
2302 |  |
          * the values will be cached for later use to avoid the SQL generation
2303 |  |
          * overhead.
2304 |  |
          *
2305 |  |
          * @param objectMappingKey
2306 |  |
          *            The object mapping key by which the object mapping to be used
2307 |  |
          *            is stored in the object mapping cache, in the persistence
2308 |  |
          *            configuration used by this instance of the DAO class.
2309 |  |
          * @param objects
2310 |  |
          *            The object containing the values to be inserted into the new
2311 |  |
          *            record.
2312 |  |
          * @return The number of records affected by this insert action, as returned
2313 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
2314 |  |
          * @throws PersistenceException
2315 |  |
          *             If anything goes wrong during the insert, if no persistence
2316 |  |
          *             configuration is set, if the persistence configuration
2317 |  |
          *             contains no object writer, or if no object mapping could be
2318 |  |
          *             found nor generated from the given object mapping key.
2319 |  |
          */
2320 |  |
         int[] insertBatch(Object objectMappingKey, Collection objects)
2321 |  |
                 throws PersistenceException;
2322 |  |
2323 |  |
         /**
2324 |  |
          * Same as <code>update(Object objectMappingKey, Object object)</code> but
2325 |  |
          * uses the object.getClass() as the object mapping key.
2326 |  |
          *
2327 |  |
          * @param object
2328 |  |
          *            The object containing the values to be update in the
2329 |  |
          *            coresponding record.
2330 |  |
          * @return The number of records affected by this update action, as returned
2331 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
2332 |  |
          * @throws PersistenceException
2333 |  |
          *             If anything goes wrong during the update, if no persistence
2334 |  |
          *             configuration is set, if the persistence configuration
2335 |  |
          *             contains no object writer, or if no object mapping could be
2336 |  |
          *             found nor generated from the given object mapping key.
2337 |  |
          * @throws DAOException
2338 |  |
          */
2339 |  |
         int update(Object object) throws PersistenceException, DAOException;
2340 |  |
2341 |  |
         /**
2342 |  |
          * Same as <code>update(Object objectMappingKey, Object object)</code> but
2343 |  |
          * uses the object.getClass() as the object mapping key.
2344 |  |
          *
2345 |  |
          * @param conn
2346 |  |
          *            JDBC Connection.
2347 |  |
          * @param object
2348 |  |
          *            The object containing the values to be update in the
2349 |  |
          *            coresponding record.
2350 |  |
          * @return The number of records affected by this update action, as returned
2351 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
2352 |  |
          * @throws PersistenceException
2353 |  |
          *             If anything goes wrong during the update, if no persistence
2354 |  |
          *             configuration is set, if the persistence configuration
2355 |  |
          *             contains no object writer, or if no object mapping could be
2356 |  |
          *             found nor generated from the given object mapping key.
2357 |  |
          * @throws DAOException
2358 |  |
          */
2359 |  |
         int update(Connection conn, Object object) throws PersistenceException,
2360 |  |
                 DAOException;
2361 |  |
2362 |  |
         /**
2363 |  |
          * Updates the record in the database coresponding to the given object, with
2364 |  |
          * the values contained in this object, according to the object mapping
2365 |  |
          * stored or generated by the given object mapping key.
2366 |  |
          *
2367 |  |
          * <br/><br/>Do not use this method if the primary key value is also
2368 |  |
          * changed during the update, or this method will have no effect. If you do
2369 |  |
          * use it for an update where the primary key has changed, the primary key
2370 |  |
          * value in the "where" clause of the SQL will contain the new primary key
2371 |  |
          * value. Since no records, or perhaps another existing record, matches the
2372 |  |
          * new, changed, primary key value, the update will have no effect. If you
2373 |  |
          * need to update a record including it's primary key, use the other update
2374 |  |
          * method.
2375 |  |
          *
2376 |  |
          * <br/><br/>A connection to the database will be obtained from the
2377 |  |
          * getConnection() method of this instance.
2378 |  |
          *
2379 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
2380 |  |
          * key, a new object mapping will be attempted generated and stored by that
2381 |  |
          * object mapping key. An object mapping can only be generated automatically
2382 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
2383 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
2384 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
2385 |  |
          * setObjectClass(Class theClass) method).
2386 |  |
          *
2387 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
2388 |  |
          * object to be updated, meaning if you want to update an object of class
2389 |  |
          * <code>Employee</code> the <code>Class</code> instance should be that
2390 |  |
          * found at <code>Employee.class</code>.
2391 |  |
          *
2392 |  |
          * <br/><br/>The SQL needed to update the record will be generated
2393 |  |
          * automatically based on the object mapping, and executed using a <code>
2394 |  |
          * PreparedStatement</code>. The SQL string contains "?" characters for
2395 |  |
          * the values will be cached for later use to avoid the SQL generation
2396 |  |
          * overhead.
2397 |  |
          *
2398 |  |
          * @param objectMappingKey
2399 |  |
          *            The object mapping key by which the object mapping to be used
2400 |  |
          *            is stored in the object mapping cache, in the persistence
2401 |  |
          *            configuration used by this instance of the DAO class.
2402 |  |
          * @param object
2403 |  |
          *            The object containing the values to be update in the
2404 |  |
          *            coresponding record.
2405 |  |
          * @return The number of records affected by this update action, as returned
2406 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
2407 |  |
          * @throws PersistenceException
2408 |  |
          *             If anything goes wrong during the update, if no persistence
2409 |  |
          *             configuration is set, if the persistence configuration
2410 |  |
          *             contains no object writer, or if no object mapping could be
2411 |  |
          *             found nor generated from the given object mapping key.
2412 |  |
          * @throws DAOException
2413 |  |
          */
2414 |  |
         int update(Object objectMappingKey, Object object)
2415 |  |
                 throws PersistenceException, DAOException;
2416 |  |
2417 |  |
         /**
2418 |  |
          * Updates the record in the database coresponding to the given object, with
2419 |  |
          * the values contained in this object, according to the object mapping
2420 |  |
          * stored or generated by the given object mapping key.
2421 |  |
          *
2422 |  |
          * <br/><br/>Do not use this method if the primary key value is also
2423 |  |
          * changed during the update, or this method will have no effect. If you do
2424 |  |
          * use it for an update where the primary key has changed, the primary key
2425 |  |
          * value in the "where" clause of the SQL will contain the new primary key
2426 |  |
          * value. Since no records, or perhaps another existing record, matches the
2427 |  |
          * new, changed, primary key value, the update will have no effect. If you
2428 |  |
          * need to update a record including it's primary key, use the other update
2429 |  |
          * method.
2430 |  |
          *
2431 |  |
          * <br/><br/>A connection to the database will be obtained from the
2432 |  |
          * getConnection() method of this instance.
2433 |  |
          *
2434 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
2435 |  |
          * key, a new object mapping will be attempted generated and stored by that
2436 |  |
          * object mapping key. An object mapping can only be generated automatically
2437 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
2438 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
2439 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
2440 |  |
          * setObjectClass(Class theClass) method).
2441 |  |
          *
2442 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
2443 |  |
          * object to be updated, meaning if you want to update an object of class
2444 |  |
          * <code>Employee</code> the <code>Class</code> instance should be that
2445 |  |
          * found at <code>Employee.class</code>.
2446 |  |
          *
2447 |  |
          * <br/><br/>The SQL needed to update the record will be generated
2448 |  |
          * automatically based on the object mapping, and executed using a <code>
2449 |  |
          * PreparedStatement</code>. The SQL string contains "?" characters for
2450 |  |
          * the values will be cached for later use to avoid the SQL generation
2451 |  |
          * overhead.
2452 |  |
          *
2453 |  |
          * @param conn
2454 |  |
          *            JDBC Connection.
2455 |  |
          * @param objectMappingKey
2456 |  |
          *            The object mapping key by which the object mapping to be used
2457 |  |
          *            is stored in the object mapping cache, in the persistence
2458 |  |
          *            configuration used by this instance of the DAO class.
2459 |  |
          * @param object
2460 |  |
          *            The object containing the values to be update in the
2461 |  |
          *            coresponding record.
2462 |  |
          * @return The number of records affected by this update action, as returned
2463 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
2464 |  |
          * @throws PersistenceException
2465 |  |
          *             If anything goes wrong during the update, if no persistence
2466 |  |
          *             configuration is set, if the persistence configuration
2467 |  |
          *             contains no object writer, or if no object mapping could be
2468 |  |
          *             found nor generated from the given object mapping key.
2469 |  |
          * @throws DAOException
2470 |  |
          */
2471 |  |
         int update(Connection conn, Object objectMappingKey, Object object)
2472 |  |
                 throws PersistenceException, DAOException;
2473 |  |
2474 |  |
         /**
2475 |  |
          * Same as
2476 |  |
          * <code>updateByPrimaryKey(Object objectMappingKey, Object object, Object oldPrimaryKeyValue)</code>
2477 |  |
          * but uses the object.getClass() as the object mapping key.
2478 |  |
          *
2479 |  |
          * @param object
2480 |  |
          *            The object containing the values to be update in the
2481 |  |
          *            coresponding record.
2482 |  |
          * @param oldPrimaryKeyValue
2483 |  |
          *            The primary key value of the record to update, meaning the
2484 |  |
          *            value of the primary key before it was changed in the object
2485 |  |
          *            to update.
2486 |  |
          * @return The number of records affected by this update action, as returned
2487 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
2488 |  |
          * @throws PersistenceException
2489 |  |
          *             If anything goes wrong during the update, if no persistence
2490 |  |
          *             configuration is set, if the persistence configuration
2491 |  |
          *             contains no object writer, or if no object mapping could be
2492 |  |
          *             found nor generated from the given object mapping key.
2493 |  |
          * @throws DAOException
2494 |  |
          */
2495 |  |
         int updateByPrimaryKey(Object object, Object oldPrimaryKeyValue)
2496 |  |
                 throws PersistenceException, DAOException;
2497 |  |
2498 |  |
         /**
2499 |  |
          * Same as
2500 |  |
          * <code>updateByPrimaryKey(Object objectMappingKey, Object object, Object oldPrimaryKeyValue)</code>
2501 |  |
          * but uses the object.getClass() as the object mapping key.
2502 |  |
          *
2503 |  |
          * @param conn
2504 |  |
          *            JDBC Connection.
2505 |  |
          * @param object
2506 |  |
          *            The object containing the values to be update in the
2507 |  |
          *            coresponding record.
2508 |  |
          * @param oldPrimaryKeyValue
2509 |  |
          *            The primary key value of the record to update, meaning the
2510 |  |
          *            value of the primary key before it was changed in the object
2511 |  |
          *            to update.
2512 |  |
          * @return The number of records affected by this update action, as returned
2513 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
2514 |  |
          * @throws PersistenceException
2515 |  |
          *             If anything goes wrong during the update, if no persistence
2516 |  |
          *             configuration is set, if the persistence configuration
2517 |  |
          *             contains no object writer, or if no object mapping could be
2518 |  |
          *             found nor generated from the given object mapping key.
2519 |  |
          * @throws DAOException
2520 |  |
          */
2521 |  |
         int updateByPrimaryKey(Connection conn, Object object,
2522 |  |
                 Object oldPrimaryKeyValue) throws PersistenceException,
2523 |  |
                 DAOException;
2524 |  |
2525 |  |
         /**
2526 |  |
          * Updates the record in the database coresponding to the given object, with
2527 |  |
          * the values contained in this object, according to the object mapping
2528 |  |
          * stored or generated by the given object mapping key.
2529 |  |
          *
2530 |  |
          * <br/><br/>Use this method when updating records in which you also change
2531 |  |
          * the primary key value. This method inserts the old primary key value into
2532 |  |
          * the "where" clause of the PreparedStatement, so the correct record is
2533 |  |
          * updated.
2534 |  |
          *
2535 |  |
          * <br/><br/>A connection to the database will be obtained from the
2536 |  |
          * getConnection() method of this instance.
2537 |  |
          *
2538 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
2539 |  |
          * key, a new object mapping will be attempted generated and stored by that
2540 |  |
          * object mapping key. An object mapping can only be generated automatically
2541 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
2542 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
2543 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
2544 |  |
          * setObjectClass(Class theClass) method).
2545 |  |
          *
2546 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
2547 |  |
          * object to be updated, meaning if you want to update an object of class
2548 |  |
          * <code>Employee</code> the <code>Class</code> instance should be that
2549 |  |
          * found at <code>Employee.class</code>.
2550 |  |
          *
2551 |  |
          * <br/><br/>The SQL needed to update the record will be generated
2552 |  |
          * automatically based on the object mapping, and executed using a <code>
2553 |  |
          * PreparedStatement</code>. The SQL string contains "?" characters for
2554 |  |
          * the values will be cached for later use to avoid the SQL generation
2555 |  |
          * overhead.
2556 |  |
          *
2557 |  |
          * @param objectMappingKey
2558 |  |
          *            The object mapping key by which the object mapping to be used
2559 |  |
          *            is stored in the object mapping cache, in the persistence
2560 |  |
          *            configuration used by this instance of the DAO class.
2561 |  |
          * @param object
2562 |  |
          *            The object containing the values to be update in the
2563 |  |
          *            coresponding record.
2564 |  |
          * @param oldPrimaryKeyValue
2565 |  |
          *            The primary key value of the record to update, meaning the
2566 |  |
          *            value of the primary key before it was changed in the object
2567 |  |
          *            to update.
2568 |  |
          * @return The number of records affected by this update action, as returned
2569 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
2570 |  |
          * @throws PersistenceException
2571 |  |
          *             If anything goes wrong during the update, if no persistence
2572 |  |
          *             configuration is set, if the persistence configuration
2573 |  |
          *             contains no object writer, or if no object mapping could be
2574 |  |
          *             found nor generated from the given object mapping key.
2575 |  |
          * @throws DAOException
2576 |  |
          */
2577 |  |
         int updateByPrimaryKey(Object objectMappingKey, Object object,
2578 |  |
                 Object oldPrimaryKeyValue) throws PersistenceException,
2579 |  |
                 DAOException;
2580 |  |
2581 |  |
         /**
2582 |  |
          * Updates the record in the database coresponding to the given object, with
2583 |  |
          * the values contained in this object, according to the object mapping
2584 |  |
          * stored or generated by the given object mapping key.
2585 |  |
          *
2586 |  |
          * <br/><br/>Use this method when updating records in which you also change
2587 |  |
          * the primary key value. This method inserts the old primary key value into
2588 |  |
          * the "where" clause of the PreparedStatement, so the correct record is
2589 |  |
          * updated.
2590 |  |
          *
2591 |  |
          * <br/><br/>A connection to the database will be obtained from the
2592 |  |
          * getConnection() method of this instance.
2593 |  |
          *
2594 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
2595 |  |
          * key, a new object mapping will be attempted generated and stored by that
2596 |  |
          * object mapping key. An object mapping can only be generated automatically
2597 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
2598 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
2599 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
2600 |  |
          * setObjectClass(Class theClass) method).
2601 |  |
          *
2602 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
2603 |  |
          * object to be updated, meaning if you want to update an object of class
2604 |  |
          * <code>Employee</code> the <code>Class</code> instance should be that
2605 |  |
          * found at <code>Employee.class</code>.
2606 |  |
          *
2607 |  |
          * <br/><br/>The SQL needed to update the record will be generated
2608 |  |
          * automatically based on the object mapping, and executed using a <code>
2609 |  |
          * PreparedStatement</code>. The SQL string contains "?" characters for
2610 |  |
          * the values will be cached for later use to avoid the SQL generation
2611 |  |
          * overhead.
2612 |  |
          *
2613 |  |
          * @param conn
2614 |  |
          *            JDBC Connection.
2615 |  |
          * @param objectMappingKey
2616 |  |
          *            The object mapping key by which the object mapping to be used
2617 |  |
          *            is stored in the object mapping cache, in the persistence
2618 |  |
          *            configuration used by this instance of the DAO class.
2619 |  |
          * @param object
2620 |  |
          *            The object containing the values to be update in the
2621 |  |
          *            coresponding record.
2622 |  |
          * @param oldPrimaryKeyValue
2623 |  |
          *            The primary key value of the record to update, meaning the
2624 |  |
          *            value of the primary key before it was changed in the object
2625 |  |
          *            to update.
2626 |  |
          * @return The number of records affected by this update action, as returned
2627 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
2628 |  |
          * @throws PersistenceException
2629 |  |
          *             If anything goes wrong during the update, if no persistence
2630 |  |
          *             configuration is set, if the persistence configuration
2631 |  |
          *             contains no object writer, or if no object mapping could be
2632 |  |
          *             found nor generated from the given object mapping key.
2633 |  |
          * @throws DAOException
2634 |  |
          */
2635 |  |
         int updateByPrimaryKey(Connection conn, Object objectMappingKey,
2636 |  |
                 Object object, Object oldPrimaryKeyValue)
2637 |  |
                 throws PersistenceException, DAOException;
2638 |  |
2639 |  |
         /**
2640 |  |
          * Same as
2641 |  |
          * <code>updateBatch(Object objectMappingKey, Collection objects)</code>
2642 |  |
          * the class returned by the getClass() of the first element in the
2643 |  |
          * collection as the object mapping key.
2644 |  |
          *
2645 |  |
          * @param objects
2646 |  |
          *            The collection of objects containing the values for the
2647 |  |
          *            records to be updated.
2648 |  |
          * @return An array containing the number of records affected by each update
2649 |  |
          *         action, as returned by
2650 |  |
          *         <code>PreparedStatement.executeBatch()</code>.
2651 |  |
          * @throws PersistenceException
2652 |  |
          *             If anything goes wrong during the update, if no persistence
2653 |  |
          *             configuration is set, if the persistence configuration
2654 |  |
          *             contains no object writer, or if no object mapping could be
2655 |  |
          *             found nor generated from the given object mapping key.
2656 |  |
          * @throws DAOException
2657 |  |
          */
2658 |  |
         int[] updateBatch(Collection objects) throws PersistenceException,
2659 |  |
                 DAOException;
2660 |  |
2661 |  |
         /**
2662 |  |
          * Same as
2663 |  |
          * <code>updateBatch(Object objectMappingKey, Collection objects)</code>
2664 |  |
          * the class returned by the getClass() of the first element in the
2665 |  |
          * collection as the object mapping key.
2666 |  |
          *
2667 |  |
          * @param conn
2668 |  |
          *            JDBC Connection.
2669 |  |
          * @param objects
2670 |  |
          *            The collection of objects containing the values for the
2671 |  |
          *            records to be updated.
2672 |  |
          * @return An array containing the number of records affected by each update
2673 |  |
          *         action, as returned by
2674 |  |
          *         <code>PreparedStatement.executeBatch()</code>.
2675 |  |
          * @throws PersistenceException
2676 |  |
          *             If anything goes wrong during the update, if no persistence
2677 |  |
          *             configuration is set, if the persistence configuration
2678 |  |
          *             contains no object writer, or if no object mapping could be
2679 |  |
          *             found nor generated from the given object mapping key.
2680 |  |
          * @throws DAOException
2681 |  |
          */
2682 |  |
         int[] updateBatch(Connection conn, Collection objects)
2683 |  |
                 throws PersistenceException, DAOException;
2684 |  |
2685 |  |
         /**
2686 |  |
          * Updates the records in the database coresponding to the given collection
2687 |  |
          * of objects, with the values contained in these objects, according to the
2688 |  |
          * object mapping stored or generated by the given object mapping key. This
2689 |  |
          * method uses JDBC batch updates to do the job, meaning all SQL statements
2690 |  |
          * are batched and sent to the database in one go.
2691 |  |
          *
2692 |  |
          * <br/><br/>Do not use this method if the primary key values are also
2693 |  |
          * changed during the update, or this method will have no effect. If you do
2694 |  |
          * use it for updates where the primary key has changed, the primary key
2695 |  |
          * value in the "where" clause of the SQL will contain the new primary key
2696 |  |
          * value. Since no records, or perhaps another existing record, match the
2697 |  |
          * new, changed, primary key values, the update will have no effect. If you
2698 |  |
          * need to batch update records including their primary keys, use the other
2699 |  |
          * updateBatch method.
2700 |  |
          *
2701 |  |
          * <br/><br/>A connection to the database will be obtained from the
2702 |  |
          * getConnection() method of this instance.
2703 |  |
          *
2704 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
2705 |  |
          * key, a new object mapping will be attempted generated and stored by that
2706 |  |
          * object mapping key. An object mapping can only be generated automatically
2707 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
2708 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
2709 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
2710 |  |
          * setObjectClass(Class theClass) method).
2711 |  |
          *
2712 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
2713 |  |
          * objects to be updated, meaning if you want to update objects of class
2714 |  |
          * <code>Employee</code> the <code>Class</code> instance should be that
2715 |  |
          * found at <code>Employee.class</code>.
2716 |  |
          *
2717 |  |
          * <br/><br/>The SQL needed to update the record will be generated
2718 |  |
          * automatically based on the object mapping, and executed using a <code>
2719 |  |
          * PreparedStatement</code>. The SQL string contains "?" characters for
2720 |  |
          * the values will be cached for later use to avoid the SQL generation
2721 |  |
          * overhead.
2722 |  |
          *
2723 |  |
          * @param objectMappingKey
2724 |  |
          *            The object mapping key by which the object mapping to be used
2725 |  |
          *            is stored in the object mapping cache, in the persistence
2726 |  |
          *            configuration used by this instance of the DAO class.
2727 |  |
          * @param objects
2728 |  |
          *            The collection of objects containing the values for the
2729 |  |
          *            records to be updated.
2730 |  |
          * @return An array containing the number of records affected by each update
2731 |  |
          *         action, as returned by <code>PreparedStatement.executeBatch()
2732 |  |
          *         </code>.
2733 |  |
          * @throws PersistenceException
2734 |  |
          *             If anything goes wrong during the update, if no persistence
2735 |  |
          *             configuration is set, if the persistence configuration
2736 |  |
          *             contains no object writer, or if no object mapping could be
2737 |  |
          *             found nor generated from the given object mapping key.
2738 |  |
          * @throws DAOException
2739 |  |
          */
2740 |  |
         int[] updateBatch(Object objectMappingKey, Collection objects)
2741 |  |
                 throws PersistenceException, DAOException;
2742 |  |
2743 |  |
         /**
2744 |  |
          * Updates the records in the database coresponding to the given collection
2745 |  |
          * of objects, with the values contained in these objects, according to the
2746 |  |
          * object mapping stored or generated by the given object mapping key. This
2747 |  |
          * method uses JDBC batch updates to do the job, meaning all SQL statements
2748 |  |
          * are batched and sent to the database in one go.
2749 |  |
          *
2750 |  |
          * <br/><br/>Do not use this method if the primary key values are also
2751 |  |
          * changed during the update, or this method will have no effect. If you do
2752 |  |
          * use it for updates where the primary key has changed, the primary key
2753 |  |
          * value in the "where" clause of the SQL will contain the new primary key
2754 |  |
          * value. Since no records, or perhaps another existing record, match the
2755 |  |
          * new, changed, primary key values, the update will have no effect. If you
2756 |  |
          * need to batch update records including their primary keys, use the other
2757 |  |
          * updateBatch method.
2758 |  |
          *
2759 |  |
          * <br/><br/>A connection to the database will be obtained from the
2760 |  |
          * getConnection() method of this instance.
2761 |  |
          *
2762 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
2763 |  |
          * key, a new object mapping will be attempted generated and stored by that
2764 |  |
          * object mapping key. An object mapping can only be generated automatically
2765 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
2766 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
2767 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
2768 |  |
          * setObjectClass(Class theClass) method).
2769 |  |
          *
2770 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
2771 |  |
          * objects to be updated, meaning if you want to update objects of class
2772 |  |
          * <code>Employee</code> the <code>Class</code> instance should be that
2773 |  |
          * found at <code>Employee.class</code>.
2774 |  |
          *
2775 |  |
          * <br/><br/>The SQL needed to update the record will be generated
2776 |  |
          * automatically based on the object mapping, and executed using a <code>
2777 |  |
          * PreparedStatement</code>. The SQL string contains "?" characters for
2778 |  |
          * the values will be cached for later use to avoid the SQL generation
2779 |  |
          * overhead.
2780 |  |
          *
2781 |  |
          * @param conn
2782 |  |
          *            JDBC Connection.
2783 |  |
          * @param objectMappingKey
2784 |  |
          *            The object mapping key by which the object mapping to be used
2785 |  |
          *            is stored in the object mapping cache, in the persistence
2786 |  |
          *            configuration used by this instance of the DAO class.
2787 |  |
          * @param objects
2788 |  |
          *            The collection of objects containing the values for the
2789 |  |
          *            records to be updated.
2790 |  |
          * @return An array containing the number of records affected by each update
2791 |  |
          *         action, as returned by <code>PreparedStatement.executeBatch()
2792 |  |
          *         </code>.
2793 |  |
          * @throws PersistenceException
2794 |  |
          *             If anything goes wrong during the update, if no persistence
2795 |  |
          *             configuration is set, if the persistence configuration
2796 |  |
          *             contains no object writer, or if no object mapping could be
2797 |  |
          *             found nor generated from the given object mapping key.
2798 |  |
          * @throws DAOException
2799 |  |
          */
2800 |  |
         int[] updateBatch(Connection conn, Object objectMappingKey,
2801 |  |
                 Collection objects) throws PersistenceException, DAOException;
2802 |  |
2803 |  |
         /**
2804 |  |
          * Same as
2805 |  |
          * <code>updateBatchByPrimaryKeys(Object objectMappingKey, Collection objects, Collection oldPrimaryKeys)</code>
2806 |  |
          * the class returned by the getClass() of the first element in the
2807 |  |
          * collection as the object mapping key.
2808 |  |
          *
2809 |  |
          * @param objects
2810 |  |
          *            The collection of objects containing the values for the
2811 |  |
          *            records to be updated.
2812 |  |
          * @param oldPrimaryKeys
2813 |  |
          *            The collection of old primary keys each matching an object in
2814 |  |
          *            the objects collection. The keys must be returned by the
2815 |  |
          *            collection iterator in the same sequence as the objects they
2816 |  |
          *            match are returned by the object.iterator().
2817 |  |
          * @return An array containing the number of records affected by each update
2818 |  |
          *         action, as returned by
2819 |  |
          *         <code>PreparedStatement.executeBatch()</code>.
2820 |  |
          * @throws PersistenceException
2821 |  |
          *             If anything goes wrong during the update, if no persistence
2822 |  |
          *             configuration is set, if the persistence configuration
2823 |  |
          *             contains no object writer, or if no object mapping could be
2824 |  |
          *             found nor generated from the given object mapping key.
2825 |  |
          * @throws DAOException
2826 |  |
          */
2827 |  |
2828 |  |
         int[] updateBatchByPrimaryKeys(Collection objects, Collection oldPrimaryKeys)
2829 |  |
                 throws PersistenceException, DAOException;
2830 |  |
2831 |  |
         /**
2832 |  |
          * Same as
2833 |  |
          * <code>updateBatchByPrimaryKeys(Object objectMappingKey, Collection objects, Collection oldPrimaryKeys)</code>
2834 |  |
          * the class returned by the getClass() of the first element in the
2835 |  |
          * collection as the object mapping key.
2836 |  |
          *
2837 |  |
          * @param conn
2838 |  |
          *            JDBC Connection.
2839 |  |
          * @param objects
2840 |  |
          *            The collection of objects containing the values for the
2841 |  |
          *            records to be updated.
2842 |  |
          * @param oldPrimaryKeys
2843 |  |
          *            The collection of old primary keys each matching an object in
2844 |  |
          *            the objects collection. The keys must be returned by the
2845 |  |
          *            collection iterator in the same sequence as the objects they
2846 |  |
          *            match are returned by the object.iterator().
2847 |  |
          * @return An array containing the number of records affected by each update
2848 |  |
          *         action, as returned by
2849 |  |
          *         <code>PreparedStatement.executeBatch()</code>.
2850 |  |
          * @throws PersistenceException
2851 |  |
          *             If anything goes wrong during the update, if no persistence
2852 |  |
          *             configuration is set, if the persistence configuration
2853 |  |
          *             contains no object writer, or if no object mapping could be
2854 |  |
          *             found nor generated from the given object mapping key.
2855 |  |
          * @throws DAOException
2856 |  |
          */
2857 |  |
2858 |  |
         int[] updateBatchByPrimaryKeys(Connection conn, Collection objects,
2859 |  |
                 Collection oldPrimaryKeys) throws PersistenceException,
2860 |  |
                 DAOException;
2861 |  |
2862 |  |
         /**
2863 |  |
          * Updates the records in the database coresponding to the given collection
2864 |  |
          * of objects, with the values contained in these objects, according to the
2865 |  |
          * object mapping stored or generated by the given object mapping key. This
2866 |  |
          * method uses JDBC batch updates to do the job, meaning all SQL statements
2867 |  |
          * are batched and sent to the database in one go.
2868 |  |
          *
2869 |  |
          * <br/><br/>Use this method if the primary key values are also changed
2870 |  |
          * during the update. The old primary key values are used to identify the
2871 |  |
          * records to be updated. The values of the primary keys in the objects are
2872 |  |
          * the values the the primary keys of the records will have after the
2873 |  |
          * update.
2874 |  |
          *
2875 |  |
          * <br/><br/>A connection to the database will be obtained from the
2876 |  |
          * getConnection() method of this instance.
2877 |  |
          *
2878 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
2879 |  |
          * key, a new object mapping will be attempted generated and stored by that
2880 |  |
          * object mapping key. An object mapping can only be generated automatically
2881 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
2882 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
2883 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
2884 |  |
          * setObjectClass(Class theClass) method).
2885 |  |
          *
2886 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
2887 |  |
          * objects to be updated, meaning if you want to update objects of class
2888 |  |
          * <code>Employee</code> the <code>Class</code> instance should be that
2889 |  |
          * found at <code>Employee.class</code>.
2890 |  |
          *
2891 |  |
          * <br/><br/>The SQL needed to update the record will be generated
2892 |  |
          * automatically based on the object mapping, and executed using a <code>
2893 |  |
          * PreparedStatement</code>. The SQL string contains "?" characters for
2894 |  |
          * the values will be cached for later use to avoid the SQL generation
2895 |  |
          * overhead.
2896 |  |
          *
2897 |  |
          * @param objectMappingKey
2898 |  |
          *            The object mapping key by which the object mapping to be used
2899 |  |
          *            is stored in the object mapping cache, in the persistence
2900 |  |
          *            configuration used by this instance of the DAO class.
2901 |  |
          * @param objects
2902 |  |
          *            The collection of objects containing the values for the
2903 |  |
          *            records to be updated.
2904 |  |
          * @param oldPrimaryKeys
2905 |  |
          *            The collection of old primary keys each matching an object in
2906 |  |
          *            the objects collection. The keys must be returned by the
2907 |  |
          *            collection iterator in the same sequence as the objects they
2908 |  |
          *            match are returned by the object.iterator().
2909 |  |
          * @return An array containing the number of records affected by each update
2910 |  |
          *         action, as returned by <code>PreparedStatement.executeBatch()
2911 |  |
          *         </code>.
2912 |  |
          * @throws PersistenceException
2913 |  |
          *             If anything goes wrong during the update, if no persistence
2914 |  |
          *             configuration is set, if the persistence configuration
2915 |  |
          *             contains no object writer, or if no object mapping could be
2916 |  |
          *             found nor generated from the given object mapping key.
2917 |  |
          * @throws DAOException
2918 |  |
          */
2919 |  |
         int[] updateBatchByPrimaryKeys(Object objectMappingKey, Collection objects,
2920 |  |
                 Collection oldPrimaryKeys) throws PersistenceException,
2921 |  |
                 DAOException;
2922 |  |
2923 |  |
         /**
2924 |  |
          * Updates the records in the database coresponding to the given collection
2925 |  |
          * of objects, with the values contained in these objects, according to the
2926 |  |
          * object mapping stored or generated by the given object mapping key. This
2927 |  |
          * method uses JDBC batch updates to do the job, meaning all SQL statements
2928 |  |
          * are batched and sent to the database in one go.
2929 |  |
          *
2930 |  |
          * <br/><br/>Use this method if the primary key values are also changed
2931 |  |
          * during the update. The old primary key values are used to identify the
2932 |  |
          * records to be updated. The values of the primary keys in the objects are
2933 |  |
          * the values the the primary keys of the records will have after the
2934 |  |
          * update.
2935 |  |
          *
2936 |  |
          * <br/><br/>A connection to the database will be obtained from the
2937 |  |
          * getConnection() method of this instance.
2938 |  |
          *
2939 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
2940 |  |
          * key, a new object mapping will be attempted generated and stored by that
2941 |  |
          * object mapping key. An object mapping can only be generated automatically
2942 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
2943 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
2944 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
2945 |  |
          * setObjectClass(Class theClass) method).
2946 |  |
          *
2947 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
2948 |  |
          * objects to be updated, meaning if you want to update objects of class
2949 |  |
          * <code>Employee</code> the <code>Class</code> instance should be that
2950 |  |
          * found at <code>Employee.class</code>.
2951 |  |
          *
2952 |  |
          * <br/><br/>The SQL needed to update the record will be generated
2953 |  |
          * automatically based on the object mapping, and executed using a <code>
2954 |  |
          * PreparedStatement</code>. The SQL string contains "?" characters for
2955 |  |
          * the values will be cached for later use to avoid the SQL generation
2956 |  |
          * overhead.
2957 |  |
          *
2958 |  |
          * @param conn
2959 |  |
          *            JDBC Connection.
2960 |  |
          * @param objectMappingKey
2961 |  |
          *            The object mapping key by which the object mapping to be used
2962 |  |
          *            is stored in the object mapping cache, in the persistence
2963 |  |
          *            configuration used by this instance of the DAO class.
2964 |  |
          * @param objects
2965 |  |
          *            The collection of objects containing the values for the
2966 |  |
          *            records to be updated.
2967 |  |
          * @param oldPrimaryKeys
2968 |  |
          *            The collection of old primary keys each matching an object in
2969 |  |
          *            the objects collection. The keys must be returned by the
2970 |  |
          *            collection iterator in the same sequence as the objects they
2971 |  |
          *            match are returned by the object.iterator().
2972 |  |
          * @return An array containing the number of records affected by each update
2973 |  |
          *         action, as returned by <code>PreparedStatement.executeBatch()
2974 |  |
          *         </code>.
2975 |  |
          * @throws PersistenceException
2976 |  |
          *             If anything goes wrong during the update, if no persistence
2977 |  |
          *             configuration is set, if the persistence configuration
2978 |  |
          *             contains no object writer, or if no object mapping could be
2979 |  |
          *             found nor generated from the given object mapping key.
2980 |  |
          * @throws DAOException
2981 |  |
          */
2982 |  |
         int[] updateBatchByPrimaryKeys(Connection conn, Object objectMappingKey,
2983 |  |
                 Collection objects, Collection oldPrimaryKeys)
2984 |  |
                 throws PersistenceException, DAOException;
2985 |  |
2986 |  |
         /**
2987 |  |
          * Same as <code>delete(Object objectMappingKey, Object object)</code> but
2988 |  |
          * uses the object.getClass() as the object mapping key.
2989 |  |
          *
2990 |  |
          * @param object
2991 |  |
          *            The object containing the primary key of the record to be
2992 |  |
          *            deleted.
2993 |  |
          * @return The number of records affected by this delete action, as returned
2994 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
2995 |  |
          * @throws PersistenceException
2996 |  |
          *             If anything goes wrong during the delete, if no persistence
2997 |  |
          *             configuration is set, if the persistence configuration
2998 |  |
          *             contains no object writer, or if no object mapping could be
2999 |  |
          *             found nor generated from the given object mapping key.
3000 |  |
          * @throws DAOException
3001 |  |
          */
3002 |  |
         int delete(Object object) throws PersistenceException, DAOException;
3003 |  |
3004 |  |
         /**
3005 |  |
          * Same as <code>delete(Object objectMappingKey, Object object)</code> but
3006 |  |
          * uses the object.getClass() as the object mapping key.
3007 |  |
          *
3008 |  |
          * @param conn
3009 |  |
          *            JDBC Connection
3010 |  |
          * @param object
3011 |  |
          *            The object containing the primary key of the record to be
3012 |  |
          *            deleted.
3013 |  |
          * @return The number of records affected by this delete action, as returned
3014 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
3015 |  |
          * @throws PersistenceException
3016 |  |
          *             If anything goes wrong during the delete, if no persistence
3017 |  |
          *             configuration is set, if the persistence configuration
3018 |  |
          *             contains no object writer, or if no object mapping could be
3019 |  |
          *             found nor generated from the given object mapping key.
3020 |  |
          * @throws DAOException
3021 |  |
          */
3022 |  |
         int delete(Connection conn, Object object) throws PersistenceException,
3023 |  |
                 DAOException;
3024 |  |
3025 |  |
         /**
3026 |  |
          * Deletes the record from the database coresponding to the given object,
3027 |  |
          * according to the object mapping stored or generated by the given object
3028 |  |
          * mapping key.
3029 |  |
          *
3030 |  |
          * <br/><br/>A connection to the database will be obtained from the
3031 |  |
          * getConnection() method of this instance.
3032 |  |
          *
3033 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
3034 |  |
          * key, a new object mapping will be attempted generated and stored by that
3035 |  |
          * object mapping key. An object mapping can only be generated automatically
3036 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
3037 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
3038 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
3039 |  |
          * setObjectClass(Class theClass) method).
3040 |  |
          *
3041 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
3042 |  |
          * object to be deleted, meaning if you want to delete an object of class
3043 |  |
          * <code>Employee</code> the <code>Class</code> instance should be that
3044 |  |
          * found at <code>Employee.class</code>.
3045 |  |
          *
3046 |  |
          * <br/><br/>The SQL needed to delete the record will be generated
3047 |  |
          * automatically based on the object mapping, and executed using a <code>
3048 |  |
          * PreparedStatement</code>. The SQL string contains one or more "?"
3049 |  |
          * characters for the primary key value and will thus be cached for later
3050 |  |
          * use to avoid the SQL generation overhead.
3051 |  |
          *
3052 |  |
          * @param objectMappingKey
3053 |  |
          *            The object mapping key by which the object mapping to be used
3054 |  |
          *            is stored in the object mapping cache, in the persistence
3055 |  |
          *            configuration used by this instance of the DAO class.
3056 |  |
          * @param object
3057 |  |
          *            The object containing the primary key of the record to be
3058 |  |
          *            deleted.
3059 |  |
          * @return The number of records affected by this delete action, as returned
3060 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
3061 |  |
          * @throws PersistenceException
3062 |  |
          *             If anything goes wrong during the delete, if no persistence
3063 |  |
          *             configuration is set, if the persistence configuration
3064 |  |
          *             contains no object writer, or if no object mapping could be
3065 |  |
          *             found nor generated from the given object mapping key.
3066 |  |
          * @throws DAOException
3067 |  |
          */
3068 |  |
         int delete(Object objectMappingKey, Object object)
3069 |  |
                 throws PersistenceException, DAOException;
3070 |  |
3071 |  |
         /**
3072 |  |
          * Deletes the record from the database coresponding to the given object,
3073 |  |
          * according to the object mapping stored or generated by the given object
3074 |  |
          * mapping key.
3075 |  |
          *
3076 |  |
          * <br/><br/>A connection to the database will be obtained from the
3077 |  |
          * getConnection() method of this instance.
3078 |  |
          *
3079 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
3080 |  |
          * key, a new object mapping will be attempted generated and stored by that
3081 |  |
          * object mapping key. An object mapping can only be generated automatically
3082 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
3083 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
3084 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
3085 |  |
          * setObjectClass(Class theClass) method).
3086 |  |
          *
3087 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
3088 |  |
          * object to be deleted, meaning if you want to delete an object of class
3089 |  |
          * <code>Employee</code> the <code>Class</code> instance should be that
3090 |  |
          * found at <code>Employee.class</code>.
3091 |  |
          *
3092 |  |
          * <br/><br/>The SQL needed to delete the record will be generated
3093 |  |
          * automatically based on the object mapping, and executed using a <code>
3094 |  |
          * PreparedStatement</code>. The SQL string contains one or more "?"
3095 |  |
          * characters for the primary key value and will thus be cached for later
3096 |  |
          * use to avoid the SQL generation overhead.
3097 |  |
          *
3098 |  |
          * @param objectMappingKey
3099 |  |
          *            The object mapping key by which the object mapping to be used
3100 |  |
          *            is stored in the object mapping cache, in the persistence
3101 |  |
          *            configuration used by this instance of the DAO class.
3102 |  |
          * @param object
3103 |  |
          *            The object containing the primary key of the record to be
3104 |  |
          *            deleted.
3105 |  |
          * @return The number of records affected by this delete action, as returned
3106 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
3107 |  |
          * @throws PersistenceException
3108 |  |
          *             If anything goes wrong during the delete, if no persistence
3109 |  |
          *             configuration is set, if the persistence configuration
3110 |  |
          *             contains no object writer, or if no object mapping could be
3111 |  |
          *             found nor generated from the given object mapping key.
3112 |  |
          * @throws DAOException
3113 |  |
          */
3114 |  |
         int delete(Connection conn, Object objectMappingKey, Object object)
3115 |  |
                 throws PersistenceException, DAOException;
3116 |  |
3117 |  |
         /**
3118 |  |
          * Same as
3119 |  |
          * <code>deleteBatch(Object objectMappingKey, Collection objects)</code>
3120 |  |
          * but uses the class returned by the getClass() method of the first object
3121 |  |
          * in the collection, as returned by the collection iterator, as the object
3122 |  |
          * mapping key.
3123 |  |
          *
3124 |  |
          * @param objects
3125 |  |
          *            The collection containing the objects to be deleted.
3126 |  |
          * @return The number of records affected by this delete action, as returned
3127 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
3128 |  |
          * @throws PersistenceException
3129 |  |
          *             If anything goes wrong during the delete, if no persistence
3130 |  |
          *             configuration is set, if the persistence configuration
3131 |  |
          *             contains no object writer, or if no object mapping could be
3132 |  |
          *             found nor generated from the given object mapping key.
3133 |  |
          * @throws DAOException
3134 |  |
          */
3135 |  |
         int[] deleteBatch(Collection objects) throws PersistenceException,
3136 |  |
                 DAOException;
3137 |  |
3138 |  |
         /**
3139 |  |
          * Same as
3140 |  |
          * <code>deleteBatch(Object objectMappingKey, Collection objects)</code>
3141 |  |
          * but uses the class returned by the getClass() method of the first object
3142 |  |
          * in the collection, as returned by the collection iterator, as the object
3143 |  |
          * mapping key.
3144 |  |
          *
3145 |  |
          * @param objects
3146 |  |
          *            The collection containing the objects to be deleted.
3147 |  |
          * @return The number of records affected by this delete action, as returned
3148 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
3149 |  |
          * @throws PersistenceException
3150 |  |
          *             If anything goes wrong during the delete, if no persistence
3151 |  |
          *             configuration is set, if the persistence configuration
3152 |  |
          *             contains no object writer, or if no object mapping could be
3153 |  |
          *             found nor generated from the given object mapping key.
3154 |  |
          * @throws DAOException
3155 |  |
          */
3156 |  |
         int[] deleteBatch(Connection conn, Collection objects)
3157 |  |
                 throws PersistenceException, DAOException;
3158 |  |
3159 |  |
         /**
3160 |  |
          * Deletes the records from the database coresponding to the given objects,
3161 |  |
          * according to the object mapping stored or generated by the given object
3162 |  |
          * mapping key. This method uses JDBC batch updates to do the job, meaning
3163 |  |
          * the delete statements are batched up and sent to the database in one go.
3164 |  |
          *
3165 |  |
          * <br/><br/>A connection to the database will be obtained from the
3166 |  |
          * getConnection() method of this instance.
3167 |  |
          *
3168 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
3169 |  |
          * key, a new object mapping will be attempted generated and stored by that
3170 |  |
          * object mapping key. An object mapping can only be generated automatically
3171 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
3172 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
3173 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
3174 |  |
          * setObjectClass(Class theClass) method).
3175 |  |
          *
3176 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
3177 |  |
          * objects to be deleted, meaning if you want to delete objects of class
3178 |  |
          * <code>Employee</code> the <code>Class</code> instance should be that
3179 |  |
          * found at <code>Employee.class</code>.
3180 |  |
          *
3181 |  |
          * <br/><br/>The SQL needed to delete the record will be generated
3182 |  |
          * automatically based on the object mapping, and executed using a <code>
3183 |  |
          * PreparedStatement</code>. The SQL string contains one or more "?"
3184 |  |
          * characters for the primary key value and will thus be cached for later
3185 |  |
          * use to avoid the SQL generation overhead.
3186 |  |
          *
3187 |  |
          * @param objectMappingKey
3188 |  |
          *            The object mapping key by which the object mapping to be used
3189 |  |
          *            is stored in the object mapping cache, in the persistence
3190 |  |
          *            configuration used by this instance of the DAO class.
3191 |  |
          * @param objects
3192 |  |
          *            The collection containing the objects to be deleted.
3193 |  |
          * @return The number of records affected by this delete action, as returned
3194 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
3195 |  |
          * @throws PersistenceException
3196 |  |
          *             If anything goes wrong during the delete, if no persistence
3197 |  |
          *             configuration is set, if the persistence configuration
3198 |  |
          *             contains no object writer, or if no object mapping could be
3199 |  |
          *             found nor generated from the given object mapping key.
3200 |  |
          */
3201 |  |
         int[] deleteBatch(Object objectMappingKey, Collection objects)
3202 |  |
                 throws PersistenceException, DAOException;
3203 |  |
3204 |  |
         /**
3205 |  |
          * Deletes the records from the database coresponding to the given objects,
3206 |  |
          * according to the object mapping stored or generated by the given object
3207 |  |
          * mapping key. This method uses JDBC batch updates to do the job, meaning
3208 |  |
          * the delete statements are batched up and sent to the database in one go.
3209 |  |
          *
3210 |  |
          * <br/><br/>A connection to the database will be obtained from the
3211 |  |
          * getConnection() method of this instance.
3212 |  |
          *
3213 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
3214 |  |
          * key, a new object mapping will be attempted generated and stored by that
3215 |  |
          * object mapping key. An object mapping can only be generated automatically
3216 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
3217 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
3218 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
3219 |  |
          * setObjectClass(Class theClass) method).
3220 |  |
          *
3221 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
3222 |  |
          * objects to be deleted, meaning if you want to delete objects of class
3223 |  |
          * <code>Employee</code> the <code>Class</code> instance should be that
3224 |  |
          * found at <code>Employee.class</code>.
3225 |  |
          *
3226 |  |
          * <br/><br/>The SQL needed to delete the record will be generated
3227 |  |
          * automatically based on the object mapping, and executed using a <code>
3228 |  |
          * PreparedStatement</code>. The SQL string contains one or more "?"
3229 |  |
          * characters for the primary key value and will thus be cached for later
3230 |  |
          * use to avoid the SQL generation overhead.
3231 |  |
          *
3232 |  |
          * @param conn
3233 |  |
          *            JDBC Conection.
3234 |  |
          * @param objectMappingKey
3235 |  |
          *            The object mapping key by which the object mapping to be used
3236 |  |
          *            is stored in the object mapping cache, in the persistence
3237 |  |
          *            configuration used by this instance of the DAO class.
3238 |  |
          * @param objects
3239 |  |
          *            The collection containing the objects to be deleted.
3240 |  |
          * @return The number of records affected by this delete action, as returned
3241 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
3242 |  |
          * @throws PersistenceException
3243 |  |
          *             If anything goes wrong during the delete, if no persistence
3244 |  |
          *             configuration is set, if the persistence configuration
3245 |  |
          *             contains no object writer, or if no object mapping could be
3246 |  |
          *             found nor generated from the given object mapping key.
3247 |  |
          * @throws DAOException
3248 |  |
          */
3249 |  |
         int[] deleteBatch(Connection conn, Object objectMappingKey,
3250 |  |
                 Collection objects) throws PersistenceException, DAOException;
3251 |  |
3252 |  |
         /**
3253 |  |
          * Deletes the record from the database matching the given primary key,
3254 |  |
          * according to the object mapping stored or generated by the given object
3255 |  |
          * mapping key.
3256 |  |
          *
3257 |  |
          * <br/><br/>A connection to the database will be obtained from the
3258 |  |
          * getConnection() method of this instance.
3259 |  |
          *
3260 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
3261 |  |
          * key, a new object mapping will be attempted generated and stored by that
3262 |  |
          * object mapping key. An object mapping can only be generated automatically
3263 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
3264 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
3265 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
3266 |  |
          * setObjectClass(Class theClass) method).
3267 |  |
          *
3268 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
3269 |  |
          * object to be deleted, meaning if you want to delete an object of class
3270 |  |
          * <code>Employee</code> the <code>Class</code> instance should be that
3271 |  |
          * found at <code>Employee.class</code>.
3272 |  |
          *
3273 |  |
          * <br/><br/>The SQL needed to delete the record will be generated
3274 |  |
          * automatically based on the object mapping, and executed using a <code>
3275 |  |
          * PreparedStatement</code>. The SQL string contains one or more "?"
3276 |  |
          * characters for the primary key value and will thus be cached for later
3277 |  |
          * use to avoid the SQL generation overhead.
3278 |  |
          *
3279 |  |
          * @param objectMappingKey
3280 |  |
          *            The object mapping key by which the object mapping to be used
3281 |  |
          *            is stored in the object mapping cache, in the persistence
3282 |  |
          *            configuration used by this instance of the DAO class.
3283 |  |
          * @param primaryKey
3284 |  |
          *            The primary key matching the record to be deleted.
3285 |  |
          * @return The number of records affected by this delete action, as returned
3286 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
3287 |  |
          * @throws PersistenceException
3288 |  |
          *             If anything goes wrong during the delete, if no persistence
3289 |  |
          *             configuration is set, if the persistence configuration
3290 |  |
          *             contains no object writer, or if no object mapping could be
3291 |  |
          *             found nor generated from the given object mapping key.
3292 |  |
          * @throws DAOException
3293 |  |
          */
3294 |  |
         int deleteByPrimaryKey(Object objectMappingKey, Object primaryKey)
3295 |  |
                 throws PersistenceException, DAOException;
3296 |  |
3297 |  |
         /**
3298 |  |
          * Deletes the record from the database matching the given primary key,
3299 |  |
          * according to the object mapping stored or generated by the given object
3300 |  |
          * mapping key.
3301 |  |
          *
3302 |  |
          * <br/><br/>A connection to the database will be obtained from the
3303 |  |
          * getConnection() method of this instance.
3304 |  |
          *
3305 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
3306 |  |
          * key, a new object mapping will be attempted generated and stored by that
3307 |  |
          * object mapping key. An object mapping can only be generated automatically
3308 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
3309 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
3310 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
3311 |  |
          * setObjectClass(Class theClass) method).
3312 |  |
          *
3313 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
3314 |  |
          * object to be deleted, meaning if you want to delete an object of class
3315 |  |
          * <code>Employee</code> the <code>Class</code> instance should be that
3316 |  |
          * found at <code>Employee.class</code>.
3317 |  |
          *
3318 |  |
          * <br/><br/>The SQL needed to delete the record will be generated
3319 |  |
          * automatically based on the object mapping, and executed using a <code>
3320 |  |
          * PreparedStatement</code>. The SQL string contains one or more "?"
3321 |  |
          * characters for the primary key value and will thus be cached for later
3322 |  |
          * use to avoid the SQL generation overhead.
3323 |  |
          *
3324 |  |
          * @param conn
3325 |  |
          *            JDBC Connection.
3326 |  |
          * @param objectMappingKey
3327 |  |
          *            The object mapping key by which the object mapping to be used
3328 |  |
          *            is stored in the object mapping cache, in the persistence
3329 |  |
          *            configuration used by this instance of the DAO class.
3330 |  |
          * @param primaryKey
3331 |  |
          *            The primary key matching the record to be deleted.
3332 |  |
          * @return The number of records affected by this delete action, as returned
3333 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
3334 |  |
          * @throws PersistenceException
3335 |  |
          *             If anything goes wrong during the delete, if no persistence
3336 |  |
          *             configuration is set, if the persistence configuration
3337 |  |
          *             contains no object writer, or if no object mapping could be
3338 |  |
          *             found nor generated from the given object mapping key.
3339 |  |
          * @throws DAOException
3340 |  |
          */
3341 |  |
         int deleteByPrimaryKey(Connection conn, Object objectMappingKey,
3342 |  |
                 Object primaryKey) throws PersistenceException, DAOException;
3343 |  |
3344 |  |
         /**
3345 |  |
          * Deletes the records from the database coresponding to the given primary
3346 |  |
          * keys, according to the object mapping stored or generated by the given
3347 |  |
          * object mapping key. This method uses JDBC batch updates to do the job,
3348 |  |
          * meaning the delete statements are batched up and sent to the database in
3349 |  |
          * one go.
3350 |  |
          *
3351 |  |
          * <br/><br/>A connection to the database will be obtained from the
3352 |  |
          * getConnection() method of this instance.
3353 |  |
          *
3354 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
3355 |  |
          * key, a new object mapping will be attempted generated and stored by that
3356 |  |
          * object mapping key. An object mapping can only be generated automatically
3357 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
3358 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
3359 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
3360 |  |
          * setObjectClass(Class theClass) method).
3361 |  |
          *
3362 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
3363 |  |
          * objects to be deleted, meaning if you want to delete objects of class
3364 |  |
          * <code>Employee</code> the <code>Class</code> instance should be that
3365 |  |
          * found at <code>Employee.class</code>.
3366 |  |
          *
3367 |  |
          * <br/><br/>The SQL needed to delete the record will be generated
3368 |  |
          * automatically based on the object mapping, and executed using a <code>
3369 |  |
          * PreparedStatement</code>. The SQL string contains one or more "?"
3370 |  |
          * characters for the primary key value and will thus be cached for later
3371 |  |
          * use to avoid the SQL generation overhead.
3372 |  |
          *
3373 |  |
          * @param objectMappingKey
3374 |  |
          *            The object mapping key by which the object mapping to be used
3375 |  |
          *            is stored in the object mapping cache, in the persistence
3376 |  |
          *            configuration used by this instance of the DAO class.
3377 |  |
          * @param primaryKeys
3378 |  |
          *            The collection containing the primary keys of the records to
3379 |  |
          *            be deleted.
3380 |  |
          * @return The number of records affected by this delete action, as returned
3381 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
3382 |  |
          * @throws PersistenceException
3383 |  |
          *             If anything goes wrong during the delete, if no persistence
3384 |  |
          *             configuration is set, if the persistence configuration
3385 |  |
          *             contains no object writer, or if no object mapping could be
3386 |  |
          *             found nor generated from the given object mapping key.
3387 |  |
          */
3388 |  |
         int[] deleteBatchByPrimaryKeys(Object objectMappingKey,
3389 |  |
                 Collection primaryKeys) throws PersistenceException, DAOException;
3390 |  |
3391 |  |
         /**
3392 |  |
          * Deletes the records from the database coresponding to the given primary
3393 |  |
          * keys, according to the object mapping stored or generated by the given
3394 |  |
          * object mapping key. This method uses JDBC batch updates to do the job,
3395 |  |
          * meaning the delete statements are batched up and sent to the database in
3396 |  |
          * one go.
3397 |  |
          *
3398 |  |
          * <br/><br/>A connection to the database will be obtained from the
3399 |  |
          * getConnection() method of this instance.
3400 |  |
          *
3401 |  |
          * <br/><br/>If no object mapping is stored by the given object mapping
3402 |  |
          * key, a new object mapping will be attempted generated and stored by that
3403 |  |
          * object mapping key. An object mapping can only be generated automatically
3404 |  |
          * if the method key is either a</code> Class</code> instance, or a <code>
3405 |  |
          * com.jenkov.mrpersister.impl.method.ObjectMappingKey</code> instance with
3406 |  |
          * a <code>Class</code> instance set (calling ObjectMappingKey's
3407 |  |
          * setObjectClass(Class theClass) method).
3408 |  |
          *
3409 |  |
          * <br/><br/>The <code>Class</code> instance should be the class of the
3410 |  |
          * objects to be deleted, meaning if you want to delete objects of class
3411 |  |
          * <code>Employee</code> the <code>Class</code> instance should be that
3412 |  |
          * found at <code>Employee.class</code>.
3413 |  |
          *
3414 |  |
          * <br/><br/>The SQL needed to delete the record will be generated
3415 |  |
          * automatically based on the object mapping, and executed using a <code>
3416 |  |
          * PreparedStatement</code>. The SQL string contains one or more "?"
3417 |  |
          * characters for the primary key value and will thus be cached for later
3418 |  |
          * use to avoid the SQL generation overhead.
3419 |  |
          *
3420 |  |
          * @param conn
3421 |  |
          *            JDBC Connection
3422 |  |
          * @param objectMappingKey
3423 |  |
          *            The object mapping key by which the object mapping to be used
3424 |  |
          *            is stored in the object mapping cache, in the persistence
3425 |  |
          *            configuration used by this instance of the DAO class.
3426 |  |
          * @param primaryKeys
3427 |  |
          *            The collection containing the primary keys of the records to
3428 |  |
          *            be deleted.
3429 |  |
          * @return The number of records affected by this delete action, as returned
3430 |  |
          *         by <code>PreparedStatement.executeUpdate()</code>.
3431 |  |
          * @throws PersistenceException
3432 |  |
          *             If anything goes wrong during the delete, if no persistence
3433 |  |
          *             configuration is set, if the persistence configuration
3434 |  |
          *             contains no object writer, or if no object mapping could be
3435 |  |
          *             found nor generated from the given object mapping key.
3436 |  |
          * @exception DAOException
3437 |  |
          */
3438 |  |
         int[] deleteBatchByPrimaryKeys(Connection conn, Object objectMappingKey,
3439 |  |
                 Collection primaryKeys) throws PersistenceException, DAOException;
3440 |  |
3441 |  |
         /**
3442 |  |
          * Executes the given SQL update. Creates a <code>Statement</code> using
3443 |  |
          * the <code>Connection</code> stored inside this GenericDao instance,
3444 |  |
          * then executes the SQL update using that <code>Statement</code>
3445 |  |
          * instance.
3446 |  |
          *
3447 |  |
          * @param sql
3448 |  |
          *            The SQL udpate to execute.
3449 |  |
          * @return The number of records affected by the update, as returned by
3450 |  |
          *         <code>Statement.executeUpdate(sql)</code>.
3451 |  |
          * @throws PersistenceException
3452 |  |
          *             If a Statement cannot be created, or an error occurs when
3453 |  |
          *             attempting to execute the update.
3454 |  |
          * @throws DAOException
3455 |  |
          */
3456 |  |
         int executeUpdate(String sql) throws PersistenceException, DAOException;
3457 |  |
3458 |  |
         /**
3459 |  |
          * Executes the given SQL update. Creates a <code>Statement</code> using
3460 |  |
          * the <code>Connection</code> stored inside this GenericDao instance,
3461 |  |
          * then executes the SQL update using that <code>Statement</code>
3462 |  |
          * instance.
3463 |  |
          *
3464 |  |
          * @param conn
3465 |  |
          * @param sql
3466 |  |
          *            The SQL udpate to execute.
3467 |  |
          * @return The number of records affected by the update, as returned by
3468 |  |
          *         <code>Statement.executeUpdate(sql)</code>.
3469 |  |
          * @throws PersistenceException
3470 |  |
          *             If a Statement cannot be created, or an error occurs when
3471 |  |
          *             attempting to execute the update.
3472 |  |
          * @throws DAOException
3473 |  |
          */
3474 |  |
         int executeUpdate(Connection conn, String sql) throws PersistenceException,
3475 |  |
                 DAOException;
3476 |  |
3477 |  |
         /**
3478 |  |
          * Executes the given SQL update. Creates a <code>PreparedStatement</code>
3479 |  |
          * using the <code>Connection</code> stored inside this GenericDao
3480 |  |
          * instance, then executes the SQL update using that
3481 |  |
          * <code>PreparedStatement</code> instance. The parameters are inserted
3482 |  |
          * into the <code>PreparedStatement</code> instance in the sequence they
3483 |  |
          * occur in the <code>Iterator</code> returned by the parameter
3484 |  |
          * collection. In most cases it is easiest to use a list as the collection.
3485 |  |
          *
3486 |  |
          * @param sql
3487 |  |
          *            The SQL udpate to execute.
3488 |  |
          * @param parameters
3489 |  |
          *            The parameters to be inserted into the
3490 |  |
          *            <code>PreparedStatement</code>
3491 |  |
          * @return The number of records affected by the update, as returned by
3492 |  |
          *         <code>PreparedStatement.executeUpdate(sql)</code>.
3493 |  |
          * @throws PersistenceException
3494 |  |
          *             If a <code>PreparedStatement</code> cannot be created, or
3495 |  |
          *             an error occurs when attempting to execute the update.
3496 |  |
          */
3497 |  |
         int executeUpdate(String sql, Collection parameters)
3498 |  |
                 throws PersistenceException, DAOException;;
3499 |  |
3500 |  |
         /**
3501 |  |
          * Executes the given SQL update. Creates a <code>PreparedStatement</code>
3502 |  |
          * using the <code>Connection</code> stored inside this GenericDao
3503 |  |
          * instance, then executes the SQL update using that
3504 |  |
          * <code>PreparedStatement</code> instance. The parameters are inserted
3505 |  |
          * into the <code>PreparedStatement</code> instance in the sequence they
3506 |  |
          * occur in the <code>Iterator</code> returned by the parameter
3507 |  |
          * collection. In most cases it is easiest to use a list as the collection.
3508 |  |
          *
3509 |  |
          * @param conn
3510 |  |
          *            JDBC Connection.
3511 |  |
          * @param sql
3512 |  |
          *            The SQL udpate to execute.
3513 |  |
          * @param parameters
3514 |  |
          *            The parameters to be inserted into the
3515 |  |
          *            <code>PreparedStatement</code>
3516 |  |
          * @return The number of records affected by the update, as returned by
3517 |  |
          *         <code>PreparedStatement.executeUpdate(sql)</code>.
3518 |  |
          * @throws PersistenceException
3519 |  |
          *             If a <code>PreparedStatement</code> cannot be created, or
3520 |  |
          *             an error occurs when attempting to execute the update.
3521 |  |
          * @throws DAOException
3522 |  |
          */
3523 |  |
         int executeUpdate(Connection conn, String sql, Collection parameters)
3524 |  |
                 throws PersistenceException, DAOException;
3525 |  |
3526 |  |
         /**
3527 |  |
          * Executes the given SQL update. Creates a <code>PreparedStatement</code>
3528 |  |
          * using the <code>Connection</code> stored inside this GenericDao
3529 |  |
          * instance, then executes the SQL update using that
3530 |  |
          * <code>PreparedStatement</code> instance. The parameters are inserted
3531 |  |
          * into the <code>PreparedStatement</code> instance in the sequence they
3532 |  |
          * occur in the parameter array.
3533 |  |
          *
3534 |  |
          * @param sql
3535 |  |
          *            The SQL udpate to execute.
3536 |  |
          * @param parameters
3537 |  |
          *            The parameters to be inserted into the
3538 |  |
          *            <code>PreparedStatement</code>
3539 |  |
          * @return The number of records affected by the update, as returned by
3540 |  |
          *         <code>PreparedStatement.executeUpdate(sql)</code>.
3541 |  |
          * @throws PersistenceException
3542 |  |
          *             If a <code>PreparedStatement</code> cannot be created, or
3543 |  |
          *             an error occurs when attempting to execute the update.
3544 |  |
          */
3545 |  |
         int executeUpdate(String sql, Object[] parameters)
3546 |  |
                 throws PersistenceException, DAOException;
3547 |  |
3548 |  |
         /**
3549 |  |
          * Executes the given SQL update. Creates a <code>PreparedStatement</code>
3550 |  |
          * using the <code>Connection</code> stored inside this GenericDao
3551 |  |
          * instance, then executes the SQL update using that
3552 |  |
          * <code>PreparedStatement</code> instance. The parameters are inserted
3553 |  |
          * into the <code>PreparedStatement</code> instance in the sequence they
3554 |  |
          * occur in the parameter array.
3555 |  |
          *
3556 |  |
          * @param conn
3557 |  |
          *            JDBC Connection.
3558 |  |
          * @param sql
3559 |  |
          *            The SQL udpate to execute.
3560 |  |
          * @param parameters
3561 |  |
          *            The parameters to be inserted into the
3562 |  |
          *            <code>PreparedStatement</code>
3563 |  |
          * @return The number of records affected by the update, as returned by
3564 |  |
          *         <code>PreparedStatement.executeUpdate(sql)</code>.
3565 |  |
          * @throws PersistenceException
3566 |  |
          *             If a <code>PreparedStatement</code> cannot be created, or
3567 |  |
          *             an error occurs when attempting to execute the update.
3568 |  |
          * @throws DAOException.
3569 |  |
          */
3570 |  |
         int executeUpdate(Connection conn, String sql, Object[] parameters)
3571 |  |
                 throws PersistenceException, DAOException;
3572 |  |
3573 |  |
     }