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