001: //$Id: Criteria.java 9116 2006-01-23 21:21:01Z steveebersole $
002: package org.hibernate;
003:
004: import java.util.List;
005:
006: import org.hibernate.criterion.CriteriaSpecification;
007: import org.hibernate.criterion.Criterion;
008: import org.hibernate.criterion.Order;
009: import org.hibernate.criterion.Projection;
010: import org.hibernate.transform.ResultTransformer;
011:
012: /**
013: * <tt>Criteria</tt> is a simplified API for retrieving entities
014: * by composing <tt>Criterion</tt> objects. This is a very
015: * convenient approach for functionality like "search" screens
016: * where there is a variable number of conditions to be placed
017: * upon the result set.<br>
018: * <br>
019: * The <tt>Session</tt> is a factory for <tt>Criteria</tt>.
020: * <tt>Criterion</tt> instances are usually obtained via
021: * the factory methods on <tt>Restrictions</tt>. eg.
022: * <pre>
023: * List cats = session.createCriteria(Cat.class)
024: * .add( Restrictions.like("name", "Iz%") )
025: * .add( Restrictions.gt( "weight", new Float(minWeight) ) )
026: * .addOrder( Order.asc("age") )
027: * .list();
028: * </pre>
029: * You may navigate associations using <tt>createAlias()</tt> or
030: * <tt>createCriteria()</tt>.
031: * <pre>
032: * List cats = session.createCriteria(Cat.class)
033: * .createCriteria("kittens")
034: * .add( Restrictions.like("name", "Iz%") )
035: * .list();
036: * </pre>
037: * <pre>
038: * List cats = session.createCriteria(Cat.class)
039: * .createAlias("kittens", "kit")
040: * .add( Restrictions.like("kit.name", "Iz%") )
041: * .list();
042: * </pre>
043: * You may specify projection and aggregation using <tt>Projection</tt>
044: * instances obtained via the factory methods on <tt>Projections</tt>.
045: * <pre>
046: * List cats = session.createCriteria(Cat.class)
047: * .setProjection( Projections.projectionList()
048: * .add( Projections.rowCount() )
049: * .add( Projections.avg("weight") )
050: * .add( Projections.max("weight") )
051: * .add( Projections.min("weight") )
052: * .add( Projections.groupProperty("color") )
053: * )
054: * .addOrder( Order.asc("color") )
055: * .list();
056: * </pre>
057: *
058: * @see Session#createCriteria(java.lang.Class)
059: * @see org.hibernate.criterion.Restrictions
060: * @see org.hibernate.criterion.Projections
061: * @see org.hibernate.criterion.Order
062: * @see org.hibernate.criterion.Criterion
063: * @see org.hibernate.criterion.Projection
064: * @see org.hibernate.criterion.DetachedCriteria a disconnected version of this API
065: * @author Gavin King
066: */
067: public interface Criteria extends CriteriaSpecification {
068:
069: /**
070: * Get the alias of the entity encapsulated by this criteria instance.
071: *
072: * @return The alias for the encapsulated entity.
073: */
074: public String getAlias();
075:
076: /**
077: * Used to specify that the query results will be a projection (scalar in
078: * nature). Implicitly specifies the {@link #PROJECTION} result transformer.
079: * <p/>
080: * The individual components contained within the given
081: * {@link Projection projection} determines the overall "shape" of the
082: * query result.
083: *
084: * @param projection The projection representing the overall "shape" of the
085: * query results.
086: * @return this (for method chaining)
087: */
088: public Criteria setProjection(Projection projection);
089:
090: /**
091: * Add a {@link Criterion restriction} to constrain the results to be
092: * retrieved.
093: *
094: * @param criterion The {@link Criterion criterion} object representing the
095: * restriction to be applied.
096: * @return this (for method chaining)
097: */
098: public Criteria add(Criterion criterion);
099:
100: /**
101: * Add an {@link Order ordering} to the result set.
102: *
103: * @param order The {@link Order order} object representing an ordering
104: * to be applied to the results.
105: * @return this (for method chaining)
106: */
107: public Criteria addOrder(Order order);
108:
109: /**
110: * Specify an association fetching strategy for an association or a
111: * collection of values.
112: *
113: * @param associationPath a dot seperated property path
114: * @param mode The fetch mode for the referenced association
115: * @return this (for method chaining)
116: */
117: public Criteria setFetchMode(String associationPath, FetchMode mode)
118: throws HibernateException;
119:
120: /**
121: * Set the lock mode of the current entity
122: *
123: * @param lockMode The lock mode to be applied
124: * @return this (for method chaining)
125: */
126: public Criteria setLockMode(LockMode lockMode);
127:
128: /**
129: * Set the lock mode of the aliased entity
130: *
131: * @param alias The previously assigned alias representing the entity to
132: * which the given lock mode should apply.
133: * @param lockMode The lock mode to be applied
134: * @return this (for method chaining)
135: */
136: public Criteria setLockMode(String alias, LockMode lockMode);
137:
138: /**
139: * Join an association, assigning an alias to the joined association.
140: * <p/>
141: * Functionally equivalent to {@link #createAlias(String, String, int)} using
142: * {@link #INNER_JOIN} for the joinType.
143: *
144: * @param associationPath A dot-seperated property path
145: * @param alias The alias to assign to the joined association (for later reference).
146: * @return this (for method chaining)
147: */
148: public Criteria createAlias(String associationPath, String alias)
149: throws HibernateException;
150:
151: /**
152: * Join an association using the specified join-type, assigning an alias
153: * to the joined association.
154: * <p/>
155: * The joinType is expected to be one of {@link #INNER_JOIN} (the default),
156: * {@link #FULL_JOIN}, or {@link #LEFT_JOIN}.
157: *
158: * @param associationPath A dot-seperated property path
159: * @param alias The alias to assign to the joined association (for later reference).
160: * @param joinType The type of join to use.
161: * @return this (for method chaining)
162: */
163: public Criteria createAlias(String associationPath, String alias,
164: int joinType) throws HibernateException;
165:
166: /**
167: * Create a new <tt>Criteria</tt>, "rooted" at the associated entity.
168: * <p/>
169: * Functionally equivalent to {@link #createCriteria(String, int)} using
170: * {@link #INNER_JOIN} for the joinType.
171: *
172: * @param associationPath A dot-seperated property path
173: * @return the created "sub criteria"
174: */
175: public Criteria createCriteria(String associationPath)
176: throws HibernateException;
177:
178: /**
179: * Create a new <tt>Criteria</tt>, "rooted" at the associated entity, using the
180: * specified join type.
181: *
182: * @param associationPath A dot-seperated property path
183: * @param joinType The type of join to use.
184: * @return the created "sub criteria"
185: */
186: public Criteria createCriteria(String associationPath, int joinType)
187: throws HibernateException;
188:
189: /**
190: * Create a new <tt>Criteria</tt>, "rooted" at the associated entity,
191: * assigning the given alias.
192: * <p/>
193: * Functionally equivalent to {@link #createCriteria(String, String, int)} using
194: * {@link #INNER_JOIN} for the joinType.
195: *
196: * @param associationPath A dot-seperated property path
197: * @param alias The alias to assign to the joined association (for later reference).
198: * @return the created "sub criteria"
199: */
200: public Criteria createCriteria(String associationPath, String alias)
201: throws HibernateException;
202:
203: /**
204: * Create a new <tt>Criteria</tt>, "rooted" at the associated entity,
205: * assigning the given alias and using the specified join type.
206: *
207: * @param associationPath A dot-seperated property path
208: * @param alias The alias to assign to the joined association (for later reference).
209: * @param joinType The type of join to use.
210: * @return the created "sub criteria"
211: */
212: public Criteria createCriteria(String associationPath,
213: String alias, int joinType) throws HibernateException;
214:
215: /**
216: * Set a strategy for handling the query results. This determines the
217: * "shape" of the query result.
218: *
219: * @param resultTransformer The transformer to apply
220: * @return this (for method chaining)
221: *
222: * @see #ROOT_ENTITY
223: * @see #DISTINCT_ROOT_ENTITY
224: * @see #ALIAS_TO_ENTITY_MAP
225: * @see #PROJECTION
226: */
227: public Criteria setResultTransformer(
228: ResultTransformer resultTransformer);
229:
230: /**
231: * Set a limit upon the number of objects to be retrieved.
232: *
233: * @param maxResults the maximum number of results
234: * @return this (for method chaining)
235: */
236: public Criteria setMaxResults(int maxResults);
237:
238: /**
239: * Set the first result to be retrieved.
240: *
241: * @param firstResult the first result to retrieve, numbered from <tt>0</tt>
242: * @return this (for method chaining)
243: */
244: public Criteria setFirstResult(int firstResult);
245:
246: /**
247: * Set a fetch size for the underlying JDBC query.
248: *
249: * @param fetchSize the fetch size
250: * @return this (for method chaining)
251: *
252: * @see java.sql.Statement#setFetchSize
253: */
254: public Criteria setFetchSize(int fetchSize);
255:
256: /**
257: * Set a timeout for the underlying JDBC query.
258: *
259: * @param timeout The timeout value to apply.
260: * @return this (for method chaining)
261: *
262: * @see java.sql.Statement#setQueryTimeout
263: */
264: public Criteria setTimeout(int timeout);
265:
266: /**
267: * Enable caching of this query result, provided query caching is enabled
268: * for the underlying session factory.
269: *
270: * @param cacheable Should the result be considered cacheable; default is
271: * to not cache (false).
272: * @return this (for method chaining)
273: */
274: public Criteria setCacheable(boolean cacheable);
275:
276: /**
277: * Set the name of the cache region to use for query result caching.
278: *
279: * @param cacheRegion the name of a query cache region, or <tt>null</tt>
280: * for the default query cache
281: * @return this (for method chaining)
282: *
283: * @see #setCacheable
284: */
285: public Criteria setCacheRegion(String cacheRegion);
286:
287: /**
288: * Add a comment to the generated SQL.
289: *
290: * @param comment a human-readable string
291: * @return this (for method chaining)
292: */
293: public Criteria setComment(String comment);
294:
295: /**
296: * Override the flush mode for this particular query.
297: *
298: * @param flushMode The flush mode to use.
299: * @return this (for method chaining)
300: */
301: public Criteria setFlushMode(FlushMode flushMode);
302:
303: /**
304: * Override the cache mode for this particular query.
305: *
306: * @param cacheMode The cache mode to use.
307: * @return this (for method chaining)
308: */
309: public Criteria setCacheMode(CacheMode cacheMode);
310:
311: /**
312: * Get the results.
313: *
314: * @return The list of matched query results.
315: */
316: public List list() throws HibernateException;
317:
318: /**
319: * Get the results as an instance of {@link ScrollableResults}
320: *
321: * @return The {@link ScrollableResults} representing the matched
322: * query results.
323: */
324: public ScrollableResults scroll() throws HibernateException;
325:
326: /**
327: * Get the results as an instance of {@link ScrollableResults} based on the
328: * given scroll mode.
329: *
330: * @param scrollMode Indicates the type of underlying database cursor to
331: * request.
332: * @return The {@link ScrollableResults} representing the matched
333: * query results.
334: */
335: public ScrollableResults scroll(ScrollMode scrollMode)
336: throws HibernateException;
337:
338: /**
339: * Convenience method to return a single instance that matches
340: * the query, or null if the query returns no results.
341: *
342: * @return the single result or <tt>null</tt>
343: * @throws HibernateException if there is more than one matching result
344: */
345: public Object uniqueResult() throws HibernateException;
346:
347: }
|