List:Commits« Previous MessageNext Message »
From:mmatthews Date:January 13 2006 8:10pm
Subject:svn commit - mysqldoc@docsrva: r814 - trunk/refman-5.0
View as plain text  
Author: mmatthews
Date: 2006-01-13 21:10:16 +0100 (Fri, 13 Jan 2006)
New Revision: 814

Log:
Added section for building from source repository.

Modified:
   trunk/refman-5.0/connector-j.xml

Modified: trunk/refman-5.0/connector-j.xml
===================================================================
--- trunk/refman-5.0/connector-j.xml	2006-01-13 19:54:03 UTC (rev 813)
+++ trunk/refman-5.0/connector-j.xml	2006-01-13 20:10:16 UTC (rev 814)
@@ -1,116 +1,87 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
-[
-  <!ENTITY % fixedchars.entities  SYSTEM "../refman-common/fixedchars.ent">
-  %fixedchars.entities;
-  <!ENTITY % title.entities       SYSTEM "../refman-common/titles.en.ent">
-  %title.entities;
-  <!ENTITY % versions.entities    SYSTEM "versions.ent">
-  %versions.entities;
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+<!ENTITY % fixedchars.entities SYSTEM "../refman-common/fixedchars.ent">
+%fixedchars.entities;
+<!ENTITY % title.entities SYSTEM "../refman-common/titles.en.ent">
+%title.entities;
+<!ENTITY % versions.entities SYSTEM "versions.ent">
+%versions.entities;
 ]>
 <section id="java-connector">
+  <title>MySQL Connector/J</title>
 
-  <title>&title-java-connector;</title>
+  <para>MySQL provides connectivity for client applications developed in the
+  Java programming language via a JDBC driver, which is called MySQL
+  Connector/J.</para>
 
-  <para>
-    MySQL provides connectivity for client applications developed in the
-    Java programming language via a JDBC driver, which is called MySQL
-    Connector/J.
-  </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.</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.
-  </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
+  section <xref linkend="cj-installing" />.</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 section <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 <ulink url="http://www.hibernate.org/">Hibernate</ulink>,
+  <ulink url="http://www.springframework.org/">Spring's JDBC templates</ulink>
+  or <ulink url="http://www.ibatis.com/common/sqlmaps.html">Ibatis SQL
+  Maps</ulink> to do the majority of repetitive work and heavier lifting that
+  is sometimes required with JDBC.</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
-    <ulink url="http://www.hibernate.org/">Hibernate</ulink>,
-    <ulink url="http://www.springframework.org/">Spring's JDBC
-    templates</ulink> or
-    <ulink url="http://www.ibatis.com/common/sqlmaps.html">Ibatis SQL
-    Maps</ulink> to do the majority of repetitive work and heavier
-    lifting that is sometimes required with JDBC.
-  </para>
+  <para>This section is not designed to be a complete JDBC tutorial. If you
+  need more information about using JDBC you might be interested in the
+  following online tutorials that are more in-depth than the information
+  presented here:</para>
 
-  <para>
-    This section is not designed to be a complete JDBC tutorial. If you
-    need more information about using JDBC you might be interested in
-    the following online tutorials that are more in-depth than the
-    information presented here:
-  </para>
-
   <itemizedlist>
-
     <listitem>
-      <para>
-        <ulink
+      <para><ulink
       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>
+      Basics </ulink> — A tutorial from Sun covering beginner topics in
+      JDBC</para>
     </listitem>
 
     <listitem>
-      <para>
-        <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>
+      <para><ulink
+      url="http://java.sun.com/developer/onlineTraining/Database/JDBCShortCourse/index.html">JDBC
+      Short Course</ulink> — A more in-depth tutorial from Sun and
+      JGuru</para>
     </listitem>
-
   </itemizedlist>
 
   <section id="cj-basic-jdbc">
+    <title>Basic JDBC concepts</title>
 
-    <title>&title-cj-basic-jdbc;</title>
+    <para>This section provides some general JDBC background.</para>
 
-    <para>
-      This section provides some general JDBC background.
-    </para>
-
     <section id="cj-connect-with-drivermanager">
+      <title>Connecting to MySQL using the <literal>DriverManager</literal>
+      Interface</title>
 
-      <title>&title-cj-connect-with-drivermanager;</title>
+      <para>When you are using JDBC outside of an application server, the
+      <literal>DriverManager</literal> class manages the establishment of
+      Connections.</para>
 
-      <para>
-        When you are using JDBC outside of an application server, the
-        <literal>DriverManager</literal> class manages the establishment
-        of Connections.
-      </para>
+      <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>
 
-      <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>
+      <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>
 
-      <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>
-
-<programlisting>import java.sql.Connection;
+      <programlisting>import java.sql.Connection;
 import java.sql.DriverManager;
 import java.sql.SQLException;
 
@@ -129,28 +100,24 @@
         }
 }</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>:
-      </para>
+      <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>:</para>
 
       <example>
+        <title>Obtaining a Connection From the
+        <literal>DriverManager</literal></title>
 
-        <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 <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>
 
-        <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>
-
-<programlisting>
+        <programlisting>
 import java.sql.Connection;
 import java.sql.DriverManager;
 import java.sql.SQLException;
@@ -169,19 +136,15 @@
         }
 </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>
-
+        <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="cj-connect-with-datasource">
           <title>&title-cj-connect-with-datasource;;</title>
 
@@ -189,7 +152,7 @@
         </section>
 -->
 
-<!--
+    <!--
         <section id="cj-controlling-transactions">
           <title>&title-cj-controlling-transactions;</title>
 
@@ -198,60 +161,46 @@
 -->
 
     <section id="cj-using-statements">
+      <title>Using Statements to Execute SQL</title>
 
-      <title>&title-cj-using-statements;</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.</para>
 
-      <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.
-      </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.</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.
-      </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>
-        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>
-        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 <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.</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.
-      </para>
-
       <example>
-
         <title>Using java.sql.Statement to Execute a SELECT Query</title>
 
-<programlisting>// assume that conn is an already created JDBC connection
+        <programlisting>// assume that conn is an already created JDBC connection
 Statement stmt = null;
 ResultSet rs = null;
 
@@ -289,12 +238,10 @@
         stmt = null;
     }
 }</programlisting>
-
       </example>
-
     </section>
 
-<!--
+    <!--
         <section id="cj-using-prepared-statements">
           <title>&title-cj-using-prepared-statements;</title>
 
@@ -303,40 +250,29 @@
 -->
 
     <section id="cj-using-callable-statements">
+      <title>Using <literal>CallableStatements</literal> to Execute Stored
+      Procedures</title>
 
-      <title>&title-cj-using-callable-statements;</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.</para>
 
-      <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.
-      </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.</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.
-      </para>
+      <para>Connector/J exposes stored procedure functionality through JDBC's
+      <classname>CallableStatement</classname> interface.</para>
 
-      <para>
-        Connector/J exposes stored procedure functionality through
-        JDBC's <classname>CallableStatement</classname> interface.
-      </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>:
-
-        <example>
-
+      <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>
           <title>Stored Procedure Example</title>
 
-<programlisting>CREATE PROCEDURE demoSp(IN inputParam VARCHAR(255), INOUT inOutParam INT)
+          <programlisting>CREATE PROCEDURE demoSp(IN inputParam VARCHAR(255), INOUT inOutParam INT)
 BEGIN
     DECLARE z INT;
     SET z = inOutParam + 1;
@@ -346,34 +282,24 @@
 
     SELECT CONCAT('zyxw', inputParam);
 END</programlisting>
+        </example></para>
 
-        </example>
-      </para>
+      <para>To use the <function>demoSp</function> procedure with Connector/J,
+      follow these steps:</para>
 
-      <para>
-        To use the <function>demoSp</function> procedure with
-        Connector/J, follow these steps:
-      </para>
-
       <orderedlist>
-
         <listitem>
-          <para>
-            Prepare the callable statement by using
-            <function>Connection.prepareCall()</function> .
-          </para>
+          <para>Prepare the callable statement by using
+          <function>Connection.prepareCall()</function> .</para>
 
-          <para>
-            Notice that you have to use JDBC escape syntax, and that the
-            parentheses surrounding the parameter placeholders are not
-            optional:
-          </para>
+          <para>Notice that you have to use JDBC escape syntax, and that the
+          parentheses surrounding the parameter placeholders are not
+          optional:</para>
 
           <example>
-
             <title>Using <function>Connection.prepareCall()</function></title>
 
-<programlisting>import java.sql.CallableStatement;
+            <programlisting>import java.sql.CallableStatement;
 
 ...
 
@@ -389,44 +315,31 @@
 
 
     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>
-
+            <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)
-          </para>
+          <para>Register the output parameters (if any exist)</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>
-
+          <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>
+              <programlisting>
 import java.sql.Types;
 ...
 //
@@ -460,28 +373,21 @@
 cStmt.registerOutParameter("inOutParam", Types.INTEGER);
 ...
 </programlisting>
-
-            </example>
-          </para>
+            </example></para>
         </listitem>
 
         <listitem>
-          <para>
-            Set the input parameters (if any exist)
-          </para>
+          <para>Set the input parameters (if any exist)</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:
+          <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>
 
-            <example>
+              <programlisting>...
 
-              <title>Setting <literal>CallableStatement</literal> Input Parameters</title>
-
-<programlisting>...
-
     //
     // Set a parameter by index
     //
@@ -509,32 +415,23 @@
     cStmt.setInt("inOutParam", 1);
 
 ...</programlisting>
-
-            </example>
-          </para>
+            </example></para>
         </listitem>
 
         <listitem>
-          <para>
-            Execute the <classname>CallableStatement</classname>, and
-            retrieve any result sets or output parameters.
-          </para>
+          <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 (<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>
-
+          <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>...
+              <programlisting>...
 
     boolean hadResults = cStmt.execute();
 
@@ -563,51 +460,40 @@
     outputValue = cStmt.getInt("inOutParam"); // name-based
 
 ...</programlisting>
-
-            </example>
-          </para>
+            </example></para>
         </listitem>
-
       </orderedlist>
-
     </section>
 
     <section id="cj-retrieve-autoinc">
+      <title>Retrieving <literal>AUTO_INCREMENT</literal> Column
+      Values</title>
 
-      <title>&title-cj-retrieve-autoinc;</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>
 
-      <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;
+          <programlisting>   Statement stmt = null;
    ResultSet rs = null;
 
    try {
@@ -683,15 +569,11 @@
     }
 }
 </programlisting>
+        </example> <example>
+          <title>Retrieving <literal>AUTO_INCREMENT</literal> Column Values
+          using <function>SELECT LAST_INSERT_ID()</function></title>
 
-        </example>
-
-        <example>
-
-          <title>Retrieving <literal>AUTO_INCREMENT</literal> Column Values using
-            <function>SELECT LAST_INSERT_ID()</function></title>
-
-<programlisting>   Statement stmt = null;
+          <programlisting>   Statement stmt = null;
    ResultSet rs = null;
 
    try {
@@ -759,15 +641,11 @@
     }
 }
    </programlisting>
-
-        </example>
-
-        <example>
-
+        </example> <example>
           <title>Retrieving <literal>AUTO_INCREMENT</literal> Column Values in
-            <literal>Updatable ResultSets</literal></title>
+          <literal>Updatable ResultSets</literal></title>
 
-<programlisting>   Statement stmt = null;
+          <programlisting>   Statement stmt = null;
    ResultSet rs = null;
 
    try {
@@ -845,27 +723,21 @@
 
 
    </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>
-
+        </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>&title-cj-retrieve-multiresults;</title>
 
@@ -873,7 +745,7 @@
         </section>
 -->
 
-<!--
+    <!--
         <section id="cj-using-result-set-metadata">
           <title>&title-cj-using-result-set-metadata;</title>
 
@@ -881,7 +753,7 @@
         </section>
 -->
 
-<!--
+    <!--
         <section id="cj-using-database-metadata">
           <title>&title-cj-using-database-metadata;</title>
 
@@ -889,2424 +761,2834 @@
         </section>
 -->
 
-<!--
+    <!--
         <section id="cj-working-with-lobs">
           <title>&title-cj-working-with-lobs;</title>
 
           <para />
         </section>
 -->
-
   </section>
 
   <section id="cj-installing">
+    <title>Installing Connector/J</title>
 
-    <title>&title-cj-installing;</title>
+    <para>Use the following instructions to install Connector/J</para>
 
-    <para>
-      Use the following instructions to install Connector/J
-    </para>
-
     <section id="cj-system-requirements">
+      <title>Required Software Versions</title>
 
-      <title>&title-cj-system-requirements;</title>
-
       <para></para>
 
       <section id="cj-supported-java-versions">
+        <title>Java Versions Supported</title>
 
-        <title>&title-cj-supported-java-versions;</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>
-          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>
-          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>
 
-        <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>
-
+        <remark>MARKUP DONE TO HERE</remark>
       </section>
 
       <section id="cj-supported-mysql-versions">
+        <title>MySQL Server Version Guidelines</title>
 
-        <title>&title-cj-supported-mysql-versions;</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>
-          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>
-          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>
-
+        <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 id="c-j-installing-driver-classpath">Installing the Driver and
+        Configuring the <literal>CLASSPATH</literal></title>
 
-        <title>&title-cj-classpath;</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>
-          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>
-          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 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>
-          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>
-          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>
 
-        <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>
+          <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>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. This
-          document does contain configuration examples for some J2EE
-          application servers in the section named
-          "<link
-        linkend="cj-j2ee">Using Connector/J with J2EE
-          and Other Java Frameworks</link>", 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 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. This document does contain configuration
+        examples for some J2EE application servers in the section named "<link
+        linkend="cj-j2ee">Using Connector/J with J2EE and Other Java
+        Frameworks</link>", 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>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>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>
+        <para>The various MysqlDataSource classes support the following
+        parameters (through standard "set" mutators):</para>
 
         <itemizedlist>
-
           <listitem>
-            <para>
-              user
-            </para>
+            <para>user</para>
           </listitem>
 
           <listitem>
-            <para>
-              password
-            </para>
+            <para>password</para>
           </listitem>
 
           <listitem>
-            <para>
-              serverName (see the previous section about fail-over
-              hosts)
-            </para>
+            <para>serverName (see the previous section about fail-over
+            hosts)</para>
           </listitem>
 
           <listitem>
-            <para>
-              databaseName
-            </para>
+            <para>databaseName</para>
           </listitem>
 
           <listitem>
-            <para>
-              port
-            </para>
+            <para>port</para>
           </listitem>
-
         </itemizedlist>
-
       </section>
-
     </section>
 
     <section id="cj-upgrading">
+      <title>Upgrading from an Older Version</title>
 
-      <title>&title-cj-upgrading;</title>
+      <para>MySQL AB tries to keep the upgrade process as easy as possible,
+      however as is the case with any software, sometimes changes need to be
+      made in new versions to support new features, improve existing
+      functionality, or comply with new standards.</para>
 
-      <para>
-        MySQL AB tries to keep the upgrade process as easy as possible,
-        however as is the case with any software, sometimes changes need
-        to be made in new versions to support new features, improve
-        existing functionality, or comply with new standards.
-      </para>
+      <para>This section has information about what users who are upgrading
+      from one version of Connector/J to another (or to a new version of the
+      MySQL server, with respect to JDBC functionality) should be aware
+      of.</para>
 
-      <para>
-        This section has information about what users who are upgrading
-        from one version of Connector/J to another (or to a new version
-        of the MySQL server, with respect to JDBC functionality) should
-        be aware of.
-      </para>
-
       <section id="cj-upgrading-3-0-to-3-1">
+        <title>Upgrading from MySQL Connector/J 3.0 to 3.1</title>
 
-        <title>&title-cj-upgrading-3-0-to-3-1;</title>
+        <para>Connector/J 3.1 is designed to be backward-compatible with
+        Connector/J 3.0 as much as possible. Major changes are isolated to new
+        functionality exposed in MySQL-4.1 and newer, which includes Unicode
+        character sets, server-side prepared statements, SQLState codes
+        returned in error messages by the server and various performance
+        enhancements that can be enabled or disabled via configuration
+        properties.</para>
 
-        <para>
-          Connector/J 3.1 is designed to be backward-compatible with
-          Connector/J 3.0 as much as possible. Major changes are
-          isolated to new functionality exposed in MySQL-4.1 and newer,
-          which includes Unicode character sets, server-side prepared
-          statements, SQLState codes returned in error messages by the
-          server and various performance enhancements that can be
-          enabled or disabled via configuration properties.
-        </para>
-
         <itemizedlist>
-
           <listitem>
-            <para>
-              Unicode Character Sets - See the next section, as well as
-              the "Character Sets" section in the server manual 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 'Illegal mix of
-              collations'.
-            </para>
+            <para>Unicode Character Sets - See the next section, as well as
+            the "Character Sets" section in the server manual 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
+            'Illegal mix of collations'.</para>
           </listitem>
 
           <listitem>
-            <para>
-              <emphasis>Server-side Prepared Statements</emphasis> -
-              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><emphasis>Server-side Prepared Statements</emphasis> -
+            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
-              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
-              your JDBC URL.
-            </para>
+            <para>Starting with version 3.1.7, the driver scans SQL you are
+            preparing via all variants of
+            <methodname>Connection.prepareStatement()</methodname> 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 your JDBC
+            URL.</para>
 
-            <para>
-              If your application encounters issues with server-side
-              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:
-            </para>
+            <para>If your application encounters issues with server-side
+            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:</para>
 
-            <para>
-              <computeroutput>useServerPrepStmts=false</computeroutput>
-            </para>
+            <para><computeroutput>useServerPrepStmts=false</computeroutput></para>
           </listitem>
 
           <listitem>
-            <para>
-              Datetimes with all-zero components ('0000-00-00 ...') -
-              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>Datetimes with all-zero components ('0000-00-00 ...') -
+            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'.
-            </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'.</para>
 
-            <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 timezone conversions,
-              therefore the driver will not allow you to enable
-              <property>noDatetimeStringSync</property> and
-              <property>useTimezone</property> at the same time.
-            </para>
+            <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 timezone 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 - Connector/J 3.1 uses SQL:1999
-              SQLState codes returned by the MySQL server (if
-              supported), which are different than 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
-              mapping. You can revert to the old mapping by using the
-              following configuration property:
-            </para>
+            <para>New SQLState Codes - Connector/J 3.1 uses SQL:1999 SQLState
+            codes returned by the MySQL server (if supported), which are
+            different than 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 mapping. You can
+            revert to the old mapping by using the following configuration
+            property:</para>
 
-            <para>
-              <computeroutput>useSqlStateCodes=false</computeroutput>
-            </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.
-            </para>
+            <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.</para>
 
-            <para>
-              To store strings in MySQL with LOB behavior, use one of
-              the TEXT types, which the driver will treat as a
-              java.sql.Clob.
-            </para>
+            <para>To store strings in MySQL with LOB behavior, use one of the
+            TEXT types, which the driver will treat as a java.sql.Clob.</para>
           </listitem>
 
           <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>".
-            </para>
+            <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>".</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>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 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>
           </listitem>
-
         </itemizedlist>
-
       </section>
 
       <section id="cj-jdbc-upgrading-issues">
+        <title>JDBC-Specific Issues When Upgrading to MySQL Server 4.1 or
+        Newer</title>
 
-        <title>&title-cj-jdbc-upgrading-issues;</title>
-
         <itemizedlist>
-
           <listitem>
-            <para>
-              <emphasis>Using the UTF-8 Character Encoding</emphasis> -
-              Prior to MySQL server version 4.1, the UTF-8 character
-              encoding was not supported by the server, however the JDBC
-              driver could use it, allowing storage of multiple
-              character sets in latin1 tables on the server.
-            </para>
+            <para><emphasis>Using the UTF-8 Character Encoding</emphasis> -
+            Prior to MySQL server version 4.1, the UTF-8 character encoding
+            was not supported by the server, however the JDBC driver could use
+            it, allowing storage of multiple character sets in latin1 tables
+            on the server.</para>
 
-            <para>
-              Starting with MySQL-4.1, this functionality is deprecated.
-              If you have applications that rely on this functionality,
-              and can not upgrade them to use the official Unicode
-              character support in MySQL server version 4.1 or newer,
-              you should add the following property to your connection
-              URL:
-            </para>
+            <para>Starting with MySQL-4.1, this functionality is deprecated.
+            If you have applications that rely on this functionality, and can
+            not upgrade them to use the official Unicode character support in
+            MySQL server version 4.1 or newer, you should add the following
+            property to your connection URL:</para>
 
-            <para>
-              <computeroutput>useOldUTF8Behavior=true</computeroutput>
-            </para>
+            <para><computeroutput>useOldUTF8Behavior=true</computeroutput></para>
           </listitem>
 
           <listitem>
-            <para>
-              <emphasis>Server-side Prepared Statements</emphasis> -
-              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). If your
-              application encounters issues with server-side 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:
-            </para>
+            <para><emphasis>Server-side Prepared Statements</emphasis> -
+            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). If your application encounters issues with
+            server-side 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:</para>
 
-            <para>
-              <computeroutput>useServerPrepStmts=false</computeroutput>
-            </para>
+            <para><computeroutput>useServerPrepStmts=false</computeroutput></para>
           </listitem>
-
         </itemizedlist>
-
       </section>
-
     </section>
 
+    <section>
+      <title>Installing from the Development Source Tree</title>
+
+      <para><caution>
+          <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>To install MySQL Connector/J from the development source
+      tree, the following prerequesites are required:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>Subversion available from <ulink
+          url="http://subversion.tigris.org/">http://subversion.tigris.org/</ulink>,
+          to checkout the sources from our repository</para>
+        </listitem>
+
+        <listitem>
+          <para>Apache Ant version 1.6 or newer, from <ulink
+          url="http://ant.apache.org/">http://ant.apache.org/</ulink> </para>
+        </listitem>
+
+        <listitem>
+          <para>JDK-1.4.2 or later. Although MySQL Connector/J can be
+          installed on older JDKs, it requires at least JDK-1.4.2 for
+          compilation.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>The Subversion source code repository for MySQL Connector/J is
+      located at <ulink
+      url="http://svn.mysql.com/svnpublic/connector-j">http://svn.mysql.com/svnpublic/connector-j</ulink>.
+      In general, you should not checkout the entire repository as it contains
+      every branch and tag for MySQL Connector/J and is quite large.</para>
+
+      <para>To checkout and compile a specfic branch of MySQL Connector/J,
+      follow these steps:</para>
+
+      <orderedlist>
+        <listitem>
+          <para>Check out the latest code from a branch (replacing [major] and
+          [minor] with appropriate version numbers. At the time of this
+          writing there are three active branches of Connector/J. They are
+          "branch_3_0", "branch_3_1" and "branch_5_0":</para>
+
+          <programlisting>svn co http://svn.mysql.com/svnpublic/connector-j/branches/branch_[major]_[minor]/connector-j</programlisting>
+
+          <para>This will create a "connector-j" subdirectory in the current
+          directory that contains the latest sources for the requested
+          branch.</para>
+        </listitem>
+
+        <listitem>
+          <para>Change the working directory to this "connector-j"
+          directory:</para>
+
+          <programlisting>shell&gt; cd connector-j</programlisting>
+        </listitem>
+
+        <listitem>
+          <para>Issue the following command to compile the driver and create a
+          .jar file suitable for installation:</para>
+
+          <programlisting>ant dist</programlisting>
+
+          <para>This will create a "build" directory in the current directory,
+          where all build output will go. A directory is created in the build
+          directory that includes the version number of the sources you are
+          building from. This directory contains the sources, compiled .class
+          files, and a .jar file suitable for deployment. For other possible
+          targets, including ones which will create a fully-packaged
+          distribution, issue the following command:<programlisting>ant --projecthelp</programlisting></para>
+        </listitem>
+
+        <listitem>
+          <para>A newly-created .jar file containing the JDBC driver will be
+          placed in the directory build/mysql-connector-java-[version].</para>
+
+          <para>Install the newly-created JDBC driver as you would a binary
+          .jar file you download from MySQL by following the instructions in
+          the section "<link linkend="???">Installing the Driver and
+          Configuring the
+          <literal>CLASSPATH</literal></link><literal>".</literal></para>
+        </listitem>
+      </orderedlist>
+    </section>
   </section>
 
   <section id="cj-jdbc-reference">
+    <title>JDBC Reference</title>
 
-    <title>&title-cj-jdbc-reference;</title>
-
     <para></para>
 
     <section id="cj-configuration-properties">
+      <title>Driver/Datasource Class Names, URL Syntax and Configuration
+      Properties for Connector/J</title>
 
-      <title>&title-cj-configuration-properties;</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.</para>
 
-      <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.
-      </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>
 
-      <para>
-        The JDBC URL format for MySQL Connector/J is as follows, with
-        items in square brackets ([, ]) being optional:
+      <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.</para>
 
-        <screen>jdbc:mysql://[host][,failoverhost...][:port]/[database][?propertyName1][=propertyValue1][&amp;propertyName2][=propertyValue2]...</screen>
-      </para>
-
-      <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.
-      </para>
-
       <screen>jdbc:mysql://[host:port],[host:port].../[database][?propertyName1][=propertyValue1][&amp;propertyName2][=propertyValue2]...</screen>
 
-      <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
-        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.
-      </para>
+      <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 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.</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.
-      </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.</para>
 
-      <para>
-        The fail-over functionality has the following behavior:
-      </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>
+      <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>
 
-      <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>
+      <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>
 
-      <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).
-      </para>
+      <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).</para>
 
-      <para>
-        Configuration properties define how Connector/J will make a
-        connection to a MySQL server. Unless otherwise noted, properties
-        can be set for a DataSource object or for a Connection object.
-      </para>
+      <para>Configuration properties define how Connector/J will make a
+      connection to a MySQL server. Unless otherwise noted, properties can be
+      set for a DataSource object or for a Connection object.</para>
 
-      <para>
-        Configuration Properties can be set in one of the following
-        ways:
-      </para>
+      <para>Configuration Properties can be set in one of the following
+      ways:</para>
 
       <itemizedlist>
-
         <listitem>
-          <para>
-            Using the set*() methods on MySQL implementations of
-            java.sql.DataSource (which is the preferred method when
-            using implementations of java.sql.DataSource):
-          </para>
+          <para>Using the set*() methods on MySQL implementations of
+          java.sql.DataSource (which is the preferred method when using
+          implementations of java.sql.DataSource):</para>
 
           <itemizedlist>
-
             <listitem>
-              <para>
-                com.mysql.jdbc.jdbc2.optional.MysqlDataSource
-              </para>
+              <para>com.mysql.jdbc.jdbc2.optional.MysqlDataSource</para>
             </listitem>
 
             <listitem>
-              <para>
-                com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource
-              </para>
+              <para>com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource</para>
             </listitem>
-
           </itemizedlist>
         </listitem>
 
         <listitem>
-          <para>
-            As a key/value pair in the java.util.Properties instance
-            passed to DriverManager.getConnection() or Driver.connect()
-          </para>
+          <para>As a key/value pair in the java.util.Properties instance
+          passed to DriverManager.getConnection() or Driver.connect()</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.
-
-            <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>
+          <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.
+          <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>
         </listitem>
-
       </itemizedlist>
 
-      <para>
-        The properties are listed in the following table:
-      </para>
+      <para>The properties are listed in the following table:</para>
 
-<!-- Generated by the genPropertiesTable target in the build script -->
+      <!-- Generated by the genPropertiesTable target in the build script -->
 
       <table>
-
         <title>Connection Properties</title>
 
         <tgroup cols="5">
           <colspec colname="cj_propstbl_prop_name" />
+
           <colspec colname="cj_propstbl_prop_defn" />
+
           <colspec colname="cj_propstbl_required" />
+
           <colspec colname="cj_propstbl_required" />
+
           <colspec colname="cj_propstbl_since_version" />
+
           <spanspec nameend="cj_propstbl_since_version"
                     namest="cj_propstbl_prop_name"
                     spanname="cj_propstbl_span_all_cols" />
-          <thead>
 
+          <thead>
             <row>
               <entry>Property Name</entry>
+
               <entry>Definition</entry>
+
               <entry>Required?</entry>
+
               <entry>Default Value</entry>
+
               <entry>Since Version</entry>
             </row>
-
           </thead>
+
           <tbody>
             <row>
               <entry
               spanname="cj_propstbl_span_all_cols"><emphasis>Connection/Authentication</emphasis></entry>
             </row>
+
             <row>
               <entry>user</entry>
+
               <entry>The user to connect as</entry>
+
               <entry>No</entry>
+
               <entry></entry>
+
               <entry>all</entry>
             </row>
+
             <row>
               <entry>password</entry>
+
               <entry>The password to use when connecting</entry>
+
               <entry>No</entry>
+
               <entry></entry>
+
               <entry>all</entry>
             </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 'com.mysql.jdbc.SocketFactory' and have
+              public no-args constructor.</entry>
+
               <entry>No</entry>
+
               <entry>com.mysql.jdbc.StandardSocketFactory</entry>
+
               <entry>3.0.3</entry>
             </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>No</entry>
+
               <entry>0</entry>
+
               <entry>3.0.1</entry>
             </row>
+
             <row>
               <entry>socketTimeout</entry>
-              <entry>Timeout on network socket operations (0, the default means no timeout).</entry>
+
+              <entry>Timeout on network socket operations (0, the default
+              means no timeout).</entry>
+
               <entry>No</entry>
+
               <entry>0</entry>
+
               <entry>3.0.1</entry>
             </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>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>No</entry>
+
               <entry></entry>
+
               <entry>3.1.5</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.0</entry>
             </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>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>No</entry>
+
               <entry></entry>
+
               <entry>3.1.4</entry>
             </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 'false'.</entry>
+
               <entry>No</entry>
+
               <entry>false</entry>
+
               <entry>3.0.17</entry>
             </row>
+
             <row>
-              <entry spanname="cj_propstbl_span_all_cols"><emphasis>High Availability and Clustering</emphasis></entry>
+              <entry spanname="cj_propstbl_span_all_cols"><emphasis>High
+              Availability and Clustering</emphasis></entry>
             </row>
+
             <row>
               <entry>autoReconnect</entry>
-              <entry>Should the driver try to re-establish stale 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 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>No</entry>
+
               <entry>false</entry>
+
               <entry>1.1</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.3</entry>
             </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>No</entry>
+
               <entry>true</entry>
+
               <entry>3.0.12</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.0.10</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.2</entry>
             </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>No</entry>
+
               <entry>50</entry>
+
               <entry>3.0.2</entry>
             </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>No</entry>
+
               <entry>30</entry>
+
               <entry>3.0.2</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.2.1</entry>
             </row>
+
             <row>
               <entry
               spanname="cj_propstbl_span_all_cols"><emphasis>Security</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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.1</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.0.2</entry>
             </row>
+
             <row>
               <entry>requireSSL</entry>
-              <entry>Require SSL connection if useSSL=true? (defaults to 'false').</entry>
+
+              <entry>Require SSL connection if useSSL=true? (defaults to
+              'false').</entry>
+
               <entry>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.0</entry>
             </row>
+
             <row>
               <entry>allowUrlInLocalInfile</entry>
-              <entry>Should the driver allow URLs in 'LOAD DATA LOCAL INFILE' statements?</entry>
+
+              <entry>Should the driver allow URLs in 'LOAD DATA LOCAL INFILE'
+              statements?</entry>
+
               <entry>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.4</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.0.1</entry>
             </row>
+
             <row>
               <entry
-              spanname="cj_propstbl_span_all_cols"><emphasis>Performance Extensions</emphasis></entry>
+              spanname="cj_propstbl_span_all_cols"><emphasis>Performance
+              Extensions</emphasis></entry>
             </row>
+
             <row>
               <entry>metadataCacheSize</entry>
+
               <entry>The number of queries to cacheResultSetMetadata for if
-                cacheResultSetMetaData is set to 'true' (default 50)</entry>
+              cacheResultSetMetaData is set to 'true' (default 50)</entry>
+
               <entry>No</entry>
+
               <entry>50</entry>
+
               <entry>3.1.1</entry>
             </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>No</entry>
+
               <entry>25</entry>
+
               <entry>3.0.10</entry>
             </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>No</entry>
+
               <entry>256</entry>
+
               <entry>3.0.10</entry>
             </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 setFetchSize() &gt;
+              0 on a statement, should that statement use cursor-based
+              fetching to retrieve rows?</entry>
+
               <entry>No</entry>
+
               <entry>false</entry>
+
               <entry>5.0.0</entry>
             </row>
+
             <row>
               <entry>blobSendChunkSize</entry>
-              <entry>Chunk to use when sending BLOB/CLOBs via ServerPreparedStatements</entry>
+
+              <entry>Chunk to use when sending BLOB/CLOBs via
+              ServerPreparedStatements</entry>
+
               <entry>No</entry>
+
               <entry>1048576</entry>
+
               <entry>3.1.9</entry>
             </row>
+
             <row>
               <entry>cacheCallableStmts</entry>
-              <entry>Should the driver cache the parsing stage of CallableStatements</entry>
+
+              <entry>Should the driver cache the parsing stage of
+              CallableStatements</entry>
+
               <entry>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.2</entry>
             </row>
+
             <row>
               <entry>cachePrepStmts</entry>
-              <entry>Should the driver cache the parsing stage of PreparedStatements of
-                client-side prepared statements, the
-                <quote>check</quote> 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
+              <quote>check</quote> for suitability of server-side prepared and
+              server-side prepared statements themselves?</entry>
+
               <entry>No</entry>
+
               <entry>false</entry>
+
               <entry>3.0.10</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.1</entry>
             </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 'SHOW VARIABLES'
+              and 'SHOW COLLATION' on a per-URL basis?</entry>
+
               <entry>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.5</entry>
             </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>No</entry>
+
               <entry>0</entry>
+
               <entry>3.1.9</entry>
             </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 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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.7</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.5</entry>
             </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
+              Connection.setAutoCommit(boolean)?</entry>
+
               <entry>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.3</entry>
             </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 Statement.close()
+              as required by the JDBC specification?</entry>
+
               <entry>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.7</entry>
             </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>No</entry>
+
               <entry>1048576</entry>
+
               <entry>3.2.1</entry>
             </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>No</entry>
+
               <entry>true</entry>
+
               <entry>3.1.4</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.7</entry>
             </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>No</entry>
+
               <entry>true</entry>
+
               <entry>3.1.5</entry>
             </row>
+
             <row>
               <entry
               spanname="cj_propstbl_span_all_cols"><emphasis>Debuging/Profiling</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>No</entry>
+
               <entry>com.mysql.jdbc.log.StandardLogger</entry>
+
               <entry>3.1.1</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.0</entry>
             </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>No</entry>
+
               <entry>30000</entry>
+
               <entry>3.1.2</entry>
             </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>No</entry>
+
               <entry>2048</entry>
+
               <entry>3.1.3</entry>
             </row>
+
             <row>
               <entry>packetDebugBufferSize</entry>
-              <entry>The maximum number of packets to retain when 'enablePacketDebug' is true</entry>
+
+              <entry>The maximum number of packets to retain when
+              'enablePacketDebug' is true</entry>
+
               <entry>No</entry>
+
               <entry>20</entry>
+
               <entry>3.1.3</entry>
             </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>No</entry>
+
               <entry>2000</entry>
+
               <entry>3.1.2</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.1</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.9</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.13</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.3</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.3</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.2</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.2</entry>
             </row>
+
             <row>
               <entry>traceProtocol</entry>
+
               <entry>Should trace-level network protocol be logged?</entry>
+
               <entry>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.2</entry>
             </row>
+
             <row>
               <entry
               spanname="cj_propstbl_span_all_cols"><emphasis>Miscellaneous</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>No</entry>
+
               <entry>true</entry>
+
               <entry>1.1g</entry>
             </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>If 'useUnicode' is set to true, what character encoding
+              should the driver use when dealing with strings? (defaults is to
+              'autodetect')</entry>
+
               <entry>No</entry>
+
               <entry></entry>
+
               <entry>1.1g</entry>
             </row>
+
             <row>
               <entry>characterSetResults</entry>
-              <entry>Character set to tell the server to return results as.</entry>
+
+              <entry>Character set to tell the server to return results
+              as.</entry>
+
               <entry>No</entry>
+
               <entry></entry>
+
               <entry>3.0.13</entry>
             </row>
+
             <row>
               <entry>connectionCollation</entry>
+
               <entry>If set, tells the server to use this collation via 'set
-                collation_connection'</entry>
+              collation_connection'</entry>
+
               <entry>No</entry>
+
               <entry></entry>
+
               <entry>3.0.13</entry>
             </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>A comma-separated list of name/value pairs to be sent as
+              SET SESSION ... to the server when the driver connects.</entry>
+
               <entry>No</entry>
+
               <entry></entry>
+
               <entry>3.1.8</entry>
             </row>
+
             <row>
               <entry>allowNanAndInf</entry>
+
               <entry>Should the driver allow NaN or +/- INF values in
-                PreparedStatement.setDouble()?</entry>
+              PreparedStatement.setDouble()?</entry>
+
               <entry>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.5</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.12</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.5</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>2.0.7</entry>
             </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>The character encoding to use for sending and retrieving
+              TEXT, MEDIUMTEXT and LONGTEXT values instead of the configured
+              connection characterEncoding</entry>
+
               <entry>No</entry>
+
               <entry></entry>
+
               <entry>5.0.0</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.0.9</entry>
             </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>No</entry>
+
               <entry>true</entry>
+
               <entry>3.0.3</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.9</entry>
             </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>No</entry>
+
               <entry>true</entry>
+
               <entry>3.1.8</entry>
             </row>
+
             <row>
               <entry>emulateLocators</entry>
+
               <entry>N/A</entry>
+
               <entry>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.0</entry>
             </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>No</entry>
+
               <entry>true</entry>
+
               <entry>3.1.7</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.0.9</entry>
             </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>No</entry>
+
               <entry>true</entry>
+
               <entry>3.1.2</entry>
             </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>No</entry>
+
               <entry>-1</entry>
+
               <entry>all versions</entry>
             </row>
+
             <row>
               <entry>noDatetimeStringSync</entry>
+
               <entry>Don't ensure that
-                ResultSet.getDatetimeType().toString().equals(ResultSet.getString())</entry>
+              ResultSet.getDatetimeType().toString().equals(ResultSet.getString())</entry>
+
               <entry>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.7</entry>
             </row>
+
             <row>
               <entry>noTimezoneConversionForTimeType</entry>
+
               <entry>Don't convert TIME values using the server timezone if
-                'useTimezone'='true'</entry>
+              'useTimezone'='true'</entry>
+
               <entry>No</entry>
+
               <entry>false</entry>
+
               <entry>5.0.0</entry>
             </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>No</entry>
+
               <entry>true</entry>
+
               <entry>3.1.8</entry>
             </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>No</entry>
+
               <entry>true</entry>
+
               <entry>3.1.8</entry>
             </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>
+              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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.12</entry>
             </row>
+
             <row>
               <entry>pedantic</entry>
+
               <entry>Follow the JDBC spec to the letter.</entry>
+
               <entry>No</entry>
+
               <entry>false</entry>
+
               <entry>3.0.0</entry>
             </row>
+
             <row>
               <entry>processEscapeCodesForPrepStmts</entry>
-              <entry>Should the driver process escape codes in queries that are prepared?</entry>
+
+              <entry>Should the driver process escape codes in queries that
+              are prepared?</entry>
+
               <entry>No</entry>
+
               <entry>true</entry>
+
               <entry>3.1.12</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>2.0.13</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.11</entry>
             </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>No</entry>
+
               <entry>true</entry>
+
               <entry>3.0.15</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.7</entry>
             </row>
+
             <row>
               <entry>serverTimezone</entry>
-              <entry>Override detection/mapping of timezone. Used when timezone from server
-                doesn't map to Java timezone</entry>
+
+              <entry>Override detection/mapping of timezone. Used when
+              timezone from server doesn't map to Java timezone</entry>
+
               <entry>No</entry>
+
               <entry></entry>
+
               <entry>3.0.2</entry>
             </row>
+
             <row>
               <entry>strictFloatingPoint</entry>
+
               <entry>Used only in older versions of compliance test</entry>
+
               <entry>No</entry>
+
               <entry>false</entry>
+
               <entry>3.0.0</entry>
             </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>No</entry>
+
               <entry>true</entry>
+
               <entry>3.0.4</entry>
             </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>No</entry>
+
               <entry>true</entry>
+
               <entry>3.0.16</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.9</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>2.0.3</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.12</entry>
             </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>No</entry>
+
               <entry>true</entry>
+
               <entry>3.0.2</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>5.0.0</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>5.0.0</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.1.6</entry>
             </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>No</entry>
+
               <entry>true</entry>
+
               <entry>3.0.15</entry>
             </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>No</entry>
+
               <entry>true</entry>
+
               <entry>3.1.0</entry>
             </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>No</entry>
+
               <entry>true</entry>
+
               <entry>3.1.3</entry>
             </row>
+
             <row>
               <entry>useStreamLengthsInPrepStmts</entry>
+
               <entry>Honor stream length parameter in
-                PreparedStatement/ResultSet.setXXXStream() method calls
-                (true/false, defaults to 'true')?</entry>
+              PreparedStatement/ResultSet.setXXXStream() method calls
+              (true/false, defaults to 'true')?</entry>
+
               <entry>No</entry>
+
               <entry>true</entry>
+
               <entry>3.0.2</entry>
             </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>No</entry>
+
               <entry>false</entry>
+
               <entry>3.0.2</entry>
             </row>
+
             <row>
               <entry>useUnbufferedInput</entry>
-              <entry>Don't use BufferedInputStream for reading data from the server</entry>
+
+              <entry>Don't use BufferedInputStream for reading data from the
+              server</entry>
+
               <entry>No</entry>
+
               <entry>true</entry>
+
               <entry>3.0.11</entry>
             </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>No</entry>
+
               <entry>true</entry>
+
               <entry>3.1.9</entry>
             </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>No</entry>
+
               <entry>exception</entry>
+
               <entry>3.1.4</entry>
             </row>
           </tbody>
         </tgroup>
-
       </table>
 
-      <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.
-      </para>
+      <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.</para>
 
-      <para>
-        Adding the following property to your URL will enable the
-        NamedPipeSocketFactory:
-      </para>
+      <para>Adding the following property to your URL will enable the
+      NamedPipeSocketFactory:</para>
 
-      <para>
-        socketFactory=com.mysql.jdbc.NamedPipeSocketFactory
-      </para>
+      <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
-        access is between 30%-50% faster than the standard TCP/IP
-        access.
-      </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 access is between
+      30%-50% faster than the standard TCP/IP access.</para>
 
-      <para>
-        You can create your own socket factories by following the
-        example code in
-        <classname>com.mysql.jdbc.NamedPipeSocketFactory</classname>, or
-        <classname>com.mysql.jdbc.StandardSocketFactory</classname>.
-      </para>
-
+      <para>You can create your own socket factories by following the example
+      code in <classname>com.mysql.jdbc.NamedPipeSocketFactory</classname>, or
+      <classname>com.mysql.jdbc.StandardSocketFactory</classname>.</para>
     </section>
 
     <section id="cj-implementation-notes">
+      <title>JDBC API Implementation Notes</title>
 
-      <title>&title-cj-implementation-notes;</title>
+      <para>MySQL Connector/J passes all of the tests in the
+      publicly-available version of Sun's JDBC compliance test suite. However,
+      in many places the JDBC specification is vague about how certain
+      functionality should be implemented, or the specification allows leeway
+      in implementation.</para>
 
-      <para>
-        MySQL Connector/J passes all of the tests in the
-        publicly-available version of Sun's JDBC compliance test suite.
-        However, in many places the JDBC specification is vague about
-        how certain functionality should be implemented, or the
-        specification allows leeway in implementation.
-      </para>
+      <para>This section gives details on a interface-by-interface level about
+      how certain implementation decisions may affect how you use MySQL
+      Connector/J.</para>
 
-      <para>
-        This section gives details on a interface-by-interface level
-        about how certain implementation decisions may affect how you
-        use MySQL Connector/J.
-      </para>
-
       <itemizedlist>
-
         <listitem>
-          <para>
-            Blob
-          </para>
+          <para>Blob</para>
 
-          <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.
-          </para>
+          <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.</para>
 
-          <para>
-            Starting with Connector/J version 3.1.0, you can emulate
-            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.
-          </para>
+          <para>Starting with Connector/J version 3.1.0, you can emulate 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.</para>
         </listitem>
 
         <listitem>
-          <para>
-            CallableStatement
-          </para>
+          <para>CallableStatement</para>
 
-          <para>
-            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>
-            method of <classname>CallableStatement</classname> is not
-            supported.
-          </para>
+          <para>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> method of
+          <classname>CallableStatement</classname> is not supported.</para>
         </listitem>
 
         <listitem>
-          <para>
-            Clob
-          </para>
+          <para>Clob</para>
 
-          <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.
-          </para>
+          <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.</para>
         </listitem>
 
         <listitem>
-          <para>
-            Connection
-          </para>
+          <para>Connection</para>
 
-          <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.
-          </para>
+          <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.</para>
         </listitem>
 
         <listitem>
-          <para>
-            DatabaseMetaData
-          </para>
+          <para>DatabaseMetaData</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.
-          </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.</para>
         </listitem>
 
         <listitem>
-          <para>
-            Driver
-          </para>
+          <para>Driver</para>
         </listitem>
 
         <listitem>
-          <para>
-            PreparedStatement
-          </para>
+          <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.
-          </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.</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.
-          </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.</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:
-          </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:</para>
 
           <itemizedlist>
-
             <listitem>
-              <para>
-                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>
+              <para>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>
             </listitem>
-
           </itemizedlist>
 
           <itemizedlist>
-
             <listitem>
-              <para>
-                Once that has been done, the stream used to read the
-                data on the client side is closed (as per the JDBC
-                spec), and can't be read from again.
-              </para>
+              <para>Once that has been done, the stream used to read the data
+              on the client side is closed (as per the JDBC spec), and can't
+              be read from again.</para>
             </listitem>
-
           </itemizedlist>
 
           <itemizedlist>
-
             <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
-                server, thus requiring the data to be re-sent, via the
-                setBinaryStream(), setAsciiStream(), setUnicodeStream(),
-                setBlob() or setClob() methods.
-              </para>
+              <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 server, thus requiring the
+              data to be re-sent, via the setBinaryStream(), setAsciiStream(),
+              setUnicodeStream(), setBlob() or setClob() 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.
-          </para>
+          <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.</para>
         </listitem>
 
         <listitem>
-          <para>
-            ResultSet
-          </para>
+          <para>ResultSet</para>
 
-          <para>
-            By default, ResultSets are completely retrieved and stored
-            in memory. In most cases this is the most efficient way to
-            operate, and due to the design of the MySQL network protocol
-            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
-            at a time.
-          </para>
+          <para>By default, ResultSets are completely retrieved and stored in
+          memory. In most cases this is the most efficient way to operate, and
+          due to the design of the MySQL network protocol 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 at a time.</para>
 
-          <para>
-            To enable this functionality, you need to create a Statement
-            instance in the following manner:
-          </para>
+          <para>To enable this functionality, you need to create a Statement
+          instance in the following manner:</para>
 
-<programlisting>
+          <programlisting>
 stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY,
               java.sql.ResultSet.CONCUR_READ_ONLY);
 stmt.setFetchSize(Integer.MIN_VALUE);</programlisting>
 
-          <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.
-          </para>
+          <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.</para>
 
-          <para>
-            There are some caveats with this approach. You will have to
-            read all of the rows in the result set (or close it) before
-            you can issue any other queries on the connection, or an
-            exception will be thrown.
-          </para>
+          <para>There are some caveats with this approach. You will have to
+          read all of the rows in the result set (or close it) before you can
+          issue any other queries on the connection, or an exception will be
+          thrown.</para>
 
-          <para>
-            The earliest the locks these statements hold can be released
-            (whether they be <literal>MyISAM</literal> table-level locks
-            or row-level locks in some other storage engine such as
-            <literal>InnoDB</literal>) is when the statement completes.
-          </para>
+          <para>The earliest the locks these statements hold can be released
+          (whether they be <literal>MyISAM</literal> table-level locks or
+          row-level locks in some other storage engine such as
+          <literal>InnoDB</literal>) is when the statement completes.</para>
 
-          <para>
-            If the statement is within scope of a transaction, then
-            locks are released when the transaction completes (which
-            implies that the statement needs to complete first). As with
-            most other databases, statements are not complete until all
-            the results pending on the statement are read or the active
-            result set for the statement is closed.
-          </para>
+          <para>If the statement is within scope of a transaction, then locks
+          are released when the transaction completes (which implies that the
+          statement needs to complete first). As with most other databases,
+          statements are not complete until all the results pending on the
+          statement are read or the active result set for the statement is
+          closed.</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.
-          </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.</para>
         </listitem>
 
         <listitem>
-          <para>
-            ResultSetMetaData
-          </para>
+          <para>ResultSetMetaData</para>
 
-          <para>
-            The "isAutoIncrement()" method only works when using MySQL
-            servers 4.0 and newer.
-          </para>
+          <para>The "isAutoIncrement()" method only works when using MySQL
+          servers 4.0 and newer.</para>
         </listitem>
 
         <listitem>
-          <para>
-            Statement
-          </para>
+          <para>Statement</para>
 
-          <para>
-            When using versions of the JDBC driver earlier than 3.2.1,
-            and connected to server versions earlier than 5.0.3, the
-            "setFetchSize()" method has no effect, other than to toggle
-            result set streaming as described above.
-          </para>
+          <para>When using versions of the JDBC driver earlier than 3.2.1, and
+          connected to server versions earlier than 5.0.3, the
+          "setFetchSize()" method has no effect, other than to toggle result
+          set streaming as described above.</para>
 
-          <para>
-            MySQL does not support SQL cursors, and the JDBC driver
-            doesn't emulate them, so "setCursorName()" has no effect.
-          </para>
+          <para>MySQL does not support SQL cursors, and the JDBC driver
+          doesn't emulate them, so "setCursorName()" has no effect.</para>
         </listitem>
-
       </itemizedlist>
-
     </section>
 
     <section id="cj-type-conversions">
+      <title>Java, JDBC and MySQL Types</title>
 
-      <title>&title-cj-type-conversions;</title>
+      <para>MySQL Connector/J is flexible in the way it handles conversions
+      between MySQL data types and Java data types.</para>
 
-      <para>
-        MySQL Connector/J is flexible in the way it handles conversions
-        between MySQL data types and Java data types.
-      </para>
+      <para>In general, any MySQL data type can be converted to a
+      java.lang.String, and any numerical type can be converted to any of the
+      Java numerical types, although round-off, overflow, or loss of precision
+      may occur.</para>
 
-      <para>
-        In general, any MySQL data type can be converted to a
-        java.lang.String, and any numerical type can be converted to any
-        of the Java numerical types, although round-off, overflow, or
-        loss of precision may occur.
-      </para>
+      <para>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".</para>
 
-      <para>
-        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".
-      </para>
+      <para>The conversions that are always guaranteed to work are listed in
+      the following table:</para>
 
-      <para>
-        The conversions that are always guaranteed to work are listed in
-        the following table:
-      </para>
-
       <table>
-
         <title>Conversion Table</title>
 
         <tgroup cols="2">
           <thead>
-
             <row>
               <entry>These MySQL Data Types</entry>
+
               <entry>Can always be converted to these Java types</entry>
             </row>
-
           </thead>
+
           <tbody>
             <row>
-              <entry><type>CHAR, VARCHAR, BLOB, TEXT, ENUM, and SET</type></entry>
-              <entry><classname>java.lang.String, java.io.InputStream, java.io.Reader,
-                java.sql.Blob, java.sql.Clob</classname></entry>
+              <entry><type>CHAR, VARCHAR, BLOB, TEXT, ENUM, and
+              SET</type></entry>
+
+              <entry><classname>java.lang.String, java.io.InputStream,
+              java.io.Reader, java.sql.Blob, java.sql.Clob</classname></entry>
             </row>
+
             <row>
-              <entry><type>FLOAT, REAL, DOUBLE PRECISION, NUMERIC, DECIMAL, TINYINT,
-                SMALLINT, MEDIUMINT, INTEGER, BIGINT</type></entry>
-              <entry><classname>java.lang.String, java.lang.Short, java.lang.Integer,
-                java.lang.Long, java.lang.Double,
-                java.math.BigDecimal</classname>
+              <entry><type>FLOAT, REAL, DOUBLE PRECISION, NUMERIC, DECIMAL,
+              TINYINT, SMALLINT, MEDIUMINT, INTEGER, BIGINT</type></entry>
 
-                <note>
-
-                  <para>
-                    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>
-
+              <entry><classname>java.lang.String, java.lang.Short,
+              java.lang.Integer, java.lang.Long, java.lang.Double,
+              java.math.BigDecimal</classname> <note>
+                  <para>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>
                 </note></entry>
             </row>
+
             <row>
               <entry><type>DATE, TIME, DATETIME, TIMESTAMP</type></entry>
+
               <entry><classname>java.lang.String, java.sql.Date,
-                java.sql.Timestamp</classname></entry>
+              java.sql.Timestamp</classname></entry>
             </row>
           </tbody>
         </tgroup>
-
       </table>
 
-      <para>
-        The <classname>ResultSet.getObject()</classname> method uses the
-        following type conversions between MySQL and Java types,
-        following the JDBC specification where appropriate:
-      </para>
+      <para>The <classname>ResultSet.getObject()</classname> method uses the
+      following type conversions between MySQL and Java types, following the
+      JDBC specification where appropriate:</para>
 
-      <para>
-        <table>
-
+      <para><table>
           <title>MySQL Types to Java Types for ResultSet.getObject()</title>
 
           <tgroup cols="2">
             <thead>
-
               <row>
                 <entry>MySQL Type Name</entry>
+
                 <entry>Returned as Java Class</entry>
               </row>
-
             </thead>
+
             <tbody>
               <row>
                 <entry><type>BIT(1)</type> (new in MySQL-5.0)</entry>
+
                 <entry><classname>java.lang.Boolean</classname></entry>
               </row>
+
               <row>
                 <entry><type>BIT( &gt; 1)</type> (new in MySQL-5.0)</entry>
+
                 <entry><classname>byte[]</classname></entry>
               </row>
+
               <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
-                  <classname>java.lang.Integer</classname> if not.</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
+                <classname>java.lang.Integer</classname> if not.</entry>
               </row>
+
               <row>
                 <entry><type>BOOL , BOOLEAN</type></entry>
-                <entry>See <type>TINYINT</type>, above as these are aliases for
-                  <type>TINYINT(1)</type>, currently.</entry>
+
+                <entry>See <type>TINYINT</type>, above as these are aliases
+                for <type>TINYINT(1)</type>, currently.</entry>
               </row>
+
               <row>
                 <entry><type>SMALLINT[(M)] [UNSIGNED]</type></entry>
-                <entry><classname>java.lang.Integer</classname> (regardless if UNSIGNED or not)</entry>
+
+                <entry><classname>java.lang.Integer</classname> (regardless if
+                UNSIGNED or not)</entry>
               </row>
+
               <row>
                 <entry><type>MEDIUMINT[(M)] [UNSIGNED]</type></entry>
+
                 <entry><classname>java.lang.Integer,</classname> if UNSIGNED
-                  <classname>java.lang.Long</classname></entry>
+                <classname>java.lang.Long</classname></entry>
               </row>
+
               <row>
                 <entry><type>INT,INTEGER[(M)] [UNSIGNED]</type></entry>
+
                 <entry><classname>java.lang.Integer</classname>, if UNSIGNED
-                  <classname>java.lang.Long</classname></entry>
+                <classname>java.lang.Long</classname></entry>
               </row>
+
               <row>
                 <entry><type>BIGINT[(M)] [UNSIGNED]</type></entry>
+
                 <entry><classname>java.lang.Long</classname>, if UNSIGNED
-                  <classname>java.math.BigInteger</classname></entry>
+                <classname>java.math.BigInteger</classname></entry>
               </row>
+
               <row>
                 <entry><type>FLOAT[(M,D)]</type></entry>
+
                 <entry><classname>java.lang.Float</classname></entry>
               </row>
+
               <row>
                 <entry><type>DOUBLE[(M,B)]</type></entry>
+
                 <entry><classname>java.lang.Double</classname></entry>
               </row>
+
               <row>
                 <entry><type>DECIMAL[(M[,D])]</type></entry>
+
                 <entry><classname>java.math.BigDecimal</classname></entry>
               </row>
+
               <row>
                 <entry><type>DATE</type></entry>
+
                 <entry><classname>java.sql.Date</classname></entry>
               </row>
+
               <row>
                 <entry><type>DATETIME</type></entry>
+
                 <entry><classname>java.sql.Timestamp</classname></entry>
               </row>
+
               <row>
                 <entry><type>TIMESTAMP[(M)]</type></entry>
+
                 <entry><classname>java.sql.Timestamp</classname></entry>
               </row>
+
               <row>
                 <entry><type>TIME</type></entry>
+
                 <entry><classname>java.sql.Time</classname></entry>
               </row>
+
               <row>
                 <entry><type>YEAR[(2|4)]</type></entry>
-                <entry><classname>java.sql.Date</classname> (with the date set two January 1st,
-                  at midnight)</entry>
+
+                <entry><classname>java.sql.Date</classname> (with the date set
+                two January 1st, at midnight)</entry>
               </row>
+
               <row>
                 <entry><type>CHAR(M)</type></entry>
-                <entry><classname>java.lang.String</classname> (unless the character set for
-                  the column is <type>BINARY</type>, then
-                  <classname>byte[]</classname> is returned.</entry>
+
+                <entry><classname>java.lang.String</classname> (unless the
+                character set for the column is <type>BINARY</type>, then
+                <classname>byte[]</classname> is returned.</entry>
               </row>
+
               <row>
                 <entry><type>VARCHAR(M) [BINARY]</type></entry>
-                <entry><classname>java.lang.String</classname> (unless the character set for
-                  the column is <type>BINARY</type>, then
-                  <classname>byte[]</classname> is returned.</entry>
+
+                <entry><classname>java.lang.String</classname> (unless the
+                character set for the column is <type>BINARY</type>, then
+                <classname>byte[]</classname> is returned.</entry>
               </row>
+
               <row>
                 <entry><type>BINARY(M)</type></entry>
+
                 <entry><classname>byte[]</classname></entry>
               </row>
+
               <row>
                 <entry><type>VARBINARY(M)</type></entry>
+
                 <entry><classname>byte[]</classname></entry>
               </row>
+
               <row>
                 <entry><type>TINYBLOB</type></entry>
+
                 <entry><classname>byte[]</classname></entry>
               </row>
+
               <row>
                 <entry><type>TINYTEXT</type></entry>
+
                 <entry><classname>java.lang.String</classname></entry>
               </row>
+
               <row>
                 <entry><type>BLOB</type></entry>
+
                 <entry><classname>byte[]</classname></entry>
               </row>
+
               <row>
                 <entry><type>TEXT</type></entry>
+
                 <entry><classname>java.lang.String</classname></entry>
               </row>
+
               <row>
                 <entry><type>MEDIUMBLOB</type></entry>
+
                 <entry><classname>byte[]</classname></entry>
               </row>
+
               <row>
                 <entry><type>MEDIUMTEXT</type></entry>
+
                 <entry><classname>java.lang.String</classname></entry>
               </row>
+
               <row>
                 <entry><type>LONGBLOB</type></entry>
+
                 <entry><classname>byte[]</classname></entry>
               </row>
+
               <row>
                 <entry><type>LONGTEXT</type></entry>
+
                 <entry><classname>java.lang.String</classname></entry>
               </row>
+
               <row>
                 <entry><type>ENUM('value1','value2',...)</type></entry>
+
                 <entry><classname>java.lang.String</classname></entry>
               </row>
+
               <row>
                 <entry><type>SET('value1','value2',...)</type></entry>
+
                 <entry><classname>java.lang.String</classname></entry>
               </row>
             </tbody>
           </tgroup>
-
-        </table>
-      </para>
-
+        </table></para>
     </section>
 
     <section id="cj-character-sets">
+      <title>Using Character Sets and Unicode</title>
 
-      <title>&title-cj-character-sets;</title>
+      <para>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
+      <interfacename>PreparedStatement</interfacename> and
+      <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> .</para>
 
-      <para>
-        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
+      <para>Prior to MySQL Server 4.1, Connector/J supported a single
+      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>characterEncoding</parameter> " properties.</para>
 
-        <interfacename>PreparedStatement</interfacename>
+      <para>Starting with MySQL Server 4.1, Connector/J supports a single
+      character encoding between client and server, and any number of
+      character encodings for data returned by the server to the client in
+      <classname>ResultSets</classname>.</para>
 
-        and
+      <para>The character encoding between client and server is automatically
+      detected upon connection. The encoding used by the driver is specified
+      on the server via the configuration variable '
+      <parameter>character_set</parameter> ' for server versions older than
+      4.1.0 and ' <parameter>character_set_server</parameter> ' for server
+      versions 4.1.0 and newer. See the "<ulink
+      url="http://www.mysql.com/doc/en/Charset-server.html">Server Character
+      Set and Collation</ulink>" section in the MySQL server manual for more
+      information.</para>
 
-        <interfacename>CallableStatement</interfacename>
+      <para>To override the automatically-detected encoding on the client
+      side, use the <parameter>characterEncoding</parameter> property in the
+      URL used to connect to the server.</para>
 
-        parameters with the exclusion of parameters set using
-        <methodname>setBytes()</methodname>,
-        <methodname>setBinaryStream()</methodname>,
-        <methodname>setAsciiStream()</methodname>,
-        <methodname>setUnicodeStream()</methodname> and
-        <methodname>setBlob()</methodname> .
-      </para>
-
-      <para>
-        Prior to MySQL Server 4.1, Connector/J supported a single
-        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>characterEncoding</parameter>
-
-        " properties.
-      </para>
-
-      <para>
-        Starting with MySQL Server 4.1, Connector/J supports a single
-        character encoding between client and server, and any number of
-        character encodings for data returned by the server to the
-        client in <classname>ResultSets</classname>.
-      </para>
-
-      <para>
-        The character encoding between client and server is
-        automatically detected upon connection. The encoding used by the
-        driver is specified on the server via the configuration variable
-        '
-
-        <parameter>character_set</parameter>
-
-        ' for server versions older than 4.1.0 and '
-
-        <parameter>character_set_server</parameter>
-
-        ' for server versions 4.1.0 and newer. See the
-        "<ulink
-      url="http://www.mysql.com/doc/en/Charset-server.html">Server
-        Character Set and Collation</ulink>" section in the MySQL server
-        manual for more information.
-      </para>
-
-      <para>
-        To override the automatically-detected encoding on the client
-        side, use the
-
-        <parameter>characterEncoding</parameter>
-
-        property in the URL used to connect to the server.
-      </para>
-
-      <para>
-        When specifying character encodings on the client side,
-        Java-style names should be used. The following table lists
-        Java-style names for MySQL character sets:
-
-        <table>
-
+      <para>When specifying character encodings on the client side, Java-style
+      names should be used. The following table lists Java-style names for
+      MySQL character sets: <table>
           <title>MySQL to Java Encoding Name Translations</title>
 
           <tgroup cols="2">
             <thead>
-
               <row>
                 <entry>MySQL Character Set Name</entry>
+
                 <entry>Java-Style Character Encoding Name</entry>
               </row>
-
             </thead>
+
             <tbody>
               <row>
                 <entry>usa7</entry>
+
                 <entry>US-ASCII</entry>
               </row>
+
               <row>
                 <entry>big5</entry>
+
                 <entry>Big5</entry>
               </row>
+
               <row>
                 <entry>gbk</entry>
+
                 <entry>GBK</entry>
               </row>
+
               <row>
                 <entry>sjis</entry>
-                <entry>SJIS (or Cp932 or MS932 for MySQL Server &lt; 4.1.11)</entry>
+
+                <entry>SJIS (or Cp932 or MS932 for MySQL Server &lt;
+                4.1.11)</entry>
               </row>
+
               <row>
                 <entry>cp932</entry>
+
                 <entry>Cp932 or MS932 (MySQL Server &gt; 4.1.11)</entry>
               </row>
+
               <row>
                 <entry>gb2312</entry>
+
                 <entry>EUC_CN</entry>
               </row>
+
               <row>
                 <entry>ujis</entry>
+
                 <entry>EUC_JP</entry>
               </row>
+
               <row>
                 <entry>euc_kr</entry>
+
                 <entry>EUC_KR</entry>
               </row>
+
               <row>
                 <entry>latin1</entry>
+
                 <entry>ISO8859_1</entry>
               </row>
+
               <row>
                 <entry>latin1_de</entry>
+
                 <entry>ISO8859_1</entry>
               </row>
+
               <row>
                 <entry>german1</entry>
+
                 <entry>ISO8859_1</entry>
               </row>
+
               <row>
                 <entry>danish</entry>
+
                 <entry>ISO8859_1</entry>
               </row>
+
               <row>
                 <entry>latin2</entry>
+
                 <entry>ISO8859_2</entry>
               </row>
+
               <row>
                 <entry>czech</entry>
+
                 <entry>ISO8859_2</entry>
               </row>
+
               <row>
                 <entry>hungarian</entry>
+
                 <entry>ISO8859_2</entry>
               </row>
+
               <row>
                 <entry>croat</entry>
+
                 <entry>ISO8859_2</entry>
               </row>
+
               <row>
                 <entry>greek</entry>
+
                 <entry>ISO8859_7</entry>
               </row>
+
               <row>
                 <entry>hebrew</entry>
+
                 <entry>ISO8859_8</entry>
               </row>
+
               <row>
                 <entry>latin5</entry>
+
                 <entry>ISO8859_9</entry>
               </row>
+
               <row>
                 <entry>latvian</entry>
+
                 <entry>ISO8859_13</entry>
               </row>
+
               <row>
                 <entry>latvian1</entry>
+
                 <entry>ISO8859_13</entry>
               </row>
+
               <row>
                 <entry>estonia</entry>
+
                 <entry>ISO8859_13</entry>
               </row>
+
               <row>
                 <entry>dos</entry>
+
                 <entry>Cp437</entry>
               </row>
+
               <row>
                 <entry>pclatin2</entry>
+
                 <entry>Cp852</entry>
               </row>
+
               <row>
                 <entry>cp866</entry>
+
                 <entry>Cp866</entry>
               </row>
+
               <row>
                 <entry>koi8_ru</entry>
+
                 <entry>KOI8_R</entry>
               </row>
+
               <row>
                 <entry>tis620</entry>
+
                 <entry>TIS620</entry>
               </row>
+
               <row>
                 <entry>win1250</entry>
+
                 <entry>Cp1250</entry>
               </row>
+
               <row>
                 <entry>win1250ch</entry>
+
                 <entry>Cp1250</entry>
               </row>
+
               <row>
                 <entry>win1251</entry>
+
                 <entry>Cp1251</entry>
               </row>
+
               <row>
                 <entry>cp1251</entry>
+
                 <entry>Cp1251</entry>
               </row>
+
               <row>
                 <entry>win1251ukr</entry>
+
                 <entry>Cp1251</entry>
               </row>
+
               <row>
                 <entry>cp1257</entry>
+
                 <entry>Cp1257</entry>
               </row>
+
               <row>
                 <entry>macroman</entry>
+
                 <entry>MacRoman</entry>
               </row>
+
               <row>
                 <entry>macce</entry>
+
                 <entry>MacCentralEurope</entry>
               </row>
+
               <row>
                 <entry>utf8</entry>
+
                 <entry>UTF-8</entry>
               </row>
+
               <row>
                 <entry>ucs2</entry>
+
                 <entry>UnicodeBig</entry>
               </row>
             </tbody>
           </tgroup>
+        </table></para>
 
-        </table>
-      </para>
-
       <warning>
-
-        <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>
-
+        <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>
 
-      <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
-
-        <parameter>characterEncoding</parameter>
-
-        property.
-      </para>
-
+      <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 <parameter>characterEncoding</parameter>
+      property.</para>
     </section>
 
-<!--
+    <!--
       <section id="cj-usage-advisor">
         <title>&title-cj-usage-advisor;</title>
 
@@ -3315,75 +3597,53 @@
 -->
 
     <section id="cj-using-ssl">
+      <title>Connecting Securely Using SSL</title>
 
-      <title>&title-cj-using-ssl;</title>
+      <para>SSL in MySQL Connector/J encrypts all data (other than the initial
+      handshake) between the JDBC driver and the server. The performance
+      penalty for enabling SSL is an increase in query processing time between
+      35% and 50%, depending on the size of the query, and the amount of data
+      it returns.</para>
 
-      <para>
-        SSL in MySQL Connector/J encrypts all data (other than the
-        initial handshake) between the JDBC driver and the server. The
-        performance penalty for enabling SSL is an increase in query
-        processing time between 35% and 50%, depending on the size of
-        the query, and the amount of data it returns.
-      </para>
+      <para>For SSL Support to work, you must have the following:</para>
 
-      <para>
-        For SSL Support to work, you must have the following:
-      </para>
-
       <itemizedlist>
-
         <listitem>
-          <para>
-            A JDK that includes JSSE (Java Secure Sockets Extension),
-            like JDK-1.4.1 or newer. SSL does not currently work with a
-            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">http://developer.java.sun.com/developer/bugParade/bugs/4273544.html</ulink>
-          </para>
+          <para>A JDK that includes JSSE (Java Secure Sockets Extension), like
+          JDK-1.4.1 or newer. SSL does not currently work with a 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">http://developer.java.sun.com/developer/bugParade/bugs/4273544.html</ulink></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">http://www.mysql.com/doc/en/Secure_connections.html</ulink>
-          </para>
+          <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">http://www.mysql.com/doc/en/Secure_connections.html</ulink></para>
         </listitem>
 
         <listitem>
-          <para>
-            A client certificate (covered later in this section)
-          </para>
+          <para>A client certificate (covered later in this section)</para>
         </listitem>
-
       </itemizedlist>
 
-      <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.
-      </para>
+      <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.</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):
-      </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):</para>
 
-<programlisting>shell&gt; keytool -import -alias mysqlServerCACert -file cacert.pem -keystore truststore
+      <programlisting>shell&gt; keytool -import -alias mysqlServerCACert -file cacert.pem -keystore truststore
         </programlisting>
 
-      <para>
-        Keytool will respond with the following information:
-      </para>
+      <para>Keytool will respond with the following information:</para>
 
-<programlisting>Enter keystore password:  *********
+      <programlisting>Enter keystore password:  *********
 Owner: EMAILADDRESS=walrus@stripped, CN=Walrus, O=MySQL AB, L=Orenburg, ST=Some
 -State, C=RU
 Issuer: EMAILADDRESS=walrus@stripped, CN=Walrus, O=MySQL AB, L=Orenburg, ST=Som
@@ -3396,24 +3656,18 @@
 Trust this certificate? [no]:  yes
 Certificate was added to keystore</programlisting>
 
-      <para>
-        You will then need to generate a client certificate, so that the
-        MySQL server knows that it is talking to a secure client:
-      </para>
+      <para>You will then need to generate a client certificate, so that the
+      MySQL server knows that it is talking to a secure client:</para>
 
-<programlisting> shell&gt; keytool -genkey -keyalg rsa -alias mysqlClientCertificate -keystore keystore </programlisting>
+      <programlisting> shell&gt; keytool -genkey -keyalg rsa -alias mysqlClientCertificate -keystore keystore </programlisting>
 
-      <para>
-        Keytool will prompt you for the following information, and
-        create a keystore named 'keystore' in the current directory.
-      </para>
+      <para>Keytool will prompt you for the following information, and create
+      a keystore named 'keystore' in the current directory.</para>
 
-      <para>
-        You should respond with information that is appropriate for your
-        situation:
-      </para>
+      <para>You should respond with information that is appropriate for your
+      situation:</para>
 
-<programlisting>Enter keystore password:  *********
+      <programlisting>Enter keystore password:  *********
 What is your first and last name?
   [Unknown]:  Matthews
 What is the name of your organizational unit?
@@ -3433,35 +3687,28 @@
 Enter key password for &lt;mysqlClientCertificate&gt;
         (RETURN if same as keystore password):</programlisting>
 
-      <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.
-      </para>
+      <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.</para>
 
-<programlisting>-Djavax.net.ssl.keyStore=path_to_keystore_file
+      <programlisting>-Djavax.net.ssl.keyStore=path_to_keystore_file
 -Djavax.net.ssl.keyStorePassword=*********
 -Djavax.net.ssl.trustStore=path_to_truststore_file
 -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().
-      </para>
+      <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().</para>
 
-      <para>
-        You can test that SSL is working by turning on JSSE debugging
-        (as detailed below), and look for the following key events:
-      </para>
+      <para>You can test that SSL is working by turning on JSSE debugging (as
+      detailed below), and look for the following key events:</para>
 
-<programlisting>...
+      <programlisting>...
  *** ClientHello, v3.1
  RandomCookie:  GMT: 1018531834 bytes = { 199, 148, 180, 215, 74, 12, 54, 244, 0, 168, 55, 103, 215, 64, 16, 138, 225, 190, 132, 153, 2, 217, 219, 239, 202, 19, 121, 78 }
  Session ID:  {}
@@ -3492,67 +3739,50 @@
  main, READ:  SSL v3.1 Handshake, length = 1712
  ...</programlisting>
 
-      <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.
-      </para>
-
+      <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.</para>
     </section>
 
     <section id="cj-replication-connection">
+      <title>Using Master/Slave Replication with ReplicationConnection</title>
 
-      <title>&title-cj-replication-connection;</title>
+      <para>Starting with Connector/J 3.1.7, we've made available a variant 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> .</para>
 
-      <para>
-        Starting with Connector/J 3.1.7, we've made available a variant
-        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> .
-      </para>
+      <para>An application signals that it wants a transaction to be read-only
+      by calling <function>Connection.setReadOnly(true)</function>, 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 <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 "time-sensitive" (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.</para>
 
-      <para>
-        An application signals that it wants a transaction to be
-        read-only by calling
-        <function>Connection.setReadOnly(true)</function>, 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 <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 "time-sensitive"
-        (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.
-      </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 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> .</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
-        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> .
-      </para>
+      <para>Here is a short, simple example of how ReplicationDriver might be
+      used in a standalone application.</para>
 
-      <para>
-        Here is a short, simple example of how ReplicationDriver might
-        be used in a standalone application.
-      </para>
-
-<programlisting id="cj-using-replication-driver-example">import java.sql.Connection;
+      <programlisting id="cj-using-replication-driver-example">import java.sql.Connection;
 import java.sql.ResultSet;
 import java.util.Properties;
 
@@ -3607,150 +3837,107 @@
     }
 }
 </programlisting>
-
     </section>
-
   </section>
 
   <section id="cj-j2ee">
+    <title>Using Connector/J with J2EE and Other Java Frameworks</title>
 
-    <title>&title-cj-j2ee;</title>
+    <para>This section describes how to use Connector/J in several
+    contexts.</para>
 
-    <para>
-      This section describes how to use Connector/J in several contexts.
-    </para>
-
     <section id="cj-general-j2ee-concepts">
+      <title>General J2EE Concepts</title>
 
-      <title>&title-cj-general-j2ee-concepts;</title>
+      <para>This section provides general background on J2EE concepts that
+      pertain to use of Connector/J.</para>
 
-      <para>
-        This section provides general background on J2EE concepts that
-        pertain to use of Connector/J.
-      </para>
-
       <section id="cj-connection-pooling">
+        <title>Understanding Connection Pooling</title>
 
-        <title>&title-cj-connection-pooling;</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>
-          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 <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.</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.
-        </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>
-          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
+        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.</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 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.
-        </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>
 
-        <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>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>
+            <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>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>
+            <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>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>
+            <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>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>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>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:
+        <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>
+            <title>Using a Connection Pool with a J2EE Application
+            Server</title>
 
-          <example>
-
-            <title>Using a Connection Pool with a J2EE Application Server</title>
-
-<programlisting>import java.sql.Connection;
+            <programlisting>import java.sql.Connection;
 import java.sql.SQLException;
 import java.sql.Statement;
 
@@ -3844,95 +4031,69 @@
         }
     }
 }</programlisting>
+          </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>
 
-          </example>
+        <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>
 
-          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>What's the Best Size for my Connection Pool?</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>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>
-          What's the Best Size for my Connection Pool?
-        </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>
-          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>
-          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>
-
+        <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 id="cj-understanding-transactions">
           <title>&title-cj-understanding-transactions;</title>
 
           <para />
         </section>
 -->
-
     </section>
 
     <section id="cj-tomcat-config">
+      <title>Using Connector/J with Tomcat</title>
 
-      <title>&title-cj-tomcat-config;</title>
-
-      <para>
-        The following instructions are based on the instructions for
-        Tomcat-5.x, available at
-        <ulink
+      <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">http://jakarta.apache.org/tomcat/tomcat-5.0-doc/jndi-datasource-examples-howto.html</ulink>
-        which is current at the time this document was written.
-      </para>
+      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;
+      <programlisting>&lt;Context ....&gt;
 
   ...
 
@@ -4058,37 +4219,30 @@
   &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
+      <programlisting>Error: java.sql.SQLException: Cannot load JDBC driver class 'null ' SQL
 state: null </programlisting>
-
     </section>
 
     <section id="cj-jboss-config">
+      <title>Using Connector/J with JBoss</title>
 
-      <title>&title-cj-jboss-config;</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 <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>
-
-<programlisting>&lt;datasources&gt;
+      <programlisting>&lt;datasources&gt;
     &lt;local-tx-datasource&gt;
         &lt;!-- This connection pool will be bound into JNDI with the name
              "java:/MySQLDB" --&gt;
@@ -4124,10 +4278,9 @@
 
     &lt;/local-tx-datasource&gt;
 &lt;/datasources&gt; </programlisting>
-
     </section>
 
-<!--
+    <!--
       <section id="cj-hibernate-config">
         <title>&title-cj-hibernate-config;</title>
 
@@ -4135,7 +4288,7 @@
       </section>
 -->
 
-<!--
+    <!--
       <section id="cj-spring-config">
         <title>&title-cj-spring-config;</title>
 
@@ -4143,7 +4296,7 @@
       </section>
 -->
 
-<!--
+    <!--
       <section id="cj-struts-config">
         <title>&title-cj-struts-config;</title>
 
@@ -4152,7 +4305,7 @@
 
 -->
 
-<!--
+    <!--
       <section id="cj-weblogic-config">
         <title>&title-cj-weblogic-config;</title>
 
@@ -4160,7 +4313,7 @@
       </section>
 -->
 
-<!--
+    <!--
       <section id="cj-websphere-config">
         <title>&title-cj-websphere-config;</title>
 
@@ -4168,169 +4321,115 @@
       </section>
 -->
 
-<!--
+    <!--
       <section id="cj-ias-config">
         <title>&title-cj-ias-config;</title>
 
         <para />
       </section>
 -->
-
   </section>
 
   <section id="cj-troubleshooting">
+    <title>Diagnosing Connector/J Problems</title>
 
-    <title>&title-cj-troubleshooting;</title>
+    <para>This section describes how to solve problems that you may encounter
+    when using Connector/J.</para>
 
-    <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>
 
-      <title>&title-cj-faq;</title>
+      <para>There are a few issues that seem to be commonly encountered often
+      by users of MySQL Connector/J. This section deals with their symptoms,
+      and their resolutions. If you have further issues, see the "SUPPORT"
+      section.</para>
 
-      <para>
-        There are a few issues that seem to be commonly encountered
-        often by users of MySQL Connector/J. This section deals with
-        their symptoms, and their resolutions. If you have further
-        issues, see the "SUPPORT" section.
-      </para>
-
       <qandaset>
-
         <qandaentry>
-
           <question>
+            <para>When I try to connect to the database with MySQL
+            Connector/J, I get the following exception:</para>
 
-            <para>
-              When I try to connect to the database with MySQL
-              Connector/J, I get the following exception:
-            </para>
-
             <screen>SQLException: Server configuration denies access to data source
 SQLState: 08001
 VendorError: 0</screen>
 
-            <para>
-              What's going on? I can connect just fine with the MySQL
-              command-line client.
-            </para>
-
+            <para>What's going on? I can connect just fine with the MySQL
+            command-line client.</para>
           </question>
 
           <answer>
+            <para>MySQL Connector/J must use TCP/IP sockets to connect to
+            MySQL, as Java does not support Unix Domain Sockets. Therefore,
+            when MySQL Connector/J connects to MySQL, the security manager in
+            MySQL server will use its grant tables to determine whether or not
+            the connection should be allowed.</para>
 
-            <para>
-              MySQL Connector/J must use TCP/IP sockets to connect to
-              MySQL, as Java does not support Unix Domain Sockets.
-              Therefore, when MySQL Connector/J connects to MySQL, the
-              security manager in MySQL server will use its grant tables
-              to determine whether or not the connection should be
-              allowed.
-            </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).</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).
-            </para>
+            <para>From the mysql command-line client, logged in as a user that
+            can grant privileges, issue the following command:</para>
 
-            <para>
-              From the mysql command-line client, logged in as a user
-              that can grant privileges, issue the following command:
-            </para>
-
             <screen>GRANT ALL PRIVILEGES ON [dbname].* to
                 '[user]'@'[hostname]' identified by
                 '[password]'</screen>
 
-            <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>
+            <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
-                work unless you add the <option>--host</option> flag,
-                and use something other than
-                <literal>localhost</literal> for the host. The
-                <command>mysql</command> command-line client will use
-                Unix domain sockets if you use the special hostname
-                <literal>localhost</literal>. If you are testing
-                connectivity to <literal>localhost</literal>, use
-                <literal>127.0.0.1</literal> as the hostname instead.
-              </para>
-
+              <para>Testing your connectivity with the
+              <command>mysql</command> command-line client will not work
+              unless you add the <option>--host</option> flag, and use
+              something other than <literal>localhost</literal> for the host.
+              The <command>mysql</command> command-line client will use Unix
+              domain sockets if you use the special hostname
+              <literal>localhost</literal>. If you are testing 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
+              <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>
+              Security Issues and the MySQL Access Privilege System'</ulink>
+              section of the MySQL manual before attempting to change
+              privileges.</para>
 
-              <para>
-                Changing privileges and permissions improperly in MySQL
-                can potentially cause your server installation to not
-                have optimal security properties.
-              </para>
-
+              <para>Changing privileges and permissions improperly in MySQL
+              can potentially cause your server installation to not have
+              optimal security properties.</para>
             </warning>
-
           </answer>
-
         </qandaentry>
 
         <qandaentry>
-
           <question>
-
-            <para>
-              My application throws an SQLException 'No Suitable
-              Driver'. Why is this happening?
-            </para>
-
+            <para>My application throws an SQLException 'No Suitable Driver'.
+            Why is this happening?</para>
           </question>
 
           <answer>
-
-            <para>
-              One of two things are happening. Either the driver is not
-              in your CLASSPATH (see the "INSTALLATION" section above),
-              or your URL format is incorrect (see "Developing
-              Applications with MySQL Connector/J").
-            </para>
-
+            <para>One of two things are happening. Either the driver is not in
+            your CLASSPATH (see the "INSTALLATION" section above), or your URL
+            format is incorrect (see "Developing Applications with MySQL
+            Connector/J").</para>
           </answer>
-
         </qandaentry>
 
         <qandaentry>
-
           <question>
+            <para>I'm trying to use MySQL Connector/J in an applet or
+            application and I get an exception similar to:</para>
 
-            <para>
-              I'm trying to use MySQL Connector/J in an applet or
-              application and I get an exception similar to:
-            </para>
-
             <screen>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?
@@ -4338,98 +4437,70 @@
 (java.security.AccessControlException)
 SQLState: 08S01
 VendorError: 0 </screen>
-
           </question>
 
           <answer>
+            <para>Either you're running an Applet, your MySQL server has been
+            installed with the "--skip-networking" option set, or your MySQL
+            server has a firewall sitting in front of it.</para>
 
-            <para>
-              Either you're running an Applet, your MySQL server has
-              been installed with the "--skip-networking" option set, or
-              your MySQL server has a firewall sitting in front of it.
-            </para>
+            <para>Applets can only make network connections back to the
+            machine that runs the web server that served the .class files for
+            the applet. This means that MySQL must run on the same machine (or
+            you must have some sort of port re-direction) for this to work.
+            This also means that you will not be able to test applets from
+            your local file system, you must always deploy them to a web
+            server.</para>
 
-            <para>
-              Applets can only make network connections back to the
-              machine that runs the web server that served the .class
-              files for the applet. This means that MySQL must run on
-              the same machine (or you must have some sort of port
-              re-direction) for this to work. This also means that you
-              will not be able to test applets from your local file
-              system, you must always deploy them to a web server.
-            </para>
+            <para>MySQL Connector/J can only communicate with MySQL using
+            TCP/IP, as Java does not support Unix domain sockets. TCP/IP
+            communication with MySQL might be affected if MySQL was started
+            with the "--skip-networking" flag, or if it is firewalled.</para>
 
-            <para>
-              MySQL Connector/J can only communicate with MySQL using
-              TCP/IP, as Java does not support Unix domain sockets.
-              TCP/IP communication with MySQL might be affected if MySQL
-              was started with the "--skip-networking" flag, or if it is
-              firewalled.
-            </para>
-
-            <para>
-              If MySQL has been started with the "--skip-networking"
-              option set (the Debian Linux package of MySQL server does
-              this for example), you need to comment it out in the file
-              /etc/mysql/my.cnf or /etc/my.cnf. Of course your my.cnf
-              file might also exist in the <filename>data</filename>
-              directory of your MySQL server, or anywhere else
-              (depending on how MySQL was compiled for your system).
-              Binaries created by MySQL AB always look in /etc/my.cnf
-              and [datadir]/my.cnf. If your MySQL server has been
-              firewalled, you will need to have the firewall configured
-              to allow TCP/IP connections from the host where your Java
-              code is running to the MySQL server on the port that MySQL
-              is listening to (by default, 3306).
-            </para>
-
+            <para>If MySQL has been started with the "--skip-networking"
+            option set (the Debian Linux package of MySQL server does this for
+            example), you need to comment it out in the file /etc/mysql/my.cnf
+            or /etc/my.cnf. Of course your my.cnf file might also exist in the
+            <filename>data</filename> directory of your MySQL server, or
+            anywhere else (depending on how MySQL was compiled for your
+            system). Binaries created by MySQL AB always look in /etc/my.cnf
+            and [datadir]/my.cnf. If your MySQL server has been firewalled,
+            you will need to have the firewall configured to allow TCP/IP
+            connections from the host where your Java code is running to the
+            MySQL server on the port that MySQL is listening to (by default,
+            3306).</para>
           </answer>
-
         </qandaentry>
 
         <qandaentry>
-
           <question>
-
-            <para id="connector_j_wait_timeout_q_and_a">
-              I have a servlet/application that works fine for a day,
-              and then stops working overnight
-            </para>
-
+            <para id="connector_j_wait_timeout_q_and_a">I have a
+            servlet/application that works fine for a day, and then stops
+            working overnight</para>
           </question>
 
           <answer>
+            <para>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 "Developing
+            Applications with MySQL Connector/J").</para>
 
-            <para>
-              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
-              "Developing Applications with MySQL Connector/J").
-            </para>
+            <para>Also, you should be catching SQLExceptions in your
+            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 your APIDOCS) to "08S01"
+            when it encounters network-connectivity issues during the
+            processing of a query. Your application code should then attempt
+            to re-connect to MySQL at this point.</para>
 
-            <para>
-              Also, you should be catching SQLExceptions in your
-              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
-              your APIDOCS) to "08S01" when it encounters
-              network-connectivity issues during the processing of a
-              query. Your application code should then attempt to
-              re-connect to MySQL at this point.
-            </para>
+            <para>The following (simplistic) example shows what code that can
+            handle these exceptions might look like:</para>
 
-            <para>
-              The following (simplistic) example shows what code that
-              can handle these exceptions might look like:
-            </para>
-
-            <para>
-              <example>
-
+            <para><example>
                 <title>Example of transaction with retry logic</title>
 
-<programlisting>public void doBusinessOp() throws SQLException {
+                <programlisting>public void doBusinessOp() throws SQLException {
         Connection conn = null;
         Statement stmt = null;
         ResultSet rs = null;
@@ -4548,45 +4619,29 @@
             }
         } while (!transactionCompleted &amp;&amp; (retryCount &gt; 0));
     }</programlisting>
-
-              </example>
-            </para>
-
+              </example></para>
           </answer>
-
         </qandaentry>
 
         <qandaentry>
-
           <question>
-
-            <para>
-              I'm trying to use JDBC-2.0 updatable result sets, and I
-              get an exception saying my result set is not updatable.
-            </para>
-
+            <para>I'm trying to use JDBC-2.0 updatable result sets, and I get
+            an exception saying my result set is not updatable.</para>
           </question>
 
           <answer>
-
-            <para>
-              Because MySQL does not have row identifiers, MySQL
-              Connector/J can only update result sets that have come
-              from queries on tables that have at least one primary key,
-              the query must select every primary key and the query can
-              only span one table (that is, no joins). This is outlined
-              in the JDBC specification.
-            </para>
-
+            <para>Because MySQL does not have row identifiers, MySQL
+            Connector/J can only update result sets that have come from
+            queries on tables that have at least one primary key, the query
+            must select every primary key and the query can only span one
+            table (that is, no joins). This is outlined in the JDBC
+            specification.</para>
           </answer>
-
         </qandaentry>
-
       </qandaset>
-
     </section>
 
-<!--
+    <!--
       <section id="cj-tracing">
         <title>&title-cj-tracing;</title>
 
@@ -4595,206 +4650,142 @@
 -->
 
     <section id="cj-reporting-bugs">
+      <title>How to Report Connector/J Bugs or Problems</title>
 
-      <title>&title-cj-reporting-bugs;</title>
+      <para>The normal place to report bugs is <ulink
+      url="http://bugs.mysql.com/">http://bugs.mysql.com/</ulink>, 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>
-        The normal place to report bugs is
-        <ulink
-      url="http://bugs.mysql.com/">http://bugs.mysql.com/</ulink>,
-        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@stripped">security@stripped</ulink>.</para>
 
-      <para>
-        If you have found a sensitive security bug in MySQL, you can
-        send email to
-        <ulink
-      url="mailto:security@stripped">security@stripped</ulink>.
-      </para>
+      <para>Writing a good bug report takes patience, but doing it right the
+      first time saves time both for us and for yourself. A good bug report,
+      containing a full test case for the bug, makes it very likely that we
+      will fix the bug in the next release.</para>
 
-      <para>
-        Writing a good bug report takes patience, but doing it right the
-        first time saves time both for us and for yourself. A good bug
-        report, containing a full test case for the bug, makes it very
-        likely that we will fix the bug in the next release.
-      </para>
+      <para>This section will help you write your report correctly so that you
+      don't waste your time doing things that may not help us much or at
+      all.</para>
 
-      <para>
-        This section will help you write your report correctly so that
-        you don't waste your time doing things that may not help us much
-        or at all.
-      </para>
+      <para>If you have a repeatable bug report, please report it to the bugs
+      database at <ulink url="???">http://bugs.mysql.com/</ulink>.</para>
 
-      <para>
-        If you have a repeatable bug report, please report it to the
-        bugs database at
-        <ulink url="???">http://bugs.mysql.com/</ulink>.
-      </para>
+      <para>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>
 
-      <para>
-        To report other problems, you can use one of the MySQL mailing
-        lists.
-      </para>
+      <para>Remember that it is possible for us to respond to a message
+      containing too much information, but not to one containing too little.
+      People often omit facts because they think they know the cause of a
+      problem and assume that some details don't matter.</para>
 
-      <para>
-        Remember that it is possible for us to respond to a message
-        containing too much information, but not to one containing too
-        little. People often omit facts because they think they know the
-        cause of a problem and assume that some details don't matter.
-      </para>
+      <para>A good principle is this: If you are in doubt about stating
+      something, state it. It is faster and less troublesome to write a couple
+      more lines in your report than to wait longer for the answer if we must
+      ask you to provide information that was missing from the initial
+      report.</para>
 
-      <para>
-        A good principle is this: If you are in doubt about stating
-        something, state it. It is faster and less troublesome to write
-        a couple more lines in your report than to wait longer for the
-        answer if we must ask you to provide information that was
-        missing from the initial report.
-      </para>
+      <para>The most common errors made in bug reports are (a) not including
+      the version number of Connector/J or MySQL used, and (b) not fully
+      describing the platform on which Connector/J is installed (including the
+      JVM version, and the platform type and version number that MySQL itself
+      is installed on).</para>
 
-      <para>
-        The most common errors made in bug reports are (a) not including
-        the version number of Connector/J or MySQL used, and (b) not
-        fully describing the platform on which Connector/J is installed
-        (including the JVM version, and the platform type and version
-        number that MySQL itself is installed on).
-      </para>
+      <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.</para>
 
-      <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.
-      </para>
+      <para>Sometimes the error is platform-dependent; in such cases, it is
+      next to impossible for us to fix anything without knowing the operating
+      system and the version number of the platform.</para>
 
-      <para>
-        Sometimes the error is platform-dependent; in such cases, it is
-        next to impossible for us to fix anything without knowing the
-        operating system and the version number of the platform.
-      </para>
+      <para>If at all possible, you should create a repeatable, stanalone
+      testcase that doesn't involve any third-party classes.</para>
 
-      <para>
-        If at all possible, you should create a repeatable, stanalone
-        testcase that doesn't involve any third-party classes.
-      </para>
+      <para>To streamline this process, we ship a base class for testcases
+      with Connector/J, named
+      '<classname>com.mysql.jdbc.util.BaseBugReport</classname>'. To 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>
+      ().</para>
 
-      <para>
-        To streamline this process, we ship a base class for testcases
-        with Connector/J, named
-        '<classname>com.mysql.jdbc.util.BaseBugReport</classname>'. To
-        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> ().
-      </para>
+      <para>In the <methodname>setUp()</methodname> method, create code that
+      creates your tables, and populates them with any data needed to
+      demonstrate the bug.</para>
 
-      <para>
-        In the <methodname>setUp()</methodname> 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.</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.
-      </para>
+      <para>In the <methodname>tearDown()</methodname> method, drop any tables
+      you created in the <methodname>setUp()</methodname> method.</para>
 
-      <para>
-        In the <methodname>tearDown()</methodname> method, drop any
-        tables you created in the <methodname>setUp()</methodname>
-        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:</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:
-      </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.
-          </para>
+          <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.</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).
-          </para>
+          <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).</para>
         </listitem>
 
         <listitem>
-          <para>
-            getConnection(String url) - Returns a connection using the
-            given URL.
-          </para>
+          <para>getConnection(String url) - 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.
-          </para>
+          <para>getConnection(String url, Properties props) - Returns a
+          connection using the given URL and properties.</para>
         </listitem>
-
       </itemizedlist>
 
-      <para>
-        If you need to use a JDBC URL that is different than
-        'jdbc:mysql:///test', then override the method
-        <methodname>getUrl()</methodname> as well.
-      </para>
+      <para>If you need to use a JDBC URL that is different than
+      'jdbc:mysql:///test', then override the method
+      <methodname>getUrl()</methodname> 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
-        expecting (vs. the behavior you are observing, which is why you
-        are most likely filing a bug report).
-      </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 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:
-      </para>
+      <para>Finally, create a <methodname>main</methodname> () method that
+      creates a new instance of your testcase, and calls the
+      <methodname>run</methodname> method:</para>
 
-<programlisting>public static void main(String[] args) throws Exception {
+      <programlisting>public static void main(String[] args) throws Exception {
       new MyBugReport().run();
  }</programlisting>
 
-      <para>
-        Once you have finished your testcase, and have verified that it
-        demonstrates the bug you are reporting, upload it with your bug
-        report to
-        <ulink
-      url="http://bugs.mysql.com/">http://bugs.mysql.com/</ulink>.
-      </para>
-
+      <para>Once you have finished your testcase, and have verified that it
+      demonstrates the bug you are reporting, upload it with your bug report
+      to <ulink
+      url="http://bugs.mysql.com/">http://bugs.mysql.com/</ulink>.</para>
     </section>
-
   </section>
 
   <xi:include href="../refman-common/news-connector-j.xml"
               xmlns:xi="http://www.w3.org/2001/XInclude" />
-
-</section>
+</section>
\ No newline at end of file

Thread
svn commit - mysqldoc@docsrva: r814 - trunk/refman-5.0mmatthews13 Jan