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