001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/db/tags/sakai_2-4-1/db-api/api/src/java/org/sakaiproject/db/api/SqlService.java $
003: * $Id: SqlService.java 22826 2007-03-17 18:59:47Z ggolden@umich.edu $
004: ***********************************************************************************
005: *
006: * Copyright (c) 2003, 2004, 2005, 2006, 2007 The Sakai Foundation.
007: *
008: * Licensed under the Educational Community License, Version 1.0 (the "License");
009: * you may not use this file except in compliance with the License.
010: * You may obtain a copy of the License at
011: *
012: * http://www.opensource.org/licenses/ecl1.php
013: *
014: * Unless required by applicable law or agreed to in writing, software
015: * distributed under the License is distributed on an "AS IS" BASIS,
016: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: * See the License for the specific language governing permissions and
018: * limitations under the License.
019: *
020: **********************************************************************************/package org.sakaiproject.db.api;
021:
022: import java.io.InputStream;
023: import java.sql.Connection;
024: import java.sql.SQLException;
025: import java.util.GregorianCalendar;
026: import java.util.List;
027:
028: import org.sakaiproject.exception.ServerOverloadException;
029:
030: /**
031: * <p>
032: * SqlService provides access to pooled Connections to Sql databases.
033: * </p>
034: * <p>
035: * The Connection objects managed by this service are standard java.sql.Connection objects.
036: * </p>
037: */
038: public interface SqlService {
039: /**********************************************************************************************************************************************************************************************************************************************************
040: * Transaction support
041: *********************************************************************************************************************************************************************************************************************************************************/
042:
043: /**
044: * Access an available or newly created Connection from the default pool. Will wait a while until one is available.
045: *
046: * @return The Connection object.
047: * @throws SQLException
048: * if a connection cannot be delivered.
049: */
050: Connection borrowConnection() throws SQLException;
051:
052: /**
053: * Release a database connection.
054: *
055: * @param conn
056: * The connetion to release. If null or not one of ours, ignored.
057: */
058: void returnConnection(Connection conn);
059:
060: /**
061: * Run some code in a transaction. The code is callback. Any calls to this service will be done within the transaction if they don't supply their
062: * own connection.<br />
063: * If the transaction fails due to a deadlock, it will be retried a number of times.
064: *
065: * @param callback
066: * The code to run.
067: * @param tag
068: * A string to use in logging failure to identify the transaction.
069: * @return true if all went well. The SqlServiceDeadlockException will be thrown if we end up failing due to a deadlock, and the
070: * SqlServiceUniqueViolation.
071: */
072: boolean transact(Runnable callback, String tag);
073:
074: /**********************************************************************************************************************************************************************************************************************************************************
075: * Sql operations
076: *********************************************************************************************************************************************************************************************************************************************************/
077:
078: /**
079: * Read a single field from the db, from multiple records, returned as string[], one per record.
080: *
081: * @param sql
082: * The sql statement.
083: * @return The List of Strings of single fields of the record found, or empty if none found.
084: */
085: List dbRead(String sql);
086:
087: /**
088: * Process a query, filling in with fields, and return the results as a List, one per record read. If a reader is provided, it will be called for each record to prepare the Object placed into the List. Otherwise, the first field of each record, as a
089: * String, will be placed in the list.
090: *
091: * @param sql
092: * The sql statement.
093: * @param fields
094: * The array of fields for parameters.
095: * @param reader
096: * The reader object to read each record.
097: * @return The List of things read, one per record.
098: */
099: List dbRead(String sql, Object[] fields, SqlReader reader);
100:
101: /**
102: * Process a query, filling in with fields, and return the results as a List, one per record read. If a reader is provided, it will be called for each record to prepare the Object placed into the List. Otherwise, the first field of each record, as a
103: * String, will be placed in the list.
104: *
105: * @param conn
106: * The db connection object to use.
107: * @param sql
108: * The sql statement.
109: * @param fields
110: * The array of fields for parameters.
111: * @param reader
112: * The reader object to read each record.
113: * @return The List of things read, one per record.
114: */
115: List dbRead(Connection conn, String sql, Object[] fields,
116: SqlReader reader);
117:
118: /**
119: * Read a single field from the db, from multiple record - concatenating the binary values into value.
120: *
121: * @param sql
122: * The sql statement.
123: * @param fields
124: * The array of fields for parameters.
125: * @param value
126: * The array of bytes to fill with the value read from the db.
127: */
128: void dbReadBinary(String sql, Object[] fields, byte[] value);
129:
130: /**
131: * Read a single field from the db, from multiple record - concatenating the binary values into value.
132: *
133: * @param conn
134: * The optional db connection object to use.
135: * @param sql
136: * The sql statement.
137: * @param fields
138: * The array of fields for parameters.
139: * @param value
140: * The array of bytes to fill with the value read from the db.
141: */
142: void dbReadBinary(Connection conn, String sql, Object[] fields,
143: byte[] value);
144:
145: /**
146: * Read a single field / record from the db, returning a stream on the result record / field. The stream holds the conection open - so it must be closed or finalized quickly!
147: *
148: * @param sql
149: * The sql statement.
150: * @param fields
151: * The array of fields for parameters.
152: * @param big
153: * If true, the read is expected to be potentially large.
154: * @throws ServerOverloadException
155: * if the read cannot complete due to lack of a free connection (if wait is false)
156: */
157: InputStream dbReadBinary(String sql, Object[] fields, boolean big)
158: throws ServerOverloadException;
159:
160: /**
161: * Execute the "insert" sql, returning a possible auto-update field Long value
162: *
163: * @param sql
164: * The sql statement.
165: * @param fields
166: * The array of fields for parameters.
167: * @param callerConnection
168: * The connection to use.
169: * @param autoColumn
170: * The name of the db column that will have auto-update - we will return the value used (leave null to disable this feature).
171: * @return The auto-update value, or null
172: */
173: Long dbInsert(Connection callerConnection, String sql,
174: Object[] fields, String autoColumn);
175:
176: /**
177: * Execute the "insert" sql, returning a possible auto-update field Long value, with an additional stream parameter.
178: *
179: * @param sql
180: * The sql statement.
181: * @param fields
182: * The array of fields for parameters.
183: * @param callerConnection
184: * The connection to use.
185: * @param autoColumn
186: * The name of the db column that will have auto-update - we will return the value used (leave null to disable this feature).
187: * @param last
188: * An input stream to add as the last parameter.
189: * @param lastLength
190: * The number of bytes in the input stream to write.
191: * @return The auto-update value, or null
192: */
193: Long dbInsert(Connection callerConnection, String sql,
194: Object[] fields, String autoColumn, InputStream last,
195: int lastLength);
196:
197: /**
198: * Execute the "write" sql - no response.
199: *
200: * @param sql
201: * The sql statement.
202: * @return true if successful, false if not.
203: */
204: boolean dbWrite(String sql);
205:
206: /**
207: * Execute the "write" sql - no response. a long field is set to "?" - fill it in with var
208: *
209: * @param sql
210: * The sql statement.
211: * @param var
212: * The value to bind to the first parameter in the sql statement.
213: * @return true if successful, false if not.
214: */
215: boolean dbWrite(String sql, String var);
216:
217: /**
218: * Execute the "write" sql - no response. a long binary field is set to "?" - fill it in with var
219: *
220: * @param sql
221: * The sql statement.
222: * @param fields
223: * The array of fields for parameters.
224: * @param var
225: * The value to bind to the last parameter in the sql statement.
226: * @param offset
227: * The start within the var to write
228: * @param len
229: * The number of bytes of var, starting with index, to write
230: * @return true if successful, false if not.
231: */
232: boolean dbWriteBinary(String sql, Object[] fields, byte[] var,
233: int offset, int len);
234:
235: /**
236: * Execute the "write" sql - no response, using a set of fields from an array.
237: *
238: * @param sql
239: * The sql statement.
240: * @param fields
241: * The array of fields for parameters.
242: * @return true if successful, false if not.
243: */
244: boolean dbWrite(String sql, Object[] fields);
245:
246: /**
247: * Execute the "write" sql - no response, using a set of fields from an array and a given connection.
248: *
249: * @param connection
250: * The connection to use.
251: * @param sql
252: * The sql statement.
253: * @param fields
254: * The array of fields for parameters.
255: * @return true if successful, false if not.
256: */
257: boolean dbWrite(Connection connection, String sql, Object[] fields);
258:
259: /**
260: * Execute the "write" sql - no response, using a set of fields from an array and a given connection logging no errors on failure.
261: *
262: * @param connection
263: * The connection to use.
264: * @param sql
265: * The sql statement.
266: * @param fields
267: * The array of fields for parameters.
268: * @return true if successful, false if not.
269: */
270: boolean dbWriteFailQuiet(Connection connection, String sql,
271: Object[] fields);
272:
273: /**
274: * Execute the "write" sql - no response, using a set of fields from an array plus one more as params.
275: *
276: * @param sql
277: * The sql statement.
278: * @param fields
279: * The array of fields for parameters.
280: * @param lastField
281: * The value to bind to the last parameter in the sql statement.
282: * @return true if successful, false if not.
283: */
284: boolean dbWrite(String sql, Object[] fields, String lastField);
285:
286: /**
287: * Read a single field BLOB from the db from one record, and update it's bytes with content.
288: *
289: * @param sql
290: * The sql statement to select the BLOB.
291: * @param content
292: * The new bytes for the BLOB.
293: */
294: void dbReadBlobAndUpdate(String sql, byte[] content);
295:
296: /**
297: * Read a single field from the db, from a single record, return the value found, and lock for update.
298: *
299: * @param sql
300: * The sql statement.
301: * @param field
302: * A StringBuffer that will be filled with the field.
303: * @return The Connection holding the lock.
304: */
305: Connection dbReadLock(String sql, StringBuffer field);
306:
307: /**
308: * Commit the update that was locked on this connection.
309: *
310: * @param sql
311: * The sql statement.
312: * @param fields
313: * The array of fields for parameters.
314: * @param var
315: * The value to bind to the last parameter in the sql statement.
316: * @param conn
317: * The database connection on which the lock was gained.
318: */
319: void dbUpdateCommit(String sql, Object[] fields, String var,
320: Connection conn);
321:
322: /**
323: * Cancel the update that was locked on this connection.
324: *
325: * @param conn
326: * The database connection on which the lock was gained.
327: */
328: void dbCancel(Connection conn);
329:
330: /**
331: * Access the calendar used in processing Time objects for Sql.
332: *
333: * @return The calendar used in processing Time objects for Sql.
334: */
335: GregorianCalendar getCal();
336:
337: /**
338: * @return a string indicating the database vendor - "oracle" or "mysql" or "hsqldb".
339: */
340: String getVendor();
341:
342: /**
343: * Load and run the named file using the given class loader, as a ddl check / create. The first non-comment ('--') line will be run, and if successfull, all other non-comment lines will be run. SQL statements must be on a single line, and may have ';'
344: * terminators.
345: *
346: * @param loader
347: * The ClassLoader used to load the resource.
348: * @param resource
349: * The path name to the resource - vender string and .sql will be added
350: */
351: void ddl(ClassLoader loader, String resource);
352:
353: /**
354: * Get the next value from this sequence, for those technologies that support sequences. For the others, return null.
355: *
356: * @param tableName
357: * The sequence table name
358: * @param conn
359: * The database connection to use (it will use a new one if null).
360: * @return The Integer value that is the next sequence, or null if sequences are not supported
361: */
362: Long getNextSequence(String tableName, Connection conn);
363:
364: /**
365: * Get the SQL statement constant for a Boolean or Bit field for this value.
366: *
367: * @param value
368: * The value.
369: * @return The SQL statement constant for a Boolean or Bit field for this value.
370: */
371: String getBooleanConstant(boolean value);
372: }
|