Package: AbstractQuery

AbstractQuery

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