1 /*
2 * Copyright (C) 2003-2012 David E. Berry
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the Free Software
16 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17 *
18 * A copy of the GNU Lesser General Public License may also be found at
19 * http://www.gnu.org/licenses/lgpl.txt
20 */
21 package org.synchronoss.cpo;
22
23 import org.synchronoss.cpo.meta.CpoMetaDescriptor;
24 import org.synchronoss.cpo.meta.domain.CpoAttribute;
25
26 import java.util.*;
27
28 /**
29 * CpoAdapter is an interface for a set of routines that are responsible for Creating, Retrieving, Updating, and
30 * Deleting (CRUD) value objects within a datasource.
31 * <p/>
32 * CpoAdapter is an interface that acts as a common facade for different datasources. It is conceivable that an
33 * CpoAdapter can be implemented for JDBC, CSV, XML, LDAP, and more datasources producing classes such as
34 * JdbcCpoAdapter, CsvCpoAdapter, XmlCpoAdapter, LdapCpoAdapter, etc.
35 *
36 * @author david berry
37 */
38 public interface CpoAdapter extends java.io.Serializable {
39
40 /**
41 * Identifies the operation to be processed by the CPO. CREATE signifies that the CPO will try to add the object to the datasource.
42 */
43 static final int CREATE = 0;
44
45 /**
46 * Identifies the operation to be processed by CPO. INSERT signifies that the CPO will try to add the object to the datasource.
47 */
48 static final int INSERT = 0;
49
50 /**
51 * Identifies the operation to be processed by CPO. UPDATE signifies that the CPO will try to update the object in the datasource.
52 */
53 static final int UPDATE = 1;
54
55 /**
56 * Identifies the operation to be processed by CPO. DELETE signifies that the CPO will try to delete the object in the datasource.
57 */
58 static final int DELETE = 2;
59
60 /**
61 * Identifies the operation to be processed by CPO. RETRIEVE signifies that the CPO will try to retrieve a single object from the datasource.
62 */
63 static final int RETRIEVE = 3;
64
65 /**
66 * Identifies the operation to be processed by CPO. LIST signifies that the CPO will try to retrieve one or more objects from the datasource.
67 */
68 static final int LIST = 4;
69
70 /**
71 * Identifies the operation to be processed by CPO. PERSIST signifies that the CPO will try to add or update the object in the datasource.
72 */
73 static final int PERSIST = 5;
74
75 /**
76 * Identifies the operation to be processed by CPO. EXIST signifies that the CPO will check to see if the object exists in the datasource.
77 */
78 static final int EXIST = 6;
79
80 /**
81 * Identifies the operation to be processed by the CPO. EXECUTE signifies that the CPO will try to execute a function or procedure in the datasource.
82 */
83 static final int EXECUTE = 7;
84
85 /**
86 * Identifies the string constants that goes along with the numeric constants defined above
87 */
88 static final String[] GROUP_IDS = {
89 "CREATE", "UPDATE", "DELETE", "RETRIEVE", "LIST", "PERSIST", "EXIST", "EXECUTE"
90 };
91
92 /**
93 * String constant for CREATE
94 */
95 static final String CREATE_GROUP = GROUP_IDS[CpoAdapter.CREATE];
96
97 /**
98 * String constant for UPDATE
99 */
100 static final String UPDATE_GROUP = GROUP_IDS[CpoAdapter.UPDATE];
101
102 /**
103 * String constant for DELETE
104 */
105 static final String DELETE_GROUP = GROUP_IDS[CpoAdapter.DELETE];
106
107 /**
108 * String constant for RETRIEVE
109 */
110 static final String RETRIEVE_GROUP = GROUP_IDS[CpoAdapter.RETRIEVE];
111
112 /**
113 * String constant for LIST
114 */
115 static final String LIST_GROUP = GROUP_IDS[CpoAdapter.LIST];
116
117 /**
118 * String constant for PERSIST
119 */
120 static final String PERSIST_GROUP = GROUP_IDS[CpoAdapter.PERSIST];
121
122 /**
123 * String constant for EXIST
124 */
125 static final String EXIST_GROUP = GROUP_IDS[CpoAdapter.EXIST];
126
127 /**
128 * String constant for EXECUTE
129 */
130 static final String EXECUTE_GROUP = GROUP_IDS[CpoAdapter.EXECUTE];
131
132 /**
133 * Creates the Object in the datasource. The assumption is that the object does not exist in the datasource. This
134 * method creates and stores the object in the datasource.
135 * <p/>
136 * <pre>Example:
137 * <code>
138 * <p/>
139 * class SomeObject so = new SomeObject();
140 * class CpoAdapter cpo = null;
141 * <p/>
142 * try {
143 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
144 * } catch (CpoException ce) {
145 * // Handle the error
146 * cpo = null;
147 * }
148 * <p/>
149 * if (cpo!=null) {
150 * so.setId(1);
151 * so.setName("SomeName");
152 * try{
153 * cpo.insertObject(so);
154 * } catch (CpoException ce) {
155 * // Handle the error
156 * }
157 * }
158 * </code>
159 * </pre>
160 *
161 * @param obj This is an object that has been defined within the metadata of the datasource. If the class is not
162 * defined an exception will be thrown.
163 * @return The number of objects created in the datasource
164 * @throws CpoException Thrown if there are errors accessing the datasource
165 */
166 public <T> long insertObject(T obj) throws CpoException;
167
168 /**
169 * Creates the Object in the datasource. The assumption is that the object does not exist in the datasource. This
170 * method creates and stores the object in the datasource
171 * <p/>
172 * <pre>Example:
173 * <code>
174 * <p/>
175 * class SomeObject so = new SomeObject();
176 * class CpoAdapter cpo = null;
177 * <p/>
178 * try {
179 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
180 * } catch (CpoException ce) {
181 * // Handle the error
182 * cpo = null;
183 * }
184 * if (cpo!=null) {
185 * so.setId(1);
186 * so.setName("SomeName");
187 * try{
188 * cpo.insertObject("IDNameInsert",so);
189 * } catch (CpoException ce) {
190 * // Handle the error
191 * }
192 * }
193 * </code>
194 * </pre>
195 *
196 * @param name The String name of the CREATE Function Group that will be used to create the object in the datasource.
197 * null signifies that the default rules will be used which is equivalent to insertObject(Object obj);
198 * @param obj This is an object that has been defined within the metadata of the datasource. If the class is not
199 * defined an exception will be thrown.
200 * @return The number of objects created in the datasource
201 * @throws CpoException Thrown if there are errors accessing the datasource
202 */
203 public <T> long insertObject(String name, T obj) throws CpoException;
204
205 /**
206 * Creates the Object in the datasource. The assumption is that the object does not exist in the datasource. This
207 * method creates and stores the object in the datasource
208 * <p/>
209 * <pre>Example:
210 * <code>
211 * <p/>
212 * class SomeObject so = new SomeObject();
213 * class CpoAdapter cpo = null;
214 * <p/>
215 * try {
216 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
217 * } catch (CpoException ce) {
218 * // Handle the error
219 * cpo = null;
220 * }
221 * <p/>
222 * if (cpo!=null) {
223 * so.setId(1);
224 * so.setName("SomeName");
225 * try{
226 * cpo.insertObject("IDNameInsert",so);
227 * } catch (CpoException ce) {
228 * // Handle the error
229 * }
230 * }
231 * </code>
232 * </pre>
233 *
234 * @param name The String name of the CREATE Function Group that will be used to create the object in the datasource.
235 * null signifies that the default rules will be used which is equivalent to insertObject(Object obj);
236 * @param obj This is an object that has been defined within the metadata of the datasource. If the class is not
237 * defined an exception will be thrown.
238 * @param wheres A collection of CpoWhere beans that define the constraints that should be used when retrieving beans
239 * @param orderBy The CpoOrderBy bean that defines the order in which beans should be returned
240 * @param nativeExpressions Native expression that will be used to augment the expression stored in the meta data. This
241 * text will be embedded at run-time
242 * @return The number of objects created in the datasource
243 * @throws CpoException Thrown if there are errors accessing the datasource
244 */
245 public <T> long insertObject(String name, T obj, Collection<CpoWhere> wheres, Collection<CpoOrderBy> orderBy, Collection<CpoNativeFunction> nativeExpressions) throws CpoException;
246
247 /**
248 * Iterates through a collection of Objects, creates and stores them in the datasource. The assumption is that the
249 * objects contained in the collection do not exist in the datasource.
250 * <p/>
251 * This method creates and stores the objects in the datasource. The objects in the collection will be treated as one
252 * transaction, assuming the datasource supports transactions.
253 * <p/>
254 * This means that if one of the objects fail being created in the datasource then the CpoAdapter will stop processing
255 * the remainder of the collection and rollback all the objects created thus far. Rollback is on the underlying
256 * datasource's support of rollback.
257 * <p/>
258 * <pre>Example:
259 * <code>
260 * <p/>
261 * class SomeObject so = null;
262 * class CpoAdapter cpo = null;
263 * <p/>
264 * try {
265 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
266 * } catch (CpoException ce) {
267 * // Handle the error
268 * cpo = null;
269 * }
270 * <p/>
271 * if (cpo!=null) {
272 * ArrayList al = new ArrayList();
273 * for (int i=0; i<3; i++){
274 * so = new SomeObject();
275 * so.setId(1);
276 * so.setName("SomeName");
277 * al.add(so);
278 * }
279 * <p/>
280 * try{
281 * cpo.insertObjects(al);
282 * } catch (CpoException ce) {
283 * // Handle the error
284 * }
285 * }
286 * </code>
287 * </pre>
288 *
289 * @param coll This is a collection of objects that have been defined within the metadata of the datasource. If the
290 * class is not defined an exception will be thrown.
291 * @return The number of objects created in the datasource
292 * @throws CpoException Thrown if there are errors accessing the datasource
293 */
294 public <T> long insertObjects(Collection<T> coll) throws CpoException;
295
296 /**
297 * Iterates through a collection of Objects, creates and stores them in the datasource. The assumption is that the
298 * objects contained in the collection do not exist in the datasource.
299 * <p/>
300 * This method creates and stores the objects in the datasource. The objects in the collection will be treated as one
301 * transaction, assuming the datasource supports transactions.
302 * <p/>
303 * This means that if one of the objects fail being created in the datasource then the CpoAdapter should stop
304 * processing the remainder of the collection, and if supported, rollback all the objects created thus far.
305 * <p/>
306 * <pre>Example:
307 * <code>
308 * <p/>
309 * class SomeObject so = null;
310 * class CpoAdapter cpo = null;
311 * <p/>
312 * <p/>
313 * try {
314 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
315 * } catch (CpoException ce) {
316 * // Handle the error
317 * cpo = null;
318 * }
319 * <p/>
320 * if (cpo!=null) {
321 * ArrayList al = new ArrayList();
322 * for (int i=0; i<3; i++){
323 * so = new SomeObject();
324 * so.setId(1);
325 * so.setName("SomeName");
326 * al.add(so);
327 * }
328 * try{
329 * cpo.insertObjects("IdNameInsert",al);
330 * } catch (CpoException ce) {
331 * // Handle the error
332 * }
333 * }
334 * </code>
335 * </pre>
336 *
337 * @param name The String name of the CREATE Function Group that will be used to create the object in the datasource.
338 * null signifies that the default rules will be used.
339 * @param coll This is a collection of objects that have been defined within the metadata of the datasource. If the
340 * class is not defined an exception will be thrown.
341 * @return The number of objects created in the datasource
342 * @throws CpoException Thrown if there are errors accessing the datasource
343 */
344 public <T> long insertObjects(String name, Collection<T> coll) throws CpoException;
345
346 /**
347 * Iterates through a collection of Objects, creates and stores them in the datasource. The assumption is that the
348 * objects contained in the collection do not exist in the datasource.
349 * <p/>
350 * This method creates and stores the objects in the datasource. The objects in the collection will be treated as one
351 * transaction, assuming the datasource supports transactions.
352 * <p/>
353 * This means that if one of the objects fail being created in the datasource then the CpoAdapter should stop
354 * processing the remainder of the collection, and if supported, rollback all the objects created thus far.
355 * <p/>
356 * <pre>Example:
357 * <code>
358 * <p/>
359 * class SomeObject so = null;
360 * class CpoAdapter cpo = null;
361 * <p/>
362 * try {
363 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
364 * } catch (CpoException ce) {
365 * // Handle the error
366 * cpo = null;
367 * }
368 * if (cpo!=null) {
369 * ArrayList al = new ArrayList();
370 * for (int i=0; i<3; i++){
371 * so = new SomeObject();
372 * so.setId(1);
373 * so.setName("SomeName");
374 * al.add(so);
375 * }
376 * try{
377 * cpo.insertObjects("IdNameInsert",al);
378 * } catch (CpoException ce) {
379 * // Handle the error
380 * }
381 * }
382 * </code>
383 * </pre>
384 *
385 * @param name The String name of the CREATE Function Group that will be used to create the object in the datasource.
386 * null signifies that the default rules will be used.
387 * @param coll This is a collection of objects that have been defined within the metadata of the datasource. If the
388 * class is not defined an exception will be thrown.
389 * @param wheres A collection of CpoWhere beans that define the constraints that should be used when retrieving beans
390 * @param orderBy The CpoOrderBy bean that defines the order in which beans should be returned
391 * @param nativeExpressions Native expression that will be used to augment the expression stored in the meta data. This
392 * text will be embedded at run-time
393 * @return The number of objects created in the datasource
394 * @throws CpoException Thrown if there are errors accessing the datasource
395 */
396 public <T> long insertObjects(String name, Collection<T> coll, Collection<CpoWhere> wheres, Collection<CpoOrderBy> orderBy, Collection<CpoNativeFunction> nativeExpressions) throws CpoException;
397
398 /**
399 * Removes the Object from the datasource. The assumption is that the object exists in the datasource. This method
400 * stores the object in the datasource
401 * <p/>
402 * <pre>Example:
403 * <code>
404 * <p/>
405 * class SomeObject so = new SomeObject();
406 * class CpoAdapter cpo = null;
407 * <p/>
408 * try {
409 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
410 * } catch (CpoException ce) {
411 * // Handle the error
412 * cpo = null;
413 * }
414 * <p/>
415 * if (cpo!=null) {
416 * so.setId(1);
417 * so.setName("SomeName");
418 * try{
419 * cpo.deleteObject(so);
420 * } catch (CpoException ce) {
421 * // Handle the error
422 * }
423 * }
424 * </code>
425 * </pre>
426 *
427 * @param obj This is an object that has been defined within the metadata of the datasource. If the class is not
428 * defined an exception will be thrown. If the object does not exist in the datasource an exception will be thrown.
429 * @return The number of objects deleted from the datasource
430 * @throws CpoException Thrown if there are errors accessing the datasource
431 */
432 public <T> long deleteObject(T obj) throws CpoException;
433
434 /**
435 * Removes the Object from the datasource. The assumption is that the object exists in the datasource. This method
436 * stores the object in the datasource
437 * <p/>
438 * <pre>Example:
439 * <code>
440 * <p/>
441 * class SomeObject so = new SomeObject();
442 * class CpoAdapter cpo = null;
443 * <p/>
444 * try {
445 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
446 * } catch (CpoException ce) {
447 * // Handle the error
448 * cpo = null;
449 * }
450 * <p/>
451 * if (cpo!=null) {
452 * so.setId(1);
453 * so.setName("SomeName");
454 * try{
455 * cpo.deleteObject("DeleteById",so);
456 * } catch (CpoException ce) {
457 * // Handle the error
458 * }
459 * }
460 * </code>
461 * </pre>
462 *
463 * @param name The String name of the DELETE Function Group that will be used to create the object in the datasource.
464 * null signifies that the default rules will be used.
465 * @param obj This is an object that has been defined within the metadata of the datasource. If the class is not
466 * defined an exception will be thrown. If the object does not exist in the datasource an exception will be thrown.
467 * @return The number of objects deleted from the datasource
468 * @throws CpoException Thrown if there are errors accessing the datasource
469 */
470 public <T> long deleteObject(String name, T obj) throws CpoException;
471
472 /**
473 * Removes the Object from the datasource. The assumption is that the object exists in the datasource. This method
474 * stores the object in the datasource
475 * <p/>
476 * <pre>Example:
477 * <code>
478 * <p/>
479 * class SomeObject so = new SomeObject();
480 * class CpoAdapter cpo = null;
481 * <p/>
482 * try {
483 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
484 * } catch (CpoException ce) {
485 * // Handle the error
486 * cpo = null;
487 * }
488 * <p/>
489 * if (cpo!=null) {
490 * so.setId(1);
491 * so.setName("SomeName");
492 * try{
493 * cpo.deleteObject("DeleteById",so);
494 * } catch (CpoException ce) {
495 * // Handle the error
496 * }
497 * }
498 * </code>
499 * </pre>
500 *
501 * @param name The String name of the DELETE Function Group that will be used to create the object in the datasource.
502 * null signifies that the default rules will be used.
503 * @param obj This is an object that has been defined within the metadata of the datasource. If the class is not
504 * defined an exception will be thrown. If the object does not exist in the datasource an exception will be thrown.
505 * @param wheres A collection of CpoWhere beans that define the constraints that should be used when retrieving beans
506 * @param orderBy The CpoOrderBy bean that defines the order in which beans should be returned
507 * @param nativeExpressions Native expression that will be used to augment the expression stored in the meta data. This
508 * text will be embedded at run-time
509 * @return The number of objects deleted from the datasource
510 * @throws CpoException Thrown if there are errors accessing the datasource
511 */
512 public <T> long deleteObject(String name, T obj, Collection<CpoWhere> wheres, Collection<CpoOrderBy> orderBy, Collection<CpoNativeFunction> nativeExpressions) throws CpoException;
513
514 /**
515 * Removes the Objects contained in the collection from the datasource. The assumption is that the object exists in
516 * the datasource. This method stores the objects contained in the collection in the datasource. The objects in the
517 * collection will be treated as one transaction, assuming the datasource supports transactions.
518 * <p/>
519 * This means that if one of the objects fail being deleted in the datasource then the CpoAdapter should stop
520 * processing the remainder of the collection, and if supported, rollback all the objects deleted thus far.
521 * <p/>
522 * <pre>Example:
523 * <code>
524 * <p/>
525 * class SomeObject so = null;
526 * class CpoAdapter cpo = null;
527 * <p/>
528 * try {
529 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
530 * } catch (CpoException ce) {
531 * // Handle the error
532 * cpo = null;
533 * }
534 * <p/>
535 * if (cpo!=null) {
536 * ArrayList al = new ArrayList();
537 * for (int i=0; i<3; i++){
538 * so = new SomeObject();
539 * so.setId(1);
540 * so.setName("SomeName");
541 * al.add(so);
542 * }
543 * <p/>
544 * try{
545 * cpo.deleteObjects(al);
546 * } catch (CpoException ce) {
547 * // Handle the error
548 * }
549 * <p/>
550 * }
551 * </code>
552 * </pre>
553 *
554 * @param coll This is a collection of objects that have been defined within the metadata of the datasource. If the
555 * class is not defined an exception will be thrown.
556 * @return The number of objects deleted from the datasource
557 * @throws CpoException Thrown if there are errors accessing the datasource
558 */
559 public <T> long deleteObjects(Collection<T> coll) throws CpoException;
560
561 /**
562 * Removes the Objects contained in the collection from the datasource. The assumption is that the object exists in
563 * the datasource. This method stores the objects contained in the collection in the datasource. The objects in the
564 * collection will be treated as one transaction, assuming the datasource supports transactions.
565 * <p/>
566 * This means that if one of the objects fail being deleted in the datasource then the CpoAdapter should stop
567 * processing the remainder of the collection, and if supported, rollback all the objects deleted thus far.
568 * <p/>
569 * <pre>Example:
570 * <code>
571 * <p/>
572 * class SomeObject so = null;
573 * class CpoAdapter cpo = null;
574 * <p/>
575 * try {
576 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
577 * } catch (CpoException ce) {
578 * // Handle the error
579 * cpo = null;
580 * }
581 * <p/>
582 * if (cpo!=null) {
583 * ArrayList al = new ArrayList();
584 * for (int i=0; i<3; i++){
585 * so = new SomeObject();
586 * so.setId(1);
587 * so.setName("SomeName");
588 * al.add(so);
589 * }
590 * <p/>
591 * try{
592 * cpo.deleteObjects("IdNameDelete",al);
593 * } catch (CpoException ce) {
594 * // Handle the error
595 * }
596 * <p/>
597 * }
598 * </code>
599 * </pre>
600 *
601 * @param name The String name of the DELETE Function Group that will be used to create the object in the datasource.
602 * null signifies that the default rules will be used.
603 * @param coll This is a collection of objects that have been defined within the metadata of the datasource. If the
604 * class is not defined an exception will be thrown.
605 * @return The number of objects deleted from the datasource
606 * @throws CpoException Thrown if there are errors accessing the datasource
607 */
608 public <T> long deleteObjects(String name, Collection<T> coll) throws CpoException;
609
610 /**
611 * Removes the Objects contained in the collection from the datasource. The assumption is that the object exists in
612 * the datasource. This method stores the objects contained in the collection in the datasource. The objects in the
613 * collection will be treated as one transaction, assuming the datasource supports transactions.
614 * <p/>
615 * This means that if one of the objects fail being deleted in the datasource then the CpoAdapter should stop
616 * processing the remainder of the collection, and if supported, rollback all the objects deleted thus far.
617 * <p/>
618 * <pre>Example:
619 * <code>
620 * <p/>
621 * class SomeObject so = null;
622 * class CpoAdapter cpo = null;
623 * <p/>
624 * try {
625 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
626 * } catch (CpoException ce) {
627 * // Handle the error
628 * cpo = null;
629 * }
630 * <p/>
631 * if (cpo!=null) {
632 * ArrayList al = new ArrayList();
633 * for (int i=0; i<3; i++){
634 * so = new SomeObject();
635 * so.setId(1);
636 * so.setName("SomeName");
637 * al.add(so);
638 * }
639 * <p/>
640 * try{
641 * cpo.deleteObjects("IdNameDelete",al);
642 * } catch (CpoException ce) {
643 * // Handle the error
644 * }
645 * }
646 * </code>
647 * </pre>
648 *
649 * @param name The String name of the DELETE Function Group that will be used to create the object in the datasource.
650 * null signifies that the default rules will be used.
651 * @param coll This is a collection of objects that have been defined within the metadata of the datasource. If the
652 * class is not defined an exception will be thrown.
653 * @param wheres A collection of CpoWhere beans that define the constraints that should be used when retrieving beans
654 * @param orderBy The CpoOrderBy bean that defines the order in which beans should be returned
655 * @param nativeExpressions Native expression that will be used to augment the expression stored in the meta data. This
656 * text will be embedded at run-time
657 * @return The number of objects deleted from the datasource
658 * @throws CpoException Thrown if there are errors accessing the datasource
659 */
660 public <T> long deleteObjects(String name, Collection<T> coll, Collection<CpoWhere> wheres, Collection<CpoOrderBy> orderBy, Collection<CpoNativeFunction> nativeExpressions) throws CpoException;
661
662 /**
663 * Executes an Object whose metadata will call an executable within the datasource. It is assumed that the executable
664 * object exists in the metadatasource. If the executable does not exist, an exception will be thrown.
665 * <p/>
666 * <pre>Example:
667 * <code>
668 * <p/>
669 * class SomeObject so = new SomeObject();
670 * class CpoAdapter cpo = null;
671 * <p/>
672 * try {
673 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
674 * } catch (CpoException ce) {
675 * // Handle the error
676 * cpo = null;
677 * }
678 * <p/>
679 * if (cpo!=null) {
680 * so.setId(1);
681 * so.setName("SomeName");
682 * try{
683 * cpo.executeObject(so);
684 * } catch (CpoException ce) {
685 * // Handle the error
686 * }
687 * }
688 * </code>
689 * </pre>
690 *
691 * @param obj This is an Object that has been defined within the metadata of the datasource. If the class is not
692 * defined an exception will be thrown. If the object does not exist in the datasource, an exception will be thrown.
693 * This object is used to populate the IN parameters used to executed the datasource object.
694 * <p/>
695 * An object of this type will be created and filled with the returned data from the value_object. This newly created
696 * object will be returned from this method.
697 * @return An object populated with the OUT parameters returned from the executable object
698 * @throws CpoException Thrown if there are errors accessing the datasource
699 */
700 public <T> T executeObject(T obj) throws CpoException;
701
702 /**
703 * Executes an Object whose metadata will call an executable within the datasource. It is assumed that the executable
704 * object exists in the metadatasource. If the executable does not exist, an exception will be thrown.
705 * <p/>
706 * <pre>Example:
707 * <code>
708 * <p/>
709 * class SomeObject so = new SomeObject();
710 * class CpoAdapter cpo = null;
711 * <p/>
712 * try {
713 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
714 * } catch (CpoException ce) {
715 * // Handle the error
716 * cpo = null;
717 * }
718 * <p/>
719 * if (cpo!=null) {
720 * so.setId(1);
721 * so.setName("SomeName");
722 * try{
723 * cpo.executeObject("execNotifyProc",so);
724 * } catch (CpoException ce) {
725 * // Handle the error
726 * }
727 * }
728 * </code>
729 * </pre>
730 *
731 * @param name The filter name which tells the datasource which objects should be returned. The name also signifies
732 * what data in the object will be populated.
733 * @param object This is an object that has been defined within the metadata of the datasource. If the class is not
734 * defined an exception will be thrown. If the object does not exist in the datasource, an exception will be thrown.
735 * This object is used to populate the IN parameters used to retrieve the collection of objects. This object defines
736 * the object type that will be returned in the collection and contain the result set data or the OUT Parameters.
737 * @return A result object populate with the OUT parameters
738 * @throws CpoException DOCUMENT ME!
739 */
740 public <T> T executeObject(String name, T object) throws CpoException;
741
742 /**
743 * Executes an Object that represents an executable object within the datasource. It is assumed that the object exists
744 * in the datasource. If the object does not exist, an exception will be thrown
745 * <p/>
746 * <pre>Example:
747 * <code>
748 * <p/>
749 * class SomeObject so = new SomeObject();
750 * class SomeResult sr = new SomeResult();
751 * class CpoAdapter cpo = null;
752 * <p/>
753 * try {
754 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
755 * } catch (CpoException ce) {
756 * // Handle the error
757 * cpo = null;
758 * }
759 * <p/>
760 * if (cpo!=null) {
761 * so.setId(1);
762 * so.setName("SomeName");
763 * try{
764 * sr = (SomeResult)cpo.executeObject("execNotifyProc",so, sr);
765 * } catch (CpoException ce) {
766 * // Handle the error
767 * }
768 * }
769 * </code>
770 * </pre>
771 *
772 * @param name The String name of the EXECUTE Function Group that will be used to create the object in the datasource.
773 * null signifies that the default rules will be used.
774 * @param criteria This is an object that has been defined within the metadata of the datasource. If the class is not
775 * defined an exception will be thrown. If the object does not exist in the datasource, an exception will be thrown.
776 * This object is used to populate the IN parameters used to retrieve the collection of objects.
777 * @param result This is an object that has been defined within the metadata of the datasource. If the class is not
778 * defined an exception will be thrown. If the object does not exist in the datasource, an exception will be thrown.
779 * This object defines the object type that will be created, filled with the return data and returned from this
780 * method.
781 * @return An object populated with the out parameters
782 * @throws CpoException Thrown if there are errors accessing the datasource
783 */
784 public <T, C> T executeObject(String name, C criteria, T result) throws CpoException;
785
786 /**
787 * The CpoAdapter will check to see if this object exists in the datasource.
788 * <p/>
789 * <pre>Example:
790 * <code>
791 * <p/>
792 * class SomeObject so = new SomeObject();
793 * long count = 0;
794 * class CpoAdapter cpo = null;
795 * <p/>
796 * try {
797 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
798 * } catch (CpoException ce) {
799 * // Handle the error
800 * cpo = null;
801 * }
802 * <p/>
803 * if (cpo!=null) {
804 * so.setId(1);
805 * so.setName("SomeName");
806 * try{
807 * count = cpo.existsObject(so);
808 * if (count>0) {
809 * // object exists
810 * } else {
811 * // object does not exist
812 * }
813 * } catch (CpoException ce) {
814 * // Handle the error
815 * }
816 * }
817 * </code>
818 * </pre>
819 *
820 * @param obj This is an object that has been defined within the metadata of the datasource. If the class is not
821 * defined an exception will be thrown. This object will be searched for inside the datasource.
822 * @return The number of objects that exist in the datasource that match the specified object
823 * @throws CpoException Thrown if there are errors accessing the datasource
824 */
825 public <T> long existsObject(T obj) throws CpoException;
826
827 /**
828 * The CpoAdapter will check to see if this object exists in the datasource.
829 * <p/>
830 * <pre>Example:
831 * <code>
832 * <p/>
833 * class SomeObject so = new SomeObject();
834 * long count = 0;
835 * class CpoAdapter cpo = null;
836 * <p/>
837 * <p/>
838 * try {
839 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
840 * } catch (CpoException ce) {
841 * // Handle the error
842 * cpo = null;
843 * }
844 * <p/>
845 * if (cpo!=null) {
846 * so.setId(1);
847 * so.setName("SomeName");
848 * try{
849 * count = cpo.existsObject("SomeExistCheck",so);
850 * if (count>0) {
851 * // object exists
852 * } else {
853 * // object does not exist
854 * }
855 * } catch (CpoException ce) {
856 * // Handle the error
857 * }
858 * }
859 * </code>
860 * </pre>
861 *
862 * @param name The String name of the EXISTS Function Group that will be used to create the object in the datasource.
863 * null signifies that the default rules will be used.
864 * @param obj This is an object that has been defined within the metadata of the datasource. If the class is not
865 * defined an exception will be thrown. This object will be searched for inside the datasource.
866 * @return The number of objects that exist in the datasource that match the specified object
867 * @throws CpoException Thrown if there are errors accessing the datasource
868 */
869 public <T> long existsObject(String name, T obj) throws CpoException;
870
871 /**
872 * The CpoAdapter will check to see if this object exists in the datasource.
873 * <p/>
874 * <pre>Example:
875 * <code>
876 * <p/>
877 * class SomeObject so = new SomeObject();
878 * long count = 0;
879 * class CpoAdapter cpo = null;
880 * <p/>
881 * <p/>
882 * try {
883 * <p/>
884 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
885 * } catch (CpoException ce) {
886 * // Handle the error
887 * cpo = null;
888 * }
889 * <p/>
890 * if (cpo!=null) {
891 * so.setId(1);
892 * so.setName("SomeName");
893 * try{
894 * CpoWhere where = cpo.newCpoWhere(CpoWhere.LOGIC_NONE, id, CpoWhere.COMP_EQ);
895 * count = cpo.existsObject("SomeExistCheck",so, where);
896 * if (count>0) {
897 * // object exists
898 * } else {
899 * // object does not exist
900 * }
901 * } catch (CpoException ce) {
902 * // Handle the error
903 * }
904 * }
905 * </code>
906 * </pre>
907 *
908 * @param name The String name of the EXISTS Function Group that will be used to create the object in the datasource.
909 * null signifies that the default rules will be used.
910 * @param obj This is an object that has been defined within the metadata of the datasource. If the class is not
911 * defined an exception will be thrown. This object will be searched for inside the datasource.
912 * @param wheres A collection of CpoWhere objects that pass in run-time constraints to the function that performs the the
913 * exist
914 * @return The number of objects that exist in the datasource that match the specified object
915 * @throws CpoException Thrown if there are errors accessing the datasource
916 */
917 public <T> long existsObject(String name, T obj, Collection<CpoWhere> wheres) throws CpoException;
918
919 /**
920 * newOrderBy allows you to dynamically change the order of the objects in the resulting collection. This allows you
921 * to apply user input in determining the order of the collection
922 *
923 * @param attribute The name of the attribute from the pojo that will be sorted.
924 * @param ascending If true, sort ascending. If false sort descending.
925 * @return A CpoOrderBy object to be passed into retrieveBeans.
926 * @throws CpoException Thrown if there are errors accessing the datasource
927 */
928 public CpoOrderBy newOrderBy(String attribute, boolean ascending) throws CpoException;
929
930 /**
931 * newOrderBy allows you to dynamically change the order of the objects in the resulting collection. This allows you
932 * to apply user input in determining the order of the collection
933 *
934 * @param marker the marker that will be replaced in the expression with the string representation of this orderBy
935 * @param attribute The name of the attribute from the pojo that will be sorted.
936 * @param ascending If true, sort ascending. If false sort descending.
937 * @return A CpoOrderBy object to be passed into retrieveBeans.
938 * @throws CpoException Thrown if there are errors accessing the datasource
939 */
940 public CpoOrderBy newOrderBy(String marker, String attribute, boolean ascending) throws CpoException;
941
942 /**
943 * newOrderBy allows you to dynamically change the order of the objects in the resulting collection. This allows you
944 * to apply user input in determining the order of the collection
945 *
946 * @param attribute The name of the attribute from the pojo that will be sorted.
947 * @param ascending If true, sort ascending. If false sort descending.
948 * @param function A string which represents a datasource function that will be called on the attribute. must be
949 * contained in the function string. The attribute name will be replaced at run-time with its datasource counterpart
950 * @return A CpoOrderBy object to be passed into retrieveBeans.
951 * @throws CpoException Thrown if there are errors accessing the datasource
952 */
953 public CpoOrderBy newOrderBy(String attribute, boolean ascending, String function) throws CpoException;
954
955 /**
956 * newOrderBy allows you to dynamically change the order of the objects in the resulting collection. This allows you
957 * to apply user input in determining the order of the collection
958 *
959 * @param marker the marker that will be replaced in the expression with the string representation of this orderBy
960 * @param attribute The name of the attribute from the pojo that will be sorted.
961 * @param ascending If true, sort ascending. If false sort descending.
962 * @param function A string which represents a datasource function that will be called on the attribute. must be
963 * contained in the function string. The attribute name will be replaced at run-time with its datasource counterpart
964 * @return A CpoOrderBy object to be passed into retrieveBeans.
965 * @throws CpoException Thrown if there are errors accessing the datasource
966 */
967 public CpoOrderBy newOrderBy(String marker, String attribute, boolean ascending, String function) throws CpoException;
968
969 /**
970 * DOCUMENT ME!
971 *
972 * @return DOCUMENT ME!
973 * @throws CpoException Thrown if there are errors accessing the datasource
974 */
975 public CpoWhere newWhere() throws CpoException;
976
977 /**
978 * DOCUMENT ME!
979 *
980 * @param logical DOCUMENT ME!
981 * @param attr DOCUMENT ME!
982 * @param comp DOCUMENT ME!
983 * @param value DOCUMENT ME!
984 * @return DOCUMENT ME!
985 * @throws CpoException Thrown if there are errors accessing the datasource
986 */
987 public <T> CpoWhere newWhere(int logical, String attr, int comp, T value) throws CpoException;
988
989 /**
990 * DOCUMENT ME!
991 *
992 * @param logical DOCUMENT ME!
993 * @param attr DOCUMENT ME!
994 * @param comp DOCUMENT ME!
995 * @param value DOCUMENT ME!
996 * @param not DOCUMENT ME!
997 * @return DOCUMENT ME!
998 * @throws CpoException Thrown if there are errors accessing the datasource
999 */
1000 public <T> CpoWhere newWhere(int logical, String attr, int comp, T value, boolean not) throws CpoException;
1001
1002 /**
1003 * Persists the Object into the datasource. The CpoAdapter will check to see if this object exists in the datasource.
1004 * If it exists, the object is updated in the datasource If the object does not exist, then it is created in the
1005 * datasource. This method stores the object in the datasource. This method uses the default EXISTS, CREATE, and
1006 * UPDATE Function Groups specified for this object.
1007 * <p/>
1008 * <pre>Example:
1009 * <code>
1010 * <p/>
1011 * class SomeObject so = new SomeObject();
1012 * class CpoAdapter cpo = null;
1013 * <p/>
1014 * try {
1015 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
1016 * } catch (CpoException ce) {
1017 * // Handle the error
1018 * cpo = null;
1019 * }
1020 * <p/>
1021 * if (cpo!=null) {
1022 * so.setId(1);
1023 * so.setName("SomeName");
1024 * try{
1025 * cpo.persistObject(so);
1026 * } catch (CpoException ce) {
1027 * // Handle the error
1028 * }
1029 * }
1030 * </code>
1031 * </pre>
1032 *
1033 * @param obj This is an object that has been defined within the metadata of the datasource. If the class is not
1034 * defined an exception will be thrown.
1035 * @return A count of the number of objects persisted
1036 * @throws CpoException Thrown if there are errors accessing the datasource
1037 * @see #existsObject
1038 * @see #insertObject
1039 * @see #updateObject
1040 */
1041 public <T> long persistObject(T obj) throws CpoException;
1042
1043 /**
1044 * Persists the Object into the datasource. The CpoAdapter will check to see if this object exists in the datasource.
1045 * If it exists, the object is updated in the datasource If the object does not exist, then it is created in the
1046 * datasource. This method stores the object in the datasource.
1047 * <p/>
1048 * <pre>Example:
1049 * <code>
1050 * <p/>
1051 * class SomeObject so = new SomeObject();
1052 * class CpoAdapter cpo = null;
1053 * <p/>
1054 * try {
1055 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
1056 * } catch (CpoException ce) {
1057 * // Handle the error
1058 * cpo = null;
1059 * }
1060 * <p/>
1061 * if (cpo!=null) {
1062 * so.setId(1);
1063 * so.setName("SomeName");
1064 * try{
1065 * cpo.persistObject("persistSomeObject",so);
1066 * } catch (CpoException ce) {
1067 * // Handle the error
1068 * }
1069 * }
1070 * </code>
1071 * </pre>
1072 *
1073 * @param name The name which identifies which EXISTS, INSERT, and UPDATE Function Groups to execute to persist the
1074 * object.
1075 * @param obj This is an object that has been defined within the metadata of the datasource. If the class is not
1076 * defined an exception will be thrown.
1077 * @return A count of the number of objects persisted
1078 * @throws CpoException Thrown if there are errors accessing the datasource
1079 * @see #existsObject
1080 * @see #insertObject
1081 * @see #updateObject
1082 */
1083 public <T> long persistObject(String name, T obj) throws CpoException;
1084
1085 /**
1086 * Persists a collection of Objects into the datasource. The CpoAdapter will check to see if this object exists in the
1087 * datasource. If it exists, the object is updated in the datasource If the object does not exist, then it is created
1088 * in the datasource. This method stores the object in the datasource. The objects in the collection will be treated
1089 * as one transaction, meaning that if one of the objects fail being inserted or updated in the datasource then the
1090 * entire collection will be rolled back.
1091 * <p/>
1092 * <pre>Example:
1093 * <code>
1094 * <p/>
1095 * class SomeObject so = null;
1096 * class CpoAdapter cpo = null;
1097 * <p/>
1098 * try {
1099 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
1100 * } catch (CpoException ce) {
1101 * // Handle the error
1102 * cpo = null;
1103 * }
1104 * <p/>
1105 * if (cpo!=null) {
1106 * ArrayList al = new ArrayList();
1107 * for (int i=0; i<3; i++){
1108 * so = new SomeObject();
1109 * so.setId(1);
1110 * so.setName("SomeName");
1111 * al.add(so);
1112 * }
1113 * try{
1114 * cpo.persistObjects(al);
1115 * } catch (CpoException ce) {
1116 * // Handle the error
1117 * }
1118 * }
1119 * </code>
1120 * </pre>
1121 *
1122 * @param coll This is a collection of objects that have been defined within the metadata of the datasource. If the
1123 * class is not defined an exception will be thrown.
1124 * @return DOCUMENT ME!
1125 * @throws CpoException Thrown if there are errors accessing the datasource
1126 * @see #existsObject
1127 * @see #insertObject
1128 * @see #updateObject
1129 */
1130 public <T> long persistObjects(Collection<T> coll) throws CpoException;
1131
1132 /**
1133 * Persists a collection of Objects into the datasource. The CpoAdapter will check to see if this object exists in the
1134 * datasource. If it exists, the object is updated in the datasource If the object does not exist, then it is created
1135 * in the datasource. This method stores the object in the datasource. The objects in the collection will be treated
1136 * as one transaction, meaning that if one of the objects fail being inserted or updated in the datasource then the
1137 * entire collection will be rolled back.
1138 * <p/>
1139 * <pre>Example:
1140 * <code>
1141 * <p/>
1142 * class SomeObject so = null;
1143 * class CpoAdapter cpo = null;
1144 * <p/>
1145 * try {
1146 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
1147 * } catch (CpoException ce) {
1148 * // Handle the error
1149 * cpo = null;
1150 * }
1151 * <p/>
1152 * if (cpo!=null) {
1153 * ArrayList al = new ArrayList();
1154 * for (int i=0; i<3; i++){
1155 * so = new SomeObject();
1156 * so.setId(1);
1157 * so.setName("SomeName");
1158 * al.add(so);
1159 * }
1160 * <p/>
1161 * try{
1162 * cpo.persistObjects("myPersist",al);
1163 * } catch (CpoException ce) {
1164 * // Handle the error
1165 * }
1166 * }
1167 * </code>
1168 * </pre>
1169 *
1170 * @param name The name which identifies which EXISTS, INSERT, and UPDATE Function Groups to execute to persist the
1171 * object.
1172 * @param coll This is a collection of objects that have been defined within the metadata of the datasource. If the
1173 * class is not defined an exception will be thrown.
1174 * @return DOCUMENT ME!
1175 * @throws CpoException Thrown if there are errors accessing the datasource
1176 * @see #existsObject
1177 * @see #insertObject
1178 * @see #updateObject
1179 */
1180 public <T> long persistObjects(String name, Collection<T> coll) throws CpoException;
1181
1182 /**
1183 * Retrieves the Bean from the datasource. The assumption is that the bean exists in the datasource. If the retrieve
1184 * function defined for these beans returns more than one row, an exception will be thrown.
1185 *
1186 * @param bean This is a bean that has been defined within the metadata of the datasource. If the class is not defined
1187 * an exception will be thrown. If the bean does not exist in the datasource, an exception will be thrown. The input
1188 * bean is used to specify the search criteria, the output bean is populated with the results of the function.
1189 * @return A bean of the same type as the result parameter that is filled in as specified the metadata for the
1190 * retireve.
1191 * @throws CpoException Thrown if there are errors accessing the datasource
1192 */
1193 public <T> T retrieveBean(T bean) throws CpoException;
1194
1195 /**
1196 * Retrieves the bean from the datasource. The assumption is that the bean exists in the datasource. If the retrieve
1197 * function defined for this beans returns more than one row, an exception will be thrown.
1198 *
1199 * @param name DOCUMENT ME!
1200 * @param bean This is an bean that has been defined within the metadata of the datasource. If the class is not
1201 * defined an exception will be thrown. If the bean does not exist in the datasource, an exception will be thrown. The
1202 * input bean is used to specify the search criteria, the output bean is populated with the results of the function.
1203 * @return An bean of the same type as the result parameter that is filled in as specified the metadata for the
1204 * retireve.
1205 * @throws CpoException Thrown if there are errors accessing the datasource
1206 */
1207 public <T> T retrieveBean(String name, T bean) throws CpoException;
1208
1209 /**
1210 * Retrieves the bean from the datasource. The assumption is that the bean exists in the datasource. If the retrieve
1211 * function defined for this beans returns more than one row, an exception will be thrown.
1212 *
1213 * @param name DOCUMENT ME!
1214 * @param bean This is an bean that has been defined within the metadata of the datasource. If the class is not
1215 * defined an exception will be thrown. If the bean does not exist in the datasource, an exception will be thrown. The
1216 * input bean is used to specify the search criteria, the output bean is populated with the results of the function.
1217 * @param wheres A collection of CpoWhere beans that define the constraints that should be used when retrieving beans
1218 * @param orderBy The CpoOrderBy bean that defines the order in which beans should be returned
1219 * @param nativeExpressions Native expression that will be used to augment the expression stored in the meta data. This
1220 * text will be embedded at run-time
1221 * @return An bean of the same type as the result parameter that is filled in as specified the metadata for the
1222 * retireve.
1223 * @throws CpoException Thrown if there are errors accessing the datasource
1224 */
1225 public <T> T retrieveBean(String name, T bean, Collection<CpoWhere> wheres, Collection<CpoOrderBy> orderBy, Collection<CpoNativeFunction> nativeExpressions) throws CpoException;
1226
1227 /**
1228 * Retrieves the bean from the datasource. The assumption is that the bean exists in the datasource. If the retrieve
1229 * function defined for this beans returns more than one row, an exception will be thrown.
1230 *
1231 * @param name The filter name which tells the datasource which beans should be returned. The name also signifies what
1232 * data in the bean will be populated.
1233 * @param criteria This is an bean that has been defined within the metadata of the datasource. If the class is not
1234 * defined an exception will be thrown. If the bean does not exist in the datasource, an exception will be thrown.
1235 * This bean is used to specify the parameters used to retrieve the collection of beans.
1236 * @param result This is an bean that has been defined within the metadata of the datasource. If the class is not
1237 * defined an exception will be thrown. If the bean does not exist in the datasource, an exception will be thrown.
1238 * This bean is used to specify the bean type that will be returned in the collection.
1239 * @param wheres A collection of CpoWhere beans that define the constraints that should be used when retrieving beans
1240 * @param orderBy The CpoOrderBy bean that defines the order in which beans should be returned
1241 * @return An bean of the same type as the result parameter that is filled in as specified the metadata for the
1242 * retireve.
1243 * @throws CpoException Thrown if there are errors accessing the datasource
1244 */
1245 public <T, C> T retrieveBean(String name, C criteria, T result, Collection<CpoWhere> wheres, Collection<CpoOrderBy> orderBy) throws CpoException;
1246
1247 /**
1248 * Retrieves the bean from the datasource. The assumption is that the bean exists in the datasource. If the retrieve
1249 * function defined for this beans returns more than one row, an exception will be thrown.
1250 *
1251 * @param name The filter name which tells the datasource which beans should be returned. The name also signifies what
1252 * data in the bean will be populated.
1253 * @param criteria This is an bean that has been defined within the metadata of the datasource. If the class is not
1254 * defined an exception will be thrown. If the bean does not exist in the datasource, an exception will be thrown.
1255 * This bean is used to specify the parameters used to retrieve the collection of beans.
1256 * @param result This is an bean that has been defined within the metadata of the datasource. If the class is not
1257 * defined an exception will be thrown. If the bean does not exist in the datasource, an exception will be thrown.
1258 * This bean is used to specify the bean type that will be returned in the collection.
1259 * @param wheres A collection of CpoWhere beans that define the constraints that should be used when retrieving beans
1260 * @param orderBy The CpoOrderBy bean that defines the order in which beans should be returned
1261 * @param nativeExpressions Native expression that will be used to augment the expression stored in the meta data. This
1262 * text will be embedded at run-time
1263 * @return An bean of the same type as the result parameter that is filled in as specified the metadata for the
1264 * retireve.
1265 * @throws CpoException Thrown if there are errors accessing the datasource
1266 */
1267 public <T, C> T retrieveBean(String name, C criteria, T result, Collection<CpoWhere> wheres, Collection<CpoOrderBy> orderBy, Collection<CpoNativeFunction> nativeExpressions) throws CpoException;
1268
1269 /**
1270 * Retrieves the bean from the datasource. The assumption is that the bean exists in the datasource.
1271 *
1272 * @param name The filter name which tells the datasource which beans should be returned. The name also signifies what
1273 * data in the bean will be populated.
1274 * @param criteria This is an bean that has been defined within the metadata of the datasource. If the class is not
1275 * defined an exception will be thrown. If the bean does not exist in the datasource, an exception will be thrown.
1276 * This bean is used to specify the parameters used to retrieve the collection of beans.
1277 * @return A collection of beans will be returned that meet the criteria specified by obj. The beans will be of the
1278 * same type as the bean that was passed in. If no beans match the criteria, an empty collection will be returned
1279 * @throws CpoException Thrown if there are errors accessing the datasource
1280 */
1281 public <C> List<C> retrieveBeans(String name, C criteria) throws CpoException;
1282
1283 /**
1284 * Retrieves the bean from the datasource. The assumption is that the bean exists in the datasource.
1285 *
1286 * @param name The filter name which tells the datasource which beans should be returned. The name also signifies what
1287 * data in the bean will be populated.
1288 * @param criteria This is an bean that has been defined within the metadata of the datasource. If the class is not
1289 * defined an exception will be thrown. If the bean does not exist in the datasource, an exception will be thrown.
1290 * This bean is used to specify the parameters used to retrieve the collection of beans.
1291 * @param where A CpoWhere bean that defines the constraints that should be used when retrieving beans
1292 * @param orderBy The CpoOrderBy bean that defines the order in which beans should be returned
1293 * @return A collection of beans will be returned that meet the criteria specified by obj. The beans will be of the
1294 * same type as the bean that was passed in. If no beans match the criteria, an empty collection will be returned
1295 * @throws CpoException Thrown if there are errors accessing the datasource
1296 */
1297 public <C> List<C> retrieveBeans(String name, C criteria, CpoWhere where, Collection<CpoOrderBy> orderBy) throws CpoException;
1298
1299 /**
1300 * Retrieves the bean from the datasource. The assumption is that the bean exists in the datasource.
1301 *
1302 * @param name The filter name which tells the datasource which beans should be returned. The name also signifies what
1303 * data in the bean will be populated.
1304 * @param criteria This is an bean that has been defined within the metadata of the datasource. If the class is not
1305 * defined an exception will be thrown. If the bean does not exist in the datasource, an exception will be thrown.
1306 * This bean is used to specify the parameters used to retrieve the collection of beans.
1307 * @param orderBy The CpoOrderBy bean that defines the order in which beans should be returned
1308 * @return A collection of beans will be returned that meet the criteria specified by obj. The beans will be of the
1309 * same type as the bean that was passed in. If no beans match the criteria, an empty collection will be returned
1310 * @throws CpoException Thrown if there are errors accessing the datasource
1311 */
1312 public <C> List<C> retrieveBeans(String name, C criteria, Collection<CpoOrderBy> orderBy) throws CpoException;
1313
1314 /**
1315 * Retrieves the bean from the datasource. The assumption is that the bean exists in the datasource.
1316 *
1317 * @param name The filter name which tells the datasource which beans should be returned. The name also signifies what
1318 * data in the bean will be populated.
1319 * @param criteria This is an bean that has been defined within the metadata of the datasource. If the class is not
1320 * defined an exception will be thrown. If the bean does not exist in the datasource, an exception will be thrown.
1321 * This bean is used to specify the parameters used to retrieve the collection of beans.
1322 * @param wheres A collection of CpoWhere beans that define the constraints that should be used when retrieving beans
1323 * @param orderBy The CpoOrderBy bean that defines the order in which beans should be returned
1324 * @return A collection of beans will be returned that meet the criteria specified by obj. The beans will be of the
1325 * same type as the bean that was passed in. If no beans match the criteria, an empty collection will be returned
1326 * @throws CpoException Thrown if there are errors accessing the datasource
1327 */
1328 public <C> List<C> retrieveBeans(String name, C criteria, Collection<CpoWhere> wheres, Collection<CpoOrderBy> orderBy) throws CpoException;
1329
1330 /**
1331 * Retrieves the bean from the datasource. The assumption is that the bean exists in the datasource.
1332 *
1333 * @param name The filter name which tells the datasource which beans should be returned. The name also signifies what
1334 * data in the bean will be populated.
1335 * @param criteria This is an bean that has been defined within the metadata of the datasource. If the class is not
1336 * defined an exception will be thrown. If the bean does not exist in the datasource, an exception will be thrown.
1337 * This bean is used to specify the parameters used to retrieve the collection of beans.
1338 * @param result This is an bean that has been defined within the metadata of the datasource. If the class is not
1339 * defined an exception will be thrown. If the bean does not exist in the datasource, an exception will be thrown.
1340 * This bean is used to specify the bean type that will be returned in the collection.
1341 * @return A collection of beans will be returned that meet the criteria specified by obj. The beans will be of the
1342 * same type as the bean that was passed in. If no beans match the criteria, an empty collection will be returned
1343 * @throws CpoException Thrown if there are errors accessing the datasource
1344 */
1345 public <T, C> List<T> retrieveBeans(String name, C criteria, T result) throws CpoException;
1346
1347 /**
1348 * Retrieves the bean from the datasource. The assumption is that the bean exists in the datasource.
1349 *
1350 * @param name The filter name which tells the datasource which beans should be returned. The name also signifies what
1351 * data in the bean will be populated.
1352 * @param criteria This is an bean that has been defined within the metadata of the datasource. If the class is not
1353 * defined an exception will be thrown. If the bean does not exist in the datasource, an exception will be thrown.
1354 * This bean is used to specify the parameters used to retrieve the collection of beans.
1355 * @param result This is an bean that has been defined within the metadata of the datasource. If the class is not
1356 * defined an exception will be thrown. If the bean does not exist in the datasource, an exception will be thrown.
1357 * This bean is used to specify the bean type that will be returned in the collection.
1358 * @param where A CpoWhere bean that defines the constraints that should be used when retrieving beans
1359 * @param orderBy The CpoOrderBy bean that defines the order in which beans should be returned
1360 * @return A collection of beans will be returned that meet the criteria specified by obj. The beans will be of the
1361 * same type as the bean that was passed in. If no beans match the criteria, an empty collection will be returned
1362 * @throws CpoException Thrown if there are errors accessing the datasource
1363 */
1364 public <T, C> List<T> retrieveBeans(String name, C criteria, T result, CpoWhere where, Collection<CpoOrderBy> orderBy) throws CpoException;
1365
1366 /**
1367 * Retrieves the bean from the datasource. The assumption is that the bean exists in the datasource.
1368 *
1369 * @param name The filter name which tells the datasource which beans should be returned. The name also signifies what
1370 * data in the bean will be populated.
1371 * @param criteria This is an bean that has been defined within the metadata of the datasource. If the class is not
1372 * defined an exception will be thrown. If the bean does not exist in the datasource, an exception will be thrown.
1373 * This bean is used to specify the parameters used to retrieve the collection of beans.
1374 * @param result This is an bean that has been defined within the metadata of the datasource. If the class is not
1375 * defined an exception will be thrown. If the bean does not exist in the datasource, an exception will be thrown.
1376 * This bean is used to specify the bean type that will be returned in the collection.
1377 * @param wheres A collection of CpoWhere beans that define the constraints that should be used when retrieving beans
1378 * @param orderBy The CpoOrderBy bean that defines the order in which beans should be returned
1379 * @return A collection of beans will be returned that meet the criteria specified by obj. The beans will be of the
1380 * same type as the bean that was passed in. If no beans match the criteria, an empty collection will be returned
1381 * @throws CpoException Thrown if there are errors accessing the datasource
1382 */
1383 public <T, C> List<T> retrieveBeans(String name, C criteria, T result, Collection<CpoWhere> wheres, Collection<CpoOrderBy> orderBy) throws CpoException;
1384
1385 /**
1386 * Retrieves the bean from the datasource. The assumption is that the bean exists in the datasource.
1387 *
1388 * @param name The filter name which tells the datasource which beans should be returned. The name also signifies what
1389 * data in the bean will be populated.
1390 * @param criteria This is an bean that has been defined within the metadata of the datasource. If the class is not
1391 * defined an exception will be thrown. If the bean does not exist in the datasource, an exception will be thrown.
1392 * This bean is used to specify the parameters used to retrieve the collection of beans.
1393 * @param result This is an bean that has been defined within the metadata of the datasource. If the class is not
1394 * defined an exception will be thrown. If the bean does not exist in the datasource, an exception will be thrown.
1395 * This bean is used to specify the bean type that will be returned in the collection.
1396 * @param wheres A collection of CpoWhere beans that define the constraints that should be used when retrieving beans
1397 * @param orderBy The CpoOrderBy bean that defines the order in which beans should be returned
1398 * @param nativeExpressions Native expression that will be used to augment the expression stored in the meta data. This
1399 * text will be embedded at run-time
1400 * @return A collection of beans will be returned that meet the criteria specified by obj. The beans will be of the
1401 * same type as the bean that was passed in. If no beans match the criteria, an empty collection will be returned
1402 * @throws CpoException Thrown if there are errors accessing the datasource
1403 */
1404 public <T, C> List<T> retrieveBeans(String name, C criteria, T result, Collection<CpoWhere> wheres, Collection<CpoOrderBy> orderBy, Collection<CpoNativeFunction> nativeExpressions) throws CpoException;
1405
1406 /**
1407 * Retrieves the bean from the datasource. The assumption is that the bean exists in the datasource.
1408 *
1409 * @param name The filter name which tells the datasource which beans should be returned. The name also signifies what
1410 * data in the bean will be populated.
1411 * @param criteria This is an bean that has been defined within the metadata of the datasource. If the class is not
1412 * defined an exception will be thrown. If the bean does not exist in the datasource, an exception will be thrown.
1413 * This bean is used to specify the parameters used to retrieve the collection of beans.
1414 * @param result This is an bean that has been defined within the metadata of the datasource. If the class is not
1415 * defined an exception will be thrown. If the bean does not exist in the datasource, an exception will be thrown.
1416 * This bean is used to specify the bean type that will be returned in the collection.
1417 * @param wheres A collection of CpoWhere beans that define the constraints that should be used when retrieving beans
1418 * @param orderBy The CpoOrderBy bean that defines the order in which beans should be returned
1419 * @param nativeExpressions Native expression that will be used to augment the expression stored in the meta data. This
1420 * text will be embedded at run-time
1421 * @param queueSize queue size of the buffer that it uses to send the beans from the producer to the consumer.
1422 * @return A CpoResultSet that can be iterated through
1423 * @throws CpoException Thrown if there are errors accessing the datasource
1424 */
1425 public <T, C> CpoResultSet<T> retrieveBeans(String name, C criteria, T result, Collection<CpoWhere> wheres, Collection<CpoOrderBy> orderBy, Collection<CpoNativeFunction> nativeExpressions, int queueSize) throws CpoException;
1426
1427 /**
1428 * Update the Object in the datasource. The CpoAdapter will check to see if the object exists in the datasource. If it
1429 * exists then the object will be updated. If it does not exist, an exception will be thrown
1430 * <p/>
1431 * <pre>Example:
1432 * <code>
1433 * <p/>
1434 * class SomeObject so = new SomeObject();
1435 * class CpoAdapter cpo = null;
1436 * <p/>
1437 * try {
1438 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
1439 * } catch (CpoException ce) {
1440 * // Handle the error
1441 * cpo = null;
1442 * }
1443 * <p/>
1444 * if (cpo!=null) {
1445 * so.setId(1);
1446 * so.setName("SomeName");
1447 * try{
1448 * cpo.updateObject(so);
1449 * } catch (CpoException ce) {
1450 * // Handle the error
1451 * }
1452 * }
1453 * </code>
1454 * </pre>
1455 *
1456 * @param obj This is an object that has been defined within the metadata of the datasource. If the class is not
1457 * defined an exception will be thrown.
1458 * @return The number of objects updated in the datasource
1459 * @throws CpoException Thrown if there are errors accessing the datasource
1460 */
1461 public <T> long updateObject(T obj) throws CpoException;
1462
1463 /**
1464 * Update the Object in the datasource. The CpoAdapter will check to see if the object exists in the datasource. If it
1465 * exists then the object will be updated. If it does not exist, an exception will be thrown
1466 * <p/>
1467 * <pre>Example:
1468 * <code>
1469 * <p/>
1470 * class SomeObject so = new SomeObject();
1471 * class CpoAdapter cpo = null;
1472 * <p/>
1473 * try {
1474 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
1475 * } catch (CpoException ce) {
1476 * // Handle the error
1477 * cpo = null;
1478 * }
1479 * <p/>
1480 * if (cpo!=null) {
1481 * so.setId(1);
1482 * so.setName("SomeName");
1483 * try{
1484 * cpo.updateObject("updateSomeObject",so);
1485 * } catch (CpoException ce) {
1486 * // Handle the error
1487 * }
1488 * }
1489 * </code>
1490 * </pre>
1491 *
1492 * @param name The String name of the UPDATE Function Group that will be used to create the object in the datasource.
1493 * null signifies that the default rules will be used.
1494 * @param obj This is an object that has been defined within the metadata of the datasource. If the class is not
1495 * defined an exception will be thrown.
1496 * @return The number of objects updated in the datasource
1497 * @throws CpoException Thrown if there are errors accessing the datasource
1498 */
1499 public <T> long updateObject(String name, T obj) throws CpoException;
1500
1501 /**
1502 * Update the Object in the datasource. The CpoAdapter will check to see if the object exists in the datasource. If it
1503 * exists then the object will be updated. If it does not exist, an exception will be thrown
1504 * <p/>
1505 * <pre>Example:
1506 * <code>
1507 * <p/>
1508 * class SomeObject so = new SomeObject();
1509 * class CpoAdapter cpo = null;
1510 * <p/>
1511 * try {
1512 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
1513 * } catch (CpoException ce) {
1514 * // Handle the error
1515 * cpo = null;
1516 * }
1517 * <p/>
1518 * if (cpo!=null) {
1519 * so.setId(1);
1520 * so.setName("SomeName");
1521 * try{
1522 * cpo.updateObject("updateSomeObject",so);
1523 * } catch (CpoException ce) {
1524 * // Handle the error
1525 * }
1526 * }
1527 * </code>
1528 * </pre>
1529 *
1530 * @param name The String name of the UPDATE Function Group that will be used to create the object in the datasource.
1531 * null signifies that the default rules will be used.
1532 * @param obj This is an object that has been defined within the metadata of the datasource. If the class is not
1533 * defined an exception will be thrown.
1534 * @param wheres A collection of CpoWhere objects to be used by the function
1535 * @param orderBy A collection of CpoOrderBy objects to be used by the function
1536 * @param nativeExpressions A collection of CpoNativeFunction objects to be used by the function
1537 * @return The number of objects updated in the datasource
1538 * @throws CpoException Thrown if there are errors accessing the datasource
1539 */
1540 public <T> long updateObject(String name, T obj, Collection<CpoWhere> wheres, Collection<CpoOrderBy> orderBy, Collection<CpoNativeFunction> nativeExpressions) throws CpoException;
1541
1542 /**
1543 * Updates a collection of Objects in the datasource. The assumption is that the objects contained in the collection
1544 * exist in the datasource. This method stores the object in the datasource. The objects in the collection will be
1545 * treated as one transaction, meaning that if one of the objects fail being updated in the datasource then the entire
1546 * collection will be rolled back, if supported by the datasource.
1547 * <p/>
1548 * <pre>Example:
1549 * <code>
1550 * <p/>
1551 * class SomeObject so = null;
1552 * class CpoAdapter cpo = null;
1553 * <p/>
1554 * try {
1555 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
1556 * } catch (CpoException ce) {
1557 * // Handle the error
1558 * cpo = null;
1559 * }
1560 * <p/>
1561 * if (cpo!=null) {
1562 * ArrayList al = new ArrayList();
1563 * for (int i=0; i<3; i++){
1564 * so = new SomeObject();
1565 * so.setId(1);
1566 * so.setName("SomeName");
1567 * al.add(so);
1568 * }
1569 * <p/>
1570 * try{
1571 * cpo.updateObjects(al);
1572 * } catch (CpoException ce) {
1573 * // Handle the error
1574 * }
1575 * }
1576 * </code>
1577 * </pre>
1578 *
1579 * @param coll This is a collection of objects that have been defined within the metadata of the datasource. If the
1580 * class is not defined an exception will be thrown.
1581 * @return The number of objects updated in the datasource
1582 * @throws CpoException Thrown if there are errors accessing the datasource
1583 */
1584 public <T> long updateObjects(Collection<T> coll) throws CpoException;
1585
1586 /**
1587 * Updates a collection of Objects in the datasource. The assumption is that the objects contained in the collection
1588 * exist in the datasource. This method stores the object in the datasource. The objects in the collection will be
1589 * treated as one transaction, meaning that if one of the objects fail being updated in the datasource then the entire
1590 * collection will be rolled back, if supported by the datasource.
1591 * <p/>
1592 * <pre>Example:
1593 * <code>
1594 * <p/>
1595 * class SomeObject so = null;
1596 * class CpoAdapter cpo = null;
1597 * <p/>
1598 * <p/>
1599 * try {
1600 * <p/>
1601 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
1602 * <p/>
1603 * } catch (CpoException ce) {
1604 * <p/>
1605 * // Handle the error
1606 * cpo = null;
1607 * <p/>
1608 * }
1609 * <p/>
1610 * if (cpo!=null) {
1611 * <p/>
1612 * ArrayList al = new ArrayList();
1613 * for (int i=0; i<3; i++){
1614 * <p/>
1615 * so = new SomeObject();
1616 * so.setId(1);
1617 * so.setName("SomeName");
1618 * al.add(so);
1619 * }
1620 * <p/>
1621 * try{
1622 * <p/>
1623 * cpo.updateObjects("myUpdate",al);
1624 * <p/>
1625 * } catch (CpoException ce) {
1626 * <p/>
1627 * // Handle the error
1628 * <p/>
1629 * }
1630 * <p/>
1631 * }
1632 * </code>
1633 * </pre>
1634 *
1635 * @param name The String name of the UPDATE Function Group that will be used to create the object in the datasource.
1636 * null signifies that the default rules will be used.
1637 * @param coll This is a collection of objects that have been defined within the metadata of the datasource. If the
1638 * class is not defined an exception will be thrown.
1639 * @return The number of objects updated in the datasource
1640 * @throws CpoException Thrown if there are errors accessing the datasource
1641 */
1642 public <T> long updateObjects(String name, Collection<T> coll) throws CpoException;
1643
1644 /**
1645 * Updates a collection of Objects in the datasource. The assumption is that the objects contained in the collection
1646 * exist in the datasource. This method stores the object in the datasource. The objects in the collection will be
1647 * treated as one transaction, meaning that if one of the objects fail being updated in the datasource then the entire
1648 * collection will be rolled back, if supported by the datasource.
1649 * <p/>
1650 * <pre>Example:
1651 * <code>
1652 * <p/>
1653 * class SomeObject so = null;
1654 * class CpoAdapter cpo = null;
1655 * <p/>
1656 * try {
1657 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
1658 * } catch (CpoException ce) {
1659 * // Handle the error
1660 * cpo = null;
1661 * }
1662 * <p/>
1663 * if (cpo!=null) {
1664 * ArrayList al = new ArrayList();
1665 * for (int i=0; i<3; i++){
1666 * so = new SomeObject();
1667 * so.setId(1);
1668 * so.setName("SomeName");
1669 * al.add(so);
1670 * }
1671 * try{
1672 * cpo.updateObjects("myUpdate",al);
1673 * } catch (CpoException ce) {
1674 * // Handle the error
1675 * }
1676 * }
1677 * </code>
1678 * </pre>
1679 *
1680 * @param name The String name of the UPDATE Function Group that will be used to create the object in the datasource.
1681 * null signifies that the default rules will be used.
1682 * @param coll This is a collection of objects that have been defined within the metadata of the datasource. If the
1683 * class is not defined an exception will be thrown.
1684 * @param wheres A collection of CpoWhere objects to be used by the function
1685 * @param orderBy A collection of CpoOrderBy objects to be used by the function
1686 * @param nativeExpressions A collection of CpoNativeFunction objects to be used by the function
1687 * @return The number of objects updated in the datasource
1688 * @throws CpoException Thrown if there are errors accessing the datasource
1689 */
1690 public <T> long updateObjects(String name, Collection<T> coll, Collection<CpoWhere> wheres, Collection<CpoOrderBy> orderBy, Collection<CpoNativeFunction> nativeExpressions) throws CpoException;
1691
1692 /**
1693 * Provides a mechanism for the user to obtain a CpoTrxAdapter object. This object allows the to control when commits
1694 * and rollbacks occur on CPO.
1695 * <p/>
1696 * <p/>
1697 * <pre>Example:
1698 * <code>
1699 * <p/>
1700 * class SomeObject so = null;
1701 * class CpoAdapter cpo = null;
1702 * class CpoTrxAdapter cpoTrx = null;
1703 * <p/>
1704 * try {
1705 * cpo = new JdbcCpoAdapter(new JdbcDataSourceInfo(driver, url, user, password,1,1,false));
1706 * cpoTrx = cpo.getCpoTrxAdapter();
1707 * } catch (CpoException ce) {
1708 * // Handle the error
1709 * cpo = null;
1710 * }
1711 * <p/>
1712 * if (cpo!=null) {
1713 * try{
1714 * for (int i=0; i<3; i++){
1715 * so = new SomeObject();
1716 * so.setId(1);
1717 * so.setName("SomeName");
1718 * cpo.updateObject("myUpdate",so);
1719 * }
1720 * cpoTrx.commit();
1721 * } catch (CpoException ce) {
1722 * // Handle the error
1723 * cpoTrx.rollback();
1724 * }
1725 * }
1726 * </code>
1727 * </pre>
1728 *
1729 * @return A CpoTrxAdapter to manage the transactionality of CPO
1730 * @throws CpoException Thrown if there are errors accessing the datasource
1731 * @see CpoTrxAdapter
1732 */
1733 public CpoTrxAdapter getCpoTrxAdapter() throws CpoException;
1734
1735 public CpoMetaDescriptor getCpoMetaDescriptor();
1736
1737 public String getDataSourceName();
1738
1739 public List<CpoAttribute> getCpoAttributes(String expression) throws CpoException;
1740 }