KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > lutris > appserver > server > sql > DBConnection


1 /*
2  * Enhydra Java Application Server Project
3  *
4  * The contents of this file are subject to the Enhydra Public License
5  * Version 1.1 (the "License"); you may not use this file except in
6  * compliance with the License. You may obtain a copy of the License on
7  * the Enhydra web site ( http://www.enhydra.org/ ).
8  *
9  * Software distributed under the License is distributed on an "AS IS"
10  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
11  * the License for the specific terms governing rights and limitations
12  * under the License.
13  *
14  * The Initial Developer of the Enhydra Application Server is Lutris
15  * Technologies, Inc. The Enhydra Application Server and portions created
16  * by Lutris Technologies, Inc. are Copyright Lutris Technologies, Inc.
17  * All Rights Reserved.
18  *
19  * Contributor(s):
20  *
21  * $Id: DBConnection.java,v 1.1 2004/09/03 13:42:37 sinisa Exp $
22  */
23 package com.lutris.appserver.server.sql;
24
25 import java.sql.CallableStatement JavaDoc;
26 import java.sql.Connection JavaDoc;
27 import java.sql.PreparedStatement JavaDoc;
28 import java.sql.ResultSet JavaDoc;
29 import java.sql.SQLException JavaDoc;
30
31 /**
32  * This interface defines a database connection.
33  *
34  * @author Paul Morgan
35  * @since LBS1.8
36  * @version $Revision: 1.1 $
37  */
38 public interface DBConnection {
39
40     /**
41      * Validates this connection. Check to see that it
42      * is not closed and has been properly allocated.
43      *
44      * @exception java.sql.SQLException
45      * If it is not valid.
46      */
47     public void validate() throws SQLException JavaDoc;
48
49     /**
50      * Closes down all query-specific resources.
51      *
52      * @exception java.sql.SQLException If a database error occurs.
53      */
54     public void reset() throws SQLException JavaDoc;
55
56     /**
57      * Get a prepared statement given an SQL string. If the statement is
58      * cached, return that statement, otherwise prepare and save in the
59      * cache.
60      *
61      * @param sql The SQL statement to prepared.
62      * @return The prepared statement, which is associated only with this
63      * connection and must not be used once the connection is released.
64      * @exception java.sql.SQLException If a SQL error occured compiling the
65      * statement.
66      */
67     public PreparedStatement JavaDoc prepareStatement(String JavaDoc sql)
68         throws SQLException JavaDoc;
69
70     /**
71      * Creates a CallableStatement object for calling database
72      * stored procedures. Refer to jdk api refernece.
73      * @param sql The SQL statement to be called.
74      * @return a new CallableStatement object containing the
75      * pre-compiled SQL statement.
76      * @exception java.sql.SQLException If a database access error occurs
77      * statement.
78      */
79     public CallableStatement JavaDoc prepareCall(String JavaDoc sql)
80         throws SQLException JavaDoc;
81
82     /**
83      * Execute a prepared query statement. Once the query has completed,
84      * <CODE>reset()</CODE> should be called.
85      *
86      * @param preparedStmt The statement to execute.
87      * @param msg for logging/debug purposes
88      * @return Query result set, do not call close, use reset(),
89      * @exception java.sql.SQLException If a SQL error occured executing the
90      * statement.
91      */
92     public ResultSet JavaDoc executeQuery(PreparedStatement JavaDoc preparedStmt,
93             String JavaDoc msg)
94         throws SQLException JavaDoc;
95
96     /**
97      * Execute a SQL query statement. This is a wrapper that adds logging.
98      * Once the query has completed, <CODE>reset()</CODE> should be called.
99      *
100      * @param sql The SQL query statement
101      * @return Query result set, do not call close, use reset(),
102      * @exception java.sql.SQLException If a SQL error occured executing the
103      * statement.
104      */
105     public ResultSet JavaDoc executeQuery(String JavaDoc sql) throws SQLException JavaDoc;
106
107     /**
108      * Execute a SQL update statement. This is a wrapper that adds logging.
109      * Once the update has completed, <CODE>reset()</CODE> should be called.
110      *
111      * @param sql
112      * The SQL query statement
113      * @return
114      * Either the row count for UPDATE, INSERT, DELETE or 0 for
115      * SQL statements that return nothing.
116      * @exception java.sql.SQLException
117      * If a SQL error occured executing the update.
118      */
119     public int executeUpdate(String JavaDoc sql) throws SQLException JavaDoc;
120
121     /**
122      * Execute a prepared update statement. Once the update has completed,
123      * <CODE>reset()</CODE> should be called.
124      *
125      * @param preparedStmt The statement to execute.
126      * @param msg for logging/debug purposes
127      * @return Either the row count for UPDATE, INSERT, DELETE or 0 for
128      * SQL statements that return nothing.
129      * @exception java.sql.SQLException If a SQL error occured executing the
130      * statement.
131      */
132     public int executeUpdate(PreparedStatement JavaDoc preparedStmt,
133             String JavaDoc msg)
134         throws SQLException JavaDoc;
135
136     /**
137      * Execute a SQL statement that does not return a resultset. This is a
138      * wrapper that adds logging. Once the query has completed,
139      * <CODE>reset()</CODE> should be called.
140      *
141      * @param sql The SQL query statement
142      * @return True if the next result is a ResultSet; false if it is
143      * an update count or there are no more results.
144      * @exception java.sql.SQLException If a SQL error occured executing the
145      * statement.
146      */
147     public boolean execute(String JavaDoc sql) throws SQLException JavaDoc;
148
149     /**
150      * Check for warnings in a result set.
151      *
152      * @param resultSet The result set to check for warnings.
153      * @exception java.sql.SQLException If a SQL error occured compiling the
154      * statement.
155      */
156     public void warningCheck(ResultSet JavaDoc resultSet)
157         throws SQLException JavaDoc;
158
159     /**
160      * Return this connection to its allocator. This object should not be
161      * used after calling this function.
162      */
163     public void release();
164
165     /**
166      * Check if a connection is valid after an SQL exception
167      * is thrown. If it is not usable, then the connection is
168      * dropped from the connection allocator and closed. The connection
169      * is then no longer usable.
170      *
171      * @param sqlExcept
172      * the SQL exception that occured.
173      * @return true
174      * if the exception does not affect this
175      * connection object. False otherwise - in which case
176      * this connection object is no longer usable.
177      */
178     public boolean handleException(SQLException JavaDoc sqlExcept);
179
180     /**
181      * Commit a transaction.
182      *
183      * @exception java.sql.SQLException If a database access error occurs.
184      */
185     public void commit() throws SQLException JavaDoc;
186
187     /**
188      * Autocommit on/off.
189      *
190      * @param on
191      * false to disable auto commit mode. True to enable.
192      * @exception SQLException
193      * if a database access error occurs.
194      */
195     public void setAutoCommit(boolean on) throws SQLException JavaDoc;
196
197     /**
198      * Rollback a transaction. Should only be used when
199      * <A HREF=#setAutoCommit>auto-commit</A> mode
200      * has been disabled.
201      *
202      * @exception SQLException
203      * if a database access error occurs.
204      */
205     public void rollback() throws SQLException JavaDoc;
206     
207     /**
208      * Method called when this connection object is allocated from the
209      * connection allocator.
210      *
211      * @exception SQLException
212      * if <CODE>reset</CODE> had no been called on the previous operation.
213      */
214     public void allocate() throws SQLException JavaDoc;
215     
216     /**
217      * Close this connection. Use by the connection allocator when this
218      * object is no longer used. Errors are ignored.
219      */
220     public void close();
221     
222     /**
223      * Get the generation number specified when the connection was created.
224      *
225      * @return The generation number.
226      */
227     public int getGeneration();
228
229     /**
230      * Increment the count of the number of requests against
231      * this connection.
232      */
233     public void incrRequestCount();
234
235     /**
236      * Get the database URL.
237      * @return The database URL.
238      */
239     public String JavaDoc getUrl();
240
241     /**
242      * Get the database user name. Normally user for error messages.
243      * @return The database user name.
244      */
245     public String JavaDoc getUser();
246
247     /**
248      * Get the underlying <code>Connection</code> object.
249      * Use with extreme caution.
250      * @return the connection object
251      */
252     public Connection JavaDoc getConnection();
253
254     /**
255      * @return true if this connection is marked to be dropped out
256      * of the connection pool and closed.
257      */
258     public boolean isMarkedForDrop();
259     
260     /**
261      * @return database name of current connection
262      *
263      */
264     public String JavaDoc getDatabaseName();
265 }
266
Popular Tags