Package: CriteriaQuery

CriteriaQuery

Coverage

1: /*
2: * JOPA
3: * Copyright (C) 2024 Czech Technical University in Prague
4: *
5: * This library is free software; you can redistribute it and/or
6: * modify it under the terms of the GNU Lesser General Public
7: * License as published by the Free Software Foundation; either
8: * version 3.0 of the License, or (at your option) any later version.
9: *
10: * This library is distributed in the hope that it will be useful,
11: * but WITHOUT ANY WARRANTY; without even the implied warranty of
12: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13: * Lesser General Public License for more details.
14: *
15: * You should have received a copy of the GNU Lesser General Public
16: * License along with this library.
17: */
18: package cz.cvut.kbss.jopa.model.query.criteria;
19:
20: import cz.cvut.kbss.jopa.model.metamodel.EntityType;
21:
22: import java.util.List;
23:
24: /**
25: * Interface used to control the execution of typed queries.
26: *
27: * @param <T> Query result type
28: */
29: public interface CriteriaQuery<T> {
30:
31: /**
32: * Create and add a query root corresponding to the given entity class.
33: *
34: * @param entityClass the entity class
35: * @return query root corresponding to the given entity
36: */
37: <X> Root<X> from(Class<X> entityClass);
38:
39: /**
40: * Create and add a query root corresponding to the given entity type.
41: *
42: * @param entity metamodel entity representing the entity of type X
43: * @return query root corresponding to the given entity
44: */
45: <X> Root<X> from(EntityType<X> entity);
46:
47: /**
48: * Specify the item that is to be returned in the query result. Replaces the previously specified selection(s), if any.
49: *
50: * @param selection - selection specifying the item that is to be returned in the query result
51: * @return the modified query
52: */
53: CriteriaQuery<T> select(Selection<? extends T> selection);
54:
55: /**
56: * Modify the query to restrict the query result according to the specified boolean expression. Replaces the previously added restriction(s), if any.
57: *
58: * @param expression - a simple or compound boolean expression
59: * @return the modified query
60: */
61: CriteriaQuery<T> where(Expression<Boolean> expression);
62:
63: /**
64: * Modify the query to restrict the query result according to the conjunction of the specified restriction predicates. Replaces the previously added restriction(s), if any. If no restrictions are specified, any previously added restrictions are simply removed.
65: *
66: * @param predicates - zero or more restriction predicates
67: * @return the modified query
68: */
69: CriteriaQuery<T> where(Predicate... predicates);
70:
71: /**
72: * Modify the query to restrict the query result according to the conjunction of the specified restriction predicates. Replaces the previously added restriction(s), if any. If no restrictions are specified, any previously added restrictions are simply removed.
73: *
74: * @param predicates - list of predicates
75: * @return the modified query
76: */
77: CriteriaQuery<T> where(List<Predicate> predicates);
78:
79: Class<T> getResultType();
80:
81: /**
82: * Specify whether duplicate query results will be eliminated. A true value will cause duplicates to be eliminated. A false value will cause duplicates to be retained. If distinct has not been specified, duplicate results must be retained.
83: *
84: * @param distinct - boolean value specifying whether duplicate results must be eliminated from the query result or whether they must be retained
85: * @return the modified query
86: */
87: CriteriaQuery<T> distinct(boolean distinct);
88:
89: /**
90: * Specify that duplicates query results will be eliminated.
91: *
92: * @return the modified query
93: */
94: CriteriaQuery<T> distinct();
95:
96: /**
97: * Return whether duplicate query results must be eliminated or retained.
98: *
99: * @return boolean indicating whether duplicate query results must be eliminated
100: */
101: boolean isDistinct();
102:
103: /**
104: * Return the selection of the query, or null if no selection has been set.
105: *
106: * @return selection item
107: */
108: Selection<T> getSelection();
109:
110: /**
111: * Return the predicate that corresponds to the where clause restriction(s), or null if no restrictions have been specified.
112: *
113: * @return where clause predicate
114: */
115: Predicate getRestriction();
116:
117: /**
118: * Specify the expressions that are used to form groups over the query results. Replaces the previous specified grouping expressions, if any. If no grouping expressions are specified, any previously added grouping expressions are simply removed.
119: *
120: * @param grouping zero or more grouping expressions
121: * @return the modified query
122: */
123: CriteriaQuery<T> groupBy(Expression<?>... grouping);
124:
125: /**
126: * Specify the expressions that are used to form groups over the query results. Replaces the previous specified grouping expressions, if any. If no grouping expressions are specified, any previously added grouping expressions are simply removed.
127: *
128: * @param grouping list of zero or more grouping expressions
129: * @return the modified query
130: */
131: CriteriaQuery<T> groupBy(List<Expression<?>> grouping);
132:
133: /**
134: * Specify the ordering expressions that are used to order the query results. Replaces the previous ordering expressions, if any. If no ordering expressions are specified, the previous ordering, if any, is simply removed, and results will be returned in no particular order. The left-to-right sequence of the ordering expressions determines the precedence, whereby the leftmost has highest precedence.
135: *
136: * @param o list of zero or more ordering expressions
137: * @return the modified query
138: */
139: CriteriaQuery<T> orderBy(List<Order> o);
140:
141: /**
142: * Specify the ordering expressions that are used to order the query results. Replaces the previous ordering expressions, if any. If no ordering expressions are specified, the previous ordering, if any, is simply removed, and results will be returned in no particular order. The left-to-right sequence of the ordering expressions determines the precedence, whereby the leftmost has highest precedence.
143: *
144: * @param o zero or more ordering expressions
145: * @return the modified query
146: */
147: CriteriaQuery<T> orderBy(Order... o);
148:
149:
150: /**
151: * Return the ordering expressions in order of precedence. Returns empty list if no ordering expressions have been specified.
152: *
153: * @return the list of ordering expressions
154: */
155: List<Order> getOrderList();
156:
157: /**
158: * Specify a restriction over the groups of the query. Replaces the previous having restriction(s), if any.
159: *
160: * @param restriction a simple or compound boolean expression
161: * @return the modified query
162: */
163: CriteriaQuery<T> having(Expression<Boolean> restriction);
164:
165: /**
166: * Specify restrictions over the groups of the query according the conjunction of the specified restriction predicates. Replaces the previously added having restriction(s), if any. If no restrictions are specified, any previously added restrictions are simply removed.
167: *
168: * @param restrictions zero or more restriction predicates
169: * @return the modified query
170: */
171: CriteriaQuery<T> having(Predicate... restrictions);
172: }