1 | /* |
2 | Copyright (C) 2002-2004 MySQL AB |
3 | |
4 | This program is free software; you can redistribute it and/or modify |
5 | it under the terms of version 2 of the GNU General Public License as |
6 | published by the Free Software Foundation. |
7 | |
8 | There are special exceptions to the terms and conditions of the GPL |
9 | as it is applied to this software. View the full text of the |
10 | exception in file EXCEPTIONS-CONNECTOR-J in the directory of this |
11 | software distribution. |
12 | |
13 | This program is distributed in the hope that it will be useful, |
14 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
15 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
16 | GNU General Public License for more details. |
17 | |
18 | You should have received a copy of the GNU General Public License |
19 | along with this program; if not, write to the Free Software |
20 | Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
21 | |
22 | |
23 | |
24 | */ |
25 | package com.mysql.jdbc.util; |
26 | |
27 | import java.sql.Connection; |
28 | import java.sql.SQLException; |
29 | import java.util.Properties; |
30 | |
31 | import com.mysql.jdbc.Driver; |
32 | |
33 | /** |
34 | * Base class to help file bug reports for Connector/J. |
35 | * |
36 | * <p> |
37 | * MySQL AB |
38 | * <ul> |
39 | * really |
40 | * </ul> |
41 | * appreciates repeatable testcases when reporting bugs, so we're giving you |
42 | * this class to make that job a bit easier (and standarized). |
43 | * |
44 | * <p> |
45 | * To create a testcase, create a class that inherits from this class |
46 | * (com.mysql.jdbc.util.BaseBugReport), and override the methods 'setUp', |
47 | * 'tearDown' and 'runTest'. |
48 | * |
49 | * <p> |
50 | * In the 'setUp' method, create code that creates your tables, and populates |
51 | * them with any data needed to demonstrate the bug. |
52 | * |
53 | * <p> |
54 | * In the 'runTest' method, create code that demonstrates the bug using the |
55 | * tables and data you created in the 'setUp' method. |
56 | * |
57 | * <p> |
58 | * In the 'tearDown' method, drop any tables you created in the 'setUp' method. |
59 | * |
60 | * <p> |
61 | * In any of the above three methods, you should use one of the variants of the |
62 | * 'getConnection' method to create a JDBC connection to MySQL, which will use |
63 | * the default JDBC URL of 'jdbc:mysql:///test'. |
64 | * |
65 | * <p> |
66 | * If you need to use a JDBC URL that is different than 'jdbc:mysql:///test', |
67 | * then override the method 'getUrl' as well. |
68 | * |
69 | * <p> |
70 | * Use the 'assertTrue' methods to create conditions that must be met in your |
71 | * testcase demonstrating the behavior you are expecting (vs. the behavior you |
72 | * are observing, which is why you are most likely filing a bug report). |
73 | * |
74 | * <p> |
75 | * Finally, create a 'main' method that creates a new instance of your testcase, |
76 | * and calls the 'run' method: |
77 | * |
78 | * <p> |
79 | * |
80 | * <pre> |
81 | * public static void main(String[] args) throws Exception { |
82 | * new MyBugReport().run(); |
83 | * } |
84 | * </pre> |
85 | * |
86 | * <p> |
87 | * When filing a potential bug with MySQL Connector/J at http://bugs.mysql.com/ |
88 | * or on the bugs mailing list, please include the code that you have just |
89 | * written using this class. |
90 | * |
91 | * @author Mark Matthews |
92 | * @version $Id: BaseBugReport.java 3726 2005-05-19 15:52:24Z mmatthews $ |
93 | */ |
94 | public abstract class BaseBugReport { |
95 | |
96 | private Connection conn; |
97 | |
98 | private Driver driver; |
99 | |
100 | /** |
101 | * Constructor for this BugReport, sets up JDBC driver used to create |
102 | * connections. |
103 | */ |
104 | public BaseBugReport() { |
105 | try { |
106 | this.driver = new Driver(); |
107 | } catch (SQLException ex) { |
108 | throw new RuntimeException(ex.toString()); |
109 | } |
110 | } |
111 | |
112 | /** |
113 | * Override this method with code that sets up the testcase for |
114 | * demonstrating your bug (creating tables, populating data, etc). |
115 | * |
116 | * @throws Exception |
117 | * if an error occurs during the 'setUp' phase. |
118 | */ |
119 | public abstract void setUp() throws Exception; |
120 | |
121 | /** |
122 | * Override this method with code that cleans up anything created in the |
123 | * setUp() method. |
124 | * |
125 | * @throws Exception |
126 | * if an error occurs during the 'tearDown' phase. |
127 | */ |
128 | public abstract void tearDown() throws Exception; |
129 | |
130 | /** |
131 | * Override this method with code that demonstrates the bug. This method |
132 | * will be called after setUp(), and before tearDown(). |
133 | * |
134 | * @throws Exception |
135 | * if an error occurs during your test run. |
136 | */ |
137 | public abstract void runTest() throws Exception; |
138 | |
139 | /** |
140 | * Runs the testcase by calling the setUp(), runTest() and tearDown() |
141 | * methods. The tearDown() method is run regardless of any errors occuring |
142 | * in the other methods. |
143 | * |
144 | * @throws Exception |
145 | * if an error occurs in any of the aforementioned methods. |
146 | */ |
147 | public final void run() throws Exception { |
148 | try { |
149 | setUp(); |
150 | runTest(); |
151 | |
152 | } finally { |
153 | tearDown(); |
154 | } |
155 | } |
156 | |
157 | /** |
158 | * Throws an exception with the given message if condition evalutates to |
159 | * 'false'. |
160 | * |
161 | * @param message |
162 | * the message to use in the exception |
163 | * @param condition |
164 | * the condition to test for |
165 | * @throws Exception |
166 | * if !condition |
167 | */ |
168 | protected final void assertTrue(String message, boolean condition) |
169 | throws Exception { |
170 | if (!condition) { |
171 | throw new Exception("Assertion failed: " + message); |
172 | } |
173 | } |
174 | |
175 | /** |
176 | * Throws an exception if condition evalutates to 'false'. |
177 | * |
178 | * @param condition |
179 | * the condition to test for |
180 | * @throws Exception |
181 | * if !condition |
182 | */ |
183 | protected final void assertTrue(boolean condition) throws Exception { |
184 | assertTrue("(no message given)", condition); |
185 | } |
186 | |
187 | /** |
188 | * Provides the JDBC URL to use to demonstrate the bug. The |
189 | * java.sql.Connection that you use to demonstrate this bug will be provided |
190 | * by the getConnection() method using this URL. |
191 | * |
192 | * The default value is 'jdbc:mysql:///test' |
193 | */ |
194 | public String getUrl() { |
195 | return "jdbc:mysql:///test"; |
196 | } |
197 | |
198 | /** |
199 | * Provides a connection to the JDBC URL specified in getUrl(). |
200 | * |
201 | * If a connection already exists, that connection is returned. Otherwise a |
202 | * new connection is created. |
203 | * |
204 | * @return a connection to the JDBC URL specified in getUrl(). |
205 | * |
206 | * @throws SQLException |
207 | * if an error is caused while creating the connection. |
208 | */ |
209 | public final synchronized Connection getConnection() throws SQLException { |
210 | if (this.conn == null || this.conn.isClosed()) { |
211 | this.conn = getNewConnection(); |
212 | } |
213 | |
214 | return this.conn; |
215 | } |
216 | |
217 | /** |
218 | * Use this if you need to get a new connection for your bug report (i.e. |
219 | * there's more than one connection involved). |
220 | * |
221 | * @return a new connection to the JDBC URL specified in getUrl(). |
222 | * |
223 | * @throws SQLException |
224 | * if an error is caused while creating the connection. |
225 | */ |
226 | public final synchronized Connection getNewConnection() throws SQLException { |
227 | return getConnection(getUrl()); |
228 | } |
229 | |
230 | /** |
231 | * Returns a connection using the given URL. |
232 | * |
233 | * @param url |
234 | * the JDBC URL to use |
235 | * @return a new java.sql.Connection to the JDBC URL. |
236 | * @throws SQLException |
237 | * if an error occurs getting the connection. |
238 | */ |
239 | public final synchronized Connection getConnection(String url) |
240 | throws SQLException { |
241 | return getConnection(url, null); |
242 | } |
243 | |
244 | /** |
245 | * Returns a connection using the given URL and properties. |
246 | * |
247 | * @param url |
248 | * the JDBC URL to use |
249 | * @param props |
250 | * the JDBC properties to use |
251 | * @return a new java.sql.Connection to the JDBC URL. |
252 | * @throws SQLException |
253 | * if an error occurs getting the connection. |
254 | */ |
255 | public final synchronized Connection getConnection(String url, |
256 | Properties props) throws SQLException { |
257 | |
258 | // Don't follow this example in your own code |
259 | // This is to bypass the java.sql.DriverManager |
260 | |
261 | return this.driver.connect(url, props); |
262 | } |
263 | } |