01: /*
02: * Copyright 2002-2007 the original author or authors.
03: *
04: * Licensed under the Apache License, Version 2.0 (the "License");
05: * you may not use this file except in compliance with the License.
06: * You may obtain a copy of the License at
07: *
08: * http://www.apache.org/licenses/LICENSE-2.0
09: *
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.transaction.support;
18:
19: import org.springframework.transaction.PlatformTransactionManager;
20: import org.springframework.transaction.TransactionDefinition;
21: import org.springframework.transaction.TransactionException;
22:
23: /**
24: * Extension of the {@link org.springframework.transaction.PlatformTransactionManager}
25: * interface, exposing a method for executing a given callback within a transaction.
26: *
27: * <p>Implementors of this interface automatically express a preference for
28: * callbacks over programmatic <code>getTransaction</code>, <code>commit</code>
29: * and <code>rollback</code> calls. Calling code may check whether a given
30: * transaction manager implements this interface to choose to prepare a
31: * callback instead of explicit transaction demarcation control.
32: *
33: * <p>Spring's {@link TransactionTemplate} and
34: * {@link org.springframework.transaction.interceptor.TransactionInterceptor}
35: * detect and use this PlatformTransactionManager variant automatically.
36: *
37: * @author Juergen Hoeller
38: * @since 2.0
39: * @see org.springframework.transaction.support.TransactionTemplate
40: * @see org.springframework.transaction.interceptor.TransactionInterceptor
41: */
42: public interface CallbackPreferringPlatformTransactionManager extends
43: PlatformTransactionManager {
44:
45: /**
46: * Execute the action specified by the given callback object within a transaction.
47: * <p>Allows for returning a result object created within the transaction, that is,
48: * a domain object or a collection of domain objects. A RuntimeException thrown
49: * by the callback is treated as a fatal exception that enforces a rollback.
50: * Such an exception gets propagated to the caller of the template.
51: * @param definition the definition for the transaction to wrap the callback in
52: * @param callback the callback object that specifies the transactional action
53: * @return a result object returned by the callback, or <code>null</code> if none
54: * @throws TransactionException in case of initialization, rollback, or system errors
55: * @throws RuntimeException if thrown by the TransactionCallback
56: */
57: Object execute(TransactionDefinition definition,
58: TransactionCallback callback) throws TransactionException;
59:
60: }
|