001: /**
002: * Objective Database Abstraction Layer (ODAL)
003: * Copyright (c) 2004, The ODAL Development Group
004: * All rights reserved.
005: * For definition of the ODAL Development Group please refer to LICENCE.txt file
006: *
007: * Distributable under LGPL license.
008: * See terms of license at gnu.org.
009: */package com.completex.objective.components.persistency;
010:
011: import com.completex.objective.components.persistency.transact.Transaction;
012: import com.completex.objective.components.persistency.transact.TransactionManagerAware;
013: import com.completex.objective.components.persistency.type.TracingCollection;
014: import com.completex.objective.components.persistency.core.ResultSetIterator;
015:
016: import java.sql.PreparedStatement;
017: import java.sql.SQLException;
018: import java.sql.CallableStatement;
019: import java.util.Collection;
020:
021: /**
022: * @author Gennady Krizhevsky
023: */
024: public interface Persistency2 extends Persistency0, InsertPersistency2,
025: TransactionManagerAware {
026:
027: /**
028: * Retrieves persistent object "by example" by primary key. The fields and their values that are set on the object are then joined by "and" into sql where clause.
029: * Even if non-key fields are set they will be ignored.
030: * PersistentObject passed as parameter used as a factory of object to be returned.
031: * The returned instance is different from the parameter one
032: *
033: * @param transaction
034: * @param persistentObject
035: * @return loaded PersistentObject
036: * @throws OdalPersistencyException
037: * @throws RecordValidationException if primary key is missing or the values are not set
038: */
039: Object load(Transaction transaction,
040: PersistentObject persistentObject)
041: throws OdalPersistencyException;
042:
043: /**
044: * Retrieves persistent object "by example" by primary key. The fields and their values that are set on the object are then joined by "and" into sql where clause.
045: * Even if non-key fields are set they will be ignored.
046: * PersistentObject passed as parameter used as a factory of object to be returned.
047: * The returned instance is different from the parameter one
048: *
049: * @see LockType
050: * @param transaction
051: * @param persistentObject
052: * @param lock Lock type
053: * @return loaded PersistentObject
054: * @throws OdalPersistencyException
055: */
056: Object load(Transaction transaction,
057: PersistentObject persistentObject, LockType lock)
058: throws OdalPersistencyException;
059:
060: /**
061: * Retrieves persistent object "by example" by primary key. The fields and their values that are set on the object are then joined by "and" into sql where clause.
062: * Even if non-key fields are set they will be ignored.
063: * PersistentObject passed as parameter used as a factory of object to be returned.
064: * The returned instance is different from the parameter one
065: *
066: * @param transaction
067: * @param persistentObject
068: * @param lockType
069: * @param timeout Timeout on lock in seconds
070: * @return loaded PersistentObject
071: * @throws OdalPersistencyException
072: */
073: Object load(Transaction transaction,
074: PersistentObject persistentObject, LockType lockType,
075: long timeout) throws OdalPersistencyException;
076:
077: /**
078: * Retrieves collection of persistent objects "by example" PersistentObject.
079: * The fields and their values that are set on the object are then joined by "and" into sql where clause.
080: * PersistentObject passed as parameter used as a factory of objects to be returned.
081: *
082: * @param transaction
083: * @param persistentObject
084: * @return Collection of persistent objects never null. If nothing found the one with 0-length is returned.
085: * @throws OdalPersistencyException
086: */
087: Collection select(Transaction transaction,
088: PersistentObject persistentObject)
089: throws OdalPersistencyException;
090:
091: /**
092: * Retrieves collection of persistent objects "by query".
093: * Query controls the type of collection and objects to return.
094: * Collection is never null. If nothing found the one with 0-length is returned.
095: *
096: * @see Query
097: * @param transaction
098: * @param query
099: * @return Collection of persistent objects - never null. If nothing found the one with 0-length is returned.
100: * @throws OdalPersistencyException
101: */
102: Collection select(Transaction transaction, Query query)
103: throws OdalPersistencyException;
104:
105: /**
106: * Retrieves collection of persistent objects "by query".
107: * Query controls the type of collection and objects to return.
108: * Collection is never null. If nothing found the one with 0-length is returned.
109: *
110: * @param transaction
111: * @param query
112: * @param controller LifeCycle interface that called when certain events happen
113: * @return Collection of persistent objects - never null. If nothing found the one with 0-length is returned.
114: * @throws OdalPersistencyException
115: */
116: Collection select(Transaction transaction, Query query,
117: LifeCycleController controller)
118: throws OdalPersistencyException;
119:
120: /**
121: * Retrieves collection of persistent objects "by example" PersistentObject.
122: * The fields and their values that are set on the object are then joined by "and" into sql where clause.
123: * PersistentObject passed as parameter used as a factory of objects to be returned.
124: *
125: * @param transaction
126: * @param persistentObject
127: * @param controller
128: * @return Collection of persistent objects - never null. If nothing found the one with 0-length is returned.
129: * @throws OdalPersistencyException
130: */
131: Collection select(Transaction transaction,
132: PersistentObject persistentObject,
133: LifeCycleController controller)
134: throws OdalPersistencyException;
135:
136: /**
137: * Retrieves collection of persistent objects "by example" PersistentObject.
138: * The fields and their values that are set on the object are then joined by "and" into sql where clause.
139: * PersistentObject passed as parameter used as a factory of objects to be returned.
140: *
141: * @param transaction
142: * @param persistentObject
143: * @param controller
144: * @param lock Lock type
145: * @return Collection of persistent objects - never null. If nothing found the one with 0-length is returned.
146: * @throws OdalPersistencyException
147: */
148: Collection select(Transaction transaction,
149: PersistentObject persistentObject,
150: LifeCycleController controller, LockType lock)
151: throws OdalPersistencyException;
152:
153: /**
154: * Retrieves collection of persistent objects "by example" PersistentObject.
155: * The fields and their values that are set on the object are then joined by "and" into sql where clause.
156: * PersistentObject passed as parameter used as a factory of objects to be returned.
157: *
158: * @param transaction
159: * @param persistentObject
160: * @param controller
161: * @param lock
162: * @param timeout Timeout on lock in seconds
163: * @return Collection of persistent objects - never null. If nothing found the one with 0-length is returned.
164: * @throws OdalPersistencyException
165: */
166: Collection select(Transaction transaction,
167: PersistentObject persistentObject,
168: LifeCycleController controller, LockType lock, long timeout)
169: throws OdalPersistencyException;
170:
171: /**
172: * Method will use query object to build exists sql statement.
173: * Concrete implementation may reject query in case sql string is set
174: * externally.
175: *
176: * @param transaction
177: * @param query
178: * @return true if query returns any results
179: * @throws OdalPersistencyException
180: */
181: boolean selectExists(Transaction transaction, Query query)
182: throws OdalPersistencyException;
183:
184: /**
185: * Method will use persistentObject to build exists sql statement.
186: * Concrete implementation may reject query in case sql string is set
187: * externally.
188: *
189: * @param transaction
190: * @param persistentObject
191: * @return true if query returns any results
192: * @throws OdalPersistencyException
193: */
194: boolean selectExists(Transaction transaction,
195: PersistentObject persistentObject)
196: throws OdalPersistencyException;
197:
198: /**
199: * Method will use query object to build "select count(*)" statement.
200: * Concrete implementation may reject query in case sql string is set
201: * externally.
202: *
203: * @param transaction
204: * @param query
205: * @return count
206: * @throws OdalPersistencyException
207: */
208: long selectCount(Transaction transaction, Query query)
209: throws OdalPersistencyException;
210:
211: /**
212: * Method will use persistentObject object to build "select count(*)" statement.
213: *
214: * @param transaction
215: * @param persistentObject
216: * @return count
217: * @throws OdalPersistencyException
218: */
219: long selectCount(Transaction transaction,
220: PersistentObject persistentObject)
221: throws OdalPersistencyException;
222:
223: /**
224: * Retrieves collection of persistent objects "by query" and returns the 1st object.
225: *
226: * @param transaction
227: * @param query
228: * @return 1st object or null if nothing found
229: * @throws OdalPersistencyException
230: */
231: Object selectFirst(Transaction transaction, Query query)
232: throws OdalPersistencyException;
233:
234: /**
235: * Retrieves collection of persistent objects "by example" and returns the 1st object.
236: *
237: * @param transaction
238: * @param persistentObject
239: * @return 1st object or null if nothing found
240: * @throws OdalPersistencyException
241: */
242: Object selectFirst(Transaction transaction,
243: PersistentObject persistentObject)
244: throws OdalPersistencyException;
245:
246: /**
247: * Retrieves collection of persistent objects "by example" and returns the 1st object.
248: *
249: * @param transaction
250: * @param persistentObject
251: * @param controller
252: * @return 1st object or null if nothing found
253: * @throws OdalPersistencyException
254: */
255: Object selectFirst(final Transaction transaction,
256: final PersistentObject persistentObject,
257: final LifeCycleController controller)
258: throws OdalPersistencyException;
259:
260: /**
261: * Retrieves collection of persistent objects "by example" and returns the 1st object.
262: *
263: * @see LockType
264: * @param transaction
265: * @param persistentObject
266: * @param lockType
267: * @return 1st object or null if nothing found
268: * @throws OdalPersistencyException
269: */
270: Object selectFirst(Transaction transaction,
271: PersistentObject persistentObject, LockType lockType)
272: throws OdalPersistencyException;
273:
274: /**
275: * Method can be used for queries that return single value results
276: *
277: * @param transaction
278: * @param query
279: * @return single value
280: * @throws OdalPersistencyException
281: */
282: Object selectSingle(Transaction transaction, Query query)
283: throws OdalPersistencyException;
284:
285: /**
286: * Get next sequence using default sequence generator
287: *
288: * @param transaction transaction
289: * @param persistency persistency
290: * @param record record
291: * @param name of the sequence
292: * @return next sequnce value
293: * @throws OdalPersistencyException
294: */
295: long getNextSeqValue(Transaction transaction,
296: Persistency persistency, Record record, String name)
297: throws OdalPersistencyException;
298:
299: /**
300: * Insert persistent object
301: *
302: * @param transaction transaction
303: * @param persistentObject PersistentObject
304: * @return number of row affected or RC_NON_DIRTY value if record is not "dirty". Should not be used for batch updates or complex/compound objects
305: * @throws DuplicateRecordException if duplicate record is detected
306: * @throws OdalPersistencyException
307: */
308: int insert(Transaction transaction,
309: PersistentObject persistentObject)
310: throws DuplicateRecordException, OdalPersistencyException;
311:
312: /**
313: * Insert persistent object
314: *
315: * @param transaction transaction
316: * @param persistentObject
317: * @param controller
318: * @return number of row affected or RC_NON_DIRTY value if record is not "dirty". Should not be used for batch updates or complex/compound objects
319: * @throws DuplicateRecordException
320: * @throws OdalPersistencyException
321: */
322: int insert(Transaction transaction,
323: PersistentObject persistentObject,
324: LifeCycleController controller)
325: throws DuplicateRecordException, OdalPersistencyException;
326:
327: /**
328: * Update persistent object. Key values are the ones of primary key and "optimistic lock" fields.
329: *
330: * @param transaction transaction
331: * @param persistentObject
332: * @return number of row affected or RC_NON_DIRTY value if record is not "dirty". Should not be used for batch updates or complex/compound objects
333: * @throws OdalPersistencyException
334: */
335: int update(Transaction transaction,
336: PersistentObject persistentObject)
337: throws OdalPersistencyException;
338:
339: /**
340: * Update persistent object. Key values are the ones of primary key and "optimistic lock" fields.
341: *
342: * @param transaction transaction
343: * @param persistentObject
344: * @param controller
345: * @return number of row affected or RC_NON_DIRTY value if record is not "dirty". Should not be used for batch updates or complex/compound objects
346: * @throws OdalPersistencyException
347: */
348: int update(Transaction transaction,
349: PersistentObject persistentObject,
350: LifeCycleController controller)
351: throws OdalPersistencyException;
352:
353: /**
354: * Update persistent object. Key values are the ones of primary key and "optimistic lock" fields.
355: *
356: * @param transaction transaction
357: * @param persistentObject
358: * @param extraWhere sql fragment that is added to the where clause w/o actual "WHERE" keyword inside
359: * @param extraParameters optional parameters for extraWhere sql fragment
360: * @param controller LifeCycleController
361: * @return number of row affected or RC_NON_DIRTY value if record is not "dirty". Should not be used for batch updates or complex/compound objects
362: * @throws OdalPersistencyException
363: */
364: int update(Transaction transaction,
365: PersistentObject persistentObject, String extraWhere,
366: Parameters extraParameters, LifeCycleController controller)
367: throws OdalPersistencyException;
368:
369: /**
370: * Update persistent object. Key values are the ones of primary key and "optimistic lock" fields.
371: *
372: * @param transaction transaction
373: * @param persistentObject
374: * @param extraWhere sql fragment
375: * @param extraParameters optional parameters for extraWhere sql fragment
376: * @param controller LifeCycleController
377: * @return number of row affected or RC_NON_DIRTY value if record is not "dirty". Should not be used for batch updates or complex/compound objects
378: * @throws OdalPersistencyException
379: */
380: int update(Transaction transaction,
381: PersistentObject persistentObject, String extraWhere,
382: Object[] extraParameters, LifeCycleController controller)
383: throws OdalPersistencyException;
384:
385: /**
386: * Execute ad-hoc data modifying sql.
387: *
388: * @param transaction
389: * @param sql
390: * @param parameters
391: * @return number of row affected or RC_NON_DIRTY value if record is not "dirty". Should not be used for batch updates or complex/compound objects
392: * @throws OdalPersistencyException
393: */
394: int executeUpdate(Transaction transaction, String sql,
395: Parameters parameters) throws OdalPersistencyException;
396:
397: /**
398: * Execute ad-hoc data modifying sql.
399: *
400: * @param transaction
401: * @param sql
402: * @return number of row affected or RC_NON_DIRTY value if record is not "dirty". Should not be used for batch updates or complex/compound objects
403: * @throws OdalPersistencyException
404: */
405: int executeUpdate(Transaction transaction, String sql)
406: throws OdalPersistencyException;
407:
408: /**
409: * Execute truncate table sql.
410: *
411: * @param transaction
412: * @param tableName
413: * @return number of row affected.
414: * @throws OdalPersistencyException
415: */
416: int truncate(Transaction transaction, String tableName)
417: throws OdalPersistencyException;
418:
419: /**
420: * Delete persistent object by primary key
421: *
422: * @param transaction
423: * @param persistentObject
424: * @return number of row affected. Should not be used for batch updates or complex/compound objects
425: * @throws OdalPersistencyException
426: */
427: int delete(Transaction transaction,
428: PersistentObject persistentObject)
429: throws OdalPersistencyException;
430:
431: /**
432: * Delete persistent object by primary key
433: *
434: * @param transaction
435: * @param persistentObject
436: * @param controller
437: * @return number of row affected. Should not be used for batch updates or complex/compound objects
438: * @throws OdalPersistencyException
439: */
440: int delete(Transaction transaction,
441: PersistentObject persistentObject,
442: LifeCycleController controller)
443: throws OdalPersistencyException;
444:
445: /**
446: * Deletes persistent object "by example" PersistentObject. The fields and their values that are set on the object are then joined by "and" into sql where clause.
447: *
448: * @param transaction
449: * @param persistentObject
450: * @param controller LifeCycleController
451: * @param limit max number of rows to delete (limit must be supported by the database)
452: * @return number of row affected. Should not be used for batch updates or complex/compound objects
453: * @throws OdalPersistencyException
454: */
455: int deleteByExample(Transaction transaction,
456: PersistentObject persistentObject,
457: LifeCycleController controller, int limit)
458: throws OdalPersistencyException;
459:
460: /**
461: * Deletes persistent object "by example" PersistentObject. The fields and their values that are set on the object are then joined by "and" into sql where clause.
462: *
463: * @param transaction
464: * @param persistentObject
465: * @param controller LifeCycleController
466: * @return number of row affected. Should not be used for batch updates or complex/compound objects
467: * @throws OdalPersistencyException
468: */
469: int deleteByExample(Transaction transaction,
470: PersistentObject persistentObject,
471: LifeCycleController controller)
472: throws OdalPersistencyException;
473:
474: //
475: // Methods to insert, delete & update collections:
476: //
477:
478: /**
479: * Insert collection of persistent objects
480: *
481: * @param transaction
482: * @param persistentObjects
483: * @return array of return codes - one per collection entry
484: * @throws OdalPersistencyException
485: */
486: int[] insert(Transaction transaction, Collection persistentObjects)
487: throws OdalPersistencyException;
488:
489: /**
490: * Delete collection of persistent objects
491: *
492: * @param transaction
493: * @param persistentObjects
494: * @return array of return codes - one per collection entry
495: * @throws OdalPersistencyException
496: */
497: int[] delete(Transaction transaction, Collection persistentObjects)
498: throws OdalPersistencyException;
499:
500: /**
501: * Update collection of persistent objects
502: *
503: * @param transaction
504: * @param persistentObjects
505: * @return array of return codes - one per collection entry
506: * @throws OdalPersistencyException
507: */
508: int[] update(Transaction transaction, Collection persistentObjects)
509: throws OdalPersistencyException;
510:
511: /**
512: * Update collection of persistent objects
513: *
514: * @param transaction
515: * @param collection
516: * @param lifeCycleController
517: * @return array of return codes - one per collection entry
518: * @throws OdalPersistencyException
519: */
520: int[] update(Transaction transaction, Collection collection,
521: LifeCycleController lifeCycleController)
522: throws OdalPersistencyException;
523:
524: /**
525: * Update collection of persistent objects.
526: * TracingCollection collection will be matched with the source one and "trced".
527: * That is objects that are in collection but not in source will be deleted,
528: * that are not in collection but are in source will be inserted, objects that are in
529: * both but "dirty" will be updated
530: *
531: * @param transaction
532: * @param collection
533: * @param source
534: * @param lifeCycleController
535: * @return array of return codes - one per collection entry
536: * @throws OdalPersistencyException
537: */
538: int[] update(Transaction transaction, TracingCollection collection,
539: Collection source, LifeCycleController lifeCycleController)
540: throws OdalPersistencyException;
541:
542: //
543: // Some lower level methods
544: //
545:
546: /**
547: *
548: * @param transaction
549: * @param query
550: * @param bindBuffer
551: * @return PreparedStatement
552: * @throws OdalPersistencyException
553: */
554: PreparedStatement prepareStatement(Transaction transaction,
555: Query query, StringBuffer bindBuffer)
556: throws OdalPersistencyException;
557:
558: /**
559: *
560: * @param transaction
561: * @param query
562: * @param bindBuffer
563: * @return CallableStatement
564: * @throws SQLException
565: */
566: CallableStatement prepareCall(Transaction transaction, Call query,
567: StringBuffer bindBuffer) throws SQLException;
568:
569: /**
570: * @see ResultSetIterator
571: * @param statement
572: * @param parameters
573: * @return new ResultSetIterator
574: * @throws SQLException
575: */
576: ResultSetIterator resultSetIterator(PreparedStatement statement,
577: AbstractParameters parameters) throws SQLException;
578:
579: int pipeInsert(Transaction transaction,
580: PersistentObject persistentObject,
581: LifeCycleController controller)
582: throws OdalPersistencyException;
583:
584: /**
585: * Executes stored procedure call that doe not return result set
586: *
587: * @param transaction transaction
588: * @param call Call object
589: * @throws java.sql.SQLException
590: */
591: void executeCall(Transaction transaction, Call call)
592: throws SQLException;
593:
594: /**
595: *
596: * Returns 1st AbstractPersistentObject if several are found or null none is found
597: *
598: * @param transaction
599: * @param query
600: * @param controller
601: * @return 1st AbstractPersistentObject if several are found or null if none is found
602: * @throws com.completex.objective.components.persistency.OdalPersistencyException
603: */
604: Object selectFirst(Transaction transaction, Query query,
605: LifeCycleController controller)
606: throws OdalPersistencyException;
607:
608: /**
609: * Returns 1st AbstractPersistentObject if several are found or null none is found
610: *
611: * @param transaction
612: * @param persistentObject
613: * @param controller
614: * @param lockType
615: * @return 1st AbstractPersistentObject if several are found or null none is found
616: * @throws com.completex.objective.components.persistency.OdalPersistencyException
617: */
618: Object selectFirst(Transaction transaction,
619: PersistentObject persistentObject,
620: LifeCycleController controller, LockType lockType)
621: throws OdalPersistencyException;
622:
623: /**
624: * Retrieves persistent object "by example" by primary key. The fields and their values that are set on the object are then joined by "and" into sql where clause.
625: * Even if non-key fields are set they will be ignored.
626: * PersistentObject passed as parameter used as a factory of object to be returned.
627: * The returned instance is different from the parameter one
628: *
629: * @param transaction
630: * @param persistentObject
631: * @param controller
632: * @param lockType
633: * @param timeout Timeout on lock in seconds
634: * @return loaded PersistentObject
635: * @throws com.completex.objective.components.persistency.OdalPersistencyException
636: */
637: Object load(Transaction transaction,
638: PersistentObject persistentObject,
639: LifeCycleController controller, LockType lockType,
640: long timeout) throws OdalPersistencyException;
641:
642: Object load(Transaction transaction,
643: PersistentObject persistentObject,
644: LifeCycleController controller)
645: throws OdalPersistencyException;
646: }
|