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