KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > hibernate > Criteria


1 //$Id: Criteria.java,v 1.18 2005/04/29 15:13:02 oneovthafew Exp $
2 package org.hibernate;
3
4 import java.util.List JavaDoc;
5
6 import org.hibernate.criterion.CriteriaSpecification;
7 import org.hibernate.criterion.Criterion;
8 import org.hibernate.criterion.Order;
9 import org.hibernate.criterion.Projection;
10 import org.hibernate.transform.ResultTransformer;
11
12 /**
13  * <tt>Criteria</tt> is a simplified API for retrieving entities
14  * by composing <tt>Criterion</tt> objects. This is a very
15  * convenient approach for functionality like "search" screens
16  * where there is a variable number of conditions to be placed
17  * upon the result set.<br>
18  * <br>
19  * The <tt>Session</tt> is a factory for <tt>Criteria</tt>.
20  * <tt>Criterion</tt> instances are usually obtained via
21  * the factory methods on <tt>Restrictions</tt>. eg.
22  * <pre>
23  * List cats = session.createCriteria(Cat.class)
24  * .add( Restrictions.like("name", "Iz%") )
25  * .add( Restrictions.gt( "weight", new Float(minWeight) ) )
26  * .addOrder( Order.asc("age") )
27  * .list();
28  * </pre>
29  * You may navigate associations using <tt>createAlias()</tt> or
30  * <tt>createCriteria()</tt>.
31  * <pre>
32  * List cats = session.createCriteria(Cat.class)
33  * .createCriteria("kittens")
34  * .add( Restrictions.like("name", "Iz%") )
35  * .list();
36  * </pre>
37  * <pre>
38  * List cats = session.createCriteria(Cat.class)
39  * .createAlias("kittens", "kit")
40  * .add( Restrictions.like("kit.name", "Iz%") )
41  * .list();
42  * </pre>
43  * You may specify projection and aggregation using <tt>Projection</tt>
44  * instances obtained via the factory methods on <tt>Projections</tt>.
45  * <pre>
46  * List cats = session.createCriteria(Cat.class)
47  * .setProjection( Projections.projectionList()
48  * .add( Projections.rowCount() )
49  * .add( Projections.avg("weight") )
50  * .add( Projections.max("weight") )
51  * .add( Projections.min("weight") )
52  * .add( Projections.groupProperty("color") )
53  * )
54  * .addOrder( Order.asc("color") )
55  * .list();
56  * </pre>
57  *
58  * @see Session#createCriteria(java.lang.Class)
59  * @see org.hibernate.criterion.Restrictions
60  * @see org.hibernate.criterion.Projections
61  * @see org.hibernate.criterion.Order
62  * @see org.hibernate.criterion.Criterion
63  * @see org.hibernate.criterion.Projection
64  * @see org.hibernate.DetachedCriteria a disconnected version of this API
65  * @author Gavin King
66  */
67 public interface Criteria extends CriteriaSpecification {
68
69     /**
70      * Add a <tt>Criterion</tt> to constrain the results to be
71      * retrieved.
72      *
73      * @param criterion
74      * @return Criteria
75      */
76     public Criteria add(Criterion criterion);
77     
78     /**
79      * Add an <tt>Order</tt> to the result set.
80      *
81      * @param order
82      * @return Criteria
83      */
84     public Criteria addOrder(Order order);
85
86     /**
87      * Specify an association fetching strategy for a
88      * one-to-many, many-to-one or one-to-one association, or
89      * for a collection of values.
90      *
91      * @param associationPath a dot seperated property path
92      * @param mode the fetch mode
93      * @return the Criteria object for method chaining
94      */
95     public Criteria setFetchMode(String JavaDoc associationPath, FetchMode mode) throws HibernateException;
96     /**
97      * Join an association, assigning an alias to the joined entity
98      */
99     public Criteria createAlias(String JavaDoc associationPath, String JavaDoc alias) throws HibernateException;
100
101     /**
102      * Create a new <tt>Criteria</tt>, "rooted" at the associated entity
103      */
104     public Criteria createCriteria(String JavaDoc associationPath) throws HibernateException;
105
106     /**
107      * Create a new <tt>Criteria</tt>, "rooted" at the associated entity,
108      * assigning the given alias
109      */
110     public Criteria createCriteria(String JavaDoc associationPath, String JavaDoc alias) throws HibernateException;
111
112     /**
113      * Set a projection of projection list, and select
114      * the <tt>PROJECTION</tt> result transformer
115      */
116     public Criteria setProjection(Projection projection);
117     
118     /**
119      * Get the alias of the entity
120      */
121     public String JavaDoc getAlias();
122
123     /**
124      * Set a strategy for handling the query results. This determines the
125      * "shape" of the query result set.
126      * @see Criteria#ROOT_ENTITY
127      * @see Criteria#DISTINCT_ROOT_ENTITY
128      * @see Criteria#ALIAS_TO_ENTITY_MAP
129      * @param resultTransformer
130      */
131     public Criteria setResultTransformer(ResultTransformer resultTransformer);
132
133     /**
134      * Set a limit upon the number of objects to be
135      * retrieved.
136      *
137      * @param maxResults the maximum number of results
138      * @return Criteria
139      */
140     public Criteria setMaxResults(int maxResults);
141     
142     /**
143      * Set the first result to be retrieved.
144      *
145      * @param firstResult the first result, numbered from <tt>0</tt>
146      * @return Criteria
147      */
148     public Criteria setFirstResult(int firstResult);
149     
150     /**
151      * Set a fetch size for the underlying JDBC query.
152      * @param fetchSize the fetch size
153      */
154     public Criteria setFetchSize(int fetchSize);
155
156     /**
157      * Set a timeout for the underlying JDBC query.
158      *
159      * @param timeout
160      * @return Criteria
161      */
162     public Criteria setTimeout(int timeout);
163
164     /**
165      * Enable caching of this query result set
166      */
167     public Criteria setCacheable(boolean cacheable);
168
169     /**
170      * Set the name of the cache region.
171      *
172      * @param cacheRegion the name of a query cache region, or <tt>null</tt>
173      * for the default query cache
174      */
175     public Criteria setCacheRegion(String JavaDoc cacheRegion);
176
177     /**
178      * Get the results.
179      *
180      * @return List
181      * @throws HibernateException
182      */
183     public List JavaDoc list() throws HibernateException;
184     
185     /**
186      * Get the results as an instance of <tt>ScrollableResults</tt>.
187      *
188      * @return ScrollableResults
189      * @throws HibernateException
190      */
191     public ScrollableResults scroll() throws HibernateException;
192
193     /**
194      * Get the results as an instance of <tt>ScrollableResults</tt>.
195      *
196      * @return ScrollableResults
197      * @throws HibernateException
198      */
199     public ScrollableResults scroll(ScrollMode scrollMode) throws HibernateException;
200
201     /**
202      * Convenience method to return a single instance that matches
203      * the query, or null if the query returns no results.
204      *
205      * @return the single result or <tt>null</tt>
206      * @throws HibernateException if there is more than one matching result
207      */
208     public Object JavaDoc uniqueResult() throws HibernateException;
209
210     /**
211      * Set the lock mode of the current entity
212      * @param lockMode the lock mode
213      */
214     public Criteria setLockMode(LockMode lockMode);
215     /**
216      * Set the lock mode of the aliased entity
217      * @param alias an alias
218      * @param lockMode the lock mode
219      */
220     public Criteria setLockMode(String JavaDoc alias, LockMode lockMode);
221
222     /**
223      * Add a comment to the generated SQL
224      * @param comment a human-readable string
225      */
226     public Criteria setComment(String JavaDoc comment);
227     
228     /**
229      * Override the flush mode
230      */
231     public Criteria setFlushMode(FlushMode flushMode);
232     
233     /**
234      * Override the cache mode
235      */
236     public Criteria setCacheMode(CacheMode cacheMode);
237     
238 }
Popular Tags