Go to most recent revision | Details | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
33 | PointedEar | 1 | /* |
2 | * Hibernate, Relational Persistence for Idiomatic Java |
||
3 | * |
||
4 | * Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as |
||
5 | * indicated by the @author tags or express copyright attribution |
||
6 | * statements applied by the authors. All third-party contributions are |
||
7 | * distributed under license by Red Hat Middleware LLC. |
||
8 | * |
||
9 | * This copyrighted material is made available to anyone wishing to use, modify, |
||
10 | * copy, or redistribute it subject to the terms and conditions of the GNU |
||
11 | * Lesser General Public License, as published by the Free Software Foundation. |
||
12 | * |
||
13 | * This program is distributed in the hope that it will be useful, |
||
14 | * but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY |
||
15 | * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License |
||
16 | * for more details. |
||
17 | * |
||
18 | * You should have received a copy of the GNU Lesser General Public License |
||
19 | * along with this distribution; if not, write to: |
||
20 | * Free Software Foundation, Inc. |
||
21 | * 51 Franklin Street, Fifth Floor |
||
22 | * Boston, MA 02110-1301 USA |
||
23 | * |
||
24 | */ |
||
25 | package org.hibernate; |
||
26 | |||
27 | import java.util.List; |
||
28 | |||
29 | import org.hibernate.criterion.CriteriaSpecification; |
||
30 | import org.hibernate.criterion.Criterion; |
||
31 | import org.hibernate.criterion.Order; |
||
32 | import org.hibernate.criterion.Projection; |
||
33 | import org.hibernate.transform.ResultTransformer; |
||
34 | |||
35 | /** |
||
36 | * <tt>Criteria</tt> is a simplified API for retrieving entities |
||
37 | * by composing <tt>Criterion</tt> objects. This is a very |
||
38 | * convenient approach for functionality like "search" screens |
||
39 | * where there is a variable number of conditions to be placed |
||
40 | * upon the result set.<br> |
||
41 | * <br> |
||
42 | * The <tt>Session</tt> is a factory for <tt>Criteria</tt>. |
||
43 | * <tt>Criterion</tt> instances are usually obtained via |
||
44 | * the factory methods on <tt>Restrictions</tt>. eg. |
||
45 | * <pre> |
||
46 | * List cats = session.createCriteria(Cat.class) |
||
47 | * .add( Restrictions.like("name", "Iz%") ) |
||
48 | * .add( Restrictions.gt( "weight", new Float(minWeight) ) ) |
||
49 | * .addOrder( Order.asc("age") ) |
||
50 | * .list(); |
||
51 | * </pre> |
||
52 | * You may navigate associations using <tt>createAlias()</tt> or |
||
53 | * <tt>createCriteria()</tt>. |
||
54 | * <pre> |
||
55 | * List cats = session.createCriteria(Cat.class) |
||
56 | * .createCriteria("kittens") |
||
57 | * .add( Restrictions.like("name", "Iz%") ) |
||
58 | * .list(); |
||
59 | * </pre> |
||
60 | * <pre> |
||
61 | * List cats = session.createCriteria(Cat.class) |
||
62 | * .createAlias("kittens", "kit") |
||
63 | * .add( Restrictions.like("kit.name", "Iz%") ) |
||
64 | * .list(); |
||
65 | * </pre> |
||
66 | * You may specify projection and aggregation using <tt>Projection</tt> |
||
67 | * instances obtained via the factory methods on <tt>Projections</tt>. |
||
68 | * <pre> |
||
69 | * List cats = session.createCriteria(Cat.class) |
||
70 | * .setProjection( Projections.projectionList() |
||
71 | * .add( Projections.rowCount() ) |
||
72 | * .add( Projections.avg("weight") ) |
||
73 | * .add( Projections.max("weight") ) |
||
74 | * .add( Projections.min("weight") ) |
||
75 | * .add( Projections.groupProperty("color") ) |
||
76 | * ) |
||
77 | * .addOrder( Order.asc("color") ) |
||
78 | * .list(); |
||
79 | * </pre> |
||
80 | * |
||
81 | * @see Session#createCriteria(java.lang.Class) |
||
82 | * @see org.hibernate.criterion.Restrictions |
||
83 | * @see org.hibernate.criterion.Projections |
||
84 | * @see org.hibernate.criterion.Order |
||
85 | * @see org.hibernate.criterion.Criterion |
||
86 | * @see org.hibernate.criterion.Projection |
||
87 | * @see org.hibernate.criterion.DetachedCriteria a disconnected version of this API |
||
88 | * @author Gavin King |
||
89 | */ |
||
90 | public interface Criteria extends CriteriaSpecification { |
||
91 | |||
92 | /** |
||
93 | * Get the alias of the entity encapsulated by this criteria instance. |
||
94 | * |
||
95 | * @return The alias for the encapsulated entity. |
||
96 | */ |
||
97 | public String getAlias(); |
||
98 | |||
99 | /** |
||
100 | * Used to specify that the query results will be a projection (scalar in |
||
101 | * nature). Implicitly specifies the {@link #PROJECTION} result transformer. |
||
102 | * <p/> |
||
103 | * The individual components contained within the given |
||
104 | * {@link Projection projection} determines the overall "shape" of the |
||
105 | * query result. |
||
106 | * |
||
107 | * @param projection The projection representing the overall "shape" of the |
||
108 | * query results. |
||
109 | * @return this (for method chaining) |
||
110 | */ |
||
111 | public Criteria setProjection(Projection projection); |
||
112 | |||
113 | /** |
||
114 | * Add a {@link Criterion restriction} to constrain the results to be |
||
115 | * retrieved. |
||
116 | * |
||
117 | * @param criterion The {@link Criterion criterion} object representing the |
||
118 | * restriction to be applied. |
||
119 | * @return this (for method chaining) |
||
120 | */ |
||
121 | public Criteria add(Criterion criterion); |
||
122 | |||
123 | /** |
||
124 | * Add an {@link Order ordering} to the result set. |
||
125 | * |
||
126 | * @param order The {@link Order order} object representing an ordering |
||
127 | * to be applied to the results. |
||
128 | * @return this (for method chaining) |
||
129 | */ |
||
130 | public Criteria addOrder(Order order); |
||
131 | |||
132 | /** |
||
133 | * Specify an association fetching strategy for an association or a |
||
134 | * collection of values. |
||
135 | * |
||
136 | * @param associationPath a dot seperated property path |
||
137 | * @param mode The fetch mode for the referenced association |
||
138 | * @return this (for method chaining) |
||
139 | */ |
||
140 | public Criteria setFetchMode(String associationPath, FetchMode mode) throws HibernateException; |
||
141 | |||
142 | /** |
||
143 | * Set the lock mode of the current entity |
||
144 | * |
||
145 | * @param lockMode The lock mode to be applied |
||
146 | * @return this (for method chaining) |
||
147 | */ |
||
148 | public Criteria setLockMode(LockMode lockMode); |
||
149 | |||
150 | /** |
||
151 | * Set the lock mode of the aliased entity |
||
152 | * |
||
153 | * @param alias The previously assigned alias representing the entity to |
||
154 | * which the given lock mode should apply. |
||
155 | * @param lockMode The lock mode to be applied |
||
156 | * @return this (for method chaining) |
||
157 | */ |
||
158 | public Criteria setLockMode(String alias, LockMode lockMode); |
||
159 | |||
160 | /** |
||
161 | * Join an association, assigning an alias to the joined association. |
||
162 | * <p/> |
||
163 | * Functionally equivalent to {@link #createAlias(String, String, int)} using |
||
164 | * {@link #INNER_JOIN} for the joinType. |
||
165 | * |
||
166 | * @param associationPath A dot-seperated property path |
||
167 | * @param alias The alias to assign to the joined association (for later reference). |
||
168 | * @return this (for method chaining) |
||
169 | */ |
||
170 | public Criteria createAlias(String associationPath, String alias) throws HibernateException; |
||
171 | |||
172 | /** |
||
173 | * Join an association using the specified join-type, assigning an alias |
||
174 | * to the joined association. |
||
175 | * <p/> |
||
176 | * The joinType is expected to be one of {@link #INNER_JOIN} (the default), |
||
177 | * {@link #FULL_JOIN}, or {@link #LEFT_JOIN}. |
||
178 | * |
||
179 | * @param associationPath A dot-seperated property path |
||
180 | * @param alias The alias to assign to the joined association (for later reference). |
||
181 | * @param joinType The type of join to use. |
||
182 | * @return this (for method chaining) |
||
183 | */ |
||
184 | public Criteria createAlias(String associationPath, String alias, int joinType) throws HibernateException; |
||
185 | |||
186 | /** |
||
187 | * Create a new <tt>Criteria</tt>, "rooted" at the associated entity. |
||
188 | * <p/> |
||
189 | * Functionally equivalent to {@link #createCriteria(String, int)} using |
||
190 | * {@link #INNER_JOIN} for the joinType. |
||
191 | * |
||
192 | * @param associationPath A dot-seperated property path |
||
193 | * @return the created "sub criteria" |
||
194 | */ |
||
195 | public Criteria createCriteria(String associationPath) throws HibernateException; |
||
196 | |||
197 | /** |
||
198 | * Create a new <tt>Criteria</tt>, "rooted" at the associated entity, using the |
||
199 | * specified join type. |
||
200 | * |
||
201 | * @param associationPath A dot-seperated property path |
||
202 | * @param joinType The type of join to use. |
||
203 | * @return the created "sub criteria" |
||
204 | */ |
||
205 | public Criteria createCriteria(String associationPath, int joinType) throws HibernateException; |
||
206 | |||
207 | /** |
||
208 | * Create a new <tt>Criteria</tt>, "rooted" at the associated entity, |
||
209 | * assigning the given alias. |
||
210 | * <p/> |
||
211 | * Functionally equivalent to {@link #createCriteria(String, String, int)} using |
||
212 | * {@link #INNER_JOIN} for the joinType. |
||
213 | * |
||
214 | * @param associationPath A dot-seperated property path |
||
215 | * @param alias The alias to assign to the joined association (for later reference). |
||
216 | * @return the created "sub criteria" |
||
217 | */ |
||
218 | public Criteria createCriteria(String associationPath, String alias) throws HibernateException; |
||
219 | |||
220 | /** |
||
221 | * Create a new <tt>Criteria</tt>, "rooted" at the associated entity, |
||
222 | * assigning the given alias and using the specified join type. |
||
223 | * |
||
224 | * @param associationPath A dot-seperated property path |
||
225 | * @param alias The alias to assign to the joined association (for later reference). |
||
226 | * @param joinType The type of join to use. |
||
227 | * @return the created "sub criteria" |
||
228 | */ |
||
229 | public Criteria createCriteria(String associationPath, String alias, int joinType) throws HibernateException; |
||
230 | |||
231 | /** |
||
232 | * Set a strategy for handling the query results. This determines the |
||
233 | * "shape" of the query result. |
||
234 | * |
||
235 | * @param resultTransformer The transformer to apply |
||
236 | * @return this (for method chaining) |
||
237 | * |
||
238 | * @see #ROOT_ENTITY |
||
239 | * @see #DISTINCT_ROOT_ENTITY |
||
240 | * @see #ALIAS_TO_ENTITY_MAP |
||
241 | * @see #PROJECTION |
||
242 | */ |
||
243 | public Criteria setResultTransformer(ResultTransformer resultTransformer); |
||
244 | |||
245 | /** |
||
246 | * Set a limit upon the number of objects to be retrieved. |
||
247 | * |
||
248 | * @param maxResults the maximum number of results |
||
249 | * @return this (for method chaining) |
||
250 | */ |
||
251 | public Criteria setMaxResults(int maxResults); |
||
252 | |||
253 | /** |
||
254 | * Set the first result to be retrieved. |
||
255 | * |
||
256 | * @param firstResult the first result to retrieve, numbered from <tt>0</tt> |
||
257 | * @return this (for method chaining) |
||
258 | */ |
||
259 | public Criteria setFirstResult(int firstResult); |
||
260 | |||
261 | /** |
||
262 | * Set a fetch size for the underlying JDBC query. |
||
263 | * |
||
264 | * @param fetchSize the fetch size |
||
265 | * @return this (for method chaining) |
||
266 | * |
||
267 | * @see java.sql.Statement#setFetchSize |
||
268 | */ |
||
269 | public Criteria setFetchSize(int fetchSize); |
||
270 | |||
271 | /** |
||
272 | * Set a timeout for the underlying JDBC query. |
||
273 | * |
||
274 | * @param timeout The timeout value to apply. |
||
275 | * @return this (for method chaining) |
||
276 | * |
||
277 | * @see java.sql.Statement#setQueryTimeout |
||
278 | */ |
||
279 | public Criteria setTimeout(int timeout); |
||
280 | |||
281 | /** |
||
282 | * Enable caching of this query result, provided query caching is enabled |
||
283 | * for the underlying session factory. |
||
284 | * |
||
285 | * @param cacheable Should the result be considered cacheable; default is |
||
286 | * to not cache (false). |
||
287 | * @return this (for method chaining) |
||
288 | */ |
||
289 | public Criteria setCacheable(boolean cacheable); |
||
290 | |||
291 | /** |
||
292 | * Set the name of the cache region to use for query result caching. |
||
293 | * |
||
294 | * @param cacheRegion the name of a query cache region, or <tt>null</tt> |
||
295 | * for the default query cache |
||
296 | * @return this (for method chaining) |
||
297 | * |
||
298 | * @see #setCacheable |
||
299 | */ |
||
300 | public Criteria setCacheRegion(String cacheRegion); |
||
301 | |||
302 | /** |
||
303 | * Add a comment to the generated SQL. |
||
304 | * |
||
305 | * @param comment a human-readable string |
||
306 | * @return this (for method chaining) |
||
307 | */ |
||
308 | public Criteria setComment(String comment); |
||
309 | |||
310 | /** |
||
311 | * Override the flush mode for this particular query. |
||
312 | * |
||
313 | * @param flushMode The flush mode to use. |
||
314 | * @return this (for method chaining) |
||
315 | */ |
||
316 | public Criteria setFlushMode(FlushMode flushMode); |
||
317 | |||
318 | /** |
||
319 | * Override the cache mode for this particular query. |
||
320 | * |
||
321 | * @param cacheMode The cache mode to use. |
||
322 | * @return this (for method chaining) |
||
323 | */ |
||
324 | public Criteria setCacheMode(CacheMode cacheMode); |
||
325 | |||
326 | /** |
||
327 | * Get the results. |
||
328 | * |
||
329 | * @return The list of matched query results. |
||
330 | */ |
||
331 | public List list() throws HibernateException; |
||
332 | |||
333 | /** |
||
334 | * Get the results as an instance of {@link ScrollableResults} |
||
335 | * |
||
336 | * @return The {@link ScrollableResults} representing the matched |
||
337 | * query results. |
||
338 | */ |
||
339 | public ScrollableResults scroll() throws HibernateException; |
||
340 | |||
341 | /** |
||
342 | * Get the results as an instance of {@link ScrollableResults} based on the |
||
343 | * given scroll mode. |
||
344 | * |
||
345 | * @param scrollMode Indicates the type of underlying database cursor to |
||
346 | * request. |
||
347 | * @return The {@link ScrollableResults} representing the matched |
||
348 | * query results. |
||
349 | */ |
||
350 | public ScrollableResults scroll(ScrollMode scrollMode) throws HibernateException; |
||
351 | |||
352 | /** |
||
353 | * Convenience method to return a single instance that matches |
||
354 | * the query, or null if the query returns no results. |
||
355 | * |
||
356 | * @return the single result or <tt>null</tt> |
||
357 | * @throws HibernateException if there is more than one matching result |
||
358 | */ |
||
359 | public Object uniqueResult() throws HibernateException; |
||
360 | |||
361 | } |