Package: CriteriaBuilder

CriteriaBuilder

Coverage

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