KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > mysql > jdbc > util > BaseBugReport


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