1 package com.atlassian.sal.spi;
2
3 import io.atlassian.fugue.Option;
4 import com.atlassian.sal.api.rdbms.ConnectionCallback;
5
6 import javax.annotation.Nonnull;
7
8 /**
9 * Interface allowing SAL to execute a callback with a {@link java.sql.Connection}, in the context of a transaction.
10 *
11 * Host must export this.
12 *
13 * Host must implement this; may use {@code com.atlassian.sal.spring.connection.SpringHostConnectionAccessor}
14 *
15 * @since 3.0
16 */
17 public interface HostConnectionAccessor {
18 /**
19 * Execute a callback which is supplied a {@link java.sql.Connection}, within a transaction.
20 *
21 * It is up to the caller as to whether it attempts to participate in an existing transaction. This is explicitly
22 * explained in {@link com.atlassian.sal.api.rdbms.TransactionalExecutor}.
23 *
24 * In the case of the callback returning normally:
25 * <ul>
26 * <li>If it is a new connection/transaction that the implementation started then the transaction must be committed, or</li>
27 * <li>In the case of an existing transaction, the implementation will do nothing and wait for the larger transaction to be committed</li>
28 * </ul>
29 * In the case of the callback throwing a RuntimeException:
30 * <ul>
31 * <li>The implementation will mark the transaction as "rollback only" and rethrow the error</li>
32 * </ul>
33 *
34 * The host must ensure that the Connection provided to the ConnectionCallback has <code>autoCommit=false</code>.
35 *
36 * The following methods are guaranteed not to be called on <code>connection</code>:
37 * {@link java.sql.Connection#setAutoCommit(boolean)}
38 * {@link java.sql.Connection#commit()}
39 * {@link java.sql.Connection#close()}
40 * {@link java.sql.Connection#rollback()}
41 * {@link java.sql.Connection#setReadOnly(boolean)}
42 * {@link java.sql.Connection#abort(java.util.concurrent.Executor)}
43 * {@link java.sql.Connection#setCatalog(String)}
44 * {@link java.sql.Connection#setSchema(String)}
45 * {@link java.sql.Connection#setTransactionIsolation(int)}
46 * {@link java.sql.Connection#setNetworkTimeout(java.util.concurrent.Executor, int)}
47 *
48 * @param readOnly <code>connection</code> should be read only
49 * @param newTransaction attempt to create a new transaction even if there is already a "current" transaction
50 * @param callback mandatory
51 * @return return value of <code>callback</code>
52 */
53 <A> A execute(final boolean readOnly, final boolean newTransaction, @Nonnull ConnectionCallback<A> callback);
54
55 /**
56 * Returns the configured schema name (if any), for connections provided during {@link #execute(boolean, boolean, ConnectionCallback)}
57 *
58 * @return schema name, if there is one
59 */
60 @Nonnull
61 Option<String> getSchemaName();
62 }