Author: tbedford
Date: 2008-08-08 16:26:49 +0200 (Fri, 08 Aug 2008)
New Revision: 11511
Log:
Updates regarding JVM support and details on compiling C/J 5.1 source code.\nSome general updates and corrections.
Modified:
trunk/refman-common/connector-j.xml
Modified: trunk/refman-common/connector-j.xml
===================================================================
--- trunk/refman-common/connector-j.xml 2008-08-08 02:18:29 UTC (rev 11510)
+++ trunk/refman-common/connector-j.xml 2008-08-08 14:26:49 UTC (rev 11511)
Changed blocks: 19, Lines Added: 182, Lines Deleted: 71; 14515 bytes
@@ -17,7 +17,7 @@
<para>
MySQL Connector/J is a JDBC Type 4 driver. Different versions are
- available that are compatible with the JDBC-3.0 and JDBC-4.0
+ available that are compatible with the JDBC 3.0 and JDBC 4.0
specifications. The Type 4 designation means that the driver is
pure-Java implementation of the MySQL protocol and does not rely on
the MySQL client libraries.
@@ -109,10 +109,19 @@
<para>
Developers using Spring, see
<xref
- linkend="connector-j-usagenotes-spring-config"/>.
+ linkend="connector-j-usagenotes-spring-config"/>.
</para>
</listitem>
+<!-- <listitem>
+ <para>
+ Developers using GlassFish (Sun Application Server), see
+ <xref
+ linkend="connector-j-usagenotes-glassfish-config"/>.
+ </para>
+ </listitem>
+ -->
+
</itemizedlist>
<formalpara role="mnmas-kb">
@@ -143,7 +152,8 @@
<listitem>
<para>
- Connector/J 5.1 is the Type IV pure Java JDBC driver and
+ Connector/J 5.1 is the Type 4 pure Java JDBC driver, which
+ conforms to the JDBC 3.0 and JDBC 4.0 specifications. 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
@@ -188,8 +198,61 @@
</itemizedlist>
<para>
+ The following table summarizes the Connector/J versions available:
+ </para>
+
+ <para>
+ <informaltable>
+ <tgroup cols="5">
+ <colspec colwidth="20*"/>
+ <colspec colwidth="20*"/>
+ <colspec colwidth="20*"/>
+ <colspec colwidth="20*"/>
+ <colspec colwidth="20*"/>
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">Connector/J version</emphasis></entry>
+ <entry><emphasis role="bold">Driver Type</emphasis></entry>
+ <entry><emphasis role="bold">JDBC version</emphasis></entry>
+ <entry><emphasis role="bold">MySQL Server version</emphasis></entry>
+ <entry><emphasis role="bold">Status</emphasis></entry>
+ </row>
+ <row>
+ <entry>5.1</entry>
+ <entry>4</entry>
+ <entry>3.0, 4.0</entry>
+ <entry>4.1, 5.0, 5.1, 6.0</entry>
+ <entry>Recommended version</entry>
+ </row>
+ <row>
+ <entry>5.0</entry>
+ <entry>4</entry>
+ <entry>3.0</entry>
+ <entry>4.1, 5.0</entry>
+ <entry>Released version</entry>
+ </row>
+ <row>
+ <entry>3.1</entry>
+ <entry>4</entry>
+ <entry>3.0</entry>
+ <entry>4.1, 5.0</entry>
+ <entry>Obsolete</entry>
+ </row>
+ <row>
+ <entry>3.0</entry>
+ <entry>4</entry>
+ <entry>3.0</entry>
+ <entry>3.x, 4.1</entry>
+ <entry>Obsolete</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+
+ <para>
The current recommended version for Connector/J is 5.1. This guide
- covers all three connector versions, with specific notes given
+ covers all four connector versions, with specific notes given
where a setting applies to a specific option.
</para>
@@ -198,49 +261,44 @@
<title>Java Versions Supported</title>
<para>
- MySQL Connector/J supports Java-2 JVMs, including:
+ The following table summarizes Connector/J Java dependencies:
</para>
- <itemizedlist>
-
- <listitem>
- <para>
- JDK 1.2.x (only for Connector/J 3.1.x or earlier)
- </para>
- </listitem>
-
- <listitem>
- <para>
- JDK 1.3.x
- </para>
- </listitem>
-
- <listitem>
- <para>
- JDK 1.4.x
- </para>
- </listitem>
-
- <listitem>
- <para>
- JDK 1.5.x
- </para>
- </listitem>
-
- <listitem>
- <para>
- JDK 1.6.x
- </para>
- </listitem>
-
- </itemizedlist>
-
<para>
- If you are building Connector/J from source using the source
- distribution (see
- <xref linkend="connector-j-installing-source"/>) then you must
- use JDK 1.4.x or newer to compile the Connector package. For
- Connector/J 5.1 you must use JDK-1.6.x.
+ <informaltable>
+ <tgroup cols="3">
+ <colspec colwidth="30*"/>
+ <colspec colwidth="30*"/>
+ <colspec colwidth="30*"/>
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">Connector/J version</emphasis></entry>
+ <entry><emphasis role="bold">Java RTE required</emphasis></entry>
+ <entry><emphasis role="bold">JDK required (to build source code)</emphasis></entry>
+ </row>
+ <row>
+ <entry>5.1</entry>
+ <entry>1.3.x, 1.4.x, 1.5.x, 1.6.x</entry>
+ <entry>1.6.x and 1.5.x (or older)</entry>
+ </row>
+ <row>
+ <entry>5.0</entry>
+ <entry>1.3.x, 1.4.x, 1.5.x, 1.6.x</entry>
+ <entry>1.4.2, 1.5.x, 1.6.x</entry>
+ </row>
+ <row>
+ <entry>3.1</entry>
+ <entry>1.2.x, 1.3.x, 1.4.x, 1.5.x, 1.6.x</entry>
+ <entry>1.4.2, 1.5.x, 1.6.x</entry>
+ </row>
+ <row>
+ <entry>3.0</entry>
+ <entry>1.2.x, 1.3.x, 1.4.x, 1.5.x, 1.6.x</entry>
+ <entry>1.4.2, 1.5.x, 1.6.x</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
</para>
<para>
@@ -250,8 +308,8 @@
<para>
Because of the implementation of
<classname>java.sql.Savepoint</classname>, 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
+ newer will not run on a Java runtime older than 1.4 unless the
+ class verifier is turned off (by setting the
<option>-Xverify:none</option> option to the Java runtime). This
is because the class verifier will try to load the class
definition for <classname>java.sql.Savepoint</classname> even
@@ -266,6 +324,15 @@
available in JDK-1.4.0.
</para>
+ <para>
+ If you are building Connector/J from source code using the
+ source distribution (see
+ <xref linkend="connector-j-installing-source"/>) then you must
+ use JDK 1.4.2 or newer to compile the Connector package. For
+ Connector/J 5.1 you must have both JDK-1.6.x. and JDK-1.5.x
+ installed in order to be able to build the source code.
+ </para>
+
</section>
</section>
@@ -275,12 +342,12 @@
<title>Connector/J Installation</title>
<para>
- 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 <literal>CLASSPATH</literal>.
+ You can install the Connector/J package using either the binary or
+ source distribution. The binary distribution provides the easiest
+ method 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
+ <literal>CLASSPATH</literal>.
</para>
<para>
@@ -360,7 +427,7 @@
<para>
If you are going to use the driver with the JDBC DriverManager,
you would use <literal>com.mysql.jdbc.Driver</literal> as the
- class that implements java.sql.Driver.
+ class that implements <classname>java.sql.Driver</classname>.
</para>
<para>
@@ -384,18 +451,18 @@
Or with a Bourne-compatible shell (sh, ksh, bash):
</para>
-<programlisting>export set CLASSPATH=/path/mysql-connector-java-[ver]-bin.jar:$CLASSPATH</programlisting>
+<programlisting>shell> export set CLASSPATH=/path/mysql-connector-java-[ver]-bin.jar:$CLASSPATH</programlisting>
<para>
- Within Windows 2000, Windows XP and Windows Server 2003, you
- must set the environment variable through the System control
- panel.
+ Within Windows 2000, Windows XP, Windows Server 2003 and Windows
+ Vista, you must set the environment variable through the System
+ Control Panel.
</para>
<para>
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
+ such as GlassFish, 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 <literal>CLASSPATH</literal> environment variable. For
configuration examples for some J2EE application servers, see
@@ -414,9 +481,9 @@
</para>
<para>
- You can also use the MysqlDataSource or
- MysqlConnectionPoolDataSource classes in the
- <literal>com.mysql.jdbc.jdbc2.optional</literal> package, if
+ You can also use the <classname>MysqlDataSource</classname> or
+ <classname>MysqlConnectionPoolDataSource</classname> classes in
+ the <literal>com.mysql.jdbc.jdbc2.optional</literal> package, if
your J2EE application server supports or requires them. Starting
with Connector/J 5.0.0, the
<literal>javax.sql.XADataSource</literal> interface is
@@ -427,8 +494,9 @@
</para>
<para>
- The various MysqlDataSource classes support the following
- parameters (through standard set mutators):
+ The various <classname>MysqlDataSource</classname> classes
+ support the following parameters (through standard set
+ mutators):
</para>
<itemizedlist>
@@ -595,7 +663,7 @@
from this behavior via
<property>noDatetimeStringSync=true</property> (the
default value is <literal>false</literal>) so that you can
- get retrieve the unaltered all-zero value as a String. It
+ retrieve the unaltered all-zero value as a String. It
should be noted that this also precludes using any time
zone conversions, therefore the driver will not allow you
to enable <property>noDatetimeStringSync</property> and
@@ -778,7 +846,7 @@
You should read this section only if you are interested in
helping us test our new code. If you just want to get MySQL
Connector/J up and running on your system, you should use a
- standard release distribution.
+ standard binary release distribution.
</para>
</caution>
@@ -807,9 +875,12 @@
<listitem>
<para>
- JDK-1.4.2 or later. Although MySQL Connector/J can be
- installed on older JDKs, to compile it from source you must
- have at least JDK-1.4.2.
+ JDK 1.4.2 or later. Although MySQL Connector/J can be be
+ used with older JDKs, to compile it from source you must
+ have at least JDK 1.4.2. If you are building Connector/J 5.1
+ you will need JDK 1.6.x and an older JDK such as JDK 1.5.x.
+ You will then need to point your JAVA_HOME environment
+ variable at the older installation.
</para>
</listitem>
@@ -852,6 +923,17 @@
<listitem>
<para>
+ If you are building Connector/J 5.1 make sure that you have
+ both JDK 1.6.x installed and an older JDK such as JDK 1.5.x.
+ This is because Connector/J supports both JDBC 3.0 (which
+ was prior to JDK 1.6.x) and JDBC 4.0. Set your JAVA_HOME
+ environment variable to the path of the older JDK
+ installation.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
Change location to the <filename>connector-j</filename>
directory to make it your current working directory:
</para>
@@ -861,6 +943,25 @@
<listitem>
<para>
+ If you are building Connector/J 5.1 you need to edit the
+ <filename>build.xml</filename> to reflect the location of
+ your JDK 1.6.x installation. The lines that you need to
+ change are:
+ </para>
+
+<programlisting>
+ <property name="com.mysql.jdbc.java6.javac" value="C:\jvms\jdk1.6.0\bin\javac.exe" />
+ <property name="com.mysql.jdbc.java6.rtjar" value="C:\jvms\jdk1.6.0\jre\lib\rt.jar" />
+ </programlisting>
+
+ <para>
+ Alternatively, you can set the value of these property names
+ through the Ant <option>-D</option> option.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
Issue the following command to compile the driver and create
a <filename>.jar</filename> file suitable for installation:
</para>
@@ -901,8 +1002,10 @@
</orderedlist>
<para>
- If you want to build the Connector/J 5.1 branch then you must
- have a compatible JDK 6.0 installed.
+ A package containing both the binary and source code for
+ Connector/J 5.1 can also be found at the following location:
+ <ulink url="http://dev.mysql.com/downloads/connector/j/5.1.html">
+ Connector/J 5.1 Download</ulink>
</para>
</section>
@@ -4335,6 +4438,14 @@
</section>
+ <section id="connector-j-usagenotes-glassfish-config">
+
+ <title>Using Connector/J with GlassFish</title>
+
+ <para />
+
+ </section>
+
<!--
<section id="connector-j-usagenotes-struts-config">
<title>Using Connector/J with Struts</title>
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r11511 - trunk/refman-common | anthony.bedford | 8 Aug |
