KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > springframework > orm > hibernate3 > HibernateCallback


1 /*
2  * Copyright 2002-2006 the original author or authors.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 package org.springframework.orm.hibernate3;
18
19 import java.sql.SQLException JavaDoc;
20
21 import org.hibernate.HibernateException;
22 import org.hibernate.Session;
23
24 /**
25  * Callback interface for Hibernate code. To be used with {@link HibernateTemplate}'s
26  * execution methods, often as anonymous classes within a method implementation.
27  * A typical implementation will call <code>Session.load/find/update</code> to perform
28  * some operations on persistent objects. It can also perform direct JDBC operations
29  * via Hibernate's <code>Session.connection()</code>, operating on a JDBC Connection.
30  *
31  * <p>Note that Hibernate works on unmodified plain Java objects, performing dirty
32  * detection via copies made at load time. Returned objects can thus be used outside
33  * of an active Hibernate Session without any hassle, e.g. for display in a web GUI.
34  * Reassociating such instances with a new Session, e.g. for updates when coming
35  * back from the GUI, is straightforward, as the instance has kept its identity.
36  * You should care to reassociate them as early as possible though, to avoid having
37  * already loaded a version from the database in the same Session.
38  *
39  * @author Juergen Hoeller
40  * @since 1.2
41  * @see HibernateTemplate
42  * @see HibernateTransactionManager
43  */
44 public interface HibernateCallback {
45
46     /**
47      * Gets called by <code>HibernateTemplate.execute</code> with an active
48      * Hibernate <code>Session</code>. Does not need to care about activating
49      * or closing the <code>Session</code>, or handling transactions.
50      *
51      * <p>If called without a thread-bound Hibernate transaction (initiated
52      * by HibernateTransactionManager), the code will simply get executed on the
53      * underlying JDBC connection with its transactional semantics. If Hibernate
54      * is configured to use a JTA-aware DataSource, the JDBC connection and thus
55      * the callback code will be transactional if a JTA transaction is active.
56      *
57      * <p>Allows for returning a result object created within the callback,
58      * i.e. a domain object or a collection of domain objects.
59      * A thrown custom RuntimeException is treated as an application exception:
60      * It gets propagated to the caller of the template.
61      *
62      * @param session active Hibernate session
63      * @return a result object, or <code>null</code> if none
64      * @throws HibernateException if thrown by the Hibernate API
65      * @throws SQLException if thrown by Hibernate-exposed JDBC API
66      * @see HibernateTemplate#execute
67      * @see HibernateTemplate#executeFind
68      */
69     Object JavaDoc doInHibernate(Session session) throws HibernateException, SQLException JavaDoc;
70
71 }
72
Popular Tags