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