001: /*
002: Copyright (C) 2007 MySQL AB
003:
004: This program is free software; you can redistribute it and/or modify
005: it under the terms of version 2 of the GNU General Public License as
006: published by the Free Software Foundation.
007:
008: There are special exceptions to the terms and conditions of the GPL
009: as it is applied to this software. View the full text of the
010: exception in file EXCEPTIONS-CONNECTOR-J in the directory of this
011: software distribution.
012:
013: This program is distributed in the hope that it will be useful,
014: but WITHOUT ANY WARRANTY; without even the implied warranty of
015: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
016: GNU General Public License for more details.
017:
018: You should have received a copy of the GNU General Public License
019: along with this program; if not, write to the Free Software
020: Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
021:
022: */
023:
024: package com.mysql.jdbc;
025:
026: import java.sql.SQLException;
027: import java.util.Properties;
028:
029: /**
030: * Implement this interface to be placed "in between" query execution, so that
031: * you can influence it. (currently experimental).
032: *
033: * StatementInterceptors are "chainable" when configured by the user, the
034: * results returned by the "current" interceptor will be passed on to the next
035: * on in the chain, from left-to-right order, as specified by the user in the
036: * JDBC configuration property "statementInterceptors".
037: *
038: * @version $Id: $
039: */
040:
041: public interface StatementInterceptor {
042:
043: /**
044: * Called once per connection that wants to use the interceptor
045: *
046: * The properties are the same ones passed in in the URL or arguments to
047: * Driver.connect() or DriverManager.getConnection().
048: *
049: * @param conn the connection for which this interceptor is being created
050: * @param props configuration values as passed to the connection. Note that
051: * in order to support javax.sql.DataSources, configuration properties specific
052: * to an interceptor <strong>must</strong> be passed via setURL() on the
053: * DataSource. StatementInterceptor properties are not exposed via
054: * accessor/mutator methods on DataSources.
055: *
056: * @throws SQLException should be thrown if the the StatementInterceptor
057: * can not initialize itself.
058: */
059:
060: public abstract void init(Connection conn, Properties props)
061: throws SQLException;
062:
063: /**
064: * Called before the given statement is going to be sent to the
065: * server for processing.
066: *
067: * Interceptors are free to return a result set (which must implement the
068: * interface com.mysql.jdbc.ResultSetInternalMethods), and if so,
069: * the server will not execute the query, and the given result set will be
070: * returned to the application instead.
071: *
072: * This method will be called while the connection-level mutex is held, so
073: * it will only be called from one thread at a time.
074: *
075: * @param sql the SQL representation of the statement
076: * @param interceptedStatement the actual statement instance being intercepted
077: * @param connection the connection the statement is using (passed in to make
078: * thread-safe implementations straightforward)
079: *
080: * @return a result set that should be returned to the application instead
081: * of results that are created from actual execution of the intercepted
082: * statement.
083: *
084: * @throws SQLException if an error occurs during execution
085: *
086: * @see com.mysql.jdbc.ResultSetInternalMethods
087: */
088:
089: public abstract ResultSetInternalMethods preProcess(String sql,
090: Statement interceptedStatement, Connection connection)
091: throws SQLException;
092:
093: /**
094: * Called after the given statement has been sent to the server
095: * for processing.
096: *
097: * Interceptors are free to inspect the "original" result set, and if a
098: * different result set is returned by the interceptor, it is used in place
099: * of the "original" result set. (the result set returned by the interceptor
100: * must implement the interface
101: * com.mysql.jdbc.ResultSetInternalMethods).
102: *
103: * This method will be called while the connection-level mutex is held, so
104: * it will only be called from one thread at a time.
105: *
106: * @param sql the SQL representation of the statement
107: * @param interceptedStatement the actual statement instance being intercepted
108: * @param connection the connection the statement is using (passed in to make
109: * thread-safe implementations straightforward)
110: *
111: * @return a result set that should be returned to the application instead
112: * of results that are created from actual execution of the intercepted
113: * statement.
114: *
115: * @throws SQLException if an error occurs during execution
116: *
117: * @see com.mysql.jdbc.ResultSetInternalMethods
118: */
119: public abstract ResultSetInternalMethods postProcess(String sql,
120: Statement interceptedStatement,
121: ResultSetInternalMethods originalResultSet,
122: Connection connection) throws SQLException;
123:
124: /**
125: * Should the driver execute this interceptor only for the
126: * "original" top-level query, and not put it in the execution
127: * path for queries that may be executed from other interceptors?
128: *
129: * If an interceptor issues queries using the connection it was created for,
130: * and does not return <code>true</code> for this method, it must ensure
131: * that it does not cause infinite recursion.
132: *
133: * @return true if the driver should ensure that this interceptor is only
134: * executed for the top-level "original" query.
135: */
136: public abstract boolean executeTopLevelOnly();
137: }
|