001: /*
002: Copyright (C) 2002-2004 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: */
025: package com.mysql.jdbc.util;
026:
027: import java.sql.Connection;
028: import java.sql.SQLException;
029: import java.util.Properties;
030:
031: import com.mysql.jdbc.Driver;
032:
033: /**
034: * Base class to help file bug reports for Connector/J.
035: *
036: * <p>
037: * MySQL AB
038: * <ul>
039: * really
040: * </ul>
041: * appreciates repeatable testcases when reporting bugs, so we're giving you
042: * this class to make that job a bit easier (and standarized).
043: *
044: * <p>
045: * To create a testcase, create a class that inherits from this class
046: * (com.mysql.jdbc.util.BaseBugReport), and override the methods 'setUp',
047: * 'tearDown' and 'runTest'.
048: *
049: * <p>
050: * In the 'setUp' method, create code that creates your tables, and populates
051: * them with any data needed to demonstrate the bug.
052: *
053: * <p>
054: * In the 'runTest' method, create code that demonstrates the bug using the
055: * tables and data you created in the 'setUp' method.
056: *
057: * <p>
058: * In the 'tearDown' method, drop any tables you created in the 'setUp' method.
059: *
060: * <p>
061: * In any of the above three methods, you should use one of the variants of the
062: * 'getConnection' method to create a JDBC connection to MySQL, which will use
063: * the default JDBC URL of 'jdbc:mysql:///test'.
064: *
065: * <p>
066: * If you need to use a JDBC URL that is different than 'jdbc:mysql:///test',
067: * then override the method 'getUrl' as well.
068: *
069: * <p>
070: * Use the 'assertTrue' methods to create conditions that must be met in your
071: * testcase demonstrating the behavior you are expecting (vs. the behavior you
072: * are observing, which is why you are most likely filing a bug report).
073: *
074: * <p>
075: * Finally, create a 'main' method that creates a new instance of your testcase,
076: * and calls the 'run' method:
077: *
078: * <p>
079: *
080: * <pre>
081: * public static void main(String[] args) throws Exception {
082: * new MyBugReport().run();
083: * }
084: * </pre>
085: *
086: * <p>
087: * When filing a potential bug with MySQL Connector/J at http://bugs.mysql.com/
088: * or on the bugs mailing list, please include the code that you have just
089: * written using this class.
090: *
091: * @author Mark Matthews
092: * @version $Id: BaseBugReport.java 3726 2005-05-19 15:52:24Z mmatthews $
093: */
094: public abstract class BaseBugReport {
095:
096: private Connection conn;
097:
098: private Driver driver;
099:
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()
210: throws SQLException {
211: if (this .conn == null || this .conn.isClosed()) {
212: this .conn = getNewConnection();
213: }
214:
215: return this .conn;
216: }
217:
218: /**
219: * Use this if you need to get a new connection for your bug report (i.e.
220: * there's more than one connection involved).
221: *
222: * @return a new connection to the JDBC URL specified in getUrl().
223: *
224: * @throws SQLException
225: * if an error is caused while creating the connection.
226: */
227: public final synchronized Connection getNewConnection()
228: throws SQLException {
229: return getConnection(getUrl());
230: }
231:
232: /**
233: * Returns a connection using the given URL.
234: *
235: * @param url
236: * the JDBC URL to use
237: * @return a new java.sql.Connection to the JDBC URL.
238: * @throws SQLException
239: * if an error occurs getting the connection.
240: */
241: public final synchronized Connection getConnection(String url)
242: throws SQLException {
243: return getConnection(url, null);
244: }
245:
246: /**
247: * Returns a connection using the given URL and properties.
248: *
249: * @param url
250: * the JDBC URL to use
251: * @param props
252: * the JDBC properties to use
253: * @return a new java.sql.Connection to the JDBC URL.
254: * @throws SQLException
255: * if an error occurs getting the connection.
256: */
257: public final synchronized Connection getConnection(String url,
258: Properties props) throws SQLException {
259:
260: // Don't follow this example in your own code
261: // This is to bypass the java.sql.DriverManager
262:
263: return this.driver.connect(url, props);
264: }
265: }
|