home *** CD-ROM | disk | FTP | other *** search
/ PC Extra 07 & 08 / pca1507.iso / intface / pca / special4 / software / eclipse.project / WEB-INF / lib / mysql-connector-java-2.0.14-bin.jar / README < prev   
Encoding:
Text File  |  2002-08-13  |  13.5 KB  |  317 lines
  1. MySQL Connector/J 2.0.14
  2. (Formerly MM.MySQL - Mark Matthews JDBC Driver for MySQL)
  3. Copyright (c) 2002 MySQL-AB
  4.  
  5. CONTENTS
  6.  
  7. * License
  8. * System Requirements
  9. * Introduction
  10. * Usage and Installation
  11. * Troubleshooting
  12. * Known Bugs
  13. * Support
  14.  
  15. LICENSE
  16.  
  17. This library is free software; you can redistribute it and/or
  18. modify it under the terms of the GNU Library General Public
  19. License as published by the Free Software Foundation; either
  20. version 2 of the License, or (at your option) any later version.
  21.  
  22. This library is distributed in the hope that it will be useful,
  23. but WITHOUT ANY WARRANTY; without even the implied warranty of
  24. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  25. Library General Public License for more details.
  26.  
  27. You should have received a copy of the GNU Library General Public
  28. License along with this library; if not, write to the
  29. Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  30. Boston, MA  02111-1307, USA.
  31.  
  32. See the COPYING file located in the top-level-directory of
  33. the archive of this library for complete text of license.
  34.  
  35. SYSTEM REQUIREMENTS
  36.  
  37. * Any Java virtual machine supporting JDBC-1.2 or JDBC-2.0 (JDK-1.1 or higher)
  38. * Any MySQL server supporting version 9 or 10 of the MySQL protocol
  39.  
  40. Because MySQL is not fully ANSI SQL-92 compliant, it is not possible to 
  41. create a fully JDBC-compliant driver for MySQL.  However, this driver 
  42. strives to implement as much of the JDBC API as is feasible.
  43.  
  44. INTRODUCTION
  45.  
  46. MySQL Connector/J  is an implemntation of the JDBC API for the MySQL relational
  47. database server. It strives to conform as much as possible to the API
  48. as specified by JavaSoft. It is known to work with many third-party 
  49. products, including Borland JBuilder, IBM Visual Age for Java, SQL/J,
  50. the Locomotive and Symantec Visual Cafe.
  51.  
  52. USAGE AND INSTALLATION
  53.  
  54. MySQL Connector/J  is distributed as a .jar archive containing the sources 
  55. and class files as well as a class-file only "binary" .jar archive 
  56. named "mysql-connector-j-2.0.13-bin.jar".
  57.  
  58. You will need to use the "jar" command-line utility that comes with your JDK 
  59. to un-archive the distribution.
  60.  
  61. Once you have un-archived the distribution .jar archive,
  62. you can install the driver in one of two ways:
  63.  
  64. Either copy the "com" and "org" subdirectories and all of their contents
  65. to anywhere you like, and put the directory holding the "com" and "org"
  66. subdirectories in your classpath, or...
  67.  
  68. Put mysql-connector-j-2.0.14-bin.jar in your classpath, either by adding the 
  69. FULL path to it to your CLASSPATH enviornment variable, or putting it
  70. in $JAVA_HOME/jre/lib/ext.
  71.  
  72. If you are using a servlet engine or application server, you will have
  73. to read your vendor's documentation for more information on how to
  74. configure third-party class libraries, as most application servers
  75. ignore the CLASSPATH environment variable. If you are developing
  76. servlets and/or JSPs, and your application server is J2EE-compliant, 
  77. you should put the driver's .jar file in the WEB-INF/lib subdirectory
  78. of your webapp, as this is the standard location for third party 
  79. class libraries in J2EE web applications. You can also use the
  80. MysqlDataSource, MysqlConnectionPoolDataSource or MysqlXADataSource 
  81. classes in the com.mysql.jdbc.jdbc2.optional package, if your J2EE 
  82. application server supports/requires them. MysqlDataSource supports the 
  83. following parameters (through standard "set" mutators):
  84.  
  85.     user
  86.     password
  87.     serverName
  88.     databaseName
  89.     port
  90.  
  91. If you are going to use the driver with the JDBC DriverManager, you would use
  92. "com.mysql.jdbc.Driver" as the class that implements java.sql.Driver.
  93.  
  94. You might use this name in a Class.forName() call to load the driver:
  95.  
  96.     Class.forName("com.mysql.jdbc.Driver").newInstance();
  97.  
  98. To connect to the database, you need to use a JDBC url with the following 
  99. format ([xxx] denotes optional url components):
  100.  
  101.   jdbc:mysql://[hostname][:port]/[dbname][?param1=value1][¶m2=value2].....
  102.  
  103. URL Parameters (can be passed as properties in 
  104. DriverManager.getConnection() as well):
  105.  
  106. ==============================================================================
  107. Name                | Use                                       | Default 
  108. ==============================================================================
  109. user                | The user to connect as                    | none 
  110. --------------------+-------------------------------------------+-------------
  111. password            | The password to use when connecting       | none 
  112. --------------------+-------------------------------------------+-------------
  113. autoReconnect       | should the driver attempt to              | false
  114.                     | re-connect if the connection dies?        |
  115.                     | (true/false)                              |         
  116. --------------------+-------------------------------------------+-------------
  117. maxReconnects       | if autoReconnect is enabled, how many     | 3
  118.                     | times should the driver attemt to         |
  119.                     | reconnect?                                |
  120. --------------------+-------------------------------------------+-------------
  121. initialTimeout      | if autoReconnect is enabled, the          | 2
  122.                     | initial time to wait between              |
  123.                     | re-connect attempts (seconds)             |
  124. --------------------+-------------------------------------------+-------------
  125. maxRows             | The maximum number of rows to return      | 0
  126.                     | (0 means return all rows)                 |
  127. --------------------+-------------------------------------------+-------------
  128. useUnicode          | should the driver use Unicode character   | false 
  129.                     | encodings when handling                   | 
  130.                     | strings? If not used with                 |
  131.                     | characterEncoding, the driver will        |
  132.                     | attempt to determine the character set    |
  133.                     | in use on the server, and adjust          |
  134.                     | accordingly (true/false)                  |     
  135. --------------------+-------------------------------------------+-------------            
  136. characterEncoding   | if useUnicode is true, what character     | none
  137.                     | encoding should the driver use when       |
  138.                     | dealing with strings?                     |                 
  139. --------------------+-------------------------------------------+-------------
  140. relaxAutocommit        | if the version of MySQL the driver        | false
  141.                     | connects to does not support              |
  142.                     | transactions, allow calls to commit,      |
  143.                     | rollback and setAutoCommit? (true/false)    |
  144. --------------------+-------------------------------------------+-------------
  145. ultraDevHack        | Create PreparedStatements for             | false
  146.                     | prepareCall(), because UltraDev           |
  147.                     | is broken? (true/false)                   |
  148. --------------------+-------------------------------------------+-------------            
  149. capitalizeTypeNames | Capitalize type names in                  | false
  150.                     | DatabaseMetaData? (usually only           |
  151.                     | usefull when using WebObjects)            |
  152. --------------------+-------------------------------------------+-------------
  153. profileSql          | Dump queries and execution/fetch times    | false
  154.                     | to STDERR. Useful for optimizing queries  |
  155.                     | that are auto-generated as in CMP EJBs    |   
  156.                     | (true/false)                              |
  157. ------------------------------------------------------------------------------
  158.             
  159. A simple connection example looks like:
  160.  
  161.     Class.forName("com.mysql.jdbc.Driver").newInstance();
  162.     
  163.     java.sql.Connection conn;
  164.     
  165.     conn = DriverManager.getConnection(
  166.         "jdbc:mysql://localhost/test?user=blah&password=blah");
  167.     
  168. If you need further JDBC tutorial information, please see
  169. http://www.java.sun.com/products/jdbc/
  170.  
  171. The driver supports batch updates for Statements and PreparedStatements.
  172. Batch updates will be processed in entirety, if any of the updates raise a
  173. SQLException, a java.sql.BatchUpdateException will be thrown after all updates
  174. have been processed, with update count values of '-3' for any statements that
  175. were not completed (see section 6.1 in the JDBC-2.1 API spec for more details).
  176.  
  177. Various DataSource implementations exist, all under the 
  178. com.mysql.jdbc.jdbc2.optional package. They are "MysqlDataSource",
  179. "MysqlConnectionPoolDataSource" and "MysqlXaDataSource". Refer to your 
  180. application server documentation for information on how to use these classes.
  181. An example of using the standard DataSource ("MysqlDataSource") can be found
  182. in the "testsuite" directory.
  183.  
  184. TROUBLESHOOTING
  185.  
  186. There are a few issues that seem to be encountered often by users of MySQL Connector/J . 
  187. This section deals with their symptoms, and their resolutions. If you have
  188. further issues, see the "SUPPORT" section below.
  189.  
  190.   Issue: 
  191.  
  192.   "When I try to connect to the database with MySQL Connector/J , I get the
  193.   following exception:
  194.  
  195.   SQLException: Server configuration denies access to data source
  196.   SQLState: 08001
  197.   VendorError: 0
  198.  
  199.   What's going on? I can connect with the MySQL client."
  200.  
  201.   Resolution: 
  202.  
  203.   MySQL Connector/J  must use TCP/IP sockets to connect to MySQL, as 
  204.   Java does not support Unix Domain Sockets. Therefore, when MySQL Connector/J 
  205.   connects to MySQL, the security manager in MySQL server will use the
  206.   HOSTS table to determine whether or not the connection should be allowed.
  207.  
  208.   You must add grants to allow this to happen. The following is an example
  209.   of how to do this (but not the most secure).
  210.  
  211.   From the mysql command-line client, issue the following command
  212.  
  213.   "GRANT ALL PRIVILEGES ON [dbname].* to '[user]'@'[hostname]' identified by 
  214.   '[password]'"
  215.  
  216.   replacing [dbname] with the name of your database, [user] with the username,
  217.   [hostname] with the host that MySQL Connector/J  will be connecting from, and [password]
  218.   with the password you want to use. Be aware that RedHat linux is broken with
  219.   respect to the hostname portion for the case when you are connecting from 
  220.   localhost. You need to use "localhost.localdomain" for the [hostname] value 
  221.   in this case.
  222.  
  223.   Follow this by issuing the "FLUSH PRIVILEGES" command.
  224.  
  225.   I suggest you read the permissions/security section of your MySQL server 
  226.   manual for a much more detailed explanation of how this works.
  227.   
  228.   ----
  229.  
  230.   Issue: 
  231.  
  232.   "My application throws a SQLException 'No Suitable Driver'".
  233.  
  234.   Resolution: 
  235.  
  236.   One of two things are happening. Either the driver is not in
  237.   your CLASSPATH (see the "USAGE AND INSTALLATION" section above), or your
  238.   URL format is incoorect (once again see "USAGE AND INSTALLATION").
  239.  
  240.   ----
  241.  
  242.   Issue: 
  243.  
  244.   "I'm trying to use MySQL Connector/J  in an applet and I get the following
  245.   exception: 
  246.   
  247.   SQLException: Cannot connect to MySQL server on host:3306. Is there 
  248.   a MySQL server running on the machine/port you are trying to connect to? 
  249.   (java.security.AccessControlException) 
  250.   SQLState:     08S01 
  251.   VendorError:  0 
  252.   
  253.   What's wrong?"
  254.  
  255.   Resolution:
  256.   
  257.   Applets can only make network connections back to the machine that the
  258.   webserver that served the .class files for the applet. This means that
  259.   mysql must run on the same machine (or you must have some sort of port
  260.   re-direction) for this to work. This also means that you will not be
  261.   able to test applets from your local filesystem, you must always deploy
  262.   them to a webserver.
  263.  
  264.   ----
  265.  
  266.   Issue: 
  267.  
  268.   "I have a servlet/application that works fine for a day, and then stops 
  269.   working overnight".
  270.  
  271.   Resolution: 
  272.  
  273.   MySQL closes connections after 8 hours of inactivity. You either
  274.   need to use a connection pool that handles stale connections or use the 
  275.   "autoReconnect" parameter (see "USAGE AND INSTALLATION"). Also, you should
  276.   be catching SQLExceptions in your application and dealing with them, rather
  277.   than propagating them all the way until your application exits, this is just
  278.   good software development. MySQL Connector/J  will set the SQLState (see 
  279.   java.sql.SQLException.getSQLState() in your APIDOCS) to "08S01" when it 
  280.   encounters network-connectivity issues during the processing of a query. 
  281.   Your application code should then attempt to re-connect to MySQL at this 
  282.   point.
  283.  
  284.   ----
  285.  
  286.   Issue:
  287.  
  288.   "I'm trying to use JDBC-2.0 updatable result sets, and I get an exception
  289.   saying my result set is not updatable..."
  290.  
  291.   Resolution:
  292.  
  293.   Because MySQL does not have row identifiers, MySQL Connector/J  can only update
  294.   result sets that have come from queries that select the primary key(s) and
  295.   only span one table (i.e. no joins). This is outlined in the JDBC specification.
  296.  
  297.  
  298. KNOWN BUGS
  299.  
  300. There are some parts of the JDBC-2.0 spec that are not implemented (yet). 
  301.  
  302. If you see something that is not implemented, and you have an idea on how to
  303. do it, go ahead and let me know. I'm always looking for help and/or feedback
  304. about the driver.
  305.  
  306. SUPPORT
  307.  
  308. Commercial support for MySQL Connector/J is available from MySQL-AB. Please
  309. e-mail sales@mysql.com for more information.
  310.  
  311. Community-based support is available by subscribing to java@lists.mysql.com.
  312. See http://www.mysql.com/documentation/lists.html for more information.
  313.  
  314. --
  315. This software is OSI Certified Open Source Software.
  316. OSI Certified is a certification mark of the Open Source Initiative.
  317.