mysql-connector-java-5.1.5

1. MySQL Connector/J ________________________________________________________ MySQL provides connectivity for client applications developed in the Java programming language via a JDBC driver, which is called MySQL Connector/J. MySQL Connector/J is a JDBC-3.0 Type 4 driver, which means that is pure Java, implements version 3.0 of the JDBC specification, and communicates directly with the MySQL server using the MySQL protocol. Although JDBC is useful by itself, we would hope that if you are not familiar with JDBC that after reading the first few sections of this manual, that you would avoid using naked JDBC for all but the most trivial problems and consider using one of the popular persistence frameworks such as Hibernate (http://www.hibernate.org/), Spring's JDBC templates (http://www.springframework.org/) or Ibatis SQL Maps (http://ibatis.apache.org/) to do the majority of repetitive work and heavier lifting that is sometimes required with JDBC. This section is not designed to be a complete JDBC tutorial. If you need more information about using JDBC you might be interested in the following online tutorials that are more in-depth than the information presented here: * JDBC Basics (http://java.sun.com/docs/books/tutorial/jdbc/basics/inde x.html) --- A tutorial from Sun covering beginner topics in JDBC * JDBC Short Course (http://java.sun.com/developer/onlineTraining/Database/JD BCShortCourse/index.html) --- A more in-depth tutorial from Sun and JGuru Key topics: * For help with connection strings, connection options setting up your connection through JDBC, see Section Section, "Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J." * For tips on using Connector/J and JDBC with generic J2EE toolkits, see Section Section, "Using Connector/J with J2EE and Other Java Frameworks." * Developers using the Tomcat server platform, see Section Section, "Using Connector/J with Tomcat." * Developers using JBoss, see Section Section, "Using Connector/J with JBoss." * Developers using Spring, see Section Section, "Using Connector/J with Spring." MySQL Enterprise MySQL Enterprise subscribers will find more information about using JDBC with MySQL in the Knowledge Base articles about JDBC (https://kb.mysql.com/search.php?cat=search&category=10). Access to the MySQL Knowledge Base collection of articles is one of the advantages of subscribing to MySQL Enterprise. For more information see http://www.mysql.com/products/enterprise/advisors.html. 1.1. Connector/J Versions There are currently four versions of MySQL Connector/J available: * Connector/J 5.1 is current in alpha status. It provides compatibility with all the functionality of MySQL, including 4.1, 5.0, 5.1 and the 6.0 alpha release featuring the new Falcon storage engine. Connector/J 5.1 provides ease of development features, including auto-registration with the Driver Manager, standardized validity checks, categorized SQLExceptions, support for the JDBC-4.0 XML processing, per connection client information, NCHAR, NVARCHAR and NCLOB types. This release also includes all bug fixes up to and including Connector/J 5.0.6. * Connector/J 5.0 provides support for all the functionality offered by Connector/J 3.1 and includes distributed transaction (XA) support. * Connector/J 3.1 was designed for connectivity to MySQL 4.1 and MySQL 5.0 servers and provides support for all the functionality in MySQL 5.0 except distributed transaction (XA) support. * Connector/J 3.0 provides core functionality and was designed with connectivity to MySQL 3.x or MySQL 4.1 servers, although it will provide basic compatibility with later versions of MySQL. Connector/J 3.0 does not support server-side prepared statements, and does not support any of the features in versions of MySQL later than 4.1. The current recommended version for Connector/J is 5.0. This guide covers all three connector versions, with specific notes given where a setting applies to a specific option. 1.1.1. Java Versions Supported MySQL Connector/J supports Java-2 JVMs, including: * JDK 1.2.x (only for Connector/J 3.1.x or earlier) * JDK 1.3.x * JDK 1.4.x * JDK 1.5.x If you are building Connector/J from source using the source distribution (see Section Section, "Installing from the Development Source Tree") then you must use JDK 1.4.x or newer to compiler the Connector package. MySQL Connector/J does not support JDK-1.1.x or JDK-1.0.x. Because of the implementation of java.sql.Savepoint, Connector/J 3.1.0 and newer will not run on JDKs older than 1.4 unless the class verifier is turned off (by setting the -Xverify:none option to the Java runtime). This is because the class verifier will try to load the class definition for java.sql.Savepoint even though it is not accessed by the driver unless you actually use savepoint functionality. Caching functionality provided by Connector/J 3.1.0 or newer is also not available on JVMs older than 1.4.x, as it relies on java.util.LinkedHashMap which was first available in JDK-1.4.0. 1.2. Connector/J Installation You can install the Connector/J package using two methods, using either the binary or source distribution. The binary distribution provides the easiest methods for installation; the source distribution enables you to customize your installation further. With either solution, you must manually add the Connector/J location to your Java CLASSPATH. 1.2.1. Installing Connector/J from a Binary Distribution The easiest method of installation is to use the binary distribution of the Connector/J package. The binary distribution is available either as a Tar/Gzip or Zip file which you must extract to a suitable location and then optionally make the information about the package available by changing your CLASSPATH (see Section Section, "Installing the Driver and Configuring the CLASSPATH"). MySQL Connector/J is distributed as a .zip or .tar.gz archive containing the sources, the class files, and the JAR archive named mysql-connector-java-[version]-bin.jar, and starting with Connector/J 3.1.8 a debug build of the driver in a file named mysql-connector-java-[version]-bin-g.jar. Starting with Connector/J 3.1.9, the .class files that constitute the JAR files are only included as part of the driver JAR file. You should not use the debug build of the driver unless instructed to do so when reporting a problem or a bug to MySQL AB, as it is not designed to be run in production environments, and will have adverse performance impact when used. The debug binary also depends on the Aspect/J runtime library, which is located in the src/lib/aspectjrt.jar file that comes with the Connector/J distribution. You will need to use the appropriate graphical or command-line utility to extract the distribution (for example, WinZip for the .zip archive, and tar for the .tar.gz archive). Because there are potentially long filenames in the distribution, we use the GNU tar archive format. You will need to use GNU tar (or an application that understands the GNU tar archive format) to unpack the .tar.gz variant of the distribution. 1.2.2. Installing the Driver and Configuring the CLASSPATH Once you have extracted the distribution archive, you can install th