1 package com.atlassian.sal.spi;
2
3 import com.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 {@link 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 host as to whether it attempts to participate in an existing transaction. This is explicitly
22 * explained to the consumer in {@link com.atlassian.sal.api.rdbms.TransactionalExecutor}.
23 *
24 * The host must ensure that the Connection provided to the ConnectionCallback has <code>autoCommit=false</code>.
25 *
26 * {@link java.sql.Connection#commit()} or {@link java.sql.Connection#rollback()} will be called immediately prior
27 * to return. It may be necessary to wrap the <code>connection</code> passed to <code>callback</code> in the case
28 * of <code>newTransaction</code> being false, so that the entire transaction is not committed too early.
29 *
30 * The following methods are guaranteed not to be called on <code>connection</code> during the execution of
31 * <code>callback</code>:
32 * {@link java.sql.Connection#setAutoCommit(boolean)}
33 * {@link java.sql.Connection#commit()}
34 * {@link java.sql.Connection#close()}
35 * {@link java.sql.Connection#rollback()}
36 * {@link java.sql.Connection#setReadOnly(boolean)}
37 * {@link java.sql.Connection#abort(java.util.concurrent.Executor)}
38 * {@link java.sql.Connection#setCatalog(String)}
39 * {@link java.sql.Connection#setSchema(String)}
40 * {@link java.sql.Connection#setTransactionIsolation(int)}
41 * {@link java.sql.Connection#setNetworkTimeout(java.util.concurrent.Executor, int)}
42 *
43 * @param readOnly <code>connection</code> should be read only
44 * @param newTransaction attempt to create a new transaction even if there is already a "current" transaction
45 * @param callback mandatory
46 * @return return value of <code>callback</code>
47 */
48 <A> A execute(final boolean readOnly, final boolean newTransaction, @Nonnull ConnectionCallback<A> callback);
49
50 /**
51 * Returns the configured schema name (if any), for connections provided during {@link #execute(boolean, boolean, ConnectionCallback)}
52 *
53 * @return schema name, if there is one
54 */
55 @Nonnull
56 Option<String> getSchemaName();
57 }