1 package com.atlassian.sal.spi;
2
3 import com.atlassian.sal.api.rdbms.ConnectionCallback;
4
5 import javax.annotation.Nonnull;
6
7 /**
8 * Interface allowing SAL to execute a callback with a {@link java.sql.Connection}, in the context of a transaction.
9 *
10 * Host should export this.
11 *
12 * Host should implement this; may use {@link com.atlassian.sal.spring.connection.SpringHostConnectionAccessor}
13 *
14 * @since 3.0
15 */
16 public interface HostConnectionAccessor
17 {
18 /**
19 * Execute a callback which is supplied a {@link java.sql.Connection}, within a transaction.
20 *
21 * It is up to the host as to whether it attempts to participate in an existing transaction.
22 *
23 * {@link java.sql.Connection#commit()} or {@link java.sql.Connection#rollback()} will be called immediately prior
24 * to return.
25 *
26 * The following methods are guaranteed not to be called on <code>connection</code>:
27 * {@link java.sql.Connection#setAutoCommit(boolean)}
28 * {@link java.sql.Connection#commit()}
29 * {@link java.sql.Connection#close()}
30 * {@link java.sql.Connection#rollback()}
31 * {@link java.sql.Connection#setReadOnly(boolean)}
32 * {@link java.sql.Connection#abort(java.util.concurrent.Executor)}
33 * {@link java.sql.Connection#setCatalog(String)}
34 * {@link java.sql.Connection#setSchema(String)}
35 * {@link java.sql.Connection#setTransactionIsolation(int)}
36 * {@link java.sql.Connection#setNetworkTimeout(java.util.concurrent.Executor, int)}
37 *
38 * @param readOnly <code>connection</code> should be read only
39 * @param newTransaction attempt to create a new transaction even if there is already a "current" transaction
40 * @param callback mandatory
41 * @return return value of <code>callback</code>
42 */
43 <A> A execute(final boolean readOnly, final boolean newTransaction, @Nonnull ConnectionCallback<A> callback);
44 }