001: /*
002: * Enhydra Java Application Server Project
003: *
004: * The contents of this file are subject to the Enhydra Public License
005: * Version 1.1 (the "License"); you may not use this file except in
006: * compliance with the License. You may obtain a copy of the License on
007: * the Enhydra web site ( http://www.enhydra.org/ ).
008: *
009: * Software distributed under the License is distributed on an "AS IS"
010: * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
011: * the License for the specific terms governing rights and limitations
012: * under the License.
013: *
014: * The Initial Developer of the Enhydra Application Server is Lutris
015: * Technologies, Inc. The Enhydra Application Server and portions created
016: * by Lutris Technologies, Inc. are Copyright Lutris Technologies, Inc.
017: * All Rights Reserved.
018: *
019: * Contributor(s):
020: *
021: * $Id: DBConnection.java,v 1.1 2007-01-24 16:59:09 sinisa Exp $
022: */
023: package com.lutris.appserver.server.sql;
024:
025: import java.sql.CallableStatement;
026: import java.sql.Connection;
027: import java.sql.PreparedStatement;
028: import java.sql.ResultSet;
029: import java.sql.SQLException;
030:
031: /**
032: * This interface defines a database connection.
033: *
034: * @author Paul Morgan
035: * @since LBS1.8
036: * @version $Revision: 1.1 $
037: */
038: public interface DBConnection {
039:
040: /**
041: * Validates this connection. Check to see that it
042: * is not closed and has been properly allocated.
043: *
044: * @exception java.sql.SQLException
045: * If it is not valid.
046: */
047: public void validate() throws SQLException;
048:
049: /**
050: * Closes down all query-specific resources.
051: *
052: * @exception java.sql.SQLException If a database error occurs.
053: */
054: public void reset() throws SQLException;
055:
056: /**
057: * Get a prepared statement given an SQL string. If the statement is
058: * cached, return that statement, otherwise prepare and save in the
059: * cache.
060: *
061: * @param sql The SQL statement to prepared.
062: * @return The prepared statement, which is associated only with this
063: * connection and must not be used once the connection is released.
064: * @exception java.sql.SQLException If a SQL error occured compiling the
065: * statement.
066: */
067: public PreparedStatement prepareStatement(String sql)
068: throws SQLException;
069:
070: /**
071: * Creates a CallableStatement object for calling database
072: * stored procedures. Refer to jdk api refernece.
073: * @param sql The SQL statement to be called.
074: * @return a new CallableStatement object containing the
075: * pre-compiled SQL statement.
076: * @exception java.sql.SQLException If a database access error occurs
077: * statement.
078: */
079: public CallableStatement prepareCall(String sql)
080: throws SQLException;
081:
082: /**
083: * Execute a prepared query statement. Once the query has completed,
084: * <CODE>reset()</CODE> should be called.
085: *
086: * @param preparedStmt The statement to execute.
087: * @param msg for logging/debug purposes
088: * @return Query result set, do not call close, use reset(),
089: * @exception java.sql.SQLException If a SQL error occured executing the
090: * statement.
091: */
092: public ResultSet executeQuery(PreparedStatement preparedStmt,
093: String msg) throws SQLException;
094:
095: /**
096: * Execute a SQL query statement. This is a wrapper that adds logging.
097: * Once the query has completed, <CODE>reset()</CODE> should be called.
098: *
099: * @param sql The SQL query statement
100: * @return Query result set, do not call close, use reset(),
101: * @exception java.sql.SQLException If a SQL error occured executing the
102: * statement.
103: */
104: public ResultSet executeQuery(String sql) throws SQLException;
105:
106: /**
107: * Execute a SQL update statement. This is a wrapper that adds logging.
108: * Once the update has completed, <CODE>reset()</CODE> should be called.
109: *
110: * @param sql
111: * The SQL query statement
112: * @return
113: * Either the row count for UPDATE, INSERT, DELETE or 0 for
114: * SQL statements that return nothing.
115: * @exception java.sql.SQLException
116: * If a SQL error occured executing the update.
117: */
118: public int executeUpdate(String sql) throws SQLException;
119:
120: /**
121: * Execute a prepared update statement. Once the update has completed,
122: * <CODE>reset()</CODE> should be called.
123: *
124: * @param preparedStmt The statement to execute.
125: * @param msg for logging/debug purposes
126: * @return Either the row count for UPDATE, INSERT, DELETE or 0 for
127: * SQL statements that return nothing.
128: * @exception java.sql.SQLException If a SQL error occured executing the
129: * statement.
130: */
131: public int executeUpdate(PreparedStatement preparedStmt, String msg)
132: throws SQLException;
133:
134: /**
135: * Execute a SQL statement that does not return a resultset. This is a
136: * wrapper that adds logging. Once the query has completed,
137: * <CODE>reset()</CODE> should be called.
138: *
139: * @param sql The SQL query statement
140: * @return True if the next result is a ResultSet; false if it is
141: * an update count or there are no more results.
142: * @exception java.sql.SQLException If a SQL error occured executing the
143: * statement.
144: */
145: public boolean execute(String sql) throws SQLException;
146:
147: /**
148: * Check for warnings in a result set.
149: *
150: * @param resultSet The result set to check for warnings.
151: * @exception java.sql.SQLException If a SQL error occured compiling the
152: * statement.
153: */
154: public void warningCheck(ResultSet resultSet) throws SQLException;
155:
156: /**
157: * Return this connection to its allocator. This object should not be
158: * used after calling this function.
159: */
160: public void release();
161:
162: /**
163: * Check if a connection is valid after an SQL exception
164: * is thrown. If it is not usable, then the connection is
165: * dropped from the connection allocator and closed. The connection
166: * is then no longer usable.
167: *
168: * @param sqlExcept
169: * the SQL exception that occured.
170: * @return true
171: * if the exception does not affect this
172: * connection object. False otherwise - in which case
173: * this connection object is no longer usable.
174: */
175: public boolean handleException(SQLException sqlExcept);
176:
177: /**
178: * Commit a transaction.
179: *
180: * @exception java.sql.SQLException If a database access error occurs.
181: */
182: public void commit() throws SQLException;
183:
184: /**
185: * Autocommit on/off.
186: *
187: * @param on
188: * false to disable auto commit mode. True to enable.
189: * @exception SQLException
190: * if a database access error occurs.
191: */
192: public void setAutoCommit(boolean on) throws SQLException;
193:
194: /**
195: * Rollback a transaction. Should only be used when
196: * <A HREF=#setAutoCommit>auto-commit</A> mode
197: * has been disabled.
198: *
199: * @exception SQLException
200: * if a database access error occurs.
201: */
202: public void rollback() throws SQLException;
203:
204: /**
205: * Method called when this connection object is allocated from the
206: * connection allocator.
207: *
208: * @exception SQLException
209: * if <CODE>reset</CODE> had no been called on the previous operation.
210: */
211: public void allocate() throws SQLException;
212:
213: /**
214: * Close this connection. Use by the connection allocator when this
215: * object is no longer used. Errors are ignored.
216: */
217: public void close();
218:
219: /**
220: * Get the generation number specified when the connection was created.
221: *
222: * @return The generation number.
223: */
224: public int getGeneration();
225:
226: /**
227: * Increment the count of the number of requests against
228: * this connection.
229: */
230: public void incrRequestCount();
231:
232: /**
233: * Get the database URL.
234: * @return The database URL.
235: */
236: public String getUrl();
237:
238: /**
239: * Get the database user name. Normally user for error messages.
240: * @return The database user name.
241: */
242: public String getUser();
243:
244: /**
245: * Get the underlying <code>Connection</code> object.
246: * Use with extreme caution.
247: * @return the connection object
248: */
249: public Connection getConnection();
250:
251: /**
252: * @return true if this connection is marked to be dropped out
253: * of the connection pool and closed.
254: */
255: public boolean isMarkedForDrop();
256:
257: /**
258: * @return database name of current connection
259: *
260: */
261: public String getDatabaseName();
262: }
|