Package: CriteriaBuilder$In

CriteriaBuilder$In

Coverage

1: /**
2: * Copyright (C) 2011 Czech Technical University in Prague
3: *
4: * This program is free software: you can redistribute it and/or modify it under
5: * the terms of the GNU General Public License as published by the Free Software
6: * Foundation, either version 3 of the License, or (at your option) any
7: * later version.
8: *
9: * This program is distributed in the hope that it will be useful, but WITHOUT
10: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
11: * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
12: * details. You should have received a copy of the GNU General Public License
13: * along with this program. If not, see <http://www.gnu.org/licenses/>.
14: */
15:
16: package cz.cvut.kbss.jopa.model.query.criteria;
17:
18: import java.math.BigDecimal;
19: import java.math.BigInteger;
20: import java.util.Collection;
21: import java.util.Map;
22: import java.util.Set;
23:
24: import cz.cvut.kbss.jopa.model.query.Tuple;
25:
26: /**
27: * Used to construct criteria queries, compound selections, expressions,
28: * predicates, orderings. Note that Predicate is used instead of
29: * Expression<Boolean> in this API in order to work around the fact that Java
30: * generics are not compatible with varags.
31: */
32: public interface CriteriaBuilder {
33:         /**
34:          * Create a CriteriaQuery object.
35:          *
36:          * @return criteria query object
37:          */
38:         CriteriaQuery<Object> createQuery();
39:
40:         /**
41:          * Create a CriteriaQuery object with the specified result type. @param
42:          * resultClass type of the query result @return criteria query object
43:          **/
44:         <T> CriteriaQuery<T> createQuery(Class<T> resultClass);
45:
46:         /**
47:          * Create a CriteriaQuery object that returns a tuple of objects as its
48:          * result.
49:          *
50:          * @return criteria query object
51:          */
52:         CriteriaQuery<Tuple> createTupleQuery();
53:
54:         // selection construction methods:
55:         /**
56:          * Create a selection item corresponding to a constructor. This method is
57:          * used to specify a constructor that will be applied to the results of the
58:          * query execution. If the constructor is for an entity class, the resulting
59:          * entities will be in the new state after the query is executed.
60:          *
61:          * @param resultClass
62:          * class whose instance is to be constructed
63:          * @param selections
64:          * arguments to the constructor
65:          * @return compound selection item
66:          * @throws IllegalArgumentException
67:          * if an argument is a
68:          *
69:          * tuple- or array-valued selection item
70:          */
71:         <Y> CompoundSelection<Y> construct(Class<Y> resultClass,
72:                         Selection<?>... selections);
73:
74:         /**
75:          * Create a tuple-valued selection item.
76:          *
77:          * @param selections
78:          * selection items
79:          * @return tuple-valued compound selection
80:          * @throws IllegalArgumentException
81:          * if an argument is a
82:          *
83:          * tuple- or array-valued selection item
84:          */
85:         CompoundSelection<Tuple> tuple(Selection<?>... selections);
86:
87:         /**
88:          * Create an array-valued selection item.
89:          *
90:          * @param selections
91:          * selection items
92:          * @return array-valued compound selection
93:          * @throws IllegalArgumentException
94:          * if an argument is a
95:          *
96:          * tuple- or array-valued selection item
97:          */
98:         CompoundSelection<Object[]> array(Selection<?>... selections);
99:
100:         // ordering:
101:         /**
102:          * Create an ordering by the ascending value of the expression.
103:          *
104:          * @param x
105:          * expression used to define the ordering
106:          * @return ascending ordering corresponding to the expression
107:          */
108:         Order asc(Expression<?> x);
109:
110:         /**
111:          * Create an ordering by the descending value of the expression.
112:          *
113:          * @param x
114:          * expression used to define the ordering
115:          * @return descending ordering corresponding to the expression
116:          */
117:         Order desc(Expression<?> x);
118:
119:         // aggregate functions:
120:         /**
121:          * Create an aggregate expression applying the avg operation.
122:          *
123:          * @param x
124:          * expression representing input value to avg operation
125:          * @return avg expression
126:          */
127:         <N extends Number> Expression<Double> avg(Expression<N> x);
128:
129:         /**
130:          * Create an aggregate expression applying the sum operation.
131:          *
132:          * @param x
133:          * expression representing input value to sum operation
134:          * @return sum expression
135:          */
136:         <N extends Number> Expression<N> sum(Expression<N> x);
137:
138:         /**
139:          * Create an aggregate expression applying the sum operation to an
140:          * Integer-valued expression, returning a Long result.
141:          *
142:          * @param x
143:          * expression representing input value to sum operation
144:          * @return sum expression
145:          */
146:         Expression<Long> sumAsLong(Expression<Integer> x);
147:
148:         /**
149:          * Create an aggregate expression applying the sum operation to a
150:          * Float-valued expression, returning a Double result.
151:          *
152:          * @param x
153:          * expression representing input value to sum operation
154:          * @return sum expression
155:          */
156:         Expression<Double> sumAsDouble(Expression<Float> x);
157:
158:         /**
159:          * Create an aggregate expression applying the numerical max operation.
160:          *
161:          * @param x
162:          * expression representing input value to max operation
163:          * @return max expression
164:          */
165:         <N extends Number> Expression<N> max(Expression<N> x);
166:
167:         /**
168:          * Create an aggregate expression applying the numerical min operation.
169:          *
170:          * @param x
171:          * expression representing input value to min operation
172:          * @return min expression
173:          */
174:         <N extends Number> Expression<N> min(Expression<N> x);
175:
176:         /**
177:          * Create an aggregate expression for finding the greatest of the values
178:          * (strings, dates, etc).
179:          *
180:          * @param x
181:          * expression representing input value to greatest
182:          *
183:          * operation
184:          * @return greatest expression
185:          */
186:         <X extends Comparable<? super X>> Expression<X> greatest(Expression<X> x);
187:
188:         /**
189:          * Create an aggregate expression for finding the least of the values
190:          * (strings, dates, etc).
191:          *
192:          * @param x
193:          * expression representing input value to least
194:          *
195:          * operation
196:          * @return least expression
197:          */
198:         <X extends Comparable<? super X>> Expression<X> least(Expression<X> x);
199:
200:         /**
201:          * Create an aggregate expression applying the count operation.
202:          *
203:          * @param x
204:          * expression representing input value to count
205:          *
206:          * operation
207:          * @return count expression
208:          */
209:         Expression<Long> count(Expression<?> x);
210:
211:         /**
212:          * Create an aggregate expression applying the count distinct operation.
213:          *
214:          * @param x
215:          * expression representing input value to
216:          *
217:          * count distinct operation
218:          * @return count distinct expression
219:          */
220:         Expression<Long> countDistinct(Expression<?> x);
221:
222:         // subqueries:
223:         /**
224:          * Create a predicate testing the existence of a subquery result.
225:          *
226:          * @param subquery
227:          * subquery whose result is to be tested
228:          * @return exists predicate
229:          */
230:         Predicate exists(Subquery<?> subquery);
231:
232:         /**
233:          * Create an all expression over the subquery results.
234:          *
235:          * @param subquery
236:          * @return all expression
237:          */
238:         <Y> Expression<Y> all(Subquery<Y> subquery);
239:
240:         /**
241:          * Create a some expression over the subquery results. This expression is
242:          * equivalent to an any expression.
243:          *
244:          * @param subquery
245:          * @return some expression
246:          */
247:         <Y> Expression<Y> some(Subquery<Y> subquery);
248:
249:         /**
250:          * Create an any expression over the subquery results. This expression is
251:          * equivalent to a some expression.
252:          *
253:          * @param subquery
254:          * @return any expression
255:          */
256:         <Y> Expression<Y> any(Subquery<Y> subquery);
257:
258:         // boolean functions:
259:         /**
260:          * Create a conjunction of the given boolean expressions.
261:          *
262:          * @param x
263:          * boolean expression
264:          * @param y
265:          * boolean expression
266:          * @return and predicate
267:          */
268:         Predicate and(Expression<Boolean> x, Expression<Boolean> y);
269:
270:         /**
271:          * Create a conjunction of the given restriction predicates. A conjunction
272:          * of zero predicates is true.
273:          *
274:          * @param restrictions
275:          * zero or more restriction predicates
276:          * @return and predicate
277:          */
278:         Predicate and(Predicate... restrictions);
279:
280:         /**
281:          * Create a disjunction of the given boolean expressions.
282:          *
283:          * @param x
284:          * boolean expression
285:          * @param y
286:          * boolean expression
287:          * @return or predicate
288:          */
289:         Predicate or(Expression<Boolean> x, Expression<Boolean> y);
290:
291:         /**
292:          * Create a disjunction of the given restriction predicates. A disjunction
293:          * of zero predicates is false.
294:          *
295:          * @param restrictions
296:          * zero or more restriction predicates
297:          * @return or predicate
298:          */
299:         Predicate or(Predicate... restrictions);
300:
301:         /**
302:          * Create a negation of the given restriction.
303:          *
304:          * @param restriction
305:          * restriction expression
306:          * @return not predicate
307:          */
308:         Predicate not(Expression<Boolean> restriction);
309:
310:         /**
311:          * Create a conjunction (with zero conjuncts). A conjunction with zero
312:          * conjuncts is true.
313:          *
314:          * @return and predicate
315:          */
316:         Predicate conjunction();
317:
318:         /**
319:          * Create a disjunction (with zero disjuncts). A disjunction with zero
320:          * disjuncts is false.
321:          *
322:          * @return or predicate
323:          */
324:         Predicate disjunction();
325:
326:         // turn Expression<Boolean> into a Predicate
327:         // useful for use with varargs methods
328:         /**
329:          * Create a predicate testing for a true value.
330:          *
331:          * @param x
332:          * expression to be tested
333:          * @return predicate
334:          */
335:         Predicate isTrue(Expression<Boolean> x);
336:
337:         /**
338:          * Create a predicate testing for a false value.
339:          *
340:          * @param x
341:          * expression to be tested
342:          * @return predicate
343:          */
344:         Predicate isFalse(Expression<Boolean> x);
345:
346:         // null tests:
347:         /**
348:          * Create a predicate to test whether the expression is null.
349:          *
350:          * @param x
351:          * expression
352:          * @return is-null predicate
353:          */
354:         Predicate isNull(Expression<?> x);
355:
356:         /**
357:          * Create a predicate to test whether the expression is not null.
358:          *
359:          * @param x
360:          * expression
361:          * @return is-not-null predicate
362:          */
363:         Predicate isNotNull(Expression<?> x);
364:
365:         // equality:
366:         /**
367:          * Create a predicate for testing the arguments for equality.
368:          *
369:          * @param x
370:          * expression
371:          * @param y
372:          * expression
373:          * @return equality predicate
374:          */
375:         Predicate equal(Expression<?> x, Expression<?> y);
376:
377:         /**
378:          * Create a predicate for testing the arguments for equality.
379:          *
380:          * @param x
381:          * expression
382:          * @param y
383:          * object
384:          * @return equality predicate
385:          */
386:         Predicate equal(Expression<?> x, Object y);
387:
388:         /**
389:          * Create a predicate for testing the arguments for inequality.
390:          *
391:          * @param x
392:          * expression
393:          * @param y
394:          * expression
395:          * @return inequality predicate
396:          */
397:         Predicate notEqual(Expression<?> x, Expression<?> y);
398:
399:         /**
400:          * Create a predicate for testing the arguments for inequality.
401:          *
402:          * @param x
403:          * expression
404:          * @param y
405:          * object
406:          * @return inequality predicate
407:          */
408:         Predicate notEqual(Expression<?> x, Object y);
409:
410:         // comparisons for generic (non-numeric) operands:
411:         /**
412:          * Create a predicate for testing whether the first argument is greater than
413:          * the second.
414:          *
415:          * @param x
416:          * expression
417:          * @param y
418:          * expression
419:          * @return greater-than predicate
420:          */
421:         <Y extends Comparable<? super Y>> Predicate greaterThan(
422:                         Expression<? extends Y> x, Expression<? extends Y> y);
423:
424:         /**
425:          * Create a predicate for testing whether the first argument is greater than
426:          * the second.
427:          *
428:          * @param x
429:          * expression
430:          * @param y
431:          * value
432:          * @return greater-than predicate
433:          */
434:         <Y extends Comparable<? super Y>> Predicate greaterThan(
435:                         Expression<? extends Y> x, Y y);
436:
437:         /**
438:          * Create a predicate for testing whether the first argument is greater than
439:          * or equal to the second.
440:          *
441:          * @param x
442:          * expression
443:          * @param y
444:          * expression
445:          * @return greater-than-or-equal predicate
446:          */
447:         <Y extends Comparable<? super Y>> Predicate greaterThanOrEqualTo(
448:                         Expression<? extends Y> x, Expression<? extends Y> y);
449:
450:         /**
451:          * Create a predicate for testing whether the first argument is greater than
452:          * or equal to the second.
453:          *
454:          * @param x
455:          * expression
456:          * @param y
457:          * value
458:          * @return greater-than-or-equal predicate
459:          */
460:         <Y extends Comparable<? super Y>> Predicate greaterThanOrEqualTo(
461:                         Expression<? extends Y> x, Y y);
462:
463:         /**
464:          * Create a predicate for testing whether the first argument is less than
465:          * the second.
466:          *
467:          * @param x
468:          * expression
469:          * @param y
470:          * expression
471:          * @return less-than predicate
472:          */
473:         <Y extends Comparable<? super Y>> Predicate lessThan(
474:                         Expression<? extends Y> x, Expression<? extends Y> y);
475:
476:         /**
477:          * Create a predicate for testing whether the first argument is less than
478:          * the second.
479:          *
480:          * @param x
481:          * expression
482:          * @param y
483:          * value
484:          * @return less-than predicate
485:          */
486:         <Y extends Comparable<? super Y>> Predicate lessThan(
487:                         Expression<? extends Y> x, Y y);
488:
489:         /**
490:          * Create a predicate for testing whether the first argument is less than or
491:          * equal to the second.
492:          *
493:          * @param x
494:          * expression
495:          * @param y
496:          * expression
497:          * @return less-than-or-equal predicate
498:          */
499:         <Y extends Comparable<? super Y>> Predicate lessThanOrEqualTo(
500:                         Expression<? extends Y> x, Expression<? extends Y> y);
501:
502:         /**
503:          * Create a predicate for testing whether the first argument is less than or
504:          * equal to the second.
505:          *
506:          * @param x
507:          * expression
508:          * @param y
509:          * value
510:          * @return less-than-or-equal predicate
511:          */
512:         <Y extends Comparable<? super Y>> Predicate lessThanOrEqualTo(
513:                         Expression<? extends Y> x, Y y);
514:
515:         /**
516:          * Create a predicate for testing whether the first argument is between the
517:          * second and third arguments in value.
518:          *
519:          * @param v
520:          * expression
521:          * @param x
522:          * expression
523:          * @param y
524:          * expression
525:          * @return between predicate
526:          */
527:         <Y extends Comparable<? super Y>> Predicate between(
528:                         Expression<? extends Y> v, Expression<? extends Y> x,
529:                         Expression<? extends Y> y);
530:
531:         /**
532:          * Create a predicate for testing whether the first argument is between the
533:          * second and third arguments in value.
534:          *
535:          * @param v
536:          * expression
537:          * @param x
538:          * value
539:          * @param y
540:          * value
541:          * @return between predicate
542:          */
543:         <Y extends Comparable<? super Y>> Predicate between(
544:                         Expression<? extends Y> v, Y x, Y y);
545:
546:         // comparisons for numeric operands:
547:         /**
548:          * Create a predicate for testing whether the first argument is greater than
549:          * the second.
550:          *
551:          * @param x
552:          * expression
553:          * @param y
554:          * expression
555:          * @return greater-than predicate
556:          */
557:         Predicate gt(Expression<? extends Number> x, Expression<? extends Number> y);
558:
559:         /**
560:          * Create a predicate for testing whether the first argument is greater than
561:          * the second.
562:          *
563:          * @param x
564:          * expression
565:          * @param y
566:          * value
567:          * @return greater-than predicate
568:          */
569:         Predicate gt(Expression<? extends Number> x, Number y);
570:
571:         /**
572:          * Create a predicate for testing whether the first argument is greater than
573:          * or equal to the second.
574:          *
575:          * @param x
576:          * expression
577:          * @param y
578:          * expression
579:          * @return greater-than-or-equal predicate
580:          */
581:         Predicate ge(Expression<? extends Number> x, Expression<? extends Number> y);
582:
583:         /**
584:          * Create a predicate for testing whether the first argument is greater than
585:          * or equal to the second.
586:          *
587:          * @param x
588:          * expression
589:          * @param y
590:          * value
591:          * @return greater-than-or-equal predicate
592:          */
593:         Predicate ge(Expression<? extends Number> x, Number y);
594:
595:         /**
596:          * Create a predicate for testing whether the first argument is less than
597:          * the second.
598:          *
599:          * @param x
600:          * expression
601:          * @param y
602:          * expression
603:          * @return less-than predicate
604:          */
605:         Predicate lt(Expression<? extends Number> x, Expression<? extends Number> y);
606:
607:         /**
608:          * Create a predicate for testing whether the first argument is less than
609:          * the second.
610:          *
611:          * @param x
612:          * expression
613:          * @param y
614:          * value
615:          * @return less-than predicate
616:          */
617:         Predicate lt(Expression<? extends Number> x, Number y);
618:
619:         /**
620:          * Create a predicate for testing whether the first argument is less than or
621:          * equal to the second.
622:          *
623:          * @param x
624:          * expression
625:          * @param y
626:          * expression
627:          * @return less-than-or-equal predicate
628:          */
629:         Predicate le(Expression<? extends Number> x, Expression<? extends Number> y);
630:
631:         /**
632:          * Create a predicate for testing whether the first argument is less than or
633:          * equal to the second.
634:          *
635:          * @param x
636:          * expression
637:          * @param y
638:          * value
639:          * @return less-than-or-equal predicate
640:          */
641:         Predicate le(Expression<? extends Number> x, Number y);
642:
643:         // numerical operations:
644:         /**
645:          * Create an expression that returns the arithmetic negation of its
646:          * argument.
647:          *
648:          * @param x
649:          * expression
650:          * @return arithmetic negation
651:          */
652:         <N extends Number> Expression<N> neg(Expression<N> x);
653:
654:         /**
655:          * Create an expression that returns the absolute value of its argument.
656:          *
657:          * @param x
658:          * expression
659:          * @return absolute value
660:          */
661:         <N extends Number> Expression<N> abs(Expression<N> x);
662:
663:         /**
664:          * Create an expression that returns the sum of its arguments.
665:          *
666:          * @param x
667:          * expression
668:          * @param y
669:          * expression
670:          * @return sum
671:          */
672:         <N extends Number> Expression<N> sum(Expression<? extends N> x,
673:                         Expression<? extends N> y);
674:
675:         /**
676:          * Create an expression that returns the sum of its arguments.
677:          *
678:          * @param x
679:          * expression
680:          * @param y
681:          * value
682:          * @return sum
683:          */
684:         <N extends Number> Expression<N> sum(Expression<? extends N> x, N y);
685:
686:         /**
687:          * Create an expression that returns the sum of its arguments.
688:          *
689:          * @param x
690:          * value
691:          * @param y
692:          * expression
693:          * @return sum
694:          */
695:         <N extends Number> Expression<N> sum(N x, Expression<? extends N> y);
696:
697:         /**
698:          * Create an expression that returns the product of its arguments.
699:          *
700:          * @param x
701:          * expression
702:          * @param y
703:          * expression
704:          * @return product
705:          */
706:         <N extends Number> Expression<N> prod(Expression<? extends N> x,
707:                         Expression<? extends N> y);
708:
709:         /**
710:          * Create an expression that returns the product of its arguments.
711:          *
712:          * @param x
713:          * expression
714:          * @param y
715:          * value
716:          * @return product
717:          */
718:         <N extends Number> Expression<N> prod(Expression<? extends N> x, N y);
719:
720:         /**
721:          * Create an expression that returns the product of its arguments.
722:          *
723:          * @param x
724:          * value
725:          * @param y
726:          * expression
727:          * @return product
728:          */
729:         <N extends Number> Expression<N> prod(N x, Expression<? extends N> y);
730:
731:         /**
732:          * Create an expression that returns the difference between its arguments.
733:          *
734:          * @param x
735:          * expression
736:          * @param y
737:          * expression
738:          * @return difference
739:          */
740:         <N extends Number> Expression<N> diff(Expression<? extends N> x,
741:                         Expression<? extends N> y);
742:
743:         /**
744:          * Create an expression that returns the difference between its arguments.
745:          *
746:          * @param x
747:          * expression
748:          * @param y
749:          * value
750:          * @return difference
751:          */
752:         <N extends Number> Expression<N> diff(Expression<? extends N> x, N y);
753:
754:         /**
755:          * Create an expression that returns the difference between its arguments.
756:          *
757:          * @param x
758:          * value
759:          * @param y
760:          * expression
761:          * @return difference
762:          */
763:         <N extends Number> Expression<N> diff(N x, Expression<? extends N> y);
764:
765:         /**
766:          * Create an expression that returns the quotient of its arguments.
767:          *
768:          * @param x
769:          * expression
770:          * @param y
771:          * expression
772:          * @return quotient
773:          */
774:         Expression<Number> quot(Expression<? extends Number> x,
775:                         Expression<? extends Number> y);
776:
777:         /**
778:          * Create an expression that returns the quotient of its arguments.
779:          *
780:          * @param x
781:          * expression
782:          * @param y
783:          * value
784:          * @return quotient
785:          */
786:         Expression<Number> quot(Expression<? extends Number> x, Number y);
787:
788:         /**
789:          * Create an expression that returns the quotient of its arguments.
790:          *
791:          * @param x
792:          * value
793:          * @param y
794:          * expression
795:          * @return quotient
796:          */
797:         Expression<Number> quot(Number x, Expression<? extends Number> y);
798:
799:         /**
800:          * Create an expression that returns the modulus of its arguments.
801:          *
802:          * @param x
803:          * expression
804:          * @param y
805:          * expression
806:          * @return modulus
807:          */
808:         Expression<Integer> mod(Expression<Integer> x, Expression<Integer> y);
809:
810:         /**
811:          * Create an expression that returns the modulus of its arguments.
812:          *
813:          * @param x
814:          * expression
815:          * @param y
816:          * value
817:          * @return modulus
818:          */
819:         Expression<Integer> mod(Expression<Integer> x, Integer y);
820:
821:         /**
822:          * Create an expression that returns the modulus of its arguments.
823:          *
824:          * @param x
825:          * value
826:          * @param y
827:          * expression
828:          * @return modulus
829:          */
830:         Expression<Integer> mod(Integer x, Expression<Integer> y);
831:
832:         /**
833:          * Create an expression that returns the square root of its argument.
834:          *
835:          * @param x
836:          * expression
837:          * @return square root
838:          */
839:         Expression<Double> sqrt(Expression<? extends Number> x);
840:
841:         // typecasts:
842:         /**
843:          * Typecast. Returns same expression object.
844:          *
845:          * @param number
846:          * numeric expression
847:          * @return Expression<Long>
848:          */
849:         Expression<Long> toLong(Expression<? extends Number> number);
850:
851:         /**
852:          * Typecast. Returns same expression object.
853:          *
854:          * @param number
855:          * numeric expression
856:          * @return Expression<Integer>
857:          */
858:         Expression<Integer> toInteger(Expression<? extends Number> number);
859:
860:         /**
861:          * Typecast. Returns same expression object.
862:          *
863:          * @param number
864:          * numeric expression
865:          * @return Expression<Float>
866:          */
867:         Expression<Float> toFloat(Expression<? extends Number> number);
868:
869:         /**
870:          * Typecast. Returns same expression object.
871:          *
872:          * @param number
873:          * numeric expression
874:          * @return Expression<Double>
875:          */
876:         Expression<Double> toDouble(Expression<? extends Number> number);
877:
878:         /**
879:          * Typecast. Returns same expression object.
880:          *
881:          * @param number
882:          * numeric expression
883:          * @return Expression<BigDecimal>
884:          */
885:         Expression<BigDecimal> toBigDecimal(Expression<? extends Number> number);
886:
887:         /**
888:          * Typecast. Returns same expression object.
889:          *
890:          * @param number
891:          * numeric expression
892:          * @return Expression<BigInteger>
893:          */
894:         Expression<BigInteger> toBigInteger(Expression<? extends Number> number);
895:
896:         /**
897:          * Typecast. Returns same expression object.
898:          *
899:          * @param character
900:          * expression
901:          * @return Expression<String>
902:          */
903:         Expression<String> toString(Expression<Character> character);
904:
905:         // literals:
906:         /**
907:          * Create an expression for a literal.
908:          *
909:          * @param value
910:          * value represented by the expression
911:          * @return expression literal
912:          * @throws IllegalArgumentException
913:          * if value is null
914:          */
915:         <T> Expression<T> literal(T value);
916:
917:         /**
918:          * Create an expression for a null literal with the given type.
919:          *
920:          * @param resultClass
921:          * type of the null literal
922:          * @return null expression literal
923:          */
924:         <T> Expression<T> nullLiteral(Class<T> resultClass);
925:
926:         // parameters:
927:         /**
928:          * Create a parameter expression.
929:          *
930:          * @param paramClass
931:          * parameter class
932:          * @return parameter expression
933:          */
934:         <T> ParameterExpression<T> parameter(Class<T> paramClass);
935:
936:         /**
937:          * Create a parameter expression with the given name.
938:          *
939:          * @param paramClass
940:          * parameter class
941:          * @param name
942:          * name that can be used to refer to
943:          *
944:          * the parameter
945:          * @return parameter expression
946:          */
947:         <T> ParameterExpression<T> parameter(Class<T> paramClass, String name);
948:
949:         // collection operations:
950:         /**
951:          * Create a predicate that tests whether a collection is empty.
952:          *
953:          * @param collection
954:          * expression
955:          * @return is-empty predicate
956:          */
957:         <C extends Collection<?>> Predicate isEmpty(Expression<C> collection);
958:
959:         /**
960:          * Create a predicate that tests whether a collection is not empty.
961:          *
962:          * @param collection
963:          * expression
964:          * @return is-not-empty predicate
965:          */
966:         <C extends Collection<?>> Predicate isNotEmpty(Expression<C> collection);
967:
968:         /**
969:          * Create an expression that tests the size of a collection.
970:          *
971:          * @param collection
972:          * expression
973:          * @return size expression
974:          */
975:         <C extends Collection<?>> Expression<Integer> size(Expression<C> collection);
976:
977:         /**
978:          * Create an expression that tests the size of a collection.
979:          *
980:          * @param collection
981:          * collection
982:          * @return size expression
983:          */
984:         <E, C extends Collection<?>> Expression<Integer> size(C collection);
985:
986:         /**
987:          * <E, Create a predicate that tests whether an element is a member of a
988:          * collection. If the collection is empty, the predicate will be false.
989:          *
990:          * @param elem
991:          * element expression
992:          * @param collection
993:          * expression
994:          * @return is-member predicate
995:          **/
996:         <E, C extends Collection<E>> Predicate isMember(Expression<E> elem,
997:                         Expression<C> collection);
998:
999:         /**
1000:          * Create a predicate that tests whether an element is a member of a
1001:          * collection. If the collection is empty, the predicate will be false.
1002:          *
1003:          * @param elem
1004:          * element
1005:          * @param collection
1006:          * expression
1007:          * @return is-member predicate
1008:          **/
1009:         <E, C extends Collection<E>> Predicate isMember(E elem,
1010:                         Expression<C> collection);
1011:
1012:         /**
1013:          * Create a predicate that tests whether an element is not a member of a
1014:          * collection. If the collection is empty, the predicate will be true.
1015:          *
1016:          * @param elem
1017:          * element expression
1018:          * @param collection
1019:          * expression
1020:          * @return is-not-member predicate
1021:          **/
1022:         <E, C extends Collection<E>> Predicate isNotMember(Expression<E> elem,
1023:                         Expression<C> collection);
1024:
1025:         /**
1026:          * Create a predicate that tests whether an element is not a member of a
1027:          * collection. If the collection is empty, the predicate will be true.
1028:          *
1029:          * @param elem
1030:          * element
1031:          * @param collection
1032:          * expression
1033:          * @return is-not-member predicate
1034:          **/
1035:         <E, C extends Collection<E>> Predicate isNotMember(E elem,
1036:                         Expression<C> collection);
1037:
1038:         // get the values and keys collections of the Map, which may then
1039:         // be passed to size(), isMember(), isEmpty(), etc
1040:         /**
1041:          * Create an expression that returns the values of a map.
1042:          *
1043:          * @param map
1044:          * map
1045:          * @return collection expression
1046:          */
1047:         <V, M extends Map<?, V>> Expression<Collection<V>> values(M map);
1048:
1049:         /**
1050:          * Create an expression that returns the keys of a map.
1051:          *
1052:          * @param map
1053:          * map
1054:          * @return set expression
1055:          */
1056:         <K, M extends Map<K, ?>> Expression<Set<K>> keys(M map);
1057:
1058:         // string functions:
1059:         /**
1060:          * Create a predicate for testing whether the expression satisfies the given
1061:          * pattern.
1062:          *
1063:          * @param x
1064:          * string expression
1065:          * @param pattern
1066:          * string expression
1067:          * @return like predicate
1068:          */
1069:         Predicate like(Expression<String> x, Expression<String> pattern);
1070:
1071:         /**
1072:          * Create a predicate for testing whether the expression satisfies the given
1073:          * pattern.
1074:          *
1075:          * @param x
1076:          * string expression
1077:          * @param pattern
1078:          * string
1079:          * @return like predicate
1080:          */
1081:         Predicate like(Expression<String> x, String pattern);
1082:
1083:         /**
1084:          * Create a predicate for testing whether the expression satisfies the given
1085:          * pattern.
1086:          *
1087:          * @param x
1088:          * string expression
1089:          * @param pattern
1090:          * string expression
1091:          * @param escapeChar
1092:          * escape character expression
1093:          * @return like predicate
1094:          */
1095:         Predicate like(Expression<String> x, Expression<String> pattern,
1096:                         Expression<Character> escapeChar);
1097:
1098:         /**
1099:          * Create a predicate for testing whether the expression satisfies the given
1100:          * pattern.
1101:          *
1102:          * @param x
1103:          * string expression
1104:          * @param pattern
1105:          * string expression
1106:          * @param escapeChar
1107:          * escape character
1108:          * @return like predicate
1109:          */
1110:         Predicate like(Expression<String> x, Expression<String> pattern,
1111:                         char escapeChar);
1112:
1113:         /**
1114:          * Create a predicate for testing whether the expression satisfies the given
1115:          * pattern.
1116:          *
1117:          * @param x
1118:          * string expression
1119:          * @param pattern
1120:          * string
1121:          * @param escapeChar
1122:          * escape character expression
1123:          * @return like predicate
1124:          */
1125:         Predicate like(Expression<String> x, String pattern,
1126:                         Expression<Character> escapeChar);
1127:
1128:         /**
1129:          * Create a predicate for testing whether the expression satisfies the given
1130:          * pattern.
1131:          *
1132:          * @param x
1133:          * string expression
1134:          * @param pattern
1135:          * string
1136:          * @param escapeChar
1137:          * escape character
1138:          * @return like predicate
1139:          */
1140:         Predicate like(Expression<String> x, String pattern, char escapeChar);
1141:
1142:         /**
1143:          * Create a predicate for testing whether the expression does not satisfy
1144:          * the given pattern.
1145:          *
1146:          * @param x
1147:          * string expression
1148:          * @param pattern
1149:          * string expression
1150:          * @return not-like predicate
1151:          */
1152:         Predicate notLike(Expression<String> x, Expression<String> pattern);
1153:
1154:         /**
1155:          * Create a predicate for testing whether the expression does not satisfy
1156:          * the given pattern.
1157:          *
1158:          * @param x
1159:          * string expression
1160:          * @param pattern
1161:          * string
1162:          * @return not-like predicate
1163:          */
1164:         Predicate notLike(Expression<String> x, String pattern);
1165:
1166:         /**
1167:          * Create a predicate for testing whether the expression does not satisfy
1168:          * the given pattern.
1169:          *
1170:          * @param x
1171:          * string expression
1172:          * @param pattern
1173:          * string expression
1174:          * @param escapeChar
1175:          * escape character expression
1176:          * @return not-like predicate
1177:          */
1178:         Predicate notLike(Expression<String> x, Expression<String> pattern,
1179:                         Expression<Character> escapeChar);
1180:
1181:         /**
1182:          * Create a predicate for testing whether the expression does not satisfy
1183:          * the given pattern.
1184:          *
1185:          * @param x
1186:          * string expression
1187:          * @param pattern
1188:          * string expression
1189:          * @param escapeChar
1190:          * escape character
1191:          * @return not-like predicate
1192:          */
1193:         Predicate notLike(Expression<String> x, Expression<String> pattern,
1194:                         char escapeChar);
1195:
1196:         /**
1197:          * Create a predicate for testing whether the expression does not satisfy
1198:          * the given pattern.
1199:          *
1200:          * @param x
1201:          * string expression
1202:          * @param pattern
1203:          * string
1204:          * @param escapeChar
1205:          * escape character expression
1206:          * @return not-like predicate
1207:          */
1208:         Predicate notLike(Expression<String> x, String pattern,
1209:                         Expression<Character> escapeChar);
1210:
1211:         /**
1212:          * Create a predicate for testing whether the expression does not satisfy
1213:          * the given pattern.
1214:          *
1215:          * @param x
1216:          * string expression
1217:          * @param pattern
1218:          * string
1219:          * @param escapeChar
1220:          * escape character
1221:          * @return not-like predicate
1222:          */
1223:         Predicate notLike(Expression<String> x, String pattern, char escapeChar);
1224:
1225:         /**
1226:          * Create an expression for string concatenation.
1227:          *
1228:          * @param x
1229:          * string expression
1230:          * @param y
1231:          * string expression
1232:          * @return expression corresponding to concatenation
1233:          */
1234:         Expression<String> concat(Expression<String> x, Expression<String> y);
1235:
1236:         /**
1237:          * Create an expression for string concatenation.
1238:          *
1239:          * @param x
1240:          * string expression
1241:          * @param y
1242:          * string
1243:          * @return expression corresponding to concatenation
1244:          */
1245:         Expression<String> concat(Expression<String> x, String y);
1246:
1247:         /**
1248:          * Create an expression for string concatenation.
1249:          *
1250:          * @param x
1251:          * string
1252:          * @param y
1253:          * string expression
1254:          * @return expression corresponding to concatenation
1255:          */
1256:         Expression<String> concat(String x, Expression<String> y);
1257:
1258:         /**
1259:          * Create an expression for substring extraction. Extracts a substring
1260:          * starting at the specified position through to end of the string. First
1261:          * position is 1.
1262:          *
1263:          * @param x
1264:          * string expression
1265:          * @param from
1266:          * start position expression
1267:          * @return expression corresponding to substring extraction
1268:          */
1269:         Expression<String> substring(Expression<String> x, Expression<Integer> from);
1270:
1271:         /**
1272:          * Create an expression for substring extraction. Extracts a substring
1273:          * starting at the specified position through to end of the string. First
1274:          * position is 1.
1275:          *
1276:          * @param x
1277:          * string expression
1278:          * @param from
1279:          * start position
1280:          * @return expression corresponding to substring extraction
1281:          */
1282:         Expression<String> substring(Expression<String> x, int from);
1283:
1284:         /**
1285:          * Create an expression for substring extraction. Extracts a substring of
1286:          * given length starting at the specified position. First position is 1.
1287:          *
1288:          * @param x
1289:          * string expression
1290:          * @param from
1291:          * start position expression
1292:          * @param len
1293:          * length expression
1294:          * @return expression corresponding to substring extraction
1295:          */
1296:         Expression<String> substring(Expression<String> x,
1297:                         Expression<Integer> from, Expression<Integer> len);
1298:
1299:         /**
1300:          * Create an expression for substring extraction. Extracts a substring of
1301:          * given length starting at the specified position. First position is 1.
1302:          *
1303:          * @param x
1304:          * string expression
1305:          * @param from
1306:          * start position
1307:          * @param len
1308:          * length
1309:          * @return expression corresponding to substring extraction
1310:          */
1311:         Expression<String> substring(Expression<String> x, int from, int len);
1312:
1313:         public static enum Trimspec {
1314:                 /**
1315:                  * Trim from leading end.
1316:                  */
1317:                 LEADING,
1318:                 /**
1319:                  * Trim from trailing end.
1320:                  */
1321:                 TRAILING,
1322:                 /**
1323:                  * Trim from both ends.
1324:                  */
1325:                 BOTH
1326:         }
1327:
1328:         /**
1329:          * Create expression to trim blanks from both ends of a string.
1330:          *
1331:          * @param x
1332:          * expression for string to trim
1333:          * @return trim expression
1334:          */
1335:         Expression<String> trim(Expression<String> x);
1336:
1337:         /**
1338:          * Create expression to trim blanks from a string.
1339:          *
1340:          * @param ts
1341:          * trim specification
1342:          * @param x
1343:          * expression for string to trim
1344:          * @return trim expression
1345:          */
1346:         Expression<String> trim(Trimspec ts, Expression<String> x);
1347:
1348:         /**
1349:          * Create expression to trim character from both ends of a string.
1350:          *
1351:          * @param t
1352:          * expression for character to be trimmed
1353:          * @param x
1354:          * expression for string to trim
1355:          * @return trim expression
1356:          */
1357:         Expression<String> trim(Expression<Character> t, Expression<String> x);
1358:
1359:         /**
1360:          * Create expression to trim character from a string.
1361:          *
1362:          * @param ts
1363:          * trim specification
1364:          * @param t
1365:          * expression for character to be trimmed
1366:          * @param x
1367:          * expression for string to trim
1368:          * @return trim expression
1369:          */
1370:         Expression<String> trim(Trimspec ts, Expression<Character> t,
1371:                         Expression<String> x);
1372:
1373:         /**
1374:          * Create expression to trim character from both ends of a string.
1375:          *
1376:          * @param t
1377:          * character to be trimmed
1378:          * @param x
1379:          * expression for string to trim
1380:          * @return trim expression
1381:          */
1382:         Expression<String> trim(char t, Expression<String> x);
1383:
1384:         /**
1385:          * Create expression to trim character from a string.
1386:          *
1387:          * @param ts
1388:          * trim specification
1389:          * @param t
1390:          * character to be trimmed
1391:          * @param x
1392:          * expression for string to trim
1393:          * @return trim expression
1394:          */
1395:         Expression<String> trim(Trimspec ts, char t, Expression<String> x);
1396:
1397:         /**
1398:          * Create expression for converting a string to lowercase.
1399:          *
1400:          * @param x
1401:          * string expression
1402:          * @return expression to convert to lowercase
1403:          */
1404:         Expression<String> lower(Expression<String> x);
1405:
1406:         /**
1407:          * Create expression for converting a string to uppercase.
1408:          *
1409:          * @param x
1410:          * string expression
1411:          * @return expression to convert to uppercase
1412:          */
1413:         Expression<String> upper(Expression<String> x);
1414:
1415:         /**
1416:          * Create expression to return length of a string.
1417:          *
1418:          * @param x
1419:          * string expression
1420:          * @return length expression
1421:          */
1422:         Expression<Integer> length(Expression<String> x);
1423:
1424:         /**
1425:          * Create expression to locate the position of one string within another,
1426:          * returning position of first character if found. The first position in a
1427:          * string is denoted by 1. If the string to be located is not found, 0 is
1428:          * returned.
1429:          *
1430:          * @param x
1431:          * expression for string to be searched
1432:          * @param pattern
1433:          * expression for string to be located
1434:          * @return expression corresponding to position
1435:          */
1436:         Expression<Integer> locate(Expression<String> x, Expression<String> pattern);
1437:
1438:         /**
1439:          * Create expression to locate the position of one string within another,
1440:          * returning position of first character if found. The first position in a
1441:          * string is denoted by 1. If the string to be located is not found, 0 is
1442:          * returned.
1443:          *
1444:          * @param x
1445:          * expression for string to be searched
1446:          * @param pattern
1447:          * string to be located
1448:          * @return expression corresponding to position
1449:          */
1450:         Expression<Integer> locate(Expression<String> x, String pattern);
1451:
1452:         /**
1453:          * Create expression to locate the position of one string within another,
1454:          * returning position of first character if found. The first position in a
1455:          * string is denoted by 1. If the string to be located is not found, 0 is
1456:          * returned.
1457:          *
1458:          * @param x
1459:          * expression for string to be searched
1460:          * @param pattern
1461:          * expression for string to be located
1462:          * @param from
1463:          * expression for position at which to start search
1464:          * @return expression corresponding to position
1465:          */
1466:         Expression<Integer> locate(Expression<String> x,
1467:                         Expression<String> pattern, Expression<Integer> from);
1468:
1469:         /**
1470:          * Create expression to locate the position of one string within another,
1471:          * returning position of first character if found. The first position in a
1472:          * string is denoted by 1. If the string to be located is not found, 0 is
1473:          * returned.
1474:          *
1475:          * @param x
1476:          * expression for string to be searched
1477:          * @param pattern
1478:          * string to be located
1479:          * @param from
1480:          * position at which to start search
1481:          * @return expression corresponding to position
1482:          */
1483:         Expression<Integer> locate(Expression<String> x, String pattern, int from);
1484:
1485:         // Date/time/timestamp functions:
1486:         /**
1487:          * Create expression to return current date.
1488:          *
1489:          * @return expression for current date
1490:          */
1491:         Expression<java.sql.Date> currentDate();
1492:
1493:         /**
1494:          * Create expression to return current timestamp.
1495:          *
1496:          * @return expression for current timestamp
1497:          */
1498:         Expression<java.sql.Timestamp> currentTimestamp();
1499:
1500:         /**
1501:          * Create expression to return current time.
1502:          *
1503:          * @return expression for current time
1504:          */
1505:         Expression<java.sql.Time> currentTime();
1506:
1507:         // in builders:
1508:         /**
1509:          * Interface used to build in predicates.
1510:          */
1511:         public static interface In<T> extends Predicate {
1512:                 /**
1513:                  * Return the expression to be tested against the list of values.
1514:                  *
1515:                  * @return expression
1516:                  */
1517:                 Expression<T> getExpression();
1518:
1519:                 /**
1520:                  * Add to list of values to be tested against.
1521:                  *
1522:                  * @param value
1523:                  * value
1524:                  * @return in predicate
1525:                  */
1526:                 In<T> value(T value);
1527:
1528:                 /**
1529:                  * Add to list of values to be tested against.
1530:                  *
1531:                  * @param value
1532:                  * expression
1533:                  * @return in predicate
1534:                  */
1535:                 In<T> value(Expression<? extends T> value);
1536:         }
1537:
1538:         /**
1539:          * Create predicate to test whether given expression is contained in a list
1540:          * of values.
1541:          *
1542:          * @param expression
1543:          * to be tested against list of values
1544:          * @return in predicate
1545:          **/
1546:         <T> In<T> in(Expression<? extends T> expression);
1547:
1548:         // coalesce, nullif:
1549:         /**
1550:          * Create an expression that returns null if all its arguments evaluate to
1551:          * null, and the value of the first non-null argument otherwise.
1552:          *
1553:          * @param x
1554:          * expression
1555:          * @param y
1556:          * expression
1557:          * @return coalesce expression
1558:          */
1559:         <Y> Expression<Y> coalesce(Expression<? extends Y> x,
1560:                         Expression<? extends Y> y);
1561:
1562:         /**
1563:          * Create an expression that returns null if all its arguments evaluate to
1564:          * null, and the value of the first non-null argument otherwise.
1565:          *
1566:          * @param x
1567:          * expression
1568:          * @param y
1569:          * value
1570:          * @return coalesce expression
1571:          */
1572:         <Y> Expression<Y> coalesce(Expression<? extends Y> x, Y y);
1573:
1574:         /**
1575:          * Create an expression that tests whether its argument are equal, returning
1576:          * null if they are and the value of the first expression if they are not.
1577:          *
1578:          * @param x
1579:          * expression
1580:          * @param y
1581:          * expression
1582:          * @return nullif expression
1583:          */
1584:         <Y> Expression<Y> nullif(Expression<Y> x, Expression<?> y);
1585:
1586:         /**
1587:          * Create an expression that tests whether its argument are equal, returning
1588:          * null if they are and the value of the first expression if they are not.
1589:          *
1590:          * @param x
1591:          * expression
1592:          * @param y
1593:          * value
1594:          * @return nullif expression
1595:          */
1596:         <Y> Expression<Y> nullif(Expression<Y> x, Y y);
1597:
1598:         // coalesce builder:
1599:         /**
1600:          * Interface used to build coalesce expressions.
1601:          *
1602:          * A coalesce expression is equivalent to a case expression that returns
1603:          * null if all its arguments evaluate to null, and the value of its first
1604:          * non-null argument otherwise.
1605:          */
1606:         public static interface Coalesce<T> extends Expression<T> {
1607:                 /**
1608:                  * Add an argument to the coalesce expression.
1609:                  *
1610:                  * @param value
1611:                  * value
1612:                  * @return coalesce expression
1613:                  */
1614:                 Coalesce<T> value(T value);
1615:
1616:                 /**
1617:                  * Add an argument to the coalesce expression.
1618:                  *
1619:                  * @param value
1620:                  * expression
1621:                  * @return coalesce expression
1622:                  */
1623:                 Coalesce<T> value(Expression<? extends T> value);
1624:         }
1625:
1626:         /**
1627:          * Create a coalesce expression.
1628:          *
1629:          * @return coalesce expression
1630:          */
1631:         <T> Coalesce<T> coalesce();
1632:
1633:         // case builders:
1634:         /**
1635:          * Interface used to build simple case expressions. Case conditions are
1636:          * evaluated in the order in which they are specified.
1637:          */
1638:         public static interface SimpleCase<C, R> extends Expression<R> {
1639:                 /**
1640:                  * Return the expression to be tested against the conditions.
1641:                  *
1642:                  * @return expression
1643:                  */
1644:                 Expression<C> getExpression();
1645:
1646:                 /**
1647:                  * Add a when/then clause to the case expression.
1648:                  *
1649:                  * @param condition
1650:                  * "when" condition
1651:                  * @param result
1652:                  * "then" result value
1653:                  * @return simple case expression
1654:                  */
1655:                 SimpleCase<C, R> when(C condition, R result);
1656:
1657:                 /**
1658:                  * Add a when/then clause to the case expression.
1659:                  *
1660:                  * @param condition
1661:                  * "when" condition
1662:                  * @param result
1663:                  * "then" result expression
1664:                  * @return simple case expression
1665:                  */
1666:                 SimpleCase<C, R> when(C condition, Expression<? extends R> result);
1667:
1668:                 /**
1669:                  * Add an "else" clause to the case expression.
1670:                  *
1671:                  * @param result
1672:                  * "else" result
1673:                  * @return expression
1674:                  */
1675:                 Expression<R> otherwise(R result);
1676:
1677:                 /**
1678:                  * Add an "else" clause to the case expression.
1679:                  *
1680:                  * @param result
1681:                  * "else" result expression
1682:                  * @return expression
1683:                  */
1684:                 Expression<R> otherwise(Expression<? extends R> result);
1685:         }
1686:
1687:         /**
1688:          * Create a simple case expression.
1689:          *
1690:          * @param expression
1691:          * to be tested against the case conditions
1692:          * @return simple case expression
1693:          **/
1694:         <C, R> SimpleCase<C, R> selectCase(Expression<? extends C> expression);
1695:
1696:         /**
1697:          * Interface used to build general case expressions. Case conditions are
1698:          * evaluated in the order in which they are specified.
1699:          */
1700:         public static interface Case<R> extends Expression<R> {
1701:                 /**
1702:                  * Add a when/then clause to the case expression.
1703:                  *
1704:                  * @param condition
1705:                  * "when" condition
1706:                  * @param result
1707:                  * "then" result value
1708:                  * @return general case expression
1709:                  */
1710:                 Case<R> when(Expression<Boolean> condition, R result);
1711:
1712:                 /**
1713:                  * Add a when/then clause to the case expression.
1714:                  *
1715:                  * @param condition
1716:                  * "when" condition
1717:                  * @param result
1718:                  * "then" result expression
1719:                  * @return general case expression
1720:                  */
1721:                 Case<R> when(Expression<Boolean> condition,
1722:                                 Expression<? extends R> result);
1723:
1724:                 /**
1725:                  * Add an "else" clause to the case expression.
1726:                  *
1727:                  * @param result
1728:                  * "else" result
1729:                  * @return expression
1730:                  */
1731:                 Expression<R> otherwise(R result);
1732:
1733:                 /**
1734:                  * Add an "else" clause to the case expression.
1735:                  *
1736:                  * @param result
1737:                  * "else" result expression
1738:                  * @return expression
1739:                  */
1740:                 Expression<R> otherwise(Expression<? extends R> result);
1741:         }
1742:
1743:         /**
1744:          * Create a general case expression.
1745:          *
1746:          * @return general case expression
1747:          */
1748:         <R> Case<R> selectCase();
1749:
1750:         /**
1751:          * Create an expression for the execution of a database function.
1752:          *
1753:          * @param name
1754:          * function name
1755:          * @param type
1756:          * expected result type
1757:          * @param args
1758:          * function arguments
1759:          * @return expression
1760:          */
1761:         <T> Expression<T> function(String name, Class<T> type,
1762:                         Expression<?>... args);
1763: }