WebSVN - WebE - Blame - Rev 33 - /trunk/src/org/hibernate/Criteria.java

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	}

Subversion Repositories WebE

(root)/trunk/src/org/hibernate/Criteria.java - Rev 33