List:Commits« Previous MessageNext Message »
From:paul Date:January 13 2006 8:53pm
Subject:svn commit - mysqldoc@docsrva: r816 - in trunk: . refman-4.1 refman-5.0 refman-5.1 refman-common
View as plain text  
Author: paul
Date: 2006-01-13 21:53:45 +0100 (Fri, 13 Jan 2006)
New Revision: 816

Log:
 r2173@kite-hub:  paul | 2006-01-13 14:53:25 -0600
 Add markup.


Modified:
   trunk/
   trunk/refman-4.1/connector-j.xml
   trunk/refman-5.0/connector-j.xml
   trunk/refman-5.1/connector-j.xml
   trunk/refman-common/titles.en.ent


Property changes on: trunk
___________________________________________________________________
Name: svk:merge
   - b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:6161
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:2168
   + b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:6161
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:2173

Modified: trunk/refman-4.1/connector-j.xml
===================================================================
--- trunk/refman-4.1/connector-j.xml	2006-01-13 20:11:16 UTC (rev 815)
+++ trunk/refman-4.1/connector-j.xml	2006-01-13 20:53:45 UTC (rev 816)
@@ -1363,6 +1363,141 @@
 
     </section>
 
+    <section id="cj-installing-source">
+
+      <title>&title-cj-installing-source;</title>
+
+      <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>
+
+      <para>
+        To install MySQL Connector/J from the development source tree,
+        make sure that you have the following prerequisites:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Subversion, to check out the sources from our repository
+            (available from
+            <ulink url="http://subversion.tigris.org/"/>).
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Apache Ant version 1.6 or newer (available from
+            <ulink url="http://ant.apache.org/"/>).
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            JDK-1.4.2 or later. Although MySQL Connector/J can be
+            installed on older JDKs, to compile it from source you must
+            have at least JDK-1.4.2.
+          </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"/>. In
+        general, you should not check out the entire repository because
+        it contains every branch and tag for MySQL Connector/J and is
+        quite large.
+      </para>
+
+      <para>
+        To check out and compile a specific branch of MySQL Connector/J,
+        follow these steps:
+      </para>
+
+      <orderedlist>
+
+        <listitem>
+          <para>
+            At the time of this writing, there are three active branches
+            of Connector/J: <literal>branch_3_0</literal>,
+            <literal>branch_3_1</literal> and
+            <literal>branch_5_0</literal>. Check out the latest code
+            from the branch that you want with the following command
+            (replacing <replaceable>[major]</replaceable> and
+            <replaceable>[minor]</replaceable> with appropriate version
+            numbers):
+          </para>
+
+<programlisting>shell&gt; <userinput>svn co http://svn.mysql.com/svnpublic/connector-j/branches/branch_<replaceable>[major]</replaceable>_<replaceable>[minor]</replaceable>/connector-j</userinput></programlisting>
+
+          <para>
+            This creates a <filename>connector-j</filename> subdirectory
+            in the current directory that contains the latest sources
+            for the requested branch.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Change location to the <filename>connector-j</filename>
+            directory to make it your current working directory:
+          </para>
+
+<programlisting>shell&gt; <userinput>cd connector-j</userinput></programlisting>
+        </listitem>
+
+        <listitem>
+          <para>
+            Issue the following command to compile the driver and create
+            a <filename>.jar</filename> file suitable for installation:
+          </para>
+
+<programlisting>shell&gt; <userinput>ant dist</userinput></programlisting>
+
+          <para>
+            This creates a <filename>build</filename> directory in the
+            current directory, where all build output will go. A
+            directory is created in the <filename>build</filename>
+            directory that includes the version number of the sources
+            you are building from. This directory contains the sources,
+            compiled <filename>.class</filename> files, and a
+            <filename>.jar</filename> file suitable for deployment. For
+            other possible targets, including ones that will create a
+            fully packaged distribution, issue the following command:
+          </para>
+
+<programlisting>shell&gt; <userinput>ant --projecthelp</userinput></programlisting>
+        </listitem>
+
+        <listitem>
+          <para>
+            A newly created <filename>.jar</filename> file containing
+            the JDBC driver will be placed in the directory
+            <filename>build/mysql-connector-java-<replaceable>[version]</replaceable></filename>.
+          </para>
+
+          <para>
+            Install the newly created JDBC driver as you would a binary
+            <filename>.jar</filename> file that you download from MySQL
+            by following the instructions in
+            <xref linkend="cj-classpath"/>.
+          </para>
+        </listitem>
+
+      </orderedlist>
+
+    </section>
+
   </section>
 
   <section id="cj-jdbc-reference">

Modified: trunk/refman-5.0/connector-j.xml
===================================================================
--- trunk/refman-5.0/connector-j.xml	2006-01-13 20:11:16 UTC (rev 815)
+++ trunk/refman-5.0/connector-j.xml	2006-01-13 20:53:45 UTC (rev 816)
@@ -1,87 +1,116 @@
 <?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>
 
-  <para>MySQL provides connectivity for client applications developed in the
-  Java programming language via a JDBC driver, which is called MySQL
-  Connector/J.</para>
+  <title>&title-java-connector;</title>
 
-  <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 provides connectivity for client applications developed in the
+    Java programming language via a JDBC driver, which is called MySQL
+    Connector/J.
+  </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>
+    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>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 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 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>
+    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>
+
   <itemizedlist>
+
     <listitem>
-      <para><ulink
+      <para>
+        <ulink
       url="http://java.sun.com/docs/books/tutorial/jdbc/basics/index.html">JDBC
-      Basics </ulink> — A tutorial from Sun covering beginner topics in
-      JDBC</para>
+        Basics </ulink> &mdash; 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> — 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> &mdash; A more in-depth tutorial from Sun
+        and JGuru
+      </para>
     </listitem>
+
   </itemizedlist>
 
   <section id="cj-basic-jdbc">
-    <title>Basic JDBC concepts</title>
 
-    <para>This section provides some general JDBC background.</para>
+    <title>&title-cj-basic-jdbc;</title>
 
+    <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>
 
-      <para>When you are using JDBC outside of an application server, the
-      <literal>DriverManager</literal> class manages the establishment of
-      Connections.</para>
+      <title>&title-cj-connect-with-drivermanager;</title>
 
-      <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>
+        When you are using JDBC outside of an application server, the
+        <literal>DriverManager</literal> class manages the establishment
+        of Connections.
+      </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 <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>
 
-      <programlisting>import java.sql.Connection;
+      <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;
 import java.sql.DriverManager;
 import java.sql.SQLException;
 
@@ -100,24 +129,28 @@
         }
 }</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>
 
-        <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>
+        <title>Obtaining a Connection From the <literal>DriverManager</literal></title>
 
-        <programlisting>
+        <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>
 import java.sql.Connection;
 import java.sql.DriverManager;
 import java.sql.SQLException;
@@ -136,15 +169,19 @@
         }
 </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>
 
@@ -152,7 +189,7 @@
         </section>
 -->
 
-    <!--
+<!--
         <section id="cj-controlling-transactions">
           <title>&title-cj-controlling-transactions;</title>
 
@@ -161,46 +198,60 @@
 -->
 
     <section id="cj-using-statements">
-      <title>Using Statements to Execute SQL</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>
+      <title>&title-cj-using-statements;</title>
 
-      <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>
+        <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>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 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 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>
+        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>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>
+        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>
+
       <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;
 
@@ -238,10 +289,12 @@
         stmt = null;
     }
 }</programlisting>
+
       </example>
+
     </section>
 
-    <!--
+<!--
         <section id="cj-using-prepared-statements">
           <title>&title-cj-using-prepared-statements;</title>
 
@@ -250,29 +303,40 @@
 -->
 
     <section id="cj-using-callable-statements">
-      <title>Using <literal>CallableStatements</literal> to Execute Stored
-      Procedures</title>
 
-      <para>Starting with MySQL server version 5.0 when used with Connector/J
-      3.1.1 or newer, the <classname>java.sql.CallableStatement</classname>
-      interface is fully implemented with the exception of the
-      <function>getParameterMetaData()</function> method.</para>
+      <title>&title-cj-using-callable-statements;</title>
 
-      <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>
+        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>Connector/J exposes stored procedure functionality through JDBC's
-      <classname>CallableStatement</classname> interface.</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>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>
+        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>
+
           <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;
@@ -282,24 +346,34 @@
 
     SELECT CONCAT('zyxw', inputParam);
 END</programlisting>
-        </example></para>
 
-      <para>To use the <function>demoSp</function> procedure with Connector/J,
-      follow these steps:</para>
+        </example>
+      </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;
 
 ...
 
@@ -315,31 +389,44 @@
 
 
     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;
 ...
 //
@@ -373,21 +460,28 @@
 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: <example>
-              <title>Setting <literal>CallableStatement</literal> Input
-              Parameters</title>
+          <para>
+            Input and in/out parameters are set as for
+            <classname>PreparedStatement</classname> objects. However,
+            <classname>CallableStatement</classname> also supports
+            setting parameters by name:
 
-              <programlisting>...
+            <example>
 
+              <title>Setting <literal>CallableStatement</literal> Input Parameters</title>
+
+<programlisting>...
+
     //
     // Set a parameter by index
     //
@@ -415,23 +509,32 @@
     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();
 
@@ -460,40 +563,51 @@
     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>
 
-      <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>
+      <title>&title-cj-retrieve-autoinc;</title>
 
-          <programlisting>   Statement stmt = null;
+      <para>
+        Before version 3.0 of the JDBC API, there was no standard way of
+        retrieving key values from databases that supported <quote>auto
+        increment</quote> or identity columns. With older JDBC drivers
+        for MySQL, you could always use a MySQL-specific method on the
+        <classname>Statement</classname> interface, or issue the query
+        <literal>SELECT LAST_INSERT_ID()</literal> after issuing an
+        <literal>INSERT</literal> to a table that had an
+        <literal>AUTO_INCREMENT</literal> key. Using the MySQL-specific
+        method call isn't portable, and issuing a
+        <literal>SELECT</literal> to get the
+        <literal>AUTO_INCREMENT</literal> key's value requires another
+        round-trip to the database, which isn't as efficient as
+        possible. The following code snippets demonstrate the three
+        different ways to retrieve <literal>AUTO_INCREMENT</literal>
+        values. First, we demonstrate the use of the new JDBC-3.0 method
+        <function>getGeneratedKeys()</function> which is now the
+        preferred method to use if you need to retrieve
+        <literal>AUTO_INCREMENT</literal> keys and have access to
+        JDBC-3.0. The second example shows how you can retrieve the same
+        value using a standard <literal>SELECT
+        LAST_INSERT_ID()</literal> query. The final example shows how
+        updatable result sets can retrieve the
+        <literal>AUTO_INCREMENT</literal> value when using the
+        <function>insertRow()</function> method.
+
+        <example>
+
+          <title>Retrieving <literal>AUTO_INCREMENT</literal> Column Values using
+            <function>Statement.getGeneratedKeys()</function></title>
+
+<programlisting>   Statement stmt = null;
    ResultSet rs = null;
 
    try {
@@ -569,11 +683,15 @@
     }
 }
 </programlisting>
-        </example> <example>
-          <title>Retrieving <literal>AUTO_INCREMENT</literal> Column Values
-          using <function>SELECT LAST_INSERT_ID()</function></title>
 
-          <programlisting>   Statement stmt = null;
+        </example>
+
+        <example>
+
+          <title>Retrieving <literal>AUTO_INCREMENT</literal> Column Values using
+            <function>SELECT LAST_INSERT_ID()</function></title>
+
+<programlisting>   Statement stmt = null;
    ResultSet rs = null;
 
    try {
@@ -641,11 +759,15 @@
     }
 }
    </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 {
@@ -723,21 +845,27 @@
 
 
    </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>
 
@@ -745,7 +873,7 @@
         </section>
 -->
 
-    <!--
+<!--
         <section id="cj-using-result-set-metadata">
           <title>&title-cj-using-result-set-metadata;</title>
 
@@ -753,7 +881,7 @@
         </section>
 -->
 
-    <!--
+<!--
         <section id="cj-using-database-metadata">
           <title>&title-cj-using-database-metadata;</title>
 
@@ -761,2834 +889,2559 @@
         </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>
 
-    <para>Use the following instructions to install Connector/J</para>
+    <title>&title-cj-installing;</title>
 
+    <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>
 
-        <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>
+        <title>&title-cj-supported-java-versions;</title>
 
-        <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>
+          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>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>
+          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>
 
-        <remark>MARKUP DONE TO HERE</remark>
+        <para>
+          Caching functionality provided by Connector/J 3.1.0 or newer
+          is also not available on JVMs older than 1.4.x, as it relies
+          on <classname>java.util.LinkedHashMap</classname> which was
+          first available in JDK-1.4.0.
+        </para>
+
+        <remark>
+          MARKUP DONE TO HERE
+        </remark>
+
       </section>
 
       <section id="cj-supported-mysql-versions">
-        <title>MySQL Server Version Guidelines</title>
 
-        <para>MySQL Connector/J supports all known MySQL server versions. Some
-        features (foreign keys, updatable result sets) require more recent
-        versions of MySQL to operate.</para>
+        <title>&title-cj-supported-mysql-versions;</title>
 
-        <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>
+          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>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>
+          When connecting to MySQL server version 4.1 or newer, it is
+          best to use MySQL Connector/J version 3.1, as it has full
+          support for features in the newer versions of the server,
+          including Unicode characters, views, stored procedures and
+          server-side prepared statements.
+        </para>
+
+        <para>
+          Although Connector/J version 3.0 will connect to MySQL server,
+          version 4.1 or newer, and implements Unicode characters and
+          the new authorization mechanism, Connector/J 3.0 will not be
+          updated to support new features in current and future server
+          versions.
+        </para>
+
       </section>
 
       <section id="cj-classpath">
-        <title id="c-j-installing-driver-classpath">Installing the Driver and
-        Configuring the <literal>CLASSPATH</literal></title>
 
-        <para>MySQL Connector/J is distributed as a .zip or .tar.gz archive
-        containing the sources, the class files a class-file only
-        <quote>binary</quote> .jar archive named
-        "<filename>mysql-connector-java-[version]-bin.jar</filename>", and
-        starting with Connector/J 3.1.8 a <quote>debug</quote> build of the
-        driver in a file named
-        "<filename>mysql-connector-java-[version]-bin-g.jar</filename>".</para>
+        <title>&title-cj-classpath;</title>
 
-        <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>
+          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>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>
+          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 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 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>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>
+          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>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>
+          Once you have extracted the distribution archive, you can
+          install the driver by placing
+          mysql-connector-java-[version]-bin.jar in your classpath,
+          either by adding the FULL path to it to your CLASSPATH
+          environment variable, or by directly specifying it with the
+          command line switch -cp when starting your JVM
+        </para>
 
+        <para>
+          If you are going to use the driver with the JDBC
+          DriverManager, you would use "com.mysql.jdbc.Driver" as the
+          class that implements java.sql.Driver.
+        </para>
+
         <example>
+
           <title>Setting the CLASSPATH Under UNIX</title>
 
-          <para>The following command works for 'csh' under UNIX:</para>
+          <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>
 
-      <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>
+      <title>&title-cj-upgrading;</title>
 
-      <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>
+        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>
+
       <section id="cj-upgrading-3-0-to-3-1">
-        <title>Upgrading from MySQL Connector/J 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>
+        <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>
+
         <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>
+    <section id="cj-installing-source">
 
-      <para><caution>
-          <para>You should read this section only if you are interested in
+      <title>&title-cj-installing-source;</title>
+
+      <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>
+          Connector/J up and running on your system, you should use a
+          standard release distribution.
+        </para>
 
+      </caution>
+
+      <para>
+        To install MySQL Connector/J from the development source tree,
+        make sure that you have the following prerequisites:
+      </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>
+          <para>
+            Subversion, to check out the sources from our repository
+            (available from
+            <ulink url="http://subversion.tigris.org/"/>).
+          </para>
         </listitem>
 
         <listitem>
-          <para>Apache Ant version 1.6 or newer, from <ulink
-          url="http://ant.apache.org/">http://ant.apache.org/</ulink> </para>
+          <para>
+            Apache Ant version 1.6 or newer (available from
+            <ulink url="http://ant.apache.org/"/>).
+          </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>
+          <para>
+            JDK-1.4.2 or later. Although MySQL Connector/J can be
+            installed on older JDKs, to compile it from source you must
+            have at least JDK-1.4.2.
+          </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>
+        The Subversion source code repository for MySQL Connector/J is
+        located at
+        <ulink url="http://svn.mysql.com/svnpublic/connector-j"/>. In
+        general, you should not check out the entire repository because
+        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>
+      <para>
+        To check out and compile a specific 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>
+          <para>
+            At the time of this writing, there are three active branches
+            of Connector/J: <literal>branch_3_0</literal>,
+            <literal>branch_3_1</literal> and
+            <literal>branch_5_0</literal>. Check out the latest code
+            from the branch that you want with the following command
+            (replacing <replaceable>[major]</replaceable> and
+            <replaceable>[minor]</replaceable> with appropriate version
+            numbers):
+          </para>
 
-          <programlisting>svn co http://svn.mysql.com/svnpublic/connector-j/branches/branch_[major]_[minor]/connector-j</programlisting>
+<programlisting>shell&gt; <userinput>svn co http://svn.mysql.com/svnpublic/connector-j/branches/branch_<replaceable>[major]</replaceable>_<replaceable>[minor]</replaceable>/connector-j</userinput></programlisting>
 
-          <para>This will create a "connector-j" subdirectory in the current
-          directory that contains the latest sources for the requested
-          branch.</para>
+          <para>
+            This creates a <filename>connector-j</filename> 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>
+          <para>
+            Change location to the <filename>connector-j</filename>
+            directory to make it your current working directory:
+          </para>
 
-          <programlisting>shell&gt; cd connector-j</programlisting>
+<programlisting>shell&gt; <userinput>cd connector-j</userinput></programlisting>
         </listitem>
 
         <listitem>
-          <para>Issue the following command to compile the driver and create a
-          .jar file suitable for installation:</para>
+          <para>
+            Issue the following command to compile the driver and create
+            a <filename>.jar</filename> file suitable for installation:
+          </para>
 
-          <programlisting>ant dist</programlisting>
+<programlisting>shell&gt; <userinput>ant dist</userinput></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>
+          <para>
+            This creates a <filename>build</filename> directory in the
+            current directory, where all build output will go. A
+            directory is created in the <filename>build</filename>
+            directory that includes the version number of the sources
+            you are building from. This directory contains the sources,
+            compiled <filename>.class</filename> files, and a
+            <filename>.jar</filename> file suitable for deployment. For
+            other possible targets, including ones that will create a
+            fully packaged distribution, issue the following command:
+          </para>
+
+<programlisting>shell&gt; <userinput>ant --projecthelp</userinput></programlisting>
         </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>
+            A newly created <filename>.jar</filename> file containing
+            the JDBC driver will be placed in the directory
+            <filename>build/mysql-connector-java-<replaceable>[version]</replaceable></filename>.
+          </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>
+          <para>
+            Install the newly created JDBC driver as you would a binary
+            <filename>.jar</filename> file that you download from MySQL
+            by following the instructions in
+            <xref linkend="cj-classpath"/>.
+          </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>
 
-      <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>
+      <title>&title-cj-configuration-properties;</title>
 
-      <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 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>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>
+      <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>
+        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>
 
-      <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>
+      <title>&title-cj-implementation-notes;</title>
 
-      <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>
+        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>
+
       <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>
 
-      <para>MySQL Connector/J is flexible in the way it handles conversions
-      between MySQL data types and Java data types.</para>
+      <title>&title-cj-type-conversions;</title>
 
-      <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>
+        MySQL Connector/J is flexible in the way it handles conversions
+        between MySQL data types and Java data types.
+      </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>
+        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>The conversions that are always guaranteed to work are listed in
-      the following table:</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>
+
       <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><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><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>
+
+                  <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>
 
-      <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>
+      <title>&title-cj-character-sets;</title>
 
-      <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>
+        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>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>
+        <interfacename>PreparedStatement</interfacename>
 
-      <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>
+        and
 
-      <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>
+        <interfacename>CallableStatement</interfacename>
 
-      <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>
+        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>
+
           <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>
 
@@ -3597,53 +3450,75 @@
 -->
 
     <section id="cj-using-ssl">
-      <title>Connecting Securely 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>
+      <title>&title-cj-using-ssl;</title>
 
-      <para>For SSL Support to work, you must have the following:</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>
+
       <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
@@ -3656,18 +3531,24 @@
 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?
@@ -3687,28 +3568,35 @@
 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:  {}
@@ -3739,50 +3627,67 @@
  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>
 
-      <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>
+      <title>&title-cj-replication-connection;</title>
 
-      <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>
+        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>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>
+        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>Here is a short, simple example of how ReplicationDriver might be
-      used in a standalone application.</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>
 
-      <programlisting id="cj-using-replication-driver-example">import java.sql.Connection;
+      <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;
 import java.sql.ResultSet;
 import java.util.Properties;
 
@@ -3837,107 +3742,150 @@
     }
 }
 </programlisting>
+
     </section>
+
   </section>
 
   <section id="cj-j2ee">
-    <title>Using Connector/J with J2EE and Other Java Frameworks</title>
 
-    <para>This section describes how to use Connector/J in several
-    contexts.</para>
+    <title>&title-cj-j2ee;</title>
 
+    <para>
+      This section describes how to use Connector/J in several contexts.
+    </para>
+
     <section id="cj-general-j2ee-concepts">
-      <title>General J2EE Concepts</title>
 
-      <para>This section provides general background on J2EE concepts that
-      pertain to use of Connector/J.</para>
+      <title>&title-cj-general-j2ee-concepts;</title>
 
+      <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>
 
-        <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>
+        <title>&title-cj-connection-pooling;</title>
 
-        <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>
+          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>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>
+          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>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>
+          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>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>
+          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>
+
         <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: <example>
-            <title>Using a Connection Pool with a J2EE Application
-            Server</title>
+        <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:
 
-            <programlisting>import java.sql.Connection;
+          <example>
+
+            <title>Using a Connection Pool with a J2EE Application Server</title>
+
+<programlisting>import java.sql.Connection;
 import java.sql.SQLException;
 import java.sql.Statement;
 
@@ -4031,69 +3979,95 @@
         }
     }
 }</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>
 
-        <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>
+          </example>
 
-        <para>What's the Best Size for my Connection Pool?</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>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>
+          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>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>
+          What's the Best Size for my Connection Pool?
+        </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>
+          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>
+
       </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>
 
-      <para>The following instructions are based on the instructions for
-      Tomcat-5.x, available at <ulink
+      <title>&title-cj-tomcat-config;</title>
+
+      <para>
+        The following instructions are based on the instructions for
+        Tomcat-5.x, available at
+        <ulink
       url="http://jakarta.apache.org/tomcat/tomcat-5.0-doc/jndi-datasource-examples-howto.html">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;
 
   ...
 
@@ -4219,30 +4193,37 @@
   &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>
 
-      <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>
+      <title>&title-cj-jboss-config;</title>
 
-      <programlisting>&lt;datasources&gt;
+      <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;
     &lt;local-tx-datasource&gt;
         &lt;!-- This connection pool will be bound into JNDI with the name
              "java:/MySQLDB" --&gt;
@@ -4278,9 +4259,10 @@
 
     &lt;/local-tx-datasource&gt;
 &lt;/datasources&gt; </programlisting>
+
     </section>
 
-    <!--
+<!--
       <section id="cj-hibernate-config">
         <title>&title-cj-hibernate-config;</title>
 
@@ -4288,7 +4270,7 @@
       </section>
 -->
 
-    <!--
+<!--
       <section id="cj-spring-config">
         <title>&title-cj-spring-config;</title>
 
@@ -4296,7 +4278,7 @@
       </section>
 -->
 
-    <!--
+<!--
       <section id="cj-struts-config">
         <title>&title-cj-struts-config;</title>
 
@@ -4305,7 +4287,7 @@
 
 -->
 
-    <!--
+<!--
       <section id="cj-weblogic-config">
         <title>&title-cj-weblogic-config;</title>
 
@@ -4313,7 +4295,7 @@
       </section>
 -->
 
-    <!--
+<!--
       <section id="cj-websphere-config">
         <title>&title-cj-websphere-config;</title>
 
@@ -4321,115 +4303,169 @@
       </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>
 
-    <para>This section describes how to solve problems that you may encounter
-    when using Connector/J.</para>
+    <title>&title-cj-troubleshooting;</title>
 
+    <para>
+      This section describes how to solve problems that you may
+      encounter when using Connector/J.
+    </para>
+
     <section id="cj-faq">
-      <title>Common Problems and Solutions</title>
 
-      <para>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>
+      <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>
+
       <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>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>
+              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>From the mysql command-line client, logged in as a user that
-            can grant privileges, issue the following command:</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>
+
             <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?
@@ -4437,70 +4473,98 @@
 (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>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>
+              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>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>
+              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>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>
+              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>
+
           </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>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>
+              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>The following (simplistic) example shows what code that can
-            handle these exceptions might look like:</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><example>
+            <para>
+              The following (simplistic) example shows what code that
+              can handle these exceptions might look like:
+            </para>
+
+            <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;
@@ -4619,29 +4683,45 @@
             }
         } 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>
 
@@ -4650,142 +4730,206 @@
 -->
 
     <section id="cj-reporting-bugs">
-      <title>How to Report Connector/J Bugs or Problems</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>
+      <title>&title-cj-reporting-bugs;</title>
 
-      <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>
+        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>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>
+        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>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>
+        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>If you have a repeatable bug report, please report it to the bugs
-      database at <ulink url="???">http://bugs.mysql.com/</ulink>.</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>Any bug that we are able to repeat has a high chance of being
-      fixed in the next MySQL release.</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>To report other problems, you can use one of the MySQL mailing
-      lists.</para>
+      <para>
+        Any bug that we are able to repeat has a high chance of being
+        fixed in the next MySQL release.
+      </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>
+        To report other problems, you can use one of the MySQL mailing
+        lists.
+      </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>
+        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>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>
+        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>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>
+        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>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>
+        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>If at all possible, you should create a repeatable, stanalone
-      testcase that doesn't involve any third-party classes.</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>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>
+        If at all possible, you should create a repeatable, stanalone
+        testcase that doesn't involve any third-party classes.
+      </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>
+        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>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>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>tearDown()</methodname> method, drop any tables
-      you created in the <methodname>setUp()</methodname> 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 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 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>
+
       <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>
\ No newline at end of file
+
+</section>

Modified: trunk/refman-5.1/connector-j.xml
===================================================================
--- trunk/refman-5.1/connector-j.xml	2006-01-13 20:11:16 UTC (rev 815)
+++ trunk/refman-5.1/connector-j.xml	2006-01-13 20:53:45 UTC (rev 816)
@@ -1363,6 +1363,141 @@
 
     </section>
 
+    <section id="cj-installing-source">
+
+      <title>&title-cj-installing-source;</title>
+
+      <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>
+
+      <para>
+        To install MySQL Connector/J from the development source tree,
+        make sure that you have the following prerequisites:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Subversion, to check out the sources from our repository
+            (available from
+            <ulink url="http://subversion.tigris.org/"/>).
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Apache Ant version 1.6 or newer (available from
+            <ulink url="http://ant.apache.org/"/>).
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            JDK-1.4.2 or later. Although MySQL Connector/J can be
+            installed on older JDKs, to compile it from source you must
+            have at least JDK-1.4.2.
+          </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"/>. In
+        general, you should not check out the entire repository because
+        it contains every branch and tag for MySQL Connector/J and is
+        quite large.
+      </para>
+
+      <para>
+        To check out and compile a specific branch of MySQL Connector/J,
+        follow these steps:
+      </para>
+
+      <orderedlist>
+
+        <listitem>
+          <para>
+            At the time of this writing, there are three active branches
+            of Connector/J: <literal>branch_3_0</literal>,
+            <literal>branch_3_1</literal> and
+            <literal>branch_5_0</literal>. Check out the latest code
+            from the branch that you want with the following command
+            (replacing <replaceable>[major]</replaceable> and
+            <replaceable>[minor]</replaceable> with appropriate version
+            numbers):
+          </para>
+
+<programlisting>shell&gt; <userinput>svn co http://svn.mysql.com/svnpublic/connector-j/branches/branch_<replaceable>[major]</replaceable>_<replaceable>[minor]</replaceable>/connector-j</userinput></programlisting>
+
+          <para>
+            This creates a <filename>connector-j</filename> subdirectory
+            in the current directory that contains the latest sources
+            for the requested branch.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Change location to the <filename>connector-j</filename>
+            directory to make it your current working directory:
+          </para>
+
+<programlisting>shell&gt; <userinput>cd connector-j</userinput></programlisting>
+        </listitem>
+
+        <listitem>
+          <para>
+            Issue the following command to compile the driver and create
+            a <filename>.jar</filename> file suitable for installation:
+          </para>
+
+<programlisting>shell&gt; <userinput>ant dist</userinput></programlisting>
+
+          <para>
+            This creates a <filename>build</filename> directory in the
+            current directory, where all build output will go. A
+            directory is created in the <filename>build</filename>
+            directory that includes the version number of the sources
+            you are building from. This directory contains the sources,
+            compiled <filename>.class</filename> files, and a
+            <filename>.jar</filename> file suitable for deployment. For
+            other possible targets, including ones that will create a
+            fully packaged distribution, issue the following command:
+          </para>
+
+<programlisting>shell&gt; <userinput>ant --projecthelp</userinput></programlisting>
+        </listitem>
+
+        <listitem>
+          <para>
+            A newly created <filename>.jar</filename> file containing
+            the JDBC driver will be placed in the directory
+            <filename>build/mysql-connector-java-<replaceable>[version]</replaceable></filename>.
+          </para>
+
+          <para>
+            Install the newly created JDBC driver as you would a binary
+            <filename>.jar</filename> file that you download from MySQL
+            by following the instructions in
+            <xref linkend="cj-classpath"/>.
+          </para>
+        </listitem>
+
+      </orderedlist>
+
+    </section>
+
   </section>
 
   <section id="cj-jdbc-reference">

Modified: trunk/refman-common/titles.en.ent
===================================================================
--- trunk/refman-common/titles.en.ent	2006-01-13 20:11:16 UTC (rev 815)
+++ trunk/refman-common/titles.en.ent	2006-01-13 20:53:45 UTC (rev 816)
@@ -187,6 +187,7 @@
 <!ENTITY title-cj-ias-config "Using Connector/J with Oracle Application Server">
 <!ENTITY title-cj-implementation-notes "JDBC API Implementation Notes">
 <!ENTITY title-cj-installing "Installing Connector/J">
+<!ENTITY title-cj-installing-source "Installing from the Development Source Tree">
 <!ENTITY title-cj-j2ee "Using Connector/J with J2EE and Other Java Frameworks">
 <!ENTITY title-cj-jboss-config "Using Connector/J with JBoss">
 <!ENTITY title-cj-jdbc-reference "JDBC Reference">

Thread
svn commit - mysqldoc@docsrva: r816 - in trunk: . refman-4.1 refman-5.0 refman-5.1 refman-commonpaul13 Jan