mysql-connector-java-5.1.0

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/index.htm l) --- A tutorial from Sun covering beginner topics in JDBC * JDBC Short Course (http://java.sun.com/developer/onlineTraining/Database/JDBCSho rtCourse/index.html) --- A more in-depth tutorial from Sun and JGuru 1.1. Connector/J Versions There are currently three versions of MySQL Connector/J available: * 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. * 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 5.0 provides support for all the functionality offered by Connector/J 3.1 and includes distributed transaction (XA) support. 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 ors 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 the driver by placing mysql-connector-java-[version]-bin.jar in your classpath, either by adding the full path to it to your CLASSPATH environment variable, or by directly specifying it with the command line switch -cp when starting your JVM. If you are going to use the driver with the JDBC DriverManager, you would use com.mysql.jdbc.Driver as the class that implements java.sql.Driver. You can set the CLASSPATH environment variable under UNIX, Linux or Mac OS X either locally for a user within their .profile, .login or other login file. You can also set it globally by editing the global /etc/profile file. For example, under a C shell (csh, tcsh) you would add the Connector/J driver to your CLASSPATH using the following: shell> setenv CLASSPATH /path/mysql-connector-java-[ver]-bin.jar:$CLA SSPATH Or with a Bourne-compatible shell (sh, ksh, bash): export set CLASSPATH=/path/mysql-connector-java-[ver]-bin.jar:$CLASSP ATH Within Windows 2000, Windows XP and Windows Server 2003, you must set the environment variable through the System control panel. If you want to use MySQL Connector/J with an application server such as Tomcat or JBoss, you will have to read your vendor's documentation for more information on how to configure third-party class libraries, as most application servers ignore the CLASSPATH environment variable. For configuration examples for some J2EE application servers, see Section Section, "Using Connector/J with J2EE and Other Java Frameworks." However, the authoritative source for JDBC connection pool configuration information for your particular application server is the documentation for that application server. If you are developing servlets or JSPs, and your application