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