Session


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