001: package com.completex.objective.components.persistency;
002:
003: import com.completex.objective.components.persistency.type.MultipartCollection;
004:
005: import java.util.Collection;
006:
007: /**
008: * @author Gennady Krizhevsky
009: */
010: public interface SelectPersistency {
011:
012: static final long NO_TIMEOUT = 0L;
013:
014: /**
015: * Retrieves persistent object "by example" by primary key.
016: * The fields and their values that are set on the object are then joined by "and" into sql where clause.
017: * Even if non-key fields are set they will be ignored.
018: * PersistentObject passed as parameter used as a factory of object to be returned.
019: * The returned instance is different from the parameter one
020: *
021: * @param persistentObject PersistentObject which values and corresponding column names are used to build the where clause
022: * @return loaded PersistentObject
023: * @throws com.completex.objective.components.persistency.OdalPersistencyException primary key values are nulls
024: *
025: */
026: Object load(PersistentObject persistentObject)
027: throws OdalPersistencyException;
028:
029: /**
030: * Retrieves persistent object "by example" by primary key.
031: * The fields and their values that are set on the object are then joined by "and" into sql where clause.
032: * Even if non-key fields are set they will be ignored.
033: * PersistentObject passed as parameter used as a factory of object to be returned.
034: * The returned instance is different from the parameter one
035: *
036: * @param persistentObject
037: * @param lockType
038: * @return loaded PersistentObject
039: * @throws com.completex.objective.components.persistency.OdalPersistencyException
040: *
041: */
042: Object load(PersistentObject persistentObject, LockType lockType)
043: throws OdalPersistencyException;
044:
045: /**
046: * Retrieves persistent object "by example" by primary key.
047: * The fields and their values that are set on the object are then joined by "and" into sql where clause.
048: * Even if non-key fields are set they will be ignored.
049: * PersistentObject passed as parameter used as a factory of object to be returned.
050: * The returned instance is different from the parameter one
051: *
052: * @param persistentObject PersistentObject which values and corresponding column names are used to build the where clause
053: * @param lockType Lock type
054: * @return loaded PersistentObject
055: * @throws com.completex.objective.components.persistency.OdalPersistencyException
056: *
057: * @see com.completex.objective.components.persistency.LockType
058: */
059: Object load(PersistentObject persistentObject, LockType lockType,
060: long timeout) throws OdalPersistencyException;
061:
062: /**
063: * Retrieves persistent object "by example" by primary key.
064: * The fields and their values that are set on the object are then joined by "and" into sql where clause.
065: * Even if non-key fields are set they will be ignored.
066: * PersistentObject passed as parameter used as a factory of object to be returned.
067: * The returned instance is different from the parameter one.
068: * Method will wait indefinitely until the record is released if locked by another session
069: * and will lock it upon retieval
070: *
071: * @param persistentObject PersistentObject which values and corresponding column names are used to build the where clause
072: * @return loaded <code>PersistentObject</code>
073: * @throws com.completex.objective.components.persistency.OdalPersistencyException
074: *
075: */
076: Object loadForUpdate(PersistentObject persistentObject)
077: throws OdalPersistencyException;
078:
079: /**
080: * Retrieves collection of persistent objects "by example" PersistentObject.
081: * The fields and their values that are set on the object are then joined by "and" into sql where clause.
082: * PersistentObject passed as parameter used as a factory of objects to be returned.
083: *
084: * @param persistentObject PersistentObject which values and corresponding column names are used to build the where clause
085: * @return Collection of persistent objects never null. If nothing found the one with 0-length is returned.
086: * @throws com.completex.objective.components.persistency.OdalPersistencyException
087: *
088: */
089: Collection select(PersistentObject persistentObject)
090: throws OdalPersistencyException;
091:
092: /**
093: * Retrieves collection of persistent objects "by query".
094: * Query controls the type of collection and objects to return.
095: * Collection is never null. If nothing found the one with 0-length is returned.
096: *
097: * @param query
098: * @return Collection of persistent objects - never null. If nothing found the one with 0-length is returned.
099: * @throws com.completex.objective.components.persistency.OdalPersistencyException
100: *
101: * @see com.completex.objective.components.persistency.Query
102: */
103: Collection select(Query query) throws OdalPersistencyException;
104:
105: /**
106: * Retrieves collection of persistent objects "by example" PersistentObject.
107: * The fields and their values that are set on the object are then joined by "and" into sql where clause.
108: * PersistentObject passed as parameter used as a factory of objects to be returned.
109: *
110: * @param persistentObject PersistentObject which values and corresponding column names are used to build the where clause
111: * @param controller
112: * @return Collection of persistent objects - never null. If nothing found the one with 0-length is returned.
113: * @throws com.completex.objective.components.persistency.OdalPersistencyException
114: *
115: */
116: Collection select(PersistentObject persistentObject,
117: LifeCycleController controller, LockType lock)
118: throws OdalPersistencyException;
119:
120: /**
121: * Retrieves collection of persistent objects "by query".
122: * Query controls the type of collection and objects to return.
123: * Collection is never null. If nothing found the one with 0-length is returned.
124: *
125: * @param query
126: * @param controller LifeCycle interface that called when certain events happen
127: * @return Collection of persistent objects - never null. If nothing found the one with 0-length is returned.
128: * @throws com.completex.objective.components.persistency.OdalPersistencyException
129: *
130: */
131: Collection select(Query query, LifeCycleController controller)
132: throws OdalPersistencyException;
133:
134: /**
135: * Retrieves collection of persistent objects "by example" PersistentObject.
136: * The fields and their values that are set on the object are then joined by "and" into sql where clause.
137: * PersistentObject passed as parameter used as a factory of objects to be returned.
138: *
139: * @param persistentObject PersistentObject which values and corresponding column names are used to build the where clause
140: * @param controller
141: * @return Collection of persistent objects - never null. If nothing found the one with 0-length is returned.
142: * @throws com.completex.objective.components.persistency.OdalPersistencyException
143: *
144: */
145: Collection select(PersistentObject persistentObject,
146: LifeCycleController controller)
147: throws OdalPersistencyException;
148:
149: /**
150: * Retrieves collection of persistent objects "by example" PersistentObject.
151: * The fields and their values that are set on the object are then joined by "and" into sql where clause.
152: * PersistentObject passed as parameter used as a factory of objects to be returned.
153: *
154: * @param persistentObject PersistentObject which values and corresponding column names are used to build the where clause
155: * @param controller
156: * @param lock
157: * @param timeout Timeout on lock in seconds
158: * @return Collection of persistent objects - never null. If nothing found the one with 0-length is returned.
159: * @throws com.completex.objective.components.persistency.OdalPersistencyException
160: *
161: */
162: Collection select(PersistentObject persistentObject,
163: LifeCycleController controller, LockType lock, long timeout)
164: throws OdalPersistencyException;
165:
166: /**
167: * Retrieves collection of persistent objects "by example" PersistentObject.
168: * The fields and their values that are set on the object are then joined by "and" into sql where clause.
169: * PersistentObject passed as parameter used as a factory of objects to be returned.
170: * Method will wait indefinitely until the records are released if locked by another session
171: * and will lock them upon retieval
172: *
173: * @param persistentObject PersistentObject which values and corresponding column names are used to build the where clause
174: * @return Collection of persistent objects - never null. If nothing found the one with 0-length is returned.
175: * @throws com.completex.objective.components.persistency.OdalPersistencyException
176: *
177: */
178: Collection selectForUpdate(PersistentObject persistentObject)
179: throws OdalPersistencyException;
180:
181: /**
182: * Method will use query object to build exists sql statement.
183: * Concrete implementation may reject query in case sql string is set
184: * externally.
185: *
186: * @param query
187: * @return true if query returns any results
188: * @throws com.completex.objective.components.persistency.OdalPersistencyException
189: *
190: */
191: boolean selectExists(Query query) throws OdalPersistencyException;
192:
193: /**
194: * Method will use persistentObject to build exists sql statement.
195: * Concrete implementation may reject query in case sql string is set
196: * externally.
197: *
198: * @param persistentObject PersistentObject which values and corresponding column names are used to build the where clause
199: * @return true if query returns any results
200: * @throws com.completex.objective.components.persistency.OdalPersistencyException
201: *
202: */
203: boolean selectExists(PersistentObject persistentObject)
204: throws OdalPersistencyException;
205:
206: /**
207: * Method will use query object to build "select count(*)" statement.
208: * Concrete implementation may reject query in case sql string is set
209: * externally.
210: *
211: * @param query
212: * @return count
213: * @throws com.completex.objective.components.persistency.OdalPersistencyException
214: *
215: */
216: long selectCount(Query query) throws OdalPersistencyException;
217:
218: /**
219: * Method will use PersistentObject object to build "select count(*)" statement.
220: *
221: * @param persistentObject PersistentObject which values and corresponding column names are used to build the where clause
222: * @return count
223: * @throws com.completex.objective.components.persistency.OdalPersistencyException
224: *
225: */
226: long selectCount(PersistentObject persistentObject)
227: throws OdalPersistencyException;
228:
229: /**
230: * Retrieves collection of persistent objects "by query" and returns the 1st object.
231: *
232: * @param query
233: * @return 1st object or null if nothing found
234: * @throws com.completex.objective.components.persistency.OdalPersistencyException
235: *
236: */
237: Object selectFirst(Query query) throws OdalPersistencyException;
238:
239: Object selectFirst(final Query query,
240: final LifeCycleController controller)
241: throws OdalPersistencyException;
242:
243: /**
244: * Retrieves collection of persistent objects "by example" and returns the 1st object.
245: *
246: * @param persistentObject PersistentObject which values and corresponding column names are used to build the where clause
247: * @return 1st object or null if nothing found
248: * @throws com.completex.objective.components.persistency.OdalPersistencyException
249: *
250: */
251: Object selectFirst(PersistentObject persistentObject)
252: throws OdalPersistencyException;
253:
254: /**
255: * Retrieves collection of persistent objects "by example" and returns the 1st object.
256: * Method will wait indefinitely until the records are released if locked by another session
257: * and will lock them upon retieval
258: *
259: * @param persistentObject PersistentObject which values and corresponding column names are used to build the where clause
260: * @return 1st object or null if nothing found
261: * @throws com.completex.objective.components.persistency.OdalPersistencyException
262: *
263: */
264: Object selectFirstForUpdate(PersistentObject persistentObject)
265: throws OdalPersistencyException;
266:
267: /**
268: * Method can be used for queries that return single value results
269: *
270: * @param query
271: * @return single value
272: * @throws com.completex.objective.components.persistency.OdalPersistencyException
273: *
274: */
275: Object selectSingle(Query query) throws OdalPersistencyException;
276:
277: /**
278: * Get next sequence using default sequence generator
279: *
280: * @param name of the sequence
281: * @return next sequnce value
282: * @throws com.completex.objective.components.persistency.OdalPersistencyException
283: *
284: */
285: long getNextSeqValue(String name) throws OdalPersistencyException;
286:
287: /**
288: * Execute single result set procedure call
289: *
290: * @param query
291: * @param controller
292: * @return Collection of persistent objects
293: * @throws com.completex.objective.components.persistency.OdalPersistencyException
294: *
295: */
296: Collection selectSinglePartResultCall(Call query,
297: LifeCycleController controller)
298: throws OdalPersistencyException;
299:
300: /**
301: * Execute single result set procedure call
302: *
303: * @param query
304: * @return Collection of persistent objects
305: * @throws com.completex.objective.components.persistency.OdalPersistencyException
306: *
307: */
308: Collection selectSinglePartResultCall(Call query)
309: throws OdalPersistencyException;
310:
311: /**
312: * Execute multi-result set procedure call
313: *
314: * @param query
315: * @param controller
316: * @return Collection of persistent objects
317: * @throws com.completex.objective.components.persistency.OdalPersistencyException
318: *
319: */
320: MultipartCollection selectMultiPartResultCall(Call query,
321: LifeCycleController controller)
322: throws OdalPersistencyException;
323:
324: /**
325: * Execute multi-result set procedure call
326: *
327: * @param query
328: * @return Collection of persistent objects
329: * @throws com.completex.objective.components.persistency.OdalPersistencyException
330: *
331: */
332: MultipartCollection selectMultiPartResultCall(Call query)
333: throws OdalPersistencyException;
334:
335: Object load(PersistentObject persistentObject,
336: LifeCycleController controller)
337: throws OdalPersistencyException;
338:
339: Object load(PersistentObject persistentObject,
340: LifeCycleController controller, LockType lockType,
341: long timeout) throws OdalPersistencyException;
342:
343: Object selectFirst(PersistentObject persistentObject,
344: LifeCycleController controller)
345: throws OdalPersistencyException;
346: }
|