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