StatementInterceptor.java
6.21 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
/*
Copyright (c) 2007, 2014, Oracle and/or its affiliates. All rights reserved.
The MySQL Connector/J is licensed under the terms of the GPLv2
<http://www.gnu.org/licenses/old-licenses/gpl-2.0.html>, like most MySQL Connectors.
There are special exceptions to the terms and conditions of the GPLv2 as it is applied to
this software, see the FOSS License Exception
<http://www.mysql.com/about/legal/licensing/foss-exception.html>.
This program is free software; you can redistribute it and/or modify it under the terms
of the GNU General Public License as published by the Free Software Foundation; version 2
of the License.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this
program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth
Floor, Boston, MA 02110-1301 USA
*/
package com.mysql.jdbc;
import java.sql.SQLException;
import java.util.Properties;
/**
* Implement this interface to be placed "in between" query execution, so that you can influence it. (currently experimental).
*
* StatementInterceptors are "chainable" when configured by the user, the results returned by the "current" interceptor will be passed on to the next on in the
* chain, from left-to-right order, as specified by the user in the JDBC configuration property "statementInterceptors".
*/
public interface StatementInterceptor extends Extension {
/**
* Called once per connection that wants to use the interceptor
*
* The properties are the same ones passed in in the URL or arguments to
* Driver.connect() or DriverManager.getConnection().
*
* @param conn
* the connection for which this interceptor is being created
* @param props
* configuration values as passed to the connection. Note that
* in order to support javax.sql.DataSources, configuration properties specific
* to an interceptor <strong>must</strong> be passed via setURL() on the
* DataSource. StatementInterceptor properties are not exposed via
* accessor/mutator methods on DataSources.
*
* @throws SQLException
* should be thrown if the the StatementInterceptor
* can not initialize itself.
*/
public abstract void init(Connection conn, Properties props) throws SQLException;
/**
* Called before the given statement is going to be sent to the
* server for processing.
*
* Interceptors are free to return a result set (which must implement the
* interface com.mysql.jdbc.ResultSetInternalMethods), and if so,
* the server will not execute the query, and the given result set will be
* returned to the application instead.
*
* This method will be called while the connection-level mutex is held, so
* it will only be called from one thread at a time.
*
* @param sql
* the SQL representation of the statement
* @param interceptedStatement
* the actual statement instance being intercepted
* @param connection
* the connection the statement is using (passed in to make
* thread-safe implementations straightforward)
*
* @return a result set that should be returned to the application instead
* of results that are created from actual execution of the intercepted
* statement.
*
* @throws SQLException
* if an error occurs during execution
*
* @see com.mysql.jdbc.ResultSetInternalMethods
*/
public abstract ResultSetInternalMethods preProcess(String sql, Statement interceptedStatement, Connection connection) throws SQLException;
/**
* Called after the given statement has been sent to the server
* for processing.
*
* Interceptors are free to inspect the "original" result set, and if a
* different result set is returned by the interceptor, it is used in place
* of the "original" result set. (the result set returned by the interceptor
* must implement the interface
* com.mysql.jdbc.ResultSetInternalMethods).
*
* This method will be called while the connection-level mutex is held, so
* it will only be called from one thread at a time.
*
* @param sql
* the SQL representation of the statement
* @param interceptedStatement
* the actual statement instance being intercepted
* @param connection
* the connection the statement is using (passed in to make
* thread-safe implementations straightforward)
*
* @return a result set that should be returned to the application instead
* of results that are created from actual execution of the intercepted
* statement.
*
* @throws SQLException
* if an error occurs during execution
*
* @see com.mysql.jdbc.ResultSetInternalMethods
*/
public abstract ResultSetInternalMethods postProcess(String sql, Statement interceptedStatement, ResultSetInternalMethods originalResultSet,
Connection connection) throws SQLException;
/**
* Should the driver execute this interceptor only for the
* "original" top-level query, and not put it in the execution
* path for queries that may be executed from other interceptors?
*
* If an interceptor issues queries using the connection it was created for,
* and does not return <code>true</code> for this method, it must ensure
* that it does not cause infinite recursion.
*
* @return true if the driver should ensure that this interceptor is only
* executed for the top-level "original" query.
*/
public abstract boolean executeTopLevelOnly();
/**
* Called by the driver when this extension should release any resources
* it is holding and cleanup internally before the connection is
* closed.
*/
public abstract void destroy();
}