Subversion Repositories WebE

Rev

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
}