1 /*
2 * Copyright 2004-2007 Brian McCallister
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.skife.jdbi.v2;
18
19 import java.sql.Connection;
20 import java.util.List;
21 import java.util.Map;
22
23 import org.skife.jdbi.v2.exceptions.TransactionFailedException;
24 import org.skife.jdbi.v2.tweak.SQLLog;
25 import org.skife.jdbi.v2.tweak.StatementBuilder;
26 import org.skife.jdbi.v2.tweak.StatementLocator;
27 import org.skife.jdbi.v2.tweak.StatementRewriter;
28
29 /**
30 * This represents a connection to the database system. It ususally is a wrapper around
31 * a JDBC Connection object.
32 */
33 public interface Handle
34 {
35
36 /**
37 * Get the JDBC Connection this Handle uses
38 * @return the JDBC Connection this Handle uses
39 */
40 Connection getConnection();
41
42 /**
43 * @throws org.skife.jdbi.v2.exceptions.UnableToCloseResourceException if any
44 * resources throw exception while closing
45 */
46 void close();
47
48 /**
49 * Define a statement attribute which will be applied to all {@link StatementContext}
50 * instances for statements created from this handle
51 *
52 * @param key Attribute name
53 * @param value Attribute value
54 */
55 void define(String key, Object value);
56
57 /**
58 * Start a transaction
59 */
60 Handle begin();
61
62 /**
63 * Commit a transaction
64 */
65 Handle commit();
66
67 /**
68 * Rollback a transaction
69 */
70 Handle rollback();
71
72 /**
73 * Rollback a transaction to a named checkpoint
74 * @param checkpointName the name of the checkpoint, previously declared with {@see Handle#checkpoint}
75 */
76 Handle rollback(String checkpointName);
77
78 /**
79 * Is the handle in a transaction? It defers to the underlying {@link org.skife.jdbi.v2.tweak.TransactionHandler}
80 */
81 boolean isInTransaction();
82
83 /**
84 * Return a default Query instance which can be executed later, as long as this handle remains open.
85 * @param sql the select sql
86 */
87 Query<Map<String, Object>> createQuery(String sql);
88
89 /**
90 * Create an Insert or Update statement which returns the number of rows modified.
91 * @param sql The statement sql
92 */
93 Update createStatement(String sql);
94
95 /**
96 * Create a call to a stored procedure
97 *
98 * @param callableSql
99 * @return the Call
100 */
101 public Call createCall(String callableSql);
102
103
104 /**
105 * Execute a simple insert statement
106 * @param sql the insert SQL
107 * @return the number of rows inserted
108 */
109 int insert(String sql, Object... args);
110
111 /**
112 * Execute a simple update statement
113 * @param sql the update SQL
114 * @param args positional arguments
115 * @return the number of updated inserted
116 */
117 int update(String sql, Object... args);
118
119 /**
120 * Prepare a batch to execute. This is for efficiently executing more than one
121 * of the same statements with different parameters bound
122 * @param sql the batch SQL
123 * @return a batch which can have "statements" added
124 */
125 PreparedBatch prepareBatch(String sql);
126
127 /**
128 * Create a non-prepared (no bound parameters, but different SQL, batch statement
129 * @return empty batch
130 * @see Handle#prepareBatch(String)
131 */
132 Batch createBatch();
133
134 /**
135 * Executes <code>callback</code> in a transaction. If the transaction succeeds, the
136 * result of the callback will be returned. If it fails a {@link TransactionFailedException}
137 * will be thrown.
138 *
139 * @return value returned from the callback
140 * @throws TransactionFailedException if the transaction failed in the callback
141 */
142 <ReturnType> ReturnType inTransaction(TransactionCallback<ReturnType> callback) throws TransactionFailedException;
143
144 /**
145 * Convenience method which executes a select with purely positional arguments
146 * @param sql SQL or named statement
147 * @param args arguments to bind positionally
148 * @return results of the query
149 */
150 List<Map<String, Object>> select(String sql, Object... args);
151
152 /**
153 * Allows for overiding the default statement locator. The default searches the
154 * classpath for named statements
155 */
156 public void setStatementLocator(StatementLocator locator);
157
158 /**
159 * Allows for overiding the default statement rewriter. The default handles
160 * named parameter interpolation.
161 */
162 public void setStatementRewriter(StatementRewriter rewriter);
163
164 /**
165 * Creates an SQL script, looking for the source of the script using the
166 * current statement locator (which defaults to searching the classpath)
167 */
168 public Script createScript(String name);
169
170 /**
171 * Execute some SQL with no return value
172 * @param sql the sql to execute
173 * @param args arguments to bind to the sql
174 */
175 void execute(String sql, Object... args);
176
177 /**
178 * Create a transaction checkpoint (savepoint in JDBC terminology) with the name provided.
179 * @param name The name of the checkpoint
180 * @return The same handle
181 */
182 Handle checkpoint(String name);
183
184 /**
185 * Release a previously created checkpoint
186 *
187 * @param checkpointName the name of the checkpoint to release
188 */
189 Handle release(String checkpointName);
190
191 /**
192 * Specify the statement builder to use for this handle
193 * @param builder StatementBuilder to be used
194 */
195 void setStatementBuilder(StatementBuilder builder);
196
197 /**
198 * Specify the class used to log sql statements. The default is inherited from the DBI used
199 * to create this Handle.
200 */
201 void setSQLLog(SQLLog log);
202
203 /**
204 * Specify the class used to collect timing information. The default is inherited from the DBI used
205 * to create this Handle.
206 */
207 void setTimingCollector(TimingCollector timingCollector);
208 }