Package: CriteriaQuery

CriteriaQuery

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.util.List;
18: import java.util.Set;
19:
20: /**
21: * The CriteriaQuery interface defines functionality that is specific to
22: * top-level queries.
23: *
24: * @param <T>
25: * type of the defined result
26: */
27: public interface CriteriaQuery<T> extends AbstractQuery<T> {
28:         /**
29:          * Specify the item that is to be returned in the query result. Replaces the
30:          * previously specified selection(s), if any.
31:          *
32:          * Note: Applications using the string-based API may need to specify the
33:          * type of the select item when it results from a get or join operation and
34:          * the query result type is specified. For example:
35:          *
36:          * CriteriaQuery<String> q = cb.createQuery(String.class); Root<Order> order
37:          * = q.from(Order.class);
38:          * q.select(order.get("shippingAddress").<String>get("state"));
39:          *
40:          * CriteriaQuery<Product> q2 = cb.createQuery(Product.class);
41:          * q2.select(q2.from(Order.class)
42:          *
43:          * .join("items")
44:          *
45:          * .<Item,Product>join("product"));
46:          *
47:          * @param selection
48:          * selection specifying the item that
49:          *
50:          * is to be returned in the query result
51:          * @return the modified query
52:          * @throws IllegalArgumentException
53:          * if the selection is
54:          *
55:          * a compound selection and more than one selection
56:          *
57:          * item has the same assigned alias
58:          */
59:         CriteriaQuery<T> select(Selection<? extends T> selection);
60:
61:         /**
62:          * Specify the selection items that are to be returned in the query result.
63:          * Replaces the previously specified selection(s), if any.
64:          *
65:          * The type of the result of the query execution depends on the
66:          * specification of the type of the criteria query object created as well as
67:          * the arguments to the multiselect method. An argument to the multiselect
68:          * method must not be a tuple- or array-valued compound selection item.
69:          *
70:          * The semantics of this method are as follows:
71:          *
72:          * If the type of the criteria query is CriteriaQuery<Tuple> (i.e., a
73:          * criteria query object created by either the createTupleQuery method or by
74:          * passing a Tuple class argument to the createQuery method), a Tuple object
75:          * corresponding to the arguments of the multiselect method, in the
76:          * specified order, will be instantiated and returned for each row that
77:          * results from the query execution.
78:          *
79:          * If the type of the criteria query is CriteriaQuery<X> for some
80:          * user-defined class X (i.e., a criteria query object created by passing a
81:          * X class argument to the createQuery method), the arguments to the
82:          * multiselect method will be passed to the X constructor and an instance of
83:          * type X will be returned for each row.
84:          *
85:          * If the type of the criteria query is CriteriaQuery<X[]> for some class X,
86:          * an instance of type X[] will be returned for each row. The elements of
87:          * the array will correspond to the arguments of the multiselect method, in
88:          * the specified order.
89:          *
90:          * If the type of the criteria query is CriteriaQuery<Object> or if the
91:          * criteria query was created without specifying a type, and only a single
92:          * argument is passed to the multiselect method, an instance of type Object
93:          * will be returned for each row.
94:          *
95:          * If the type of the criteria query is CriteriaQuery<Object> or if the
96:          * criteria query was created without specifying a type, and more than one
97:          * argument is passed to the multiselect method, an instance of type
98:          * Object[] will be instantiated and returned for each row. The elements of
99:          * the array will correspond to the arguments to the multiselect method, in
100:          * the specified order.
101:          *
102:          * @param selections
103:          * selection items corresponding to the
104:          *
105:          * results to be returned by the query
106:          * @return the modified query
107:          * @throws IllegalArgumentException
108:          * if a selection item is
109:          *
110:          * not valid or if more than one selection item has
111:          *
112:          * the same assigned alias
113:          */
114:         CriteriaQuery<T> multiselect(Selection<?>... selections);
115:
116:         /**
117:          * Specify the selection items that are to be returned in the query result.
118:          * Replaces the previously specified selection(s), if any.
119:          *
120:          * The type of the result of the query execution depends on the
121:          * specification of the type of the criteria query object created as well as
122:          * the argument to the multiselect method. An element of the list passed to
123:          * the multiselect method must not be a tuple- or array-valued compound
124:          * selection item.
125:          *
126:          * The semantics of this method are as follows:
127:          *
128:          * If the type of the criteria query is CriteriaQuery<Tuple> (i.e., a
129:          * criteria query object created by either the createTupleQuery method or by
130:          * passing a Tuple class argument to the createQuery method), a Tuple object
131:          * corresponding to the elements of the list passed to the multiselect
132:          * method, in the specified order, will be instantiated and returned for
133:          * each row that results from the query execution.
134:          *
135:          * If the type of the criteria query is CriteriaQuery<X> for some
136:          * user-defined class X (i.e., a criteria query object created by passing a
137:          * X class argument to the createQuery method), the elements of the list
138:          * passed to the multiselect method will be passed to the X constructor and
139:          * an instance of type X will be returned for each row.
140:          *
141:          * If the type of the criteria query is CriteriaQuery<X[]> for some class X,
142:          * an instance of type X[] will be returned for each row. The elements of
143:          * the array will correspond to the elements of the list passed to the
144:          * multiselect method, in the specified order.
145:          *
146:          * If the type of the criteria query is CriteriaQuery<Object> or if the
147:          * criteria query was created without specifying a type, and the list passed
148:          * to the multiselect method contains only a single element, an instance of
149:          * type Object will be returned for each row.
150:          *
151:          * If the type of the criteria query is CriteriaQuery<Object> or if the
152:          * criteria query was created without specifying a type, and the list passed
153:          * to the multiselect method contains more than one element, an instance of
154:          * type Object[] will be instantiated and returned for each row. The
155:          * elements of the array will correspond to the elements of the list passed
156:          * to the multiselect method, in the specified order.
157:          *
158:          * @param selectionList
159:          * list of selection items corresponding
160:          *
161:          * to the results to be returned by the query
162:          * @return the modified query
163:          * @throws IllegalArgumentException
164:          * if a selection item is
165:          *
166:          * not valid or if more than one selection item has
167:          *
168:          * the same assigned alias
169:          */
170:         CriteriaQuery<T> multiselect(List<Selection<?>> selectionList);
171:
172:         /**
173:          * Modify the query to restrict the query result according to the specified
174:          * boolean expression. Replaces the previously added restriction(s), if any.
175:          * This method only overrides the return type of the corresponding
176:          * AbstractQuery method.
177:          *
178:          * @param restriction
179:          * a simple or compound boolean expression
180:          * @return the modified query
181:          */
182:         CriteriaQuery<T> where(Expression<Boolean> restriction);
183:
184:         /**
185:          * Modify the query to restrict the query result according to the
186:          * conjunction of the specified restriction predicates. Replaces the
187:          * previously added restriction(s), if any. If no restrictions are
188:          * specified, any previously added restrictions are simply removed. This
189:          * method only overrides the return type of the corresponding AbstractQuery
190:          * method.
191:          *
192:          * @param restrictions
193:          * zero or more restriction predicates
194:          * @return the modified query
195:          */
196:         CriteriaQuery<T> where(Predicate... restrictions);
197:
198:         /**
199:          * Specify the expressions that are used to form groups over the query
200:          * results. Replaces the previous specified grouping expressions, if any. If
201:          * no grouping expressions are specified, any previously added grouping
202:          * expressions are simply removed. This method only overrides the return
203:          * type of the corresponding AbstractQuery method.
204:          *
205:          * @param grouping
206:          * zero or more grouping expressions
207:          * @return the modified query
208:          */
209:         CriteriaQuery<T> groupBy(Expression<?>... grouping);
210:
211:         /**
212:          * Specify the expressions that are used to form groups over the query
213:          * results. Replaces the previous specified grouping expressions, if any. If
214:          * no grouping expressions are specified, any previously added grouping
215:          * expressions are simply removed. This method only overrides the return
216:          * type of the corresponding AbstractQuery method.
217:          *
218:          * @param grouping
219:          * list of zero or more grouping expressions
220:          * @return the modified query
221:          */
222:         CriteriaQuery<T> groupBy(List<Expression<?>> grouping);
223:
224:         /**
225:          * Specify a restriction over the groups of the query. Replaces the previous
226:          * having restriction(s), if any. This method only overrides the return type
227:          * of the corresponding AbstractQuery method.
228:          *
229:          * @param restriction
230:          * a simple or compound boolean expression
231:          * @return the modified query
232:          */
233:         CriteriaQuery<T> having(Expression<Boolean> restriction);
234:
235:         /**
236:          * Specify restrictions over the groups of the query according the
237:          * conjunction of the specified restriction predicates. Replaces the
238:          * previously added having restriction(s), if any. If no restrictions are
239:          * specified, any previously added restrictions are simply removed. This
240:          * method only overrides the return type of the corresponding AbstractQuery
241:          * method.
242:          *
243:          * @param restrictions
244:          * zero or more restriction predicates
245:          * @return the modified query
246:          */
247:         CriteriaQuery<T> having(Predicate... restrictions);
248:
249:         /**
250:          * Specify the ordering expressions that are used to order the query
251:          * results. Replaces the previous ordering expressions, if any. If no
252:          * ordering expressions are specified, the previous ordering, if any, is
253:          * simply removed, and results will be returned in no particular order. The
254:          * left-to-right sequence of the ordering expressions determines the
255:          * precedence, whereby the leftmost has highest precedence.
256:          *
257:          * @param o
258:          * zero or more ordering expressions
259:          * @return the modified query
260:          */
261:         CriteriaQuery<T> orderBy(Order... o);
262:
263:         /**
264:          * Specify the ordering expressions that are used to order the query
265:          * results. Replaces the previous ordering expressions, if any. If no
266:          * ordering expressions are specified, the previous ordering, if any, is
267:          * simply removed, and results will be returned in no particular order. The
268:          * order of the ordering expressions in the list determines the precedence,
269:          * whereby the first element in the list has highest precedence.
270:          *
271:          * @param o
272:          * list of zero or more ordering expressions
273:          * @return the modified query
274:          */
275:         CriteriaQuery<T> orderBy(List<Order> o);
276:
277:         /**
278:          * Specify whether duplicate query results will be eliminated. A true value
279:          * will cause duplicates to be eliminated. A false value will cause
280:          * duplicates to be retained. If distinct has not been specified, duplicate
281:          * results must be retained. This method only overrides the return type of
282:          * the corresponding AbstractQuery method.
283:          *
284:          * @param distinct
285:          * boolean value specifying whether duplicate
286:          *
287:          * results must be eliminated from the query result or
288:          *
289:          * whether they must be retained
290:          * @return the modified query.
291:          */
292:         CriteriaQuery<T> distinct(boolean distinct);
293:
294:         /**
295:          * Return the ordering expressions in order of precedence. Returns empty
296:          * list if no ordering expressions have been specified. Modifications to the
297:          * list do not affect the query.
298:          *
299:          * @return the list of ordering expressions
300:          */
301:         List<Order> getOrderList();
302:
303:         /**
304:          * Return the parameters of the query. Returns empty set if there are no
305:          * parameters. Modifications to the set do not affect the query.
306:          *
307:          * @return the query parameters
308:          */
309:         Set<ParameterExpression<?>> getParameters();
310: }