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