WebSVN - WebE - Blame - Rev 33 - /trunk/src/org/hibernate/Session.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.io.Serializable;
		28	import java.sql.Connection;
		29
		30	import org.hibernate.jdbc.Work;
		31	import org.hibernate.stat.SessionStatistics;
		32
		33	/**
		34	* The main runtime interface between a Java application and Hibernate. This is the
		35	* central API class abstracting the notion of a persistence service.<br>
		36	* <br>
		37	* The lifecycle of a <tt>Session</tt> is bounded by the beginning and end of a logical
		38	* transaction. (Long transactions might span several database transactions.)<br>
		39	* <br>
		40	* The main function of the <tt>Session</tt> is to offer create, read and delete operations
		41	* for instances of mapped entity classes. Instances may exist in one of three states:<br>
		42	* <br>
		43	* <i>transient:</i> never persistent, not associated with any <tt>Session</tt><br>
		44	* <i>persistent:</i> associated with a unique <tt>Session</tt><br>
		45	* <i>detached:</i> previously persistent, not associated with any <tt>Session</tt><br>
		46	* <br>
		47	* Transient instances may be made persistent by calling <tt>save()</tt>,
		48	* <tt>persist()</tt> or <tt>saveOrUpdate()</tt>. Persistent instances may be made transient
		49	* by calling<tt> delete()</tt>. Any instance returned by a <tt>get()</tt> or
		50	* <tt>load()</tt> method is persistent. Detached instances may be made persistent
		51	* by calling <tt>update()</tt>, <tt>saveOrUpdate()</tt>, <tt>lock()</tt> or <tt>replicate()</tt>.
		52	* The state of a transient or detached instance may also be made persistent as a new
		53	* persistent instance by calling <tt>merge()</tt>.<br>
		54	* <br>
		55	* <tt>save()</tt> and <tt>persist()</tt> result in an SQL <tt>INSERT</tt>, <tt>delete()</tt>
		56	* in an SQL <tt>DELETE</tt> and <tt>update()</tt> or <tt>merge()</tt> in an SQL <tt>UPDATE</tt>.
		57	* Changes to <i>persistent</i> instances are detected at flush time and also result in an SQL
		58	* <tt>UPDATE</tt>. <tt>saveOrUpdate()</tt> and <tt>replicate()</tt> result in either an
		59	* <tt>INSERT</tt> or an <tt>UPDATE</tt>.<br>
		60	* <br>
		61	* It is not intended that implementors be threadsafe. Instead each thread/transaction
		62	* should obtain its own instance from a <tt>SessionFactory</tt>.<br>
		63	* <br>
		64	* A <tt>Session</tt> instance is serializable if its persistent classes are serializable.<br>
		65	* <br>
		66	* A typical transaction should use the following idiom:
		67	* <pre>
		68	* Session sess = factory.openSession();
		69	* Transaction tx;
		70	* try {
		71	* tx = sess.beginTransaction();
		72	* //do some work
		73	* ...
		74	* tx.commit();
		75	* }
		76	* catch (Exception e) {
		77	* if (tx!=null) tx.rollback();
		78	* throw e;
		79	* }
		80	* finally {
		81	* sess.close();
		82	* }
		83	* </pre>
		84	* <br>
		85	* If the <tt>Session</tt> throws an exception, the transaction must be rolled back
		86	* and the session discarded. The internal state of the <tt>Session</tt> might not
		87	* be consistent with the database after the exception occurs.
		88	*
		89	* @see SessionFactory
		90	* @author Gavin King
		91	*/
		92	public interface Session extends Serializable {
		93
		94	/**
		95	* Retrieve the entity mode in effect for this session.
		96	*
		97	* @return The entity mode for this session.
		98	*/
		99	public EntityMode getEntityMode();
		100
		101	/**
		102	* Starts a new Session with the given entity mode in effect. This secondary
		103	* Session inherits the connection, transaction, and other context
		104	* information from the primary Session. It doesn't need to be flushed
		105	* or closed by the developer.
		106	*
		107	* @param entityMode The entity mode to use for the new session.
		108	* @return The new session
		109	*/
		110	public Session getSession(EntityMode entityMode);
		111
		112	/**
		113	* Force this session to flush. Must be called at the end of a
		114	* unit of work, before commiting the transaction and closing the
		115	* session (depending on {@link #setFlushMode flush-mode},
		116	* {@link Transaction#commit()} calls this method).
		117	* <p/>
		118	* <i>Flushing</i> is the process of synchronizing the underlying persistent
		119	* store with persistable state held in memory.
		120	*
		121	* @throws HibernateException Indicates problems flushing the session or
		122	* talking to the database.
		123	*/
		124	public void flush() throws HibernateException;
		125
		126	/**
		127	* Set the flush mode for this session.
		128	* <p/>
		129	* The flush mode determines the points at which the session is flushed.
		130	* <i>Flushing</i> is the process of synchronizing the underlying persistent
		131	* store with persistable state held in memory.
		132	* <p/>
		133	* For a logically "read only" session, it is reasonable to set the session's
		134	* flush mode to {@link FlushMode#MANUAL} at the start of the session (in
		135	* order to achieve some extra performance).
		136	*
		137	* @param flushMode the new flush mode
		138	* @see FlushMode
		139	*/
		140	public void setFlushMode(FlushMode flushMode);
		141
		142	/**
		143	* Get the current flush mode for this session.
		144	*
		145	* @return The flush mode
		146	*/
		147	public FlushMode getFlushMode();
		148
		149	/**
		150	* Set the cache mode.
		151	* <p/>
		152	* Cache mode determines the manner in which this session can interact with
		153	* the second level cache.
		154	*
		155	* @param cacheMode The new cache mode.
		156	*/
		157	public void setCacheMode(CacheMode cacheMode);
		158
		159	/**
		160	* Get the current cache mode.
		161	*
		162	* @return The current cache mode.
		163	*/
		164	public CacheMode getCacheMode();
		165
		166	/**
		167	* Get the session factory which created this session.
		168	*
		169	* @return The session factory.
		170	* @see SessionFactory
		171
		172	*/
		173	public SessionFactory getSessionFactory();
		174
		175	/**
		176	* Get the JDBC connection of this Session.<br>
		177	* <br>
		178	* If the session is using aggressive collection release (as in a
		179	* CMT environment), it is the application's responsibility to
		180	* close the connection returned by this call. Otherwise, the
		181	* application should not close the connection.
		182	*
		183	* @return the JDBC connection in use by the <tt>Session</tt>
		184	* @throws HibernateException if the <tt>Session</tt> is disconnected
		185	* @deprecated (scheduled for removal in 4.x). Replacement depends on need; for doing direct JDBC stuff use
		186	* {@link #doWork}; for opening a 'temporary Session' use (TBD).
		187	*/
		188	public Connection connection() throws HibernateException;
		189
		190	/**
		191	* End the session by releasing the JDBC connection and cleaning up. It is
		192	* not strictly necessary to close the session but you must at least
		193	* {@link #disconnect()} it.
		194	*
		195	* @return the connection provided by the application or null.
		196	* @throws HibernateException Indicates problems cleaning up.
		197	*/
		198	public Connection close() throws HibernateException;
		199
		200	/**
		201	* Cancel the execution of the current query.
		202	* <p/>
		203	* This is the sole method on session which may be safely called from
		204	* another thread.
		205	*
		206	* @throws HibernateException There was a problem canceling the query
		207	*/
		208	public void cancelQuery() throws HibernateException;
		209
		210	/**
		211	* Check if the session is still open.
		212	*
		213	* @return boolean
		214	*/
		215	public boolean isOpen();
		216
		217	/**
		218	* Check if the session is currently connected.
		219	*
		220	* @return boolean
		221	*/
		222	public boolean isConnected();
		223
		224	/**
		225	* Does this session contain any changes which must be synchronized with
		226	* the database? In other words, would any DML operations be executed if
		227	* we flushed this session?
		228	*
		229	* @return True if the session contains pending changes; false otherwise.
		230	* @throws HibernateException could not perform dirtying checking
		231	*/
		232	public boolean isDirty() throws HibernateException;
		233
		234	/**
		235	* Return the identifier value of the given entity as associated with this
		236	* session. An exception is thrown if the given entity instance is transient
		237	* or detached in relation to this session.
		238	*
		239	* @param object a persistent instance
		240	* @return the identifier
		241	* @throws TransientObjectException if the instance is transient or associated with
		242	* a different session
		243	*/
		244	public Serializable getIdentifier(Object object) throws HibernateException;
		245
		246	/**
		247	* Check if this instance is associated with this <tt>Session</tt>.
		248	*
		249	* @param object an instance of a persistent class
		250	* @return true if the given instance is associated with this <tt>Session</tt>
		251	*/
		252	public boolean contains(Object object);
		253
		254	/**
		255	* Remove this instance from the session cache. Changes to the instance will
		256	* not be synchronized with the database. This operation cascades to associated
		257	* instances if the association is mapped with <tt>cascade="evict"</tt>.
		258	*
		259	* @param object a persistent instance
		260	* @throws HibernateException
		261	*/
		262	public void evict(Object object) throws HibernateException;
		263
		264	/**
		265	* Return the persistent instance of the given entity class with the given identifier,
		266	* obtaining the specified lock mode, assuming the instance exists.
		267	*
		268	* @param theClass a persistent class
		269	* @param id a valid identifier of an existing persistent instance of the class
		270	* @param lockMode the lock level
		271	* @return the persistent instance or proxy
		272	* @throws HibernateException
		273	*/
		274	public Object load(Class theClass, Serializable id, LockMode lockMode) throws HibernateException;
		275
		276	/**
		277	* Return the persistent instance of the given entity class with the given identifier,
		278	* obtaining the specified lock mode, assuming the instance exists.
		279	*
		280	* @param entityName a persistent class
		281	* @param id a valid identifier of an existing persistent instance of the class
		282	* @param lockMode the lock level
		283	* @return the persistent instance or proxy
		284	* @throws HibernateException
		285	*/
		286	public Object load(String entityName, Serializable id, LockMode lockMode) throws HibernateException;
		287
		288	/**
		289	* Return the persistent instance of the given entity class with the given identifier,
		290	* assuming that the instance exists. This method might return a proxied instance that
		291	* is initialized on-demand, when a non-identifier method is accessed.
		292	* <br><br>
		293	* You should not use this method to determine if an instance exists (use <tt>get()</tt>
		294	* instead). Use this only to retrieve an instance that you assume exists, where non-existence
		295	* would be an actual error.
		296	*
		297	* @param theClass a persistent class
		298	* @param id a valid identifier of an existing persistent instance of the class
		299	* @return the persistent instance or proxy
		300	* @throws HibernateException
		301	*/
		302	public Object load(Class theClass, Serializable id) throws HibernateException;
		303
		304	/**
		305	* Return the persistent instance of the given entity class with the given identifier,
		306	* assuming that the instance exists. This method might return a proxied instance that
		307	* is initialized on-demand, when a non-identifier method is accessed.
		308	* <br><br>
		309	* You should not use this method to determine if an instance exists (use <tt>get()</tt>
		310	* instead). Use this only to retrieve an instance that you assume exists, where non-existence
		311	* would be an actual error.
		312	*
		313	* @param entityName a persistent class
		314	* @param id a valid identifier of an existing persistent instance of the class
		315	* @return the persistent instance or proxy
		316	* @throws HibernateException
		317	*/
		318	public Object load(String entityName, Serializable id) throws HibernateException;
		319
		320	/**
		321	* Read the persistent state associated with the given identifier into the given transient
		322	* instance.
		323	*
		324	* @param object an "empty" instance of the persistent class
		325	* @param id a valid identifier of an existing persistent instance of the class
		326	* @throws HibernateException
		327	*/
		328	public void load(Object object, Serializable id) throws HibernateException;
		329
		330	/**
		331	* Persist the state of the given detached instance, reusing the current
		332	* identifier value. This operation cascades to associated instances if
		333	* the association is mapped with <tt>cascade="replicate"</tt>.
		334	*
		335	* @param object a detached instance of a persistent class
		336	*/
		337	public void replicate(Object object, ReplicationMode replicationMode) throws HibernateException;
		338
		339	/**
		340	* Persist the state of the given detached instance, reusing the current
		341	* identifier value. This operation cascades to associated instances if
		342	* the association is mapped with <tt>cascade="replicate"</tt>.
		343	*
		344	* @param object a detached instance of a persistent class
		345	*/
		346	public void replicate(String entityName, Object object, ReplicationMode replicationMode) throws HibernateException;
		347
		348	/**
		349	* Persist the given transient instance, first assigning a generated identifier. (Or
		350	* using the current value of the identifier property if the <tt>assigned</tt>
		351	* generator is used.) This operation cascades to associated instances if the
		352	* association is mapped with <tt>cascade="save-update"</tt>.
		353	*
		354	* @param object a transient instance of a persistent class
		355	* @return the generated identifier
		356	* @throws HibernateException
		357	*/
		358	public Serializable save(Object object) throws HibernateException;
		359
		360	/**
		361	* Persist the given transient instance, first assigning a generated identifier. (Or
		362	* using the current value of the identifier property if the <tt>assigned</tt>
		363	* generator is used.) This operation cascades to associated instances if the
		364	* association is mapped with <tt>cascade="save-update"</tt>.
		365	*
		366	* @param object a transient instance of a persistent class
		367	* @return the generated identifier
		368	* @throws HibernateException
		369	*/
		370	public Serializable save(String entityName, Object object) throws HibernateException;
		371
		372	/**
		373	* Either {@link #save(Object)} or {@link #update(Object)} the given
		374	* instance, depending upon resolution of the unsaved-value checks (see the
		375	* manual for discussion of unsaved-value checking).
		376	* <p/>
		377	* This operation cascades to associated instances if the association is mapped
		378	* with <tt>cascade="save-update"</tt>.
		379	*
		380	* @see Session#save(java.lang.Object)
		381	* @see Session#update(Object object)
		382	* @param object a transient or detached instance containing new or updated state
		383	* @throws HibernateException
		384	*/
		385	public void saveOrUpdate(Object object) throws HibernateException;
		386
		387	/**
		388	* Either {@link #save(String, Object)} or {@link #update(String, Object)}
		389	* the given instance, depending upon resolution of the unsaved-value checks
		390	* (see the manual for discussion of unsaved-value checking).
		391	* <p/>
		392	* This operation cascades to associated instances if the association is mapped
		393	* with <tt>cascade="save-update"</tt>.
		394	*
		395	* @see Session#save(String,Object)
		396	* @see Session#update(String,Object)
		397	* @param object a transient or detached instance containing new or updated state
		398	* @throws HibernateException
		399	*/
		400	public void saveOrUpdate(String entityName, Object object) throws HibernateException;
		401
		402	/**
		403	* Update the persistent instance with the identifier of the given detached
		404	* instance. If there is a persistent instance with the same identifier,
		405	* an exception is thrown. This operation cascades to associated instances
		406	* if the association is mapped with <tt>cascade="save-update"</tt>.
		407	*
		408	* @param object a detached instance containing updated state
		409	* @throws HibernateException
		410	*/
		411	public void update(Object object) throws HibernateException;
		412
		413	/**
		414	* Update the persistent instance with the identifier of the given detached
		415	* instance. If there is a persistent instance with the same identifier,
		416	* an exception is thrown. This operation cascades to associated instances
		417	* if the association is mapped with <tt>cascade="save-update"</tt>.
		418	*
		419	* @param object a detached instance containing updated state
		420	* @throws HibernateException
		421	*/
		422	public void update(String entityName, Object object) throws HibernateException;
		423
		424	/**
		425	* Copy the state of the given object onto the persistent object with the same
		426	* identifier. If there is no persistent instance currently associated with
		427	* the session, it will be loaded. Return the persistent instance. If the
		428	* given instance is unsaved, save a copy of and return it as a newly persistent
		429	* instance. The given instance does not become associated with the session.
		430	* This operation cascades to associated instances if the association is mapped
		431	* with <tt>cascade="merge"</tt>.<br>
		432	* <br>
		433	* The semantics of this method are defined by JSR-220.
		434	*
		435	* @param object a detached instance with state to be copied
		436	* @return an updated persistent instance
		437	*/
		438	public Object merge(Object object) throws HibernateException;
		439
		440	/**
		441	* Copy the state of the given object onto the persistent object with the same
		442	* identifier. If there is no persistent instance currently associated with
		443	* the session, it will be loaded. Return the persistent instance. If the
		444	* given instance is unsaved, save a copy of and return it as a newly persistent
		445	* instance. The given instance does not become associated with the session.
		446	* This operation cascades to associated instances if the association is mapped
		447	* with <tt>cascade="merge"</tt>.<br>
		448	* <br>
		449	* The semantics of this method are defined by JSR-220.
		450	*
		451	* @param object a detached instance with state to be copied
		452	* @return an updated persistent instance
		453	*/
		454	public Object merge(String entityName, Object object) throws HibernateException;
		455
		456	/**
		457	* Make a transient instance persistent. This operation cascades to associated
		458	* instances if the association is mapped with <tt>cascade="persist"</tt>.<br>
		459	* <br>
		460	* The semantics of this method are defined by JSR-220.
		461	*
		462	* @param object a transient instance to be made persistent
		463	*/
		464	public void persist(Object object) throws HibernateException;
		465	/**
		466	* Make a transient instance persistent. This operation cascades to associated
		467	* instances if the association is mapped with <tt>cascade="persist"</tt>.<br>
		468	* <br>
		469	* The semantics of this method are defined by JSR-220.
		470	*
		471	* @param object a transient instance to be made persistent
		472	*/
		473	public void persist(String entityName, Object object) throws HibernateException;
		474
		475	/**
		476	* Remove a persistent instance from the datastore. The argument may be
		477	* an instance associated with the receiving <tt>Session</tt> or a transient
		478	* instance with an identifier associated with existing persistent state.
		479	* This operation cascades to associated instances if the association is mapped
		480	* with <tt>cascade="delete"</tt>.
		481	*
		482	* @param object the instance to be removed
		483	* @throws HibernateException
		484	*/
		485	public void delete(Object object) throws HibernateException;
		486
		487	/**
		488	* Remove a persistent instance from the datastore. The <b>object</b> argument may be
		489	* an instance associated with the receiving <tt>Session</tt> or a transient
		490	* instance with an identifier associated with existing persistent state.
		491	* This operation cascades to associated instances if the association is mapped
		492	* with <tt>cascade="delete"</tt>.
		493	*
		494	* @param entityName The entity name for the instance to be removed.
		495	* @param object the instance to be removed
		496	* @throws HibernateException
		497	*/
		498	public void delete(String entityName, Object object) throws HibernateException;
		499
		500	/**
		501	* Obtain the specified lock level upon the given object. This may be used to
		502	* perform a version check (<tt>LockMode.READ</tt>), to upgrade to a pessimistic
		503	* lock (<tt>LockMode.UPGRADE</tt>), or to simply reassociate a transient instance
		504	* with a session (<tt>LockMode.NONE</tt>). This operation cascades to associated
		505	* instances if the association is mapped with <tt>cascade="lock"</tt>.
		506	*
		507	* @param object a persistent or transient instance
		508	* @param lockMode the lock level
		509	* @throws HibernateException
		510	*/
		511	public void lock(Object object, LockMode lockMode) throws HibernateException;
		512
		513	/**
		514	* Obtain the specified lock level upon the given object. This may be used to
		515	* perform a version check (<tt>LockMode.READ</tt>), to upgrade to a pessimistic
		516	* lock (<tt>LockMode.UPGRADE</tt>), or to simply reassociate a transient instance
		517	* with a session (<tt>LockMode.NONE</tt>). This operation cascades to associated
		518	* instances if the association is mapped with <tt>cascade="lock"</tt>.
		519	*
		520	* @param object a persistent or transient instance
		521	* @param lockMode the lock level
		522	* @throws HibernateException
		523	*/
		524	public void lock(String entityName, Object object, LockMode lockMode) throws HibernateException;
		525
		526	/**
		527	* Re-read the state of the given instance from the underlying database. It is
		528	* inadvisable to use this to implement long-running sessions that span many
		529	* business tasks. This method is, however, useful in certain special circumstances.
		530	* For example
		531	* <ul>
		532	* <li>where a database trigger alters the object state upon insert or update
		533	* <li>after executing direct SQL (eg. a mass update) in the same session
		534	* <li>after inserting a <tt>Blob</tt> or <tt>Clob</tt>
		535	* </ul>
		536	*
		537	* @param object a persistent or detached instance
		538	* @throws HibernateException
		539	*/
		540	public void refresh(Object object) throws HibernateException;
		541
		542	/**
		543	* Re-read the state of the given instance from the underlying database, with
		544	* the given <tt>LockMode</tt>. It is inadvisable to use this to implement
		545	* long-running sessions that span many business tasks. This method is, however,
		546	* useful in certain special circumstances.
		547	*
		548	* @param object a persistent or detached instance
		549	* @param lockMode the lock mode to use
		550	* @throws HibernateException
		551	*/
		552	public void refresh(Object object, LockMode lockMode) throws HibernateException;
		553
		554	/**
		555	* Determine the current lock mode of the given object.
		556	*
		557	* @param object a persistent instance
		558	* @return the current lock mode
		559	* @throws HibernateException
		560	*/
		561	public LockMode getCurrentLockMode(Object object) throws HibernateException;
		562
		563	/**
		564	* Begin a unit of work and return the associated <tt>Transaction</tt> object.
		565	* If a new underlying transaction is required, begin the transaction. Otherwise
		566	* continue the new work in the context of the existing underlying transaction.
		567	* The class of the returned <tt>Transaction</tt> object is determined by the
		568	* property <tt>hibernate.transaction_factory</tt>.
		569	*
		570	* @return a Transaction instance
		571	* @throws HibernateException
		572	* @see Transaction
		573	*/
		574	public Transaction beginTransaction() throws HibernateException;
		575
		576	/**
		577	* Get the <tt>Transaction</tt> instance associated with this session.
		578	* The class of the returned <tt>Transaction</tt> object is determined by the
		579	* property <tt>hibernate.transaction_factory</tt>.
		580	*
		581	* @return a Transaction instance
		582	* @throws HibernateException
		583	* @see Transaction
		584	*/
		585	public Transaction getTransaction();
		586
		587	/**
		588	* Create a new <tt>Criteria</tt> instance, for the given entity class,
		589	* or a superclass of an entity class.
		590	*
		591	* @param persistentClass a class, which is persistent, or has persistent subclasses
		592	* @return Criteria
		593	*/
		594	public Criteria createCriteria(Class persistentClass);
		595
		596	/**
		597	* Create a new <tt>Criteria</tt> instance, for the given entity class,
		598	* or a superclass of an entity class, with the given alias.
		599	*
		600	* @param persistentClass a class, which is persistent, or has persistent subclasses
		601	* @return Criteria
		602	*/
		603	public Criteria createCriteria(Class persistentClass, String alias);
		604
		605	/**
		606	* Create a new <tt>Criteria</tt> instance, for the given entity name.
		607	*
		608	* @param entityName
		609	* @return Criteria
		610	*/
		611	public Criteria createCriteria(String entityName);
		612
		613	/**
		614	* Create a new <tt>Criteria</tt> instance, for the given entity name,
		615	* with the given alias.
		616	*
		617	* @param entityName
		618	* @return Criteria
		619	*/
		620	public Criteria createCriteria(String entityName, String alias);
		621
		622	/**
		623	* Create a new instance of <tt>Query</tt> for the given HQL query string.
		624	*
		625	* @param queryString a HQL query
		626	* @return Query
		627	* @throws HibernateException
		628	*/
		629	public Query createQuery(String queryString) throws HibernateException;
		630
		631	/**
		632	* Create a new instance of <tt>SQLQuery</tt> for the given SQL query string.
		633	*
		634	* @param queryString a SQL query
		635	* @return SQLQuery
		636	* @throws HibernateException
		637	*/
		638	public SQLQuery createSQLQuery(String queryString) throws HibernateException;
		639
		640	/**
		641	* Create a new instance of <tt>Query</tt> for the given collection and filter string.
		642	*
		643	* @param collection a persistent collection
		644	* @param queryString a Hibernate query
		645	* @return Query
		646	* @throws HibernateException
		647	*/
		648	public Query createFilter(Object collection, String queryString) throws HibernateException;
		649
		650	/**
		651	* Obtain an instance of <tt>Query</tt> for a named query string defined in the
		652	* mapping file.
		653	*
		654	* @param queryName the name of a query defined externally
		655	* @return Query
		656	* @throws HibernateException
		657	*/
		658	public Query getNamedQuery(String queryName) throws HibernateException;
		659
		660	/**
		661	* Completely clear the session. Evict all loaded instances and cancel all pending
		662	* saves, updates and deletions. Do not close open iterators or instances of
		663	* <tt>ScrollableResults</tt>.
		664	*/
		665	public void clear();
		666
		667	/**
		668	* Return the persistent instance of the given entity class with the given identifier,
		669	* or null if there is no such persistent instance. (If the instance is already associated
		670	* with the session, return that instance. This method never returns an uninitialized instance.)
		671	* Obtain the specified lock mode if the instance exists.
		672	*
		673	* @param clazz a persistent class
		674	* @param id an identifier
		675	* @return a persistent instance or null
		676	* @throws HibernateException
		677	*/
		678	public Object get(Class clazz, Serializable id) throws HibernateException;
		679
		680	/**
		681	* Return the persistent instance of the given entity class with the given identifier,
		682	* or null if there is no such persistent instance. (If the instance is already associated
		683	* with the session, return that instance. This method never returns an uninitialized instance.)
		684	* Obtain the specified lock mode if the instance exists.
		685	*
		686	* @param clazz a persistent class
		687	* @param id an identifier
		688	* @param lockMode the lock mode
		689	* @return a persistent instance or null
		690	* @throws HibernateException
		691	*/
		692	public Object get(Class clazz, Serializable id, LockMode lockMode) throws HibernateException;
		693
		694	/**
		695	* Return the persistent instance of the given named entity with the given identifier,
		696	* or null if there is no such persistent instance. (If the instance is already associated
		697	* with the session, return that instance. This method never returns an uninitialized instance.)
		698	*
		699	* @param entityName the entity name
		700	* @param id an identifier
		701	* @return a persistent instance or null
		702	* @throws HibernateException
		703	*/
		704	public Object get(String entityName, Serializable id) throws HibernateException;
		705
		706	/**
		707	* Return the persistent instance of the given entity class with the given identifier,
		708	* or null if there is no such persistent instance. (If the instance is already associated
		709	* with the session, return that instance. This method never returns an uninitialized instance.)
		710	* Obtain the specified lock mode if the instance exists.
		711	*
		712	* @param entityName the entity name
		713	* @param id an identifier
		714	* @param lockMode the lock mode
		715	* @return a persistent instance or null
		716	* @throws HibernateException
		717	*/
		718	public Object get(String entityName, Serializable id, LockMode lockMode) throws HibernateException;
		719
		720
		721	/**
		722	* Return the entity name for a persistent entity
		723	*
		724	* @param object a persistent entity
		725	* @return the entity name
		726	* @throws HibernateException
		727	*/
		728	public String getEntityName(Object object) throws HibernateException;
		729
		730	/**
		731	* Enable the named filter for this current session.
		732	*
		733	* @param filterName The name of the filter to be enabled.
		734	* @return The Filter instance representing the enabled fiter.
		735	*/
		736	public Filter enableFilter(String filterName);
		737
		738	/**
		739	* Retrieve a currently enabled filter by name.
		740	*
		741	* @param filterName The name of the filter to be retrieved.
		742	* @return The Filter instance representing the enabled fiter.
		743	*/
		744	public Filter getEnabledFilter(String filterName);
		745
		746	/**
		747	* Disable the named filter for the current session.
		748	*
		749	* @param filterName The name of the filter to be disabled.
		750	*/
		751	public void disableFilter(String filterName);
		752
		753	/**
		754	* Get the statistics for this session.
		755	*/
		756	public SessionStatistics getStatistics();
		757
		758	/**
		759	* Set an unmodified persistent object to read only mode, or a read only
		760	* object to modifiable mode. In read only mode, no snapshot is maintained
		761	* and the instance is never dirty checked.
		762	*
		763	* @see Query#setReadOnly(boolean)
		764	*/
		765	public void setReadOnly(Object entity, boolean readOnly);
		766
		767	/**
		768	* Controller for allowing users to perform JDBC related work using the Connection
		769	* managed by this Session.
		770	*
		771	* @param work The work to be performed.
		772	* @throws HibernateException Generally indicates wrapped {@link java.sql.SQLException}
		773	*/
		774	public void doWork(Work work) throws HibernateException;
		775
		776
		777	/**
		778	* Disconnect the <tt>Session</tt> from the current JDBC connection. If
		779	* the connection was obtained by Hibernate close it and return it to
		780	* the connection pool; otherwise, return it to the application.
		781	* <p/>
		782	* This is used by applications which supply JDBC connections to Hibernate
		783	* and which require long-sessions (or long-conversations)
		784	* <p/>
		785	* Note that disconnect() called on a session where the connection was
		786	* retrieved by Hibernate through its configured
		787	* {@link org.hibernate.connection.ConnectionProvider} has no effect,
		788	* provided {@link ConnectionReleaseMode#ON_CLOSE} is not in effect.
		789	*
		790	* @return the application-supplied connection or <tt>null</tt>
		791	* @see #reconnect(Connection)
		792	* @see #reconnect()
		793	*/
		794	Connection disconnect() throws HibernateException;
		795
		796	/**
		797	* Obtain a new JDBC connection. This is used by applications which
		798	* require long transactions and do not supply connections to the
		799	* session.
		800	*
		801	* @see #disconnect()
		802	* @deprecated Manual reconnection is only needed in the case of
		803	* application-supplied connections, in which case the
		804	* {@link #reconnect(java.sql.Connection)} for should be used.
		805	*/
		806	void reconnect() throws HibernateException;
		807
		808	/**
		809	* Reconnect to the given JDBC connection. This is used by applications
		810	* which require long transactions and use application-supplied connections.
		811	*
		812	* @param connection a JDBC connection
		813	* @see #disconnect()
		814	*/
		815	void reconnect(Connection connection) throws HibernateException;
		816	}

Subversion Repositories WebE

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