Package: AbstractQuery

AbstractQuery

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: import cz.cvut.kbss.jopa.model.metamodel.EntityType;
21:
22: /**
23: * The AbstractQuery interface defines functionality that is common to both
24: * top-level queries and subqueries. It is not intended to be used directly in
25: * query construction.
26: *
27: * All queries must have:
28: *
29: * a set of root entities (which may in turn own joins) All queries may have:
30: *
31: * a conjunction of restrictions
32: *
33: * @param <T>
34: * type of the result
35: */
36: public interface AbstractQuery<T> {
37:         /**
38:          * Create and add a query root corresponding to the given entity, forming a
39:          * cartesian product with any existing roots.
40:          *
41:          * @param entityClass
42:          * the entity class
43:          * @return query root corresponding to the given entity
44:          */
45:         <X> Root<X> from(Class<X> entityClass);
46:
47:         /**
48:          * Create and add a query root corresponding to the given entity, forming a
49:          * cartesian product with any existing roots.
50:          *
51:          * @param entity
52:          * metamodel entity representing the entity
53:          *
54:          * of type X
55:          * @return query root corresponding to the given entity
56:          */
57:         <X> Root<X> from(EntityType<X> entity);
58:
59:         /**
60:          * Modify the query to restrict the query results according to the specified
61:          * boolean expression. Replaces the previously added restriction(s), if any.
62:          *
63:          * @param restriction
64:          * a simple or compound boolean expression
65:          * @return the modified query
66:          */
67:         AbstractQuery<T> where(Expression<Boolean> restriction);
68:
69:         /**
70:          * Modify the query to restrict the query results according to the
71:          * conjunction of the specified restriction predicates. Replaces the
72:          * previously added restriction(s), if any. If no restrictions are
73:          * specified, any previously added restrictions are simply removed.
74:          *
75:          * @param restrictions
76:          * zero or more restriction predicates
77:          * @return the modified query
78:          */
79:         AbstractQuery<T> where(Predicate... restrictions);
80:
81:         /**
82:          * Specify the expressions that are used to form groups over the query
83:          * results. Replaces the previous specified grouping expressions, if any. If
84:          * no grouping expressions are specified, any previously added grouping
85:          * expressions are simply removed.
86:          *
87:          * @param grouping
88:          * zero or more grouping expressions
89:          * @return the modified query
90:          */
91:         AbstractQuery<T> groupBy(Expression<?>... grouping);
92:
93:         /**
94:          * Specify the expressions that are used to form groups over the query
95:          * results. Replaces the previous specified grouping expressions, if any. If
96:          * no grouping expressions are specified, any previously added grouping
97:          * expressions are simply removed.
98:          *
99:          * @param grouping
100:          * list of zero or more grouping expressions
101:          * @return the modified query
102:          */
103:         AbstractQuery<T> groupBy(List<Expression<?>> grouping);
104:
105:         /**
106:          * Specify a restriction over the groups of the query. Replaces the previous
107:          * having restriction(s), if any.
108:          *
109:          * @param restriction
110:          * a simple or compound boolean expression
111:          * @return the modified query
112:          */
113:         AbstractQuery<T> having(Expression<Boolean> restriction);
114:
115:         /**
116:          * Specify restrictions over the groups of the query according the
117:          * conjunction of the specified restriction predicates. Replaces the
118:          * previously added having restriction(s), if any. If no restrictions are
119:          * specified, any previously added restrictions are simply removed.
120:          *
121:          * @param restrictions
122:          * zero or more restriction predicates
123:          * @return the modified query
124:          */
125:         AbstractQuery<T> having(Predicate... restrictions);
126:
127:         /**
128:          * Specify whether duplicate query results will be eliminated. A true value
129:          * will cause duplicates to be eliminated. A false value will cause
130:          * duplicates to be retained. If distinct has not been specified, duplicate
131:          * results must be retained.
132:          *
133:          * @param distinct
134:          * boolean value specifying whether duplicate
135:          *
136:          * results must be eliminated from the query result or
137:          *
138:          * whether they must be retained
139:          * @return the modified query
140:          */
141:         AbstractQuery<T> distinct(boolean distinct);
142:
143:         /**
144:          * Create a subquery of the query.
145:          *
146:          * @param type
147:          * the subquery result type
148:          * @return subquery
149:          */
150:         <U> Subquery<U> subquery(Class<U> type);
151:
152:         /**
153:          * Return the query roots. These are the roots that have been defined for
154:          * the CriteriaQuery or Subquery itself, including any subquery roots
155:          * defined as a result of correlation. Returns empty set if no roots have
156:          * been defined. Modifications to the set do not affect the query.
157:          *
158:          * @return the set of query roots
159:          */
160:         Set<Root<?>> getRoots();
161:
162:         /**
163:          * Return the selection of the query, or null if no selection has been set.
164:          *
165:          * @return selection item
166:          */
167:         Selection<T> getSelection();
168:
169:         /**
170:          * Return the predicate that corresponds to the where clause restriction(s),
171:          * or null if no restrictions have been specified.
172:          *
173:          * @return where clause predicate
174:          */
175:         Predicate getRestriction();
176:
177:         /**
178:          * Return a list of the grouping expressions. Returns empty list if no
179:          * grouping expressions have been specified. Modifications to the list do
180:          * not affect the query.
181:          *
182:          * @return the list of grouping expressions
183:          */
184:         List<Expression<?>> getGroupList();
185:
186:         /**
187:          * Return the predicate that corresponds to the restriction(s) over the
188:          * grouping items, or null if no restrictions have been specified.
189:          *
190:          * @return having clause predicate
191:          */
192:         Predicate getGroupRestriction();
193:
194:         /**
195:          * Return whether duplicate query results must be eliminated or retained.
196:          *
197:          * @return boolean indicating whether duplicate query results
198:          *
199:          * must be eliminated
200:          */
201:         boolean isDistinct();
202:
203:         /**
204:          * Return the result type of the query or subquery. If a result type was
205:          * specified as an argument to the createQuery or subquery method, that type
206:          * will be returned. If the query was created using the createTupleQuery
207:          * method, the result type is Tuple. Otherwise, the result type is Object.
208:          *
209:          * @return result type
210:          */
211:         Class<T> getResultType();
212: }