MySQL Lists are EOL. Please join:

List:Commits« Previous MessageNext Message »
From:mcbrown Date:August 2 2006 10:55am
Subject:svn commit - mysqldoc@docsrva: r2918 - trunk/refman-4.1
View as plain text  
Author: mcbrown
Date: 2006-08-02 12:55:34 +0200 (Wed, 02 Aug 2006)
New Revision: 2918

Log:
Rolling C/J back into the main docs



Modified:
   trunk/refman-4.1/connector-j.xml
   trunk/refman-4.1/news.xml
   trunk/refman-4.1/renamed-nodes.txt


Modified: trunk/refman-4.1/connector-j.xml
===================================================================
--- trunk/refman-4.1/connector-j.xml	2006-08-01 18:56:55 UTC (rev 2917)
+++ trunk/refman-4.1/connector-j.xml	2006-08-02 10:55:34 UTC (rev 2918)
Changed blocks: 72, Lines Added: 2538, Lines Deleted: 2528; 237232 bytes

@@ -4,12 +4,12 @@
 [
   <!ENTITY % fixedchars.entities  SYSTEM "../refman-common/fixedchars.ent">
   %fixedchars.entities;
-  <!ENTITY % urls.entities       SYSTEM "../refman-common/urls.ent">
-  %urls.entities;
+  <!ENTITY % title.entities       SYSTEM "../refman-common/urls.ent">
+  %title.entities;
   <!ENTITY % versions.entities    SYSTEM "versions.ent">
   %versions.entities;
 ]>
-<section id="java-connector">
+<section id="connector-j">
 
   <title>MySQL Connector/J</title>
 

@@ -20,24 +20,18 @@
   </para>
 
   <para>
-    MySQL Connector/J is a JDBC-3.0 <quote>Type 4</quote> 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.
+    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.
   </para>
 
   <para>
-    This document is arranged for a beginning JDBC developer. If you are
-    already experienced with using JDBC, you might consider starting
-    with the <xref linkend="cj-installing"/>.
-  </para>
-
-  <para>
     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 <quote>naked</quote> JDBC for all
-    but the most trivial problems and consider using one of the popular
-    persistence frameworks such as
+    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
     <ulink url="http://www.hibernate.org/">Hibernate</ulink>,
     <ulink url="http://www.springframework.org/">Spring's JDBC
     templates</ulink> or <ulink url="http://ibatis.apache.org/">Ibatis

@@ -57,7 +51,8 @@
     <listitem>
       <para>
         <ulink
-      url="http://java.sun.com/docs/books/tutorial/jdbc/basics/index.html">JDBC
+          url="http://java.sun.com/docs/books/tutorial/jdbc/basics/index.html"
+          >JDBC
         Basics</ulink> &mdash; A tutorial from Sun covering beginner
         topics in JDBC
       </para>

@@ -65,7 +60,9 @@
 
     <listitem>
       <para>
-        <ulink url="http://java.sun.com/developer/onlineTraining/Database/JDBCShortCourse/index.html">JDBC
+        <ulink
+          url="http://java.sun.com/developer/onlineTraining/Database/JDBCShortCourse/index.html"
+          >JDBC
         Short Course</ulink> &mdash; A more in-depth tutorial from Sun
         and JGuru
       </para>

@@ -73,1060 +70,314 @@
 
   </itemizedlist>
 
-  <section id="cj-basic-jdbc">
+  <section id="connector-j-versions">
 
-    <title>Basic JDBC concepts</title>
+    <title>Connector/J Versions</title>
 
     <para>
-      This section provides some general JDBC background.
+      There are currently three version of MySQL Connector/J available:
     </para>
 
-    <section id="cj-connect-with-drivermanager">
+    <itemizedlist>
 
-      <title>Connecting to MySQL Using the <literal>DriverManager</literal> Interface</title>
+      <listitem>
+        <para>
+          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.
+        </para>
+      </listitem>
 
-      <para>
-        When you are using JDBC outside of an application server, the
-        <literal>DriverManager</literal> class manages the establishment
-        of Connections.
-      </para>
+      <listitem>
+        <para>
+          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.
+        </para>
+      </listitem>
 
-      <para>
-        The <literal>DriverManager</literal> needs to be told which JDBC
-        drivers it should try to make Connections with. The easiest way
-        to do this is to use <function>Class.forName()</function> on the
-        class that implements the <literal>java.sql.Driver</literal>
-        interface. With MySQL Connector/J, the name of this class is
-        <literal>com.mysql.jdbc.Driver</literal>. With this method, you
-        could use an external configuration file to supply the driver
-        class name and driver parameters to use when connecting to a
-        database.
-      </para>
+      <listitem>
+        <para>
+          Connector/J 5.0 provides support for all the functionality
+          offered by Connector/J 3.1 and includes distributed
+          transaction (XA) support.
+        </para>
+      </listitem>
 
-      <para>
-        The following section of Java code shows how you might register
-        MySQL Connector/J from the <function>main()</function> method of
-        your application:
-      </para>
+    </itemizedlist>
 
-<programlisting>import java.sql.Connection;
-import java.sql.DriverManager;
-import java.sql.SQLException;
+    <para>
+      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.
+    </para>
 
-// Notice, do not import com.mysql.jdbc.*
-// or you will have problems!
+    <section id="connector-j-versions-java">
 
-public class LoadDriver {
-    public static void main(String[] args) {
-        try {
-            // The newInstance() call is a work around for some
-            // broken Java implementations
+      <title>Java Versions Supported</title>
 
-            Class.forName("com.mysql.jdbc.Driver").newInstance();
-        } catch (Exception ex) {
-            // handle the error
-        }
-}</programlisting>
-
       <para>
-        After the driver has been registered with the
-        <literal>DriverManager</literal>, you can obtain a
-        <literal>Connection</literal> instance that is connected to a
-        particular database by calling
-        <function>DriverManager.getConnection()</function>:
+        MySQL Connector/J supports Java-2 JVMs, including:
       </para>
 
-      <example>
+      <itemizedlist>
 
-        <title>Obtaining a Connection From the <literal>DriverManager</literal></title>
+        <listitem>
+          <para>
+            JDK 1.2.x
+          </para>
+        </listitem>
 
-        <para>
-          This example shows how you can obtain a
-          <literal>Connection</literal> instance from the
-          <literal>DriverManager</literal>. There are a few different
-          signatures for the <function>getConnection()</function>
-          method. You should see the API documentation that comes with
-          your JDK for more specific information on how to use them.
-        </para>
+        <listitem>
+          <para>
+            JDK 1.3.x
+          </para>
+        </listitem>
 
-<programlisting>
-import java.sql.Connection;
-import java.sql.DriverManager;
-import java.sql.SQLException;
+        <listitem>
+          <para>
+            JDK 1.4.x
+          </para>
+        </listitem>
 
-    ... try {
-            Connection conn = DriverManager.getConnection("jdbc:mysql://localhost/test?user=monty&amp;password=greatsqldb");
+        <listitem>
+          <para>
+            JDK 1.5.x
+          </para>
+        </listitem>
 
-            // Do something with the Connection
+      </itemizedlist>
 
-           ....
-        } catch (SQLException ex) {
-            // handle any errors
-            System.out.println("SQLException: " + ex.getMessage());
-            System.out.println("SQLState: " + ex.getSQLState());
-            System.out.println("VendorError: " + ex.getErrorCode());
-        }
-</programlisting>
+      <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 compiler the Connector package.
+      </para>
 
-        <para>
-          Once a <classname>Connection</classname> is established, it
-          can be used to create <classname>Statement</classname> and
-          <classname>PreparedStatement</classname> objects, as well as
-          retrieve metadata about the database. This is explained in the
-          following sections.
-        </para>
+      <para>
+        MySQL Connector/J does not support JDK-1.1.x or JDK-1.0.x
+      </para>
 
-      </example>
+      <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
+        <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
+        though it is not accessed by the driver unless you actually use
+        savepoint functionality.
+      </para>
 
+      <para>
+        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
+        <classname>java.util.LinkedHashMap</classname> which was first
+        available in JDK-1.4.0.
+      </para>
+
     </section>
 
-<!--
-        <section id="cj-connect-with-datasource">
-          <title>Connecting to MySQL Using the <literal>DataSource</literal> Interface;</title>
+  </section>
 
-          <para />
-        </section>
--->
+  <section id="connector-j-installing">
 
-<!--
-        <section id="cj-controlling-transactions">
-          <title>Controlling transactions</title>
+    <title>Installing Connector/J</title>
 
-          <para />
-        </section>
--->
+    <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 with either solution, you must
+    </para>
 
-    <section id="cj-using-statements">
+    <section id="connector-j-installing-binary">
 
-      <title>Using Statements to Execute SQL</title>
+      <title>Installing Connector/J from a binary distribution</title>
 
       <para>
-        <classname>Statement</classname> objects allow you to execute
-        basic SQL queries and retrieve the results through the
-        <literal>ResultSet</literal> class which is described later.
+        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
+        <literal>CLASSPATH</literal> (see
+        <xref
+          linkend="connector-j-installing-classpath"/>).
       </para>
 
       <para>
-        To create a <classname>Statement</classname> instance, you call
-        the <function>createStatement()</function> method on the
-        <literal>Connection</literal> object you have retrieved via one
-        of the <function>DriverManager.getConnection()</function> or
-        <function>DataSource.getConnection()</function> methods
-        described earlier.
+        MySQL Connector/J is distributed as a .zip or .tar.gz archive
+        containing the sources, the class files, and the JAR archive
+        named
+        <filename>mysql-connector-java-<replaceable>[version]</replaceable>-bin.jar</filename>,
+        and starting with Connector/J 3.1.8 a debug build of the driver
+        in a file named
+        <filename>mysql-connector-java-<replaceable>[version]</replaceable>-bin-g.jar</filename>.
       </para>
 
       <para>
-        Once you have a <classname>Statement</classname> instance, you
-        can execute a <literal>SELECT</literal> query by calling the
-        <literal>executeQuery(String)</literal> method with the SQL you
-        want to use.
+        Starting with Connector/J 3.1.9, the <filename>.class</filename>
+        files that constitute the JAR files are only included as part of
+        the driver JAR file.
       </para>
 
       <para>
-        To update data in the database, use the
-        <literal>executeUpdate(String SQL)</literal> method. This method
-        returns the number of rows affected by the update statement.
+        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 <filename>src/lib/aspectjrt.jar</filename> file
+        that comes with the Connector/J distribution.
       </para>
 
       <para>
-        If you don't know ahead of time whether the SQL statement will
-        be a <literal>SELECT</literal> or an
-        <literal>UPDATE</literal>/<literal>INSERT</literal>, then you
-        can use the <literal>execute(String SQL)</literal> method. This
-        method will return true if the SQL query was a
-        <literal>SELECT</literal>, or false if it was an
-        <literal>UPDATE</literal>, <literal>INSERT</literal>, or
-        <literal>DELETE</literal> statement. If the statement was a
-        <literal>SELECT</literal> query, you can retrieve the results by
-        calling the <function>getResultSet()</function> method. If the
-        statement was an <literal>UPDATE</literal>,
-        <literal>INSERT</literal>, or <literal>DELETE</literal>
-        statement, you can retrieve the affected rows count by calling
-        <function>getUpdateCount()</function> on the
-        <classname>Statement</classname> instance.
+        You will need to use the appropriate graphical or command-line
+        utility to un-archive the distribution (for example, WinZip for
+        the .zip archive, and <command>tar</command> 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.
       </para>
 
-      <example>
-
-        <title>Using java.sql.Statement to Execute a SELECT Query</title>
-
-<programlisting>// assume that conn is an already created JDBC connection
-Statement stmt = null;
-ResultSet rs = null;
-
-try {
-    stmt = conn.createStatement();
-    rs = stmt.executeQuery("SELECT foo FROM bar");
-
-    // or alternatively, if you don't know ahead of time that
-    // the query will be a SELECT...
-
-    if (stmt.execute("SELECT foo FROM bar")) {
-        rs = stmt.getResultSet();
-    }
-
-    // Now do something with the ResultSet ....
-} finally {
-    // it is a good idea to release
-    // resources in a finally{} block
-    // in reverse-order of their creation
-    // if they are no-longer needed
-
-    if (rs != null) {
-        try {
-            rs.close();
-        } catch (SQLException sqlEx) { // ignore }
-
-        rs = null;
-    }
-
-    if (stmt != null) {
-        try {
-            stmt.close();
-        } catch (SQLException sqlEx) { // ignore }
-
-        stmt = null;
-    }
-}</programlisting>
-
-      </example>
-
     </section>
 
-<!--
-        <section id="cj-using-prepared-statements">
-          <title>Using <literal>PreparedStatements</literal> to Execute SQL</title>
+    <section id="connector-j-installing-classpath">
 
-          <para />
-        </section>
--->
+      <title>Installing the Driver and Configuring the <literal>CLASSPATH</literal></title>
 
-    <section id="cj-using-callable-statements">
-
-      <title>Using <literal>CallableStatements</literal> to Execute Stored Procedures</title>
-
       <para>
-        Starting with MySQL server version 5.0 when used with
-        Connector/J 3.1.1 or newer, the
-        <classname>java.sql.CallableStatement</classname> interface is
-        fully implemented with the exception of the
-        <function>getParameterMetaData()</function> method.
+        Once you have extracted the distribution archive, you can
+        install the driver by placing
+        <filename>mysql-connector-java-[version]-bin.jar </filename>in
+        your classpath, either by adding the full path to it to your
+        <literal>CLASSPATH</literal> environment variable, or by
+        directly specifying it with the command line switch -cp when
+        starting your JVM.
       </para>
 
       <para>
-        MySQL's stored procedure syntax is documented in the
-        "<ulink url="http://www.mysql.com/doc/en/stored-procedures.html">Stored
-        Procedures and Functions</ulink>" section of the MySQL Reference
-        Manual.
+        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.
       </para>
 
       <para>
-        Connector/J exposes stored procedure functionality through
-        JDBC's <classname>CallableStatement</classname> interface.
+        You can set the <literal>CLASSPATH</literal> environment
+        variableunder UNIX, Linux or Mac OS X either locally for a user
+        within their <literal>.profile</literal>,
+        <literal>.login</literal> or other login file. You can also set
+        it globally by editing the global
+        <literal>/etc/profile</literal> file.
       </para>
 
       <para>
-        The following example shows a stored procedure that returns the
-        value of <varname>inOutParam</varname> incremented by 1, and the
-        string passed in via <varname>inputParam</varname> as a
-        <classname>ResultSet</classname>:
+        For example, under a C shell (csh, tcsh) you would add the
+        Connector/J driver to your <literal>CLASSPATH</literal> using
+        the following:
+      </para>
 
-        <example>
+<programlisting>shell&gt; setenv CLASSPATH /path/to/mysql-connector-java-[version]-bin.jar:$CLASSPATH</programlisting>
 
-          <title>Stored Procedure Example</title>
+      <para>
+        Or with a Bourne-compatible shell (sh, ksh, bash):
+      </para>
 
-<programlisting>CREATE PROCEDURE demoSp(IN inputParam VARCHAR(255), INOUT inOutParam INT)
-BEGIN
-    DECLARE z INT;
-    SET z = inOutParam + 1;
-    SET inOutParam = z;
+<programlisting>export set CLASSPATH=/path/to/mysql-connector-java-[version]-bin.jar:$CLASSPATH</programlisting>
 
-    SELECT inputParam;
+      <para>
+        Within Windows 2000, Windows XP and Windows Server 2003, you
+        must set the environment variable through the System control
+        panel.
+      </para>
 
-    SELECT CONCAT('zyxw', inputParam);
-END</programlisting>
+      <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
+        third-party class libraries, as most application servers ignore
+        the <literal>CLASSPATH</literal> environment variable. For
+        configuration examples for some J2EE application servers, see
+        <xref linkend="connector-j-usagenotes-j2ee"/>. However, the
+        authoritative source for JDBC connection pool configuration
+        information for your particular application server is the
+        documentation for that application server.
+      </para>
 
-        </example>
+      <para>
+        If you are developing servlets or JSPs, and your application
+        server is J2EE-compliant, you can put the driver's .jar file in
+        the WEB-INF/lib subdirectory of your webapp, as this is a
+        standard location for third party class libraries in J2EE web
+        applications.
       </para>
 
       <para>
-        To use the <function>demoSp</function> procedure with
-        Connector/J, follow these steps:
+        You can also use the MysqlDataSource or
+        MysqlConnectionPoolDataSource 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
+        implemented via the
+        <literal>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</literal>
+        class, which supports XA distributed transactions when used in
+        combination with MySQL server version 5.0.
       </para>
 
-      <orderedlist>
+      <para>
+        The various MysqlDataSource classes support the following
+        parameters (through standard set mutators):
+      </para>
 
+      <itemizedlist>
+
         <listitem>
           <para>
-            Prepare the callable statement by using
-            <function>Connection.prepareCall()</function> .
+            user
           </para>
+        </listitem>
 
+        <listitem>
           <para>
-            Notice that you have to use JDBC escape syntax, and that the
-            parentheses surrounding the parameter placeholders are not
-            optional:
+            password
           </para>
-
-          <example>
-
-            <title>Using <function>Connection.prepareCall()</function></title>
-
-<programlisting>import java.sql.CallableStatement;
-
-...
-
-    //
-    // Prepare a call to the stored procedure 'demoSp'
-    // with two parameters
-    //
-    // Notice the use of JDBC-escape syntax ({call ...})
-    //
-
-    CallableStatement cStmt = conn.prepareCall("{call demoSp(?, ?)}");
-
-
-
-    cStmt.setString(1, "abcdefg");</programlisting>
-
-          </example>
-
-          <note>
-            <para>
-              <function>Connection.prepareCall()</function> is an
-              expensive method, due to the metadata retrieval that the
-              driver performs to support output parameters. For
-              performance reasons, you should try to minimize
-              unnecessary calls to
-              <function>Connection.prepareCall()</function> by reusing
-              <classname>CallableStatement</classname> instances in your
-              code.
-            </para>
-          </note>
         </listitem>
 
         <listitem>
           <para>
-            Register the output parameters (if any exist)
+            serverName (see the previous section about fail-over hosts)
           </para>
-
-          <para>
-            To retrieve the values of output parameters (parameters
-            specified as <literal>OUT</literal> or
-            <literal>INOUT</literal> when you created the stored
-            procedure), JDBC requires that they be specified before
-            statement execution using the various
-            <function>registerOutputParameter()</function> methods in
-            the <classname>CallableStatement</classname> interface:
-
-            <example>
-
-              <title>Registering Output Parameters</title>
-
-<programlisting>
-import java.sql.Types;
-...
-//
-// Connector/J supports both named and indexed
-// output parameters. You can register output
-// parameters using either method, as well
-// as retrieve output parameters using either
-// method, regardless of what method was
-// used to register them.
-//
-// The following examples show how to use
-// the various methods of registering
-// output parameters (you should of course
-// use only one registration per parameter).
-//
-
-//
-// Registers the second parameter as output, and
-// uses the type 'INTEGER' for values returned from
-// getObject()
-//
-
-cStmt.registerOutParameter(2, Types.INTEGER);
-
-//
-// Registers the named parameter 'inOutParam', and
-// uses the type 'INTEGER' for values returned from
-// getObject()
-//
-
-cStmt.registerOutParameter("inOutParam", Types.INTEGER);
-...
-</programlisting>
-
-            </example>
-          </para>
         </listitem>
 
         <listitem>
           <para>
-            Set the input parameters (if any exist)
+            databaseName
           </para>
-
-          <para>
-            Input and in/out parameters are set as for
-            <classname>PreparedStatement</classname> objects. However,
-            <classname>CallableStatement</classname> also supports
-            setting parameters by name:
-
-            <example>
-
-              <title>Setting <literal>CallableStatement</literal> Input Parameters</title>
-
-<programlisting>...
-
-    //
-    // Set a parameter by index
-    //
-
-    cStmt.setString(1, "abcdefg");
-
-    //
-    // Alternatively, set a parameter using
-    // the parameter name
-    //
-
-    cStmt.setString("inputParameter", "abcdefg");
-
-    //
-    // Set the 'in/out' parameter using an index
-    //
-
-    cStmt.setInt(2, 1);
-
-    //
-    // Alternatively, set the 'in/out' parameter
-    // by name
-    //
-
-    cStmt.setInt("inOutParam", 1);
-
-...</programlisting>
-
-            </example>
-          </para>
         </listitem>
 
         <listitem>
           <para>
-            Execute the <classname>CallableStatement</classname>, and
-            retrieve any result sets or output parameters.
+            port
           </para>
-
-          <para>
-            Although <classname>CallableStatement</classname> supports
-            calling any of the <classname>Statement</classname> execute
-            methods (<function>executeUpdate()</function>,
-            <function>executeQuery()</function> or
-            <function>execute()</function>), the most flexible method to
-            call is <function>execute()</function>, as you do not need
-            to know ahead of time if the stored procedure returns result
-            sets:
-
-            <example>
-
-              <title>Retrieving Results and Output Parameter Values</title>
-
-<programlisting>...
-
-    boolean hadResults = cStmt.execute();
-
-    //
-    // Process all returned result sets
-    //
-
-    while (hadResults) {
-        ResultSet rs = cStmt.getResultSet();
-
-        // process result set
-        ...
-
-        hadResults = cStmt.getMoreResults();
-    }
-
-    //
-    // Retrieve output parameters
-    //
-    // Connector/J supports both index-based and
-    // name-based retrieval
-    //
-
-    int outputValue = cStmt.getInt(2); // index-based
-
-    outputValue = cStmt.getInt("inOutParam"); // name-based
-
-...</programlisting>
-
-            </example>
-          </para>
         </listitem>
 
-      </orderedlist>
+      </itemizedlist>
 
     </section>
 
-    <section id="cj-retrieve-autoinc">
+    <section id="connector-j-installing-upgrading">
 
-      <title>Retrieving <literal>AUTO_INCREMENT</literal> Column Values</title>
-
-      <para>
-        Before version 3.0 of the JDBC API, there was no standard way of
-        retrieving key values from databases that supported <quote>auto
-        increment</quote> or identity columns. With older JDBC drivers
-        for MySQL, you could always use a MySQL-specific method on the
-        <classname>Statement</classname> interface, or issue the query
-        <literal>SELECT LAST_INSERT_ID()</literal> after issuing an
-        <literal>INSERT</literal> to a table that had an
-        <literal>AUTO_INCREMENT</literal> key. Using the MySQL-specific
-        method call isn't portable, and issuing a
-        <literal>SELECT</literal> to get the
-        <literal>AUTO_INCREMENT</literal> key's value requires another
-        round-trip to the database, which isn't as efficient as
-        possible. The following code snippets demonstrate the three
-        different ways to retrieve <literal>AUTO_INCREMENT</literal>
-        values. First, we demonstrate the use of the new JDBC-3.0 method
-        <function>getGeneratedKeys()</function> which is now the
-        preferred method to use if you need to retrieve
-        <literal>AUTO_INCREMENT</literal> keys and have access to
-        JDBC-3.0. The second example shows how you can retrieve the same
-        value using a standard <literal>SELECT
-        LAST_INSERT_ID()</literal> query. The final example shows how
-        updatable result sets can retrieve the
-        <literal>AUTO_INCREMENT</literal> value when using the
-        <function>insertRow()</function> method.
-
-        <example>
-
-          <title>Retrieving <literal>AUTO_INCREMENT</literal> Column Values using
-            <function>Statement.getGeneratedKeys()</function></title>
-
-<programlisting>   Statement stmt = null;
-   ResultSet rs = null;
-
-   try {
-
-    //
-    // Create a Statement instance that we can use for
-    // 'normal' result sets assuming you have a
-    // Connection 'conn' to a MySQL database already
-    // available
-
-    stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY,
-                                java.sql.ResultSet.CONCUR_UPDATABLE);
-
-    //
-    // Issue the DDL queries for the table for this example
-    //
-
-    stmt.executeUpdate("DROP TABLE IF EXISTS autoIncTutorial");
-    stmt.executeUpdate(
-            "CREATE TABLE autoIncTutorial ("
-            + "priKey INT NOT NULL AUTO_INCREMENT, "
-            + "dataField VARCHAR(64), PRIMARY KEY (priKey))");
-
-    //
-    // Insert one row that will generate an AUTO INCREMENT
-    // key in the 'priKey' field
-    //
-
-    stmt.executeUpdate(
-            "INSERT INTO autoIncTutorial (dataField) "
-            + "values ('Can I Get the Auto Increment Field?')",
-            Statement.RETURN_GENERATED_KEYS);
-
-    //
-    // Example of using Statement.getGeneratedKeys()
-    // to retrieve the value of an auto-increment
-    // value
-    //
-
-    int autoIncKeyFromApi = -1;
-
-    rs = stmt.getGeneratedKeys();
-
-    if (rs.next()) {
-        autoIncKeyFromApi = rs.getInt(1);
-    } else {
-
-        // throw an exception from here
-    }
-
-    rs.close();
-
-    rs = null;
-
-    System.out.println("Key returned from getGeneratedKeys():"
-        + autoIncKeyFromApi);
-} finally {
-
-    if (rs != null) {
-        try {
-            rs.close();
-        } catch (SQLException ex) {
-            // ignore
-        }
-    }
-
-    if (stmt != null) {
-        try {
-            stmt.close();
-        } catch (SQLException ex) {
-            // ignore
-        }
-    }
-}
-</programlisting>
-
-        </example>
-
-        <example>
-
-          <title>Retrieving <literal>AUTO_INCREMENT</literal> Column Values using
-            <function>SELECT LAST_INSERT_ID()</function></title>
-
-<programlisting>   Statement stmt = null;
-   ResultSet rs = null;
-
-   try {
-
-    //
-    // Create a Statement instance that we can use for
-    // 'normal' result sets.
-
-    stmt = conn.createStatement();
-
-    //
-    // Issue the DDL queries for the table for this example
-    //
-
-    stmt.executeUpdate("DROP TABLE IF EXISTS autoIncTutorial");
-    stmt.executeUpdate(
-            "CREATE TABLE autoIncTutorial ("
-            + "priKey INT NOT NULL AUTO_INCREMENT, "
-            + "dataField VARCHAR(64), PRIMARY KEY (priKey))");
-
-    //
-    // Insert one row that will generate an AUTO INCREMENT
-    // key in the 'priKey' field
-    //
-
-    stmt.executeUpdate(
-            "INSERT INTO autoIncTutorial (dataField) "
-            + "values ('Can I Get the Auto Increment Field?')");
-
-    //
-    // Use the MySQL LAST_INSERT_ID()
-    // function to do the same thing as getGeneratedKeys()
-    //
-
-    int autoIncKeyFromFunc = -1;
-    rs = stmt.executeQuery("SELECT LAST_INSERT_ID()");
-
-    if (rs.next()) {
-        autoIncKeyFromFunc = rs.getInt(1);
-    } else {
-        // throw an exception from here
-    }
-
-    rs.close();
-
-    System.out.println("Key returned from " + "'SELECT LAST_INSERT_ID()': "
-        + autoIncKeyFromFunc);
-
-} finally {
-
-    if (rs != null) {
-        try {
-            rs.close();
-        } catch (SQLException ex) {
-            // ignore
-        }
-    }
-
-    if (stmt != null) {
-        try {
-            stmt.close();
-        } catch (SQLException ex) {
-            // ignore
-        }
-    }
-}
-   </programlisting>
-
-        </example>
-
-        <example>
-
-          <title>Retrieving <literal>AUTO_INCREMENT</literal> Column Values in
-            <literal>Updatable ResultSets</literal></title>
-
-<programlisting>   Statement stmt = null;
-   ResultSet rs = null;
-
-   try {
-
-    //
-    // Create a Statement instance that we can use for
-    // 'normal' result sets as well as an 'updatable'
-    // one, assuming you have a Connection 'conn' to
-    // a MySQL database already available
-    //
-
-    stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY,
-                                java.sql.ResultSet.CONCUR_UPDATABLE);
-
-    //
-    // Issue the DDL queries for the table for this example
-    //
-
-    stmt.executeUpdate("DROP TABLE IF EXISTS autoIncTutorial");
-    stmt.executeUpdate(
-            "CREATE TABLE autoIncTutorial ("
-            + "priKey INT NOT NULL AUTO_INCREMENT, "
-            + "dataField VARCHAR(64), PRIMARY KEY (priKey))");
-
-    //
-    // Example of retrieving an AUTO INCREMENT key
-    // from an updatable result set
-    //
-
-    rs = stmt.executeQuery("SELECT priKey, dataField "
-       + "FROM autoIncTutorial");
-
-    rs.moveToInsertRow();
-
-    rs.updateString("dataField", "AUTO INCREMENT here?");
-    rs.insertRow();
-
-    //
-    // the driver adds rows at the end
-    //
-
-    rs.last();
-
-    //
-    // We should now be on the row we just inserted
-    //
-
-    int autoIncKeyFromRS = rs.getInt("priKey");
-
-    rs.close();
-
-    rs = null;
-
-    System.out.println("Key returned for inserted row: "
-        + autoIncKeyFromRS);
-
-} finally {
-
-    if (rs != null) {
-        try {
-            rs.close();
-        } catch (SQLException ex) {
-            // ignore
-        }
-    }
-
-    if (stmt != null) {
-        try {
-            stmt.close();
-        } catch (SQLException ex) {
-            // ignore
-        }
-    }
-}
-
-
-   </programlisting>
-
-        </example>
-
-        When you run the preceding example code, you should get the
-        following output: Key returned from
-        <function>getGeneratedKeys()</function>: 1 Key returned from
-        <literal>SELECT LAST_INSERT_ID()</literal>: 1 Key returned for
-        inserted row: 2 You should be aware, that at times, it can be
-        tricky to use the <literal>SELECT LAST_INSERT_ID()</literal>
-        query, as that function's value is scoped to a connection. So,
-        if some other query happens on the same connection, the value
-        will be overwritten. On the other hand, the
-        <function>getGeneratedKeys()</function> method is scoped by the
-        <classname>Statement</classname> instance, so it can be used
-        even if other queries happen on the same connection, but not on
-        the same <classname>Statement</classname> instance.
-      </para>
-
-    </section>
-
-<!--
-        <section id="cj-retrieve-multiresults">
-          <title>Retrieving Multiple <literal>ResultSets</literal> from a <literal>Statement</literal> or <literal>CallableStatement</literal></title>
-
-          <para />
-        </section>
--->
-
-<!--
-        <section id="cj-using-result-set-metadata">
-          <title>Using <literal>ResultSetMetaData</literal> to Retrieve Information about a <literal>ResultSet</literal></title>
-
-          <para />
-        </section>
--->
-
-<!--
-        <section id="cj-using-database-metadata">
-          <title>Using <literal>DatabaseMetaData</literal> to Retrieve Information about a Database</title>
-
-          <para />
-        </section>
--->
-
-<!--
-        <section id="cj-working-with-lobs">
-          <title>Working with <literal>BLOB</literal> and <literal>CLOB</literal> Values</title>
-
-          <para />
-        </section>
--->
-
-  </section>
-
-  <section id="cj-installing">
-
-    <title>Installing Connector/J</title>
-
-    <para>
-      Use the following instructions to install Connector/J
-    </para>
-
-    <section id="cj-system-requirements">
-
-      <title>Required Software Versions</title>
-
-      <para></para>
-
-      <section id="cj-supported-java-versions">
-
-        <title>Java Versions Supported</title>
-
-        <para>
-          MySQL Connector/J supports Java-2 JVMs, including JDK-1.2.x,
-          JDK-1.3.x, JDK-1.4.x and JDK-1.5.x, and requires JDK-1.4.x or
-          newer to compile (but not run). MySQL Connector/J does not
-          support JDK-1.1.x or JDK-1.0.x
-        </para>
-
-        <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 (<option>-Xverify:none</option>), as
-          the class verifier will try to load the class definition for
-          <classname>java.sql.Savepoint</classname> even though it is
-          not accessed by the driver unless you actually use savepoint
-          functionality.
-        </para>
-
-        <para>
-          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 <classname>java.util.LinkedHashMap</classname> which was
-          first available in JDK-1.4.0.
-        </para>
-
-        <remark>
-          MARKUP DONE TO HERE
-        </remark>
-
-      </section>
-
-      <section id="cj-supported-mysql-versions">
-
-        <title>MySQL Server Version Guidelines</title>
-
-        <para>
-          MySQL Connector/J supports all known MySQL server versions.
-          Some features (foreign keys, updatable result sets) require
-          more recent versions of MySQL to operate.
-        </para>
-
-        <para>
-          When connecting to MySQL server version 4.1 or newer, it is
-          best to use MySQL Connector/J version 3.1, as it has full
-          support for features in the newer versions of the server,
-          including Unicode characters, views, stored procedures and
-          server-side prepared statements.
-        </para>
-
-        <para>
-          Although Connector/J version 3.0 will connect to MySQL server,
-          version 4.1 or newer, and implements Unicode characters and
-          the new authorization mechanism, Connector/J 3.0 will not be
-          updated to support new features in current and future server
-          versions.
-        </para>
-
-      </section>
-
-      <section id="cj-classpath">
-
-        <title>Installing the Driver and Configuring the <literal>CLASSPATH</literal></title>
-
-        <para>
-          MySQL Connector/J is distributed as a .zip or .tar.gz archive
-          containing the sources, the class files a class-file only
-          <quote>binary</quote> .jar archive named
-          "<filename>mysql-connector-java-[version]-bin.jar</filename>",
-          and starting with Connector/J 3.1.8 a <quote>debug</quote>
-          build of the driver in a file named
-          "<filename>mysql-connector-java-[version]-bin-g.jar</filename>".
-        </para>
-
-        <para>
-          Starting with Connector/J 3.1.9, we don't ship the .class
-          files <quote>unbundled,</quote> they are only available in the
-          JAR archives that ship with the driver.
-        </para>
-
-        <para>
-          You should not use the <quote>debug</quote> build of the
-          driver unless instructed to do so when reporting a problem or
-          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
-          <filename>src/lib/aspectjrt.jar</filename> file that comes
-          with the Connector/J distribution.
-        </para>
-
-        <para>
-          You will need to use the appropriate graphical or command-line
-          utility to un-archive the distribution (for example, WinZip
-          for the .zip archive, and <command>tar</command> 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.
-        </para>
-
-        <para>
-          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
-        </para>
-
-        <para>
-          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.
-        </para>
-
-        <example>
-
-          <title>Setting the CLASSPATH Under UNIX</title>
-
-          <para>
-            The following command works for 'csh' under UNIX:
-          </para>
-
-          <screen>$ setenv CLASSPATH /path/to/mysql-connector-java-[version]-bin.jar:$CLASSPATH</screen>
-
-        </example>
-
-        <para>
-          The above command can be added to the appropriate startup file
-          for the login shell to make MySQL Connector/J available to all
-          Java applications.
-        </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 third-party class libraries, as most application
-          servers ignore the CLASSPATH environment variable. For
-          configuration examples for some J2EE application servers, see
-          <xref linkend="cj-j2ee"/>. However, the authoritative source
-          for JDBC connection pool configuration information for your
-          particular application server is the documentation for that
-          application server.
-        </para>
-
-        <para>
-          If you are developing servlets or JSPs, and your application
-          server is J2EE-compliant, you can put the driver's .jar file
-          in the WEB-INF/lib subdirectory of your webapp, as this is a
-          standard location for third party class libraries in J2EE web
-          applications.
-        </para>
-
-        <para>
-          You can also use the MysqlDataSource or
-          MysqlConnectionPoolDataSource classes in the
-          com.mysql.jdbc.jdbc2.optional package, if your J2EE
-          application server supports or requires them. Starting with
-          Connector/J 5.0.0, the javax.sql.XADataSource interface is
-          implemented via the
-          com.mysql.jdbc.jdbc2.optional.MysqlXADataSource class, which
-          supports XA distributed transactions when used in combination
-          with MySQL server version 5.0.
-        </para>
-
-        <para>
-          The various MysqlDataSource classes support the following
-          parameters (through standard "set" mutators):
-        </para>
-
-        <itemizedlist>
-
-          <listitem>
-            <para>
-              user
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              password
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              serverName (see the previous section about fail-over
-              hosts)
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              databaseName
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              port
-            </para>
-          </listitem>
-
-        </itemizedlist>
-
-      </section>
-
-    </section>
-
-    <section id="cj-upgrading">
-
       <title>Upgrading from an Older Version</title>
 
       <para>

@@ -1143,7 +394,7 @@
         be aware of.
       </para>
 
-      <section id="cj-upgrading-3-0-to-3-1">
+      <section id="connector-j-installing-upgrading-3-0-to-3-1">
 
         <title>Upgrading from MySQL Connector/J 3.0 to 3.1</title>
 

@@ -1161,32 +412,34 @@
 
           <listitem>
             <para>
-              Unicode Character Sets &mdash; See the next section, as
-              well as <xref linkend="charset"/>, for information on this
-              new feature of MySQL. If you have something misconfigured,
-              it will usually show up as an error with a message similar
-              to <literal>Illegal mix of collations</literal>.
+              <emphasis role="bold">Unicode Character Sets</emphasis>
+              &mdash; See the next section, as well as
+              <xref linkend="charset"/>, for information on this new
+              feature of MySQL. If you have something misconfigured, it
+              will usually show up as an error with a message similar to
+              <literal>Illegal mix of collations</literal>.
             </para>
           </listitem>
 
           <listitem>
             <para>
-              <emphasis>Server-side Prepared Statements</emphasis>
-              &mdash; Connector/J 3.1 will automatically detect and use
-              server-side prepared statements when they are available
-              (MySQL server version 4.1.0 and newer).
+              <emphasis role="bold">Server-side Prepared
+              Statements</emphasis> &mdash; Connector/J 3.1 will
+              automatically detect and use server-side prepared
+              statements when they are available (MySQL server version
+              4.1.0 and newer).
             </para>
 
             <para>
               Starting with version 3.1.7, the driver scans SQL you are
               preparing via all variants of
-              <methodname>Connection.prepareStatement()</methodname> to
+              <literal>Connection.prepareStatement()</literal> to
               determine if it is a supported type of statement to
               prepare on the server side, and if it is not supported by
               the server, it instead prepares it as a client-side
               emulated prepared statement. You can disable this feature
               by passing
-              <property>'emulateUnsupportedPstmts=false'</property> in
+              <property>emulateUnsupportedPstmts=false</property> in
               your JDBC URL.
             </para>
 

@@ -1195,73 +448,95 @@
               prepared statements, you can revert to the older
               client-side emulated prepared statement code that is still
               presently used for MySQL servers older than 4.1.0 with the
-              following connection property:
+              connection property
+              <property>useServerPrepStmts=false</property>
             </para>
-
-            <para>
-              <computeroutput>useServerPrepStmts=false</computeroutput>
-            </para>
           </listitem>
 
           <listitem>
             <para>
-              Datetimes with all-zero components ('0000-00-00 ...')
-              &mdash; These values can not be represented reliably in
-              Java. Connector/J 3.0.x always converted them to NULL when
-              being read from a ResultSet.
+              <emphasis role="bold">Datetimes</emphasis> with all-zero
+              components (<literal>0000-00-00 ...</literal>) &mdash;
+              These values can not be represented reliably in Java.
+              Connector/J 3.0.x always converted them to NULL when being
+              read from a ResultSet.
             </para>
 
             <para>
               Connector/J 3.1 throws an exception by default when these
               values are encountered as this is the most correct
               behavior according to the JDBC and SQL standards. This
-              behavior can be modified using the '
-              <property>zeroDateTimeBehavior</property> ' configuration
-              property. The allowable values are: 'exception' (the
-              default), which throws an SQLException with an SQLState of
-              'S1009', 'convertToNull', which returns NULL instead of
-              the date, and 'round', which rounds the date to the
-              nearest closest value which is '0001-01-01'.
+              behavior can be modified using the
+              <property>zeroDateTimeBehavior</property> configuration
+              property. The allowable values are:
             </para>
 
+            <itemizedlist>
+
+              <listitem>
+                <para>
+                  <literal>exception</literal> (the default), which
+                  throws an SQLException with an SQLState of
+                  <literal>S1009</literal>.
+                </para>
+              </listitem>
+
+              <listitem>
+                <para>
+                  <literal>convertToNull</literal>, which returns
+                  <literal>NULL</literal> instead of the date.
+                </para>
+              </listitem>
+
+              <listitem>
+                <para>
+                  <literal>round</literal>, which rounds the date to the
+                  nearest closest value which is
+                  <literal>0001-01-01</literal>.
+                </para>
+              </listitem>
+
+            </itemizedlist>
+
             <para>
-              Starting with Connector/J 3.1.7, ResultSet.getString() can
-              be decoupled from this behavior via '
-              <property>noDatetimeStringSync=true</property> ' (the
-              default value is 'false') so that you can get 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
+              Starting with Connector/J 3.1.7,
+              <literal>ResultSet.getString()</literal> can be decoupled
+              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
+              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
               <property>useTimezone</property> at the same time.
             </para>
           </listitem>
 
           <listitem>
             <para>
-              New SQLState Codes &mdash; Connector/J 3.1 uses SQL:1999
-              SQLState codes returned by the MySQL server (if
-              supported), which are different from the
-              <quote>legacy</quote> X/Open state codes that Connector/J
-              3.0 uses. If connected to a MySQL server older than
-              MySQL-4.1.0 (the oldest version to return SQLStates as
-              part of the error code), the driver will use a built-in
+              <emphasis role="bold">New SQLState Codes</emphasis>
+              &mdash; Connector/J 3.1 uses SQL:1999 SQLState codes
+              returned by the MySQL server (if supported), which are
+              different from the legacy X/Open state codes that
+              Connector/J 3.0 uses. If connected to a MySQL server older
+              than MySQL-4.1.0 (the oldest version to return SQLStates
+              as part of the error code), the driver will use a built-in
               mapping. You can revert to the old mapping by using the
-              following configuration property:
+              configuration property
+              <property>useSqlStateCodes=false</property>.
             </para>
-
-            <para>
-              <computeroutput>useSqlStateCodes=false</computeroutput>
-            </para>
           </listitem>
 
           <listitem>
             <para>
-              Calling ResultSet.getString() on a BLOB column will now
-              return the address of the byte[] array that represents it,
-              instead of a String representation of the BLOB. BLOBs have
-              no character set, so they can't be converted to
-              java.lang.Strings without data loss or corruption.
+              <emphasis
+                role="bold"><literal>ResultSet.getString()</literal></emphasis>
+              &mdash; Calling <literal>ResultSet.getString()</literal>
+              on a BLOB column will now return the address of the byte[]
+              array that represents it, instead of a String
+              representation of the BLOB. BLOBs have no character set,
+              so they can't be converted to java.lang.Strings without
+              data loss or corruption.
             </para>
 
             <para>

@@ -1273,27 +548,28 @@
 
           <listitem>
             <para>
-              Starting with Connector/J 3.1.8 a <quote>debug</quote>
-              build of the driver in a file named
-              "<filename>mysql-connector-java-[version]-bin-g.jar</filename>"
-              is shipped alongside the normal <quote>binary</quote> jar
-              file that is named
-              "<filename>mysql-connector-java-[version]-bin.jar</filename>".
+              <emphasis role="bold">Debug builds</emphasis> &mdash;
+              Starting with Connector/J 3.1.8 a debug build of the
+              driver in a file named
+              <filename>mysql-connector-java-<replaceable>[version]</replaceable>-bin-g.jar</filename>
+              is shipped alongside the normal binary jar file that is
+              named
+              <filename>mysql-connector-java-<replaceable>[version]</replaceable>-bin.jar</filename>.
             </para>
 
             <para>
               Starting with Connector/J 3.1.9, we don't ship the .class
-              files <quote>unbundled,</quote> they are only available in
-              the JAR archives that ship with the driver.
+              files unbundled, they are only available in the JAR
+              archives that ship with the driver.
             </para>
 
             <para>
-              You should not use the <quote>debug</quote> build of the
-              driver unless instructed to do so when reporting a problem
-              or 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
+              You should not use the debug build of the driver unless
+              instructed to do so when reporting a problem or 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
               <filename>src/lib/aspectjrt.jar</filename> file that comes
               with the Connector/J distribution.
             </para>

@@ -1303,7 +579,7 @@
 
       </section>
 
-      <section id="cj-jdbc-upgrading-issues">
+      <section id="connector-j-installing-upgrading-issues">
 
         <title>JDBC-Specific Issues When Upgrading to MySQL Server 4.1 or Newer</title>
 

@@ -1356,19 +632,23 @@
 
     </section>
 
-    <section id="cj-installing-source">
+    <section id="connector-j-installing-source">
 
       <title>Installing from the Development Source Tree</title>
 
-      <caution>
+      <formalpara>
+
+        <title>Caution</title>
+
         <para>
           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.
         </para>
-      </caution>
 
+      </formalpara>
+
       <para>
         To install MySQL Connector/J from the development source tree,
         make sure that you have the following prerequisites:

@@ -1387,7 +667,8 @@
         <listitem>
           <para>
             Apache Ant version 1.6 or newer (available from
-            <ulink url="http://ant.apache.org/"/>).
+            <ulink
+              url="http://ant.apache.org/"/>).
           </para>
         </listitem>
 

@@ -1429,7 +710,8 @@
             numbers):
           </para>
 
-<programlisting>shell&gt; <userinput>svn co http://svn.mysql.com/svnpublic/connector-j/branches/branch_<replaceable>[major]</replaceable>_<replaceable>[minor]</replaceable>/connector-j</userinput></programlisting>
+<programlisting>shell&gt; <userinput>svn co &raquo;
+http://svn.mysql.com/svnpublic/connector-j/branches/branch_<replaceable>[major]</replaceable>_<replaceable>[minor]</replaceable>/connector-j</userinput></programlisting>
 
           <para>
             This creates a <filename>connector-j</filename> subdirectory

@@ -1481,7 +763,8 @@
             Install the newly created JDBC driver as you would a binary
             <filename>.jar</filename> file that you download from MySQL
             by following the instructions in
-            <xref linkend="cj-classpath"/>.
+            <xref
+              linkend="connector-j-installing-classpath"/>.
           </para>
         </listitem>
 

@@ -1491,87 +774,193 @@
 
   </section>
 
-  <section id="cj-jdbc-reference">
+  <section id="connector-j-examples">
 
-    <title>JDBC Reference</title>
+    <title>Connector/J Examples</title>
 
-    <para></para>
+    <para>
+      Examples of using Connector/J are located throughout this
+      document, this section provides a summary and links to these
+      examples.
+    </para>
 
-    <section id="cj-configuration-properties">
+    <itemizedlist>
 
-      <title>Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J</title>
+      <listitem>
+        <para>
+          <xref linkend="connector-j-examples-connection-drivermanager"/>
+        </para>
+      </listitem>
 
+      <listitem>
+        <para>
+          <xref linkend="connector-j-examples-execute-select"/>
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <xref linkend="connector-j-examples-stored-procedure"/>
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <xref linkend="connector-j-examples-preparecall"/>
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <xref linkend="connector-j-examples-output-param"/>
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <xref linkend="connector-j-examples-callablestatement"/>
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <xref linkend="connector-j-examples-retrieving-results-params"/>
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <xref linkend="connector-j-examples-autoincrement-getgeneratedkeys"/>
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <xref linkend="connector-j-examples-autoincrement-select"/>
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <xref linkend="connector-j-examples-autoincrement-updateable-resultsets"/>
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <xref linkend="connector-j-examples-connectionpool-j2ee"/>
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <xref linkend="connector-j-examples-transaction-retry"/>
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+  </section>
+
+  <section id="connector-j-reference">
+
+    <title>Connector/J (JDBC) Reference</title>
+
+    <para>
+      This section of the manual contains reference material for MySQL
+      Connector/J, some of which is automatically generated during the
+      Connector/J build process.
+    </para>
+
+    <section id="connector-j-reference-configuration-properties">
+
+      <title>Driver/Datasource Class Names, URL Syntax and Configuration Properties
+        for Connector/J</title>
+
       <para>
         The name of the class that implements java.sql.Driver in MySQL
-        Connector/J is 'com.mysql.jdbc.Driver'. The
-        'org.gjt.mm.mysql.Driver' class name is also usable to remain
-        backward-compatible with MM.MySQL. You should use this class
-        name when registering the driver, or when otherwise configuring
-        software to use MySQL Connector/J.
+        Connector/J is <literal>com.mysql.jdbc.Driver</literal>. The
+        <literal>org.gjt.mm.mysql.Driver</literal> class name is also
+        usable to remain backward-compatible with MM.MySQL. You should
+        use this class name when registering the driver, or when
+        otherwise configuring software to use MySQL Connector/J.
       </para>
 
       <para>
         The JDBC URL format for MySQL Connector/J is as follows, with
         items in square brackets ([, ]) being optional:
-
-        <screen>jdbc:mysql://[host][,failoverhost...][:port]/[database][?propertyName1][=propertyValue1][&amp;propertyName2][=propertyValue2]...</screen>
       </para>
 
+<programlisting>jdbc:mysql://[host][,failoverhost...][:port]/[database] &raquo;
+[?propertyName1][=propertyValue1][&amp;propertyName2][=propertyValue2]...</programlisting>
+
       <para>
-        If the hostname is not specified, it defaults to '127.0.0.1'. If
-        the port is not specified, it defaults to '3306', the default
-        port number for MySQL servers.
+        If the hostname is not specified, it defaults to 127.0.0.1. If
+        the port is not specified, it defaults to 3306, the default port
+        number for MySQL servers.
       </para>
 
-      <screen>jdbc:mysql://[host:port],[host:port].../[database][?propertyName1][=propertyValue1][&amp;propertyName2][=propertyValue2]...</screen>
+<programlisting>jdbc:mysql://[host:port],[host:port].../[database] &raquo;
+[?propertyName1][=propertyValue1][&amp;propertyName2][=propertyValue2]...</programlisting>
 
       <para>
         If the database is not specified, the connection will be made
         with no default database. In this case, you will need to either
-        call the <function>setCatalog()</function> method on the
+        call the <literal>setCatalog()</literal> method on the
         Connection instance or fully-specify table names using the
-        database name (i.e. 'SELECT dbname.tablename.colname FROM
-        dbname.tablename...') in your SQL. Not specifying the database
-        to use upon connection is generally only useful when building
-        tools that work with multiple databases, such as GUI database
-        managers.
+        database name (i.e. <literal>SELECT dbname.tablename.colname
+        FROM dbname.tablename...</literal>) in your SQL. Not specifying
+        the database to use upon connection is generally only useful
+        when building tools that work with multiple databases, such as
+        GUI database managers.
       </para>
 
       <para>
         MySQL Connector/J has fail-over support. This allows the driver
-        to fail-over to any number of <quote>slave</quote> hosts and
-        still perform read-only queries. Fail-over only happens when the
-        connection is in an autoCommit(true) state, because fail-over
-        can not happen reliably when a transaction is in progress. Most
-        application servers and connection pools set autoCommit to
-        'true' at the end of every transaction/connection use.
+        to fail-over to any number of slave hosts and still perform
+        read-only queries. Fail-over only happens when the connection is
+        in an <literal>autoCommit(true)</literal> state, because
+        fail-over can not happen reliably when a transaction is in
+        progress. Most application servers and connection pools set
+        <literal>autoCommit</literal> to <literal>true</literal> at the
+        end of every transaction/connection use.
       </para>
 
       <para>
         The fail-over functionality has the following behavior:
       </para>
 
-      <para>
-        If the URL property "autoReconnect" is false: Failover only
-        happens at connection initialization, and failback occurs when
-        the driver determines that the first host has become available
-        again.
-      </para>
+      <itemizedlist>
 
-      <para>
-        If the URL property "autoReconnect" is true: Failover happens
-        when the driver determines that the connection has failed
-        (before <emphasis>every</emphasis> query), and falls back to the
-        first host when it determines that the host has become available
-        again (after queriesBeforeRetryMaster queries have been issued).
-      </para>
+        <listitem>
+          <para>
+            If the URL property <property>autoReconnect</property> is
+            false: Failover only happens at connection initialization,
+            and failback occurs when the driver determines that the
+            first host has become available again.
+          </para>
+        </listitem>
 
+        <listitem>
+          <para>
+            If the URL property <property>autoReconnect</property> is
+            true: Failover happens when the driver determines that the
+            connection has failed (before <emphasis>every</emphasis>
+            query), and falls back to the first host when it determines
+            that the host has become available again (after
+            <literal>queriesBeforeRetryMaster</literal> queries have
+            been issued).
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
       <para>
         In either case, whenever you are connected to a "failed-over"
         server, the connection will be set to read-only state, so
         queries that would modify data will have exceptions thrown (the
-        query will <emphasis>never</emphasis> be processed by the MySQL
-        server).
+        query will <emphasis role="bold">never</emphasis> be processed
+        by the MySQL server).
       </para>
 
       <para>

@@ -1614,26 +1003,33 @@
         <listitem>
           <para>
             As a key/value pair in the java.util.Properties instance
-            passed to DriverManager.getConnection() or Driver.connect()
+            passed to <literal>DriverManager.getConnection()</literal>
+            or <literal>Driver.connect()</literal>
           </para>
         </listitem>
 
         <listitem>
           <para>
             As a JDBC URL parameter in the URL given to
-            java.sql.DriverManager.getConnection(),
-            java.sql.Driver.connect() or the MySQL implementations of
-            javax.sql.DataSource's setURL() method.
+            <literal>java.sql.DriverManager.getConnection()</literal>,
+            <literal>java.sql.Driver.connect()</literal> or the MySQL
+            implementations of the
+            <literal>javax.sql.DataSource</literal>
+            <literal>setURL()</literal> method.
+          </para>
 
-            <note>
-              <para>
-                If the mechanism you use to configure a JDBC URL is
-                XML-based, you will need to use the XML character
-                literal &amp;amp; to separate configuration parameters,
-                as the ampersand is a reserved character for XML.
-              </para>
-            </note>
-          </para>
+          <formalpara>
+
+            <title>Note</title>
+
+            <para>
+              If the mechanism you use to configure a JDBC URL is
+              XML-based, you will need to use the XML character literal
+              &amp;amp; to separate configuration parameters, as the
+              ampersand is a reserved character for XML.
+            </para>
+
+          </formalpara>
         </listitem>
 
       </itemizedlist>

@@ -1641,6 +1037,7 @@
       <para>
         The properties are listed in the following tables.
       </para>
+
 <!-- Generated by the genPropertiesTable target in the build script
 
 Do NOT adjust the content structure in these tables directly in this document.

@@ -1650,1349 +1047,1036 @@
 
  -->
 
-<formalpara>
-   <title>Connection/Authentication</title>
+      <formalpara>
 
-   <para>
-      <informaltable>
-         <tgroup cols="4">
-            <colspec colwidth="30*" colname="cj_propstbl_prop_name" />
+        <title>Connection/Authentication</title>
 
-            <colspec colwidth="50*" colname="cj_propstbl_prop_defn" />
-
-            <colspec colwidth="10*" colname="cj_propstbl_default" />
-
-            <colspec colwidth="10*" colname="cj_propstbl_since_version" />
-
-            <tbody>
-               <row>
-                  <entry>
-                     <emphasis role="bold">Property Name</emphasis>
-                  </entry>
-
-                  <entry>
-                     <emphasis role="bold">Definition</emphasis>
-                  </entry>
-
-                  <entry>
-                     <emphasis role="bold">Default Value</emphasis>
-                  </entry>
-
-                  <entry>
-                     <emphasis role="bold">Since Version</emphasis>
-                  </entry>
-               </row>
-
-               <row>
+        <para>
+          <informaltable>
+            <tgroup cols="4">
+              <colspec colwidth="30*" colname="cj_propstbl_prop_name"/>
+              <colspec colwidth="50*" colname="cj_propstbl_prop_defn"/>
+              <colspec colwidth="10*" colname="cj_propstbl_default"/>
+              <colspec colwidth="10*" colname="cj_propstbl_since_version"/>
+              <tbody>
+                <row>
+                  <entry><emphasis role="bold">Property Name</emphasis></entry>
+                  <entry><emphasis role="bold">Definition</emphasis></entry>
+                  <entry><emphasis role="bold">Default Value</emphasis></entry>
+                  <entry><emphasis role="bold">Since Version</emphasis></entry>
+                </row>
+                <row>
                   <entry>user</entry>
-
                   <entry>The user to connect as</entry>
-
-                  <entry>
-                  </entry>
-
+                  <entry/>
                   <entry>all</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>password</entry>
-
                   <entry>The password to use when connecting</entry>
-
-                  <entry>
-                  </entry>
-
+                  <entry/>
                   <entry>all</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>socketFactory</entry>
-
-                  <entry>The name of the class that the driver should use for creating socket connections to the server. This class must implement the interface 'com.mysql.jdbc.SocketFactory' and have public no-args constructor.</entry>
-
+                  <entry>The name of the class that the driver should use for creating socket
+                    connections to the server. This class must implement
+                    the interface
+                    <classname>com.mysql.jdbc.SocketFactory</classname>
+                    and have public no-args constructor.</entry>
                   <entry>com.mysql.jdbc.StandardSocketFactory</entry>
-
                   <entry>3.0.3</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>connectTimeout</entry>
-
-                  <entry>Timeout for socket connect (in milliseconds), with 0 being no timeout. Only works on JDK-1.4 or newer. Defaults to '0'.</entry>
-
+                  <entry>Timeout for socket connect (in milliseconds), with 0 being no timeout.
+                    Only works on JDK-1.4 or newer. Defaults to 0.</entry>
                   <entry>0</entry>
-
                   <entry>3.0.1</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>socketTimeout</entry>
-
                   <entry>Timeout on network socket operations (0, the default means no timeout).</entry>
-
                   <entry>0</entry>
-
                   <entry>3.0.1</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>useConfigs</entry>
-
-                  <entry>Load the comma-delimited list of configuration properties before parsing the URL or applying user-specified properties. These configurations are explained in the 'Configurations' of the documentation.</entry>
-
-                  <entry>
-                  </entry>
-
+                  <entry>Load the comma-delimited list of configuration properties before parsing
+                    the URL or applying user-specified properties. See
+                    <xref linkend="connector-j-reference-configuration-properties"/></entry>
+                  <entry/>
                   <entry>3.1.5</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>interactiveClient</entry>
-
-                  <entry>Set the CLIENT_INTERACTIVE flag, which tells MySQL to timeout connections based on INTERACTIVE_TIMEOUT instead of WAIT_TIMEOUT</entry>
-
+                  <entry>Set the CLIENT_INTERACTIVE flag, which tells MySQL to timeout
+                    connections based on INTERACTIVE_TIMEOUT instead of
+                    WAIT_TIMEOUT</entry>
                   <entry>false</entry>
-
                   <entry>3.1.0</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>propertiesTransform</entry>
-
-                  <entry>An implementation of com.mysql.jdbc.ConnectionPropertiesTransform that the driver will use to modify URL properties passed to the driver before attempting a connection</entry>
-
-                  <entry>
-                  </entry>
-
+                  <entry>An implementation of
+                    <classname>com.mysql.jdbc.ConnectionPropertiesTransform</classname>
+                    that the driver will use to modify URL properties
+                    passed to the driver before attempting a connection</entry>
+                  <entry/>
                   <entry>3.1.4</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>useCompression</entry>
-
-                  <entry>Use zlib compression when communicating with the server (true/false)? Defaults to 'false'.</entry>
-
+                  <entry>Use zlib compression when communicating with the server (true/false)?
+                    Defaults to <literal>false</literal>.</entry>
                   <entry>false</entry>
-
                   <entry>3.0.17</entry>
-               </row>
-            </tbody>
-         </tgroup>
-      </informaltable>
-   </para>
-</formalpara>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
 
-<formalpara>
-   <title>High Availability and Clustering</title>
+      </formalpara>
 
-   <para>
-      <informaltable>
-         <tgroup cols="4">
-            <colspec colwidth="30*" colname="cj_propstbl_prop_name" />
+      <formalpara>
 
-            <colspec colwidth="50*" colname="cj_propstbl_prop_defn" />
+        <title>High Availability and Clustering</title>
 
-            <colspec colwidth="10*" colname="cj_propstbl_default" />
-
-            <colspec colwidth="10*" colname="cj_propstbl_since_version" />
-
-            <tbody>
-               <row>
-                  <entry>
-                     <emphasis role="bold">Property Name</emphasis>
-                  </entry>
-
-                  <entry>
-                     <emphasis role="bold">Definition</emphasis>
-                  </entry>
-
-                  <entry>
-                     <emphasis role="bold">Default Value</emphasis>
-                  </entry>
-
-                  <entry>
-                     <emphasis role="bold">Since Version</emphasis>
-                  </entry>
-               </row>
-
-               <row>
+        <para>
+          <informaltable>
+            <tgroup cols="4">
+              <colspec colwidth="30*" colname="cj_propstbl_prop_name"/>
+              <colspec colwidth="50*" colname="cj_propstbl_prop_defn"/>
+              <colspec colwidth="10*" colname="cj_propstbl_default"/>
+              <colspec colwidth="10*" colname="cj_propstbl_since_version"/>
+              <tbody>
+                <row>
+                  <entry><emphasis role="bold">Property Name</emphasis></entry>
+                  <entry><emphasis role="bold">Definition</emphasis></entry>
+                  <entry><emphasis role="bold">Default Value</emphasis></entry>
+                  <entry><emphasis role="bold">Since Version</emphasis></entry>
+                </row>
+                <row>
                   <entry>autoReconnect</entry>
-
-                  <entry>Should the driver try to re-establish stale and/or dead connections? If enabled the driver will throw an exception for a queries issued on a stale or dead connection, which belong to the current transaction, but will attempt reconnect before the next query issued on the connection in a new transaction. The use of this feature is not recommended, because it has side effects related to session state and data consistency when applications don'thandle SQLExceptions properly, and is only designed to be used when you are unable to configure your application to handle SQLExceptions resulting from dead andstale connections properly. Alternatively, investigate setting the MySQL server variable "wait_timeout"to some high value rather than the default of 8 hours.</entry>
-
+                  <entry>Should the driver try to re-establish stale and/or dead connections? If
+                    enabled the driver will throw an exception for a
+                    queries issued on a stale or dead connection, which
+                    belong to the current transaction, but will attempt
+                    reconnect before the next query issued on the
+                    connection in a new transaction. The use of this
+                    feature is not recommended, because it has side
+                    effects related to session state and data
+                    consistency when applications don'thandle
+                    SQLExceptions properly, and is only designed to be
+                    used when you are unable to configure your
+                    application to handle SQLExceptions resulting from
+                    dead andstale connections properly. Alternatively,
+                    investigate setting the MySQL server variable
+                    "wait_timeout"to some high value rather than the
+                    default of 8 hours.</entry>
                   <entry>false</entry>
-
                   <entry>1.1</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>autoReconnectForPools</entry>
-
-                  <entry>Use a reconnection strategy appropriate for connection pools (defaults to 'false')</entry>
-
+                  <entry>Use a reconnection strategy appropriate for connection pools (defaults
+                    to 'false')</entry>
                   <entry>false</entry>
-
                   <entry>3.1.3</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>failOverReadOnly</entry>
-
-                  <entry>When failing over in autoReconnect mode, should the connection be set to 'read-only'?</entry>
-
+                  <entry>When failing over in autoReconnect mode, should the connection be set to
+                    'read-only'?</entry>
                   <entry>true</entry>
-
                   <entry>3.0.12</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>reconnectAtTxEnd</entry>
-
-                  <entry>If autoReconnect is set to true, should the driver attempt reconnectionsat the end of every transaction?</entry>
-
+                  <entry>If autoReconnect is set to true, should the driver attempt
+                    reconnectionsat the end of every transaction?</entry>
                   <entry>false</entry>
-
                   <entry>3.0.10</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>roundRobinLoadBalance</entry>
-
-                  <entry>When autoReconnect is enabled, and failoverReadonly is false, should we pick hosts to connect to on a round-robin basis?</entry>
-
+                  <entry>When autoReconnect is enabled, and failoverReadonly is false, should we
+                    pick hosts to connect to on a round-robin basis?</entry>
                   <entry>false</entry>
-
                   <entry>3.1.2</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>queriesBeforeRetryMaster</entry>
-
-                  <entry>Number of queries to issue before falling back to master when failed over (when using multi-host failover). Whichever condition is met first, 'queriesBeforeRetryMaster' or 'secondsBeforeRetryMaster' will cause an attempt to be made to reconnect to the master. Defaults to 50.</entry>
-
+                  <entry>Number of queries to issue before falling back to master when failed
+                    over (when using multi-host failover). Whichever
+                    condition is met first, 'queriesBeforeRetryMaster'
+                    or 'secondsBeforeRetryMaster' will cause an attempt
+                    to be made to reconnect to the master. Defaults to
+                    50.</entry>
                   <entry>50</entry>
-
                   <entry>3.0.2</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>secondsBeforeRetryMaster</entry>
-
-                  <entry>How long should the driver wait, when failed over, before attempting to reconnect to the master server? Whichever condition is met first, 'queriesBeforeRetryMaster' or 'secondsBeforeRetryMaster' will cause an attempt to be made to reconnect to the master. Time in seconds, defaults to 30</entry>
-
+                  <entry>How long should the driver wait, when failed over, before attempting to
+                    reconnect to the master server? Whichever condition
+                    is met first, 'queriesBeforeRetryMaster' or
+                    'secondsBeforeRetryMaster' will cause an attempt to
+                    be made to reconnect to the master. Time in seconds,
+                    defaults to 30</entry>
                   <entry>30</entry>
-
                   <entry>3.0.2</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>enableDeprecatedAutoreconnect</entry>
-
-                  <entry>Auto-reconnect functionality is deprecated starting with version 3.2, and will be removed in version 3.3. Set this property to 'true' to disable the check for the feature being configured.</entry>
-
+                  <entry>Auto-reconnect functionality is deprecated starting with version 3.2,
+                    and will be removed in version 3.3. Set this
+                    property to 'true' to disable the check for the
+                    feature being configured.</entry>
                   <entry>false</entry>
-
                   <entry>3.2.1</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>resourceId</entry>
-
-                  <entry>A globally unique name that identifies the resource that this datasource or connection is connected to, used for XAResource.isSameRM() when the driver can't determine this value based on hostnames used in the URL</entry>
-
-                  <entry>
-                  </entry>
-
+                  <entry>A globally unique name that identifies the resource that this datasource
+                    or connection is connected to, used for
+                    <literal>XAResource.isSameRM()</literal> when the
+                    driver can't determine this value based on hostnames
+                    used in the URL</entry>
+                  <entry/>
                   <entry>5.0.1</entry>
-               </row>
-            </tbody>
-         </tgroup>
-      </informaltable>
-   </para>
-</formalpara>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
 
-<formalpara>
-   <title>Security</title>
+      </formalpara>
 
-   <para>
-      <informaltable>
-         <tgroup cols="4">
-            <colspec colwidth="30*" colname="cj_propstbl_prop_name" />
+      <formalpara>
 
-            <colspec colwidth="50*" colname="cj_propstbl_prop_defn" />
+        <title>Security</title>
 
-            <colspec colwidth="10*" colname="cj_propstbl_default" />
-
-            <colspec colwidth="10*" colname="cj_propstbl_since_version" />
-
-            <tbody>
-               <row>
-                  <entry>
-                     <emphasis role="bold">Property Name</emphasis>
-                  </entry>
-
-                  <entry>
-                     <emphasis role="bold">Definition</emphasis>
-                  </entry>
-
-                  <entry>
-                     <emphasis role="bold">Default Value</emphasis>
-                  </entry>
-
-                  <entry>
-                     <emphasis role="bold">Since Version</emphasis>
-                  </entry>
-               </row>
-
-               <row>
+        <para>
+          <informaltable>
+            <tgroup cols="4">
+              <colspec colwidth="30*" colname="cj_propstbl_prop_name"/>
+              <colspec colwidth="50*" colname="cj_propstbl_prop_defn"/>
+              <colspec colwidth="10*" colname="cj_propstbl_default"/>
+              <colspec colwidth="10*" colname="cj_propstbl_since_version"/>
+              <tbody>
+                <row>
+                  <entry><emphasis role="bold">Property Name</emphasis></entry>
+                  <entry><emphasis role="bold">Definition</emphasis></entry>
+                  <entry><emphasis role="bold">Default Value</emphasis></entry>
+                  <entry><emphasis role="bold">Since Version</emphasis></entry>
+                </row>
+                <row>
                   <entry>allowMultiQueries</entry>
-
-                  <entry>Allow the use of ';' to delimit multiple queries during one statement (true/false, defaults to 'false'</entry>
-
+                  <entry>Allow the use of ';' to delimit multiple queries during one statement
+                    (true/false, defaults to 'false'</entry>
                   <entry>false</entry>
-
                   <entry>3.1.1</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>useSSL</entry>
-
-                  <entry>Use SSL when communicating with the server (true/false), defaults to 'false'</entry>
-
+                  <entry>Use SSL when communicating with the server (true/false), defaults to
+                    'false'</entry>
                   <entry>false</entry>
-
                   <entry>3.0.2</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>requireSSL</entry>
-
                   <entry>Require SSL connection if useSSL=true? (defaults to 'false').</entry>
-
                   <entry>false</entry>
-
                   <entry>3.1.0</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>allowUrlInLocalInfile</entry>
-
                   <entry>Should the driver allow URLs in 'LOAD DATA LOCAL INFILE' statements?</entry>
-
                   <entry>false</entry>
-
                   <entry>3.1.4</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>paranoid</entry>
-
-                  <entry>Take measures to prevent exposure sensitive information in error messages and clear data structures holding sensitive data when possible? (defaults to 'false')</entry>
-
+                  <entry>Take measures to prevent exposure sensitive information in error
+                    messages and clear data structures holding sensitive
+                    data when possible? (defaults to 'false')</entry>
                   <entry>false</entry>
-
                   <entry>3.0.1</entry>
-               </row>
-            </tbody>
-         </tgroup>
-      </informaltable>
-   </para>
-</formalpara>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
 
-<formalpara>
-   <title>Performance Extensions</title>
+      </formalpara>
 
-   <para>
-      <informaltable>
-         <tgroup cols="4">
-            <colspec colwidth="30*" colname="cj_propstbl_prop_name" />
+      <formalpara>
 
-            <colspec colwidth="50*" colname="cj_propstbl_prop_defn" />
+        <title>Performance Extensions</title>
 
-            <colspec colwidth="10*" colname="cj_propstbl_default" />
-
-            <colspec colwidth="10*" colname="cj_propstbl_since_version" />
-
-            <tbody>
-               <row>
-                  <entry>
-                     <emphasis role="bold">Property Name</emphasis>
-                  </entry>
-
-                  <entry>
-                     <emphasis role="bold">Definition</emphasis>
-                  </entry>
-
-                  <entry>
-                     <emphasis role="bold">Default Value</emphasis>
-                  </entry>
-
-                  <entry>
-                     <emphasis role="bold">Since Version</emphasis>
-                  </entry>
-               </row>
-
-               <row>
+        <para>
+          <informaltable>
+            <tgroup cols="4">
+              <colspec colwidth="30*" colname="cj_propstbl_prop_name"/>
+              <colspec colwidth="50*" colname="cj_propstbl_prop_defn"/>
+              <colspec colwidth="10*" colname="cj_propstbl_default"/>
+              <colspec colwidth="10*" colname="cj_propstbl_since_version"/>
+              <tbody>
+                <row>
+                  <entry><emphasis role="bold">Property Name</emphasis></entry>
+                  <entry><emphasis role="bold">Definition</emphasis></entry>
+                  <entry><emphasis role="bold">Default Value</emphasis></entry>
+                  <entry><emphasis role="bold">Since Version</emphasis></entry>
+                </row>
+                <row>
                   <entry>metadataCacheSize</entry>
-
-                  <entry>The number of queries to cacheResultSetMetadata for if cacheResultSetMetaData is set to 'true' (default 50)</entry>
-
+                  <entry>The number of queries to cacheResultSetMetadata for if
+                    cacheResultSetMetaData is set to 'true' (default 50)</entry>
                   <entry>50</entry>
-
                   <entry>3.1.1</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>prepStmtCacheSize</entry>
-
-                  <entry>If prepared statement caching is enabled, how many prepared statements should be cached?</entry>
-
+                  <entry>If prepared statement caching is enabled, how many prepared statements
+                    should be cached?</entry>
                   <entry>25</entry>
-
                   <entry>3.0.10</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>prepStmtCacheSqlLimit</entry>
-
-                  <entry>If prepared statement caching is enabled, what's the largest SQL the driver will cache the parsing for?</entry>
-
+                  <entry>If prepared statement caching is enabled, what's the largest SQL the
+                    driver will cache the parsing for?</entry>
                   <entry>256</entry>
-
                   <entry>3.0.10</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>useCursorFetch</entry>
-
-                  <entry>If connected to MySQL &gt; 5.0.2, and setFetchSize() &gt; 0 on a statement, should that statement use cursor-based fetching to retrieve rows?</entry>
-
+                  <entry>If connected to MySQL &gt; 5.0.2, and <literal>setFetchSize()</literal>
+                    &gt; 0 on a statement, should that statement use
+                    cursor-based fetching to retrieve rows?</entry>
                   <entry>false</entry>
-
                   <entry>5.0.0</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>blobSendChunkSize</entry>
-
                   <entry>Chunk to use when sending BLOB/CLOBs via ServerPreparedStatements</entry>
-
                   <entry>1048576</entry>
-
                   <entry>3.1.9</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>cacheCallableStmts</entry>
-
                   <entry>Should the driver cache the parsing stage of CallableStatements</entry>
-
                   <entry>false</entry>
-
                   <entry>3.1.2</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>cachePrepStmts</entry>
-
-                  <entry>Should the driver cache the parsing stage of PreparedStatements of client-side prepared statements, the "check" for suitability of server-side prepared and server-side prepared statements themselves?</entry>
-
+                  <entry>Should the driver cache the parsing stage of PreparedStatements of
+                    client-side prepared statements, the check for
+                    suitability of server-side prepared and server-side
+                    prepared statements themselves?</entry>
                   <entry>false</entry>
-
                   <entry>3.0.10</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>cacheResultSetMetadata</entry>
-
-                  <entry>Should the driver cache ResultSetMetaData for Statements and PreparedStatements? (Req. JDK-1.4+, true/false, default 'false')</entry>
-
+                  <entry>Should the driver cache ResultSetMetaData for Statements and
+                    PreparedStatements? (Req. JDK-1.4+, true/false,
+                    default 'false')</entry>
                   <entry>false</entry>
-
                   <entry>3.1.1</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>cacheServerConfiguration</entry>
-
-                  <entry>Should the driver cache the results of 'SHOW VARIABLES' and 'SHOW COLLATION' on a per-URL basis?</entry>
-
+                  <entry>Should the driver cache the results of <literal>SHOW VARIABLES</literal>
+                    and <literal>SHOW COLLATION</literal> on a per-URL
+                    basis?</entry>
                   <entry>false</entry>
-
                   <entry>3.1.5</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>defaultFetchSize</entry>
-
-                  <entry>The driver will call setFetchSize(n) with this value on all newly-created Statements</entry>
-
+                  <entry>The driver will call setFetchSize(n) with this value on all
+                    newly-created Statements</entry>
                   <entry>0</entry>
-
                   <entry>3.1.9</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>dontTrackOpenResources</entry>
-
-                  <entry>The JDBC specification requires the driver to automatically track and close resources, however if your application doesn't do a good job of explicitly calling close() on statements or result sets, this can cause memory leakage. Setting this property to true relaxes this constraint, and can be more memory efficient for some applications.</entry>
-
+                  <entry>The JDBC specification requires the driver to automatically track and
+                    close resources, however if your application doesn't
+                    do a good job of explicitly calling
+                    <literal>close()</literal> on statements or result
+                    sets, this can cause memory leakage. Setting this
+                    property to true relaxes this constraint, and can be
+                    more memory efficient for some applications.</entry>
                   <entry>false</entry>
-
                   <entry>3.1.7</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>dynamicCalendars</entry>
-
-                  <entry>Should the driver retrieve the default calendar when required, or cache it per connection/session?</entry>
-
+                  <entry>Should the driver retrieve the default calendar when required, or cache
+                    it per connection/session?</entry>
                   <entry>false</entry>
-
                   <entry>3.1.5</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>elideSetAutoCommits</entry>
-
-                  <entry>If using MySQL-4.1 or newer, should the driver only issue 'set autocommit=n' queries when the server's state doesn't match the requested state by Connection.setAutoCommit(boolean)?</entry>
-
+                  <entry>If using MySQL-4.1 or newer, should the driver only issue 'set
+                    autocommit=n' queries when the server's state
+                    doesn't match the requested state by
+                    <literal>Connection.setAutoCommit(boolean)</literal>?</entry>
                   <entry>false</entry>
-
                   <entry>3.1.3</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>holdResultsOpenOverStatementClose</entry>
-
-                  <entry>Should the driver close result sets on Statement.close() as required by the JDBC specification?</entry>
-
+                  <entry>Should the driver close result sets on
+                    <literal>Statement.close()</literal> as required by
+                    the JDBC specification?</entry>
                   <entry>false</entry>
-
                   <entry>3.1.7</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>locatorFetchBufferSize</entry>
-
-                  <entry>If 'emulateLocators' is configured to 'true', what size buffer should be used when fetching BLOB data for getBinaryInputStream?</entry>
-
+                  <entry>If 'emulateLocators' is configured to 'true', what size buffer should be
+                    used when fetching BLOB data for
+                    getBinaryInputStream?</entry>
                   <entry>1048576</entry>
-
                   <entry>3.2.1</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>rewriteBatchedStatements</entry>
-
-                  <entry>Should the driver use multiqueries (irregardless of the setting of "allowMultiQueries") as well as rewriting of prepared statements for INSERT into multi-value inserts when executeBatch() is called? Notice that this has the potential for SQL injection if using plain java.sql.Statements and your code doesn't sanitize input correctly. Notice that for prepared statements, server-side prepared statements can not currently take advantage of this rewrite option, and that if you don't specify stream lengths when using PreparedStatement.set*Stream(),the driver won't be able to determine the optimium number of parameters per batch and you might receive anan error from the driver that the resultant packet is too large. Statement.getGeneratedKeys() for these rewritten statements only works when the entire batch includes INSERT statements.</entry>
-
+                  <entry>Should the driver use multiqueries (irregardless of the setting of
+                    <literal>allowMultiQueries</literal>) as well as
+                    rewriting of prepared statements for
+                    <literal>INSERT</literal> into multi-value inserts
+                    when executeBatch() is called? Notice that this has
+                    the potential for SQL injection if using plain
+                    java.sql.Statements and your code doesn't sanitize
+                    input correctly. Notice that for prepared
+                    statements, server-side prepared statements can not
+                    currently take advantage of this rewrite option, and
+                    that if you don't specify stream lengths when using
+                    PreparedStatement.set*Stream(),the driver won't be
+                    able to determine the optimium number of parameters
+                    per batch and you might receive anan error from the
+                    driver that the resultant packet is too large.
+                    Statement.getGeneratedKeys() for these rewritten
+                    statements only works when the entire batch includes
+                    INSERT statements.</entry>
                   <entry>false</entry>
-
                   <entry>3.1.13</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>useFastIntParsing</entry>
-
-                  <entry>Use internal String-&gt;Integer conversion routines to avoid excessive object creation?</entry>
-
+                  <entry>Use internal String-&gt;Integer conversion routines to avoid excessive
+                    object creation?</entry>
                   <entry>true</entry>
-
                   <entry>3.1.4</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>useJvmCharsetConverters</entry>
-
-                  <entry>Always use the character encoding routines built into the JVM, rather than using lookup tables for single-byte character sets? (The default of "true" for this is appropriate for newer JVMs</entry>
-
+                  <entry>Always use the character encoding routines built into the JVM, rather
+                    than using lookup tables for single-byte character
+                    sets? (The default of "true" for this is appropriate
+                    for newer JVMs</entry>
                   <entry>true</entry>
-
                   <entry>5.0.1</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>useLocalSessionState</entry>
-
-                  <entry>Should the driver refer to the internal values of autocommit and transaction isolation that are set by Connection.setAutoCommit() and Connection.setTransactionIsolation(), rather than querying the database?</entry>
-
+                  <entry>Should the driver refer to the internal values of autocommit and
+                    transaction isolation that are set by
+                    Connection.setAutoCommit() and
+                    Connection.setTransactionIsolation(), rather than
+                    querying the database?</entry>
                   <entry>false</entry>
-
                   <entry>3.1.7</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>useReadAheadInput</entry>
-
-                  <entry>Use newer, optimized non-blocking, buffered input stream when reading from the server?</entry>
-
+                  <entry>Use newer, optimized non-blocking, buffered input stream when reading
+                    from the server?</entry>
                   <entry>true</entry>
-
                   <entry>3.1.5</entry>
-               </row>
-            </tbody>
-         </tgroup>
-      </informaltable>
-   </para>
-</formalpara>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
 
-<formalpara>
-   <title>Debuging/Profiling</title>
+      </formalpara>
 
-   <para>
-      <informaltable>
-         <tgroup cols="4">
-            <colspec colwidth="30*" colname="cj_propstbl_prop_name" />
+      <formalpara>
 
-            <colspec colwidth="50*" colname="cj_propstbl_prop_defn" />
+        <title>Debuging/Profiling</title>
 
-            <colspec colwidth="10*" colname="cj_propstbl_default" />
-
-            <colspec colwidth="10*" colname="cj_propstbl_since_version" />
-
-            <tbody>
-               <row>
-                  <entry>
-                     <emphasis role="bold">Property Name</emphasis>
-                  </entry>
-
-                  <entry>
-                     <emphasis role="bold">Definition</emphasis>
-                  </entry>
-
-                  <entry>
-                     <emphasis role="bold">Default Value</emphasis>
-                  </entry>
-
-                  <entry>
-                     <emphasis role="bold">Since Version</emphasis>
-                  </entry>
-               </row>
-
-               <row>
+        <para>
+          <informaltable>
+            <tgroup cols="4">
+              <colspec colwidth="30*" colname="cj_propstbl_prop_name"/>
+              <colspec colwidth="50*" colname="cj_propstbl_prop_defn"/>
+              <colspec colwidth="10*" colname="cj_propstbl_default"/>
+              <colspec colwidth="10*" colname="cj_propstbl_since_version"/>
+              <tbody>
+                <row>
+                  <entry><emphasis role="bold">Property Name</emphasis></entry>
+                  <entry><emphasis role="bold">Definition</emphasis></entry>
+                  <entry><emphasis role="bold">Default Value</emphasis></entry>
+                  <entry><emphasis role="bold">Since Version</emphasis></entry>
+                </row>
+                <row>
                   <entry>logger</entry>
-
-                  <entry>The name of a class that implements 'com.mysql.jdbc.log.Log' that will be used to log messages to.(default is 'com.mysql.jdbc.log.StandardLogger', which logs to STDERR)</entry>
-
+                  <entry>The name of a class that implements 'com.mysql.jdbc.log.Log' that will
+                    be used to log messages to.(default is
+                    'com.mysql.jdbc.log.StandardLogger', which logs to
+                    STDERR)</entry>
                   <entry>com.mysql.jdbc.log.StandardLogger</entry>
-
                   <entry>3.1.1</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>profileSQL</entry>
-
-                  <entry>Trace queries and their execution/fetch times to the configured logger (true/false) defaults to 'false'</entry>
-
+                  <entry>Trace queries and their execution/fetch times to the configured logger
+                    (true/false) defaults to 'false'</entry>
                   <entry>false</entry>
-
                   <entry>3.1.0</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>reportMetricsIntervalMillis</entry>
-
-                  <entry>If 'gatherPerfMetrics' is enabled, how often should they be logged (in ms)?</entry>
-
+                  <entry>If 'gatherPerfMetrics' is enabled, how often should they be logged (in
+                    ms)?</entry>
                   <entry>30000</entry>
-
                   <entry>3.1.2</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>maxQuerySizeToLog</entry>
-
-                  <entry>Controls the maximum length/size of a query that will get logged when profiling or tracing</entry>
-
+                  <entry>Controls the maximum length/size of a query that will get logged when
+                    profiling or tracing</entry>
                   <entry>2048</entry>
-
                   <entry>3.1.3</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>packetDebugBufferSize</entry>
-
                   <entry>The maximum number of packets to retain when 'enablePacketDebug' is true</entry>
-
                   <entry>20</entry>
-
                   <entry>3.1.3</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>slowQueryThresholdMillis</entry>
-
-                  <entry>If 'logSlowQueries' is enabled, how long should a query (in ms) before it is logged as 'slow'?</entry>
-
+                  <entry>If 'logSlowQueries' is enabled, how long should a query (in ms) before
+                    it is logged as 'slow'?</entry>
                   <entry>2000</entry>
-
                   <entry>3.1.2</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>useUsageAdvisor</entry>
-
-                  <entry>Should the driver issue 'usage' warnings advising proper and efficient usage of JDBC and MySQL Connector/J to the log (true/false, defaults to 'false')?</entry>
-
+                  <entry>Should the driver issue 'usage' warnings advising proper and efficient
+                    usage of JDBC and MySQL Connector/J to the log
+                    (true/false, defaults to 'false')?</entry>
                   <entry>false</entry>
-
                   <entry>3.1.1</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>autoGenerateTestcaseScript</entry>
-
-                  <entry>Should the driver dump the SQL it is executing, including server-side prepared statements to STDERR?</entry>
-
+                  <entry>Should the driver dump the SQL it is executing, including server-side
+                    prepared statements to STDERR?</entry>
                   <entry>false</entry>
-
                   <entry>3.1.9</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>dumpMetadataOnColumnNotFound</entry>
-
-                  <entry>Should the driver dump the field-level metadata of a result set into the exception message when ResultSet.findColumn() fails?</entry>
-
+                  <entry>Should the driver dump the field-level metadata of a result set into the
+                    exception message when ResultSet.findColumn() fails?</entry>
                   <entry>false</entry>
-
                   <entry>3.1.13</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>dumpQueriesOnException</entry>
-
-                  <entry>Should the driver dump the contents of the query sent to the server in the message for SQLExceptions?</entry>
-
+                  <entry>Should the driver dump the contents of the query sent to the server in
+                    the message for SQLExceptions?</entry>
                   <entry>false</entry>
-
                   <entry>3.1.3</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>enablePacketDebug</entry>
-
-                  <entry>When enabled, a ring-buffer of 'packetDebugBufferSize' packets will be kept, and dumped when exceptions are thrown in key areas in the driver's code</entry>
-
+                  <entry>When enabled, a ring-buffer of 'packetDebugBufferSize' packets will be
+                    kept, and dumped when exceptions are thrown in key
+                    areas in the driver's code</entry>
                   <entry>false</entry>
-
                   <entry>3.1.3</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>explainSlowQueries</entry>
-
-                  <entry>If 'logSlowQueries' is enabled, should the driver automatically issue an 'EXPLAIN' on the server and send the results to the configured log at a WARN level?</entry>
-
+                  <entry>If 'logSlowQueries' is enabled, should the driver automatically issue an
+                    'EXPLAIN' on the server and send the results to the
+                    configured log at a WARN level?</entry>
                   <entry>false</entry>
-
                   <entry>3.1.2</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>logSlowQueries</entry>
-
-                  <entry>Should queries that take longer than 'slowQueryThresholdMillis' be logged?</entry>
-
+                  <entry>Should queries that take longer than 'slowQueryThresholdMillis' be
+                    logged?</entry>
                   <entry>false</entry>
-
                   <entry>3.1.2</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>traceProtocol</entry>
-
                   <entry>Should trace-level network protocol be logged?</entry>
-
                   <entry>false</entry>
-
                   <entry>3.1.2</entry>
-               </row>
-            </tbody>
-         </tgroup>
-      </informaltable>
-   </para>
-</formalpara>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
 
-<formalpara>
-   <title>Miscellaneous</title>
+      </formalpara>
 
-   <para>
-      <informaltable>
-         <tgroup cols="4">
-            <colspec colwidth="30*" colname="cj_propstbl_prop_name" />
+      <formalpara>
 
-            <colspec colwidth="50*" colname="cj_propstbl_prop_defn" />
+        <title>Miscellaneous</title>
 
-            <colspec colwidth="10*" colname="cj_propstbl_default" />
-
-            <colspec colwidth="10*" colname="cj_propstbl_since_version" />
-
-            <tbody>
-               <row>
-                  <entry>
-                     <emphasis role="bold">Property Name</emphasis>
-                  </entry>
-
-                  <entry>
-                     <emphasis role="bold">Definition</emphasis>
-                  </entry>
-
-                  <entry>
-                     <emphasis role="bold">Default Value</emphasis>
-                  </entry>
-
-                  <entry>
-                     <emphasis role="bold">Since Version</emphasis>
-                  </entry>
-               </row>
-
-               <row>
+        <para>
+          <informaltable>
+            <tgroup cols="4">
+              <colspec colwidth="30*" colname="cj_propstbl_prop_name"/>
+              <colspec colwidth="50*" colname="cj_propstbl_prop_defn"/>
+              <colspec colwidth="10*" colname="cj_propstbl_default"/>
+              <colspec colwidth="10*" colname="cj_propstbl_since_version"/>
+              <tbody>
+                <row>
+                  <entry><emphasis role="bold">Property Name</emphasis></entry>
+                  <entry><emphasis role="bold">Definition</emphasis></entry>
+                  <entry><emphasis role="bold">Default Value</emphasis></entry>
+                  <entry><emphasis role="bold">Since Version</emphasis></entry>
+                </row>
+                <row>
                   <entry>useUnicode</entry>
-
-                  <entry>Should the driver use Unicode character encodings when handling strings? Should only be used when the driver can't determine the character set mapping, or you are trying to 'force' the driver to use a character set that MySQL either doesn't natively support (such as UTF-8), true/false, defaults to 'true'</entry>
-
+                  <entry>Should the driver use Unicode character encodings when handling strings?
+                    Should only be used when the driver can't determine
+                    the character set mapping, or you are trying to
+                    'force' the driver to use a character set that MySQL
+                    either doesn't natively support (such as UTF-8),
+                    true/false, defaults to 'true'</entry>
                   <entry>true</entry>
-
                   <entry>1.1g</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>characterEncoding</entry>
-
-                  <entry>If 'useUnicode' is set to true, what character encoding should the driver use when dealing with strings? (defaults is to 'autodetect')</entry>
-
-                  <entry>
-                  </entry>
-
+                  <entry>If 'useUnicode' is set to true, what character encoding should the
+                    driver use when dealing with strings? (defaults is
+                    to 'autodetect')</entry>
+                  <entry/>
                   <entry>1.1g</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>characterSetResults</entry>
-
                   <entry>Character set to tell the server to return results as.</entry>
-
-                  <entry>
-                  </entry>
-
+                  <entry/>
                   <entry>3.0.13</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>connectionCollation</entry>
-
-                  <entry>If set, tells the server to use this collation via 'set collation_connection'</entry>
-
-                  <entry>
-                  </entry>
-
+                  <entry>If set, tells the server to use this collation via 'set
+                    collation_connection'</entry>
+                  <entry/>
                   <entry>3.0.13</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>sessionVariables</entry>
-
-                  <entry>A comma-separated list of name/value pairs to be sent as SET SESSION ... to the server when the driver connects.</entry>
-
-                  <entry>
-                  </entry>
-
+                  <entry>A comma-separated list of name/value pairs to be sent as SET SESSION ...
+                    to the server when the driver connects.</entry>
+                  <entry/>
                   <entry>3.1.8</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>allowNanAndInf</entry>
-
-                  <entry>Should the driver allow NaN or +/- INF values in PreparedStatement.setDouble()?</entry>
-
+                  <entry>Should the driver allow NaN or +/- INF values in
+                    PreparedStatement.setDouble()?</entry>
                   <entry>false</entry>
-
                   <entry>3.1.5</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>autoClosePStmtStreams</entry>
-
-                  <entry>Should the driver automatically call .close() on streams/readers passed as arguments via set*() methods?</entry>
-
+                  <entry>Should the driver automatically call .close() on streams/readers passed
+                    as arguments via set*() methods?</entry>
                   <entry>false</entry>
-
                   <entry>3.1.12</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>autoDeserialize</entry>
-
-                  <entry>Should the driver automatically detect and de-serialize objects stored in BLOB fields?</entry>
-
+                  <entry>Should the driver automatically detect and de-serialize objects stored
+                    in BLOB fields?</entry>
                   <entry>false</entry>
-
                   <entry>3.1.5</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>capitalizeTypeNames</entry>
-
-                  <entry>Capitalize type names in DatabaseMetaData? (usually only useful when using WebObjects, true/false, defaults to 'false')</entry>
-
+                  <entry>Capitalize type names in DatabaseMetaData? (usually only useful when
+                    using WebObjects, true/false, defaults to 'false')</entry>
                   <entry>false</entry>
-
                   <entry>2.0.7</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>clobCharacterEncoding</entry>
-
-                  <entry>The character encoding to use for sending and retrieving TEXT, MEDIUMTEXT and LONGTEXT values instead of the configured connection characterEncoding</entry>
-
-                  <entry>
-                  </entry>
-
+                  <entry>The character encoding to use for sending and retrieving TEXT,
+                    MEDIUMTEXT and LONGTEXT values instead of the
+                    configured connection characterEncoding</entry>
+                  <entry/>
                   <entry>5.0.0</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>clobberStreamingResults</entry>
-
-                  <entry>This will cause a 'streaming' ResultSet to be automatically closed, and any outstanding data still streaming from the server to be discarded if another query is executed before all the data has been read from the server.</entry>
-
+                  <entry>This will cause a 'streaming' ResultSet to be automatically closed, and
+                    any outstanding data still streaming from the server
+                    to be discarded if another query is executed before
+                    all the data has been read from the server.</entry>
                   <entry>false</entry>
-
                   <entry>3.0.9</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>continueBatchOnError</entry>
-
-                  <entry>Should the driver continue processing batch commands if one statement fails. The JDBC spec allows either way (defaults to 'true').</entry>
-
+                  <entry>Should the driver continue processing batch commands if one statement
+                    fails. The JDBC spec allows either way (defaults to
+                    'true').</entry>
                   <entry>true</entry>
-
                   <entry>3.0.3</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>createDatabaseIfNotExist</entry>
-
-                  <entry>Creates the database given in the URL if it doesn't yet exist. Assumes the configured user has permissions to create databases.</entry>
-
+                  <entry>Creates the database given in the URL if it doesn't yet exist. Assumes
+                    the configured user has permissions to create
+                    databases.</entry>
                   <entry>false</entry>
-
                   <entry>3.1.9</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>emptyStringsConvertToZero</entry>
-
-                  <entry>Should the driver allow conversions from empty string fields to numeric values of '0'?</entry>
-
+                  <entry>Should the driver allow conversions from empty string fields to numeric
+                    values of '0'?</entry>
                   <entry>true</entry>
-
                   <entry>3.1.8</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>emulateLocators</entry>
-
                   <entry>N/A</entry>
-
                   <entry>false</entry>
-
                   <entry>3.1.0</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>emulateUnsupportedPstmts</entry>
-
-                  <entry>Should the driver detect prepared statements that are not supported by the server, and replace them with client-side emulated versions?</entry>
-
+                  <entry>Should the driver detect prepared statements that are not supported by
+                    the server, and replace them with client-side
+                    emulated versions?</entry>
                   <entry>true</entry>
-
                   <entry>3.1.7</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>ignoreNonTxTables</entry>
-
-                  <entry>Ignore non-transactional table warning for rollback? (defaults to 'false').</entry>
-
+                  <entry>Ignore non-transactional table warning for rollback? (defaults to
+                    'false').</entry>
                   <entry>false</entry>
-
                   <entry>3.0.9</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>jdbcCompliantTruncation</entry>
-
-                  <entry>Should the driver throw java.sql.DataTruncation exceptions when data is truncated as is required by the JDBC specification when connected to a server that supports warnings(MySQL 4.1.0 and newer)?</entry>
-
+                  <entry>Should the driver throw java.sql.DataTruncation exceptions when data is
+                    truncated as is required by the JDBC specification
+                    when connected to a server that supports
+                    warnings(MySQL 4.1.0 and newer)?</entry>
                   <entry>true</entry>
-
                   <entry>3.1.2</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>maxRows</entry>
-
-                  <entry>The maximum number of rows to return (0, the default means return all rows).</entry>
-
+                  <entry>The maximum number of rows to return (0, the default means return all
+                    rows).</entry>
                   <entry>-1</entry>
-
                   <entry>all versions</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>noAccessToProcedureBodies</entry>
-
-                  <entry>When determining procedure parameter types for CallableStatements, and the connected user can't access procedure bodies through "SHOW CREATE PROCEDURE" or select on mysql.proc should the driver instead create basic metadata (all parameters reported as INOUT VARCHARs) instead of throwing an exception?</entry>
-
+                  <entry>When determining procedure parameter types for CallableStatements, and
+                    the connected user can't access procedure bodies
+                    through "SHOW CREATE PROCEDURE" or select on
+                    mysql.proc should the driver instead create basic
+                    metadata (all parameters reported as INOUT VARCHARs)
+                    instead of throwing an exception?</entry>
                   <entry>false</entry>
-
                   <entry>5.0.3</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>noDatetimeStringSync</entry>
-
-                  <entry>Don't ensure that ResultSet.getDatetimeType().toString().equals(ResultSet.getString())</entry>
-
+                  <entry>Don't ensure that
+                    ResultSet.getDatetimeType().toString().equals(ResultSet.getString())</entry>
                   <entry>false</entry>
-
                   <entry>3.1.7</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>noTimezoneConversionForTimeType</entry>
-
-                  <entry>Don't convert TIME values using the server timezone if 'useTimezone'='true'</entry>
-
+                  <entry>Don't convert TIME values using the server timezone if
+                    'useTimezone'='true'</entry>
                   <entry>false</entry>
-
                   <entry>5.0.0</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>nullCatalogMeansCurrent</entry>
-
-                  <entry>When DatabaseMetadataMethods ask for a 'catalog' parameter, does the value null mean use the current catalog? (this is not JDBC-compliant, but follows legacy behavior from earlier versions of the driver)</entry>
-
+                  <entry>When DatabaseMetadataMethods ask for a 'catalog' parameter, does the
+                    value null mean use the current catalog? (this is
+                    not JDBC-compliant, but follows legacy behavior from
+                    earlier versions of the driver)</entry>
                   <entry>true</entry>
-
                   <entry>3.1.8</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>nullNamePatternMatchesAll</entry>
-
-                  <entry>Should DatabaseMetaData methods that accept *pattern parameters treat null the same as '%' (this is not JDBC-compliant, however older versions of the driver accepted this departure from the specification)</entry>
-
+                  <entry>Should DatabaseMetaData methods that accept *pattern parameters treat
+                    null the same as '%' (this is not JDBC-compliant,
+                    however older versions of the driver accepted this
+                    departure from the specification)</entry>
                   <entry>true</entry>
-
                   <entry>3.1.8</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>overrideSupportsIntegrityEnhancementFacility</entry>
-
-                  <entry>Should the driver return "true" for DatabaseMetaData.supportsIntegrityEnhancementFacility() even if the database doesn't support it to workaround applications that require this method to return "true" to signal support of foreign keys, even though the SQL specification states that this facility contains much more than just foreign key support (one such application being OpenOffice)?</entry>
-
+                  <entry>Should the driver return "true" for
+                    DatabaseMetaData.supportsIntegrityEnhancementFacility()
+                    even if the database doesn't support it to
+                    workaround applications that require this method to
+                    return "true" to signal support of foreign keys,
+                    even though the SQL specification states that this
+                    facility contains much more than just foreign key
+                    support (one such application being OpenOffice)?</entry>
                   <entry>false</entry>
-
                   <entry>3.1.12</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>pedantic</entry>
-
                   <entry>Follow the JDBC spec to the letter.</entry>
-
                   <entry>false</entry>
-
                   <entry>3.0.0</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>pinGlobalTxToPhysicalConnection</entry>
-
-                  <entry>When using XAConnections, should the driver ensure that operations on a given XID are always routed to the same physical connection? This allows the XAConnection to support "XA START ... JOIN" after "XA END" has been called</entry>
-
+                  <entry>When using XAConnections, should the driver ensure that operations on a
+                    given XID are always routed to the same physical
+                    connection? This allows the XAConnection to support
+                    "XA START ... JOIN" after "XA END" has been called</entry>
                   <entry>false</entry>
-
                   <entry>5.0.1</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>processEscapeCodesForPrepStmts</entry>
-
                   <entry>Should the driver process escape codes in queries that are prepared?</entry>
-
                   <entry>true</entry>
-
                   <entry>3.1.12</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>relaxAutoCommit</entry>
-
-                  <entry>If the version of MySQL the driver connects to does not support transactions, still allow calls to commit(), rollback() and setAutoCommit() (true/false, defaults to 'false')?</entry>
-
+                  <entry>If the version of MySQL the driver connects to does not support
+                    transactions, still allow calls to commit(),
+                    rollback() and setAutoCommit() (true/false, defaults
+                    to 'false')?</entry>
                   <entry>false</entry>
-
                   <entry>2.0.13</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>retainStatementAfterResultSetClose</entry>
-
-                  <entry>Should the driver retain the Statement reference in a ResultSet after ResultSet.close() has been called. This is not JDBC-compliant after JDBC-4.0.</entry>
-
+                  <entry>Should the driver retain the Statement reference in a ResultSet after
+                    ResultSet.close() has been called. This is not
+                    JDBC-compliant after JDBC-4.0.</entry>
                   <entry>false</entry>
-
                   <entry>3.1.11</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>rollbackOnPooledClose</entry>
-
-                  <entry>Should the driver issue a rollback() when the logical connection in a pool is closed?</entry>
-
+                  <entry>Should the driver issue a rollback() when the logical connection in a
+                    pool is closed?</entry>
                   <entry>true</entry>
-
                   <entry>3.0.15</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>runningCTS13</entry>
-
-                  <entry>Enables workarounds for bugs in Sun's JDBC compliance testsuite version 1.3</entry>
-
+                  <entry>Enables workarounds for bugs in Sun's JDBC compliance testsuite version
+                    1.3</entry>
                   <entry>false</entry>
-
                   <entry>3.1.7</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>serverTimezone</entry>
-
-                  <entry>Override detection/mapping of timezone. Used when timezone from server doesn't map to Java timezone</entry>
-
-                  <entry>
-                  </entry>
-
+                  <entry>Override detection/mapping of timezone. Used when timezone from server
+                    doesn't map to Java timezone</entry>
+                  <entry/>
                   <entry>3.0.2</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>strictFloatingPoint</entry>
-
                   <entry>Used only in older versions of compliance test</entry>
-
                   <entry>false</entry>
-
                   <entry>3.0.0</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>strictUpdates</entry>
-
-                  <entry>Should the driver do strict checking (all primary keys selected) of updatable result sets (true, false, defaults to 'true')?</entry>
-
+                  <entry>Should the driver do strict checking (all primary keys selected) of
+                    updatable result sets (true, false, defaults to
+                    'true')?</entry>
                   <entry>true</entry>
-
                   <entry>3.0.4</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>tinyInt1isBit</entry>
-
-                  <entry>Should the driver treat the datatype TINYINT(1) as the BIT type (because the server silently converts BIT -&gt; TINYINT(1) when creating tables)?</entry>
-
+                  <entry>Should the driver treat the datatype TINYINT(1) as the BIT type (because
+                    the server silently converts BIT -&gt; TINYINT(1)
+                    when creating tables)?</entry>
                   <entry>true</entry>
-
                   <entry>3.0.16</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>transformedBitIsBoolean</entry>
-
-                  <entry>If the driver converts TINYINT(1) to a different type, should it use BOOLEAN instead of BIT for future compatibility with MySQL-5.0, as MySQL-5.0 has a BIT type?</entry>
-
+                  <entry>If the driver converts TINYINT(1) to a different type, should it use
+                    BOOLEAN instead of BIT for future compatibility with
+                    MySQL-5.0, as MySQL-5.0 has a BIT type?</entry>
                   <entry>false</entry>
-
                   <entry>3.1.9</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>ultraDevHack</entry>
-
-                  <entry>Create PreparedStatements for prepareCall() when required, because UltraDev is broken and issues a prepareCall() for _all_ statements? (true/false, defaults to 'false')</entry>
-
+                  <entry>Create PreparedStatements for prepareCall() when required, because
+                    UltraDev is broken and issues a prepareCall() for
+                    _all_ statements? (true/false, defaults to 'false')</entry>
                   <entry>false</entry>
-
                   <entry>2.0.3</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>useGmtMillisForDatetimes</entry>
-
-                  <entry>Convert between session timezone and GMT before creating Date and Timestamp instances (value of "false" is legacy behavior, "true" leads to more JDBC-compliant behavior.</entry>
-
+                  <entry>Convert between session timezone and GMT before creating Date and
+                    Timestamp instances (value of "false" is legacy
+                    behavior, "true" leads to more JDBC-compliant
+                    behavior.</entry>
                   <entry>false</entry>
-
                   <entry>3.1.12</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>useHostsInPrivileges</entry>
-
-                  <entry>Add '@hostname' to users in DatabaseMetaData.getColumn/TablePrivileges() (true/false), defaults to 'true'.</entry>
-
+                  <entry>Add '@hostname' to users in DatabaseMetaData.getColumn/TablePrivileges()
+                    (true/false), defaults to 'true'.</entry>
                   <entry>true</entry>
-
                   <entry>3.0.2</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>useInformationSchema</entry>
-
-                  <entry>When connected to MySQL-5.0.7 or newer, should the driver use the INFORMATION_SCHEMA to derive information used by DatabaseMetaData?</entry>
-
+                  <entry>When connected to MySQL-5.0.7 or newer, should the driver use the
+                    INFORMATION_SCHEMA to derive information used by
+                    DatabaseMetaData?</entry>
                   <entry>false</entry>
-
                   <entry>5.0.0</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>useJDBCCompliantTimezoneShift</entry>
-
-                  <entry>Should the driver use JDBC-compliant rules when converting TIME/TIMESTAMP/DATETIME values' timezone information for those JDBC arguments which take a java.util.Calendar argument? (Notice that this option is exclusive of the "useTimezone=true" configuration option.)</entry>
-
+                  <entry>Should the driver use JDBC-compliant rules when converting
+                    TIME/TIMESTAMP/DATETIME values' timezone information
+                    for those JDBC arguments which take a
+                    java.util.Calendar argument? (Notice that this
+                    option is exclusive of the "useTimezone=true"
+                    configuration option.)</entry>
                   <entry>false</entry>
-
                   <entry>5.0.0</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>useOldUTF8Behavior</entry>
-
-                  <entry>Use the UTF-8 behavior the driver did when communicating with 4.0 and older servers</entry>
-
+                  <entry>Use the UTF-8 behavior the driver did when communicating with 4.0 and
+                    older servers</entry>
                   <entry>false</entry>
-
                   <entry>3.1.6</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>useOnlyServerErrorMessages</entry>
-
-                  <entry>Don't prepend 'standard' SQLState error messages to error messages returned by the server.</entry>
-
+                  <entry>Don't prepend 'standard' SQLState error messages to error messages
+                    returned by the server.</entry>
                   <entry>true</entry>
-
                   <entry>3.0.15</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>useServerPrepStmts</entry>
-
-                  <entry>Use server-side prepared statements if the server supports them? (defaults to 'true').</entry>
-
+                  <entry>Use server-side prepared statements if the server supports them?
+                    (defaults to 'true').</entry>
                   <entry>true</entry>
-
                   <entry>3.1.0</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>useSqlStateCodes</entry>
-
-                  <entry>Use SQL Standard state codes instead of 'legacy' X/Open/SQL state codes (true/false), default is 'true'</entry>
-
+                  <entry>Use SQL Standard state codes instead of 'legacy' X/Open/SQL state codes
+                    (true/false), default is 'true'</entry>
                   <entry>true</entry>
-
                   <entry>3.1.3</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>useStreamLengthsInPrepStmts</entry>
-
-                  <entry>Honor stream length parameter in PreparedStatement/ResultSet.setXXXStream() method calls (true/false, defaults to 'true')?</entry>
-
+                  <entry>Honor stream length parameter in
+                    PreparedStatement/ResultSet.setXXXStream() method
+                    calls (true/false, defaults to 'true')?</entry>
                   <entry>true</entry>
-
                   <entry>3.0.2</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>useTimezone</entry>
-
-                  <entry>Convert time/date types between client and server timezones (true/false, defaults to 'false')?</entry>
-
+                  <entry>Convert time/date types between client and server timezones (true/false,
+                    defaults to 'false')?</entry>
                   <entry>false</entry>
-
                   <entry>3.0.2</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>useUnbufferedInput</entry>
-
                   <entry>Don't use BufferedInputStream for reading data from the server</entry>
-
                   <entry>true</entry>
-
                   <entry>3.0.11</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>yearIsDateType</entry>
-
-                  <entry>Should the JDBC driver treat the MySQL type "YEAR" as a java.sql.Date, or as a SHORT?</entry>
-
+                  <entry>Should the JDBC driver treat the MySQL type "YEAR" as a java.sql.Date,
+                    or as a SHORT?</entry>
                   <entry>true</entry>
-
                   <entry>3.1.9</entry>
-               </row>
-
-               <row>
+                </row>
+                <row>
                   <entry>zeroDateTimeBehavior</entry>
-
-                  <entry>What should happen when the driver encounters DATETIME values that are composed entirely of zeroes (used by MySQL to represent invalid dates)? Valid values are 'exception', 'round' and 'convertToNull'.</entry>
-
+                  <entry>What should happen when the driver encounters DATETIME values that are
+                    composed entirely of zeroes (used by MySQL to
+                    represent invalid dates)? Valid values are
+                    'exception', 'round' and 'convertToNull'.</entry>
                   <entry>exception</entry>
-
                   <entry>3.1.4</entry>
-               </row>
-            </tbody>
-         </tgroup>
-      </informaltable>
-   </para>
-</formalpara>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
 
+      </formalpara>
 
-
 <!-- End generated content -->
 
       <para>
         Connector/J also supports access to MySQL via named pipes on
-        Windows NT/2000/XP using the 'NamedPipeSocketFactory' as a
-        plugin-socket factory via the 'socketFactory' property. If you
-        don't use a 'namedPipePath' property, the default of
-        '\\.\pipe\MySQL' will be used. If you use the
-        NamedPipeSocketFactory, the hostname and port number values in
-        the JDBC url will be ignored.
+        Windows NT/2000/XP using the
+        <property>NamedPipeSocketFactory</property> as a plugin-socket
+        factory via the <property>socketFactory</property> property. If
+        you don't use a <property>namedPipePath</property> property, the
+        default of '\\.\pipe\MySQL' will be used. If you use the
+        <literal>NamedPipeSocketFactory</literal>, the hostname and port
+        number values in the JDBC url will be ignored. You can enable
+        this feature using:
       </para>
 
-      <para>
-        Adding the following property to your URL will enable the
-        NamedPipeSocketFactory:
-      </para>
+<programlisting>socketFactory=com.mysql.jdbc.NamedPipeSocketFactory
+        </programlisting>
 
       <para>
-        socketFactory=com.mysql.jdbc.NamedPipeSocketFactory
-      </para>
-
-      <para>
         Named pipes only work when connecting to a MySQL server on the
         same physical machine as the one the JDBC driver is being used
         on. In simple performance tests, it appears that named pipe

@@ -3009,7 +2093,7 @@
 
     </section>
 
-    <section id="cj-implementation-notes">
+    <section id="connector-j-reference-implementation-notes">
 
       <title>JDBC API Implementation Notes</title>
 

@@ -3036,12 +2120,13 @@
 
           <para>
             The Blob implementation does not allow in-place modification
-            (they are 'copies', as reported by the
-            DatabaseMetaData.locatorsUpdateCopies() method). Because of
-            this, you should use the corresponding
-            PreparedStatement.setBlob() or ResultSet.updateBlob() (in
-            the case of updatable result sets) methods to save changes
-            back to the database.
+            (they are copies, as reported by the
+            <literal>DatabaseMetaData.locatorsUpdateCopies()</literal>
+            method). Because of this, you should use the corresponding
+            <literal>PreparedStatement.setBlob()</literal> or
+            <literal>ResultSet.updateBlob()</literal> (in the case of
+            updatable result sets) methods to save changes back to the
+            database.
           </para>
 
           <para>

@@ -3049,13 +2134,15 @@
             Blobs with locators by adding the property
             'emulateLocators=true' to your JDBC URL. You must then use a
             column alias with the value of the column set to the actual
-            name of the Blob column in the SELECT that you write to
-            retrieve the Blob. The SELECT must also reference only one
-            table, the table must have a primary key, and the SELECT
-            must cover all columns that make up the primary key. The
-            driver will then delay loading the actual Blob data until
-            you retrieve the Blob and call retrieval methods
-            (getInputStream(), getBytes(), and so forth) on it.
+            name of the Blob column in the <literal>SELECT</literal>
+            that you write to retrieve the Blob. The
+            <literal>SELECT</literal> must also reference only one
+            table, the table must have a primary key, and the
+            <literal>SELECT</literal> must cover all columns that make
+            up the primary key. The driver will then delay loading the
+            actual Blob data until you retrieve the Blob and call
+            retrieval methods (<literal>getInputStream()</literal>,
+            <literal>getBytes()</literal>, and so forth) on it.
           </para>
         </listitem>
 

@@ -3068,7 +2155,7 @@
             Starting with Connector/J 3.1.1, stored procedures are
             supported when connecting to MySQL version 5.0 or newer via
             the <classname>CallableStatement</classname> interface.
-            Currently, the <function>getParameterMetaData()</function>
+            Currently, the <literal>getParameterMetaData()</literal>
             method of <classname>CallableStatement</classname> is not
             supported.
           </para>

@@ -3081,11 +2168,12 @@
 
           <para>
             The Clob implementation does not allow in-place modification
-            (they are 'copies', as reported by the
-            DatabaseMetaData.locatorsUpdateCopies() method). Because of
-            this, you should use the PreparedStatement.setClob() method
-            to save changes back to the database. The JDBC API does not
-            have a ResultSet.updateClob() method.
+            (they are copies, as reported by the
+            <literal>DatabaseMetaData.locatorsUpdateCopies()</literal>
+            method). Because of this, you should use the
+            <literal>PreparedStatement.setClob()</literal> method to
+            save changes back to the database. The JDBC API does not
+            have a <literal>ResultSet.updateClob()</literal> method.
           </para>
         </listitem>
 

@@ -3096,14 +2184,14 @@
 
           <para>
             Unlike older versions of MM.MySQL the
-            <function>isClosed()</function> method does not
-            <quote>ping</quote> the server to determine if it is alive.
-            In accordance with the JDBC specification, it only returns
-            true if 'closed()' has been called on the connection. If you
-            need to determine if the connection is still valid, you
-            should issue a simple query, such as "SELECT 1". The driver
-            will throw an exception if the connection is no longer
-            valid.
+            <literal>isClosed()</literal> method does not ping the
+            server to determine if it is alive. In accordance with the
+            JDBC specification, it only returns true if
+            <literal>closed()</literal> has been called on the
+            connection. If you need to determine if the connection is
+            still valid, you should issue a simple query, such as
+            <literal>SELECT 1</literal>. The driver will throw an
+            exception if the connection is no longer valid.
           </para>
         </listitem>
 

@@ -3113,56 +2201,55 @@
           </para>
 
           <para>
-            Foreign Key information (getImported/ExportedKeys() and
-            getCrossReference()) is only available from 'InnoDB'-type
-            tables. However, the driver uses 'SHOW CREATE TABLE' to
-            retrieve this information, so when other storage engines
-            support foreign keys, the driver will transparently support
-            them as well.
+            Foreign Key information
+            (<literal>getImportedKeys()</literal>/<literal>getExportedKeys()</literal>
+            and <literal>getCrossReference()</literal>) is only
+            available from InnoDB tables. However, the driver uses
+            <literal>SHOW CREATE TABLE</literal> to retrieve this
+            information, so when other storage engines support foreign
+            keys, the driver will transparently support them as well.
           </para>
         </listitem>
 
         <listitem>
           <para>
-            Driver
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
             PreparedStatement
           </para>
 
           <para>
             PreparedStatements are implemented by the driver, as MySQL
             does not have a prepared statement feature. Because of this,
-            the driver does not implement getParameterMetaData() or
-            getMetaData() as it would require the driver to have a
-            complete SQL parser in the client.
+            the driver does not implement
+            <literal>getParameterMetaData()</literal> or
+            <literal>getMetaData()</literal> as it would require the
+            driver to have a complete SQL parser in the client.
           </para>
 
           <para>
             Starting with version 3.1.0 MySQL Connector/J, server-side
-            prepared statements and 'binary-encoded' result sets are
-            used when the server supports them.
+            prepared statements and binary-encoded result sets are used
+            when the server supports them.
           </para>
 
           <para>
             Take care when using a server-side prepared statement with
-            <quote>large</quote> parameters that are set via
-            setBinaryStream(), setAsciiStream(), setUnicodeStream(),
-            setBlob(), or setClob(). If you want to re-execute the
-            statement with any <quote>large</quote> parameter changed to
-            a non-<quote>large</quote> parameter, it is necessary to
-            call clearParameters() and set all parameters again. The
-            reason for this is as follows:
+            <emphasis role="bold">large</emphasis> parameters that are
+            set via <literal>setBinaryStream()</literal>,
+            <literal>setAsciiStream()</literal>,
+            <literal>setUnicodeStream()</literal>,
+            <literal>setBlob()</literal>, or
+            <literal>setClob()</literal>. If you want to re-execute the
+            statement with any large parameter changed to a non-large
+            parameter, it is necessary to call
+            <literal>clearParameters()</literal> and set all parameters
+            again. The reason for this is as follows:
           </para>
 
           <itemizedlist>
 
             <listitem>
               <para>
-                The driver streams the 'large' data 'out-of-band' to the
+                The driver streams the large data out-of-band to the
                 prepared statement on the server side when the parameter
                 is set (before execution of the prepared statement).
               </para>

@@ -3186,25 +2273,28 @@
 
             <listitem>
               <para>
-                If a parameter changes from <quote>large</quote> to
-                non-<quote>large,</quote> the driver must reset the
-                server-side state of the prepared statement to allow the
-                parameter that is being changed to take the place of the
-                prior <quote>large</quote> value. This removes all of
-                the 'large' data that has already been sent to the
+                If a parameter changes from large to non-large, the
+                driver must reset the server-side state of the prepared
+                statement to allow the parameter that is being changed
+                to take the place of the prior large value. This removes
+                all of the large data that has already been sent to the
                 server, thus requiring the data to be re-sent, via the
-                setBinaryStream(), setAsciiStream(), setUnicodeStream(),
-                setBlob() or setClob() methods.
+                <literal>setBinaryStream()</literal>,
+                <literal>setAsciiStream()</literal>,
+                <literal>setUnicodeStream()</literal>,
+                <literal>setBlob()</literal> or
+                <literal>setClob()</literal> methods.
               </para>
             </listitem>
 
           </itemizedlist>
 
           <para>
-            Consequently, if you want to change the <quote>type</quote>
-            of a parameter to a non-<quote>large</quote> one, you must
-            call clearParameters() and set all parameters of the
-            prepared statement again before it can be re-executed.
+            Consequently, if you want to change the type of a parameter
+            to a non-large one, you must call
+            <literal>clearParameters()</literal> and set all parameters
+            of the prepared statement again before it can be
+            re-executed.
           </para>
         </listitem>
 

@@ -3220,7 +2310,7 @@
             is easier to implement. If you are working with ResultSets
             that have a large number of rows or large values, and can
             not allocate heap space in your JVM for the memory required,
-            you can tell the driver to 'stream' the results back one row
+            you can tell the driver to stream the results back one row
             at a time.
           </para>
 

@@ -3236,10 +2326,10 @@
 
           <para>
             The combination of a forward-only, read-only result set,
-            with a fetch size of Integer.MIN_VALUE serves as a signal to
-            the driver to <quote>stream</quote> result sets row-by-row.
-            After this any result sets created with the statement will
-            be retrieved row-by-row.
+            with a fetch size of <literal>Integer.MIN_VALUE</literal>
+            serves as a signal to the driver to stream result sets
+            row-by-row. After this any result sets created with the
+            statement will be retrieved row-by-row.
           </para>
 
           <para>

@@ -3266,10 +2356,10 @@
           </para>
 
           <para>
-            Therefore, if using <quote>streaming</quote> results, you
-            should process them as quickly as possible if you want to
-            maintain concurrent access to the tables referenced by the
-            statement producing the result set.
+            Therefore, if using streaming results, you should process
+            them as quickly as possible if you want to maintain
+            concurrent access to the tables referenced by the statement
+            producing the result set.
           </para>
         </listitem>
 

@@ -3279,8 +2369,8 @@
           </para>
 
           <para>
-            The "isAutoIncrement()" method only works when using MySQL
-            servers 4.0 and newer.
+            The <literal>isAutoIncrement()</literal> method only works
+            when using MySQL servers 4.0 and newer.
           </para>
         </listitem>
 

@@ -3306,7 +2396,7 @@
 
     </section>
 
-    <section id="cj-type-conversions">
+    <section id="connector-j-reference-type-conversions">
 
       <title>Java, JDBC and MySQL Types</title>
 

@@ -3326,8 +2416,9 @@
         Starting with Connector/J 3.1.0, the JDBC driver will issue
         warnings or throw DataTruncation exceptions as is required by
         the JDBC specification unless the connection was configured not
-        to do so by using the property "jdbcCompliantTruncation" and
-        setting it to "false".
+        to do so by using the property
+        <property>jdbcCompliantTruncation</property> and setting it to
+        <literal>false</literal>.
       </para>
 
       <para>

@@ -3351,8 +2442,7 @@
                     types</emphasis></entry>
                 </row>
                 <row>
-                  <entry><literal>CHAR, VARCHAR, BLOB, TEXT, ENUM, and
-                    SET</literal></entry>
+                  <entry><literal>CHAR, VARCHAR, BLOB, TEXT, ENUM, and SET</literal></entry>
                   <entry><literal>java.lang.String, java.io.InputStream, java.io.Reader,
                     java.sql.Blob, java.sql.Clob</literal></entry>
                 </row>

@@ -3361,27 +2451,26 @@
                     SMALLINT, MEDIUMINT, INTEGER, BIGINT</literal></entry>
                   <entry><literal>java.lang.String, java.lang.Short, java.lang.Integer,
                     java.lang.Long, java.lang.Double,
-                    java.math.BigDecimal</literal>
-</entry>
-
+                    java.math.BigDecimal</literal></entry>
                 </row>
                 <row>
                   <entry><literal>DATE, TIME, DATETIME, TIMESTAMP</literal></entry>
-                  <entry><literal>java.lang.String, java.sql.Date,
-                    java.sql.Timestamp</literal></entry>
+                  <entry><literal>java.lang.String, java.sql.Date, java.sql.Timestamp</literal></entry>
                 </row>
               </tbody>
             </tgroup>
           </informaltable>
         </para>
+
       </formalpara>
-      <para><emphasis role="bold">Note:</emphasis>
-        round-off, overflow or loss of precision may
-        occur if you choose a Java numeric data type
-        that has less precision or capacity than the
-        MySQL data type you are converting to/from.
+
+      <para>
+        <emphasis role="bold">Note:</emphasis> round-off, overflow or
+        loss of precision may occur if you choose a Java numeric data
+        type that has less precision or capacity than the MySQL data
+        type you are converting to/from.
       </para>
-      
+
       <para>
         The <classname>ResultSet.getObject()</classname> method uses the
         following type conversions between MySQL and Java types,

@@ -3413,12 +2502,13 @@
                 <row>
                   <entry><type>TINYINT</type></entry>
                   <entry><classname>java.lang.Boolean</classname> if the configuration property
-                    "tinyInt1isBit" is set to "true" (the default) and
-                    the storage size is "1", or
+                    <literal>tinyInt1isBit</literal> is set to
+                    <literal>true</literal> (the default) and the
+                    storage size is 1, or
                     <classname>java.lang.Integer</classname> if not.</entry>
                 </row>
                 <row>
-                  <entry><type>BOOL , BOOLEAN</type></entry>
+                  <entry><type>BOOL</type>, <type>BOOLEAN</type></entry>
                   <entry>See <type>TINYINT</type>, above as these are aliases for
                     <type>TINYINT(1)</type>, currently.</entry>
                 </row>

@@ -3543,7 +2633,7 @@
 
     </section>
 
-    <section id="cj-character-sets">
+    <section id="connector-j-reference-charsets">
 
       <title>Using Character Sets and Unicode</title>
 

@@ -3551,9 +2641,9 @@
         All strings sent from the JDBC driver to the server are
         converted automatically from native Java Unicode form to the
         client character encoding, including all queries sent via
-        <methodname>Statement.execute()</methodname>,
-        <methodname>Statement.executeUpdate()</methodname>,
-        <methodname>Statement.executeQuery()</methodname> as well as all
+        <literal>Statement.execute()</literal>,
+        <literal>Statement.executeUpdate()</literal>,
+        <literal>Statement.executeQuery()</literal> as well as all
 
         <interfacename>PreparedStatement</interfacename>
 

@@ -3562,11 +2652,11 @@
         <interfacename>CallableStatement</interfacename>
 
         parameters with the exclusion of parameters set using
-        <methodname>setBytes()</methodname>,
-        <methodname>setBinaryStream()</methodname>,
-        <methodname>setAsciiStream()</methodname>,
-        <methodname>setUnicodeStream()</methodname> and
-        <methodname>setBlob()</methodname> .
+        <literal>setBytes()</literal>,
+        <literal>setBinaryStream()</literal>,
+        <literal>setAsciiStream()</literal>,
+        <literal>setUnicodeStream()</literal> and
+        <literal>setBlob()</literal> .
       </para>
 
       <para>

@@ -3574,7 +2664,7 @@
         character encoding per connection, which could either be
         automatically detected from the server configuration, or could
         be configured by the user through the
-        <parameter>"useUnicode"</parameter> and
+        <parameter>useUnicode</parameter> and
         "<parameter>characterEncoding</parameter>" properties.
       </para>
 

@@ -3777,34 +2867,38 @@
 
       </formalpara>
 
-      <warning>
+      <formalpara>
+
+        <title>Warning</title>
+
         <para>
           Do not issue the query 'set names' with Connector/J, as the
           driver will not detect that the character set has changed, and
           will continue to use the character set detected during the
           initial connection setup.
         </para>
-      </warning>
 
+      </formalpara>
+
       <para>
         To allow multiple character sets to be sent from the client, the
-        "UTF-8" encoding should be used, either by configuring "utf8" as
-        the default server character set, or by configuring the JDBC
-        driver to use "UTF-8" through the
+        UTF-8 encoding should be used, either by configuring
+        <literal>utf8</literal> as the default server character set, or
+        by configuring the JDBC driver to use UTF-8 through the
         <parameter>characterEncoding</parameter> property.
       </para>
 
     </section>
 
 <!--
-      <section id="cj-usage-advisor">
+      <section id="connector-j-reference-usage-advisor">
         <title>Using the Usage Advisor</title>
 
         <para></para>
       </section>
 -->
 
-    <section id="cj-using-ssl">
+    <section id="connector-j-reference-using-ssl">
 
       <title>Connecting Securely Using SSL</title>
 

@@ -3829,15 +2923,16 @@
             JDK that you can add JSSE to, like JDK-1.2.x or JDK-1.3.x
             due to the following JSSE bug:
             <ulink
-          url="http://developer.java.sun.com/developer/bugParade/bugs/4273544.html"/>
+              url="http://developer.java.sun.com/developer/bugParade/bugs/4273544.html"
+            />
           </para>
         </listitem>
 
         <listitem>
           <para>
             A MySQL server that supports SSL and has been compiled and
-            configured to do so, which is MySQL-4.0.4 or later, see:
-            <ulink url="http://www.mysql.com/doc/en/secure-connections.html"/>
+            configured to do so, which is MySQL-4.0.4 or later, see
+            <xref linkend="secure-connections"/>, for more information.
           </para>
         </listitem>
 

@@ -3852,17 +2947,18 @@
       <para>
         You will first need to import the MySQL server CA Certificate
         into a Java truststore. A sample MySQL server CA Certificate is
-        located in the 'SSL' subdirectory of the MySQL source
-        distribution. This is what SSL will use to determine if you are
-        communicating with a secure MySQL server.
+        located in the <filename>SSL</filename> subdirectory of the
+        MySQL source distribution. This is what SSL will use to
+        determine if you are communicating with a secure MySQL server.
       </para>
 
       <para>
-        To use Java's 'keytool' to create a truststore in the current
-        directory , and import the server's CA certificate
-        ('cacert.pem'), you can do the following (assuming that'keytool'
-        is in your path. It's located in the 'bin' subdirectory of your
-        JDK or JRE):
+        To use Java's <command>keytool</command> to create a truststore
+        in the current directory , and import the server's CA
+        certificate (<filename>cacert.pem</filename>), you can do the
+        following (assuming that <command>keytool</command> is in your
+        path. The <command>keytool</command> should be located in the
+        <filename>bin</filename> subdirectory of your JDK or JRE):
       </para>
 
 <programlisting>shell&gt; keytool -import -alias mysqlServerCACert -file cacert.pem -keystore truststore

@@ -3894,7 +2990,8 @@
 
       <para>
         Keytool will prompt you for the following information, and
-        create a keystore named 'keystore' in the current directory.
+        create a keystore named <filename>keystore</filename> in the
+        current directory.
       </para>
 
       <para>

@@ -3925,11 +3022,12 @@
       <para>
         Finally, to get JSSE to use the keystore and truststore that you
         have generated, you need to set the following system properties
-        when you start your JVM, replacing 'path_to_keystore_file' with
-        the full path to the keystore file you created,
-        'path_to_truststore_file' with the path to the truststore file
-        you created, and using the appropriate password values for each
-        property.
+        when you start your JVM, replacing
+        <property>path_to_keystore_file</property> with the full path to
+        the keystore file you created,
+        <property>path_to_truststore_file</property> with the path to
+        the truststore file you created, and using the appropriate
+        password values for each property.
       </para>
 
 <programlisting>-Djavax.net.ssl.keyStore=path_to_keystore_file

@@ -3938,11 +3036,13 @@
 -Djavax.net.ssl.trustStorePassword=********* </programlisting>
 
       <para>
-        You will also need to set 'useSSL' to 'true' in your connection
-        parameters for MySQL Connector/J, either by adding 'useSSL=true'
-        to your URL, or by setting the property 'useSSL' to 'true' in
-        the java.util.Properties instance you pass to
-        DriverManager.getConnection().
+        You will also need to set <property>useSSL</property> to
+        <literal>true</literal> in your connection parameters for MySQL
+        Connector/J, either by adding <literal>useSSL=true</literal> to
+        your URL, or by setting the property <property>useSSL</property>
+        to <literal>true</literal> in the
+        <classname>java.util.Properties</classname> instance you pass to
+        <literal>DriverManager.getConnection()</literal>.
       </para>
 
       <para>

@@ -3983,16 +3083,17 @@
 
       <para>
         JSSE provides debugging (to STDOUT) when you set the following
-        system property: -Djavax.net.debug=all This will tell you what
-        keystores and truststores are being used, as well as what is
-        going on during the SSL handshake and certificate exchange. It
-        will be helpful when trying to determine what is not working
-        when trying to get an SSL connection to happen.
+        system property: <literal>-Djavax.net.debug=all</literal> This
+        will tell you what keystores and truststores are being used, as
+        well as what is going on during the SSL handshake and
+        certificate exchange. It will be helpful when trying to
+        determine what is not working when trying to get an SSL
+        connection to happen.
       </para>
 
     </section>
 
-    <section id="cj-replication-connection">
+    <section id="connector-j-reference-replication-connection">
 
       <title>Using Master/Slave Replication with ReplicationConnection</title>
 

@@ -4001,39 +3102,39 @@
         of the driver that will automatically send queries to a
         read/write master, or a failover or round-robin loadbalanced set
         of slaves based on the state of
-        <function>Connection.getReadOnly()</function> .
+        <literal>Connection.getReadOnly()</literal> .
       </para>
 
       <para>
         An application signals that it wants a transaction to be
         read-only by calling
-        <function>Connection.setReadOnly(true)</function>, this
-        <quote>replication-aware</quote> connection will use one of the
-        slave connections, which are load-balanced per-vm using a
-        round-robin scheme (a given connection is <quote>sticky</quote>
-        to a slave unless that slave is removed from service). If you
-        have a write transaction, or if you have a read that is
-        <quote>time-sensitive</quote> (remember, replication in MySQL is
-        asynchronous), set the connection to be not read-only, by
-        calling <function>Connection.setReadOnly(false)</function> and
-        the driver will ensure that further calls are sent to the
-        <quote>master</quote> MySQL server. The driver takes care of
-        propagating the current state of autocommit, isolation level,
-        and catalog between all of the connections that it uses to
-        accomplish this load balancing functionality.
+        <literal>Connection.setReadOnly(true)</literal>, this
+        replication-aware connection will use one of the slave
+        connections, which are load-balanced per-vm using a round-robin
+        scheme (a given connection is sticky to a slave unless that
+        slave is removed from service). If you have a write transaction,
+        or if you have a read that is time-sensitive (remember,
+        replication in MySQL is asynchronous), set the connection to be
+        not read-only, by calling
+        <literal>Connection.setReadOnly(false)</literal> and the driver
+        will ensure that further calls are sent to the master MySQL
+        server. The driver takes care of propagating the current state
+        of autocommit, isolation level, and catalog between all of the
+        connections that it uses to accomplish this load balancing
+        functionality.
       </para>
 
       <para>
         To enable this functionality, use the "
-        <function>com.mysql.jdbc.ReplicationDriver</function> " class
-        when configuring your application server's connection pool or
-        when creating an instance of a JDBC driver for your standalone
+        <literal>com.mysql.jdbc.ReplicationDriver</literal> " class when
+        configuring your application server's connection pool or when
+        creating an instance of a JDBC driver for your standalone
         application. Because it accepts the same URL format as the
-        standard MySQL JDBC driver,
-        <function>ReplicationDriver</function> does not currently work
-        with <function>java.sql.DriverManager</function> -based
-        connection creation unless it is the only MySQL JDBC driver
-        registered with the <function>DriverManager</function> .
+        standard MySQL JDBC driver, <literal>ReplicationDriver</literal>
+        does not currently work with
+        <literal>java.sql.DriverManager</literal> -based connection
+        creation unless it is the only MySQL JDBC driver registered with
+        the <literal>DriverManager</literal> .
       </para>
 
       <para>

@@ -4041,7 +3142,7 @@
         be used in a standalone application.
       </para>
 
-<programlisting id="cj-using-replication-driver-example">import java.sql.Connection;
+<programlisting id="connector-j-using-replication-driver-example">import java.sql.Connection;
 import java.sql.ResultSet;
 import java.util.Properties;
 

@@ -4101,145 +3202,987 @@
 
   </section>
 
-  <section id="cj-j2ee">
+  <section id="connector-j-usagenotes">
 
-    <title>Using Connector/J with J2EE and Other Java Frameworks</title>
+    <title>Connector/J Notes and Tips</title>
 
-    <para>
-      This section describes how to use Connector/J in several contexts.
-    </para>
+    <section id="connector-j-usagenotes-basic">
 
-    <section id="cj-general-j2ee-concepts">
+      <title>Basic JDBC concepts</title>
 
-      <title>General J2EE Concepts</title>
-
       <para>
-        This section provides general background on J2EE concepts that
-        pertain to use of Connector/J.
+        This section provides some general JDBC background.
       </para>
 
-      <section id="cj-connection-pooling">
+      <section id="connector-j-usagenotes-connect-drivermanager">
 
-        <title>Understanding Connection Pooling</title>
+        <title>Connecting to MySQL Using the <literal>DriverManager</literal> Interface</title>
 
         <para>
-          Connection pooling is a technique of creating and managing a
-          pool of connections that are ready for use by any thread that
-          needs them.
+          When you are using JDBC outside of an application server, the
+          <literal>DriverManager</literal> class manages the
+          establishment of Connections.
         </para>
 
         <para>
-          This technique of <quote>pooling</quote> connections is based
-          on the fact that most applications only need a thread to have
-          access to a JDBC connection when they are actively processing
-          a transaction, which usually take only milliseconds to
-          complete. When not processing a transaction, the connection
-          would otherwise sit idle. Instead, connection pooling allows
-          the idle connection to be used by some other thread to do
-          useful work.
+          The <literal>DriverManager</literal> needs to be told which
+          JDBC drivers it should try to make Connections with. The
+          easiest way to do this is to use
+          <literal>Class.forName()</literal> on the class that
+          implements the <literal>java.sql.Driver</literal> interface.
+          With MySQL Connector/J, the name of this class is
+          <literal>com.mysql.jdbc.Driver</literal>. With this method,
+          you could use an external configuration file to supply the
+          driver class name and driver parameters to use when connecting
+          to a database.
         </para>
 
         <para>
-          In practice, when a thread needs to do work against a MySQL or
-          other database with JDBC, it requests a connection from the
-          pool. When the thread is finished using the connection, it
-          returns it to the pool, so that it may be used by any other
-          threads that want to use it.
+          The following section of Java code shows how you might
+          register MySQL Connector/J from the <literal>main()</literal>
+          method of your application:
         </para>
 
+<programlisting>import java.sql.Connection;
+import java.sql.DriverManager;
+import java.sql.SQLException;
+
+// Notice, do not import com.mysql.jdbc.*
+// or you will have problems!
+
+public class LoadDriver {
+    public static void main(String[] args) {
+        try {
+            // The newInstance() call is a work around for some
+            // broken Java implementations
+
+            Class.forName("com.mysql.jdbc.Driver").newInstance();
+        } catch (Exception ex) {
+            // handle the error
+        }
+}</programlisting>
+
         <para>
-          When the connection is <quote>loaned out</quote> from the
-          pool, it is used exclusively by the thread that requested it.
-          From a programming point of view, it is the same as if your
-          thread called DriverManager.getConnection() every time it
-          needed a JDBC connection, however with connection pooling,
-          your thread may end up using either a new, or already-existing
-          connection.
+          After the driver has been registered with the
+          <literal>DriverManager</literal>, you can obtain a
+          <literal>Connection</literal> instance that is connected to a
+          particular database by calling
+          <literal>DriverManager.getConnection()</literal>:
         </para>
 
+        <example id="connector-j-examples-connection-drivermanager">
+
+          <title>Obtaining a Connection From the <literal>DriverManager</literal></title>
+
+          <para>
+            This example shows how you can obtain a
+            <literal>Connection</literal> instance from the
+            <literal>DriverManager</literal>. There are a few different
+            signatures for the <literal>getConnection()</literal>
+            method. You should see the API documentation that comes with
+            your JDK for more specific information on how to use them.
+          </para>
+
+<programlisting>
+import java.sql.Connection;
+import java.sql.DriverManager;
+import java.sql.SQLException;
+
+    ... try {
+            Connection conn = DriverManager.getConnection("jdbc:mysql://localhost/test?user=monty&amp;password=greatsqldb");
+
+            // Do something with the Connection
+
+           ....
+        } catch (SQLException ex) {
+            // handle any errors
+            System.out.println("SQLException: " + ex.getMessage());
+            System.out.println("SQLState: " + ex.getSQLState());
+            System.out.println("VendorError: " + ex.getErrorCode());
+        }
+</programlisting>
+
+          <para>
+            Once a <classname>Connection</classname> is established, it
+            can be used to create <classname>Statement</classname> and
+            <classname>PreparedStatement</classname> objects, as well as
+            retrieve metadata about the database. This is explained in
+            the following sections.
+          </para>
+
+        </example>
+
+      </section>
+
+<!--
+        <section id="connector-j-usagenotes-connect-datasource">
+          <title>Connecting to MySQL Using the <literal>DataSource</literal> Interface;</title>
+
+          <para />
+        </section>
+-->
+
+<!--
+        <section id="connector-j-usagenotes-controlling-transactions">
+          <title>Controlling transactions</title>
+
+          <para />
+        </section>
+-->
+
+      <section id="connector-j-usagenotes-statements">
+
+        <title>Using Statements to Execute SQL</title>
+
         <para>
-          Connection pooling can greatly increase the performance of
-          your Java application, while reducing overall resource usage.
-          The main benefits to connection pooling are:
+          <classname>Statement</classname> objects allow you to execute
+          basic SQL queries and retrieve the results through the
+          <literal>ResultSet</literal> class which is described later.
         </para>
 
-        <itemizedlist>
+        <para>
+          To create a <classname>Statement</classname> instance, you
+          call the <literal>createStatement()</literal> method on the
+          <literal>Connection</literal> object you have retrieved via
+          one of the <literal>DriverManager.getConnection()</literal> or
+          <literal>DataSource.getConnection()</literal> methods
+          described earlier.
+        </para>
 
+        <para>
+          Once you have a <classname>Statement</classname> instance, you
+          can execute a <literal>SELECT</literal> query by calling the
+          <literal>executeQuery(String)</literal> method with the SQL
+          you want to use.
+        </para>
+
+        <para>
+          To update data in the database, use the
+          <literal>executeUpdate(String SQL)</literal> method. This
+          method returns the number of rows affected by the update
+          statement.
+        </para>
+
+        <para>
+          If you don't know ahead of time whether the SQL statement will
+          be a <literal>SELECT</literal> or an
+          <literal>UPDATE</literal>/<literal>INSERT</literal>, then you
+          can use the <literal>execute(String SQL)</literal> method.
+          This method will return true if the SQL query was a
+          <literal>SELECT</literal>, or false if it was an
+          <literal>UPDATE</literal>, <literal>INSERT</literal>, or
+          <literal>DELETE</literal> statement. If the statement was a
+          <literal>SELECT</literal> query, you can retrieve the results
+          by calling the <literal>getResultSet()</literal> method. If
+          the statement was an <literal>UPDATE</literal>,
+          <literal>INSERT</literal>, or <literal>DELETE</literal>
+          statement, you can retrieve the affected rows count by calling
+          <literal>getUpdateCount()</literal> on the
+          <classname>Statement</classname> instance.
+        </para>
+
+        <example id="connector-j-examples-execute-select">
+
+          <title>Using java.sql.Statement to Execute a <literal>SELECT</literal> Query</title>
+
+<programlisting>// assume that conn is an already created JDBC connection
+Statement stmt = null;
+ResultSet rs = null;
+
+try {
+    stmt = conn.createStatement();
+    rs = stmt.executeQuery("SELECT foo FROM bar");
+
+    // or alternatively, if you don't know ahead of time that
+    // the query will be a SELECT...
+
+    if (stmt.execute("SELECT foo FROM bar")) {
+        rs = stmt.getResultSet();
+    }
+
+    // Now do something with the ResultSet ....
+} finally {
+    // it is a good idea to release
+    // resources in a finally{} block
+    // in reverse-order of their creation
+    // if they are no-longer needed
+
+    if (rs != null) {
+        try {
+            rs.close();
+        } catch (SQLException sqlEx) { // ignore }
+
+        rs = null;
+    }
+
+    if (stmt != null) {
+        try {
+            stmt.close();
+        } catch (SQLException sqlEx) { // ignore }
+
+        stmt = null;
+    }
+}</programlisting>
+
+        </example>
+
+      </section>
+
+<!--
+        <section id="connector-j-usagenotes-prepared-statements">
+          <title>Using <literal>PreparedStatements</literal> to Execute SQL</title>
+
+          <para />
+        </section>
+-->
+
+      <section id="connector-j-usagenotes-statements-callable">
+
+        <title>Using <literal>CallableStatements</literal> to Execute Stored Procedures</title>
+
+        <para>
+          Starting with MySQL server version 5.0 when used with
+          Connector/J 3.1.1 or newer, the
+          <classname>java.sql.CallableStatement</classname> interface is
+          fully implemented with the exception of the
+          <literal>getParameterMetaData()</literal> method.
+        </para>
+
+        <para>
+          Connector/J exposes stored procedure functionality through
+          JDBC's <classname>CallableStatement</classname> interface.
+        </para>
+
+        <formalpara>
+
+          <title>Note</title>
+
+          <para>
+            Current versions of MySQL server do not return enough
+            information for the JDBC driver to provide result set
+            metadata for callable statements. This means that when using
+            <literal>CallableStatement</literal>,
+            <literal>ResultSetMetaData</literal> may return
+            <literal>NULL</literal>.
+          </para>
+
+        </formalpara>
+
+        <para>
+          The following example shows a stored procedure that returns
+          the value of <varname>inOutParam</varname> incremented by 1,
+          and the string passed in via <varname>inputParam</varname> as
+          a <classname>ResultSet</classname>:
+
+          <example id="connector-j-examples-stored-procedure">
+
+            <title>Stored Procedures</title>
+
+<programlisting>CREATE PROCEDURE demoSp(IN inputParam VARCHAR(255), INOUT inOutParam INT)
+BEGIN
+    DECLARE z INT;
+    SET z = inOutParam + 1;
+    SET inOutParam = z;
+
+    SELECT inputParam;
+
+    SELECT CONCAT('zyxw', inputParam);
+END</programlisting>
+
+          </example>
+        </para>
+
+        <para>
+          To use the <literal>demoSp</literal> procedure with
+          Connector/J, follow these steps:
+        </para>
+
+        <orderedlist>
+
           <listitem>
             <para>
-              Reduced connection creation time
+              Prepare the callable statement by using
+              <literal>Connection.prepareCall()</literal> .
             </para>
 
             <para>
-              Although this is not usually an issue with the quick
-              connection setup that MySQL offers compared to other
-              databases, creating new JDBC connections still incurs
-              networking and JDBC driver overhead that will be avoided
-              if connections are <quote>recycled.</quote>
+              Notice that you have to use JDBC escape syntax, and that
+              the parentheses surrounding the parameter placeholders are
+              not optional:
             </para>
+
+            <example id="connector-j-examples-preparecall">
+
+              <title>Using <literal>Connection.prepareCall()</literal></title>
+
+<programlisting>import java.sql.CallableStatement;
+
+...
+
+    //
+    // Prepare a call to the stored procedure 'demoSp'
+    // with two parameters
+    //
+    // Notice the use of JDBC-escape syntax ({call ...})
+    //
+
+    CallableStatement cStmt = conn.prepareCall("{call demoSp(?, ?)}");
+
+
+
+    cStmt.setString(1, "abcdefg");</programlisting>
+
+            </example>
+
+            <formalpara>
+
+              <title>Note</title>
+
+              <para>
+                <literal>Connection.prepareCall()</literal> is an
+                expensive method, due to the metadata retrieval that the
+                driver performs to support output parameters. For
+                performance reasons, you should try to minimize
+                unnecessary calls to
+                <literal>Connection.prepareCall()</literal> by reusing
+                <classname>CallableStatement</classname> instances in
+                your code.
+              </para>
+
+            </formalpara>
           </listitem>
 
           <listitem>
             <para>
-              Simplified programming model
+              Register the output parameters (if any exist)
             </para>
 
             <para>
-              When using connection pooling, each individual thread can
-              act as though it has created its own JDBC connection,
-              allowing you to use straight-forward JDBC programming
-              techniques.
+              To retrieve the values of output parameters (parameters
+              specified as <literal>OUT</literal> or
+              <literal>INOUT</literal> when you created the stored
+              procedure), JDBC requires that they be specified before
+              statement execution using the various
+              <literal>registerOutputParameter()</literal> methods in
+              the <classname>CallableStatement</classname> interface:
+
+              <example id="connector-j-examples-output-param">
+
+                <title>Registering Output Parameters</title>
+
+<programlisting>
+import java.sql.Types;
+...
+//
+// Connector/J supports both named and indexed
+// output parameters. You can register output
+// parameters using either method, as well
+// as retrieve output parameters using either
+// method, regardless of what method was
+// used to register them.
+//
+// The following examples show how to use
+// the various methods of registering
+// output parameters (you should of course
+// use only one registration per parameter).
+//
+
+//
+// Registers the second parameter as output, and
+// uses the type 'INTEGER' for values returned from
+// getObject()
+//
+
+cStmt.registerOutParameter(2, Types.INTEGER);
+
+//
+// Registers the named parameter 'inOutParam', and
+// uses the type 'INTEGER' for values returned from
+// getObject()
+//
+
+cStmt.registerOutParameter("inOutParam", Types.INTEGER);
+...
+</programlisting>
+
+              </example>
             </para>
           </listitem>
 
           <listitem>
             <para>
-              Controlled resource usage
+              Set the input parameters (if any exist)
             </para>
 
             <para>
-              If you don't use connection pooling, and instead create a
-              new connection every time a thread needs one, your
-              application's resource usage can be quite wasteful and
-              lead to unpredictable behavior under load.
+              Input and in/out parameters are set as for
+              <classname>PreparedStatement</classname> objects. However,
+              <classname>CallableStatement</classname> also supports
+              setting parameters by name:
+
+              <example id="connector-j-examples-callablestatement">
+
+                <title>Setting <literal>CallableStatement</literal> Input Parameters</title>
+
+<programlisting>...
+
+    //
+    // Set a parameter by index
+    //
+
+    cStmt.setString(1, "abcdefg");
+
+    //
+    // Alternatively, set a parameter using
+    // the parameter name
+    //
+
+    cStmt.setString("inputParameter", "abcdefg");
+
+    //
+    // Set the 'in/out' parameter using an index
+    //
+
+    cStmt.setInt(2, 1);
+
+    //
+    // Alternatively, set the 'in/out' parameter
+    // by name
+    //
+
+    cStmt.setInt("inOutParam", 1);
+
+...</programlisting>
+
+              </example>
             </para>
           </listitem>
 
-        </itemizedlist>
+          <listitem>
+            <para>
+              Execute the <classname>CallableStatement</classname>, and
+              retrieve any result sets or output parameters.
+            </para>
 
+            <para>
+              Although <classname>CallableStatement</classname> supports
+              calling any of the <classname>Statement</classname>
+              execute methods (<literal>executeUpdate()</literal>,
+              <literal>executeQuery()</literal> or
+              <literal>execute()</literal>), the most flexible method to
+              call is <literal>execute()</literal>, as you do not need
+              to know ahead of time if the stored procedure returns
+              result sets:
+
+              <example id="connector-j-examples-retrieving-results-params">
+
+                <title>Retrieving Results and Output Parameter Values</title>
+
+<programlisting>...
+
+    boolean hadResults = cStmt.execute();
+
+    //
+    // Process all returned result sets
+    //
+
+    while (hadResults) {
+        ResultSet rs = cStmt.getResultSet();
+
+        // process result set
+        ...
+
+        hadResults = rs.getMoreResults();
+    }
+
+    //
+    // Retrieve output parameters
+    //
+    // Connector/J supports both index-based and
+    // name-based retrieval
+    //
+
+    int outputValue = rs.getInt(2); // index-based
+
+    outputValue = rs.getInt("inOutParam"); // name-based
+
+...</programlisting>
+
+              </example>
+            </para>
+          </listitem>
+
+        </orderedlist>
+
+      </section>
+
+      <section id="connector-j-usagenotes-last-insert-id">
+
+        <title>Retrieving <literal>AUTO_INCREMENT</literal> Column Values</title>
+
         <para>
-          Remember that each connection to MySQL has overhead (memory,
-          CPU, context switches, and so forth) on both the client and
-          server side. Every connection limits how many resources there
-          are available to your application as well as the MySQL server.
-          Many of these resources will be used whether or not the
-          connection is actually doing any useful work!
-        </para>
+          Before version 3.0 of the JDBC API, there was no standard way
+          of retrieving key values from databases that supported auto
+          increment or identity columns. With older JDBC drivers for
+          MySQL, you could always use a MySQL-specific method on the
+          <classname>Statement</classname> interface, or issue the query
+          <literal>SELECT LAST_INSERT_ID()</literal> after issuing an
+          <literal>INSERT</literal> to a table that had an
+          <literal>AUTO_INCREMENT</literal> key. Using the
+          MySQL-specific method call isn't portable, and issuing a
+          <literal>SELECT</literal> to get the
+          <literal>AUTO_INCREMENT</literal> key's value requires another
+          round-trip to the database, which isn't as efficient as
+          possible. The following code snippets demonstrate the three
+          different ways to retrieve <literal>AUTO_INCREMENT</literal>
+          values. First, we demonstrate the use of the new JDBC-3.0
+          method <literal>getGeneratedKeys()</literal> which is now the
+          preferred method to use if you need to retrieve
+          <literal>AUTO_INCREMENT</literal> keys and have access to
+          JDBC-3.0. The second example shows how you can retrieve the
+          same value using a standard <literal>SELECT
+          LAST_INSERT_ID()</literal> query. The final example shows how
+          updatable result sets can retrieve the
+          <literal>AUTO_INCREMENT</literal> value when using the
+          <literal>insertRow()</literal> method.
 
-        <para>
-          Connection pools can be tuned to maximize performance, while
-          keeping resource utilization below the point where your
-          application will start to fail rather than just run slower.
+          <example id="connector-j-examples-autoincrement-getgeneratedkeys">
+
+            <title>Retrieving <literal>AUTO_INCREMENT</literal> Column Values using
+              <literal>Statement.getGeneratedKeys()</literal></title>
+
+<programlisting>   Statement stmt = null;
+   ResultSet rs = null;
+
+   try {
+
+    //
+    // Create a Statement instance that we can use for
+    // 'normal' result sets assuming you have a
+    // Connection 'conn' to a MySQL database already
+    // available
+
+    stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY,
+                                java.sql.ResultSet.CONCUR_UPDATABLE);
+
+    //
+    // Issue the DDL queries for the table for this example
+    //
+
+    stmt.executeUpdate("DROP TABLE IF EXISTS autoIncTutorial");
+    stmt.executeUpdate(
+            "CREATE TABLE autoIncTutorial ("
+            + "priKey INT NOT NULL AUTO_INCREMENT, "
+            + "dataField VARCHAR(64), PRIMARY KEY (priKey))");
+
+    //
+    // Insert one row that will generate an AUTO INCREMENT
+    // key in the 'priKey' field
+    //
+
+    stmt.executeUpdate(
+            "INSERT INTO autoIncTutorial (dataField) "
+            + "values ('Can I Get the Auto Increment Field?')",
+            Statement.RETURN_GENERATED_KEYS);
+
+    //
+    // Example of using Statement.getGeneratedKeys()
+    // to retrieve the value of an auto-increment
+    // value
+    //
+
+    int autoIncKeyFromApi = -1;
+
+    rs = stmt.getGeneratedKeys();
+
+    if (rs.next()) {
+        autoIncKeyFromApi = rs.getInt(1);
+    } else {
+
+        // throw an exception from here
+    }
+
+    rs.close();
+
+    rs = null;
+
+    System.out.println("Key returned from getGeneratedKeys():"
+        + autoIncKeyFromApi);
+} finally {
+
+    if (rs != null) {
+        try {
+            rs.close();
+        } catch (SQLException ex) {
+            // ignore
+        }
+    }
+
+    if (stmt != null) {
+        try {
+            stmt.close();
+        } catch (SQLException ex) {
+            // ignore
+        }
+    }
+}
+</programlisting>
+
+          </example>
+
+          <example id="connector-j-examples-autoincrement-select">
+
+            <title>Retrieving <literal>AUTO_INCREMENT</literal> Column Values using
+              <literal>SELECT LAST_INSERT_ID()</literal></title>
+
+<programlisting>   Statement stmt = null;
+   ResultSet rs = null;
+
+   try {
+
+    //
+    // Create a Statement instance that we can use for
+    // 'normal' result sets.
+
+    stmt = conn.createStatement();
+
+    //
+    // Issue the DDL queries for the table for this example
+    //
+
+    stmt.executeUpdate("DROP TABLE IF EXISTS autoIncTutorial");
+    stmt.executeUpdate(
+            "CREATE TABLE autoIncTutorial ("
+            + "priKey INT NOT NULL AUTO_INCREMENT, "
+            + "dataField VARCHAR(64), PRIMARY KEY (priKey))");
+
+    //
+    // Insert one row that will generate an AUTO INCREMENT
+    // key in the 'priKey' field
+    //
+
+    stmt.executeUpdate(
+            "INSERT INTO autoIncTutorial (dataField) "
+            + "values ('Can I Get the Auto Increment Field?')");
+
+    //
+    // Use the MySQL LAST_INSERT_ID()
+    // function to do the same thing as getGeneratedKeys()
+    //
+
+    int autoIncKeyFromFunc = -1;
+    rs = stmt.executeQuery("SELECT LAST_INSERT_ID()");
+
+    if (rs.next()) {
+        autoIncKeyFromFunc = rs.getInt(1);
+    } else {
+        // throw an exception from here
+    }
+
+    rs.close();
+
+    System.out.println("Key returned from " + "'SELECT LAST_INSERT_ID()': "
+        + autoIncKeyFromFunc);
+
+} finally {
+
+    if (rs != null) {
+        try {
+            rs.close();
+        } catch (SQLException ex) {
+            // ignore
+        }
+    }
+
+    if (stmt != null) {
+        try {
+            stmt.close();
+        } catch (SQLException ex) {
+            // ignore
+        }
+    }
+}
+   </programlisting>
+
+          </example>
+
+          <example id="connector-j-examples-autoincrement-updateable-resultsets">
+
+            <title>Retrieving <literal>AUTO_INCREMENT</literal> Column Values in
+              <literal>Updatable ResultSets</literal></title>
+
+<programlisting>   Statement stmt = null;
+   ResultSet rs = null;
+
+   try {
+
+    //
+    // Create a Statement instance that we can use for
+    // 'normal' result sets as well as an 'updatable'
+    // one, assuming you have a Connection 'conn' to
+    // a MySQL database already available
+    //
+
+    stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY,
+                                java.sql.ResultSet.CONCUR_UPDATABLE);
+
+    //
+    // Issue the DDL queries for the table for this example
+    //
+
+    stmt.executeUpdate("DROP TABLE IF EXISTS autoIncTutorial");
+    stmt.executeUpdate(
+            "CREATE TABLE autoIncTutorial ("
+            + "priKey INT NOT NULL AUTO_INCREMENT, "
+            + "dataField VARCHAR(64), PRIMARY KEY (priKey))");
+
+    //
+    // Example of retrieving an AUTO INCREMENT key
+    // from an updatable result set
+    //
+
+    rs = stmt.executeQuery("SELECT priKey, dataField "
+       + "FROM autoIncTutorial");
+
+    rs.moveToInsertRow();
+
+    rs.updateString("dataField", "AUTO INCREMENT here?");
+    rs.insertRow();
+
+    //
+    // the driver adds rows at the end
+    //
+
+    rs.last();
+
+    //
+    // We should now be on the row we just inserted
+    //
+
+    int autoIncKeyFromRS = rs.getInt("priKey");
+
+    rs.close();
+
+    rs = null;
+
+    System.out.println("Key returned for inserted row: "
+        + autoIncKeyFromRS);
+
+} finally {
+
+    if (rs != null) {
+        try {
+            rs.close();
+        } catch (SQLException ex) {
+            // ignore
+        }
+    }
+
+    if (stmt != null) {
+        try {
+            stmt.close();
+        } catch (SQLException ex) {
+            // ignore
+        }
+    }
+}
+
+
+   </programlisting>
+
+          </example>
+
+          When you run the preceding example code, you should get the
+          following output: Key returned from
+          <literal>getGeneratedKeys()</literal>: 1 Key returned from
+          <literal>SELECT LAST_INSERT_ID()</literal>: 1 Key returned for
+          inserted row: 2 You should be aware, that at times, it can be
+          tricky to use the <literal>SELECT LAST_INSERT_ID()</literal>
+          query, as that function's value is scoped to a connection. So,
+          if some other query happens on the same connection, the value
+          will be overwritten. On the other hand, the
+          <literal>getGeneratedKeys()</literal> method is scoped by the
+          <classname>Statement</classname> instance, so it can be used
+          even if other queries happen on the same connection, but not
+          on the same <classname>Statement</classname> instance.
         </para>
 
+      </section>
+
+<!--
+        <section id="connector-j-usagenotes-multiresults">
+          <title>Retrieving Multiple <literal>ResultSets</literal> from a <literal>Statement</literal> or <literal>CallableStatement</literal></title>
+
+          <para />
+        </section>
+-->
+
+<!--
+        <section id="connector-j-usagenotes-result-set-metadata">
+          <title>Using <literal>ResultSetMetaData</literal> to Retrieve Information about a <literal>ResultSet</literal></title>
+
+          <para />
+        </section>
+-->
+
+<!--
+        <section id="connector-j-usagenotes-database-metadata">
+          <title>Using <literal>DatabaseMetaData</literal> to Retrieve Information about a Database</title>
+
+          <para />
+        </section>
+-->
+
+<!--
+        <section id="connector-j-usagenotes-lobs">
+          <title>Working with <literal>BLOB</literal> and <literal>CLOB</literal> Values</title>
+
+          <para />
+        </section>
+-->
+
+    </section>
+
+    <section id="connector-j-usagenotes-j2ee">
+
+      <title>Using Connector/J with J2EE and Other Java Frameworks</title>
+
+      <para>
+        This section describes how to use Connector/J in several
+        contexts.
+      </para>
+
+      <section id="connector-j-usagenotes-j2ee-concepts">
+
+        <title>General J2EE Concepts</title>
+
         <para>
-          Luckily, Sun has standardized the concept of connection
-          pooling in JDBC through the JDBC-2.0 "Optional" interfaces,
-          and all major application servers have implementations of
-          these APIs that work fine with MySQL Connector/J.
+          This section provides general background on J2EE concepts that
+          pertain to use of Connector/J.
         </para>
 
-        <para>
-          Generally, you configure a connection pool in your application
-          server configuration files, and access it via the Java Naming
-          and Directory Interface (JNDI). The following code shows how
-          you might use a connection pool from an application deployed
-          in a J2EE application server:
+        <section id="connector-j-usagenotes-j2ee-concepts-connection-pooling">
 
-          <example>
+          <title>Understanding Connection Pooling</title>
 
-            <title>Using a Connection Pool with a J2EE Application Server</title>
+          <para>
+            Connection pooling is a technique of creating and managing a
+            pool of connections that are ready for use by any thread
+            that needs them.
+          </para>
 
+          <para>
+            This technique of pooling connections is based on the fact
+            that most applications only need a thread to have access to
+            a JDBC connection when they are actively processing a
+            transaction, which usually take only milliseconds to
+            complete. When not processing a transaction, the connection
+            would otherwise sit idle. Instead, connection pooling allows
+            the idle connection to be used by some other thread to do
+            useful work.
+          </para>
+
+          <para>
+            In practice, when a thread needs to do work against a MySQL
+            or other database with JDBC, it requests a connection from
+            the pool. When the thread is finished using the connection,
+            it returns it to the pool, so that it may be used by any
+            other threads that want to use it.
+          </para>
+
+          <para>
+            When the connection is loaned out from the pool, it is used
+            exclusively by the thread that requested it. From a
+            programming point of view, it is the same as if your thread
+            called <literal>DriverManager.getConnection()</literal>
+            every time it needed a JDBC connection, however with
+            connection pooling, your thread may end up using either a
+            new, or already-existing connection.
+          </para>
+
+          <para>
+            Connection pooling can greatly increase the performance of
+            your Java application, while reducing overall resource
+            usage. The main benefits to connection pooling are:
+          </para>
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                Reduced connection creation time
+              </para>
+
+              <para>
+                Although this is not usually an issue with the quick
+                connection setup that MySQL offers compared to other
+                databases, creating new JDBC connections still incurs
+                networking and JDBC driver overhead that will be avoided
+                if connections are recycled.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                Simplified programming model
+              </para>
+
+              <para>
+                When using connection pooling, each individual thread
+                can act as though it has created its own JDBC
+                connection, allowing you to use straight-forward JDBC
+                programming techniques.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                Controlled resource usage
+              </para>
+
+              <para>
+                If you don't use connection pooling, and instead create
+                a new connection every time a thread needs one, your
+                application's resource usage can be quite wasteful and
+                lead to unpredictable behavior under load.
+              </para>
+            </listitem>
+
+          </itemizedlist>
+
+          <para>
+            Remember that each connection to MySQL has overhead (memory,
+            CPU, context switches, and so forth) on both the client and
+            server side. Every connection limits how many resources
+            there are available to your application as well as the MySQL
+            server. Many of these resources will be used whether or not
+            the connection is actually doing any useful work!
+          </para>
+
+          <para>
+            Connection pools can be tuned to maximize performance, while
+            keeping resource utilization below the point where your
+            application will start to fail rather than just run slower.
+          </para>
+
+          <para>
+            Luckily, Sun has standardized the concept of connection
+            pooling in JDBC through the JDBC-2.0 Optional interfaces,
+            and all major application servers have implementations of
+            these APIs that work fine with MySQL Connector/J.
+          </para>
+
+          <para>
+            Generally, you configure a connection pool in your
+            application server configuration files, and access it via
+            the Java Naming and Directory Interface (JNDI). The
+            following code shows how you might use a connection pool
+            from an application deployed in a J2EE application server:
+
+            <example id="connector-j-examples-connectionpool-j2ee">
+
+              <title>Using a Connection Pool with a J2EE Application Server</title>
+
 <programlisting>import java.sql.Connection;
 import java.sql.SQLException;
 import java.sql.Statement;

@@ -4335,91 +4278,96 @@
     }
 }</programlisting>
 
-          </example>
+            </example>
 
-          As shown in the example above, after obtaining the JNDI
-          InitialContext, and looking up the DataSource, the rest of the
-          code should look familiar to anyone who has done JDBC
-          programming in the past.
-        </para>
+            As shown in the example above, after obtaining the JNDI
+            InitialContext, and looking up the DataSource, the rest of
+            the code should look familiar to anyone who has done JDBC
+            programming in the past.
+          </para>
 
-        <para>
-          The most important thing to remember when using connection
-          pooling is to make sure that no matter what happens in your
-          code (exceptions, flow-of-control, and so forth), connections,
-          and anything created by them (such as statements or result
-          sets) are closed, so that they may be re-used, otherwise they
-          will be <quote>stranded,</quote> which in the best case means
-          that the MySQL server resources they represent (such as
-          buffers, locks, or sockets) may be tied up for some time, or
-          worst case, may be tied up forever.
-        </para>
+          <para>
+            The most important thing to remember when using connection
+            pooling is to make sure that no matter what happens in your
+            code (exceptions, flow-of-control, and so forth),
+            connections, and anything created by them (such as
+            statements or result sets) are closed, so that they may be
+            re-used, otherwise they will be stranded, which in the best
+            case means that the MySQL server resources they represent
+            (such as buffers, locks, or sockets) may be tied up for some
+            time, or worst case, may be tied up forever.
+          </para>
 
-        <para>
-          What's the Best Size for my Connection Pool?
-        </para>
+          <para>
+            What's the Best Size for my Connection Pool?
+          </para>
 
-        <para>
-          As with all other configuration rules-of-thumb, the answer is
-          <quote>It depends.</quote> Although the optimal size depends
-          on anticipated load and average database transaction time, the
-          optimum connection pool size is smaller than you might expect.
-          If you take Sun's Java Petstore blueprint application for
-          example, a connection pool of 15-20 connections can serve a
-          relatively moderate load (600 concurrent users) using MySQL
-          and Tomcat with response times that are acceptable.
-        </para>
+          <para>
+            As with all other configuration rules-of-thumb, the answer
+            is: it depends. Although the optimal size depends on
+            anticipated load and average database transaction time, the
+            optimum connection pool size is smaller than you might
+            expect. If you take Sun's Java Petstore blueprint
+            application for example, a connection pool of 15-20
+            connections can serve a relatively moderate load (600
+            concurrent users) using MySQL and Tomcat with response times
+            that are acceptable.
+          </para>
 
-        <para>
-          To correctly size a connection pool for your application, you
-          should create load test scripts with tools such as Apache
-          JMeter or The Grinder, and load test your application.
-        </para>
+          <para>
+            To correctly size a connection pool for your application,
+            you should create load test scripts with tools such as
+            Apache JMeter or The Grinder, and load test your
+            application.
+          </para>
 
-        <para>
-          An easy way to determine a starting point is to configure your
-          connection pool's maximum number of connections to be
-          <quote>unbounded,</quote> run a load test, and measure the
-          largest amount of concurrently used connections. You can then
-          work backward from there to determine what values of minimum
-          and maximum pooled connections give the best performance for
-          your particular application.
-        </para>
+          <para>
+            An easy way to determine a starting point is to configure
+            your connection pool's maximum number of connections to be
+            unbounded, run a load test, and measure the largest amount
+            of concurrently used connections. You can then work backward
+            from there to determine what values of minimum and maximum
+            pooled connections give the best performance for your
+            particular application.
+          </para>
 
-      </section>
+        </section>
 
 <!--
-        <section id="cj-understanding-transactions">
+        <section id="connector-j-usagenotes-j2ee-concepts-transactions">
           <title>Understanding Transactions</title>
 
           <para />
         </section>
 -->
 
-    </section>
+      </section>
 
-    <section id="cj-tomcat-config">
+      <section id="connector-j-usagenotes-tomcat">
 
-      <title>Using Connector/J with Tomcat</title>
+        <title>Using Connector/J with Tomcat</title>
 
-      <para>
-        The following instructions are based on the instructions for
-        Tomcat-5.x, available at
-        <ulink url="http://jakarta.apache.org/tomcat/tomcat-5.0-doc/jndi-datasource-examples-howto.html"/>
-        which is current at the time this document was written.
-      </para>
+        <para>
+          The following instructions are based on the instructions for
+          Tomcat-5.x, available at
+          <ulink
+            url="http://jakarta.apache.org/tomcat/tomcat-5.0-doc/jndi-datasource-examples-howto.html"
+          />
+          which is current at the time this document was written.
+        </para>
 
-      <para>
-        First, install the .jar file that comes with Connector/J in
-        <filename>$CATALINA_HOME/common/lib</filename> so that it is
-        available to all applications installed in the container.
-      </para>
+        <para>
+          First, install the .jar file that comes with Connector/J in
+          <filename>$CATALINA_HOME/common/lib</filename> so that it is
+          available to all applications installed in the container.
+        </para>
 
-      <para>
-        Next, Configure the JNDI DataSource by adding a declaration
-        resource to <filename>$CATALINA_HOME/conf/server.xml</filename>
-        in the context that defines your web application:
-      </para>
+        <para>
+          Next, Configure the JNDI DataSource by adding a declaration
+          resource to
+          <filename>$CATALINA_HOME/conf/server.xml</filename> in the
+          context that defines your web application:
+        </para>
 
 <programlisting>&lt;Context ....&gt;
 

@@ -4547,35 +4495,36 @@
   &lt;/ResourceParams&gt;
 &lt;/Context&gt;</programlisting>
 
-      <para>
-        In general, you should follow the installation instructions that
-        come with your version of Tomcat, as the way you configure
-        datasources in Tomcat changes from time-to-time, and
-        unfortunately if you use the wrong syntax in your XML file, you
-        will most likely end up with an exception similar to the
-        following:
-      </para>
+        <para>
+          In general, you should follow the installation instructions
+          that come with your version of Tomcat, as the way you
+          configure datasources in Tomcat changes from time-to-time, and
+          unfortunately if you use the wrong syntax in your XML file,
+          you will most likely end up with an exception similar to the
+          following:
+        </para>
 
 <programlisting>Error: java.sql.SQLException: Cannot load JDBC driver class 'null ' SQL
 state: null </programlisting>
 
-    </section>
+      </section>
 
-    <section id="cj-jboss-config">
+      <section id="connector-j-usagenotes-jboss">
 
-      <title>Using Connector/J with JBoss</title>
+        <title>Using Connector/J with JBoss</title>
 
-      <para>
-        These instructions cover JBoss-4.x. To make the JDBC driver
-        classes available to the application server, copy the .jar file
-        that comes with Connector/J to the <filename>lib</filename>
-        directory for your server configuration (which is usually called
-        "<filename>default</filename>"). Then, in the same configuration
-        directory, in the subdirectory named <quote>deploy,</quote>
-        create a datasource configuration file that ends with "-ds.xml",
-        which tells JBoss to deploy this file as a JDBC Datasource. The
-        file should have the following contents:
-      </para>
+        <para>
+          These instructions cover JBoss-4.x. To make the JDBC driver
+          classes available to the application server, copy the .jar
+          file that comes with Connector/J to the
+          <filename>lib</filename> directory for your server
+          configuration (which is usually called
+          <filename>default</filename>). Then, in the same configuration
+          directory, in the subdirectory named deploy, create a
+          datasource configuration file that ends with "-ds.xml", which
+          tells JBoss to deploy this file as a JDBC Datasource. The file
+          should have the following contents:
+        </para>
 
 <programlisting>&lt;datasources&gt;
     &lt;local-tx-datasource&gt;

@@ -4614,10 +4563,10 @@
     &lt;/local-tx-datasource&gt;
 &lt;/datasources&gt; </programlisting>
 
-    </section>
+      </section>
 
 <!--
-      <section id="cj-hibernate-config">
+      <section id="connector-j-usagenotes-hibernate-config">
         <title>Using Connector/J with Hibernate</title>
 
         <para></para>

@@ -4625,7 +4574,7 @@
 -->
 
 <!--
-      <section id="cj-spring-config">
+      <section id="connector-j-usagenotes-spring-config">
         <title>Using Connector/J with Spring</title>
 
         <para />

@@ -4633,7 +4582,7 @@
 -->
 
 <!--
-      <section id="cj-struts-config">
+      <section id="connector-j-usagenotes-struts-config">
         <title>Using Connector/J with Struts</title>
 
         <para />

@@ -4642,7 +4591,7 @@
 -->
 
 <!--
-      <section id="cj-weblogic-config">
+      <section id="connector-j-usagenotes-weblogic-config">
         <title>Using Connector/J with BEA WebLogic</title>
 
         <para />

@@ -4650,7 +4599,7 @@
 -->
 
 <!--
-      <section id="cj-websphere-config">
+      <section id="connector-j-usagenotes-websphere-config">
         <title>Using Connector/J with IBM WebSphere</title>
 
         <para />

@@ -4658,26 +4607,17 @@
 -->
 
 <!--
-      <section id="cj-ias-config">
+      <section id="connector-j-usagenotes-ias-config">
         <title>Using Connector/J with Oracle Application Server</title>
 
         <para />
       </section>
 -->
 
-  </section>
+    </section>
 
-  <section id="cj-troubleshooting">
+    <section id="connector-j-usagenotes-troubleshooting">
 
-    <title>Diagnosing Connector/J Problems</title>
-
-    <para>
-      This section describes how to solve problems that you may
-      encounter when using Connector/J.
-    </para>
-
-    <section id="cj-faq">
-
       <title>Common Problems and Solutions</title>
 
       <para>

@@ -4697,9 +4637,9 @@
               Connector/J, I get the following exception:
             </para>
 
-            <screen>SQLException: Server configuration denies access to data source
+<programlisting>SQLException: Server configuration denies access to data source
 SQLState: 08001
-VendorError: 0</screen>
+VendorError: 0</programlisting>
 
             <para>
               What's going on? I can connect just fine with the MySQL

@@ -4719,32 +4659,16 @@
             </para>
 
             <para>
-              You must add grants to allow this to happen. The following
-              is an example of how to do this (but not the most secure).
+              You must add the necessary security credentials to the
+              MySQL server for this to happen, using the
+              <literal>GRANT</literal> statement to your MySQL Server.
+              See <xref linkend="grant"/>, for more information.
             </para>
 
-            <para>
-              From the mysql command-line client, logged in as a user
-              that can grant privileges, issue the following command:
-            </para>
+            <formalpara>
 
-            <screen>GRANT ALL PRIVILEGES ON [dbname].* to
-                '[user]'@'[hostname]' identified by
-                '[password]'</screen>
+              <title>Note</title>
 
-            <para>
-              replacing [dbname] with the name of your database, [user]
-              with the user name, [hostname] with the host that MySQL
-              Connector/J will be connecting from, and [password] with
-              the password you want to use. Be aware that RedHat Linux
-              is broken with respect to the hostname portion for the
-              case when you are connecting from localhost. You need to
-              use "localhost.localdomain" for the [hostname] value in
-              this case. Follow this by issuing the "FLUSH PRIVILEGES"
-              command.
-            </para>
-
-            <note>
               <para>
                 Testing your connectivity with the
                 <command>mysql</command> command-line client will not

@@ -4757,26 +4681,21 @@
                 connectivity to <literal>localhost</literal>, use
                 <literal>127.0.0.1</literal> as the hostname instead.
               </para>
-            </note>
 
-            <warning>
-              <para>
-                If you don't understand what the 'GRANT' command does,
-                or how it works, you should read and understand the
-                <ulink
-              url="http://www.mysql.com/doc/en/Privilege_system.html">'General
-                Security Issues and the MySQL Access Privilege
-                System'</ulink> section of the MySQL manual before
-                attempting to change privileges.
-              </para>
+            </formalpara>
 
+            <formalpara>
+
+              <title>Warning</title>
+
               <para>
                 Changing privileges and permissions improperly in MySQL
                 can potentially cause your server installation to not
                 have optimal security properties.
               </para>
-            </warning>
 
+            </formalpara>
+
           </answer>
 
         </qandaentry>

@@ -4795,11 +4714,38 @@
           <answer>
 
             <para>
-              One of two things are happening. Either the driver is not
-              in your CLASSPATH or your URL format is incorrect (see the
-              <xref linkend="cj-installing"/> section.).
+              There are three possible causes for this error:
             </para>
 
+            <itemizedlist>
+
+              <listitem>
+                <para>
+                  The Connector/J driver is not in your
+                  <literal>CLASSPATH</literal>, see
+                  <xref
+                linkend="connector-j-installing"/>.
+                </para>
+              </listitem>
+
+              <listitem>
+                <para>
+                  The format of your connection URL is incorrect, or you
+                  are referencing the wrong JDBC driver.
+                </para>
+              </listitem>
+
+              <listitem>
+                <para>
+                  When using DriverManager, the
+                  <literal>jdbc.drivers</literal> system property has
+                  not been populated with the location of the
+                  Connector/J driver.
+                </para>
+              </listitem>
+
+            </itemizedlist>
+
           </answer>
 
         </qandaentry>

@@ -4813,13 +4759,13 @@
               application and I get an exception similar to:
             </para>
 
-            <screen>SQLException: Cannot connect to MySQL server on host:3306.
+<programlisting>SQLException: Cannot connect to MySQL server on host:3306.
 Is there a MySQL server running on the machine/port you
 are trying to connect to?
 
 (java.security.AccessControlException)
 SQLState: 08S01
-VendorError: 0 </screen>
+VendorError: 0 </programlisting>
 
           </question>
 

@@ -4886,7 +4832,8 @@
               MySQL closes connections after 8 hours of inactivity. You
               either need to use a connection pool that handles stale
               connections or use the "autoReconnect" parameter (see
-              <xref linkend="cj-configuration-properties"/>).
+              <xref
+                linkend="connector-j-reference-configuration-properties"/>).
             </para>
 
             <para>

@@ -4894,7 +4841,8 @@
               application and dealing with them, rather than propagating
               them all the way until your application exits, this is
               just good programming practice. MySQL Connector/J will set
-              the SQLState (see java.sql.SQLException.getSQLState() in
+              the SQLState (see
+              <literal>java.sql.SQLException.getSQLState()</literal> in
               your APIDOCS) to "08S01" when it encounters
               network-connectivity issues during the processing of a
               query. Your application code should then attempt to

@@ -4907,7 +4855,7 @@
             </para>
 
             <para>
-              <example>
+              <example id="connector-j-examples-transaction-retry">
 
                 <title>Example of transaction with retry logic</title>
 

@@ -5034,6 +4982,24 @@
               </example>
             </para>
 
+            <formalpara>
+
+              <title>Note</title>
+
+              <para>
+                Use of the <option>autoReconnect</option> option is not
+                recommended because there is no safe method of
+                reconnecting to the MySQL server without risking some
+                corruption of the connection state or database state
+                information. Instead, you should use a connection pool
+                which will enable your application to connect to the
+                MySQL server using an available connection from the
+                pool. The <option>autoReconnect</option> facility is
+                deprecated, and may be removed in a future release.
+              </para>
+
+            </formalpara>
+
           </answer>
 
         </qandaentry>

@@ -5069,30 +5035,70 @@
     </section>
 
 <!--
-      <section id="cj-tracing">
+      <section id="connector-j-usagenotes-tracing">
         <title>Enabling Tracing Options</title>
 
         <para></para>
       </section>
 -->
 
-    <section id="cj-reporting-bugs">
+  </section>
 
+  <section id="connector-j-support">
+
+    <title>Connector/J Support</title>
+
+    <section id="connector-j-support-community">
+
+      <title>Connector/J Community Support</title>
+
+      <para>
+        MySQL AB provides assistance to the user community by means of
+        its mailing lists. For Connector/J related issues, you can get
+        help from experienced users by using the MySQL and Java mailing
+        list. Archives and subscription information is available online
+        at <ulink
+          url="http://lists.mysql.com/java"/>.
+      </para>
+
+      <para>
+        For information about subscribing to MySQL mailing lists or to
+        browse list archives, visit
+        <ulink url="http://lists.mysql.com/"/>. See
+        <xref linkend="mailing-lists"/>.
+      </para>
+
+      <para>
+        Community support from experienced users is also available
+        through the
+        <ulink url="http://forums.mysql.com/list.php?39">JDBC
+        Forum</ulink>. You may also find help from other users in the
+        other MySQL Forums, located at
+        <ulink url="http://forums.mysql.com"/>. See
+        <xref
+          linkend="forums"/>.
+      </para>
+
+    </section>
+
+    <section id="connector-j-support-bug-report">
+
       <title>How to Report Connector/J Bugs or Problems</title>
 
       <para>
         The normal place to report bugs is
-        <ulink url="http://bugs.mysql.com/"/>, which is the address for
-        our bugs database. This database is public, and can be browsed
-        and searched by anyone. If you log in to the system, you will
-        also be able to enter new reports.
+        <ulink
+          url="http://bugs.mysql.com/"/>, which is the
+        address for our bugs database. This database is public, and can
+        be browsed and searched by anyone. If you log in to the system,
+        you will also be able to enter new reports.
       </para>
 
       <para>
         If you have found a sensitive security bug in MySQL, you can
         send email to
-        <ulink
-      url="mailto:security_at_mysql.com">security_at_@stripped</ulink>.
+        <ulink url="mailto:security_at_mysql.com"
+        >security_at_mysql.com</ulink>.
       </para>
 
       <para>

@@ -5110,15 +5116,12 @@
 
       <para>
         If you have a repeatable bug report, please report it to the
-        bugs database at <ulink url="http://bugs.mysql.com/"/>.
+        bugs database at <ulink url="http://bugs.mysql.com/"/>. Any bug
+        that we are able to repeat has a high chance of being fixed in
+        the next MySQL release.
       </para>
 
       <para>
-        Any bug that we are able to repeat has a high chance of being
-        fixed in the next MySQL release.
-      </para>
-
-      <para>
         To report other problems, you can use one of the MySQL mailing
         lists.
       </para>

@@ -5149,10 +5152,10 @@
       <para>
         This is highly relevant information, and in 99 cases out of 100,
         the bug report is useless without it. Very often we get
-        questions like, ``Why doesn't this work for me?'' Then we find
-        that the feature requested wasn't implemented in that MySQL
-        version, or that a bug described in a report has already been
-        fixed in newer MySQL versions.
+        questions like, <quote>Why doesn't this work for me?</quote>
+        Then we find that the feature requested wasn't implemented in
+        that MySQL version, or that a bug described in a report has
+        already been fixed in newer MySQL versions.
       </para>
 
       <para>

@@ -5173,65 +5176,64 @@
         create a testcase for Connector/J using this class, create your
         own class that inherits from
         <classname>com.mysql.jdbc.util.BaseBugReport</classname> and
-        override the methods <methodname>setUp()</methodname>,
-        <methodname>tearDown()</methodname> and
-        <methodname>runTest</methodname> ().
+        override the methods <literal>setUp()</literal>,
+        <literal>tearDown()</literal> and <literal>runTest()</literal>.
       </para>
 
       <para>
-        In the <methodname>setUp()</methodname> method, create code that
+        In the <literal>setUp()</literal> method, create code that
         creates your tables, and populates them with any data needed to
         demonstrate the bug.
       </para>
 
       <para>
-        In the <methodname>runTest</methodname> () method, create code
-        that demonstrates the bug using the tables and data you created
-        in the <function>setUp</function> method.
+        In the <literal>runTest()</literal> method, create code that
+        demonstrates the bug using the tables and data you created in
+        the <literal>setUp</literal> method.
       </para>
 
       <para>
-        In the <methodname>tearDown()</methodname> method, drop any
-        tables you created in the <methodname>setUp()</methodname>
-        method.
+        In the <literal>tearDown()</literal> method, drop any tables you
+        created in the <literal>setUp()</literal> method.
       </para>
 
       <para>
         In any of the above three methods, you should use one of the
-        variants of the <methodname>getConnection</methodname> () method
-        to create a JDBC connection to MySQL:
+        variants of the <literal>getConnection()</literal> method to
+        create a JDBC connection to MySQL:
       </para>
 
       <itemizedlist>
 
         <listitem>
           <para>
-            getConnection() - Provides a connection to the JDBC URL
-            specified in getUrl(). If a connection already exists, that
-            connection is returned, otherwise a new connection is
-            created.
+            <literal>getConnection()</literal> - Provides a connection
+            to the JDBC URL specified in <literal>getUrl()</literal>. If
+            a connection already exists, that connection is returned,
+            otherwise a new connection is created.
           </para>
         </listitem>
 
         <listitem>
           <para>
-            getNewConnection() - Use this if you need to get a new
-            connection for your bug report (i.e. there's more than one
-            connection involved).
+            <literal>getNewConnection()</literal> - Use this if you need
+            to get a new connection for your bug report (i.e. there's
+            more than one connection involved).
           </para>
         </listitem>
 
         <listitem>
           <para>
-            getConnection(String url) - Returns a connection using the
-            given URL.
+            <literal>getConnection(String url)</literal> - Returns a
+            connection using the given URL.
           </para>
         </listitem>
 
         <listitem>
           <para>
-            getConnection(String url, Properties props) - Returns a
-            connection using the given URL and properties.
+            <literal>getConnection(String url, Properties
+            props)</literal> - Returns a connection using the given URL
+            and properties.
           </para>
         </listitem>
 

@@ -5240,22 +5242,22 @@
       <para>
         If you need to use a JDBC URL that is different from
         'jdbc:mysql:///test', override the method
-        <methodname>getUrl()</methodname> as well.
+        <literal>getUrl()</literal> as well.
       </para>
 
       <para>
-        Use the <methodname>assertTrue(boolean expression)</methodname>
-        and <methodname>assertTrue(String failureMessage, boolean
-        expression)</methodname> methods to create conditions that must
-        be met in your testcase demonstrating the behavior you are
+        Use the <literal>assertTrue(boolean expression)</literal> and
+        <literal>assertTrue(String failureMessage, boolean
+        expression)</literal> methods to create conditions that must be
+        met in your testcase demonstrating the behavior you are
         expecting (vs. the behavior you are observing, which is why you
         are most likely filing a bug report).
       </para>
 
       <para>
-        Finally, create a <methodname>main</methodname> () method that
-        creates a new instance of your testcase, and calls the
-        <methodname>run</methodname> method:
+        Finally, create a <literal>main()</literal> method that creates
+        a new instance of your testcase, and calls the
+        <literal>run</literal> method:
       </para>
 
 <programlisting>public static void main(String[] args) throws Exception {

@@ -5270,9 +5272,17 @@
 
     </section>
 
+    <section id="connector-j-support-changelog">
+
+      <title>Connector/J Change History</title>
+
+      <para>
+        The Connector/J Change History (Changelog) is located with the
+        main Changelog for MySQL. See <xref linkend="cj-news"/>.
+      </para>
+
+    </section>
+
   </section>
 
-  <xi:include href="../refman-common/news-connector-j.xml"
-              xmlns:xi="http://www.w3.org/2001/XInclude" />
-
 </section>


Modified: trunk/refman-4.1/news.xml
===================================================================
--- trunk/refman-4.1/news.xml	2006-08-01 18:56:55 UTC (rev 2917)
+++ trunk/refman-4.1/news.xml	2006-08-02 10:55:34 UTC (rev 2918)
Changed blocks: 1, Lines Added: 2, Lines Deleted: 0; 474 bytes

@@ -81,4 +81,6 @@
 
   <xi:include href="../refman-common/news-connector-net.xml"  xmlns:xi="http://www.w3.org/2001/XInclude"/>
 
+  <xi:include href="../refman-common/news-connector-j.xml"  xmlns:xi="http://www.w3.org/2001/XInclude"/>
+
 </appendix>


Modified: trunk/refman-4.1/renamed-nodes.txt
===================================================================
--- trunk/refman-4.1/renamed-nodes.txt	2006-08-01 18:56:55 UTC (rev 2917)
+++ trunk/refman-4.1/renamed-nodes.txt	2006-08-02 10:55:34 UTC (rev 2918)
Changed blocks: 1, Lines Added: 31, Lines Deleted: 0; 2125 bytes

@@ -255,3 +255,34 @@
 mxj-jmx-agent connector-mxj-usagenotes-jmx-agent
 mxj-standard-environment connector-mxj-usagenotes-standard-environment
 mxj-install connector-mxj-install
+java-connector connector-j
+cj-basic-jdbc connector-j-usagenotes-basic
+cj-connect-with-drivermanager connector-j-usagenotes-connect-drivermanager
+cj-using-callable-statements connector-j-usagenotes-statements-callable
+cj-retrieve-autoinc connector-j-usagenotes-last-insert-id
+cj-installing connector-j-installing
+cj-system-requirements connector-j-versions
+cj-supported-java-versions connector-j-verions-java
+cj-supported-mysql-versions connector-j-versions
+cj-classpath connector-j-installing-classpath
+cj-upgrading connector-j-installing-upgrading
+cj-upgrading-3-0-to-3-1 connector-j-installing-upgrading-3-0-to-3-1
+cj-jdbc-upgrading-issues connector-j-installing-upgrading-issues
+cj-installing-source connector-j-installing-source
+cj-jdbc-reference connector-j-reference
+cj-configuration-properties connector-j-reference-configuration-properties
+cj-implementation-notes connector-j-reference-implementation-notes
+cj-type-conversions connector-j-references-type-conversions
+cj-character-sets connector-j-reference-charsets
+cj-usage-advisor connector-j-reference-usage-advisor
+cj-using-ssl connector-j-reference-using-ssl
+cj-replication-connection connector-j-reference-replication-connection
+cj-j2ee connector-j-usagenotes-j2ee
+cj-general-j2ee-concepts connector-j-usagenotes-j2ee-concepts
+cj-connection-pooling connector-j-usagenotes-j2ee-concepts-connection-pooling
+cj-understanding-transactions connector-j-usagenotes-j2ee-concepts-transactions
+cj-tomcat-config connector-j-usagenotes-tomcat
+cj-jboss-config connector-j-usagenotes-jboss
+cj-troubleshooting connector-j-usagenotes-troubleshooting
+cj-faq connector-j-usagenotes-troubleshooting
+cj-reporting-bugs connector-j-support-bug-report


Thread
svn commit - mysqldoc@docsrva: r2918 - trunk/refman-4.1mcbrown2 Aug