001: /*
002: * The contents of this file are subject to the Mozilla Public License
003: * Version 1.1 (the "License"); you may not use this file except in
004: * compliance with the License. You may obtain a copy of the License at
005: * http://www.mozilla.org/MPL/
006: *
007: * Software distributed under the License is distributed on an "AS IS"
008: * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
009: * License for the specific language governing rights and limitations
010: * under the License.
011: *
012: * The Original Code is iSQL-Viewer, A Mutli-Platform Database Tool.
013: *
014: * The Initial Developer of the Original Code is iSQL-Viewer, A Mutli-Platform Database Tool.
015: * Portions created by Mark A. Kobold are Copyright (C) 2000-2007. All Rights Reserved.
016: *
017: * Contributor(s):
018: * Mark A. Kobold [mkobold <at> isqlviewer <dot> com].
019: *
020: * If you didn't download this code from the following link, you should check
021: * if you aren't using an obsolete version: http://www.isqlviewer.com
022: */
023: package org.isqlviewer.sql;
024:
025: import java.sql.ResultSet;
026: import java.sql.SQLException;
027: import java.sql.SQLWarning;
028: import java.sql.Statement;
029:
030: /**
031: * Protocol for defining a client that can render results from an JDBC command execution.
032: * <p>
033: *
034: * @author Mark A. Kobold <mkobold at isqlviewer dot com>
035: * @version 1.0
036: */
037: public interface ResultSetRenderer {
038:
039: /**
040: * Basic initialization method to allocate resource prior to executing a query.
041: * <p>
042: */
043: public void initialize();
044:
045: /**
046: * Allows the renderer to substitute the variable by name with something else.
047: * <p>
048: * When an SQL Statement is executed and inline variables in the Jav variable form of ${variable.name} are detect
049: * the SQL executor will request a substitution for the variable name.
050: *
051: * @param variableName to substitute.
052: * @return the value to be substituted for the given variable name.
053: */
054: public String substituteVariable(String variableName);
055:
056: /**
057: * Processes ResultSet objects from a statement execution.
058: * <p>
059: * This is the common method for dispatching a result set for processing outside the database connection object.
060: * Once a Statement has executed and has results this method will be invoked. Implementations are not required to
061: * nor are they encouraged to close the resultset as the code calling this method should ensure that the resultset
062: * is closed properly. If the statement is returning multiple resultsets this method will be called for each
063: * resultset recieved. The exception for closing ResultSets is described in the supportsUpdateableResultSets()
064: * method.
065: * <p>
066: * The count parameter is for convience to indicate which resultset this is in a series of resultsets, if the
067: * statement is returning only one resultset or is executing a single statement the count should always be 0. There
068: * are situations where multiple queries can be executed in a single statement the count parameter in this situation
069: * will also represent the resultset count in the series.
070: *
071: * @see #supportsUpdateableResultSets()
072: * @see Statement#getResultSet()
073: * @param nativeSQL SQL that created the given ResultSet.
074: * @param stmtID unique identifier for this statement.
075: * @param set ResultSet returned from the statement's execution.
076: * @param count in the situation of multiple resultsets this will be a counter for the resultset.
077: * @return number of rows processed from the result set.
078: */
079: public long processResultSet(String stmtID, ResultSet set,
080: String nativeSQL, int count);
081:
082: /**
083: * Processes row updates from a statement execution.
084: * <p>
085: * If a Statement execution does not return any resultsets then it most likely was an UPDATE or something similar.
086: * This allows for notification for the that update count returned by the statement.
087: *
088: * @see Statement#getUpdateCount()
089: * @param nativeSQL the SQL that created the update count.
090: * @param stmtID unique identifier for the executing statement.
091: * @param updateCount the update count as a result of statement execution.
092: */
093: public void processRowUpdates(String stmtID, int updateCount,
094: String nativeSQL);
095:
096: /**
097: * Process generated keys result set after initial result set is processed.
098: * <p>
099: * If this ResultSetViewer supports processing generated keys, this method should called if and only the statement
100: * provides generated keys resultset. Like the other methods implementations are not required to close the
101: * resultset, the invoking code should close the resultset after this method is closed.
102: * <p>
103: * A Side note that the generated keys is a JDBC 3.0 feature so make sure that the JDBC driver has been updated to
104: * be uses in the JDK 1.4.x+ runtimes as the JDK 1.4.x runtimes support the JDBC 3.0 specification.
105: *
106: * @see #supportsGeneratedKeys()
107: * @see Statement#getGeneratedKeys()
108: * @param nativeSQL SQL statement that the keys originated from.
109: * @param stmtID unique identifier for this statement.
110: * @param keys generated keys as a result of the previous resultset.
111: */
112: public void processGeneratedKeys(String stmtID, ResultSet keys,
113: String nativeSQL);
114:
115: /**
116: * Notifcation that the a statement object has been created and is ready to execute.
117: * <p>
118: * Simple callback method for indicating that the Statement object has been created and will be executing shortly
119: * after this method. Implementations can use the stmtID for ensuring each resultset is processed correctly, if
120: * implementation are responding to multiple statement executions.
121: *
122: * @param stmtID unique identifier for the statement currently executing.
123: */
124: public void statementInitialized(String stmtID, Statement statement);
125:
126: /**
127: * Determines if this object wants to view generated keys.
128: * <p>
129: * If this method returns true, a second call should be made to processGeneratedKeys so that the can be properly
130: * handled. Note if there are no generated keys and or they are supported for a paticular JDBC platform.
131: * <p>
132: * You can check support for generated keys through the DatabaseMetaData object.
133: *
134: * @see java.sql.DatabaseMetaData#supportsGetGeneratedKeys()
135: * @return true to process generated keys or not process them.
136: */
137: public boolean supportsGeneratedKeys();
138:
139: /**
140: * Determining if this resultset viewer can edit updatable resultsets.
141: * <p>
142: * If a ResultSet is deemed updateable and this method returns true, then the DatabaseConnection object will not
143: * automatically close the resultset when it is done processing it. This allows this object to keeps a reference to
144: * it and provide updates to the Resultset as needed.
145: * <p>
146: * If the ResultSet is not updatable or the statement is generating multiple results then the value returned here
147: * will be ignored as with multiple resultsets it says in the JDBC API that one and only one resultset should be
148: * open per statement object. so with that if multiple results are being returned all results will be automatically
149: * closed.
150: * <p>
151: * Since the resultset is not automatically closed, it is strongly encouraged that extra steps are taken to ensure
152: * that a resultset is closed, as open resultsets can cause erratic problems on certain JDBC platforms.
153: *
154: * @return if this object can perform updates on the ResultSet.
155: */
156: public boolean supportsUpdateableResultSets();
157:
158: /**
159: * Delegates an SQLException from a given ResultSet.
160: * <p>
161: * If performing some processing of the given ResultSet, results with an SQLException, than it should be delegated
162: * here.
163: * <p>
164: * Code may send a null ResultSet to indicate a general SQLException.
165: *
166: * @param set ResultSet as the source of the Exception, can be null.
167: * @param e Exception that has occured.
168: */
169: public void handleSQLException(SQLException e);
170:
171: /**
172: * handler if the statement has been interrupted or cancelled.
173: * <p>
174: * if an error occurs in the realm that the statement execution was interuppted threading wise or through the use of
175: * the cancel method on the statement this method will be used to indicate that the statement was interrupted and no
176: * further processing will be be executed on the statement.
177: * <p>
178: * Implementations can use the statement identifier to clean up and resources if nessecary, no further calls to this
179: * object should be made with the given statement ID, if so exceptions should be thrown.
180: *
181: * @param stmtID unqiue identifier for the statement that was cancelled.
182: */
183: public void finalizeStatement(String stmtID);
184:
185: /**
186: * Statement warnings from a resultset can be delegated here.
187: * <p>
188: * Any code that invokes this method should clear all warnings from the given Statement to help insure that the same
189: * warning is not processed more than it needs to be.
190: *
191: * @param stmt Source statement object the warnings are coming from.
192: * @param warnings from a statement.
193: */
194: public void recieveStatementWarnings(Statement stmt,
195: SQLWarning warnings);
196:
197: /**
198: * Delegates SQLWarnings from the given ResultSet to be handled.
199: * <p>
200: * Any code that invokes this method should clear all warnings from the given ResultSet to help insure that the same
201: * warning is not processed more than it needs to be.
202: *
203: * @param set ResultSet source where the given warnings came from.
204: * @param warnings detected from the given resultset.
205: */
206: public void recieveResultsetWarnings(ResultSet set,
207: SQLWarning warnings);
208:
209: /**
210: * @return
211: */
212: public boolean isCancelled();
213:
214: }
|