Package: CriteriaQuery

CriteriaQuery

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