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