| Server IP : 180.180.241.3 / Your IP : 216.73.216.252 Web Server : Microsoft-IIS/7.5 System : Windows NT NETWORK-NHRC 6.1 build 7601 (Windows Server 2008 R2 Standard Edition Service Pack 1) i586 User : IUSR ( 0) PHP Version : 5.3.28 Disable Function : NONE MySQL : ON | cURL : ON | WGET : OFF | Perl : OFF | Python : OFF | Sudo : OFF | Pkexec : OFF Directory : C:/Program Files (x86)/MySQL/Connector J 5.1.29/docs/ |
Upload File : |
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>MySQL Connector/J Developer Guide</title><link rel="stylesheet" type="text/css" href="mvl.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<script language="javascript" type="text/javascript">
function addOnload(theFunc)
{
var previous = window.onload;
if (typeof window.onload != 'function')
{
window.onload = theFunc;
}
else
{
window.onload = function()
{
previous();
theFunc();
}
}
}
addOnload(function()
{
var base = new Date(1390839468*1000);
var now = new Date();
var diff = ((now-base)/1000)/(24*3600);
if (diff > 90) {
var nodes = document.getElementsByClassName('titlepage');
nodes[0].innerHTML = '<p style="border: 5px #ff0000 solid; padding: 5px; margin 5px">' +
'This copy of the manual is more than 90 days old. We encourage you to download a ' +
'new version from <a href="http://dev.mysql.com">dev.mysql.com/doc</a>.</p>' + nodes[0].innerHTML;
}
});
</script>
<noscript></noscript>
</head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="book"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j"></a>MySQL Connector/J Developer Guide</h1></div><div><div class="abstract"><p class="title"><b>Abstract</b></p><p>
This manual describes how to install, configure, and develop
database applications using MySQL Connector/J, the JDBC driver
for communicating with MySQL servers.
</p><p>
For release notes detailing the changes in each release of
Connector/J, see
<a class="ulink" href="http://dev.mysql.com/doc/relnotes/connector-j/en/" target="_top">MySQL
Connector/J Release Notes</a>.
</p><p>
Document generated on:
2014-01-27
(revision: 37530)
</p></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="preface"><a href="#preface">Preface and Legal Notices</a></span></dt><dt><span class="chapter"><a href="#connector-j-overview">1. Overview of MySQL Connector/J</a></span></dt><dt><span class="chapter"><a href="#connector-j-versions">2. Connector/J Versions</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-change-history">2.1. Connector/J Release Notes and Change History</a></span></dt><dt><span class="section"><a href="#connector-j-versions-java">2.2. Java Versions Supported</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-j-installing">3. Connector/J Installation</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-binary-installation">3.1. Installing Connector/J from a Binary Distribution</a></span></dt><dt><span class="section"><a href="#connector-j-installing-classpath">3.2. Installing the Driver and Configuring the <code class="literal">CLASSPATH</code></a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading">3.3. Upgrading from an Older Version</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-installing-upgrading-5-1">3.3.1. Upgrading to MySQL Connector/J 5.1.x</a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading-issues">3.3.2. JDBC-Specific Issues When Upgrading to MySQL Server 4.1 or Newer</a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading-3-0-to-3-1">3.3.3. Upgrading from MySQL Connector/J 3.0 to 3.1</a></span></dt></dl></dd><dt><span class="section"><a href="#connector-j-installing-source">3.4. Installing from the Development Source Tree</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-j-examples">4. Connector/J Examples</a></span></dt><dt><span class="chapter"><a href="#connector-j-reference">5. Connector/J (JDBC) Reference</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-reference-configuration-properties">5.1. Driver/Datasource Class Names, URL Syntax and Configuration Properties
for Connector/J</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-useconfigs">5.1.1. Properties Files for the <code class="literal">useConfigs</code> Option</a></span></dt></dl></dd><dt><span class="section"><a href="#connector-j-reference-implementation-notes">5.2. JDBC API Implementation Notes</a></span></dt><dt><span class="section"><a href="#connector-j-reference-type-conversions">5.3. Java, JDBC and MySQL Types</a></span></dt><dt><span class="section"><a href="#connector-j-reference-charsets">5.4. Using Character Sets and Unicode</a></span></dt><dt><span class="section"><a href="#connector-j-reference-using-ssl">5.5. Connecting Securely Using SSL</a></span></dt><dt><span class="section"><a href="#connector-j-using-pam">5.6. Connecting Using PAM Authentication</a></span></dt><dt><span class="section"><a href="#connector-j-reference-replication-connection">5.7. Using Master/Slave Replication with ReplicationConnection</a></span></dt><dt><span class="section"><a href="#connector-j-reference-error-sqlstates">5.8. Mapping MySQL Error Numbers to JDBC SQLState Codes</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-j-usagenotes-basic">6. JDBC Concepts</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-usagenotes-connect-drivermanager">6.1. Connecting to MySQL Using the JDBC <code class="literal">DriverManager</code>
Interface</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-statements">6.2. Using JDBC <code class="literal">Statement</code> Objects to Execute SQL</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-statements-callable">6.3. Using JDBC <code class="literal">CallableStatements</code> to Execute Stored
Procedures</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-last-insert-id">6.4. Retrieving <code class="literal">AUTO_INCREMENT</code> Column Values through JDBC</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-j-usagenotes-j2ee-concepts-connection-pooling">7. Connection Pooling with Connector/J</a></span></dt><dt><span class="chapter"><a href="#connector-j-multi-host-connections">8. Multi-Host Connections</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections">8.1. Configuring Load Balancing with Connector/J</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-j2ee-concepts-load-balancing-failover">8.2. Configuring Failover with Connector/J</a></span></dt><dt><span class="section"><a href="#connector-j-master-slave-replication-connection">8.3. Master/Slave Replication with ReplicationConnection</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-j-interceptors">9. Using the Connector/J Interceptor Classes</a></span></dt><dt><span class="chapter"><a href="#connector-j-usagenotes-tomcat">10. Using Connector/J with Tomcat</a></span></dt><dt><span class="chapter"><a href="#connector-j-usagenotes-jboss">11. Using Connector/J with JBoss</a></span></dt><dt><span class="chapter"><a href="#connector-j-usagenotes-spring-config">12. Using Connector/J with Spring</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-usagenotes-spring-config-jdbctemplate">12.1. Using <code class="classname">JdbcTemplate</code></a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-spring-config-transactional">12.2. Transactional JDBC Access</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-spring-config-connpooling">12.3. Connection Pooling with Spring</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-j-usagenotes-glassfish-config">13. Using Connector/J with GlassFish</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-usagenotes-glassfish-config-jsp">13.1. A Simple JSP Application with Glassfish, Connector/J and MySQL</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-glassfish-config-servlet">13.2. A Simple Servlet with Glassfish, Connector/J and MySQL</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-j-usagenotes-troubleshooting">14. Troubleshooting Connector/J Applications</a></span></dt><dt><span class="chapter"><a href="#connector-j-usagenotes-known-issues-limitations">15. Known Issues and Limitations</a></span></dt><dt><span class="chapter"><a href="#connector-j-support">16. Connector/J Support</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-support-community">16.1. Connector/J Community Support</a></span></dt><dt><span class="section"><a href="#connector-j-support-bug-report">16.2. How to Report Connector/J Bugs or Problems</a></span></dt></dl></dd><dt><span class="appendix"><a href="#connector-j-third-party-licenses">A. Licenses for Third-Party Components</a></span></dt><dd><dl><dt><span class="section"><a href="#license-ant-contrib">A.1. Ant-Contrib License</a></span></dt><dt><span class="section"><a href="#license-c3p0-0-91">A.2. c3p0 JDBC Library License</a></span></dt><dt><span class="section"><a href="#license-gnu-lgpl-2-1">A.3. GNU Lesser General Public License Version 2.1, February 1999</a></span></dt><dt><span class="section"><a href="#license-jboss-common-jdbc-wrapper">A.4. jboss-common-jdbc-wrapper.jar License</a></span></dt><dt><span class="section"><a href="#license-nanoxml">A.5. NanoXML License</a></span></dt><dt><span class="section"><a href="#license-rox-jar">A.6. rox.jar License</a></span></dt><dt><span class="section"><a href="#license-slf4j">A.7. Simple Logging Facade for Java (SLF4J) License</a></span></dt></dl></dd></dl></div><div class="preface"><div class="titlepage"><div><div><h1 class="title"><a name="preface"></a>Preface and Legal Notices</h1></div></div></div><p>
This manual describes how to install, configure, and develop
database applications using MySQL Connector/J, the JDBC driver for
communicating with MySQL servers.
</p><h2><a name="legalnotice"></a>Legal Notices</h2><p>
Copyright © 1998, 2014, Oracle and/or its affiliates. All
rights reserved.
</p><p>
This software and related documentation are provided under a license
agreement containing restrictions on use and disclosure and are
protected by intellectual property laws. Except as expressly
permitted in your license agreement or allowed by law, you may not
use, copy, reproduce, translate, broadcast, modify, license,
transmit, distribute, exhibit, perform, publish, or display any
part, in any form, or by any means. Reverse engineering,
disassembly, or decompilation of this software, unless required by
law for interoperability, is prohibited.
</p><p>
The information contained herein is subject to change without notice
and is not warranted to be error-free. If you find any errors,
please report them to us in writing.
</p><p>
If this software or related documentation is delivered to the U.S.
Government or anyone licensing it on behalf of the U.S. Government,
the following notice is applicable:
</p><p>
U.S. GOVERNMENT RIGHTS Programs, software, databases, and related
documentation and technical data delivered to U.S. Government
customers are "commercial computer software" or "commercial
technical data" pursuant to the applicable Federal Acquisition
Regulation and agency-specific supplemental regulations. As such,
the use, duplication, disclosure, modification, and adaptation shall
be subject to the restrictions and license terms set forth in the
applicable Government contract, and, to the extent applicable by the
terms of the Government contract, the additional rights set forth in
FAR 52.227-19, Commercial Computer Software License (December 2007).
Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.
</p><p>
This software is developed for general use in a variety of
information management applications. It is not developed or intended
for use in any inherently dangerous applications, including
applications which may create a risk of personal injury. If you use
this software in dangerous applications, then you shall be
responsible to take all appropriate fail-safe, backup, redundancy,
and other measures to ensure the safe use of this software. Oracle
Corporation and its affiliates disclaim any liability for any
damages caused by use of this software in dangerous applications.
</p><p>
Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. MySQL is a trademark of Oracle Corporation and/or its
affiliates, and shall not be used without Oracle's express written
authorization. Other names may be trademarks of their respective
owners.
</p><p>
This software and documentation may provide access to or information
on content, products, and services from third parties. Oracle
Corporation and its affiliates are not responsible for and expressly
disclaim all warranties of any kind with respect to third-party
content, products, and services. Oracle Corporation and its
affiliates will not be responsible for any loss, costs, or damages
incurred due to your access to or use of third-party content,
products, or services.
</p><p>
This documentation is in prerelease status and is intended for
demonstration and preliminary use only. It may not be specific to
the hardware on which you are using the software. Oracle Corporation
and its affiliates are not responsible for and expressly disclaim
all warranties of any kind with respect to this documentation and
will not be responsible for any loss, costs, or damages incurred due
to the use of this documentation.
</p><p>
The information contained in this document is for informational
sharing purposes only and should be considered in your capacity as a
customer advisory board member or pursuant to your beta trial
agreement only. It is not a commitment to deliver any material,
code, or functionality, and should not be relied upon in making
purchasing decisions. The development, release, and timing of any
features or functionality described in this document remains at the
sole discretion of Oracle.
</p><p>
This document in any form, software or printed matter, contains
proprietary information that is the exclusive property of Oracle.
Your access to and use of this material is subject to the terms and
conditions of your Oracle Software License and Service Agreement,
which has been executed and with which you agree to comply. This
document and information contained herein may not be disclosed,
copied, reproduced, or distributed to anyone outside Oracle without
prior written consent of Oracle or as specifically provided below.
This document is not part of your license agreement nor can it be
incorporated into any contractual agreement with Oracle or its
subsidiaries or affiliates.
</p><p>
This documentation is NOT distributed under a GPL license. Use of
this documentation is subject to the following terms:
</p><p>
You may create a printed copy of this documentation solely for your
own personal use. Conversion to other formats is allowed as long as
the actual content is not altered or edited in any way. You shall
not publish or distribute this documentation in any form or on any
media, except if you distribute the documentation in a manner
similar to how Oracle disseminates it (that is, electronically for
download on a Web site with the software) or on a CD-ROM or similar
medium, provided however that the documentation is disseminated
together with the software on the same medium. Any other use, such
as any dissemination of printed copies or use of this documentation,
in whole or in part, in another publication, requires the prior
written consent from an authorized representative of Oracle. Oracle
and/or its affiliates reserve any and all rights to this
documentation not expressly granted above.
</p><p>
For more information on the terms of this license, or for details on
how the MySQL documentation is built and produced, please visit
<a class="ulink" href="http://dev.mysql.com/contact/" target="_top">MySQL Contact &
Questions</a>.
</p><p>
For help with using MySQL, please visit either the
<a class="ulink" href="http://forums.mysql.com" target="_top">MySQL Forums</a> or
<a class="ulink" href="http://lists.mysql.com" target="_top">MySQL Mailing Lists</a>
where you can discuss your issues with other MySQL users.
</p><p>
For additional documentation on MySQL products, including
translations of the documentation into other languages, and
downloadable versions in variety of formats, including HTML and PDF
formats, see the <a class="ulink" href="http://dev.mysql.com/doc" target="_top">MySQL
Documentation Library</a>.
</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-overview"></a>Chapter 1. Overview of MySQL Connector/J</h1></div></div></div><a class="indexterm" name="idm47020252178368"></a><p>
MySQL provides connectivity for client applications developed in
the Java programming language through a JDBC driver, which is
called MySQL Connector/J.
</p><p>
MySQL Connector/J is a JDBC Type 4 driver. Different versions are
available that are compatible with the JDBC 3.0 and JDBC 4.0
specifications. The Type 4 designation means that the driver is a
pure Java implementation of the MySQL protocol and does not rely
on the MySQL client libraries.
</p><p>
For large-scale programs that use common design patterns of data
access, consider using one of the popular persistence frameworks
such as <a class="ulink" href="http://www.hibernate.org/" target="_top">Hibernate</a>,
<a class="ulink" href="http://www.springframework.org/" target="_top">Spring's JDBC
templates</a> or <a class="ulink" href="http://ibatis.apache.org/" target="_top">Ibatis
SQL Maps</a> to reduce the amount of JDBC code for you to
debug, tune, secure, and maintain.
</p><h2><a name="idm47020252173376"></a>
Key Topics
</h2><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
For help with connection strings, connection options, and
setting up your connection through JDBC, see
<a class="xref" href="#connector-j-reference-configuration-properties" title="5.1. Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J">Section 5.1, “Driver/Datasource Class Names, URL Syntax and Configuration Properties
for Connector/J”</a>.
</p></li></ul></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-versions"></a>Chapter 2. Connector/J Versions</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-change-history">2.1. Connector/J Release Notes and Change History</a></span></dt><dt><span class="section"><a href="#connector-j-versions-java">2.2. Java Versions Supported</a></span></dt></dl></div><a class="indexterm" name="idm47020252170192"></a><p>
There are currently four versions of MySQL Connector/J available:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Connector/J 5.1 is the Type 4 pure Java JDBC driver, which
conforms to the JDBC 3.0 and JDBC 4.0 specifications. It
provides compatibility with all the functionality of MySQL,
including 4.1, 5.0, 5.1, 5.5, 5.6, and 5.7. Connector/J 5.1
provides ease of development features, including
auto-registration with the Driver Manager, standardized
validity checks, categorized SQLExceptions, support for the
JDBC-4.0 XML processing, per connection client information,
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/char.html" target="_top"><code class="literal">NCHAR</code></a>,
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/char.html" target="_top"><code class="literal">NVARCHAR</code></a> and
<code class="literal">NCLOB</code> types. This release also includes all
bug fixes up to and including Connector/J 5.0.6.
</p></li><li class="listitem"><p>
Connector/J 5.0 provides support for all the functionality
offered by Connector/J 3.1 and includes distributed
transaction (XA) support.
</p></li><li class="listitem"><p>
Connector/J 3.1 was designed for connectivity to MySQL 4.1 and
MySQL 5.0 servers and provides support for all the
functionality in MySQL 5.0 except distributed transaction (XA)
support.
</p></li><li class="listitem"><p>
Connector/J 3.0 provides core functionality and was designed
for connectivity to MySQL 3.x or MySQL 4.1 servers, although
it provides basic compatibility with later versions of MySQL.
Connector/J 3.0 does not support server-side prepared
statements, and does not support any of the features in
versions of MySQL later than 4.1.
</p></li></ul></div><p>
The following table summarizes the Connector/J versions available,
along with the details of JDBC driver type, what version of the
JDBC API it supports, what versions of MySQL Server it works with,
and whether it is currently supported or not:
</p><p>
</p><div class="table"><a name="idm47020252160592"></a><p class="title"><b>Table 2.1. Summary of Connector/J Versions</b></p><div class="table-contents"><table summary="Summary of Connector/J Versions" border="1"><colgroup><col><col><col><col><col></colgroup><thead><tr><th scope="col">Connector/J version</th><th scope="col">Driver Type</th><th scope="col">JDBC version</th><th scope="col">MySQL Server version</th><th scope="col">Status</th></tr></thead><tbody><tr><td scope="row">5.1</td><td>4</td><td>3.0, 4.0</td><td>4.1, 5.0, 5.1, 5.5, 5.6, 5.7</td><td>Recommended version</td></tr><tr><td scope="row">5.0</td><td>4</td><td>3.0</td><td>4.1, 5.0</td><td>Released version</td></tr><tr><td scope="row">3.1</td><td>4</td><td>3.0</td><td>4.1, 5.0</td><td>Obsolete</td></tr><tr><td scope="row">3.0</td><td>4</td><td>3.0</td><td>3.x, 4.1</td><td>Obsolete</td></tr></tbody></table></div></div><p><br class="table-break">
</p><p>
The current recommended version for Connector/J is 5.1. This guide
covers all four connector versions, with specific notes given
where a setting applies to a specific option.
</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-change-history"></a>2.1. Connector/J Release Notes and Change History</h2></div></div></div><p>
For details of new features and bug fixes in each Connector/J
release, see the
<a class="ulink" href="http://dev.mysql.com/doc/relnotes/connector-j/en/" target="_top">MySQL
Connector/J Release Notes</a>.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-versions-java"></a>2.2. Java Versions Supported</h2></div></div></div><p>
The following table summarizes what version of Java RTE is
required to use Connector/J with Java applications, and what
version of JDK is required to build Connector/J source code:
</p><p>
</p><div class="table"><a name="idm47020252139696"></a><p class="title"><b>Table 2.2. Summary of Java Versions Required by Connector/J</b></p><div class="table-contents"><table summary="Summary of Java Versions Required by Connector/J" border="1"><colgroup><col><col><col></colgroup><thead><tr><th scope="col">Connector/J version</th><th scope="col">Java RTE required</th><th scope="col">JDK required (to build source code)</th></tr></thead><tbody><tr><td scope="row">5.1</td><td>1.5.x, 1.6.x, 1.7.x</td><td>1.6.x and 1.5.x</td></tr><tr><td scope="row">5.0</td><td>1.3.x, 1.4.x, 1.5.x, 1.6.x</td><td>1.4.2, 1.5.x, 1.6.x</td></tr><tr><td scope="row">3.1</td><td>1.2.x, 1.3.x, 1.4.x, 1.5.x, 1.6.x</td><td>1.4.2, 1.5.x, 1.6.x</td></tr><tr><td scope="row">3.0</td><td>1.2.x, 1.3.x, 1.4.x, 1.5.x, 1.6.x</td><td>1.4.2, 1.5.x, 1.6.x</td></tr></tbody></table></div></div><p><br class="table-break">
</p><p>
If you are building Connector/J from source code using the
source distribution (see
<a class="xref" href="#connector-j-installing-source" title="3.4. Installing from the Development Source Tree">Section 3.4, “Installing from the Development Source Tree”</a>), you must use
JDK 1.4.2 or newer to compile the Connector package. For
Connector/J 5.1, you must have both JDK-1.6.x and JDK-1.5.x
installed to be able to build the source code.
</p><p>
Java 1.7 support requires Connector/J 5.1.21 and higher. Several
JDBC 4.1 methods were implemented for the first time in
Connector/J 5.1.21.
</p><p>
Because of the implementation of
<code class="classname">java.sql.Savepoint</code>, Connector/J 3.1.0 and
newer will not run on a Java runtime older than 1.4 unless the
class verifier is turned off (by setting the
<code class="option">-Xverify:none</code> option to the Java runtime). This
is because the class verifier will try to load the class
definition for <code class="classname">java.sql.Savepoint</code> even
though it is not accessed by the driver unless you actually use
savepoint functionality.
</p><p>
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
<code class="classname">java.util.LinkedHashMap</code> which was first
available in JDK-1.4.0.
</p><p>
MySQL Connector/J does not support JDK-1.1.x or JDK-1.0.x.
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-installing"></a>Chapter 3. Connector/J Installation</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-binary-installation">3.1. Installing Connector/J from a Binary Distribution</a></span></dt><dt><span class="section"><a href="#connector-j-installing-classpath">3.2. Installing the Driver and Configuring the <code class="literal">CLASSPATH</code></a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading">3.3. Upgrading from an Older Version</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-installing-upgrading-5-1">3.3.1. Upgrading to MySQL Connector/J 5.1.x</a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading-issues">3.3.2. JDBC-Specific Issues When Upgrading to MySQL Server 4.1 or Newer</a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading-3-0-to-3-1">3.3.3. Upgrading from MySQL Connector/J 3.0 to 3.1</a></span></dt></dl></dd><dt><span class="section"><a href="#connector-j-installing-source">3.4. Installing from the Development Source Tree</a></span></dt></dl></div><p>
You can install the Connector/J package using either the binary or
source distribution. The binary distribution provides the easiest
method for installation; the source distribution lets you
customize your installation further. With either solution, you
manually add the Connector/J location to your Java
<code class="literal">CLASSPATH</code>.
</p><p>
If you are upgrading from a previous version, read the upgrade
information in <a class="xref" href="#connector-j-installing-upgrading" title="3.3. Upgrading from an Older Version">Section 3.3, “Upgrading from an Older Version”</a>
before continuing.
</p><p>
Connector/J is also available as part of the Maven project. For
more information, and to download the Connector/J JAR files, see
the <a class="ulink" href="http://www.ibiblio.org/maven/" target="_top">Maven
repository</a>.
</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-binary-installation"></a>3.1. Installing Connector/J from a Binary Distribution</h2></div></div></div><p>
For the easiest method of installation, use the binary
distribution of the Connector/J package. The binary distribution
is available either as a tar/gzip or zip file. Extract it to a
suitable location, then optionally make the information about
the package available by changing your
<code class="literal">CLASSPATH</code> (see
<a class="xref" href="#connector-j-installing-classpath" title="3.2. Installing the Driver and Configuring the CLASSPATH">Section 3.2, “Installing the Driver and Configuring the <code class="literal">CLASSPATH</code>”</a>).
</p><p>
MySQL Connector/J is distributed as a <code class="literal">.zip</code> or
<code class="literal">.tar.gz</code> archive containing the sources, the
class files, and the JAR archive named
<code class="filename">mysql-connector-java-<em class="replaceable"><code>version</code></em>-bin.jar</code>.
</p><p>
Starting with Connector/J 3.1.9, the <code class="filename">.class</code>
files that constitute the JAR files are only included as part of
the driver JAR file.
</p><p>
Starting with Connector/J 3.1.8, the archive also includes a
debug build of the driver in a file named
<code class="filename">mysql-connector-java-<em class="replaceable"><code>version</code></em>-bin-g.jar</code>.
Do not use the debug build of the driver unless instructed to do
so when reporting a problem or a bug, 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
<code class="filename">src/lib/aspectjrt.jar</code> file that comes with
the Connector/J distribution.
</p><p>
Use the appropriate graphical or command-line utility to extract
the distribution (for example, WinZip for the .zip archive, and
<span class="command"><strong>tar</strong></span> for the .tar.gz archive). Because there
are potentially long file names in the distribution, we use the
GNU tar archive format. Use GNU tar (or an application that
understands the GNU tar archive format) to unpack the .tar.gz
variant of the distribution.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-installing-classpath"></a>3.2. Installing the Driver and Configuring the <code class="literal">CLASSPATH</code></h2></div></div></div><a class="indexterm" name="idm47020252087264"></a><p>
Once you have extracted the distribution archive, you can
install the driver by placing
<code class="filename">mysql-connector-java-<em class="replaceable"><code>version</code></em>-bin.jar
</code>in your classpath, either by adding the full path to
it to your <code class="literal">CLASSPATH</code> environment variable, or
by directly specifying it with the command line switch
<code class="literal">-cp</code> when starting the JVM.
</p><p>
To use the driver with the JDBC
<code class="literal">DriverManager</code>, use
<code class="literal">com.mysql.jdbc.Driver</code> as the class that
implements <code class="classname">java.sql.Driver</code>.
</p><p>
You can set the <code class="literal">CLASSPATH</code> environment
variable under Unix, Linux or Mac OS X either locally for a user
within their <code class="literal">.profile</code>,
<code class="literal">.login</code> or other login file. You can also set
it globally by editing the global
<code class="literal">/etc/profile</code> file.
</p><p>
For example, add the Connector/J driver to your
<code class="literal">CLASSPATH</code> using one of the following forms,
depending on your command shell:
</p><pre class="programlisting">
# Bourne-compatible shell (sh, ksh, bash, zsh):
shell> export CLASSPATH=/path/mysql-connector-java-<em class="replaceable"><code>ver</code></em>-bin.jar:$CLASSPATH
# C shell (csh, tcsh):
shell> setenv CLASSPATH /path/mysql-connector-java-<em class="replaceable"><code>ver</code></em>-bin.jar:$CLASSPATH
</pre><p>
Within Windows 2000, Windows XP, Windows Server 2003 and Windows
Vista, you set the environment variable through the System
Control Panel.
</p><p>
To use MySQL Connector/J with an application server such as
GlassFish, Tomcat or JBoss, read your vendor's documentation for
more information on how to configure third-party class
libraries, as most application servers ignore the
<code class="literal">CLASSPATH</code> environment variable. For
configuration examples for some J2EE application servers, see
<a class="xref" href="#connector-j-usagenotes-j2ee-concepts-connection-pooling" title="Chapter 7. Connection Pooling with Connector/J">Chapter 7, <i>Connection Pooling with Connector/J</i></a>
<a class="xref" href="#connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections" title="8.1. Configuring Load Balancing with Connector/J">Section 8.1, “Configuring Load Balancing with Connector/J”</a>,
and
<a class="xref" href="#connector-j-usagenotes-j2ee-concepts-load-balancing-failover" title="8.2. Configuring Failover with Connector/J">Section 8.2, “Configuring Failover with Connector/J”</a>.
However, the authoritative source for JDBC connection pool
configuration information for your particular application server
is the documentation for that application server.
</p><p>
If you are developing servlets or JSPs, and your application
server is J2EE-compliant, you can put the driver's
<code class="literal">.jar</code> file in the
<code class="filename">WEB-INF/lib</code> subdirectory of your webapp, as
this is a standard location for third party class libraries in
J2EE web applications.
</p><p>
You can also use the <code class="classname">MysqlDataSource</code> or
<code class="classname">MysqlConnectionPoolDataSource</code> classes in
the <code class="literal">com.mysql.jdbc.jdbc2.optional</code> package, if
your J2EE application server supports or requires them. Starting
with Connector/J 5.0.0, the
<code class="literal">javax.sql.XADataSource</code> interface is
implemented using the
<code class="literal">com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</code>
class, which supports XA distributed transactions when used in
combination with MySQL server version 5.0.
</p><p>
The various <code class="classname">MysqlDataSource</code> classes
support the following parameters (through standard set
mutators):
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">user</code>
</p></li><li class="listitem"><p>
<code class="literal">password</code>
</p></li><li class="listitem"><p>
<code class="literal">serverName</code> (see the previous section
about fail-over hosts)
</p></li><li class="listitem"><p>
<code class="literal">databaseName</code>
</p></li><li class="listitem"><p>
<code class="literal">port</code>
</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-installing-upgrading"></a>3.3. Upgrading from an Older Version</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="#connector-j-installing-upgrading-5-1">3.3.1. Upgrading to MySQL Connector/J 5.1.x</a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading-issues">3.3.2. JDBC-Specific Issues When Upgrading to MySQL Server 4.1 or Newer</a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading-3-0-to-3-1">3.3.3. Upgrading from MySQL Connector/J 3.0 to 3.1</a></span></dt></dl></div><p>
This section has information for users who are upgrading from
one version of Connector/J to another, or to a new version of
the MySQL server that supports a more recent level of JDBC. A
newer version of Connector/J might include changes to support
new features, improve existing functionality, or comply with new
standards.
</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-j-installing-upgrading-5-1"></a>3.3.1. Upgrading to MySQL Connector/J 5.1.x</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
In Connector/J 5.0.x and earlier, the alias for a table in
a <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/select.html" target="_top"><code class="literal">SELECT</code></a> statement is
returned when accessing the result set metadata using
<code class="function">ResultSetMetaData.getColumnName()</code>.
This behavior however is not JDBC compliant, and in
Connector/J 5.1 this behavior was changed so that the
original table name, rather than the alias, is returned.
</p><p>
The JDBC-compliant behavior is designed to let API users
reconstruct the DML statement based on the metadata within
<code class="literal">ResultSet</code> and
<code class="literal">ResultSetMetaData</code>.
</p><p>
You can get the alias for a column in a result set by
calling
<code class="function">ResultSetMetaData.getColumnLabel()</code>.
To use the old noncompliant behavior with
<code class="function">ResultSetMetaData.getColumnName()</code>,
use the <code class="option">useOldAliasMetadataBehavior</code>
option and set the value to <code class="literal">true</code>.
</p><p>
In Connector/J 5.0.x, the default value of
<code class="option">useOldAliasMetadataBehavior</code> was
<code class="literal">true</code>, but in Connector/J 5.1 this was
changed to a default value of <code class="literal">false</code>.
</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-j-installing-upgrading-issues"></a>3.3.2. JDBC-Specific Issues When Upgrading to MySQL Server 4.1 or Newer</h3></div></div></div><a class="indexterm" name="idm47020252050096"></a><a class="indexterm" name="idm47020252048944"></a><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<span class="emphasis"><em>Using the UTF-8 Character Encoding</em></span> -
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 <code class="literal">latin1</code> tables on the
server.
</p><p>
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,
add the following property to your connection URL:
</p><p>
<code class="computeroutput">useOldUTF8Behavior=true</code>
</p></li><li class="listitem"><p>
<span class="emphasis"><em>Server-side Prepared Statements</em></span> -
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:
</p><p>
<code class="computeroutput">useServerPrepStmts=false</code>
</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-j-installing-upgrading-3-0-to-3-1"></a>3.3.3. Upgrading from MySQL Connector/J 3.0 to 3.1</h3></div></div></div><p>
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, <code class="literal">SQLState</code> codes returned in
error messages by the server and various performance
enhancements that can be enabled or disabled using
configuration properties.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<span class="bold"><strong>Unicode Character Sets</strong></span>:
See the next section, as well as
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/charset.html" target="_top">Character Set Support</a>, for information on this MySQL
feature. If you have something misconfigured, it will
usually show up as an error with a message similar to
<code class="literal">Illegal mix of collations</code>.
</p></li><li class="listitem"><p>
<span class="bold"><strong>Server-side Prepared
Statements</strong></span>: 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).
</p><p>
Starting with version 3.1.7, the driver scans SQL you are
preparing using all variants of
<code class="literal">Connection.prepareStatement()</code> 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
<code class="literal">emulateUnsupportedPstmts=false</code> in your
JDBC URL.
</p><p>
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
connection property
<code class="literal">useServerPrepStmts=false</code>.
</p></li><li class="listitem"><p>
<span class="bold"><strong>Datetimes</strong></span> with all-zero
components (<code class="literal">0000-00-00 ...</code>): These
values cannot be represented reliably in Java. Connector/J
3.0.x always converted them to <code class="literal">NULL</code>
when being read from a ResultSet.
</p><p>
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
<code class="literal">zeroDateTimeBehavior</code> configuration
property. The permissible values are:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
<code class="literal">exception</code> (the default), which
throws an SQLException with an SQLState of
<code class="literal">S1009</code>.
</p></li><li class="listitem"><p>
<code class="literal">convertToNull</code>, which returns
<code class="literal">NULL</code> instead of the date.
</p></li><li class="listitem"><p>
<code class="literal">round</code>, which rounds the date to the
nearest closest value which is
<code class="literal">0001-01-01</code>.
</p></li></ul></div><p>
Starting with Connector/J 3.1.7,
<code class="literal">ResultSet.getString()</code> can be decoupled
from this behavior using
<code class="literal">noDatetimeStringSync=true</code> (the default
value is <code class="literal">false</code>) so that you can
retrieve the unaltered all-zero value as a String. Note
that this also precludes using any time zone conversions,
therefore the driver will not allow you to enable
<code class="literal">noDatetimeStringSync</code> and
<code class="literal">useTimezone</code> at the same time.
</p></li><li class="listitem"><p>
<span class="bold"><strong>New SQLState Codes</strong></span>:
Connector/J 3.1 uses SQL:1999 SQLState codes returned by
the MySQL server (if supported), which are different from
the legacy X/Open state codes that Connector/J 3.0 uses.
If connected to a MySQL server older than MySQL-4.1.0 (the
oldest version to return SQLStates as part of the error
code), the driver will use a built-in mapping. You can
revert to the old mapping by using the configuration
property <code class="literal">useSqlStateCodes=false</code>.
</p></li><li class="listitem"><p>
<span class="bold"><strong><code class="literal">ResultSet.getString()</code></strong></span>:
Calling <code class="literal">ResultSet.getString()</code> on a
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/blob.html" target="_top"><code class="literal">BLOB</code></a> column will now return
the address of the <code class="literal">byte[]</code> array that
represents it, instead of a <code class="literal">String</code>
representation of the <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/blob.html" target="_top"><code class="literal">BLOB</code></a>.
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/blob.html" target="_top"><code class="literal">BLOB</code></a> values have no
character set, so they cannot be converted to
<code class="literal">java.lang.String</code>s without data loss or
corruption.
</p><p>
To store strings in MySQL with LOB behavior, use one of
the <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/blob.html" target="_top"><code class="literal">TEXT</code></a> types, which the
driver will treat as a <code class="literal">java.sql.Clob</code>.
</p></li><li class="listitem"><p>
<span class="bold"><strong>Debug builds</strong></span>: Starting
with Connector/J 3.1.8 a debug build of the driver in a
file named
<code class="filename">mysql-connector-java-<em class="replaceable"><code>version</code></em>-bin-g.jar</code>
is shipped alongside the normal binary jar file that is
named
<code class="filename">mysql-connector-java-<em class="replaceable"><code>version</code></em>-bin.jar</code>.
</p><p>
Starting with Connector/J 3.1.9, we do not ship the
<code class="literal">.class</code> files unbundled, they are only
available in the JAR archives that ship with the driver.
</p><p>
Do not use the debug build of the driver unless instructed
to do so when reporting a problem or bug, 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
<code class="filename">src/lib/aspectjrt.jar</code> file that comes
with the Connector/J distribution.
</p></li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-installing-source"></a>3.4. Installing from the Development Source Tree</h2></div></div></div><div xmlns="http://www.w3.org/1999/xhtml" class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Caution</div><p xmlns="">
Read this section only if you are interested in helping us
test our new code. To just get MySQL Connector/J up and
running on your system, use a standard binary release
distribution.
</p></div><p>
To install MySQL Connector/J from the development source tree,
make sure that you have the following software on your system:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
A Bazaar client, to check out the sources from our Launchpad
repository (available from
<a class="ulink" href="http://bazaar-vcs.org/" target="_top">http://bazaar-vcs.org/</a>).
</p></li><li class="listitem"><p>
Apache Ant version 1.7 or newer (available from
<a class="ulink" href="http://ant.apache.org/" target="_top">http://ant.apache.org/</a>).
</p></li><li class="listitem"><p>
JDK 1.4.2 or later. Although MySQL Connector/J can be be
used with older JDKs, compiling it from source requires at
least JDK 1.4.2. To build Connector/J 5.1 requires JDK 1.6.x
<span class="emphasis"><em>and</em></span> an older JDK such as JDK 1.5.x;
point your <code class="literal">JAVA_HOME</code> environment variable
at the older installation.
</p></li><li class="listitem"><p>
The Ant Contrib and Junit libraries.
</p></li></ul></div><p>
To check out and compile a specific branch of MySQL Connector/J,
follow these steps:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Check out the latest code from the branch that you want with
one of the following commands.
</p><p>
The source code repository for MySQL Connector/J is located
on Launchpad at
<a class="ulink" href="https://code.launchpad.net/connectorj" target="_top">https://code.launchpad.net/connectorj</a>. To
check out the latest development branch, use:
</p><pre class="programlisting">
shell> <strong class="userinput"><code>bzr branch lp:connectorj</code></strong>i
</pre><p>
This creates a <code class="filename">connectorj</code> subdirectory
in the current directory that contains the latest sources
for the requested branch.
</p><p>
To check out the latest 5.1 code, use:
</p><pre class="programlisting">
shell> <strong class="userinput"><code>bzr branch lp:connectorj/5.1</code></strong>
</pre><p>
This creates a <code class="filename">5.1</code> subdirectory in the
current directory containing the latest 5.1 code.
</p></li><li class="listitem"><p>
To build Connector/J 5.1, make sure that you have both JDK
1.6.x installed and an older JDK such as JDK 1.5.x. This is
because Connector/J supports both JDBC 3.0 (which was prior
to JDK 1.6.x) and JDBC 4.0. Set your
<code class="literal">JAVA_HOME</code> environment variable to the
path of the older JDK installation.
</p></li><li class="listitem"><p>
Place the required extra libraries,
<code class="filename">ant-contrib.jar</code> and
<code class="filename">junit.jar</code>, in a separate
directory—for example, "C:\connectorj-extralibs".
</p></li><li class="listitem"><p>
Change your current working directory to either the
<code class="filename">connectorj</code> or <code class="filename">5.1</code>
directory, depending on which branch you intend to build.
</p></li><li class="listitem"><p>
To build Connector/J 5.1, edit the
<code class="filename">build.xml</code> to reflect the locations of
your JDK 1.6.x installation and the extra libraries. The
lines to change are:
</p><pre class="programlisting">
<property name="com.mysql.jdbc.java6.javac" value="C:\jvms\jdk1.6.0\bin\javac.exe" />
<property name="com.mysql.jdbc.java6.rtjar" value="C:\jvms\jdk1.6.0\jre\lib\rt.jar" />
<property name="com.mysql.jdbc.extra.libs" value="C:\connectorj-extralibs" />
</pre><p>
Alternatively, you can set the value of these property names
through the Ant <code class="option">-D</code> option.
</p></li><li class="listitem"><p>
Issue the following command to compile the driver and create
a <code class="filename">.jar</code> file suitable for installation:
</p><pre class="programlisting">
shell> <strong class="userinput"><code>ant dist</code></strong>
</pre><p>
This creates a <code class="filename">build</code> directory in the
current directory, where all build output will go. A
directory is created in the <code class="filename">build</code>
directory that includes the version number of the sources
you are building from. This directory contains the sources,
compiled <code class="filename">.class</code> files, and a
<code class="filename">.jar</code> file suitable for deployment. For
other possible targets, including ones that will create a
fully packaged distribution, issue the following command:
</p><pre class="programlisting">
shell> <strong class="userinput"><code>ant -projecthelp</code></strong>
</pre></li><li class="listitem"><p>
A newly created <code class="filename">.jar</code> file containing
the JDBC driver will be placed in the directory
<code class="filename">build/mysql-connector-java-<em class="replaceable"><code>version</code></em></code>.
</p><p>
Install the newly created JDBC driver as you would a binary
<code class="filename">.jar</code> file that you download from MySQL,
by following the instructions in
<a class="xref" href="#connector-j-installing-classpath" title="3.2. Installing the Driver and Configuring the CLASSPATH">Section 3.2, “Installing the Driver and Configuring the <code class="literal">CLASSPATH</code>”</a>.
</p></li></ol></div><p>
A package containing both the binary and source code for
Connector/J 5.1 can also be found at the following location:
<a class="ulink" href="http://dev.mysql.com/downloads/connector/j/5.1.html" target="_top">
Connector/J 5.1 Download</a>
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-examples"></a>Chapter 4. Connector/J Examples</h1></div></div></div><a class="indexterm" name="idm47020251968496"></a><p>
Examples of using Connector/J are located throughout this
document. This section provides a summary and links to these
examples.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<a class="xref" href="#connector-j-examples-connection-drivermanager" title="Example 6.1. Connector/J: Obtaining a connection from the DriverManager">Example 6.1, “Connector/J: Obtaining a connection from the
<code class="literal">DriverManager</code>”</a>
</p></li><li class="listitem"><p>
<a class="xref" href="#connector-j-examples-execute-select" title="Example 6.2. Connector/J: Using java.sql.Statement to execute a SELECT query">Example 6.2, “Connector/J: Using java.sql.Statement to execute a
<code class="literal">SELECT</code> query”</a>
</p></li><li class="listitem"><p>
<a class="xref" href="#connector-j-examples-stored-procedure" title="Example 6.3. Connector/J: Calling Stored Procedures">Example 6.3, “Connector/J: Calling Stored Procedures”</a>
</p></li><li class="listitem"><p>
<a class="xref" href="#connector-j-examples-preparecall" title="Example 6.4. Connector/J: Using Connection.prepareCall()">Example 6.4, “Connector/J: Using <code class="literal">Connection.prepareCall()</code>”</a>
</p></li><li class="listitem"><p>
<a class="xref" href="#connector-j-examples-output-param" title="Example 6.5. Connector/J: Registering output parameters">Example 6.5, “Connector/J: Registering output parameters”</a>
</p></li><li class="listitem"><p>
<a class="xref" href="#connector-j-examples-callablestatement" title="Example 6.6. Connector/J: Setting CallableStatement input parameters">Example 6.6, “Connector/J: Setting <code class="literal">CallableStatement</code> input
parameters”</a>
</p></li><li class="listitem"><p>
<a class="xref" href="#connector-j-examples-retrieving-results-params" title="Example 6.7. Connector/J: Retrieving results and output parameter values">Example 6.7, “Connector/J: Retrieving results and output parameter values”</a>
</p></li><li class="listitem"><p>
<a class="xref" href="#connector-j-examples-autoincrement-getgeneratedkeys" title="Example 6.8. Connector/J: Retrieving AUTO_INCREMENT column values using Statement.getGeneratedKeys()">Example 6.8, “Connector/J: Retrieving <code class="literal">AUTO_INCREMENT</code> column values
using <code class="literal">Statement.getGeneratedKeys()</code>”</a>
</p></li><li class="listitem"><p>
<a class="xref" href="#connector-j-examples-autoincrement-select" title="Example 6.9. Connector/J: Retrieving AUTO_INCREMENT column values using SELECT LAST_INSERT_ID()">Example 6.9, “Connector/J: Retrieving <code class="literal">AUTO_INCREMENT</code> column values
using <code class="literal">SELECT LAST_INSERT_ID()</code>”</a>
</p></li><li class="listitem"><p>
<a class="xref" href="#connector-j-examples-autoincrement-updateable-resultsets" title="Example 6.10. Connector/J: Retrieving AUTO_INCREMENT column values in Updatable ResultSets">Example 6.10, “Connector/J: Retrieving <code class="literal">AUTO_INCREMENT</code> column values
in <code class="literal">Updatable ResultSets</code>”</a>
</p></li><li class="listitem"><p>
<a class="xref" href="#connector-j-examples-connectionpool-j2ee" title="Example 7.1. Connector/J: Using a connection pool with a J2EE application server">Example 7.1, “Connector/J: Using a connection pool with a J2EE application server”</a>
</p></li><li class="listitem"><p>
<a class="xref" href="#connector-j-examples-transaction-retry" title="Example 14.1. Connector/J: Example of transaction with retry logic">Example 14.1, “Connector/J: Example of transaction with retry logic”</a>
</p></li></ul></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-reference"></a>Chapter 5. Connector/J (JDBC) Reference</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-reference-configuration-properties">5.1. Driver/Datasource Class Names, URL Syntax and Configuration Properties
for Connector/J</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-useconfigs">5.1.1. Properties Files for the <code class="literal">useConfigs</code> Option</a></span></dt></dl></dd><dt><span class="section"><a href="#connector-j-reference-implementation-notes">5.2. JDBC API Implementation Notes</a></span></dt><dt><span class="section"><a href="#connector-j-reference-type-conversions">5.3. Java, JDBC and MySQL Types</a></span></dt><dt><span class="section"><a href="#connector-j-reference-charsets">5.4. Using Character Sets and Unicode</a></span></dt><dt><span class="section"><a href="#connector-j-reference-using-ssl">5.5. Connecting Securely Using SSL</a></span></dt><dt><span class="section"><a href="#connector-j-using-pam">5.6. Connecting Using PAM Authentication</a></span></dt><dt><span class="section"><a href="#connector-j-reference-replication-connection">5.7. Using Master/Slave Replication with ReplicationConnection</a></span></dt><dt><span class="section"><a href="#connector-j-reference-error-sqlstates">5.8. Mapping MySQL Error Numbers to JDBC SQLState Codes</a></span></dt></dl></div><p>
This section of the manual contains reference material for MySQL
Connector/J.
</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-reference-configuration-properties"></a>5.1. Driver/Datasource Class Names, URL Syntax and Configuration Properties
for Connector/J</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="#connector-j-useconfigs">5.1.1. Properties Files for the <code class="literal">useConfigs</code> Option</a></span></dt></dl></div><a class="indexterm" name="idm47020251947936"></a><a class="indexterm" name="idm47020251946736"></a><p>
The name of the class that implements
<code class="literal">java.sql.Driver</code> in MySQL Connector/J is
<code class="literal">com.mysql.jdbc.Driver</code>. The
<code class="literal">org.gjt.mm.mysql.Driver</code> class name is also
usable for backward compatibility with MM.MySQL, the predecessor
of Connector/J. Use this class name when registering the driver,
or when otherwise configuring software to use MySQL Connector/J.
</p><h3><a name="idm47020251943632"></a>
JDBC URL Format
</h3><p>
The JDBC URL format for MySQL Connector/J is as follows, with
items in square brackets ([, ]) being optional:
</p><pre class="programlisting">
jdbc:mysql://[<em class="replaceable"><code>host</code></em>][,<em class="replaceable"><code>failoverhost</code></em>...][:<em class="replaceable"><code>port</code></em>]/[<em class="replaceable"><code>database</code></em>] »
[?<em class="replaceable"><code>propertyName1</code></em>][=<em class="replaceable"><code>propertyValue1</code></em>][&<em class="replaceable"><code>propertyName2</code></em>][=<em class="replaceable"><code>propertyValue2</code></em>]...
</pre><p>
If the host name is not specified, it defaults to
<code class="literal">127.0.0.1</code>. If the port is not specified, it
defaults to <code class="literal">3306</code>, the default port number for
MySQL servers.
</p><pre class="programlisting">
jdbc:mysql://[<em class="replaceable"><code>host</code></em>:<em class="replaceable"><code>port</code></em>],[<em class="replaceable"><code>host</code></em>:<em class="replaceable"><code>port</code></em>].../[<em class="replaceable"><code>database</code></em>] »
[?<em class="replaceable"><code>propertyName1</code></em>][=<em class="replaceable"><code>propertyValue1</code></em>][&<em class="replaceable"><code>propertyName2</code></em>][=<em class="replaceable"><code>propertyValue2</code></em>]...
</pre><p>
Here is a sample connection URL:
</p><pre class="programlisting">
jdbc:mysql://localhost:3306/sakila?profileSQL=true
</pre><h3><a name="idm47020251933056"></a>
IPv6 Connections
</h3><a class="indexterm" name="idm47020251932624"></a><p>
For IPv6 connections, use this alternative syntax to specify
hosts in the URL,
<code class="literal">address=(<em class="replaceable"><code>key</code></em>=<em class="replaceable"><code>value</code></em>)</code>.
Supported keys are:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">(protocol=tcp)</code>, or
<code class="literal">(protocol=pipe)</code> for named pipes on
Windows.
</p></li><li class="listitem"><p>
<code class="literal">(path=<em class="replaceable"><code>path_to_pipe</code></em>)</code>
for named pipes.
</p></li><li class="listitem"><p>
<code class="literal">(host=<em class="replaceable"><code>hostname</code></em>)</code>
for TCP connections.
</p></li><li class="listitem"><p>
<code class="literal">(port=<em class="replaceable"><code>port_number</code></em>)</code>
for TCP connections.
</p></li></ul></div><p>
For example:
</p><pre class="programlisting">
jdbc:mysql://address=(protocol=tcp)(host=localhost)(port=3306)(user=test)/db
</pre><p>
Any other parameters are treated as host-specific properties
that follow the conventions of the JDBC URL properties. This now
allows per-host overrides of any configuration property for
multi-host connections (that is, when using failover, load
balancing, or replication). Limit the overrides to user,
password, network timeouts and statement and metadata cache
sizes; the results of other per-host overrides are not defined.
</p><h3><a name="idm47020251921168"></a>
Initial Database for Connection
</h3><p>
If the database is not specified, the connection is made with no
default database. In this case, either call the
<code class="function">setCatalog()</code> method on the Connection
instance, or fully specify table names using the database name
(that is, <code class="literal">SELECT
<em class="replaceable"><code>dbname</code></em>.<em class="replaceable"><code>tablename</code></em>.<em class="replaceable"><code>colname</code></em>
FROM dbname.tablename...</code>) in your SQL. Opening a
connection without specifying the database to use is generally
only useful when building tools that work with multiple
databases, such as GUI database managers.
</p><div xmlns="http://www.w3.org/1999/xhtml" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p xmlns="">
Always use the <code class="literal">Connection.setCatalog()</code>
method to specify the desired database in JDBC applications,
rather than the <code class="literal">USE
<em class="replaceable"><code>database</code></em></code> statement.
</p></div><h3><a name="idm47020251915888"></a>
Failover Support
</h3><a class="indexterm" name="idm47020251915456"></a><p>
MySQL Connector/J has failover support. This enables the driver
to fail over to any number of slave hosts and still perform
read-only queries. Failover only happens when the connection is
in an <code class="function">autoCommit(true)</code> state, because
failover cannot happen reliably when a
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/glossary.html#glos_transaction" target="_top">transaction</a> is in
progress. Most application servers and connection pools set
<code class="literal">autoCommit</code> to <code class="literal">true</code> at the
end of every transaction/connection use.
</p><p>
The failover functionality has the following behavior:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
If the URL property <code class="literal">autoReconnect</code> is
<code class="literal">false</code>: Failover only happens at
connection initialization, and failback occurs when the
driver determines that the first host has become available
again.
</p></li><li class="listitem"><p>
If the URL property <code class="literal">autoReconnect</code> is
<code class="literal">true</code>: Failover happens when the driver
determines that the connection has failed (checked before
<span class="emphasis"><em>every</em></span> query), and falls back to the
first host when it determines that the host has become
available again (after
<code class="literal">queriesBeforeRetryMaster</code> queries have
been issued).
</p></li></ul></div><p>
In either case, whenever you are connected to a
<span class="quote">“<span class="quote">failed-over</span>”</span> server, the connection is set to
read-only state, so queries that attempt to modify data will
throw exceptions (the query will
<span class="bold"><strong>never</strong></span> be processed by the MySQL
server).
</p><h3><a name="idm47020251904416"></a>
Setting Configuration Properties
</h3><p>
Configuration properties define how Connector/J will make a
connection to a MySQL server. Unless otherwise noted, properties
can be set for a <code class="literal">DataSource</code> object or for a
<code class="literal">Connection</code> object.
</p><p>
Configuration properties can be set in one of the following
ways:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Using the <code class="literal">set*()</code> methods on MySQL
implementations of <code class="literal">java.sql.DataSource</code>
(which is the preferred method when using implementations of
<code class="literal">java.sql.DataSource</code>):
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
<code class="literal">com.mysql.jdbc.jdbc2.optional.MysqlDataSource</code>
</p></li><li class="listitem"><p>
<code class="literal">com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource</code>
</p></li></ul></div></li><li class="listitem"><p>
As a key/value pair in the
<code class="literal">java.util.Properties</code> instance passed to
<code class="literal">DriverManager.getConnection()</code> or
<code class="literal">Driver.connect()</code>
</p></li><li class="listitem"><p>
As a JDBC URL parameter in the URL given to
<code class="literal">java.sql.DriverManager.getConnection()</code>,
<code class="literal">java.sql.Driver.connect()</code> or the MySQL
implementations of the
<code class="literal">javax.sql.DataSource</code>
<code class="function">setURL()</code> method.
</p><div xmlns="http://www.w3.org/1999/xhtml" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p xmlns="">
If the mechanism you use to configure a JDBC URL is
XML-based, use the XML character literal &amp; to
separate configuration parameters, as the ampersand is a
reserved character for XML.
</p></div></li></ul></div><p>
The properties are listed in the following tables.
</p><p><b>Connection/Authentication. </b>
</p><div class="informaltable"><table summary="This table lists Connector/J Connection/Authentication
connection properties." border="1"><colgroup><col class="cj_propstbl_prop_name"><col class="cj_propstbl_prop_defn"><col class="cj_propstbl_default"><col class="cj_propstbl_since_version"></colgroup><tbody><tr><td scope="row"><span class="bold"><strong> Property Name </strong></span></td><td><span class="bold"><strong> Definition </strong></span></td><td><span class="bold"><strong> Default Value </strong></span></td><td><span class="bold"><strong> Since Version </strong></span></td></tr><tr><td scope="row">user</td><td>The user to connect as</td><td> </td><td>all versions</td></tr><tr><td scope="row">password</td><td>The password to use when connecting</td><td> </td><td>all versions</td></tr><tr><td scope="row">socketFactory</td><td>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.</td><td>com.mysql.jdbc.StandardSocketFactory</td><td>3.0.3</td></tr><tr><td scope="row">connectTimeout</td><td>Timeout for socket connect (in milliseconds), with 0 being no timeout.
Only works on JDK-1.4 or newer. Defaults to '0'.</td><td>0</td><td>3.0.1</td></tr><tr><td scope="row">socketTimeout</td><td>Timeout on network socket operations (0, the default means no timeout).</td><td>0</td><td>3.0.1</td></tr><tr><td scope="row">connectionLifecycleInterceptors</td><td>A comma-delimited list of classes that implement
"com.mysql.jdbc.ConnectionLifecycleInterceptor" that
should notified of connection lifecycle events
(creation, destruction, commit, rollback, setCatalog and
setAutoCommit) and potentially alter the execution of
these commands. ConnectionLifecycleInterceptors are
"stackable", more than one interceptor may be specified
via the configuration property as a comma-delimited
list, with the interceptors executed in order from left
to right.</td><td> </td><td>5.1.4</td></tr><tr><td scope="row">useConfigs</td><td>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.</td><td> </td><td>3.1.5</td></tr><tr><td scope="row">authenticationPlugins</td><td>Comma-delimited list of classes that implement
com.mysql.jdbc.AuthenticationPlugin and which will be
used for authentication unless disabled by
"disabledAuthenticationPlugins" property.</td><td> </td><td>5.1.19</td></tr><tr><td scope="row">defaultAuthenticationPlugin</td><td>Name of a class implementing com.mysql.jdbc.AuthenticationPlugin which
will be used as the default authentication plugin (see
below). It is an error to use a class which is not
listed in "authenticationPlugins" nor it is one of the
built-in plugins. It is an error to set as default a
plugin which was disabled with
"disabledAuthenticationPlugins" property. It is an error
to set this value to null or the empty string (i.e.
there must be at least a valid default authentication
plugin specified for the connection, meeting all
constraints listed above).</td><td>com.mysql.jdbc.authentication.MysqlNativePasswordPlugin</td><td>5.1.19</td></tr><tr><td scope="row">disabledAuthenticationPlugins</td><td>Comma-delimited list of classes implementing
com.mysql.jdbc.AuthenticationPlugin or mechanisms, i.e.
"mysql_native_password". The authentication plugins or
mechanisms listed will not be used for authentication
which will fail if it requires one of them. It is an
error to disable the default authentication plugin
(either the one named by "defaultAuthenticationPlugin"
property or the hard-coded one if
"defaultAuthenticationPlugin" property is not set).</td><td> </td><td>5.1.19</td></tr><tr><td scope="row">disconnectOnExpiredPasswords</td><td>If "disconnectOnExpiredPasswords" is set to "false" and password is
expired then server enters "sandbox" mode and sends
ERR(08001, ER_MUST_CHANGE_PASSWORD) for all commands
that are not needed to set a new password until a new
password is set.</td><td>true</td><td>5.1.23</td></tr><tr><td scope="row">interactiveClient</td><td>Set the CLIENT_INTERACTIVE flag, which tells MySQL to timeout
connections based on INTERACTIVE_TIMEOUT instead of
WAIT_TIMEOUT</td><td>false</td><td>3.1.0</td></tr><tr><td scope="row">localSocketAddress</td><td>Hostname or IP address given to explicitly configure the interface that
the driver will bind the client side of the TCP/IP
connection to when connecting.</td><td> </td><td>5.0.5</td></tr><tr><td scope="row">propertiesTransform</td><td>An implementation of com.mysql.jdbc.ConnectionPropertiesTransform that
the driver will use to modify URL properties passed to
the driver before attempting a connection</td><td> </td><td>3.1.4</td></tr><tr><td scope="row">useCompression</td><td>Use zlib compression when communicating with the server (true/false)?
Defaults to 'false'.</td><td>false</td><td>3.0.17</td></tr></tbody></table></div><p>
</p><p><b>Networking. </b>
</p><div class="informaltable"><table summary="This table lists Connector/J Networking connection
properties." border="1"><colgroup><col class="cj_propstbl_prop_name"><col class="cj_propstbl_prop_defn"><col class="cj_propstbl_default"><col class="cj_propstbl_since_version"></colgroup><tbody><tr><td scope="row"><span class="bold"><strong> Property Name </strong></span></td><td><span class="bold"><strong> Definition </strong></span></td><td><span class="bold"><strong> Default Value </strong></span></td><td><span class="bold"><strong> Since Version </strong></span></td></tr><tr><td scope="row">maxAllowedPacket</td><td>Maximum allowed packet size to send to server. If not set, the value of
system variable 'max_allowed_packet' will be used to
initialize this upon connecting. This value will not
take effect if set larger than the value of
'max_allowed_packet'. Also, due to an internal
dependency with the property "blobSendChunkSize", this
setting has a minimum value of "8203" if
"useServerPrepStmts" is set to "true".</td><td>-1</td><td>5.1.8</td></tr><tr><td scope="row">tcpKeepAlive</td><td>If connecting using TCP/IP, should the driver set SO_KEEPALIVE?</td><td>true</td><td>5.0.7</td></tr><tr><td scope="row">tcpNoDelay</td><td>If connecting using TCP/IP, should the driver set SO_TCP_NODELAY
(disabling the Nagle Algorithm)?</td><td>true</td><td>5.0.7</td></tr><tr><td scope="row">tcpRcvBuf</td><td>If connecting using TCP/IP, should the driver set SO_RCV_BUF to the
given value? The default value of '0', means use the
platform default value for this property)</td><td>0</td><td>5.0.7</td></tr><tr><td scope="row">tcpSndBuf</td><td>If connecting using TCP/IP, should the driver set SO_SND_BUF to the
given value? The default value of '0', means use the
platform default value for this property)</td><td>0</td><td>5.0.7</td></tr><tr><td scope="row">tcpTrafficClass</td><td>If connecting using TCP/IP, should the driver set traffic class or
type-of-service fields ?See the documentation for
java.net.Socket.setTrafficClass() for more information.</td><td>0</td><td>5.0.7</td></tr></tbody></table></div><p>
</p><p><b>High Availability and Clustering. </b>
</p><div class="informaltable"><table summary="This table lists Connector/J High Availability and
Clustering connection properties." border="1"><colgroup><col class="cj_propstbl_prop_name"><col class="cj_propstbl_prop_defn"><col class="cj_propstbl_default"><col class="cj_propstbl_since_version"></colgroup><tbody><tr><td scope="row"><span class="bold"><strong> Property Name </strong></span></td><td><span class="bold"><strong> Definition </strong></span></td><td><span class="bold"><strong> Default Value </strong></span></td><td><span class="bold"><strong> Since Version </strong></span></td></tr><tr><td scope="row">autoReconnect</td><td>Should the driver try to re-establish stale and/or dead connections? If
enabled the driver will throw an exception for a queries
issued on a stale or dead connection, which belong to
the current transaction, but will attempt reconnect
before the next query issued on the connection in a new
transaction. The use of this feature is not recommended,
because it has side effects related to session state and
data consistency when applications don't handle
SQLExceptions properly, and is only designed to be used
when you are unable to configure your application to
handle SQLExceptions resulting from dead and stale
connections properly. Alternatively, as a last option,
investigate setting the MySQL server variable
"wait_timeout" to a high value, rather than the default
of 8 hours.</td><td>false</td><td>1.1</td></tr><tr><td scope="row">autoReconnectForPools</td><td>Use a reconnection strategy appropriate for connection pools (defaults
to 'false')</td><td>false</td><td>3.1.3</td></tr><tr><td scope="row">failOverReadOnly</td><td>When failing over in autoReconnect mode, should the connection be set to
'read-only'?</td><td>true</td><td>3.0.12</td></tr><tr><td scope="row">maxReconnects</td><td>Maximum number of reconnects to attempt if autoReconnect is true,
default is '3'.</td><td>3</td><td>1.1</td></tr><tr><td scope="row">reconnectAtTxEnd</td><td>If autoReconnect is set to true, should the driver attempt reconnections
at the end of every transaction?</td><td>false</td><td>3.0.10</td></tr><tr><td scope="row">retriesAllDown</td><td>When using loadbalancing, the number of times the driver should cycle
through available hosts, attempting to connect. Between
cycles, the driver will pause for 250ms if no servers
are available.</td><td>120</td><td>5.1.6</td></tr><tr><td scope="row">initialTimeout</td><td>If autoReconnect is enabled, the initial time to wait between re-connect
attempts (in seconds, defaults to '2').</td><td>2</td><td>1.1</td></tr><tr><td scope="row">roundRobinLoadBalance</td><td>When autoReconnect is enabled, and failoverReadonly is false, should we
pick hosts to connect to on a round-robin basis?</td><td>false</td><td>3.1.2</td></tr><tr><td scope="row">queriesBeforeRetryMaster</td><td>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.</td><td>50</td><td>3.0.2</td></tr><tr><td scope="row">secondsBeforeRetryMaster</td><td>How long should the driver wait, when failed over, before attempting</td><td>30</td><td>3.0.2</td></tr><tr><td scope="row">allowMasterDownConnections</td><td>Should replication-aware driver establish connections to slaves when
connection to master servers cannot be established at
initial connection? Defaults to 'false', which will
cause SQLException when configured master hosts are all
unavailable when establishing a new replication-aware
Connection.</td><td>false</td><td>5.1.27</td></tr><tr><td scope="row">replicationEnableJMX</td><td>Enables JMX-based management of load-balanced connection groups,
including live addition/removal of hosts from
load-balancing pool.</td><td>false</td><td>5.1.27</td></tr><tr><td scope="row">selfDestructOnPingMaxOperations</td><td>=If set to a non-zero value, the driver will report close the connection
and report failure when Connection.ping() or
Connection.isValid(int) is called if the connection's
count of commands sent to the server exceeds this value.</td><td>0</td><td>5.1.6</td></tr><tr><td scope="row">selfDestructOnPingSecondsLifetime</td><td>If set to a non-zero value, the driver will report close the connection
and report failure when Connection.ping() or
Connection.isValid(int) is called if the connection's
lifetime exceeds this value.</td><td>0</td><td>5.1.6</td></tr><tr><td scope="row">resourceId</td><td>A globally unique name that identifies the resource that this datasource
or connection is connected to, used for
XAResource.isSameRM() when the driver can't determine
this value based on hostnames used in the URL</td><td> </td><td>5.0.1</td></tr></tbody></table></div><p>
</p><p><b>Security. </b>
</p><div class="informaltable"><table summary="This table lists Connector/J Security connection
properties." border="1"><colgroup><col class="cj_propstbl_prop_name"><col class="cj_propstbl_prop_defn"><col class="cj_propstbl_default"><col class="cj_propstbl_since_version"></colgroup><tbody><tr><td scope="row"><span class="bold"><strong> Property Name </strong></span></td><td><span class="bold"><strong> Definition </strong></span></td><td><span class="bold"><strong> Default Value </strong></span></td><td><span class="bold"><strong> Since Version </strong></span></td></tr><tr><td scope="row">allowMultiQueries</td><td>Allow the use of ';' to delimit multiple queries during one statement
(true/false), defaults to 'false', and does not affect
the addBatch() and executeBatch() methods, which instead
rely on rewriteBatchStatements.</td><td>false</td><td>3.1.1</td></tr><tr><td scope="row">useSSL</td><td>Use SSL when communicating with the server (true/false), defaults to
'false'</td><td>false</td><td>3.0.2</td></tr><tr><td scope="row">requireSSL</td><td>Require SSL connection if useSSL=true? (defaults to 'false').</td><td>false</td><td>3.1.0</td></tr><tr><td scope="row">verifyServerCertificate</td><td>If "useSSL" is set to "true", should the driver verify the server's
certificate? When using this feature, the keystore
parameters should be specified by the
"clientCertificateKeyStore*" properties, rather than
system properties.</td><td>true</td><td>5.1.6</td></tr><tr><td scope="row">clientCertificateKeyStoreUrl</td><td>URL to the client certificate KeyStore (if not specified, use defaults)</td><td> </td><td>5.1.0</td></tr><tr><td scope="row">clientCertificateKeyStoreType</td><td>KeyStore type for client certificates (NULL or empty means use the
default, which is "JKS". Standard keystore types
supported by the JVM are "JKS" and "PKCS12", your
environment may have more available depending on what
security products are installed and available to the
JVM.</td><td>JKS</td><td>5.1.0</td></tr><tr><td scope="row">clientCertificateKeyStorePassword</td><td>Password for the client certificates KeyStore</td><td> </td><td>5.1.0</td></tr><tr><td scope="row">trustCertificateKeyStoreUrl</td><td>URL to the trusted root certificate KeyStore (if not specified, use
defaults)</td><td> </td><td>5.1.0</td></tr><tr><td scope="row">trustCertificateKeyStoreType</td><td>KeyStore type for trusted root certificates (NULL or empty means use the
default, which is "JKS". Standard keystore types
supported by the JVM are "JKS" and "PKCS12", your
environment may have more available depending on what
security products are installed and available to the
JVM.</td><td>JKS</td><td>5.1.0</td></tr><tr><td scope="row">trustCertificateKeyStorePassword</td><td>Password for the trusted root certificates KeyStore</td><td> </td><td>5.1.0</td></tr><tr><td scope="row">allowLoadLocalInfile</td><td>Should the driver allow use of 'LOAD DATA LOCAL INFILE...' (defaults to
'true').</td><td>true</td><td>3.0.3</td></tr><tr><td scope="row">allowUrlInLocalInfile</td><td>Should the driver allow URLs in 'LOAD DATA LOCAL INFILE' statements?</td><td>false</td><td>3.1.4</td></tr><tr><td scope="row">paranoid</td><td>Take measures to prevent exposure sensitive information in error
messages and clear data structures holding sensitive
data when possible? (defaults to 'false')</td><td>false</td><td>3.0.1</td></tr><tr><td scope="row">passwordCharacterEncoding</td><td>What character encoding is used for passwords? Leaving this set to the
default value (null), uses the platform character set,
which works for ISO8859_1 (i.e. "latin1") passwords. For
passwords in other character encodings, the encoding
will have to be specified with this property, as it's
not possible for the driver to auto-detect this.</td><td> </td><td>5.1.7</td></tr></tbody></table></div><p>
</p><p><b>Performance Extensions. </b>
</p><div class="informaltable"><table summary="This table lists Connector/J Performance Extensions
connection properties." border="1"><colgroup><col class="cj_propstbl_prop_name"><col class="cj_propstbl_prop_defn"><col class="cj_propstbl_default"><col class="cj_propstbl_since_version"></colgroup><tbody><tr><td scope="row"><span class="bold"><strong> Property Name </strong></span></td><td><span class="bold"><strong> Definition </strong></span></td><td><span class="bold"><strong> Default Value </strong></span></td><td><span class="bold"><strong> Since Version </strong></span></td></tr><tr><td scope="row">callableStmtCacheSize</td><td>If 'cacheCallableStmts' is enabled, how many callable statements should
be cached?</td><td>100</td><td>3.1.2</td></tr><tr><td scope="row">metadataCacheSize</td><td>The number of queries to cache ResultSetMetadata for if
cacheResultSetMetaData is set to 'true' (default 50)</td><td>50</td><td>3.1.1</td></tr><tr><td scope="row">useLocalSessionState</td><td>Should the driver refer to the internal values of autocommit and
transaction isolation that are set by
Connection.setAutoCommit() and
Connection.setTransactionIsolation() and transaction
state as maintained by the protocol, rather than
querying the database or blindly sending commands to the
database for commit() or rollback() method calls?</td><td>false</td><td>3.1.7</td></tr><tr><td scope="row">useLocalTransactionState</td><td>Should the driver use the in-transaction state provided by the MySQL
protocol to determine if a commit() or rollback() should
actually be sent to the database?</td><td>false</td><td>5.1.7</td></tr><tr><td scope="row">prepStmtCacheSize</td><td>If prepared statement caching is enabled, how many prepared statements
should be cached?</td><td>25</td><td>3.0.10</td></tr><tr><td scope="row">prepStmtCacheSqlLimit</td><td>If prepared statement caching is enabled, what's the largest SQL the
driver will cache the parsing for?</td><td>256</td><td>3.0.10</td></tr><tr><td scope="row">parseInfoCacheFactory</td><td>Name of a class implementing com.mysql.jdbc.CacheAdapterFactory, which
will be used to create caches for the parsed
representation of client-side prepared statements.</td><td>com.mysql.jdbc.PerConnectionLRUFactory</td><td>5.1.1</td></tr><tr><td scope="row">serverConfigCacheFactory</td><td>Name of a class implementing
com.mysql.jdbc.CacheAdapterFactory<String,
Map<String, String>>, which will be used to
create caches for MySQL server configuration values</td><td>com.mysql.jdbc.PerVmServerConfigCacheFactory</td><td>5.1.1</td></tr><tr><td scope="row">alwaysSendSetIsolation</td><td>Should the driver always communicate with the database when
Connection.setTransactionIsolation() is called? If set
to false, the driver will only communicate with the
database when the requested transaction isolation is
different than the whichever is newer, the last value
that was set via Connection.setTransactionIsolation(),
or the value that was read from the server when the
connection was established. Note that
useLocalSessionState=true will force the same behavior
as alwaysSendSetIsolation=false, regardless of how
alwaysSendSetIsolation is set.</td><td>true</td><td>3.1.7</td></tr><tr><td scope="row">maintainTimeStats</td><td>Should the driver maintain various internal timers to enable idle time
calculations as well as more verbose error messages when
the connection to the server fails? Setting this
property to false removes at least two calls to
System.getCurrentTimeMillis() per query.</td><td>true</td><td>3.1.9</td></tr><tr><td scope="row">useCursorFetch</td><td>If connected to MySQL > 5.0.2, and setFetchSize() > 0 on a
statement, should that statement use cursor-based
fetching to retrieve rows?</td><td>false</td><td>5.0.0</td></tr><tr><td scope="row">blobSendChunkSize</td><td>Chunk size to use when sending BLOB/CLOBs via ServerPreparedStatements.
Note that this value cannot exceed the value of
"maxAllowedPacket" and, if that is the case, then this
value will be corrected automatically.</td><td>1048576</td><td>3.1.9</td></tr><tr><td scope="row">cacheCallableStmts</td><td>Should the driver cache the parsing stage of CallableStatements</td><td>false</td><td>3.1.2</td></tr><tr><td scope="row">cachePrepStmts</td><td>Should the driver cache the parsing stage of PreparedStatements of
client-side prepared statements, the "check" for
suitability of server-side prepared and server-side
prepared statements themselves?</td><td>false</td><td>3.0.10</td></tr><tr><td scope="row">cacheResultSetMetadata</td><td>Should the driver cache ResultSetMetaData for Statements and
PreparedStatements? (Req. JDK-1.4+, true/false, default
'false')</td><td>false</td><td>3.1.1</td></tr><tr><td scope="row">cacheServerConfiguration</td><td>Should the driver cache the results of 'SHOW VARIABLES' and 'SHOW
COLLATION' on a per-URL basis?</td><td>false</td><td>3.1.5</td></tr><tr><td scope="row">defaultFetchSize</td><td>The driver will call setFetchSize(n) with this value on all
newly-created Statements</td><td>0</td><td>3.1.9</td></tr><tr><td scope="row">dontTrackOpenResources</td><td>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. Also the
automatic closing of the Statement and current ResultSet
in Statement.closeOnCompletion() and
Statement.getMoreResults
([Statement.CLOSE_CURRENT_RESULT |
Statement.CLOSE_ALL_RESULTS]), respectively, ceases to
happen. This property automatically sets
holdResultsOpenOverStatementClose=true.</td><td>false</td><td>3.1.7</td></tr><tr><td scope="row">dynamicCalendars</td><td>Should the driver retrieve the default calendar when required, or cache
it per connection/session?</td><td>false</td><td>3.1.5</td></tr><tr><td scope="row">elideSetAutoCommits</td><td>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)?</td><td>false</td><td>3.1.3</td></tr><tr><td scope="row">enableQueryTimeouts</td><td>When enabled, query timeouts set via Statement.setQueryTimeout() use a
shared java.util.Timer instance for scheduling. Even if
the timeout doesn't expire before the query is
processed, there will be memory used by the TimerTask
for the given timeout which won't be reclaimed until the
time the timeout would have expired if it hadn't been
cancelled by the driver. High-load environments might
want to consider disabling this functionality.</td><td>true</td><td>5.0.6</td></tr><tr><td scope="row">holdResultsOpenOverStatementClose</td><td>Should the driver close result sets on Statement.close() as required by
the JDBC specification?</td><td>false</td><td>3.1.7</td></tr><tr><td scope="row">largeRowSizeThreshold</td><td>What size result set row should the JDBC driver consider "large", and
thus use a more memory-efficient way of representing the
row internally?</td><td>2048</td><td>5.1.1</td></tr><tr><td scope="row">loadBalanceStrategy</td><td>If using a load-balanced connection to connect to SQL nodes in a MySQL
Cluster/NDB configuration (by using the URL prefix
"jdbc:mysql:loadbalance://"), which load balancing
algorithm should the driver use: (1) "random" - the
driver will pick a random host for each request. This
tends to work better than round-robin, as the randomness
will somewhat account for spreading loads where requests
vary in response time, while round-robin can sometimes
lead to overloaded nodes if there are variations in
response times across the workload. (2)
"bestResponseTime" - the driver will route the request
to the host that had the best response time for the
previous transaction.</td><td>random</td><td>5.0.6</td></tr><tr><td scope="row">locatorFetchBufferSize</td><td>If 'emulateLocators' is configured to 'true', what size buffer should be
used when fetching BLOB data for getBinaryInputStream?</td><td>1048576</td><td>3.2.1</td></tr><tr><td scope="row">rewriteBatchedStatements</td><td>Should the driver use multiqueries (irregardless of the setting of
"allowMultiQueries") as well as rewriting of prepared
statements for INSERT into multi-value inserts when
executeBatch() is called? Notice that this has the
potential for SQL injection if using plain
java.sql.Statements and your code doesn't sanitize input
correctly. Notice that for prepared statements,
server-side prepared statements can not currently take
advantage of this rewrite option, and that if you don't
specify stream lengths when using
PreparedStatement.set*Stream(), the driver won't be able
to determine the optimum number of parameters per batch
and you might receive an error from the driver that the
resultant packet is too large.
Statement.getGeneratedKeys() for these rewritten
statements only works when the entire batch includes
INSERT statements. Please be aware using
rewriteBatchedStatements=true with INSERT .. ON
DUPLICATE KEY UPDATE that for rewritten statement server
returns only one value as sum of all affected (or found)
rows in batch and it isn't possible to map it correctly
to initial statements; in this case driver returns the
total result as a result of each batch statement, i.e.
the only unambiguous result is 0.</td><td>false</td><td>3.1.13</td></tr><tr><td scope="row">useDirectRowUnpack</td><td>Use newer result set row unpacking code that skips a copy from network
buffers to a MySQL packet instance and instead reads
directly into the result set row data buffers.</td><td>true</td><td>5.1.1</td></tr><tr><td scope="row">useDynamicCharsetInfo</td><td>Should the driver use a per-connection cache of character set
information queried from the server when necessary, or
use a built-in static mapping that is more efficient,
but isn't aware of custom character sets or character
sets implemented after the release of the JDBC driver?</td><td>true</td><td>5.0.6</td></tr><tr><td scope="row">useFastDateParsing</td><td>Use internal String->Date/Time/Timestamp conversion routines to avoid
excessive object creation?</td><td>true</td><td>5.0.5</td></tr><tr><td scope="row">useFastIntParsing</td><td>Use internal String->Integer conversion routines to avoid excessive
object creation?</td><td>true</td><td>3.1.4</td></tr><tr><td scope="row">useJvmCharsetConverters</td><td>Always use the character encoding routines built into the JVM, rather
than using lookup tables for single-byte character sets?</td><td>false</td><td>5.0.1</td></tr><tr><td scope="row">useReadAheadInput</td><td>Use newer, optimized non-blocking, buffered input stream when reading
from the server?</td><td>true</td><td>3.1.5</td></tr></tbody></table></div><p>
</p><p><b>Debugging/Profiling. </b>
</p><div class="informaltable"><table summary="This table lists Connector/J Debugging/Profiling
connection properties." border="1"><colgroup><col class="cj_propstbl_prop_name"><col class="cj_propstbl_prop_defn"><col class="cj_propstbl_default"><col class="cj_propstbl_since_version"></colgroup><tbody><tr><td scope="row"><span class="bold"><strong> Property Name </strong></span></td><td><span class="bold"><strong> Definition </strong></span></td><td><span class="bold"><strong> Default Value </strong></span></td><td><span class="bold"><strong> Since Version </strong></span></td></tr><tr><td scope="row">logger</td><td>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)</td><td>com.mysql.jdbc.log.StandardLogger</td><td>3.1.1</td></tr><tr><td scope="row">gatherPerfMetrics</td><td>Should the driver gather performance metrics, and report them via the
configured logger every 'reportMetricsIntervalMillis'
milliseconds?</td><td>false</td><td>3.1.2</td></tr><tr><td scope="row">profileSQL</td><td>Trace queries and their execution/fetch times to the configured logger
(true/false) defaults to 'false'</td><td>false</td><td>3.1.0</td></tr><tr><td scope="row">profileSql</td><td>Deprecated, use 'profileSQL' instead. Trace queries and their
execution/fetch times on STDERR (true/false) defaults to
'false'</td><td> </td><td>2.0.14</td></tr><tr><td scope="row">reportMetricsIntervalMillis</td><td>If 'gatherPerfMetrics' is enabled, how often should they be logged (in
ms)?</td><td>30000</td><td>3.1.2</td></tr><tr><td scope="row">maxQuerySizeToLog</td><td>Controls the maximum length/size of a query that will get logged when
profiling or tracing</td><td>2048</td><td>3.1.3</td></tr><tr><td scope="row">packetDebugBufferSize</td><td>The maximum number of packets to retain when 'enablePacketDebug' is true</td><td>20</td><td>3.1.3</td></tr><tr><td scope="row">slowQueryThresholdMillis</td><td>If 'logSlowQueries' is enabled, how long should a query (in ms) before
it is logged as 'slow'?</td><td>2000</td><td>3.1.2</td></tr><tr><td scope="row">slowQueryThresholdNanos</td><td>If 'useNanosForElapsedTime' is set to true, and this property is set to
a non-zero value, the driver will use this threshold (in
nanosecond units) to determine if a query was slow.</td><td>0</td><td>5.0.7</td></tr><tr><td scope="row">useUsageAdvisor</td><td>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')?</td><td>false</td><td>3.1.1</td></tr><tr><td scope="row">autoGenerateTestcaseScript</td><td>Should the driver dump the SQL it is executing, including server-side
prepared statements to STDERR?</td><td>false</td><td>3.1.9</td></tr><tr><td scope="row">autoSlowLog</td><td>Instead of using slowQueryThreshold* to determine if a query is slow
enough to be logged, maintain statistics that allow the
driver to determine queries that are outside the 99th
percentile?</td><td>true</td><td>5.1.4</td></tr><tr><td scope="row">clientInfoProvider</td><td>The name of a class that implements the
com.mysql.jdbc.JDBC4ClientInfoProvider interface in
order to support JDBC-4.0's
Connection.get/setClientInfo() methods</td><td>com.mysql.jdbc.JDBC4CommentClientInfoProvider</td><td>5.1.0</td></tr><tr><td scope="row">dumpMetadataOnColumnNotFound</td><td>Should the driver dump the field-level metadata of a result set into the
exception message when ResultSet.findColumn() fails?</td><td>false</td><td>3.1.13</td></tr><tr><td scope="row">dumpQueriesOnException</td><td>Should the driver dump the contents of the query sent to the server in
the message for SQLExceptions?</td><td>false</td><td>3.1.3</td></tr><tr><td scope="row">enablePacketDebug</td><td>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</td><td>false</td><td>3.1.3</td></tr><tr><td scope="row">explainSlowQueries</td><td>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?</td><td>false</td><td>3.1.2</td></tr><tr><td scope="row">includeInnodbStatusInDeadlockExceptions</td><td>Include the output of "SHOW ENGINE INNODB STATUS" in exception messages
when deadlock exceptions are detected?</td><td>false</td><td>5.0.7</td></tr><tr><td scope="row">includeThreadDumpInDeadlockExceptions</td><td>Include a current Java thread dump in exception messages when deadlock
exceptions are detected?</td><td>false</td><td>5.1.15</td></tr><tr><td scope="row">includeThreadNamesAsStatementComment</td><td>Include the name of the current thread as a comment visible in "SHOW
PROCESSLIST", or in Innodb deadlock dumps, useful in
correlation with
"includeInnodbStatusInDeadlockExceptions=true" and
"includeThreadDumpInDeadlockExceptions=true".</td><td>false</td><td>5.1.15</td></tr><tr><td scope="row">logSlowQueries</td><td>Should queries that take longer than 'slowQueryThresholdMillis' be
logged?</td><td>false</td><td>3.1.2</td></tr><tr><td scope="row">logXaCommands</td><td>Should the driver log XA commands sent by MysqlXaConnection to the
server, at the DEBUG level of logging?</td><td>false</td><td>5.0.5</td></tr><tr><td scope="row">profilerEventHandler</td><td>Name of a class that implements the interface
com.mysql.jdbc.profiler.ProfilerEventHandler that will
be used to handle profiling/tracing events.</td><td>com.mysql.jdbc.profiler.LoggingProfilerEventHandler</td><td>5.1.6</td></tr><tr><td scope="row">resultSetSizeThreshold</td><td>If the usage advisor is enabled, how many rows should a result set
contain before the driver warns that it is suspiciously
large?</td><td>100</td><td>5.0.5</td></tr><tr><td scope="row">traceProtocol</td><td>Should trace-level network protocol be logged?</td><td>false</td><td>3.1.2</td></tr><tr><td scope="row">useNanosForElapsedTime</td><td>For profiling/debugging functionality that measures elapsed time, should
the driver try to use nanoseconds resolution if
available (JDK >= 1.5)?</td><td>false</td><td>5.0.7</td></tr></tbody></table></div><p>
</p><p><b>Miscellaneous. </b>
</p><div class="informaltable"><table summary="This table lists Connector/J Miscellaneous connection
properties." border="1"><colgroup><col class="cj_propstbl_prop_name"><col class="cj_propstbl_prop_defn"><col class="cj_propstbl_default"><col class="cj_propstbl_since_version"></colgroup><tbody><tr><td scope="row"><span class="bold"><strong> Property Name </strong></span></td><td><span class="bold"><strong> Definition </strong></span></td><td><span class="bold"><strong> Default Value </strong></span></td><td><span class="bold"><strong> Since Version </strong></span></td></tr><tr><td scope="row">useUnicode</td><td>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'</td><td>true</td><td>1.1g</td></tr><tr><td scope="row">characterEncoding</td><td>If 'useUnicode' is set to true, what character encoding should the
driver use when dealing with strings? (defaults is to
'autodetect')</td><td> </td><td>1.1g</td></tr><tr><td scope="row">characterSetResults</td><td>Character set to tell the server to return results as.</td><td> </td><td>3.0.13</td></tr><tr><td scope="row">connectionAttributes</td><td>A comma-delimited list of user-defined key:value pairs (in addition to
standard MySQL-defined key:value pairs) to be passed to
MySQL Server for display as connection attributes in the
PERFORMANCE_SCHEMA.SESSION_CONNECT_ATTRS table. Example
usage: connectionAttributes=key1:value1,key2:value2 This
functionality is available for use with MySQL Server
version 5.6 or later only. Earlier versions of MySQL
Server do not support connection attributes, causing
this configuration option will be ignored. Setting
connectionAttributes=none will cause connection
attribute processing to be bypassed, for situations
where Connection creation/initialization speed is
critical.</td><td> </td><td>5.1.25</td></tr><tr><td scope="row">connectionCollation</td><td>If set, tells the server to use this collation via 'set
collation_connection'</td><td> </td><td>3.0.13</td></tr><tr><td scope="row">useBlobToStoreUTF8OutsideBMP</td><td>Tells the driver to treat [MEDIUM/LONG]BLOB columns as [LONG]VARCHAR
columns holding text encoded in UTF-8 that has
characters outside the BMP (4-byte encodings), which
MySQL server can't handle natively.</td><td>false</td><td>5.1.3</td></tr><tr><td scope="row">utf8OutsideBmpExcludedColumnNamePattern</td><td>When "useBlobToStoreUTF8OutsideBMP" is set to "true", column names
matching the given regex will still be treated as BLOBs
unless they match the regex specified for
"utf8OutsideBmpIncludedColumnNamePattern". The regex
must follow the patterns used for the java.util.regex
package.</td><td> </td><td>5.1.3</td></tr><tr><td scope="row">utf8OutsideBmpIncludedColumnNamePattern</td><td>Used to specify exclusion rules to
"utf8OutsideBmpExcludedColumnNamePattern". The regex
must follow the patterns used for the java.util.regex
package.</td><td> </td><td>5.1.3</td></tr><tr><td scope="row">loadBalanceEnableJMX</td><td>Enables JMX-based management of load-balanced connection groups,
including live addition/removal of hosts from
load-balancing pool.</td><td>false</td><td>5.1.13</td></tr><tr><td scope="row">sessionVariables</td><td>A comma-separated list of name/value pairs to be sent as SET SESSION ...
to the server when the driver connects.</td><td> </td><td>3.1.8</td></tr><tr><td scope="row">useColumnNamesInFindColumn</td><td>Prior to JDBC-4.0, the JDBC specification had a bug related to what
could be given as a "column name" to ResultSet methods
like findColumn(), or getters that took a String
property. JDBC-4.0 clarified "column name" to mean the
label, as given in an "AS" clause and returned by
ResultSetMetaData.getColumnLabel(), and if no AS clause,
the column name. Setting this property to "true" will
give behavior that is congruent to JDBC-3.0 and earlier
versions of the JDBC specification, but which because of
the specification bug could give unexpected results.
This property is preferred over
"useOldAliasMetadataBehavior" unless you need the
specific behavior that it provides with respect to
ResultSetMetadata.</td><td>false</td><td>5.1.7</td></tr><tr><td scope="row">allowNanAndInf</td><td>Should the driver allow NaN or +/- INF values in
PreparedStatement.setDouble()?</td><td>false</td><td>3.1.5</td></tr><tr><td scope="row">autoClosePStmtStreams</td><td>Should the driver automatically call .close() on streams/readers passed
as arguments via set*() methods?</td><td>false</td><td>3.1.12</td></tr><tr><td scope="row">autoDeserialize</td><td>Should the driver automatically detect and de-serialize objects stored
in BLOB fields?</td><td>false</td><td>3.1.5</td></tr><tr><td scope="row">blobsAreStrings</td><td>Should the driver always treat BLOBs as Strings - specifically to work
around dubious metadata returned by the server for GROUP
BY clauses?</td><td>false</td><td>5.0.8</td></tr><tr><td scope="row">capitalizeTypeNames</td><td>Capitalize type names in DatabaseMetaData? (usually only useful when
using WebObjects, true/false, defaults to 'false')</td><td>true</td><td>2.0.7</td></tr><tr><td scope="row">clobCharacterEncoding</td><td>The character encoding to use for sending and retrieving TEXT,
MEDIUMTEXT and LONGTEXT values instead of the configured
connection characterEncoding</td><td> </td><td>5.0.0</td></tr><tr><td scope="row">clobberStreamingResults</td><td>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.</td><td>false</td><td>3.0.9</td></tr><tr><td scope="row">compensateOnDuplicateKeyUpdateCounts</td><td>Should the driver compensate for the update counts of "ON DUPLICATE KEY"
INSERT statements (2 = 1, 0 = 1) when using prepared
statements?</td><td>false</td><td>5.1.7</td></tr><tr><td scope="row">continueBatchOnError</td><td>Should the driver continue processing batch commands if one statement
fails. The JDBC spec allows either way (defaults to
'true').</td><td>true</td><td>3.0.3</td></tr><tr><td scope="row">createDatabaseIfNotExist</td><td>Creates the database given in the URL if it doesn't yet exist. Assumes
the configured user has permissions to create databases.</td><td>false</td><td>3.1.9</td></tr><tr><td scope="row">detectCustomCollations</td><td>Should the driver detect custom charsets/collations installed on server
(true/false, defaults to 'false'). If this option set to
'true' driver gets actual charsets/collations from
server each time connection establishes. This could slow
down connection initialization significantly.</td><td>false</td><td>5.1.29</td></tr><tr><td scope="row">emptyStringsConvertToZero</td><td>Should the driver allow conversions from empty string fields to numeric
values of '0'?</td><td>true</td><td>3.1.8</td></tr><tr><td scope="row">emulateLocators</td><td>Should the driver emulate java.sql.Blobs with locators? With this
feature enabled, the driver will delay loading the
actual Blob data until the one of the retrieval methods
(getInputStream(), getBytes(), and so forth) on the blob
data stream has been accessed. For this to work, you
must use a column alias with the value of the column to
the actual name of the Blob. The feature also has the
following restrictions: The SELECT that created the
result set must reference only one table, the table must
have a primary key; the SELECT must alias the original
blob column name, specified as a string, to an alternate
name; the SELECT must cover all columns that make up the
primary key.</td><td>false</td><td>3.1.0</td></tr><tr><td scope="row">emulateUnsupportedPstmts</td><td>Should the driver detect prepared statements that are not supported by
the server, and replace them with client-side emulated
versions?</td><td>true</td><td>3.1.7</td></tr><tr><td scope="row">exceptionInterceptors</td><td>Comma-delimited list of classes that implement
com.mysql.jdbc.ExceptionInterceptor. These classes will
be instantiated one per Connection instance, and all
SQLExceptions thrown by the driver will be allowed to be
intercepted by these interceptors, in a chained fashion,
with the first class listed as the head of the chain.</td><td> </td><td>5.1.8</td></tr><tr><td scope="row">functionsNeverReturnBlobs</td><td>Should the driver always treat data from functions returning BLOBs as
Strings - specifically to work around dubious metadata
returned by the server for GROUP BY clauses?</td><td>false</td><td>5.0.8</td></tr><tr><td scope="row">generateSimpleParameterMetadata</td><td>Should the driver generate simplified parameter metadata for
PreparedStatements when no metadata is available either
because the server couldn't support preparing the
statement, or server-side prepared statements are
disabled?</td><td>false</td><td>5.0.5</td></tr><tr><td scope="row">getProceduresReturnsFunctions</td><td>Pre-JDBC4 DatabaseMetaData API has only the getProcedures() and
getProcedureColumns() methods, so they return metadata
info for both stored procedures and functions. JDBC4 was
extended with the getFunctions() and
getFunctionColumns() methods and the expected behaviours
of previous methods are not well defined. For JDBC4 and
higher, default 'true' value of the option means that
calls of DatabaseMetaData.getProcedures() and
DatabaseMetaData.getProcedureColumns() return metadata
for both procedures and functions as before, keeping
backward compatibility. Setting this property to 'false'
decouples Connector/J from its pre-JDBC4 behaviours for
DatabaseMetaData.getProcedures() and
DatabaseMetaData.getProcedureColumns(), forcing them to
return metadata for procedures only.</td><td>true</td><td>5.1.26</td></tr><tr><td scope="row">ignoreNonTxTables</td><td>Ignore non-transactional table warning for rollback? (defaults to
'false').</td><td>false</td><td>3.0.9</td></tr><tr><td scope="row">jdbcCompliantTruncation</td><td>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)? This property has no effect if the
server sql-mode includes STRICT_TRANS_TABLES.</td><td>true</td><td>3.1.2</td></tr><tr><td scope="row">loadBalanceAutoCommitStatementRegex</td><td>When load-balancing is enabled for auto-commit statements (via
loadBalanceAutoCommitStatementThreshold), the statement
counter will only increment when the SQL matches the
regular expression. By default, every statement issued
matches.</td><td> </td><td>5.1.15</td></tr><tr><td scope="row">loadBalanceAutoCommitStatementThreshold</td><td>When auto-commit is enabled, the number of statements which should be
executed before triggering load-balancing to rebalance.
Default value of 0 causes load-balanced connections to
only rebalance when exceptions are encountered, or
auto-commit is disabled and transactions are explicitly
committed or rolled back.</td><td>0</td><td>5.1.15</td></tr><tr><td scope="row">loadBalanceBlacklistTimeout</td><td>Time in milliseconds between checks of servers which are unavailable, by
controlling how long a server lives in the global
blacklist.</td><td>0</td><td>5.1.0</td></tr><tr><td scope="row">loadBalanceConnectionGroup</td><td>Logical group of load-balanced connections within a classloader, used to
manage different groups independently. If not specified,
live management of load-balanced connections is
disabled.</td><td> </td><td>5.1.13</td></tr><tr><td scope="row">loadBalanceExceptionChecker</td><td>Fully-qualified class name of custom exception checker. The class must
implement com.mysql.jdbc.LoadBalanceExceptionChecker
interface, and is used to inspect SQLExceptions and
determine whether they should trigger fail-over to
another host in a load-balanced deployment.</td><td>com.mysql.jdbc.StandardLoadBalanceExceptionChecker</td><td>5.1.13</td></tr><tr><td scope="row">loadBalancePingTimeout</td><td>Time in milliseconds to wait for ping response from each of
load-balanced physical connections when using
load-balanced Connection.</td><td>0</td><td>5.1.13</td></tr><tr><td scope="row">loadBalanceSQLExceptionSubclassFailover</td><td>Comma-delimited list of classes/interfaces used by default load-balanced
exception checker to determine whether a given
SQLException should trigger failover. The comparison is
done using Class.isInstance(SQLException) using the
thrown SQLException.</td><td> </td><td>5.1.13</td></tr><tr><td scope="row">loadBalanceSQLStateFailover</td><td>Comma-delimited list of SQLState codes used by default load-balanced
exception checker to determine whether a given
SQLException should trigger failover. The SQLState of a
given SQLException is evaluated to determine whether it
begins with any value in the comma-delimited list.</td><td> </td><td>5.1.13</td></tr><tr><td scope="row">loadBalanceValidateConnectionOnSwapServer</td><td>Should the load-balanced Connection explicitly check whether the
connection is live when swapping to a new physical
connection at commit/rollback?</td><td>false</td><td>5.1.13</td></tr><tr><td scope="row">maxRows</td><td>The maximum number of rows to return (0, the default means return all
rows).</td><td>-1</td><td>all versions</td></tr><tr><td scope="row">netTimeoutForStreamingResults</td><td>What value should the driver automatically set the server setting
'net_write_timeout' to when the streaming result sets
feature is in use? (value has unit of seconds, the value
'0' means the driver will not try and adjust this value)</td><td>600</td><td>5.1.0</td></tr><tr><td scope="row">noAccessToProcedureBodies</td><td>When determining procedure parameter types for CallableStatements, and
the connected user can't access procedure bodies through
"SHOW CREATE PROCEDURE" or select on mysql.proc should
the driver instead create basic metadata (all parameters
reported as IN VARCHARs, but allowing
registerOutParameter() to be called on them anyway)
instead of throwing an exception?</td><td>false</td><td>5.0.3</td></tr><tr><td scope="row">noDatetimeStringSync</td><td>Don't ensure that
ResultSet.getDatetimeType().toString().equals(ResultSet.getString())</td><td>false</td><td>3.1.7</td></tr><tr><td scope="row">noTimezoneConversionForTimeType</td><td>Don't convert TIME values using the server timezone if
'useTimezone'='true'</td><td>false</td><td>5.0.0</td></tr><tr><td scope="row">nullCatalogMeansCurrent</td><td>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)</td><td>true</td><td>3.1.8</td></tr><tr><td scope="row">nullNamePatternMatchesAll</td><td>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)</td><td>true</td><td>3.1.8</td></tr><tr><td scope="row">overrideSupportsIntegrityEnhancementFacility</td><td>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)?</td><td>false</td><td>3.1.12</td></tr><tr><td scope="row">padCharsWithSpace</td><td>If a result set column has the CHAR type and the value does not fill the
amount of characters specified in the DDL for the
column, should the driver pad the remaining characters
with space (for ANSI compliance)?</td><td>false</td><td>5.0.6</td></tr><tr><td scope="row">pedantic</td><td>Follow the JDBC spec to the letter.</td><td>false</td><td>3.0.0</td></tr><tr><td scope="row">pinGlobalTxToPhysicalConnection</td><td>When using XAConnections, should the driver ensure that operations on a
given XID are always routed to the same physical
connection? This allows the XAConnection to support "XA
START ... JOIN" after "XA END" has been called</td><td>false</td><td>5.0.1</td></tr><tr><td scope="row">populateInsertRowWithDefaultValues</td><td>When using ResultSets that are CONCUR_UPDATABLE, should the driver
pre-populate the "insert" row with default values from
the DDL for the table used in the query so those values
are immediately available for ResultSet accessors? This
functionality requires a call to the database for
metadata each time a result set of this type is created.
If disabled (the default), the default values will be
populated by the an internal call to refreshRow() which
pulls back default values and/or values changed by
triggers.</td><td>false</td><td>5.0.5</td></tr><tr><td scope="row">processEscapeCodesForPrepStmts</td><td>Should the driver process escape codes in queries that are prepared?</td><td>true</td><td>3.1.12</td></tr><tr><td scope="row">queryTimeoutKillsConnection</td><td>If the timeout given in Statement.setQueryTimeout() expires, should the
driver forcibly abort the Connection instead of
attempting to abort the query?</td><td>false</td><td>5.1.9</td></tr><tr><td scope="row">relaxAutoCommit</td><td>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')?</td><td>false</td><td>2.0.13</td></tr><tr><td scope="row">retainStatementAfterResultSetClose</td><td>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.</td><td>false</td><td>3.1.11</td></tr><tr><td scope="row">rollbackOnPooledClose</td><td>Should the driver issue a rollback() when the logical connection in a
pool is closed?</td><td>true</td><td>3.0.15</td></tr><tr><td scope="row">runningCTS13</td><td>Enables workarounds for bugs in Sun's JDBC compliance testsuite version
1.3</td><td>false</td><td>3.1.7</td></tr><tr><td scope="row">serverTimezone</td><td>Override detection/mapping of timezone. Used when timezone from server
doesn't map to Java timezone</td><td> </td><td>3.0.2</td></tr><tr><td scope="row">statementInterceptors</td><td>A comma-delimited list of classes that implement
"com.mysql.jdbc.StatementInterceptor" that should be
placed "in between" query execution to influence the
results. StatementInterceptors are "chainable", the
results returned by the "current" interceptor will be
passed on to the next in in the chain, from
left-to-right order, as specified in this property.</td><td> </td><td>5.1.1</td></tr><tr><td scope="row">strictFloatingPoint</td><td>Used only in older versions of compliance test</td><td>false</td><td>3.0.0</td></tr><tr><td scope="row">strictUpdates</td><td>Should the driver do strict checking (all primary keys selected) of
updatable result sets (true, false, defaults to 'true')?</td><td>true</td><td>3.0.4</td></tr><tr><td scope="row">tinyInt1isBit</td><td>Should the driver treat the datatype TINYINT(1) as the BIT type (because
the server silently converts BIT -> TINYINT(1) when
creating tables)?</td><td>true</td><td>3.0.16</td></tr><tr><td scope="row">transformedBitIsBoolean</td><td>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?</td><td>false</td><td>3.1.9</td></tr><tr><td scope="row">treatUtilDateAsTimestamp</td><td>Should the driver treat java.util.Date as a TIMESTAMP for the purposes
of PreparedStatement.setObject()?</td><td>true</td><td>5.0.5</td></tr><tr><td scope="row">ultraDevHack</td><td>Create PreparedStatements for prepareCall() when required, because
UltraDev is broken and issues a prepareCall() for _all_
statements? (true/false, defaults to 'false')</td><td>false</td><td>2.0.3</td></tr><tr><td scope="row">useAffectedRows</td><td>Don't set the CLIENT_FOUND_ROWS flag when connecting to the server (not
JDBC-compliant, will break most applications that rely
on "found" rows vs. "affected rows" for DML statements),
but does cause "correct" update counts from "INSERT ...
ON DUPLICATE KEY UPDATE" statements to be returned by
the server.</td><td>false</td><td>5.1.7</td></tr><tr><td scope="row">useGmtMillisForDatetimes</td><td>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.</td><td>false</td><td>3.1.12</td></tr><tr><td scope="row">useHostsInPrivileges</td><td>Add '@hostname' to users in DatabaseMetaData.getColumn/TablePrivileges()
(true/false), defaults to 'true'.</td><td>true</td><td>3.0.2</td></tr><tr><td scope="row">useInformationSchema</td><td>When connected to MySQL-5.0.7 or newer, should the driver use the
INFORMATION_SCHEMA to derive information used by
DatabaseMetaData?</td><td>false</td><td>5.0.0</td></tr><tr><td scope="row">useJDBCCompliantTimezoneShift</td><td>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.)</td><td>false</td><td>5.0.0</td></tr><tr><td scope="row">useLegacyDatetimeCode</td><td>Use code for DATE/TIME/DATETIME/TIMESTAMP handling in result sets and
statements that consistently handles timezone
conversions from client to server and back again, or use
the legacy code for these datatypes that has been in the
driver for backwards-compatibility?</td><td>true</td><td>5.1.6</td></tr><tr><td scope="row">useOldAliasMetadataBehavior</td><td>Should the driver use the legacy behavior for "AS" clauses on columns
and tables, and only return aliases (if any) for
ResultSetMetaData.getColumnName() or
ResultSetMetaData.getTableName() rather than the
original column/table name? In 5.0.x, the default value
was true.</td><td>false</td><td>5.0.4</td></tr><tr><td scope="row">useOldUTF8Behavior</td><td>Use the UTF-8 behavior the driver did when communicating with 4.0 and
older servers</td><td>false</td><td>3.1.6</td></tr><tr><td scope="row">useOnlyServerErrorMessages</td><td>Don't prepend 'standard' SQLState error messages to error messages
returned by the server.</td><td>true</td><td>3.0.15</td></tr><tr><td scope="row">useSSPSCompatibleTimezoneShift</td><td>If migrating from an environment that was using server-side prepared
statements, and the configuration property
"useJDBCCompliantTimeZoneShift" set to "true", use
compatible behavior when not using server-side prepared
statements when sending TIMESTAMP values to the MySQL
server.</td><td>false</td><td>5.0.5</td></tr><tr><td scope="row">useServerPrepStmts</td><td>Use server-side prepared statements if the server supports them?</td><td>false</td><td>3.1.0</td></tr><tr><td scope="row">useSqlStateCodes</td><td>Use SQL Standard state codes instead of 'legacy' X/Open/SQL state codes
(true/false), default is 'true'</td><td>true</td><td>3.1.3</td></tr><tr><td scope="row">useStreamLengthsInPrepStmts</td><td>Honor stream length parameter in
PreparedStatement/ResultSet.setXXXStream() method calls
(true/false, defaults to 'true')?</td><td>true</td><td>3.0.2</td></tr><tr><td scope="row">useTimezone</td><td>Convert time/date types between client and server timezones (true/false,
defaults to 'false')?</td><td>false</td><td>3.0.2</td></tr><tr><td scope="row">useUnbufferedInput</td><td>Don't use BufferedInputStream for reading data from the server</td><td>true</td><td>3.0.11</td></tr><tr><td scope="row">yearIsDateType</td><td>Should the JDBC driver treat the MySQL type "YEAR" as a java.sql.Date,
or as a SHORT?</td><td>true</td><td>3.1.9</td></tr><tr><td scope="row">zeroDateTimeBehavior</td><td>What should happen when the driver encounters DATETIME values that are
composed entirely of zeros (used by MySQL to represent
invalid dates)? Valid values are "exception", "round"
and "convertToNull".</td><td>exception</td><td>3.1.4</td></tr></tbody></table></div><p>
</p><p>
Connector/J also supports access to MySQL using named pipes on
Windows NT, Windows 2000, or Windows XP using the
<code class="literal">NamedPipeSocketFactory</code> as a plugin-socket
factory using the <code class="literal">socketFactory</code> property. If
you do not use a <code class="literal">namedPipePath</code> property, the
default of <code class="literal">'\\.\pipe\MySQL'</code> is used. If you
use the <code class="literal">NamedPipeSocketFactory</code>, the host name
and port number values in the JDBC url are ignored. To enable
this feature, use:
</p><pre class="programlisting">
socketFactory=com.mysql.jdbc.NamedPipeSocketFactory
</pre><p>
Named pipes only work when connecting to a MySQL server on the
same physical machine where the JDBC driver is running. In
simple performance tests, named pipe access is between 30%-50%
faster than the standard TCP/IP access. However, this varies per
system, and named pipes are slower than TCP/IP in many Windows
configurations.
</p><p>
To create your own socket factories, follow the example code in
<code class="classname">com.mysql.jdbc.NamedPipeSocketFactory</code>, or
<code class="classname">com.mysql.jdbc.StandardSocketFactory</code>.
</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-j-useconfigs"></a>5.1.1. Properties Files for the <code class="literal">useConfigs</code> Option</h3></div></div></div><a class="indexterm" name="idm47020251375536"></a><p>
The <code class="literal">useConfigs</code> connection option is
convenient shorthand for specifying combinations of options
for particular scenarios. The argument values you can use with
this option correspond to the names of
<code class="filename">.properties</code> files within the Connector/J
<code class="filename">mysql-connector-java-<em class="replaceable"><code>version</code></em>-bin.jar</code>
JAR file. For example, the Connector/J 5.1.9 driver includes
the following configuration properties files:
</p><pre class="programlisting">
$ unzip mysql-connector-java-5.1.19-bin.jar '*/configs/*'
Archive: mysql-connector-java-5.1.19-bin.jar
creating: com/mysql/jdbc/configs/
inflating: com/mysql/jdbc/configs/3-0-Compat.properties
inflating: com/mysql/jdbc/configs/5-0-Compat.properties
inflating: com/mysql/jdbc/configs/clusterBase.properties
inflating: com/mysql/jdbc/configs/coldFusion.properties
inflating: com/mysql/jdbc/configs/fullDebug.properties
inflating: com/mysql/jdbc/configs/maxPerformance.properties
inflating: com/mysql/jdbc/configs/solarisMaxPerformance.properties
</pre><p>
To specify one of these combinations of options, specify
<code class="literal">useConfigs=3-0-Compat</code>,
<code class="literal">useConfigs=maxPerformance</code>, and so on. The
following sections show the options that are part of each
<code class="literal">useConfigs</code> setting. For the details of why
each one is included, see the comments in the
<code class="filename">.properties</code> files.
</p><h4><a name="idm47020251368720"></a>
3-0-Compat
</h4><pre class="programlisting">
emptyStringsConvertToZero=true
jdbcCompliantTruncation=false
noDatetimeStringSync=true
nullCatalogMeansCurrent=true
nullNamePatternMatchesAll=true
transformedBitIsBoolean=false
dontTrackOpenResources=true
zeroDateTimeBehavior=convertToNull
useServerPrepStmts=false
autoClosePStmtStreams=true
processEscapeCodesForPrepStmts=false
useFastDateParsing=false
populateInsertRowWithDefaultValues=false
useDirectRowUnpack=false
</pre><h4><a name="idm47020251367472"></a>
5-0-Compat
</h4><pre class="programlisting">
useDirectRowUnpack=false
</pre><h4><a name="idm47020251366608"></a>
clusterBase
</h4><pre class="programlisting">
autoReconnect=true
failOverReadOnly=false
roundRobinLoadBalance=true
</pre><h4><a name="idm47020251365712"></a>
coldFusion
</h4><pre class="programlisting">
useDynamicCharsetInfo=false
alwaysSendSetIsolation=false
useLocalSessionState=true
autoReconnect=true
</pre><h4><a name="idm47020251364784"></a>
fullDebug
</h4><pre class="programlisting">
profileSQL=true
gatherPerMetrics=true
useUsageAdvisor=true
logSlowQueries=true
explainSlowQueries=true
</pre><h4><a name="idm47020251363840"></a>
maxPerformance
</h4><pre class="programlisting">
cachePrepStmts=true
cacheCallableStmts=true
cacheServerConfiguration=true
useLocalSessionState=true
elideSetAutoCommits=true
alwaysSendSetIsolation=false
enableQueryTimeouts=false
</pre><h4><a name="idm47020251362832"></a>
solarisMaxPerformance
</h4><pre class="programlisting">
useUnbufferedInput=false
useReadAheadInput=false
maintainTimeStats=false
</pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-reference-implementation-notes"></a>5.2. JDBC API Implementation Notes</h2></div></div></div><a class="indexterm" name="idm47020251360656"></a><p>
MySQL Connector/J passes all of the tests in the publicly
available version of Oracle's JDBC compliance test suite. This
section gives details on an interface-by-interface level about
implementation decisions that might affect how you code
applications with MySQL Connector/J. The JDBC specification is
vague about how certain functionality should be implemented, or
the specification enables leeway in implementation.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<span class="bold"><strong>BLOB</strong></span>
</p><p>
Starting with Connector/J version 3.1.0, you can emulate
BLOBs with locators by adding the property
<code class="literal">emulateLocators=true</code> to your JDBC URL.
Using this method, the driver will delay loading the actual
BLOB data until you retrieve the other data and then use
retrieval methods (<code class="function">getInputStream()</code>,
<code class="function">getBytes()</code>, and so forth) on the BLOB
data stream.
</p><p>
You must use a column alias with the value of the column to
the actual name of the BLOB, for example:
</p><pre class="programlisting">
SELECT id, 'data' as blob_data from blobtable
</pre><p>
You must also follow these rules:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
The <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/select.html" target="_top"><code class="literal">SELECT</code></a> must reference
only one table. The table must have a
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/glossary.html#glos_primary_key" target="_top">primary key</a>.
</p></li><li class="listitem"><p>
The <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/select.html" target="_top"><code class="literal">SELECT</code></a> must alias the
original BLOB column name, specified as a string, to an
alternate name.
</p></li><li class="listitem"><p>
The <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/select.html" target="_top"><code class="literal">SELECT</code></a> must cover all
columns that make up the primary key.
</p></li></ul></div><p>
The BLOB implementation does not allow in-place modification
(they are copies, as reported by the
<code class="literal">DatabaseMetaData.locatorsUpdateCopies()</code>
method). Because of this, use the corresponding
<code class="literal">PreparedStatement.setBlob()</code> or
<code class="literal">ResultSet.updateBlob()</code> (in the case of
updatable result sets) methods to save changes back to the
database.
</p></li><li class="listitem"><p>
<span class="bold"><strong>CallableStatement</strong></span>
</p><p>
Starting with Connector/J 3.1.1, stored procedures are
supported when connecting to MySQL version 5.0 or newer
using the <code class="classname">CallableStatement</code>
interface. Currently, the
<code class="function">getParameterMetaData()</code> method of
<code class="classname">CallableStatement</code> is not supported.
</p></li><li class="listitem"><p>
<span class="bold"><strong>CLOB</strong></span>
</p><p>
The CLOB implementation does not allow in-place modification
(they are copies, as reported by the
<code class="literal">DatabaseMetaData.locatorsUpdateCopies()</code>
method). Because of this, use the
<code class="literal">PreparedStatement.setClob()</code> method to
save changes back to the database. The JDBC API does not
have a <code class="literal">ResultSet.updateClob()</code> method.
</p></li><li class="listitem"><p>
<span class="bold"><strong>Connection</strong></span>
</p><p>
Unlike the pre-Connector/J JDBC driver
(<code class="literal">MM.MySQL</code>), the
<code class="function">isClosed()</code> method does not ping the
server to determine if it is available. In accordance with
the JDBC specification, it only returns true if
<code class="function">closed()</code> has been called on the
connection. If you need to determine if the connection is
still valid, issue a simple query, such as <code class="literal">SELECT
1</code>. The driver will throw an exception if the
connection is no longer valid.
</p></li><li class="listitem"><p>
<span class="bold"><strong>DatabaseMetaData</strong></span>
</p><p>
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/glossary.html#glos_foreign_key" target="_top">Foreign key</a>
information
(<code class="function">getImportedKeys()</code>/<code class="function">getExportedKeys()</code>
and <code class="function">getCrossReference()</code>) is only
available from <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/innodb-storage-engine.html" target="_top"><code class="literal">InnoDB</code></a> tables.
The driver uses <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/show-create-table.html" target="_top"><code class="literal">SHOW CREATE
TABLE</code></a> to retrieve this information, so if any
other storage engines add support for foreign keys, the
driver would transparently support them as well.
</p></li><li class="listitem"><p>
<span class="bold"><strong>PreparedStatement</strong></span>
</p><p>
PreparedStatements are implemented by the driver, as MySQL
does not have a prepared statement feature. Because of this,
the driver does not implement
<code class="function">getParameterMetaData()</code> or
<code class="function">getMetaData()</code> as it would require the
driver to have a complete SQL parser in the client.
</p><p>
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.
</p><p>
Take care when using a server-side prepared statement with
<span class="bold"><strong>large</strong></span> parameters that are
set using <code class="function">setBinaryStream()</code>,
<code class="function">setAsciiStream()</code>,
<code class="function">setUnicodeStream()</code>,
<code class="function">setBlob()</code>, or
<code class="function">setClob()</code>. To re-execute the statement
with any large parameter changed to a nonlarge parameter,
call <code class="function">clearParameters()</code> and set all
parameters again. The reason for this is as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
During both server-side prepared statements and
client-side emulation, large data is exchanged only when
<code class="literal">PreparedStatement.execute()</code> is
called.
</p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
Once that has been done, the stream used to read the
data on the client side is closed (as per the JDBC
spec), and cannot be read from again.
</p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
If a parameter changes from large to nonlarge, the
driver must reset the server-side state of the prepared
statement to allow the parameter that is being changed
to take the place of the prior large value. This removes
all of the large data that has already been sent to the
server, thus requiring the data to be re-sent, using the
<code class="function">setBinaryStream()</code>,
<code class="function">setAsciiStream()</code>,
<code class="function">setUnicodeStream()</code>,
<code class="function">setBlob()</code> or
<code class="function">setClob()</code> method.
</p></li></ul></div><p>
Consequently, to change the type of a parameter to a
nonlarge one, you must call
<code class="function">clearParameters()</code> and set all
parameters of the prepared statement again before it can be
re-executed.
</p></li><li class="listitem"><p>
<span class="bold"><strong>ResultSet</strong></span>
</p><p>
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 cannot
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.
</p><p>
To enable this functionality, create a
<code class="literal">Statement</code> instance in the following
manner:
</p><pre class="programlisting">
stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY,
java.sql.ResultSet.CONCUR_READ_ONLY);
stmt.setFetchSize(Integer.MIN_VALUE);
</pre><p>
The combination of a forward-only, read-only result set,
with a fetch size of <code class="literal">Integer.MIN_VALUE</code>
serves as a signal to the driver to stream result sets
row-by-row. After this, any result sets created with the
statement will be retrieved row-by-row.
</p><p>
There are some caveats with this approach. You must 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.
</p><p>
The earliest the locks these statements hold can be released
(whether they be <code class="literal">MyISAM</code> table-level locks
or row-level locks in some other storage engine such as
<code class="literal">InnoDB</code>) is when the statement completes.
</p><p>
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.
</p><p>
Therefore, if using streaming results, process them as
quickly as possible if you want to maintain concurrent
access to the tables referenced by the statement producing
the result set.
</p></li><li class="listitem"><p>
<span class="bold"><strong>ResultSetMetaData</strong></span>
</p><p>
The <code class="function">isAutoIncrement()</code> method only works
when using MySQL servers 4.0 and newer.
</p></li><li class="listitem"><p>
<span class="bold"><strong>Statement</strong></span>
</p><p>
When using versions of the JDBC driver earlier than 3.2.1,
and connected to server versions earlier than 5.0.3, the
<code class="function">setFetchSize()</code> method has no effect,
other than to toggle result set streaming as described
above.
</p><p>
Connector/J 5.0.0 and later include support for both
<code class="literal">Statement.cancel()</code> and
<code class="literal">Statement.setQueryTimeout()</code>. Both require
MySQL 5.0.0 or newer server, and require a separate
connection to issue the
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/kill.html" target="_top"><code class="literal">KILL QUERY</code></a>
statement. In the case of
<code class="function">setQueryTimeout()</code>, the implementation
creates an additional thread to handle the timeout
functionality.
</p><div xmlns="http://www.w3.org/1999/xhtml" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p xmlns="">
Failures to cancel the statement for
<code class="function">setQueryTimeout()</code> may manifest
themselves as <code class="literal">RuntimeException</code> rather
than failing silently, as there is currently no way to
unblock the thread that is executing the query being
cancelled due to timeout expiration and have it throw the
exception instead.
</p></div><div xmlns="http://www.w3.org/1999/xhtml" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p xmlns="">
The MySQL statement
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/kill.html" target="_top"><code class="literal">KILL QUERY</code></a>
(which is what the driver uses to implement
<code class="literal">Statement.cancel()</code>) is
non-deterministic; thus, avoid the use of
<code class="literal">Statement.cancel()</code> if possible. If no
query is in process, the next query issued will be killed
by the server. This race condition is guarded against as
of Connector/J 5.1.18.
</p></div><p>
MySQL does not support SQL cursors, and the JDBC driver
doesn't emulate them, so <code class="literal">setCursorName()</code>
has no effect.
</p><p>
Connector/J 5.1.3 and later include two additional methods:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
<code class="function">setLocalInfileInputStream()</code> sets an
<code class="literal">InputStream</code> instance that will be
used to send data to the MySQL server for a
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/load-data.html" target="_top"><code class="literal">LOAD DATA
LOCAL INFILE</code></a> statement rather than a
<code class="literal">FileInputStream</code> or
<code class="literal">URLInputStream</code> that represents the
path given as an argument to the statement.
</p><p>
This stream will be read to completion upon execution of
a <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/load-data.html" target="_top"><code class="literal">LOAD DATA
LOCAL INFILE</code></a> statement, and will automatically
be closed by the driver, so it needs to be reset before
each call to <code class="literal">execute*()</code> that would
cause the MySQL server to request data to fulfill the
request for
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/load-data.html" target="_top"><code class="literal">LOAD DATA
LOCAL INFILE</code></a>.
</p><p>
If this value is set to <code class="literal">NULL</code>, the
driver will revert to using a
<code class="literal">FileInputStream</code> or
<code class="literal">URLInputStream</code> as required.
</p></li><li class="listitem"><p>
<code class="function">getLocalInfileInputStream()</code> returns
the <code class="literal">InputStream</code> instance that will be
used to send data in response to a
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/load-data.html" target="_top"><code class="literal">LOAD DATA
LOCAL INFILE</code></a> statement.
</p><p>
This method returns <code class="literal">NULL</code> if no such
stream has been set using
<code class="function">setLocalInfileInputStream()</code>.
</p></li></ul></div></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-reference-type-conversions"></a>5.3. Java, JDBC and MySQL Types</h2></div></div></div><a class="indexterm" name="idm47020251274848"></a><p>
MySQL Connector/J is flexible in the way it handles conversions
between MySQL data types and Java data types.
</p><p>
In general, any MySQL data type can be converted to a
<code class="literal">java.lang.String</code>, and any numeric type can be
converted to any of the Java numeric types, although round-off,
overflow, or loss of precision may occur.
</p><div xmlns="http://www.w3.org/1999/xhtml" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p xmlns="">
All <code class="literal">TEXT</code> types return
<code class="literal">Types.LONGVARCHAR</code> with different
<code class="literal">getPrecision()</code> values (65535, 255,
16777215, and 2147483647 respectively) with
<code class="literal">getColumnType()</code> returning
<code class="literal">-1</code>. This behavior is intentional even
though <code class="literal">TINYTEXT</code> does not fall, regarding to
its size, within the <code class="literal">LONGVARCHAR</code> category.
This is to avoid different handling inside the same base type.
And <code class="literal">getColumnType()</code> returns
<code class="literal">-1</code> because the internal server handling is
of type <code class="literal">TEXT</code>, which is similar to
<code class="literal">BLOB</code>.
</p><p xmlns="">
Also note that <code class="literal">getColumnTypeName()</code> will
return <code class="literal">VARCHAR</code> even though
<code class="literal">getColumnType()</code> returns
<code class="literal">Types.LONGVARCHAR</code>, because
<code class="literal">VARCHAR</code> is the designated column
database-specific name for this type.
</p></div><p>
Starting with Connector/J 3.1.0, the JDBC driver issues warnings
or throws <code class="literal">DataTruncation</code> exceptions as is
required by the JDBC specification unless the connection was
configured not to do so by using the property
<code class="literal">jdbcCompliantTruncation</code> and setting it to
<code class="literal">false</code>.
</p><p>
The conversions that are always guaranteed to work are listed in
the following table. The first column lists one or more MySQL
data types, and the second column lists one or more Java types
to which the MySQL types can be converted.
</p><div class="table"><a name="idm47020251260224"></a><p class="title"><b>Table 5.1. Connection Properties - Miscellaneous</b></p><div class="table-contents"><table summary="Connection Properties - Miscellaneous" border="1"><colgroup><col><col></colgroup><thead><tr><th scope="col">These MySQL Data Types</th><th scope="col">Can always be converted to these Java types</th></tr></thead><tbody><tr><td scope="row"><code class="literal">CHAR, VARCHAR, BLOB, TEXT, ENUM, and SET</code></td><td><code class="literal">java.lang.String, java.io.InputStream, java.io.Reader,
java.sql.Blob, java.sql.Clob</code></td></tr><tr><td scope="row"><code class="literal">FLOAT, REAL, DOUBLE PRECISION, NUMERIC, DECIMAL, TINYINT,
SMALLINT, MEDIUMINT, INTEGER, BIGINT</code></td><td><code class="literal">java.lang.String, java.lang.Short, java.lang.Integer,
java.lang.Long, java.lang.Double,
java.math.BigDecimal</code></td></tr><tr><td scope="row"><code class="literal">DATE, TIME, DATETIME, TIMESTAMP</code></td><td><code class="literal">java.lang.String, java.sql.Date, java.sql.Timestamp</code></td></tr></tbody></table></div></div><br class="table-break"><div xmlns="http://www.w3.org/1999/xhtml" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p xmlns="">
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.
</p></div><p>
The <code class="classname">ResultSet.getObject()</code> method uses the
type conversions between MySQL and Java types, following the
JDBC specification where appropriate. The value returned by
<code class="classname">ResultSetMetaData.GetColumnClassName()</code> is
also shown below. For more information on the
<code class="literal">java.sql.Types</code> classes see
<a class="ulink" href="http://java.sun.com/j2se/1.4.2/docs/api/java/sql/Types.html" target="_top">Java
2 Platform Types</a>.
</p><div class="table"><a name="idm47020251247216"></a><p class="title"><b>Table 5.2. MySQL Types to Java Types for ResultSet.getObject()</b></p><div class="table-contents"><table summary="MySQL Types to Java Types for ResultSet.getObject()" border="1"><colgroup><col><col><col></colgroup><thead><tr><th scope="col">MySQL Type Name</th><th scope="col">Return value of <code class="literal">GetColumnClassName</code></th><th scope="col">Returned as Java Class</th></tr></thead><tbody><tr><td scope="row"><code class="literal">BIT(1)</code> (new in MySQL-5.0)</td><td><code class="literal">BIT</code></td><td><code class="classname">java.lang.Boolean</code></td></tr><tr><td scope="row"><code class="literal">BIT( > 1)</code> (new in MySQL-5.0)</td><td><code class="literal">BIT</code></td><td><code class="classname">byte[]</code></td></tr><tr><td scope="row"><code class="literal">TINYINT</code></td><td><code class="literal">TINYINT</code></td><td><code class="classname">java.lang.Boolean</code> if the configuration property
<code class="literal">tinyInt1isBit</code> is set to
<code class="literal">true</code> (the default) and the storage
size is 1, or <code class="classname">java.lang.Integer</code>
if not.</td></tr><tr><td scope="row"><code class="literal">BOOL</code>, <code class="literal">BOOLEAN</code></td><td><code class="literal">TINYINT</code></td><td>See <code class="literal">TINYINT</code>, above as these are aliases for
<code class="literal">TINYINT(1)</code>, currently.</td></tr><tr><td scope="row"><code class="literal">SMALLINT[(M)] [UNSIGNED]</code></td><td><code class="literal">SMALLINT [UNSIGNED]</code></td><td><code class="classname">java.lang.Integer</code> (regardless if
<code class="literal">UNSIGNED</code> or not)</td></tr><tr><td scope="row"><code class="literal">MEDIUMINT[(M)] [UNSIGNED]</code></td><td><code class="literal">MEDIUMINT [UNSIGNED]</code></td><td><code class="classname">java.lang.Integer,</code> if <code class="literal">UNSIGNED</code>
<code class="classname">java.lang.Long</code> (C/J 3.1 and
earlier), or <code class="classname">java.lang.Integer</code>
for C/J 5.0 and later</td></tr><tr><td scope="row"><code class="literal">INT,INTEGER[(M)] [UNSIGNED]</code></td><td><code class="literal">INTEGER [UNSIGNED]</code></td><td><code class="classname">java.lang.Integer</code>, if <code class="literal">UNSIGNED</code>
<code class="classname">java.lang.Long</code></td></tr><tr><td scope="row"><code class="literal">BIGINT[(M)] [UNSIGNED]</code></td><td><code class="literal">BIGINT [UNSIGNED]</code></td><td><code class="classname">java.lang.Long</code>, if UNSIGNED
<code class="classname">java.math.BigInteger</code></td></tr><tr><td scope="row"><code class="literal">FLOAT[(M,D)]</code></td><td><code class="literal">FLOAT</code></td><td><code class="classname">java.lang.Float</code></td></tr><tr><td scope="row"><code class="literal">DOUBLE[(M,B)]</code></td><td><code class="literal">DOUBLE</code></td><td><code class="classname">java.lang.Double</code></td></tr><tr><td scope="row"><code class="literal">DECIMAL[(M[,D])]</code></td><td><code class="literal">DECIMAL</code></td><td><code class="classname">java.math.BigDecimal</code></td></tr><tr><td scope="row"><code class="literal">DATE</code></td><td><code class="literal">DATE</code></td><td><code class="classname">java.sql.Date</code></td></tr><tr><td scope="row"><code class="literal">DATETIME</code></td><td><code class="literal">DATETIME</code></td><td><code class="classname">java.sql.Timestamp</code></td></tr><tr><td scope="row"><code class="literal">TIMESTAMP[(M)]</code></td><td><code class="literal">TIMESTAMP</code></td><td><code class="classname">java.sql.Timestamp</code></td></tr><tr><td scope="row"><code class="literal">TIME</code></td><td><code class="literal">TIME</code></td><td><code class="classname">java.sql.Time</code></td></tr><tr><td scope="row"><code class="literal">YEAR[(2|4)]</code></td><td><code class="literal">YEAR</code></td><td>If <code class="literal">yearIsDateType</code> configuration property is set to
<code class="literal">false</code>, then the returned object type
is <code class="classname">java.sql.Short</code>. If set to
<code class="literal">true</code> (the default), then the returned
object is of type <code class="classname">java.sql.Date</code>
with the date
set to January 1st, at midnight.</td></tr><tr><td scope="row"><code class="literal">CHAR(M)</code></td><td><code class="literal">CHAR</code></td><td><code class="classname">java.lang.String</code> (unless the character set for
the column is <code class="literal">BINARY</code>, then
<code class="classname">byte[]</code> is returned.</td></tr><tr><td scope="row"><code class="literal">VARCHAR(M) [BINARY]</code></td><td><code class="literal">VARCHAR</code></td><td><code class="classname">java.lang.String</code> (unless the character set for
the column is <code class="literal">BINARY</code>, then
<code class="classname">byte[]</code> is returned.</td></tr><tr><td scope="row"><code class="literal">BINARY(M)</code></td><td><code class="literal">BINARY</code></td><td><code class="classname">byte[]</code></td></tr><tr><td scope="row"><code class="literal">VARBINARY(M)</code></td><td><code class="literal">VARBINARY</code></td><td><code class="classname">byte[]</code></td></tr><tr><td scope="row"><code class="literal">TINYBLOB</code></td><td><code class="literal">TINYBLOB</code></td><td><code class="classname">byte[]</code></td></tr><tr><td scope="row"><code class="literal">TINYTEXT</code></td><td><code class="literal">VARCHAR</code></td><td><code class="classname">java.lang.String</code></td></tr><tr><td scope="row"><code class="literal">BLOB</code></td><td><code class="literal">BLOB</code></td><td><code class="classname">byte[]</code></td></tr><tr><td scope="row"><code class="literal">TEXT</code></td><td><code class="literal">VARCHAR</code></td><td><code class="classname">java.lang.String</code></td></tr><tr><td scope="row"><code class="literal">MEDIUMBLOB</code></td><td><code class="literal">MEDIUMBLOB</code></td><td><code class="classname">byte[]</code></td></tr><tr><td scope="row"><code class="literal">MEDIUMTEXT</code></td><td><code class="literal">VARCHAR</code></td><td><code class="classname">java.lang.String</code></td></tr><tr><td scope="row"><code class="literal">LONGBLOB</code></td><td><code class="literal">LONGBLOB</code></td><td><code class="classname">byte[]</code></td></tr><tr><td scope="row"><code class="literal">LONGTEXT</code></td><td><code class="literal">VARCHAR</code></td><td><code class="classname">java.lang.String</code></td></tr><tr><td scope="row"><code class="literal">ENUM('value1','value2',...)</code></td><td><code class="literal">CHAR</code></td><td><code class="classname">java.lang.String</code></td></tr><tr><td scope="row"><code class="literal">SET('value1','value2',...)</code></td><td><code class="literal">CHAR</code></td><td><code class="classname">java.lang.String</code></td></tr></tbody></table></div></div><br class="table-break"></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-reference-charsets"></a>5.4. Using Character Sets and Unicode</h2></div></div></div><a class="indexterm" name="idm47020251168880"></a><a class="indexterm" name="idm47020251167664"></a><a class="indexterm" name="idm47020251166448"></a><p>
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 using
<code class="literal">Statement.execute()</code>,
<code class="literal">Statement.executeUpdate()</code>,
<code class="literal">Statement.executeQuery()</code> as well as all
<code class="interfacename">PreparedStatement</code> and
<code class="interfacename">CallableStatement</code> parameters with
the exclusion of parameters set using
<code class="function">setBytes()</code>,
<code class="function">setBinaryStream()</code>,
<code class="function">setAsciiStream()</code>,
<code class="function">setUnicodeStream()</code> and
<code class="function">setBlob()</code>.
</p><h3><a name="idm47020251160048"></a>
Number of Encodings Per Connection
</h3><p>
In MySQL Server 4.1 and higher, 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 <code class="classname">ResultSets</code>.
</p><p>
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
<em class="parameter"><code>useUnicode</code></em> and
<em class="parameter"><code>characterEncoding</code></em> properties.
</p><h3><a name="idm47020251156976"></a>
Setting the Character Encoding
</h3><p>
The character encoding between client and server is
automatically detected upon connection. You specify the encoding
on the server using the
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/server-system-variables.html#sysvar_character_set_server" target="_top"><code class="literal">character_set_server</code></a> for server
versions 4.1.0 and newer, and <code class="literal">character_set</code>
system variable for server versions older than 4.1.0. The driver
automatically uses the encoding specified by the server. For
more information, see <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/charset-server.html" target="_top">Server Character Set and Collation</a>.
</p><p>
For example, to use 4-byte UTF-8 character sets with
Connector/J, configure the MySQL server with
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/server-system-variables.html#sysvar_character_set_server" target="_top"><code class="literal">character_set_server=utf8mb4</code></a>,
and leave <code class="literal">characterEncoding</code> out of the
Connector/J connection string. Connector/J will then autodetect
the UTF-8 setting.
</p><p>
To override the automatically detected encoding on the client
side, use the <em class="parameter"><code>characterEncoding</code></em> property
in the URL used to connect to the server.
</p><p>
To allow multiple character sets to be sent from the client, use
the UTF-8 encoding, either by configuring
<code class="literal">utf8</code> as the default server character set, or
by configuring the JDBC driver to use UTF-8 through the
<code class="literal">characterEncoding</code> property.
</p><p>
When specifying character encodings on the client side, use
Java-style names. The following table lists MySQL character set
names and the corresponding Java-style names:
</p><div class="table"><a name="idm47020251148464"></a><p class="title"><b>Table 5.3. MySQL to Java Encoding Name Translations</b></p><div class="table-contents"><table summary="MySQL to Java Encoding Name Translations" border="1"><colgroup><col><col></colgroup><thead><tr><th scope="col">MySQL Character Set Name</th><th scope="col">Java-Style Character Encoding Name</th></tr></thead><tbody><tr><td scope="row"><code class="literal">ascii</code></td><td><code class="literal">US-ASCII</code></td></tr><tr><td scope="row"><code class="literal">big5</code></td><td><code class="literal">Big5</code></td></tr><tr><td scope="row"><code class="literal">gbk</code></td><td><code class="literal">GBK</code></td></tr><tr><td scope="row"><code class="literal">sjis</code></td><td><code class="literal">SJIS (or Cp932 or MS932 for MySQL Server < 4.1.11)</code></td></tr><tr><td scope="row"><code class="literal">cp932</code></td><td><code class="literal">Cp932 or MS932 (MySQL Server > 4.1.11)</code></td></tr><tr><td scope="row"><code class="literal">gb2312</code></td><td><code class="literal">EUC_CN</code></td></tr><tr><td scope="row"><code class="literal">ujis</code></td><td><code class="literal">EUC_JP</code></td></tr><tr><td scope="row"><code class="literal">euckr</code></td><td><code class="literal">EUC_KR</code></td></tr><tr><td scope="row"><code class="literal">latin1</code></td><td><code class="literal">Cp1252</code></td></tr><tr><td scope="row"><code class="literal">latin2</code></td><td><code class="literal">ISO8859_2</code></td></tr><tr><td scope="row"><code class="literal">greek</code></td><td><code class="literal">ISO8859_7</code></td></tr><tr><td scope="row"><code class="literal">hebrew</code></td><td><code class="literal">ISO8859_8</code></td></tr><tr><td scope="row"><code class="literal">cp866</code></td><td><code class="literal">Cp866</code></td></tr><tr><td scope="row"><code class="literal">tis620</code></td><td><code class="literal">TIS620</code></td></tr><tr><td scope="row"><code class="literal">cp1250</code></td><td><code class="literal">Cp1250</code></td></tr><tr><td scope="row"><code class="literal">cp1251</code></td><td><code class="literal">Cp1251</code></td></tr><tr><td scope="row"><code class="literal">cp1257</code></td><td><code class="literal">Cp1257</code></td></tr><tr><td scope="row"><code class="literal">macroman</code></td><td><code class="literal">MacRoman</code></td></tr><tr><td scope="row"><code class="literal">macce</code></td><td><code class="literal">MacCentralEurope</code></td></tr><tr><td scope="row"><code class="literal">utf8</code></td><td><code class="literal">UTF-8</code></td></tr><tr><td scope="row"><code class="literal">ucs2</code></td><td><code class="literal">UnicodeBig</code></td></tr></tbody></table></div></div><br class="table-break"><div xmlns="http://www.w3.org/1999/xhtml" class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Warning</div><p xmlns="">
Do not issue the query <code class="literal">set names</code> 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.
</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-reference-using-ssl"></a>5.5. Connecting Securely Using SSL</h2></div></div></div><a class="indexterm" name="idm47020251110480"></a><p>
SSL in MySQL Connector/J encrypts all data (other than the
initial handshake) between the JDBC driver and the server. There
is a performance penalty for enabling SSL, the severity of which
depends on multiple factors including (but not limited to) the
size of the query, the amount of data returned, the server
hardware, the SSL library used, the network bandwidth, and so
on.
</p><p>
For SSL support to work, you must have the following:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
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:
<a class="ulink" href="http://developer.java.sun.com/developer/bugParade/bugs/4273544.html" target="_top">http://developer.java.sun.com/developer/bugParade/bugs/4273544.html</a>
</p></li><li class="listitem"><p>
A MySQL server that supports SSL and has been compiled and
configured to do so, which is MySQL 4.0.4 or later. For more
information, see <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/configuring-for-ssl.html" target="_top">Configuring MySQL for SSL</a>.
</p></li><li class="listitem"><p>
A client certificate (covered later in this section)
</p></li></ul></div><p>
The system works through two Java truststore files, one file
contains the certificate information for the server
(<code class="filename">truststore</code> in the examples below). The
other file contains the certificate for the client
(<code class="filename">keystore</code> in the examples below). All Java
truststore files are password protected by supplying a suitable
password to the <span class="command"><strong>keytool</strong></span> when you create the
files. You need the file names and associated passwords to
create an SSL connection.
</p><p>
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 <code class="filename">SSL</code> subdirectory of the
MySQL source distribution. This is what SSL will use to
determine if you are communicating with a secure MySQL server.
Alternatively, use the CA Certificate that you have generated or
been provided with by your SSL provider.
</p><p>
To use Java's <span class="command"><strong>keytool</strong></span> to create a truststore
in the current directory , and import the server's CA
certificate (<code class="filename">cacert.pem</code>), you can do the
following (assuming that <span class="command"><strong>keytool</strong></span> is in your
path. The <span class="command"><strong>keytool</strong></span> is typically located in the
<code class="filename">bin</code> subdirectory of your JDK or JRE):
</p><pre class="programlisting">
shell> keytool -import -alias mysqlServerCACert \
-file cacert.pem -keystore truststore
</pre><p>
Enter the password when prompted for the keystore file.
Interaction with <span class="command"><strong>keytool</strong></span> looks like this:
</p><pre class="programlisting">
Enter keystore password: *********
Owner: EMAILADDRESS=walrus@example.com, CN=Walrus,
O=MySQL AB, L=Orenburg, ST=Some-State, C=RU
Issuer: EMAILADDRESS=walrus@example.com, CN=Walrus,
O=MySQL AB, L=Orenburg, ST=Some-State, C=RU
Serial number: 0
Valid from:
Fri Aug 02 16:55:53 CDT 2002 until: Sat Aug 02 16:55:53 CDT 2003
Certificate fingerprints:
MD5: 61:91:A0:F2:03:07:61:7A:81:38:66:DA:19:C4:8D:AB
SHA1: 25:77:41:05:D5:AD:99:8C:14:8C:CA:68:9C:2F:B8:89:C3:34:4D:6C
Trust this certificate? [no]: yes
Certificate was added to keystore
</pre><p>
You then have two options: either import the client certificate
that matches the CA certificate you just imported, or create a
new client certificate.
</p><p>
Importing an existing certificate requires the certificate to be
in DER format. You can use <span class="command"><strong>openssl</strong></span> to convert
an existing certificate into the new format. For example:
</p><pre class="programlisting">
shell> openssl x509 -outform DER -in client-cert.pem -out client.cert
</pre><p>
Now import the converted certificate into your keystore using
<span class="command"><strong>keytool</strong></span>:
</p><pre class="programlisting">
shell> keytool -import -file client.cert -keystore keystore -alias mysqlClientCertificate
</pre><p>
To generate your own client certificate, use
<span class="command"><strong>keytool</strong></span> to create a suitable certificate and
add it to the <code class="filename">keystore</code> file:
</p><pre class="programlisting">
shell> keytool -genkey -keyalg rsa \
-alias mysqlClientCertificate -keystore keystore
</pre><p>
Keytool will prompt you for the following information, and
create a keystore named <code class="filename">keystore</code> in the
current directory.
</p><p>
Respond with information that is appropriate for your situation:
</p><pre class="programlisting">
Enter keystore password: *********
What is your first and last name?
[Unknown]: Matthews
What is the name of your organizational unit?
[Unknown]: Software Development
What is the name of your organization?
[Unknown]: MySQL AB
What is the name of your City or Locality?
[Unknown]: Flossmoor
What is the name of your State or Province?
[Unknown]: IL
What is the two-letter country code for this unit?
[Unknown]: US
Is <CN=Matthews, OU=Software Development, O=MySQL AB,
L=Flossmoor, ST=IL, C=US> correct?
[no]: y
Enter key password for <mysqlClientCertificate>
(RETURN if same as keystore password):
</pre><p>
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
<em class="replaceable"><code>path_to_keystore_file</code></em> with the full
path to the keystore file you created,
<em class="replaceable"><code>path_to_truststore_file</code></em> with the path
to the truststore file you created, and using the appropriate
password values for each property. You can do this either on the
command line:
</p><pre class="programlisting">
-Djavax.net.ssl.keyStore=<em class="replaceable"><code>path_to_keystore_file</code></em>
-Djavax.net.ssl.keyStorePassword=<em class="replaceable"><code>password</code></em>
-Djavax.net.ssl.trustStore=<em class="replaceable"><code>path_to_truststore_file</code></em>
-Djavax.net.ssl.trustStorePassword=<em class="replaceable"><code>password</code></em>
</pre><p>
Or you can set the values directly within the application:
</p><pre class="programlisting">
System.setProperty("javax.net.ssl.keyStore","<em class="replaceable"><code>path_to_keystore_file</code></em>");
System.setProperty("javax.net.ssl.keyStorePassword","<em class="replaceable"><code>password</code></em>");
System.setProperty("javax.net.ssl.trustStore","<em class="replaceable"><code>path_to_truststore_file</code></em>");
System.setProperty("javax.net.ssl.trustStorePassword","<em class="replaceable"><code>password</code></em>");
</pre><p>
You will also need to set <code class="literal">useSSL</code> to
<code class="literal">true</code> in your connection parameters for MySQL
Connector/J, either by adding <code class="literal">useSSL=true</code> to
your URL, or by setting the property <code class="literal">useSSL</code>
to <code class="literal">true</code> in the
<code class="classname">java.util.Properties</code> instance you pass to
<code class="literal">DriverManager.getConnection()</code>.
</p><p>
You can test that SSL is working by turning on JSSE debugging
(as detailed below), and look for the following key events:
</p><pre class="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: {}
Cipher Suites: { 0, 5, 0, 4, 0, 9, 0, 10, 0, 18, 0, 19, 0, 3, 0, 17 }
Compression Methods: { 0 }
***
[write] MD5 and SHA1 hashes: len = 59
0000: 01 00 00 37 03 01 3D B6 90 FA C7 94 B4 D7 4A 0C ...7..=.......J.
0010: 36 F4 00 A8 37 67 D7 40 10 8A E1 BE 84 99 02 D9 6...7g.@........
0020: DB EF CA 13 79 4E 00 00 10 00 05 00 04 00 09 00 ....yN..........
0030: 0A 00 12 00 13 00 03 00 11 01 00 ...........
main, WRITE: SSL v3.1 Handshake, length = 59
main, READ: SSL v3.1 Handshake, length = 74
*** ServerHello, v3.1
RandomCookie: GMT: 1018577560 bytes = { 116, 50, 4, 103, 25, 100, 58, »
202, 79, 185, 178, 100, 215, 66, 254, 21, 83, 187, 190, 42, 170, 3, »
132, 110, 82, 148, 160, 92 }
Session ID: {163, 227, 84, 53, 81, 127, 252, 254, 178, 179, 68, 63, »
182, 158, 30, 11, 150, 79, 170, 76, 255, 92, 15, 226, 24, 17, 177, »
219, 158, 177, 187, 143}
Cipher Suite: { 0, 5 }
Compression Method: 0
***
%% Created: [Session-1, SSL_RSA_WITH_RC4_128_SHA]
** SSL_RSA_WITH_RC4_128_SHA
[read] MD5 and SHA1 hashes: len = 74
0000: 02 00 00 46 03 01 3D B6 43 98 74 32 04 67 19 64 ...F..=.C.t2.g.d
0010: 3A CA 4F B9 B2 64 D7 42 FE 15 53 BB BE 2A AA 03 :.O..d.B..S..*..
0020: 84 6E 52 94 A0 5C 20 A3 E3 54 35 51 7F FC FE B2 .nR..\ ..T5Q....
0030: B3 44 3F B6 9E 1E 0B 96 4F AA 4C FF 5C 0F E2 18 .D?.....O.L.\...
0040: 11 B1 DB 9E B1 BB 8F 00 05 00 ..........
main, READ: SSL v3.1 Handshake, length = 1712
...
</pre><p>
JSSE provides debugging (to <code class="literal">stdout</code>) when you
set the following system property:
<code class="literal">-Djavax.net.debug=all</code> 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.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-using-pam"></a>5.6. Connecting Using PAM Authentication</h2></div></div></div><a class="indexterm" name="idm47020251070176"></a><p>
Java applications using Connector/J 5.1.21 and higher can
connect to MySQL servers that use the pluggable authentication
module (PAM) authentication scheme.
</p><p>
For PAM authentication to work, you must have the following:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
A MySQL server that supports PAM authentication: a
commercial distribution of MySQL 5.5.16 or higher. See
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/pam-authentication-plugin.html" target="_top">The PAM Authentication Plugin</a> for more
information. Connector/J implements the same cleartext
authentication method as in
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/cleartext-authentication-plugin.html" target="_top">The Cleartext Client-Side Authentication Plugin</a>.
</p></li><li class="listitem"><p>
SSL capability, as explained in
<a class="xref" href="#connector-j-reference-using-ssl" title="5.5. Connecting Securely Using SSL">Section 5.5, “Connecting Securely Using SSL”</a>. Because
the PAM authentication scheme sends the original password to
the server, the connection to the server must be encrypted.
</p></li></ul></div><p>
PAM authentication support is enabled by default in Connector/J
5.1.21 and up, so no extra configuration is needed.
</p><p>
To disable the PAM authentication feature, specify
<code class="literal">mysql_clear_password</code> (the method) or
<code class="literal">com.mysql.jdbc.authentication.MysqlClearPasswordPlugin</code>
(the class name) in the comma-separated list of arguments for
the <code class="literal">disabledAuthenticationPlugins</code> connection
option. See
<a class="xref" href="#connector-j-reference-configuration-properties" title="5.1. Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J">Section 5.1, “Driver/Datasource Class Names, URL Syntax and Configuration Properties
for Connector/J”</a>
for details about that connection option.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-reference-replication-connection"></a>5.7. Using Master/Slave Replication with ReplicationConnection</h2></div></div></div><p>
See
<a class="xref" href="#connector-j-master-slave-replication-connection" title="8.3. Master/Slave Replication with ReplicationConnection">Section 8.3, “Master/Slave Replication with ReplicationConnection”</a>
for details on the topic.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-reference-error-sqlstates"></a>5.8. Mapping MySQL Error Numbers to JDBC SQLState Codes</h2></div></div></div><a class="indexterm" name="idm47020251056832"></a><a class="indexterm" name="idm47020251056032"></a><a class="indexterm" name="idm47020251055232"></a><a class="indexterm" name="idm47020251054016"></a><a class="indexterm" name="idm47020251052800"></a><a class="indexterm" name="idm47020251052000"></a><a class="indexterm" name="idm47020251051200"></a><a class="indexterm" name="idm47020251050400"></a><a class="indexterm" name="idm47020251049600"></a><a class="indexterm" name="idm47020251048800"></a><a class="indexterm" name="idm47020251048000"></a><a class="indexterm" name="idm47020251047184"></a><a class="indexterm" name="idm47020251046384"></a><a class="indexterm" name="idm47020251045584"></a><a class="indexterm" name="idm47020251044784"></a><a class="indexterm" name="idm47020251043984"></a><a class="indexterm" name="idm47020251043184"></a><a class="indexterm" name="idm47020251042384"></a><a class="indexterm" name="idm47020251041584"></a><a class="indexterm" name="idm47020251040768"></a><a class="indexterm" name="idm47020251039968"></a><a class="indexterm" name="idm47020251039168"></a><a class="indexterm" name="idm47020251038368"></a><a class="indexterm" name="idm47020251037568"></a><a class="indexterm" name="idm47020251036768"></a><a class="indexterm" name="idm47020251035968"></a><a class="indexterm" name="idm47020251035168"></a><a class="indexterm" name="idm47020251034368"></a><a class="indexterm" name="idm47020251033568"></a><a class="indexterm" name="idm47020251032768"></a><a class="indexterm" name="idm47020251031968"></a><a class="indexterm" name="idm47020251031168"></a><a class="indexterm" name="idm47020251030368"></a><a class="indexterm" name="idm47020251029568"></a><a class="indexterm" name="idm47020251028768"></a><a class="indexterm" name="idm47020251027968"></a><a class="indexterm" name="idm47020251027152"></a><a class="indexterm" name="idm47020251026352"></a><a class="indexterm" name="idm47020251025552"></a><a class="indexterm" name="idm47020251024752"></a><a class="indexterm" name="idm47020251023952"></a><a class="indexterm" name="idm47020251023152"></a><a class="indexterm" name="idm47020251022352"></a><a class="indexterm" name="idm47020251021536"></a><a class="indexterm" name="idm47020251020720"></a><a class="indexterm" name="idm47020251019904"></a><a class="indexterm" name="idm47020251019088"></a><a class="indexterm" name="idm47020251018272"></a><a class="indexterm" name="idm47020251017472"></a><a class="indexterm" name="idm47020251016672"></a><a class="indexterm" name="idm47020251015872"></a><a class="indexterm" name="idm47020251015072"></a><a class="indexterm" name="idm47020251014256"></a><a class="indexterm" name="idm47020251013456"></a><a class="indexterm" name="idm47020251012640"></a><a class="indexterm" name="idm47020251011824"></a><a class="indexterm" name="idm47020251011008"></a><a class="indexterm" name="idm47020251010192"></a><a class="indexterm" name="idm47020251009392"></a><a class="indexterm" name="idm47020251008592"></a><a class="indexterm" name="idm47020251007792"></a><a class="indexterm" name="idm47020251006992"></a><a class="indexterm" name="idm47020251006192"></a><a class="indexterm" name="idm47020251005376"></a><a class="indexterm" name="idm47020251004576"></a><a class="indexterm" name="idm47020251003776"></a><a class="indexterm" name="idm47020251002960"></a><a class="indexterm" name="idm47020251002160"></a><a class="indexterm" name="idm47020251001360"></a><a class="indexterm" name="idm47020251000544"></a><a class="indexterm" name="idm47020250999744"></a><a class="indexterm" name="idm47020250998928"></a><a class="indexterm" name="idm47020250998112"></a><a class="indexterm" name="idm47020250997296"></a><a class="indexterm" name="idm47020250996480"></a><a class="indexterm" name="idm47020250995680"></a><a class="indexterm" name="idm47020250994864"></a><a class="indexterm" name="idm47020250994064"></a><a class="indexterm" name="idm47020250993264"></a><a class="indexterm" name="idm47020250992464"></a><a class="indexterm" name="idm47020250991664"></a><a class="indexterm" name="idm47020250990848"></a><a class="indexterm" name="idm47020250990048"></a><a class="indexterm" name="idm47020250989232"></a><a class="indexterm" name="idm47020250988432"></a><a class="indexterm" name="idm47020250987632"></a><a class="indexterm" name="idm47020250986832"></a><a class="indexterm" name="idm47020250986032"></a><a class="indexterm" name="idm47020250985216"></a><a class="indexterm" name="idm47020250984416"></a><a class="indexterm" name="idm47020250983600"></a><a class="indexterm" name="idm47020250982784"></a><a class="indexterm" name="idm47020250981984"></a><a class="indexterm" name="idm47020250981184"></a><a class="indexterm" name="idm47020250980384"></a><a class="indexterm" name="idm47020250979568"></a><a class="indexterm" name="idm47020250978752"></a><a class="indexterm" name="idm47020250977952"></a><a class="indexterm" name="idm47020250977152"></a><a class="indexterm" name="idm47020250976352"></a><a class="indexterm" name="idm47020250975536"></a><a class="indexterm" name="idm47020250974720"></a><a class="indexterm" name="idm47020250973904"></a><a class="indexterm" name="idm47020250973104"></a><a class="indexterm" name="idm47020250972304"></a><a class="indexterm" name="idm47020250971488"></a><a class="indexterm" name="idm47020250970688"></a><a class="indexterm" name="idm47020250969872"></a><a class="indexterm" name="idm47020250969056"></a><a class="indexterm" name="idm47020250968256"></a><a class="indexterm" name="idm47020250967456"></a><a class="indexterm" name="idm47020250966656"></a><a class="indexterm" name="idm47020250965856"></a><a class="indexterm" name="idm47020250965040"></a><a class="indexterm" name="idm47020250964240"></a><a class="indexterm" name="idm47020250963440"></a><a class="indexterm" name="idm47020250962640"></a><a class="indexterm" name="idm47020250961840"></a><a class="indexterm" name="idm47020250961040"></a><a class="indexterm" name="idm47020250960240"></a><a class="indexterm" name="idm47020250959440"></a><a class="indexterm" name="idm47020250958640"></a><a class="indexterm" name="idm47020250957840"></a><a class="indexterm" name="idm47020250957040"></a><a class="indexterm" name="idm47020250956224"></a><a class="indexterm" name="idm47020250955424"></a><a class="indexterm" name="idm47020250954608"></a><a class="indexterm" name="idm47020250953792"></a><a class="indexterm" name="idm47020250952976"></a><a class="indexterm" name="idm47020250952160"></a><a class="indexterm" name="idm47020250951360"></a><a class="indexterm" name="idm47020250950544"></a><a class="indexterm" name="idm47020250949744"></a><a class="indexterm" name="idm47020250948928"></a><a class="indexterm" name="idm47020250948128"></a><a class="indexterm" name="idm47020250947328"></a><a class="indexterm" name="idm47020250946512"></a><p>
The table below provides a mapping of the MySQL error numbers to
JDBC <code class="literal">SQLState</code> values.
</p><div class="table"><a name="idm47020250944768"></a><p class="title"><b>Table 5.4. Mapping of MySQL Error Numbers to SQLStates</b></p><div class="table-contents"><table summary="Mapping of MySQL Error Numbers to SQLStates" border="1"><colgroup><col width="20"><col width="40"><col width="20"><col width="20"></colgroup><thead><tr><th scope="col">MySQL Error Number</th><th scope="col">MySQL Error Name</th><th scope="col">Legacy (X/Open) SQLState</th><th scope="col">SQL Standard SQLState</th></tr></thead><tbody><tr><td scope="row">1022</td><td>ER_DUP_KEY</td><td>S1000</td><td>23000</td></tr><tr><td scope="row">1037</td><td>ER_OUTOFMEMORY</td><td>S1001</td><td>HY001</td></tr><tr><td scope="row">1038</td><td>ER_OUT_OF_SORTMEMORY</td><td>S1001</td><td>HY001</td></tr><tr><td scope="row">1040</td><td>ER_CON_COUNT_ERROR</td><td>08004</td><td>08004</td></tr><tr><td scope="row">1042</td><td>ER_BAD_HOST_ERROR</td><td>08004</td><td>08S01</td></tr><tr><td scope="row">1043</td><td>ER_HANDSHAKE_ERROR</td><td>08004</td><td>08S01</td></tr><tr><td scope="row">1044</td><td>ER_DBACCESS_DENIED_ERROR</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1045</td><td>ER_ACCESS_DENIED_ERROR</td><td>28000</td><td>28000</td></tr><tr><td scope="row">1047</td><td>ER_UNKNOWN_COM_ERROR</td><td>08S01</td><td>HY000</td></tr><tr><td scope="row">1050</td><td>ER_TABLE_EXISTS_ERROR</td><td>S1000</td><td>42S01</td></tr><tr><td scope="row">1051</td><td>ER_BAD_TABLE_ERROR</td><td>42S02</td><td>42S02</td></tr><tr><td scope="row">1052</td><td>ER_NON_UNIQ_ERROR</td><td>S1000</td><td>23000</td></tr><tr><td scope="row">1053</td><td>ER_SERVER_SHUTDOWN</td><td>S1000</td><td>08S01</td></tr><tr><td scope="row">1054</td><td>ER_BAD_FIELD_ERROR</td><td>S0022</td><td>42S22</td></tr><tr><td scope="row">1055</td><td>ER_WRONG_FIELD_WITH_GROUP</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1056</td><td>ER_WRONG_GROUP_FIELD</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1057</td><td>ER_WRONG_SUM_SELECT</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1058</td><td>ER_WRONG_VALUE_COUNT</td><td>21S01</td><td>21S01</td></tr><tr><td scope="row">1059</td><td>ER_TOO_LONG_IDENT</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1060</td><td>ER_DUP_FIELDNAME</td><td>S1009</td><td>42S21</td></tr><tr><td scope="row">1061</td><td>ER_DUP_KEYNAME</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1062</td><td>ER_DUP_ENTRY</td><td>S1009</td><td>23000</td></tr><tr><td scope="row">1063</td><td>ER_WRONG_FIELD_SPEC</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1064</td><td>ER_PARSE_ERROR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1065</td><td>ER_EMPTY_QUERY</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1066</td><td>ER_NONUNIQ_TABLE</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1067</td><td>ER_INVALID_DEFAULT</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1068</td><td>ER_MULTIPLE_PRI_KEY</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1069</td><td>ER_TOO_MANY_KEYS</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1070</td><td>ER_TOO_MANY_KEY_PARTS</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1071</td><td>ER_TOO_LONG_KEY</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1072</td><td>ER_KEY_COLUMN_DOES_NOT_EXITS</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1073</td><td>ER_BLOB_USED_AS_KEY</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1074</td><td>ER_TOO_BIG_FIELDLENGTH</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1075</td><td>ER_WRONG_AUTO_KEY</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1080</td><td>ER_FORCING_CLOSE</td><td>S1000</td><td>08S01</td></tr><tr><td scope="row">1081</td><td>ER_IPSOCK_ERROR</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1082</td><td>ER_NO_SUCH_INDEX</td><td>S1009</td><td>42S12</td></tr><tr><td scope="row">1083</td><td>ER_WRONG_FIELD_TERMINATORS</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1084</td><td>ER_BLOBS_AND_NO_TERMINATED</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1090</td><td>ER_CANT_REMOVE_ALL_FIELDS</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1091</td><td>ER_CANT_DROP_FIELD_OR_KEY</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1101</td><td>ER_BLOB_CANT_HAVE_DEFAULT</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1102</td><td>ER_WRONG_DB_NAME</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1103</td><td>ER_WRONG_TABLE_NAME</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1104</td><td>ER_TOO_BIG_SELECT</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1106</td><td>ER_UNKNOWN_PROCEDURE</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1107</td><td>ER_WRONG_PARAMCOUNT_TO_PROCEDURE</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1109</td><td>ER_UNKNOWN_TABLE</td><td>S1000</td><td>42S02</td></tr><tr><td scope="row">1110</td><td>ER_FIELD_SPECIFIED_TWICE</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1112</td><td>ER_UNSUPPORTED_EXTENSION</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1113</td><td>ER_TABLE_MUST_HAVE_COLUMNS</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1115</td><td>ER_UNKNOWN_CHARACTER_SET</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1118</td><td>ER_TOO_BIG_ROWSIZE</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1120</td><td>ER_WRONG_OUTER_JOIN</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1121</td><td>ER_NULL_COLUMN_IN_INDEX</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1129</td><td>ER_HOST_IS_BLOCKED</td><td>08004</td><td>HY000</td></tr><tr><td scope="row">1130</td><td>ER_HOST_NOT_PRIVILEGED</td><td>08004</td><td>HY000</td></tr><tr><td scope="row">1131</td><td>ER_PASSWORD_ANONYMOUS_USER</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1132</td><td>ER_PASSWORD_NOT_ALLOWED</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1133</td><td>ER_PASSWORD_NO_MATCH</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1136</td><td>ER_WRONG_VALUE_COUNT_ON_ROW</td><td>S1000</td><td>21S01</td></tr><tr><td scope="row">1138</td><td>ER_INVALID_USE_OF_NULL</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1139</td><td>ER_REGEXP_ERROR</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1140</td><td>ER_MIX_OF_GROUP_FUNC_AND_FIELDS</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1141</td><td>ER_NONEXISTING_GRANT</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1142</td><td>ER_TABLEACCESS_DENIED_ERROR</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1143</td><td>ER_COLUMNACCESS_DENIED_ERROR</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1144</td><td>ER_ILLEGAL_GRANT_FOR_TABLE</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1145</td><td>ER_GRANT_WRONG_HOST_OR_USER</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1146</td><td>ER_NO_SUCH_TABLE</td><td>S1000</td><td>42S02</td></tr><tr><td scope="row">1147</td><td>ER_NONEXISTING_TABLE_GRANT</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1148</td><td>ER_NOT_ALLOWED_COMMAND</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1149</td><td>ER_SYNTAX_ERROR</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1152</td><td>ER_ABORTING_CONNECTION</td><td>S1000</td><td>08S01</td></tr><tr><td scope="row">1153</td><td>ER_NET_PACKET_TOO_LARGE</td><td>S1000</td><td>08S01</td></tr><tr><td scope="row">1154</td><td>ER_NET_READ_ERROR_FROM_PIPE</td><td>S1000</td><td>08S01</td></tr><tr><td scope="row">1155</td><td>ER_NET_FCNTL_ERROR</td><td>S1000</td><td>08S01</td></tr><tr><td scope="row">1156</td><td>ER_NET_PACKETS_OUT_OF_ORDER</td><td>S1000</td><td>08S01</td></tr><tr><td scope="row">1157</td><td>ER_NET_UNCOMPRESS_ERROR</td><td>S1000</td><td>08S01</td></tr><tr><td scope="row">1158</td><td>ER_NET_READ_ERROR</td><td>S1000</td><td>08S01</td></tr><tr><td scope="row">1159</td><td>ER_NET_READ_INTERRUPTED</td><td>S1000</td><td>08S01</td></tr><tr><td scope="row">1160</td><td>ER_NET_ERROR_ON_WRITE</td><td>S1000</td><td>08S01</td></tr><tr><td scope="row">1161</td><td>ER_NET_WRITE_INTERRUPTED</td><td>S1000</td><td>08S01</td></tr><tr><td scope="row">1162</td><td>ER_TOO_LONG_STRING</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1163</td><td>ER_TABLE_CANT_HANDLE_BLOB</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1164</td><td>ER_TABLE_CANT_HANDLE_AUTO_INCREMENT</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1166</td><td>ER_WRONG_COLUMN_NAME</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1167</td><td>ER_WRONG_KEY_COLUMN</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1169</td><td>ER_DUP_UNIQUE</td><td>S1000</td><td>23000</td></tr><tr><td scope="row">1170</td><td>ER_BLOB_KEY_WITHOUT_LENGTH</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1171</td><td>ER_PRIMARY_CANT_HAVE_NULL</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1172</td><td>ER_TOO_MANY_ROWS</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1173</td><td>ER_REQUIRES_PRIMARY_KEY</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1177</td><td>ER_CHECK_NO_SUCH_TABLE</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1178</td><td>ER_CHECK_NOT_IMPLEMENTED</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1179</td><td>ER_CANT_DO_THIS_DURING_AN_TRANSACTION</td><td>S1000</td><td>25000</td></tr><tr><td scope="row">1184</td><td>ER_NEW_ABORTING_CONNECTION</td><td>S1000</td><td>08S01</td></tr><tr><td scope="row">1189</td><td>ER_MASTER_NET_READ</td><td>S1000</td><td>08S01</td></tr><tr><td scope="row">1190</td><td>ER_MASTER_NET_WRITE</td><td>S1000</td><td>08S01</td></tr><tr><td scope="row">1203</td><td>ER_TOO_MANY_USER_CONNECTIONS</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1205</td><td>ER_LOCK_WAIT_TIMEOUT</td><td>41000</td><td>41000</td></tr><tr><td scope="row">1207</td><td>ER_READ_ONLY_TRANSACTION</td><td>S1000</td><td>25000</td></tr><tr><td scope="row">1211</td><td>ER_NO_PERMISSION_TO_CREATE_USER</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1213</td><td>ER_LOCK_DEADLOCK</td><td>41000</td><td>40001</td></tr><tr><td scope="row">1216</td><td>ER_NO_REFERENCED_ROW</td><td>S1000</td><td>23000</td></tr><tr><td scope="row">1217</td><td>ER_ROW_IS_REFERENCED</td><td>S1000</td><td>23000</td></tr><tr><td scope="row">1218</td><td>ER_CONNECT_TO_MASTER</td><td>S1000</td><td>08S01</td></tr><tr><td scope="row">1222</td><td>ER_WRONG_NUMBER_OF_COLUMNS_IN_SELECT</td><td>S1000</td><td>21000</td></tr><tr><td scope="row">1226</td><td>ER_USER_LIMIT_REACHED</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1230</td><td>ER_NO_DEFAULT</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1231</td><td>ER_WRONG_VALUE_FOR_VAR</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1232</td><td>ER_WRONG_TYPE_FOR_VAR</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1234</td><td>ER_CANT_USE_OPTION_HERE</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1235</td><td>ER_NOT_SUPPORTED_YET</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1239</td><td>ER_WRONG_FK_DEF</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1241</td><td>ER_OPERAND_COLUMNS</td><td>S1000</td><td>21000</td></tr><tr><td scope="row">1242</td><td>ER_SUBQUERY_NO_1_ROW</td><td>S1000</td><td>21000</td></tr><tr><td scope="row">1247</td><td>ER_ILLEGAL_REFERENCE</td><td>S1000</td><td>42S22</td></tr><tr><td scope="row">1248</td><td>ER_DERIVED_MUST_HAVE_ALIAS</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1249</td><td>ER_SELECT_REDUCED</td><td>S1000</td><td>01000</td></tr><tr><td scope="row">1250</td><td>ER_TABLENAME_NOT_ALLOWED_HERE</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1251</td><td>ER_NOT_SUPPORTED_AUTH_MODE</td><td>S1000</td><td>08004</td></tr><tr><td scope="row">1252</td><td>ER_SPATIAL_CANT_HAVE_NULL</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1253</td><td>ER_COLLATION_CHARSET_MISMATCH</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1261</td><td>ER_WARN_TOO_FEW_RECORDS</td><td>S1000</td><td>01000</td></tr><tr><td scope="row">1262</td><td>ER_WARN_TOO_MANY_RECORDS</td><td>S1000</td><td>01000</td></tr><tr><td scope="row">1263</td><td>ER_WARN_NULL_TO_NOTNULL</td><td>S1000</td><td>01000</td></tr><tr><td scope="row">1264</td><td>ER_WARN_DATA_OUT_OF_RANGE</td><td>S1000</td><td>01000</td></tr><tr><td scope="row">1265</td><td>ER_WARN_DATA_TRUNCATED</td><td>S1000</td><td>01000</td></tr><tr><td scope="row">1280</td><td>ER_WRONG_NAME_FOR_INDEX</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1281</td><td>ER_WRONG_NAME_FOR_CATALOG</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1286</td><td>ER_UNKNOWN_STORAGE_ENGINE</td><td>S1000</td><td>42000</td></tr></tbody></table></div></div><br class="table-break"></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-basic"></a>Chapter 6. JDBC Concepts</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-usagenotes-connect-drivermanager">6.1. Connecting to MySQL Using the JDBC <code class="literal">DriverManager</code>
Interface</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-statements">6.2. Using JDBC <code class="literal">Statement</code> Objects to Execute SQL</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-statements-callable">6.3. Using JDBC <code class="literal">CallableStatements</code> to Execute Stored
Procedures</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-last-insert-id">6.4. Retrieving <code class="literal">AUTO_INCREMENT</code> Column Values through JDBC</a></span></dt></dl></div><a class="indexterm" name="idm47020250664144"></a><p>
This section provides some general JDBC background.
</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-connect-drivermanager"></a>6.1. Connecting to MySQL Using the JDBC <code class="literal">DriverManager</code>
Interface</h2></div></div></div><p>
When you are using JDBC outside of an application server, the
<code class="literal">DriverManager</code> class manages the establishment
of Connections.
</p><p>
Specify to the <code class="literal">DriverManager</code> which JDBC
drivers to try to make Connections with. The easiest way to do
this is to use <code class="literal">Class.forName()</code> on the class
that implements the <code class="literal">java.sql.Driver</code>
interface. With MySQL Connector/J, the name of this class is
<code class="literal">com.mysql.jdbc.Driver</code>. 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.
</p><p>
The following section of Java code shows how you might register
MySQL Connector/J from the <code class="function">main()</code> method of
your application. If testing this code, first read the
installation section at
<a class="xref" href="#connector-j-installing" title="Chapter 3. Connector/J Installation">Chapter 3, <i>Connector/J Installation</i></a>, to make sure you have
connector installed correctly and the
<code class="literal">CLASSPATH</code> set up. Also, ensure that MySQL is
configured to accept external TCP/IP connections.
</p><pre class="programlisting">
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
// Notice, do not import com.mysql.jdbc.*
// or you will have problems!
public class LoadDriver {
public static void main(String[] args) {
try {
// The newInstance() call is a work around for some
// broken Java implementations
Class.forName("com.mysql.jdbc.Driver").newInstance();
} catch (Exception ex) {
// handle the error
}
}
}
</pre><p>
After the driver has been registered with the
<code class="literal">DriverManager</code>, you can obtain a
<code class="literal">Connection</code> instance that is connected to a
particular database by calling
<code class="literal">DriverManager.getConnection()</code>:
</p><div class="example"><a name="connector-j-examples-connection-drivermanager"></a><p class="title"><b>Example 6.1. Connector/J: Obtaining a connection from the
<code class="literal">DriverManager</code></b></p><div class="example-contents"><p>
If you have not already done so, please review the section
<a class="xref" href="#connector-j-usagenotes-connect-drivermanager" title="6.1. Connecting to MySQL Using the JDBC DriverManager Interface">Section 6.1, “Connecting to MySQL Using the JDBC <code class="literal">DriverManager</code>
Interface”</a>
before working with these examples.
</p><p>
This example shows how you can obtain a
<code class="literal">Connection</code> instance from the
<code class="literal">DriverManager</code>. There are a few different
signatures for the <code class="function">getConnection()</code>
method. Consult the API documentation that comes with your JDK
for more specific information on how to use them.
</p><pre class="programlisting">
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
Connection conn = null;
...
try {
conn =
DriverManager.getConnection("jdbc:mysql://localhost/test?" +
"user=monty&password=greatsqldb");
// Do something with the Connection
...
} catch (SQLException ex) {
// handle any errors
System.out.println("SQLException: " + ex.getMessage());
System.out.println("SQLState: " + ex.getSQLState());
System.out.println("VendorError: " + ex.getErrorCode());
}
</pre><p>
Once a <code class="classname">Connection</code> is established, it
can be used to create <code class="classname">Statement</code> and
<code class="classname">PreparedStatement</code> objects, as well as
retrieve metadata about the database. This is explained in the
following sections.
</p></div></div><br class="example-break"></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-statements"></a>6.2. Using JDBC <code class="literal">Statement</code> Objects to Execute SQL</h2></div></div></div><p>
<code class="classname">Statement</code> objects allow you to execute
basic SQL queries and retrieve the results through the
<code class="literal">ResultSet</code> class, which is described later.
</p><p>
To create a <code class="classname">Statement</code> instance, you call
the <code class="function">createStatement()</code> method on the
<code class="literal">Connection</code> object you have retrieved using
one of the <code class="literal">DriverManager.getConnection()</code> or
<code class="literal">DataSource.getConnection()</code> methods described
earlier.
</p><p>
Once you have a <code class="classname">Statement</code> instance, you
can execute a <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/select.html" target="_top"><code class="literal">SELECT</code></a> query by
calling the <code class="function">executeQuery(String)</code> method
with the SQL you want to use.
</p><p>
To update data in the database, use the
<code class="function">executeUpdate(String SQL)</code> method. This
method returns the number of rows matched by the update
statement, not the number of rows that were modified.
</p><p>
If you do not know ahead of time whether the SQL statement will
be a <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/select.html" target="_top"><code class="literal">SELECT</code></a> or an
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/update.html" target="_top"><code class="literal">UPDATE</code></a>/<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/insert.html" target="_top"><code class="literal">INSERT</code></a>,
then you can use the <code class="function">execute(String SQL)</code>
method. This method will return true if the SQL query was a
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/select.html" target="_top"><code class="literal">SELECT</code></a>, or false if it was an
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/update.html" target="_top"><code class="literal">UPDATE</code></a>,
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/insert.html" target="_top"><code class="literal">INSERT</code></a>, or
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/delete.html" target="_top"><code class="literal">DELETE</code></a> statement. If the
statement was a <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/select.html" target="_top"><code class="literal">SELECT</code></a> query, you
can retrieve the results by calling the
<code class="function">getResultSet()</code> method. If the statement was
an <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/update.html" target="_top"><code class="literal">UPDATE</code></a>,
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/insert.html" target="_top"><code class="literal">INSERT</code></a>, or
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/delete.html" target="_top"><code class="literal">DELETE</code></a> statement, you can
retrieve the affected rows count by calling
<code class="function">getUpdateCount()</code> on the
<code class="classname">Statement</code> instance.
</p><div class="example"><a name="connector-j-examples-execute-select"></a><p class="title"><b>Example 6.2. Connector/J: Using java.sql.Statement to execute a
<code class="literal">SELECT</code> query</b></p><div class="example-contents"><pre class="programlisting">
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.sql.Statement;
import java.sql.ResultSet;
// assume that conn is an already created JDBC connection (see previous examples)
Statement stmt = null;
ResultSet rs = null;
try {
stmt = conn.createStatement();
rs = stmt.executeQuery("SELECT foo FROM bar");
// or alternatively, if you don't know ahead of time that
// the query will be a SELECT...
if (stmt.execute("SELECT foo FROM bar")) {
rs = stmt.getResultSet();
}
// Now do something with the ResultSet ....
}
catch (SQLException ex){
// handle any errors
System.out.println("SQLException: " + ex.getMessage());
System.out.println("SQLState: " + ex.getSQLState());
System.out.println("VendorError: " + ex.getErrorCode());
}
finally {
// it is a good idea to release
// resources in a finally{} block
// in reverse-order of their creation
// if they are no-longer needed
if (rs != null) {
try {
rs.close();
} catch (SQLException sqlEx) { } // ignore
rs = null;
}
if (stmt != null) {
try {
stmt.close();
} catch (SQLException sqlEx) { } // ignore
stmt = null;
}
}
</pre></div></div><br class="example-break"></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-statements-callable"></a>6.3. Using JDBC <code class="literal">CallableStatements</code> to Execute Stored
Procedures</h2></div></div></div><p>
Starting with MySQL server version 5.0 when used with
Connector/J 3.1.1 or newer, the
<code class="classname">java.sql.CallableStatement</code> interface is
fully implemented with the exception of the
<code class="function">getParameterMetaData()</code> method.
</p><p>
For more information on MySQL stored procedures, please refer to
<a class="ulink" href="http://dev.mysql.com/doc/mysql/en/stored-routines.html" target="_top">http://dev.mysql.com/doc/mysql/en/stored-routines.html</a>.
</p><p>
Connector/J exposes stored procedure functionality through
JDBC's <code class="classname">CallableStatement</code> interface.
</p><div xmlns="http://www.w3.org/1999/xhtml" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p xmlns="">
Current versions of MySQL server do not return enough
information for the JDBC driver to provide result set metadata
for callable statements. This means that when using
<code class="literal">CallableStatement</code>,
<code class="literal">ResultSetMetaData</code> may return
<code class="literal">NULL</code>.
</p></div><p>
The following example shows a stored procedure that returns the
value of <code class="varname">inOutParam</code> incremented by 1, and the
string passed in using <code class="varname">inputParam</code> as a
<code class="classname">ResultSet</code>:
</p><div class="example"><a name="connector-j-examples-stored-procedure"></a><p class="title"><b>Example 6.3. Connector/J: Calling Stored Procedures</b></p><div class="example-contents"><pre class="programlisting">
CREATE PROCEDURE demoSp(IN inputParam VARCHAR(255), \
INOUT inOutParam INT)
BEGIN
DECLARE z INT;
SET z = inOutParam + 1;
SET inOutParam = z;
SELECT inputParam;
SELECT CONCAT('zyxw', inputParam);
END
</pre></div></div><p><br class="example-break">
</p><p>
To use the <code class="literal">demoSp</code> procedure with Connector/J,
follow these steps:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Prepare the callable statement by using
<code class="literal">Connection.prepareCall()</code>.
</p><p>
Notice that you have to use JDBC escape syntax, and that the
parentheses surrounding the parameter placeholders are not
optional:
</p><div class="example"><a name="connector-j-examples-preparecall"></a><p class="title"><b>Example 6.4. Connector/J: Using <code class="literal">Connection.prepareCall()</code></b></p><div class="example-contents"><pre class="programlisting">
import java.sql.CallableStatement;
...
//
// Prepare a call to the stored procedure 'demoSp'
// with two parameters
//
// Notice the use of JDBC-escape syntax ({call ...})
//
CallableStatement cStmt = conn.prepareCall("{call demoSp(?, ?)}");
cStmt.setString(1, "abcdefg");
</pre></div></div><br class="example-break"><div xmlns="http://www.w3.org/1999/xhtml" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p xmlns="">
<code class="literal">Connection.prepareCall()</code> is an
expensive method, due to the metadata retrieval that the
driver performs to support output parameters. For
performance reasons, minimize unnecessary calls to
<code class="literal">Connection.prepareCall()</code> by reusing
<code class="classname">CallableStatement</code> instances in your
code.
</p></div></li><li class="listitem"><p>
Register the output parameters (if any exist)
</p><p>
To retrieve the values of output parameters (parameters
specified as <code class="literal">OUT</code> or
<code class="literal">INOUT</code> when you created the stored
procedure), JDBC requires that they be specified before
statement execution using the various
<code class="function">registerOutputParameter()</code> methods in
the <code class="classname">CallableStatement</code> interface:
</p><div class="example"><a name="connector-j-examples-output-param"></a><p class="title"><b>Example 6.5. Connector/J: Registering output parameters</b></p><div class="example-contents"><pre class="programlisting">
import java.sql.Types;
...
//
// Connector/J supports both named and indexed
// output parameters. You can register output
// parameters using either method, as well
// as retrieve output parameters using either
// method, regardless of what method was
// used to register them.
//
// The following examples show how to use
// the various methods of registering
// output parameters (you should of course
// use only one registration per parameter).
//
//
// Registers the second parameter as output, and
// uses the type 'INTEGER' for values returned from
// getObject()
//
cStmt.registerOutParameter(2, Types.INTEGER);
//
// Registers the named parameter 'inOutParam', and
// uses the type 'INTEGER' for values returned from
// getObject()
//
cStmt.registerOutParameter("inOutParam", Types.INTEGER);
...
</pre></div></div><p><br class="example-break">
</p></li><li class="listitem"><p>
Set the input parameters (if any exist)
</p><p>
Input and in/out parameters are set as for
<code class="classname">PreparedStatement</code> objects. However,
<code class="classname">CallableStatement</code> also supports
setting parameters by name:
</p><div class="example"><a name="connector-j-examples-callablestatement"></a><p class="title"><b>Example 6.6. Connector/J: Setting <code class="literal">CallableStatement</code> input
parameters</b></p><div class="example-contents"><pre class="programlisting">
...
//
// Set a parameter by index
//
cStmt.setString(1, "abcdefg");
//
// Alternatively, set a parameter using
// the parameter name
//
cStmt.setString("inputParameter", "abcdefg");
//
// Set the 'in/out' parameter using an index
//
cStmt.setInt(2, 1);
//
// Alternatively, set the 'in/out' parameter
// by name
//
cStmt.setInt("inOutParam", 1);
...
</pre></div></div><p><br class="example-break">
</p></li><li class="listitem"><p>
Execute the <code class="classname">CallableStatement</code>, and
retrieve any result sets or output parameters.
</p><p>
Although <code class="classname">CallableStatement</code> supports
calling any of the <code class="classname">Statement</code> execute
methods (<code class="function">executeUpdate()</code>,
<code class="function">executeQuery()</code> or
<code class="function">execute()</code>), the most flexible method to
call is <code class="function">execute()</code>, as you do not need
to know ahead of time if the stored procedure returns result
sets:
</p><div class="example"><a name="connector-j-examples-retrieving-results-params"></a><p class="title"><b>Example 6.7. Connector/J: Retrieving results and output parameter values</b></p><div class="example-contents"><pre class="programlisting">
...
boolean hadResults = cStmt.execute();
//
// Process all returned result sets
//
while (hadResults) {
ResultSet rs = cStmt.getResultSet();
// process result set
...
hadResults = cStmt.getMoreResults();
}
//
// Retrieve output parameters
//
// Connector/J supports both index-based and
// name-based retrieval
//
int outputValue = cStmt.getInt(2); // index-based
outputValue = cStmt.getInt("inOutParam"); // name-based
...
</pre></div></div><p><br class="example-break">
</p></li></ol></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-last-insert-id"></a>6.4. Retrieving <code class="literal">AUTO_INCREMENT</code> Column Values through JDBC</h2></div></div></div><p>
Before version 3.0 of the JDBC API, there was no standard way of
retrieving key values from databases that supported auto
increment or identity columns. With older JDBC drivers for
MySQL, you could always use a MySQL-specific method on the
<code class="classname">Statement</code> interface, or issue the query
<code class="literal">SELECT LAST_INSERT_ID()</code> after issuing an
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/insert.html" target="_top"><code class="literal">INSERT</code></a> to a table that had an
<code class="literal">AUTO_INCREMENT</code> key. Using the MySQL-specific
method call isn't portable, and issuing a
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/select.html" target="_top"><code class="literal">SELECT</code></a> to get the
<code class="literal">AUTO_INCREMENT</code> 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 <code class="literal">AUTO_INCREMENT</code>
values. First, we demonstrate the use of the new JDBC 3.0 method
<code class="function">getGeneratedKeys()</code> which is now the
preferred method to use if you need to retrieve
<code class="literal">AUTO_INCREMENT</code> keys and have access to JDBC
3.0. The second example shows how you can retrieve the same
value using a standard <code class="literal">SELECT
LAST_INSERT_ID()</code> query. The final example shows how
updatable result sets can retrieve the
<code class="literal">AUTO_INCREMENT</code> value when using the
<code class="function">insertRow()</code> method.
</p><div class="example"><a name="connector-j-examples-autoincrement-getgeneratedkeys"></a><p class="title"><b>Example 6.8. Connector/J: Retrieving <code class="literal">AUTO_INCREMENT</code> column values
using <code class="literal">Statement.getGeneratedKeys()</code></b></p><div class="example-contents"><pre class="programlisting">
Statement stmt = null;
ResultSet rs = null;
try {
//
// Create a Statement instance that we can use for
// 'normal' result sets assuming you have a
// Connection 'conn' to a MySQL database already
// available
stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY,
java.sql.ResultSet.CONCUR_UPDATABLE);
//
// Issue the DDL queries for the table for this example
//
stmt.executeUpdate("DROP TABLE IF EXISTS autoIncTutorial");
stmt.executeUpdate(
"CREATE TABLE autoIncTutorial ("
+ "priKey INT NOT NULL AUTO_INCREMENT, "
+ "dataField VARCHAR(64), PRIMARY KEY (priKey))");
//
// Insert one row that will generate an AUTO INCREMENT
// key in the 'priKey' field
//
stmt.executeUpdate(
"INSERT INTO autoIncTutorial (dataField) "
+ "values ('Can I Get the Auto Increment Field?')",
Statement.RETURN_GENERATED_KEYS);
//
// Example of using Statement.getGeneratedKeys()
// to retrieve the value of an auto-increment
// value
//
int autoIncKeyFromApi = -1;
rs = stmt.getGeneratedKeys();
if (rs.next()) {
autoIncKeyFromApi = rs.getInt(1);
} else {
// throw an exception from here
}
rs.close();
rs = null;
System.out.println("Key returned from getGeneratedKeys():"
+ autoIncKeyFromApi);
} finally {
if (rs != null) {
try {
rs.close();
} catch (SQLException ex) {
// ignore
}
}
if (stmt != null) {
try {
stmt.close();
} catch (SQLException ex) {
// ignore
}
}
}
</pre></div></div><br class="example-break"><div class="example"><a name="connector-j-examples-autoincrement-select"></a><p class="title"><b>Example 6.9. Connector/J: Retrieving <code class="literal">AUTO_INCREMENT</code> column values
using <code class="literal">SELECT LAST_INSERT_ID()</code></b></p><div class="example-contents"><pre class="programlisting">
Statement stmt = null;
ResultSet rs = null;
try {
//
// Create a Statement instance that we can use for
// 'normal' result sets.
stmt = conn.createStatement();
//
// Issue the DDL queries for the table for this example
//
stmt.executeUpdate("DROP TABLE IF EXISTS autoIncTutorial");
stmt.executeUpdate(
"CREATE TABLE autoIncTutorial ("
+ "priKey INT NOT NULL AUTO_INCREMENT, "
+ "dataField VARCHAR(64), PRIMARY KEY (priKey))");
//
// Insert one row that will generate an AUTO INCREMENT
// key in the 'priKey' field
//
stmt.executeUpdate(
"INSERT INTO autoIncTutorial (dataField) "
+ "values ('Can I Get the Auto Increment Field?')");
//
// Use the MySQL LAST_INSERT_ID()
// function to do the same thing as getGeneratedKeys()
//
int autoIncKeyFromFunc = -1;
rs = stmt.executeQuery("SELECT LAST_INSERT_ID()");
if (rs.next()) {
autoIncKeyFromFunc = rs.getInt(1);
} else {
// throw an exception from here
}
rs.close();
System.out.println("Key returned from " +
"'SELECT LAST_INSERT_ID()': " +
autoIncKeyFromFunc);
} finally {
if (rs != null) {
try {
rs.close();
} catch (SQLException ex) {
// ignore
}
}
if (stmt != null) {
try {
stmt.close();
} catch (SQLException ex) {
// ignore
}
}
}
</pre></div></div><br class="example-break"><div class="example"><a name="connector-j-examples-autoincrement-updateable-resultsets"></a><p class="title"><b>Example 6.10. Connector/J: Retrieving <code class="literal">AUTO_INCREMENT</code> column values
in <code class="literal">Updatable ResultSets</code></b></p><div class="example-contents"><pre class="programlisting">
Statement stmt = null;
ResultSet rs = null;
try {
//
// Create a Statement instance that we can use for
// 'normal' result sets as well as an 'updatable'
// one, assuming you have a Connection 'conn' to
// a MySQL database already available
//
stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY,
java.sql.ResultSet.CONCUR_UPDATABLE);
//
// Issue the DDL queries for the table for this example
//
stmt.executeUpdate("DROP TABLE IF EXISTS autoIncTutorial");
stmt.executeUpdate(
"CREATE TABLE autoIncTutorial ("
+ "priKey INT NOT NULL AUTO_INCREMENT, "
+ "dataField VARCHAR(64), PRIMARY KEY (priKey))");
//
// Example of retrieving an AUTO INCREMENT key
// from an updatable result set
//
rs = stmt.executeQuery("SELECT priKey, dataField "
+ "FROM autoIncTutorial");
rs.moveToInsertRow();
rs.updateString("dataField", "AUTO INCREMENT here?");
rs.insertRow();
//
// the driver adds rows at the end
//
rs.last();
//
// We should now be on the row we just inserted
//
int autoIncKeyFromRS = rs.getInt("priKey");
rs.close();
rs = null;
System.out.println("Key returned for inserted row: "
+ autoIncKeyFromRS);
} finally {
if (rs != null) {
try {
rs.close();
} catch (SQLException ex) {
// ignore
}
}
if (stmt != null) {
try {
stmt.close();
} catch (SQLException ex) {
// ignore
}
}
}
</pre></div></div><br class="example-break"><p>
Running the preceding example code should produce the following
output:
</p><pre class="programlisting">
Key returned from getGeneratedKeys(): 1
Key returned from SELECT LAST_INSERT_ID(): 1
Key returned for inserted row: 2
</pre><p>
At times, it can be tricky to use the <code class="literal">SELECT
LAST_INSERT_ID()</code> query, as that function's value is
scoped to a connection. So, if some other query happens on the
same connection, the value is overwritten. On the other hand,
the <code class="function">getGeneratedKeys()</code> method is scoped by
the <code class="classname">Statement</code> instance, so it can be used
even if other queries happen on the same connection, but not on
the same <code class="classname">Statement</code> instance.
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-j2ee-concepts-connection-pooling"></a>Chapter 7. Connection Pooling with Connector/J</h1></div></div></div><a class="indexterm" name="idm47020250554640"></a><a class="indexterm" name="idm47020250553424"></a><p>
Connection pooling is a technique of creating and managing a pool
of connections that are ready for use by any
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/glossary.html#glos_thread" target="_top">thread</a> that needs them.
Connection pooling can greatly increase the performance of your
Java application, while reducing overall resource usage.
</p><h2><a name="idm47020250551184"></a>
How Connection Pooling Works
</h2><p>
Most applications only need a thread to have access to a JDBC
connection when they are actively processing a
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/glossary.html#glos_transaction" target="_top">transaction</a>, which often
takes only milliseconds to complete. When not processing a
transaction, the connection sits idle. Connection pooling enables
the idle connection to be used by some other thread to do useful
work.
</p><p>
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 can be used by any other threads.
</p><p>
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
<code class="literal">DriverManager.getConnection()</code> every time it
needed a JDBC connection. With connection pooling, your thread may
end up using either a new connection or an already-existing
connection.
</p><h2><a name="idm47020250547296"></a>
Benefits of Connection Pooling
</h2><p>
The main benefits to connection pooling are:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Reduced connection creation time.
</p><p>
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.
</p></li><li class="listitem"><p>
Simplified programming model.
</p><p>
When using connection pooling, each individual thread can act
as though it has created its own JDBC connection, allowing you
to use straightforward JDBC programming techniques.
</p></li><li class="listitem"><p>
Controlled resource usage.
</p><p>
If you create a new connection every time a thread needs one,
rather than using connection pooling, your application's
resource usage can be wasteful and lead to unpredictable
behavior under load.
</p></li></ul></div><h2><a name="idm47020250541536"></a>
Using Connection Pooling with Connector/J
</h2><p>
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
with MySQL Connector/J.
</p><p>
Generally, you configure a connection pool in your application
server configuration files, and access it through 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:
</p><div class="example"><a name="connector-j-examples-connectionpool-j2ee"></a><p class="title"><b>Example 7.1. Connector/J: Using a connection pool with a J2EE application server</b></p><div class="example-contents"><pre class="programlisting">
import java.sql.Connection;
import java.sql.SQLException;
import java.sql.Statement;
import javax.naming.InitialContext;
import javax.sql.DataSource;
public class MyServletJspOrEjb {
public void doSomething() throws Exception {
/*
* Create a JNDI Initial context to be able to
* lookup the DataSource
*
* In production-level code, this should be cached as
* an instance or static variable, as it can
* be quite expensive to create a JNDI context.
*
* Note: This code only works when you are using servlets
* or EJBs in a J2EE application server. If you are
* using connection pooling in standalone Java code, you
* will have to create/configure datasources using whatever
* mechanisms your particular connection pooling library
* provides.
*/
InitialContext ctx = new InitialContext();
/*
* Lookup the DataSource, which will be backed by a pool
* that the application server provides. DataSource instances
* are also a good candidate for caching as an instance
* variable, as JNDI lookups can be expensive as well.
*/
DataSource ds =
(DataSource)ctx.lookup("java:comp/env/jdbc/MySQLDB");
/*
* The following code is what would actually be in your
* Servlet, JSP or EJB 'service' method...where you need
* to work with a JDBC connection.
*/
Connection conn = null;
Statement stmt = null;
try {
conn = ds.getConnection();
/*
* Now, use normal JDBC programming to work with
* MySQL, making sure to close each resource when you're
* finished with it, which permits the connection pool
* resources to be recovered as quickly as possible
*/
stmt = conn.createStatement();
stmt.execute("SOME SQL QUERY");
stmt.close();
stmt = null;
conn.close();
conn = null;
} finally {
/*
* close any jdbc instances here that weren't
* explicitly closed during normal code path, so
* that we don't 'leak' resources...
*/
if (stmt != null) {
try {
stmt.close();
} catch (sqlexception sqlex) {
// ignore, as we can't do anything about it here
}
stmt = null;
}
if (conn != null) {
try {
conn.close();
} catch (sqlexception sqlex) {
// ignore, as we can't do anything about it here
}
conn = null;
}
}
}
}
</pre></div></div><p><br class="example-break">
As shown in the example above, after obtaining the JNDI
<code class="literal">InitialContext</code>, and looking up the
<code class="literal">DataSource</code>, the rest of the code follows
familiar JDBC conventions.
</p><p>
When using connection pooling, always make sure that connections,
and anything created by them (such as statements or result sets)
are closed. This rule applies no matter what happens in your code
(exceptions, flow-of-control, and so forth). When these objects
are closed, they can be re-used; otherwise, they will be stranded,
which means that the MySQL server resources they represent (such
as buffers, locks, or sockets) are tied up for some time, or in
the worst case can be tied up forever.
</p><h2><a name="idm47020250530416"></a>
Sizing the Connection Pool
</h2><p>
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! 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.
</p><p>
The optimal size for the connection pool depends on anticipated
load and average database transaction time. In practice, the
optimal connection pool size can be 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
acceptable response times.
</p><p>
To correctly size a connection pool for your application, create
load test scripts with tools such as Apache JMeter or The Grinder,
and load test your application.
</p><p>
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.
</p><h2><a name="idm47020250526736"></a>
Validating Connections
</h2><p>
MySQL Connector/J can validate the connection by executing a
lightweight ping against a server. In the case of load-balanced
connections, this is performed against all active pooled internal
connections that are retained. This is beneficial to Java
applications using connection pools, as the pool can use this
feature to validate connections. Depending on your connection pool
and configuration, this validation can be carried out at different
times:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Before the pool returns a connection to the application.
</p></li><li class="listitem"><p>
When the application returns a connection to the pool.
</p></li><li class="listitem"><p>
During periodic checks of idle connections.
</p></li></ol></div><p>
To use this feature, specify a validation query in your connection
pool that starts with <code class="literal">/* ping */</code>. Note that the
syntax must be exactly as specified. This will cause the driver
send a ping to the server and return a dummy lightweight result
set. When using a <code class="literal">ReplicationConnection</code> or
<code class="literal">LoadBalancedConnection</code>, the ping will be sent
across all active connections.
</p><p>
It is critical that the syntax be specified correctly. The syntax
needs to be exact for reasons of efficiency, as this test is done
for every statement that is executed:
</p><pre class="programlisting">
protected static final String PING_MARKER = "/* ping */";
...
if (sql.charAt(0) == '/') {
if (sql.startsWith(PING_MARKER)) {
doPingInstead();
...
</pre><p>
None of the following snippets will work, because the ping syntax
is sensitive to whitespace, capitalization, and placement:
</p><pre class="programlisting">
sql = "/* PING */ SELECT 1";
sql = "SELECT 1 /* ping*/";
sql = "/*ping*/ SELECT 1";
sql = " /* ping */ SELECT 1";
sql = "/*to ping or not to ping*/ SELECT 1";
</pre><p>
All of the previous statements will issue a normal
<code class="literal">SELECT</code> statement and will
<span class="bold"><strong>not</strong></span> be transformed into the
lightweight ping. Further, for load-balanced connections, the
statement will be executed against one connection in the internal
pool, rather than validating each underlying physical connection.
This results in the non-active physical connections assuming a
stale state, and they may die. If Connector/J then re-balances, it
might select a dead connection, resulting in an exception being
passed to the application. To help prevent this, you can use
<code class="literal">loadBalanceValidateConnectionOnSwapServer</code> to
validate the connection before use.
</p><p>
If your Connector/J deployment uses a connection pool that allows
you to specify a validation query, take advantage of it, but
ensure that the query starts <span class="emphasis"><em>exactly</em></span> with
<code class="literal">/* ping */</code>. This is particularly important if
you are using the load-balancing or replication-aware features of
Connector/J, as it will help keep alive connections which
otherwise will go stale and die, causing problems later.
</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-multi-host-connections"></a>Chapter 8. Multi-Host Connections</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections">8.1. Configuring Load Balancing with Connector/J</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-j2ee-concepts-load-balancing-failover">8.2. Configuring Failover with Connector/J</a></span></dt><dt><span class="section"><a href="#connector-j-master-slave-replication-connection">8.3. Master/Slave Replication with ReplicationConnection</a></span></dt></dl></div><a class="indexterm" name="idm47020250512224"></a><p>
The following sections discuss a number of topics that involve
multi-host connections, namely: server load-balancing, fail-over,
and replication.
</p><p>
Developers should know the following things about multi-host
connections that are managed through Connector/J:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Each multi-host connection is a wrapper of the underlying
physical connections.
</p></li><li class="listitem"><p>
Each of the underlying physical connections has its own
session. Sessions cannot be tracked, shared, or copied,
given the MySQL architecture.
</p></li><li class="listitem"><p>
Every switch between physical connections means a switch
between sessions.
</p></li><li class="listitem"><p>
Within a transaction boundary, there are no switches between
physical connections. Beyond a transaction boundary, there
is no guarantee that a switch does not occur.
</p><div xmlns="http://www.w3.org/1999/xhtml" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p xmlns="">
If an application reuses session-scope data (for example,
variables, SSPs) beyond a transaction boundary, failures
are possible, as a switch between the physical connections
(which is also a switch between sessions) might occur.
Therefore, the application should re-prepare the session
data and also restart the last transaction in case of an
exception, or it should re-prepare session data for each
new transaction if it does not want to deal with exception
handling.
</p></div></li></ul></div><p>
</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections"></a>8.1. Configuring Load Balancing with Connector/J</h2></div></div></div><a class="indexterm" name="idm47020250503344"></a><a class="indexterm" name="idm47020250502128"></a><p>
Connector/J has long provided an effective means to distribute
read/write load across multiple MySQL server instances for
Cluster or master-master replication deployments. Starting with
Connector/J 5.1.3, you can now dynamically configure
load-balanced connections, with no service outage. In-process
transactions are not lost, and no application exceptions are
generated if any application is trying to use that particular
server instance.
</p><p>
There are two connection string options associated with this
functionality:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">loadBalanceConnectionGroup</code> – This
provides the ability to group connections from different
sources. This allows you to manage these JDBC sources within
a single class loader in any combination you choose. If they
use the same configuration, and you want to manage them as a
logical single group, give them the same name. This is the
key property for management: if you do not define a name
(string) for <code class="literal">loadBalanceConnectionGroup</code>,
you cannot manage the connections. All load-balanced
connections sharing the same
<code class="literal">loadBalanceConnectionGroup</code> value,
regardless of how the application creates them, will be
managed together.
</p></li><li class="listitem"><p>
<code class="literal">loadBalanceEnableJMX</code> – The ability to
manage the connections is exposed when you define a
<code class="literal">loadBalanceConnectionGroup</code>, but if you
want to manage this externally, enable JMX by setting this
property to <code class="literal">true</code>. This enables a JMX
implementation, which exposes the management and monitoring
operations of a connection group. Further, start your
application with the
<code class="literal">-Dcom.sun.management.jmxremote</code> JVM flag.
You can then perform connect and perform operations using a
JMX client such as <code class="literal">jconsole</code>.
</p></li></ul></div><p>
Once a connection has been made using the correct connection
string options, a number of monitoring properties are available:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Current active host count.
</p></li><li class="listitem"><p>
Current active physical connection count.
</p></li><li class="listitem"><p>
Current active logical connection count.
</p></li><li class="listitem"><p>
Total logical connections created.
</p></li><li class="listitem"><p>
Total transaction count.
</p></li></ul></div><p>
The following management operations can also be performed:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Add host.
</p></li><li class="listitem"><p>
Remove host.
</p></li></ul></div><p>
The JMX interface,
<code class="literal">com.mysql.jdbc.jmx.LoadBalanceConnectionGroupManagerMBean</code>,
has the following methods:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">int getActiveHostCount(String group);</code>
</p></li><li class="listitem"><p>
<code class="literal">int getTotalHostCount(String group);</code>
</p></li><li class="listitem"><p>
<code class="literal">long getTotalLogicalConnectionCount(String
group);</code>
</p></li><li class="listitem"><p>
<code class="literal">long getActiveLogicalConnectionCount(String
group);</code>
</p></li><li class="listitem"><p>
<code class="literal">long getActivePhysicalConnectionCount(String
group);</code>
</p></li><li class="listitem"><p>
<code class="literal">long getTotalPhysicalConnectionCount(String
group);</code>
</p></li><li class="listitem"><p>
<code class="literal">long getTotalTransactionCount(String
group);</code>
</p></li><li class="listitem"><p>
<code class="literal">void removeHost(String group, String host) throws
SQLException;</code>
</p></li><li class="listitem"><p>
<code class="literal">void stopNewConnectionsToHost(String group, String
host) throws SQLException;</code>
</p></li><li class="listitem"><p>
<code class="literal">void addHost(String group, String host, boolean
forExisting);</code>
</p></li><li class="listitem"><p>
<code class="literal">String getActiveHostsList(String group);</code>
</p></li><li class="listitem"><p>
<code class="literal">String getRegisteredConnectionGroups();</code>
</p></li></ul></div><p>
The <code class="literal">getRegisteredConnectionGroups()</code> method
returns the names of all connection groups defined in that class
loader.
</p><p>
You can test this setup with the following code:
</p><pre class="programlisting">
public class Test {
private static String URL = "jdbc:mysql:loadbalance://" +
"localhost:3306,localhost:3310/test?" +
"loadBalanceConnectionGroup=first&loadBalanceEnableJMX=true";
public static void main(String[] args) throws Exception {
new Thread(new Repeater()).start();
new Thread(new Repeater()).start();
new Thread(new Repeater()).start();
}
static Connection getNewConnection() throws SQLException, ClassNotFoundException {
Class.forName("com.mysql.jdbc.Driver");
return DriverManager.getConnection(URL, "root", "");
}
static void executeSimpleTransaction(Connection c, int conn, int trans){
try {
c.setAutoCommit(false);
Statement s = c.createStatement();
s.executeQuery("SELECT SLEEP(1) /* Connection: " + conn + ", transaction: " + trans + " */");
c.commit();
} catch (SQLException e) {
e.printStackTrace();
}
}
public static class Repeater implements Runnable {
public void run() {
for(int i=0; i < 100; i++){
try {
Connection c = getNewConnection();
for(int j=0; j < 10; j++){
executeSimpleTransaction(c, i, j);
Thread.sleep(Math.round(100 * Math.random()));
}
c.close();
Thread.sleep(100);
} catch (Exception e) {
e.printStackTrace();
}
}
}
}
}
</pre><p>
After compiling, the application can be started with the
<code class="literal">-Dcom.sun.management.jmxremote</code> flag, to
enable remote management. <code class="literal">jconsole</code> can then
be started. The <code class="literal">Test</code> main class will be
listed by <code class="literal">jconsole</code>. Select this and click
<span class="guibutton">Connect</span>. You can then navigate to the
<code class="literal">com.mysql.jdbc.jmx.LoadBalanceConnectionGroupManager</code>
bean. At this point, you can click on various operations and
examine the returned result.
</p><p>
If you now had an additional instance of MySQL running on port
3309, you could ensure that Connector/J starts using it by using
the <code class="literal">addHost()</code>, which is exposed in
<code class="literal">jconsole</code>. Note that these operations can be
performed dynamically without having to stop the application
running.
</p><p>
For further information on the combination of load balancing and
failover, see
<a class="xref" href="#connector-j-usagenotes-j2ee-concepts-load-balancing-failover" title="8.2. Configuring Failover with Connector/J">Section 8.2, “Configuring Failover with Connector/J”</a>.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-j2ee-concepts-load-balancing-failover"></a>8.2. Configuring Failover with Connector/J</h2></div></div></div><p>
Connector/J provides a useful load-balancing implementation for
Cluster or multi-master deployments, as explained in
<a class="xref" href="#connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections" title="8.1. Configuring Load Balancing with Connector/J">Section 8.1, “Configuring Load Balancing with Connector/J”</a>.
As of Connector/J 5.1.12, this same implementation is used for
balancing load between read-only slaves with
<code class="literal">ReplicationDriver</code>. When trying to balance
workload between multiple servers, the driver has to determine
when it is safe to swap servers, doing so in the middle of a
transaction, for example, could cause problems. It is important
not to lose state information. For this reason, Connector/J will
only try to pick a new server when one of the following happens:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
At transaction boundaries (transactions are explicitly
committed or rolled back).
</p></li><li class="listitem"><p>
A communication exception (SQL State starting with "08") is
encountered.
</p></li><li class="listitem"><p>
When a <code class="literal">SQLException</code> matches conditions
defined by user, using the extension points defined by the
<code class="literal">loadBalanceSQLStateFailover</code>,
<code class="literal">loadBalanceSQLExceptionSubclassFailover</code>
or <code class="literal">loadBalanceExceptionChecker</code>
properties.
</p></li></ol></div><p>
The third condition revolves around three new properties
introduced with Connector/J 5.1.13. It allows you to control
which <code class="literal">SQLException</code>s trigger failover.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">loadBalanceExceptionChecker</code> - The
<code class="literal">loadBalanceExceptionChecker</code> property is
really the key. This takes a fully-qualified class name
which implements the new
<code class="literal">com.mysql.jdbc.LoadBalanceExceptionChecker</code>
interface. This interface is very simple, and you only need
to implement the following method:
</p><pre class="programlisting">
public boolean shouldExceptionTriggerFailover(SQLException ex)
</pre><p>
A <code class="literal">SQLException</code> is passed in, and a
boolean returned. A value of <code class="literal">true</code>
triggers a failover, <code class="literal">false</code> does not.
</p><p>
You can use this to implement your own custom logic. An
example where this might be useful is when dealing with
transient errors when using MySQL Cluster, where certain
buffers may become overloaded. The following code snippet
illustrates this:
</p><pre class="programlisting">
public class NdbLoadBalanceExceptionChecker
extends StandardLoadBalanceExceptionChecker {
public boolean shouldExceptionTriggerFailover(SQLException ex) {
return super.shouldExceptionTriggerFailover(ex)
|| checkNdbException(ex);
}
private boolean checkNdbException(SQLException ex){
// Have to parse the message since most NDB errors
// are mapped to the same DEMC.
return (ex.getMessage().startsWith("Lock wait timeout exceeded") ||
(ex.getMessage().startsWith("Got temporary error")
&& ex.getMessage().endsWith("from NDB")));
}
}
</pre><p>
The code above extends
<code class="literal">com.mysql.jdbc.StandardLoadBalanceExceptionChecker</code>,
which is the default implementation. There are a few
convenient shortcuts built into this, for those who want to
have some level of control using properties, without writing
Java code. This default implementation uses the two
remaining properties:
<code class="literal">loadBalanceSQLStateFailover</code> and
<code class="literal">loadBalanceSQLExceptionSubclassFailover</code>.
</p></li><li class="listitem"><p>
<code class="literal">loadBalanceSQLStateFailover</code> - allows you
to define a comma-delimited list of
<code class="literal">SQLState</code> code prefixes, against which a
<code class="literal">SQLException</code> is compared. If the prefix
matches, failover is triggered. So, for example, the
following would trigger a failover if a given
<code class="literal">SQLException</code> starts with "00", or is
"12345":
</p><pre class="programlisting">
loadBalanceSQLStateFailover=00,12345
</pre></li><li class="listitem"><p>
<code class="literal">loadBalanceSQLExceptionSubclassFailover</code> -
can be used in conjunction with
<code class="literal">loadBalanceSQLStateFailover</code> or on its
own. If you want certain subclasses of
<code class="literal">SQLException</code> to trigger failover, simply
provide a comma-delimited list of fully-qualified class or
interface names to check against. For example, if you want
all <code class="literal">SQLTransientConnectionExceptions</code> to
trigger failover, you would specify:
</p><pre class="programlisting">
loadBalanceSQLExceptionSubclassFailover=java.sql.SQLTransientConnectionException
</pre></li></ul></div><p>
While the three fail-over conditions enumerated earlier suit
most situations, if <code class="literal">autocommit</code> is enabled,
Connector/J never re-balances, and continues using the same
physical connection. This can be problematic, particularly when
load-balancing is being used to distribute read-only load across
multiple slaves. However, Connector/J can be configured to
re-balance after a certain number of statements are executed,
when <code class="literal">autocommit</code> is enabled. This
functionality is dependent upon the following properties:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">loadBalanceAutoCommitStatementThreshold</code>
– defines the number of matching statements which will
trigger the driver to potentially swap physical server
connections. The default value, 0, retains the behavior that
connections with <code class="literal">autocommit</code> enabled are
never balanced.
</p></li><li class="listitem"><p>
<code class="literal">loadBalanceAutoCommitStatementRegex</code> –
the regular expression against which statements must match.
The default value, blank, matches all statements. So, for
example, using the following properties will cause
Connector/J to re-balance after every third statement that
contains the string <span class="quote">“<span class="quote">test</span>”</span>:
</p><pre class="programlisting">
loadBalanceAutoCommitStatementThreshold=3
loadBalanceAutoCommitStatementRegex=.*test.*
</pre><p>
<code class="literal">loadBalanceAutoCommitStatementRegex</code> can
prove useful in a number of situations. Your application may
use temporary tables, server-side session state variables,
or connection state, where letting the driver arbitrarily
swap physical connections before processing is complete
could cause data loss or other problems. This allows you to
identify a trigger statement that is only executed when it
is safe to swap physical connections.
</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-master-slave-replication-connection"></a>8.3. Master/Slave Replication with ReplicationConnection</h2></div></div></div><a class="indexterm" name="idm47020250422944"></a><a class="indexterm" name="idm47020250421728"></a><p>
This section describe a number of features of Connector/J's
support for replication-aware deployments.
</p><h3><a name="idm47020250419504"></a>
Scaling out Read Load by Distributing Read Traffic to Slaves
</h3><p>
Connector/J 3.1.7 and higher includes 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 <code class="literal">Connection.getReadOnly()</code>.
</p><p>
An application signals that it wants a transaction to be
read-only by calling
<code class="literal">Connection.setReadOnly(true)</code>, this
replication-aware connection will use one of the slave
connections, which are load-balanced per-vm using a round-robin
scheme (a given connection is sticky to a slave unless that
slave is removed from service). If you have a write transaction,
or if you have a read that is time-sensitive (remember,
replication in MySQL is asynchronous), set the connection to be
not read-only, by calling
<code class="literal">Connection.setReadOnly(false)</code> and the driver
will ensure that further calls are sent to the master MySQL
server. The driver takes care of propagating the current state
of autocommit, isolation level, and catalog between all of the
connections that it uses to accomplish this load balancing
functionality.
</p><p>
To enable this functionality, use the
<code class="literal">com.mysql.jdbc.ReplicationDriver</code> 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, <code class="literal">ReplicationDriver</code>
does not currently work with
<code class="literal">java.sql.DriverManager</code>-based connection
creation unless it is the only MySQL JDBC driver registered with
the <code class="literal">DriverManager</code> .
</p><p>
Here is a short example of how
<code class="literal">ReplicationDriver</code> might be used in a
standalone application:
</p><a name="connector-j-using-replication-driver-example"></a><pre class="programlisting">
import java.sql.Connection;
import java.sql.ResultSet;
import java.util.Properties;
import com.mysql.jdbc.ReplicationDriver;
public class ReplicationDriverDemo {
public static void main(String[] args) throws Exception {
ReplicationDriver driver = new ReplicationDriver();
Properties props = new Properties();
// We want this for failover on the slaves
props.put("autoReconnect", "true");
// We want to load balance between the slaves
props.put("roundRobinLoadBalance", "true");
props.put("user", "foo");
props.put("password", "bar");
//
// Looks like a normal MySQL JDBC url, with a
// comma-separated list of hosts, the first
// being the 'master', the rest being any number
// of slaves that the driver will load balance against
//
Connection conn =
driver.connect("jdbc:mysql:replication://master,slave1,slave2,slave3/test",
props);
//
// Perform read/write work on the master
// by setting the read-only flag to "false"
//
conn.setReadOnly(false);
conn.setAutoCommit(false);
conn.createStatement().executeUpdate("UPDATE some_table ....");
conn.commit();
//
// Now, do a query from a slave, the driver automatically picks one
// from the list
//
conn.setReadOnly(true);
ResultSet rs =
conn.createStatement().executeQuery("SELECT a,b FROM alt_table");
.......
}
}
</pre><p>
Consider investigating the Load Balancing JDBC Pool
(<span class="command"><strong>lbpool</strong></span>) tool, which provides a wrapper
around the standard JDBC driver and enables you to use DB
connection pools that includes checks for system failures and
uneven load distribution. For more information, see
<a class="ulink" href="http://code.google.com/p/mysql-lbpool/" target="_top">Load
Balancing JDBC Driver for MySQL (mysql-lbpool)</a>.
</p><h3><a name="idm47020250408128"></a>
Support for Multiple-Master Replication Topographies
</h3><p>
Since Connector/J 5.1.27, multi-master replication topographies
are supported. They can be specified using the following host
definition syntax:
</p><pre class="programlisting">address=(host=hostname)(port=3306)(type=[master|slave])</pre><p>
</p><p>
The definition described above assumes that the first (and only
the first) host is the master. Supporting deployments with an
arbitrary number of masters and slaves requires a different URL
syntax for specifying different properties for specific hosts,
which is just an expansion of the legacy URL syntax with the
property <code class="literal">type=[master|slave]</code>; for example:
</p><pre class="programlisting">jdbc:mysql://address=(type=master)(host=master1host),address=(type=master)(host=master2host),address=(type=slave)(host=slave1host)/db</pre><p>
</p><p>
Connector/J uses a load-balanced connection internally for
management of the master connections, which means that
<code class="literal">ReplicationConnection</code>, when configured to use
multiple masters, exposes the same options to balance load
across master hosts as described in
<a class="xref" href="#connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections" title="8.1. Configuring Load Balancing with Connector/J">Section 8.1, “Configuring Load Balancing with Connector/J”</a>.
</p><p>
Users may specify the property<code class="literal">
allowMasterDownConnections=true</code> to allow
<code class="literal">Connection</code> objects to be created even though
no master hosts are reachable. Such
<code class="literal">Connection</code> objects report they are read-only,
and <code class="literal">isMasterConnection()</code> returns false for
them. The <code class="literal">Connection</code> tests for available
master hosts when
<code class="literal">Connection.setReadOnly(false)</code> is called,
throwing an SQLException if it cannot establish a connection to
a master, or switching to a master connection if the host is
available.
</p><h3><a name="idm47020250399232"></a>
Live Reconfiguration of Replication Topography
</h3><p><a name="connector-j-live-reconfiguration-replication"></a>
Since Connector/J 5.1.28, live management of replication host
(single or multi-master) topographies is also supported. This
enables users to promote slaves for Java applications without
requiring an application restart.
</p><p>
The replication hosts are most effectively managed in the
context of a replication connection group. A
ReplicationConnectionGroup class represents a logical grouping
of connections which can be managed together. There may be one
or more such replication connection groups in a given Java class
loader (there can be an application with two different JDBC
resources needing to be managed independently). This key class
exposes host management methods for replication connections, and
<code class="literal">ReplicationConnection</code> objects register
themselves with the appropriate
<code class="literal">ReplicationConnectionGroup</code> if a value for the
new <code class="literal">replicationConnectionGroup</code> property is
specified. The <code class="literal">ReplicationConnectionGroup</code>
object tracks these connections until they are closed, and it is
used to manipulate the hosts associated with these connections.
</p><p>
Some important methods related to host management include:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">getMasterHosts()</code>: Returns a collection
of strings representing the hosts configured as masters
</p></li><li class="listitem"><p>
<code class="literal">getSlaveHosts()</code>: Returns a collection
of strings representing the hosts configured as slaves
</p></li><li class="listitem"><p>
<code class="literal">addSlaveHost(String host)</code>: Adds new
host to pool of possible slave hosts for selection at
start of new read-only workload
</p></li><li class="listitem"><p>
<code class="literal">promoteSlaveToMaster(String host)</code>:
Removes the host from the pool of potential slaves for
future read-only processes (existing read-only process is
allowed to continue to completion) and adds the host to
the pool of potential master hosts
</p></li><li class="listitem"><p>
<code class="literal">removeSlaveHost(String host, boolean
closeGently)</code>: Removes the host (host name match
must be exact) from the list of configured slaves; if
<code class="literal">closeGently</code> is false, existing
connections which have this host as currently active will
be closed hardly (application should expect exceptions)
</p></li><li class="listitem"><p>
<code class="literal">removeMasterHost(String host, boolean
closeGently)</code>: Same as
<code class="literal">removeSlaveHost()</code>, but removes the host
from the list of configured masters
</p></li></ul></div><p>
</p><p>
Some useful management metrics include:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">getConnectionCountWithHostAsSlave(String
host)</code>: Returns the number of
ReplicationConnection objects that have the given host
configured as a possible slave
</p></li><li class="listitem"><p>
<code class="literal"> getConnectionCountWithHostAsMaster(String
host)</code>: Returns the number of
ReplicationConnection objects that have the given host
configured as a possible master
</p></li><li class="listitem"><p>
<code class="literal">getNumberOfSlavesAdded()</code>: Returns the
number of times a slave host has been dynamically added to
the group pool
</p></li><li class="listitem"><p>
<code class="literal">getNumberOfSlavesRemoved()</code>: Returns the
number of times a slave host has been dynamically removed
from the group pool
</p></li><li class="listitem"><p>
<code class="literal">getNumberOfSlavePromotions()</code>: Returns
the number of times a slave host has been promoted to a
master
</p></li><li class="listitem"><p>
<code class="literal">getTotalConnectionCount()</code>: Returns the
number of ReplicationConnection objects which have been
registered with this group
</p></li><li class="listitem"><p>
<code class="literal">getActiveConnectionCount()</code>: Returns the
number of ReplicationConnection objects currently being
managed by this group
</p></li></ul></div><p>
</p><h3><a name="idm47020250374032"></a>
ReplicationConnectionGroupManager
</h3><p>
<code class="literal">com.mysql.jdbc.ReplicationConnectionGroupManager</code>
provides access to the replication connection groups, together
with some utility methods.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">getConnectionGroup(String groupName)</code>:
Returns the <code class="literal">ReplicationConnectionGroup</code>
object matching the groupName provided
</p></li></ul></div><p>
</p><p>
The other methods in
<code class="literal">ReplicationConnectionGroupManager</code> mirror
those of <code class="literal">ReplicationConnectionGroup</code>, except
that the first argument is a String group name. These methods
will operate on all matching ReplicationConnectionGroups, which
are helpful for removing a server from service and have it
decommissioned across all possible
<code class="literal">ReplicationConnectionGroups</code>.
</p><p>
These methods might be useful for in-JVM management of
replication hosts if an application triggers topography changes.
For managing host configurations from outside the JVM, JMX can
be used.
</p><h3><a name="idm47020250367760"></a>
Using JMX for Managing Replication Hosts
</h3><p>
When Connector/J is started with
<code class="literal">replicationEnableJMX=true</code>, a JMX MBean will
be registered, allowing manipulation of replication hosts by a
JMX client. The MBean interface is defined in
<code class="literal">com.mysql.jdbc.jmx.ReplicationGroupManagerMBean</code>,
and leverages the
<code class="literal">ReplicationConnectionGroupManager</code> static
methods:
</p><pre class="programlisting">
public abstract void addSlaveHost(String groupFilter, String host) throws SQLException;
public abstract void removeSlaveHost(String groupFilter, String host) throws SQLException;
public abstract void promoteSlaveToMaster(String groupFilter, String host) throws SQLException;
public abstract void removeMasterHost(String groupFilter, String host) throws SQLException;
public abstract String getMasterHostsList(String group);
public abstract String getSlaveHostsList(String group);
public abstract String getRegisteredConnectionGroups();
public abstract int getActiveMasterHostCount(String group);
public abstract int getActiveSlaveHostCount(String group);
public abstract int getSlavePromotionCount(String group);
public abstract long getTotalLogicalConnectionCount(String group);
public abstract long getActiveLogicalConnectionCount(String group);
</pre></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-interceptors"></a>Chapter 9. Using the Connector/J Interceptor Classes</h1></div></div></div><p>
An interceptor is a software design pattern that provides a
transparent way to extend or modify some aspect of a program,
similar to a user exit. No recompiling is required. With
Connector/J, the interceptors are enabled and disabled by updating
the connection string to refer to different sets of interceptor
classes that you instantiate.
</p><p>
The connection properties that control the interceptors are
explained in
<a class="xref" href="#connector-j-reference-configuration-properties" title="5.1. Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J">Section 5.1, “Driver/Datasource Class Names, URL Syntax and Configuration Properties
for Connector/J”</a>:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="literal">connectionLifecycleInterceptors</code>, where you
specify the fully qualified names of classes that implement
the
<code class="literal">com.mysql.jdbc.ConnectionLifecycleInterceptor</code>
interface. In these kinds of interceptor classes, you might
log events such as rollbacks, measure the time between
transaction start and end, or count events such as calls to
<code class="literal">setAutoCommit()</code>.
</p></li><li class="listitem"><p>
<code class="literal">exceptionInterceptors</code>, where you specify
the fully qualified names of classes that implement the
<code class="literal">com.mysql.jdbc.ExceptionInterceptor</code>
interface. In these kinds of interceptor classes, you might
add extra diagnostic information to exceptions that can have
multiple causes or indicate a problem with server settings.
Because <code class="literal">exceptionInterceptors</code> classes are
only called when handling a <code class="literal">SQLException</code>
thrown from Connector/J code, they can be used even in
production deployments without substantial performance
overhead.
</p></li><li class="listitem"><p>
<code class="literal">statementInterceptors</code>, where you specify
the fully qualified names of classes that implement the
<code class="literal">com.mysql.jdbc.StatementInterceptorV2</code>
interface. In these kinds of interceptor classes, you might
change or augment the processing done by certain kinds of
statements, such as automatically checking for queried data in
a <span class="command"><strong>memcached</strong></span> server, rewriting slow queries,
logging information about statement execution, or route
requests to remote servers.
</p></li></ul></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-tomcat"></a>Chapter 10. Using Connector/J with Tomcat</h1></div></div></div><a class="indexterm" name="idm47020250351344"></a><p>
The following instructions are based on the instructions for
Tomcat-5.x, available at
<a class="ulink" href="http://tomcat.apache.org/tomcat-5.5-doc/jndi-datasource-examples-howto.html" target="_top">http://tomcat.apache.org/tomcat-5.5-doc/jndi-datasource-examples-howto.html</a>
which is current at the time this document was written.
</p><p>
First, install the <code class="filename">.jar</code> file that comes with
Connector/J in <code class="filename">$CATALINA_HOME/common/lib</code> so
that it is available to all applications installed in the
container.
</p><p>
Next, configure the JNDI DataSource by adding a declaration
resource to <code class="filename">$CATALINA_HOME/conf/server.xml</code> in
the context that defines your web application:
</p><pre class="programlisting">
<Context ....>
...
<Resource name="jdbc/MySQLDB"
auth="Container"
type="javax.sql.DataSource"/>
<ResourceParams name="jdbc/MySQLDB">
<parameter>
<name>factory</name>
<value>org.apache.commons.dbcp.BasicDataSourceFactory</value>
</parameter>
<parameter>
<name>maxActive</name>
<value>10</value>
</parameter>
<parameter>
<name>maxIdle</name>
<value>5</value>
</parameter>
<parameter>
<name>validationQuery</name>
<value>SELECT 1</value>
</parameter>
<parameter>
<name>testOnBorrow</name>
<value>true</value>
</parameter>
<parameter>
<name>testWhileIdle</name>
<value>true</value>
</parameter>
<parameter>
<name>timeBetweenEvictionRunsMillis</name>
<value>10000</value>
</parameter>
<parameter>
<name>minEvictableIdleTimeMillis</name>
<value>60000</value>
</parameter>
<parameter>
<name>username</name>
<value>someuser</value>
</parameter>
<parameter>
<name>password</name>
<value>somepass</value>
</parameter>
<parameter>
<name>driverClassName</name>
<value>com.mysql.jdbc.Driver</value>
</parameter>
<parameter>
<name>url</name>
<value>jdbc:mysql://localhost:3306/test</value>
</parameter>
</ResourceParams>
</Context>
</pre><p>
Note that Connector/J 5.1.3 introduced a facility whereby, rather
than use a <code class="literal">validationQuery</code> value of
<code class="literal">SELECT 1</code>, it is possible to use
<code class="literal">validationQuery</code> with a value set to <code class="literal">/*
ping */</code>. This sends a ping to the server which then
returns a fake result set. This is a lighter weight solution. It
also has the advantage that if using
<code class="literal">ReplicationConnection</code> or
<code class="literal">LoadBalancedConnection</code> type connections, the
ping will be sent across all active connections. The following XML
snippet illustrates how to select this option:
</p><pre class="programlisting">
<parameter>
<name>validationQuery</name>
<value>/* ping */</value>
</parameter>
</pre><p>
Note that <code class="literal">/* ping */</code> has to be specified
exactly.
</p><p>
In general, 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 if you use the wrong syntax
in your XML file, you will most likely end up with an exception
similar to the following:
</p><pre class="programlisting">
Error: java.sql.SQLException: Cannot load JDBC driver class 'null ' SQL
state: null
</pre><p>
Note that the auto-loading of drivers having the
<code class="filename">META-INF/service/java.sql.Driver</code> class in
JDBC 4.0 causes an improper undeployment of the Connector/J driver
in Tomcat on Windows. Namely, the Connector/J jar remains locked.
This is an initialization problem that is not related to the
driver. The possible workarounds, if viable, are as follows: use
"<code class="literal">antiResourceLocking=true</code>" as a Tomcat Context
attribute, or remove the <code class="filename">META-INF/</code> directory.
</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-jboss"></a>Chapter 11. Using Connector/J with JBoss</h1></div></div></div><a class="indexterm" name="idm47020250334640"></a><p>
These instructions cover JBoss-4.x. To make the JDBC driver
classes available to the application server, copy the
<code class="filename">.jar</code> file that comes with Connector/J to the
<code class="filename">lib</code> directory for your server configuration
(which is usually called <code class="filename">default</code>). Then, in
the same configuration directory, in the subdirectory named
deploy, create a datasource configuration file that ends with
<code class="literal">-ds.xml</code>, which tells JBoss to deploy this file
as a JDBC Datasource. The file should have the following contents:
</p><pre class="programlisting">
<datasources>
<local-tx-datasource>
<jndi-name>MySQLDB</jndi-name>
<connection-url>jdbc:mysql://localhost:3306/dbname</connection-url>
<driver-class>com.mysql.jdbc.Driver</driver-class>
<user-name>user</user-name>
<password>pass</password>
<min-pool-size>5</min-pool-size>
<max-pool-size>20</max-pool-size>
<idle-timeout-minutes>5</idle-timeout-minutes>
<exception-sorter-class-name>
com.mysql.jdbc.integration.jboss.ExtendedMysqlExceptionSorter
</exception-sorter-class-name>
<valid-connection-checker-class-name>
com.mysql.jdbc.integration.jboss.MysqlValidConnectionChecker
</valid-connection-checker-class-name>
</local-tx-datasource>
</datasources>
</pre></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-spring-config"></a>Chapter 12. Using Connector/J with Spring</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-usagenotes-spring-config-jdbctemplate">12.1. Using <code class="classname">JdbcTemplate</code></a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-spring-config-transactional">12.2. Transactional JDBC Access</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-spring-config-connpooling">12.3. Connection Pooling with Spring</a></span></dt></dl></div><a class="indexterm" name="idm47020250328544"></a><p>
The Spring Framework is a Java-based application framework
designed for assisting in application design by providing a way to
configure components. The technique used by Spring is a well known
design pattern called Dependency Injection (see
<a class="ulink" href="http://www.martinfowler.com/articles/injection.html" target="_top">Inversion
of Control Containers and the Dependency Injection
pattern</a>). This article will focus on Java-oriented access
to MySQL databases with Spring 2.0. For those wondering, there is
a .NET port of Spring appropriately named Spring.NET.
</p><p>
Spring is not only a system for configuring components, but also
includes support for aspect oriented programming (AOP). This is
one of the main benefits and the foundation for Spring's resource
and transaction management. Spring also provides utilities for
integrating resource management with JDBC and Hibernate.
</p><p>
For the examples in this section the MySQL world sample database
will be used. The first task is to set up a MySQL data source
through Spring. Components within Spring use the
<span class="quote">“<span class="quote">bean</span>”</span> terminology. For example, to configure a
connection to a MySQL server supporting the world sample database,
you might use:
</p><pre class="programlisting">
<util:map id="dbProps">
<entry key="db.driver" value="com.mysql.jdbc.Driver"/>
<entry key="db.jdbcurl" value="jdbc:mysql://localhost/world"/>
<entry key="db.username" value="myuser"/>
<entry key="db.password" value="mypass"/>
</util:map>
</pre><p>
In the above example, we are assigning values to properties that
will be used in the configuration. For the datasource
configuration:
</p><pre class="programlisting">
<bean id="dataSource"
class="org.springframework.jdbc.datasource.DriverManagerDataSource">
<property name="driverClassName" value="${db.driver}"/>
<property name="url" value="${db.jdbcurl}"/>
<property name="username" value="${db.username}"/>
<property name="password" value="${db.password}"/>
</bean>
</pre><p>
The placeholders are used to provide values for properties of this
bean. This means that you can specify all the properties of the
configuration in one place instead of entering the values for each
property on each bean. We do, however, need one more bean to pull
this all together. The last bean is responsible for actually
replacing the placeholders with the property values.
</p><pre class="programlisting">
<bean
class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
<property name="properties" ref="dbProps"/>
</bean>
</pre><p>
Now that we have our MySQL data source configured and ready to go,
we write some Java code to access it. The example below will
retrieve three random cities and their corresponding country using
the data source we configured with Spring.
</p><pre class="programlisting">
// Create a new application context. this processes the Spring config
ApplicationContext ctx =
new ClassPathXmlApplicationContext("ex1appContext.xml");
// Retrieve the data source from the application context
DataSource ds = (DataSource) ctx.getBean("dataSource");
// Open a database connection using Spring's DataSourceUtils
Connection c = DataSourceUtils.getConnection(ds);
try {
// retrieve a list of three random cities
PreparedStatement ps = c.prepareStatement(
"select City.Name as 'City', Country.Name as 'Country' " +
"from City inner join Country on City.CountryCode = Country.Code " +
"order by rand() limit 3");
ResultSet rs = ps.executeQuery();
while(rs.next()) {
String city = rs.getString("City");
String country = rs.getString("Country");
System.out.printf("The city %s is in %s%n", city, country);
}
} catch (SQLException ex) {
// something has failed and we print a stack trace to analyse the error
ex.printStackTrace();
// ignore failure closing connection
try { c.close(); } catch (SQLException e) { }
} finally {
// properly release our connection
DataSourceUtils.releaseConnection(c, ds);
}
</pre><p>
This is very similar to normal JDBC access to MySQL with the main
difference being that we are using DataSourceUtils instead of the
DriverManager to create the connection.
</p><p>
While it may seem like a small difference, the implications are
somewhat far reaching. Spring manages this resource in a way
similar to a container managed data source in a J2EE application
server. When a connection is opened, it can be subsequently
accessed in other parts of the code if it is synchronized with a
transaction. This makes it possible to treat different parts of
your application as transactional instead of passing around a
database connection.
</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-spring-config-jdbctemplate"></a>12.1. Using <code class="classname">JdbcTemplate</code></h2></div></div></div><p>
Spring makes extensive use of the Template method design pattern
(see
<a class="ulink" href="http://en.wikipedia.org/wiki/Template_method_pattern" target="_top">Template
Method Pattern</a>). Our immediate focus will be on the
<code class="literal">JdbcTemplate</code> and related classes,
specifically <code class="literal">NamedParameterJdbcTemplate</code>. The
template classes handle obtaining and releasing a connection for
data access when one is needed.
</p><p>
The next example shows how to use
<code class="literal">NamedParameterJdbcTemplate</code> inside of a DAO
(Data Access Object) class to retrieve a random city given a
country code.
</p><pre class="programlisting">
public class Ex2JdbcDao {
/**
* Data source reference which will be provided by Spring.
*/
private DataSource dataSource;
/**
* Our query to find a random city given a country code. Notice
* the ":country" parameter toward the end. This is called a
* named parameter.
*/
private String queryString = "select Name from City " +
"where CountryCode = :country order by rand() limit 1";
/**
* Retrieve a random city using Spring JDBC access classes.
*/
public String getRandomCityByCountryCode(String cntryCode) {
// A template that permits using queries with named parameters
NamedParameterJdbcTemplate template =
new NamedParameterJdbcTemplate(dataSource);
// A java.util.Map is used to provide values for the parameters
Map params = new HashMap();
params.put("country", cntryCode);
// We query for an Object and specify what class we are expecting
return (String)template.queryForObject(queryString, params, String.class);
}
/**
* A JavaBean setter-style method to allow Spring to inject the data source.
* @param dataSource
*/
public void setDataSource(DataSource dataSource) {
this.dataSource = dataSource;
}
}
</pre><p>
The focus in the above code is on the
<code class="function">getRandomCityByCountryCode()</code> method. We
pass a country code and use the
<code class="literal">NamedParameterJdbcTemplate</code> to query for a
city. The country code is placed in a Map with the key
"country", which is the parameter is named in the SQL query.
</p><p>
To access this code, you need to configure it with Spring by
providing a reference to the data source.
</p><pre class="programlisting">
<bean id="dao" class="code.Ex2JdbcDao">
<property name="dataSource" ref="dataSource"/>
</bean>
</pre><p>
At this point, we can just grab a reference to the DAO from
Spring and call
<code class="function">getRandomCityByCountryCode()</code>.
</p><pre class="programlisting">
// Create the application context
ApplicationContext ctx =
new ClassPathXmlApplicationContext("ex2appContext.xml");
// Obtain a reference to our DAO
Ex2JdbcDao dao = (Ex2JdbcDao) ctx.getBean("dao");
String countryCode = "USA";
// Find a few random cities in the US
for(int i = 0; i < 4; ++i)
System.out.printf("A random city in %s is %s%n", countryCode,
dao.getRandomCityByCountryCode(countryCode));
</pre><p>
This example shows how to use Spring's JDBC classes to
completely abstract away the use of traditional JDBC classes
including <code class="literal">Connection</code> and
<code class="literal">PreparedStatement</code>.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-spring-config-transactional"></a>12.2. Transactional JDBC Access</h2></div></div></div><p>
You might be wondering how we can add transactions into our code
if we do not deal directly with the JDBC classes. Spring
provides a transaction management package that not only replaces
JDBC transaction management, but also enables declarative
transaction management (configuration instead of code).
</p><p>
To use transactional database access, we will need to change the
storage engine of the tables in the world database. The
downloaded script explicitly creates MyISAM tables which do not
support transactional semantics. The InnoDB storage engine does
support transactions and this is what we will be using. We can
change the storage engine with the following statements.
</p><pre class="programlisting">
ALTER TABLE City ENGINE=InnoDB;
ALTER TABLE Country ENGINE=InnoDB;
ALTER TABLE CountryLanguage ENGINE=InnoDB;
</pre><p>
A good programming practice emphasized by Spring is separating
interfaces and implementations. What this means is that we can
create a Java interface and only use the operations on this
interface without any internal knowledge of what the actual
implementation is. We will let Spring manage the implementation
and with this it will manage the transactions for our
implementation.
</p><p>
First you create a simple interface:
</p><pre class="programlisting">
public interface Ex3Dao {
Integer createCity(String name, String countryCode,
String district, Integer population);
}
</pre><p>
This interface contains one method that will create a new city
record in the database and return the id of the new record. Next
you need to create an implementation of this interface.
</p><pre class="programlisting">
public class Ex3DaoImpl implements Ex3Dao {
protected DataSource dataSource;
protected SqlUpdate updateQuery;
protected SqlFunction idQuery;
public Integer createCity(String name, String countryCode,
String district, Integer population) {
updateQuery.update(new Object[] { name, countryCode,
district, population });
return getLastId();
}
protected Integer getLastId() {
return idQuery.run();
}
}
</pre><p>
You can see that we only operate on abstract query objects here
and do not deal directly with the JDBC API. Also, this is the
complete implementation. All of our transaction management will
be dealt with in the configuration. To get the configuration
started, we need to create the DAO.
</p><pre class="programlisting">
<bean id="dao" class="code.Ex3DaoImpl">
<property name="dataSource" ref="dataSource"/>
<property name="updateQuery">...</property>
<property name="idQuery">...</property>
</bean>
</pre><p>
Now you need to set up the transaction configuration. The first
thing you must do is create transaction manager to manage the
data source and a specification of what transaction properties
are required for the <code class="literal">dao</code> methods.
</p><pre class="programlisting">
<bean id="transactionManager"
class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
<property name="dataSource" ref="dataSource"/>
</bean>
<tx:advice id="txAdvice" transaction-manager="transactionManager">
<tx:attributes>
<tx:method name="*"/>
</tx:attributes>
</tx:advice>
</pre><p>
The preceding code creates a transaction manager that handles
transactions for the data source provided to it. The
<code class="literal">txAdvice</code> uses this transaction manager and
the attributes specify to create a transaction for all methods.
Finally you need to apply this advice with an AOP pointcut.
</p><pre class="programlisting">
<aop:config>
<aop:pointcut id="daoMethods"
expression="execution(* code.Ex3Dao.*(..))"/>
<aop:advisor advice-ref="txAdvice" pointcut-ref="daoMethods"/>
</aop:config>
</pre><p>
This basically says that all methods called on the
<code class="literal">Ex3Dao</code> interface will be wrapped in a
transaction. To make use of this, you only have to retrieve the
<code class="literal">dao</code> from the application context and call a
method on the <code class="literal">dao</code> instance.
</p><pre class="programlisting">
Ex3Dao dao = (Ex3Dao) ctx.getBean("dao");
Integer id = dao.createCity(name, countryCode, district, pop);
</pre><p>
We can verify from this that there is no transaction management
happening in our Java code and it is all configured with Spring.
This is a very powerful notion and regarded as one of the most
beneficial features of Spring.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-spring-config-connpooling"></a>12.3. Connection Pooling with Spring</h2></div></div></div><a class="indexterm" name="idm47020250286896"></a><p>
In many situations, such as web applications, there will be a
large number of small database transactions. When this is the
case, it usually makes sense to create a pool of database
connections available for web requests as needed. Although MySQL
does not spawn an extra process when a connection is made, there
is still a small amount of overhead to create and set up the
connection. Pooling of connections also alleviates problems such
as collecting large amounts of sockets in the
<code class="literal">TIME_WAIT</code> state.
</p><p>
Setting up pooling of MySQL connections with Spring is as simple
as changing the data source configuration in the application
context. There are a number of configurations that we can use.
The first example is based on the
<a class="ulink" href="http://jakarta.apache.org/commons/dbcp/" target="_top">Jakarta
Commons DBCP library</a>. The example below replaces the
source configuration that was based on
<code class="literal">DriverManagerDataSource</code> with DBCP's
BasicDataSource.
</p><pre class="programlisting">
<bean id="dataSource" destroy-method="close"
class="org.apache.commons.dbcp.BasicDataSource">
<property name="driverClassName" value="${db.driver}"/>
<property name="url" value="${db.jdbcurl}"/>
<property name="username" value="${db.username}"/>
<property name="password" value="${db.password}"/>
<property name="initialSize" value="3"/>
</bean>
</pre><p>
The configuration of the two solutions is very similar. The
difference is that DBCP will pool connections to the database
instead of creating a new connection every time one is
requested. We have also set a parameter here called
<code class="literal">initialSize</code>. This tells DBCP that we want
three connections in the pool when it is created.
</p><p>
Another way to configure connection pooling is to configure a
data source in our J2EE application server. Using JBoss as an
example, you can set up the MySQL connection pool by creating a
file called <code class="filename">mysql-local-ds.xml</code> and placing
it in the server/default/deploy directory in JBoss. Once we have
this setup, we can use JNDI to look it up. With Spring, this
lookup is very simple. The data source configuration looks like
this.
</p><pre class="programlisting">
<jee:jndi-lookup id="dataSource" jndi-name="java:MySQL_DS"/>
</pre></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-glassfish-config"></a>Chapter 13. Using Connector/J with GlassFish</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-usagenotes-glassfish-config-jsp">13.1. A Simple JSP Application with Glassfish, Connector/J and MySQL</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-glassfish-config-servlet">13.2. A Simple Servlet with Glassfish, Connector/J and MySQL</a></span></dt></dl></div><a class="indexterm" name="idm47020250277552"></a><a class="indexterm" name="idm47020250276736"></a><p>
This section explains how to use MySQL Connector/J with Glassfish ™
Server Open Source Edition 3.0.1. Glassfish can be downloaded from
the
<a class="ulink" href="https://glassfish.dev.java.net/public/downloadsindex.html#top" target="_top">Glassfish
website</a>.
</p><p>
Once Glassfish is installed you will need to make sure it can
access MySQL Connector/J. To do this copy the MySQL Connector/J JAR file to the directory
<code class="filename"><em class="replaceable"><code>GLASSFISH_INSTALL</code></em>/glassfish/lib</code>.
For example, copy
<code class="filename">mysql-connector-java-5.1.12-bin.jar</code> to
<code class="filename">C:\glassfishv3\glassfish\lib</code>. Restart the
Glassfish Application Server.
</p><p>
You are now ready to create JDBC Connection Pools and JDBC
Resources.
</p><p>
<span class="bold"><strong>Creating a Connection Pool</strong></span>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
In the Glassfish Administration Console, using the navigation
tree navigate to <span class="guilabel">Resources</span>,
<span class="guilabel">JDBC</span>, <span class="guilabel">Connection
Pools</span>.
</p></li><li class="listitem"><p>
In the <span class="guilabel">JDBC Connection Pools</span> frame click
<span class="guibutton">New</span>. You will enter a two step wizard.
</p></li><li class="listitem"><p>
In the <span class="guilabel">Name</span> field under <span class="guilabel">General
Settings</span> enter the name for the connection pool,
for example enter <strong class="userinput"><code>MySQLConnPool</code></strong>.
</p></li><li class="listitem"><p>
In the <span class="guilabel">Resource Type</span> field, select
<code class="literal">javax.sql.DataSource</code> from the drop-down
listbox.
</p></li><li class="listitem"><p>
In the <span class="guilabel">Database Vendor</span> field, select
<code class="literal">MySQL</code> from the drop-down listbox. Click
<span class="guibutton">Next</span> to go to the next page of the
wizard.
</p></li><li class="listitem"><p>
You can accept the default settings for General Settings, Pool
Settings and Transactions for this example. Scroll down to
Additional Properties.
</p></li><li class="listitem"><p>
In Additional Properties you will need to ensure the following
properties are set:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<span class="bold"><strong>ServerName</strong></span> - The server
to connect to. For local testing this will be
<code class="literal">localhost</code>.
</p></li><li class="listitem"><p>
<span class="bold"><strong>User</strong></span> - The user name with
which to connect to MySQL.
</p></li><li class="listitem"><p>
<span class="bold"><strong>Password</strong></span> - The
corresponding password for the user.
</p></li><li class="listitem"><p>
<span class="bold"><strong>DatabaseName</strong></span> - The
database to connect to, for example the sample MySQL
database <code class="literal">World</code>.
</p></li></ul></div></li><li class="listitem"><p>
Click <span class="guibutton">Finish</span> to exit the wizard. You
will be taken to the <span class="guilabel">JDBC Connection
Pools</span> page where all current connection pools,
including the one you just created, will be displayed.
</p></li><li class="listitem"><p>
In the <span class="guilabel">JDBC Connection Pools</span> frame click
on the connection pool you just created. Here, you can review
and edit information about the connection pool. Because
Connector/J does not support optimized validation queries, go
to the <span class="guilabel">Advanced</span> tab, and under Connection
Validation, configure the following settings:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<span class="bold"><strong>Connection Validation</strong></span> -
select <span class="guilabel">Required</span>.
</p></li><li class="listitem"><p>
<span class="bold"><strong>Validation Method</strong></span> -
select <span class="guilabel">table</span> from the drop-down
menu.
</p></li><li class="listitem"><p>
<span class="bold"><strong>Table Name</strong></span> - enter
<code class="literal">DUAL</code>.
</p></li></ul></div><p>
</p></li><li class="listitem"><p>
To test your connection pool click the
<span class="guibutton">Ping</span> button at the top of the frame. A
message will be displayed confirming correct operation or
otherwise. If an error message is received recheck the
previous steps, and ensure that MySQL Connector/J has been correctly copied
into the previously specified location.
</p></li></ol></div><p>
Now that you have created a connection pool you will also need to
create a JDBC Resource (data source) for use by your application.
</p><p>
<span class="bold"><strong>Creating a JDBC Resource</strong></span>
</p><p>
Your Java application will usually reference a data source object
to establish a connection with the database. This needs to be
created first using the following procedure.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Using the navigation tree in the Glassfish Administration
Console, navigate to <span class="guilabel">Resources</span>,
<span class="guilabel">JDBC</span>, <span class="guilabel">JDBC
Resources</span>. A list of resources will be displayed in
the <span class="guilabel">JDBC Resources</span> frame.
</p></li><li class="listitem"><p>
Click <span class="guibutton">New</span>. The <span class="guilabel">New JDBC
Resource</span> frame will be displayed.
</p></li><li class="listitem"><p>
In the <span class="guilabel">JNDI Name</span> field, enter the JNDI
name that will be used to access this resource, for example
enter <strong class="userinput"><code>jdbc/MySQLDataSource</code></strong>.
</p></li><li class="listitem"><p>
In the <span class="guilabel">Pool Name</span> field, select a
connection pool you want this resource to use from the
drop-down listbox.
</p></li><li class="listitem"><p>
Optionally, you can enter a description into the
<span class="guilabel">Description</span> field.
</p></li><li class="listitem"><p>
Additional properties can be added if required.
</p></li><li class="listitem"><p>
Click <span class="guibutton">OK</span> to create the new JDBC
resource. The <span class="guilabel">JDBC Resources</span> frame will
list all available JDBC Resources.
</p></li></ul></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-glassfish-config-jsp"></a>13.1. A Simple JSP Application with Glassfish, Connector/J and MySQL</h2></div></div></div><p>
This section shows how to deploy a simple JSP application on
Glassfish, that connects to a MySQL database.
</p><p>
This example assumes you have already set up a suitable
Connection Pool and JDBC Resource, as explained in the preceding
sections. It is also assumed you have a sample database
installed, such as <code class="literal">world</code>.
</p><p>
The main application code, <code class="filename">index.jsp</code> is
presented here:
</p><pre class="programlisting">
<%@ page import="java.sql.*, javax.sql.*, java.io.*, javax.naming.*" %>
<html>
<head><title>Hello world from JSP</title></head>
<body>
<%
InitialContext ctx;
DataSource ds;
Connection conn;
Statement stmt;
ResultSet rs;
try {
ctx = new InitialContext();
ds = (DataSource) ctx.lookup("java:comp/env/jdbc/MySQLDataSource");
//ds = (DataSource) ctx.lookup("jdbc/MySQLDataSource");
conn = ds.getConnection();
stmt = conn.createStatement();
rs = stmt.executeQuery("SELECT * FROM Country");
while(rs.next()) {
%>
<h3>Name: <%= rs.getString("Name") %></h3>
<h3>Population: <%= rs.getString("Population") %></h3>
<%
}
}
catch (SQLException se) {
%>
<%= se.getMessage() %>
<%
}
catch (NamingException ne) {
%>
<%= ne.getMessage() %>
<%
}
%>
</body>
</html>
</pre><p>
In addition two XML files are required:
<code class="filename">web.xml</code>, and
<code class="filename">sun-web.xml</code>. There may be other files
present, such as classes and images. These files are organized
into the directory structure as follows:
</p><pre class="programlisting">
index.jsp
WEB-INF
|
- web.xml
- sun-web.xml
</pre><p>
The code for <code class="filename">web.xml</code> is:
</p><pre class="programlisting">
<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
<display-name>HelloWebApp</display-name>
<distributable/>
<resource-ref>
<res-ref-name>jdbc/MySQLDataSource</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
</web-app>
</pre><p>
The code for <code class="filename">sun-web.xml</code> is:
</p><pre class="programlisting">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Application Server 8.1 Servlet 2.4//EN" "http://www.sun.com/software/appserver/dtds/sun-web-app_2_4-1.dtd">
<sun-web-app>
<context-root>HelloWebApp</context-root>
<resource-ref>
<res-ref-name>jdbc/MySQLDataSource</res-ref-name>
<jndi-name>jdbc/MySQLDataSource</jndi-name>
</resource-ref>
</sun-web-app>
</pre><p>
These XML files illustrate a very important aspect of running
JDBC applications on Glassfish. On Glassfish it is important to
map the string specified for a JDBC resource to its JNDI name,
as set up in the Glassfish administration console. In this
example, the JNDI name for the JDBC resource, as specified in
the Glassfish Administration console when creating the JDBC
Resource, was <code class="literal">jdbc/MySQLDataSource</code>. This must
be mapped to the name given in the application. In this example
the name specified in the application,
<code class="literal">jdbc/MySQLDataSource</code>, and the JNDI name,
happen to be the same, but this does not necessarily have to be
the case. Note that the XML element <res-ref-name> is used
to specify the name as used in the application source code, and
this is mapped to the JNDI name specified using the
<jndi-name> element, in the file
<code class="filename">sun-web.xml</code>. The resource also has to be
created in the <code class="filename">web.xml</code> file, although the
mapping of the resource to a JNDI name takes place in the
<code class="filename">sun-web.xml</code> file.
</p><p>
If you do not have this mapping set up correctly in the XML
files you will not be able to lookup the data source using a
JNDI lookup string such as:
</p><pre class="programlisting">
ds = (DataSource) ctx.lookup("java:comp/env/jdbc/MySQLDataSource");
</pre><p>
You will still be able to access the data source directly using:
</p><pre class="programlisting">
ds = (DataSource) ctx.lookup("jdbc/MySQLDataSource");
</pre><p>
With the source files in place, in the correct directory
structure, you are ready to deploy the application:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
In the navigation tree, navigate to
<span class="guilabel">Applications</span> - the
<span class="guilabel">Applications</span> frame will be displayed.
Click <span class="guibutton">Deploy</span>.
</p></li><li class="listitem"><p>
You can now deploy an application packaged into a single WAR
file from a remote client, or you can choose a packaged file
or directory that is locally accessible to the server. If
you are simply testing an application locally you can simply
point Glassfish at the directory that contains your
application, without needing to package the application into
a WAR file.
</p></li><li class="listitem"><p>
Now select the application type from the
<span class="guilabel">Type</span> drop-down listbox, which in this
example is <code class="literal">Web application</code>.
</p></li><li class="listitem"><p>
Click OK.
</p></li></ol></div><p>
Now, when you navigate to the <span class="guilabel">Applications</span>
frame, you will have the option to <span class="guilabel">Launch</span>,
<span class="guilabel">Redeploy</span>, or <span class="guilabel">Restart</span>
your application. You can test your application by clicking
<span class="guilabel">Launch</span>. The application will connection to
the MySQL database and display the Name and Population of
countries in the <code class="literal">Country</code> table.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-glassfish-config-servlet"></a>13.2. A Simple Servlet with Glassfish, Connector/J and MySQL</h2></div></div></div><a class="indexterm" name="idm47020250191344"></a><p>
This section describes a simple servlet that can be used in the
Glassfish environment to access a MySQL database. As with the
previous section, this example assumes the sample database
<code class="literal">world</code> is installed.
</p><p>
The project is set up with the following directory structure:
</p><pre class="programlisting">
index.html
WEB-INF
|
- web.xml
- sun-web.xml
- classes
|
- HelloWebServlet.java
- HelloWebServlet.class
</pre><p>
The code for the servlet, located in
<code class="filename">HelloWebServlet.java</code>, is as follows:
</p><pre class="programlisting">
import javax.servlet.http.*;
import javax.servlet.*;
import java.io.*;
import java.sql.*;
import javax.sql.*;
import javax.naming.*;
public class HelloWebServlet extends HttpServlet {
InitialContext ctx = null;
DataSource ds = null;
Connection conn = null;
PreparedStatement ps = null;
ResultSet rs = null;
String sql = "SELECT Name, Population FROM Country WHERE Name=?";
public void init () throws ServletException {
try {
ctx = new InitialContext();
ds = (DataSource) ctx.lookup("java:comp/env/jdbc/MySQLDataSource");
conn = ds.getConnection();
ps = conn.prepareStatement(sql);
}
catch (SQLException se) {
System.out.println("SQLException: "+se.getMessage());
}
catch (NamingException ne) {
System.out.println("NamingException: "+ne.getMessage());
}
}
public void destroy () {
try {
if (rs != null)
rs.close();
if (ps != null)
ps.close();
if (conn != null)
conn.close();
if (ctx != null)
ctx.close();
}
catch (SQLException se) {
System.out.println("SQLException: "+se.getMessage());
}
catch (NamingException ne) {
System.out.println("NamingException: "+ne.getMessage());
}
}
public void doPost(HttpServletRequest req, HttpServletResponse resp){
try {
String country_name = req.getParameter("country_name");
resp.setContentType("text/html");
PrintWriter writer = resp.getWriter();
writer.println("<html><body>");
writer.println("<p>Country: "+country_name+"</p>");
ps.setString(1, country_name);
rs = ps.executeQuery();
if (!rs.next()){
writer.println("<p>Country does not exist!</p>");
}
else {
rs.beforeFirst();
while(rs.next()) {
writer.println("<p>Name: "+rs.getString("Name")+"</p>");
writer.println("<p>Population: "+rs.getString("Population")+"</p>");
}
}
writer.println("</body></html>");
writer.close();
}
catch (Exception e) {
e.printStackTrace();
}
}
public void doGet(HttpServletRequest req, HttpServletResponse resp){
try {
resp.setContentType("text/html");
PrintWriter writer = resp.getWriter();
writer.println("<html><body>");
writer.println("<p>Hello from servlet doGet()</p>");
writer.println("</body></html>");
writer.close();
}
catch (Exception e) {
e.printStackTrace();
}
}
}
</pre><p>
In the preceding code a basic <code class="literal">doGet()</code> method
is implemented, but is not used in the example. The code to
establish the connection with the database is as shown in the
previous example,
<a class="xref" href="#connector-j-usagenotes-glassfish-config-jsp" title="13.1. A Simple JSP Application with Glassfish, Connector/J and MySQL">Section 13.1, “A Simple JSP Application with Glassfish, Connector/J and MySQL”</a>,
and is most conveniently located in the servlet
<code class="literal">init()</code> method. The corresponding freeing of
resources is located in the destroy method. The main
functionality of the servlet is located in the
<code class="literal">doPost()</code> method. If the user enters nto the
input form a country name that can be located in the database,
the population of the country is returned. The code is invoked
using a POST action associated with the input form. The form is
defined in the file <code class="filename">index.html</code>:
</p><pre class="programlisting">
<html>
<head><title>HelloWebServlet</title></head>
<body>
<h1>HelloWebServlet</h1>
<p>Please enter country name:</p>
<form action="HelloWebServlet" method="POST">
<input type="text" name="country_name" length="50" />
<input type="submit" value="Submit" />
</form>
</body>
</html>
</pre><p>
The XML files <code class="filename">web.xml</code> and
<code class="filename">sun-web.xml</code> are as for the example in the
preceding section,
<a class="xref" href="#connector-j-usagenotes-glassfish-config-jsp" title="13.1. A Simple JSP Application with Glassfish, Connector/J and MySQL">Section 13.1, “A Simple JSP Application with Glassfish, Connector/J and MySQL”</a>,
no additional changes are required.
</p><p>
Whe compiling the Java source code, you will need to specify the
path to the file <code class="filename">javaee.jar</code>. On Windows,
this can be done as follows:
</p><pre class="programlisting">
shell> javac -classpath c:\glassfishv3\glassfish\lib\javaee.jar HelloWebServlet.java
</pre><p>
Once the code is correctly located within its directory
structure, and compiled, the application can be deployed in
Glassfish. This is done in exactly the same way as described in
the preceding section,
<a class="xref" href="#connector-j-usagenotes-glassfish-config-jsp" title="13.1. A Simple JSP Application with Glassfish, Connector/J and MySQL">Section 13.1, “A Simple JSP Application with Glassfish, Connector/J and MySQL”</a>.
</p><p>
Once deployed the application can be launched from within the
Glassfish Administration Console. Enter a country name such as
<span class="quote">“<span class="quote">England</span>”</span>, and the application will return
<span class="quote">“<span class="quote">Country does not exist!</span>”</span>. Enter
<span class="quote">“<span class="quote">France</span>”</span>, and the application will return a
population of 59225700.
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-troubleshooting"></a>Chapter 14. Troubleshooting Connector/J Applications</h1></div></div></div><a class="indexterm" name="idm47020250171440"></a><a class="indexterm" name="idm47020250170224"></a><a class="indexterm" name="idm47020250169008"></a><p>
This section explains the symptoms and resolutions for the most
commonly encountered issues with applications using MySQL
Connector/J.
</p><p><span class="bold"><strong>Questions</strong></span></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="link" href="#qandaitem-14-1-1">14.1: </a>
When I try to connect to the database with MySQL
Connector/J, I get the following exception:
</p><pre class="programlisting">
SQLException: Server configuration denies access to data source
SQLState: 08001
VendorError: 0
</pre><p>
What is going on? I can connect just fine with the MySQL
command-line client.
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-14-1-2">14.2: </a>
My application throws an SQLException 'No Suitable Driver'.
Why is this happening?
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-14-1-3">14.3: </a>
I'm trying to use MySQL Connector/J in an applet or
application and I get an exception similar to:
</p><pre class="programlisting">
SQLException: Cannot connect to MySQL server on host:3306.
Is there a MySQL server running on the machine/port you
are trying to connect to?
(java.security.AccessControlException)
SQLState: 08S01
VendorError: 0
</pre></li><li class="listitem"><p><a class="link" href="#qandaitem-14-1-4">14.4: </a>
I have a servlet/application that works fine for a day, and
then stops working overnight
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-14-1-5">14.5: </a>
I'm trying to use JDBC 2.0 updatable result sets, and I get
an exception saying my result set is not updatable.
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-14-1-6">14.6: </a>
I cannot connect to the MySQL server using Connector/J, and
I'm sure the connection parameters are correct.
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-14-1-7">14.7: </a>
I am trying to connect to my MySQL server within my
application, but I get the following error and stack trace:
</p><pre class="programlisting">
java.net.SocketException
MESSAGE: Software caused connection abort: recv failed
STACKTRACE:
java.net.SocketException: Software caused connection abort: recv failed
at java.net.SocketInputStream.socketRead0(Native Method)
at java.net.SocketInputStream.read(Unknown Source)
at com.mysql.jdbc.MysqlIO.readFully(MysqlIO.java:1392)
at com.mysql.jdbc.MysqlIO.readPacket(MysqlIO.java:1414)
at com.mysql.jdbc.MysqlIO.doHandshake(MysqlIO.java:625)
at com.mysql.jdbc.Connection.createNewIO(Connection.java:1926)
at com.mysql.jdbc.Connection.<init>(Connection.java:452)
at com.mysql.jdbc.NonRegisteringDriver.connect(NonRegisteringDriver.java:411)
</pre></li><li class="listitem"><p><a class="link" href="#qandaitem-14-1-8">14.8: </a>
My application is deployed through JBoss and I am using
transactions to handle the statements on the MySQL database.
Under heavy loads, I am getting an error and stack trace,
but these only occur after a fixed period of heavy activity.
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-14-1-9">14.9: </a>
When using <span class="command"><strong>gcj</strong></span>, a
<code class="literal">java.io.CharConversionException</code> exception
is raised when working with certain character sequences.
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-14-1-10">14.10: </a>
Updating a table that contains a
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/glossary.html#glos_primary_key" target="_top">primary key</a> that is
either <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/floating-point-types.html" target="_top"><code class="literal">FLOAT</code></a> or compound
primary key that uses <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/floating-point-types.html" target="_top"><code class="literal">FLOAT</code></a>
fails to update the table and raises an exception.
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-14-1-11">14.11: </a>
You get an
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/error-messages-server.html#error_er_net_packet_too_large" target="_top"><code class="literal">ER_NET_PACKET_TOO_LARGE</code></a>
exception, even though the binary blob size you want to
insert using JDBC is safely below the
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/server-system-variables.html#sysvar_max_allowed_packet" target="_top"><code class="literal">max_allowed_packet</code></a> size.
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-14-1-12">14.12: </a>
What should you do if you receive error messages similar to
the following: <span class="quote">“<span class="quote">Communications link failure – Last
packet sent to the server was X ms ago</span>”</span>?
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-14-1-13">14.13: </a>
Why does Connector/J not reconnect to MySQL and re-issue the
statement after a communication failure, instead of throwing
an Exception, even though I use the
<code class="literal">autoReconnect</code> connection string option?
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-14-1-14">14.14: </a>
How can I use 3-byte UTF8 with Connector/J?
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-14-1-15">14.15: </a>
How can I use 4-byte UTF8, <code class="literal">utf8mb4</code> with
Connector/J?
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-14-1-16">14.16: </a>
Using <code class="literal">useServerPrepStmts=false</code> and
certain character encodings can lead to corruption when
inserting BLOBs. How can this be avoided?
</p></li></ul></div><p><span class="bold"><strong>Questions and Answers</strong></span></p><p><a name="qandaitem-14-1-1"></a><span class="bold"><strong>14.1: </strong></span><span class="bold"><strong>
When I try to connect to the database with MySQL
Connector/J, I get the following exception:
</strong></span></p><pre class="programlisting">
SQLException: Server configuration denies access to data source
SQLState: 08001
VendorError: 0
</pre><p><span class="bold"><strong>
What is going on? I can connect just fine with the MySQL
command-line client.
</strong></span></p><p>
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 the connection is permitted.
</p><p>
You must add the necessary security credentials to the MySQL
server for this to happen, using the
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/grant.html" target="_top"><code class="literal">GRANT</code></a> statement to your MySQL
Server. See <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/grant.html" target="_top"><code class="literal">GRANT</code> Syntax</a>, for more information.
</p><div xmlns="http://www.w3.org/1999/xhtml" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p xmlns="">
Testing your connectivity with the
<span class="command"><strong>mysql</strong></span> command-line client will not work
unless you add the "host" flag, and use something other
than <code class="literal">localhost</code> for the host. The
<span class="command"><strong>mysql</strong></span> command-line client will use Unix
domain sockets if you use the special host name
<code class="literal">localhost</code>. If you are testing
connectivity to <code class="literal">localhost</code>, use
<code class="literal">127.0.0.1</code> as the host name instead.
</p></div><div xmlns="http://www.w3.org/1999/xhtml" class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Warning</div><p xmlns="">
Changing privileges and permissions improperly in MySQL
can potentially cause your server installation to not have
optimal security properties.
</p></div><p><a name="qandaitem-14-1-2"></a><span class="bold"><strong>14.2: </strong></span><span class="bold"><strong>
My application throws an SQLException 'No Suitable Driver'.
Why is this happening?
</strong></span></p><p>
There are three possible causes for this error:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The Connector/J driver is not in your
<code class="literal">CLASSPATH</code>, see
<a class="xref" href="#connector-j-installing" title="Chapter 3. Connector/J Installation">Chapter 3, <i>Connector/J Installation</i></a>.
</p></li><li class="listitem"><p>
The format of your connection URL is incorrect, or you
are referencing the wrong JDBC driver.
</p></li><li class="listitem"><p>
When using DriverManager, the
<code class="literal">jdbc.drivers</code> system property has not
been populated with the location of the Connector/J
driver.
</p></li></ul></div><p><a name="qandaitem-14-1-3"></a><span class="bold"><strong>14.3: </strong></span><span class="bold"><strong>
I'm trying to use MySQL Connector/J in an applet or
application and I get an exception similar to:
</strong></span></p><pre class="programlisting">
SQLException: Cannot connect to MySQL server on host:3306.
Is there a MySQL server running on the machine/port you
are trying to connect to?
(java.security.AccessControlException)
SQLState: 08S01
VendorError: 0
</pre><p>
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.
</p><p>
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.
</p><p>
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.
</p><p>
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
<code class="filename">/etc/mysql/my.cnf</code> or
<code class="filename">/etc/my.cnf</code>. Of course your
<code class="filename">my.cnf</code> file might also exist in the
<code class="filename">data</code> directory of your MySQL server, or
anywhere else (depending on how MySQL was compiled for your
system). Binaries created by us always look in
<code class="filename">/etc/my.cnf</code> and
<code class="filename"><em class="replaceable"><code>datadir</code></em>/my.cnf</code>.
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).
</p><p><a name="qandaitem-14-1-4"></a><span class="bold"><strong>14.4: </strong></span><span class="bold"><strong>
I have a servlet/application that works fine for a day, and
then stops working overnight
</strong></span></p><p>
MySQL closes connections after 8 hours of inactivity. You
either need to use a connection pool that handles stale
connections or use the <code class="option">autoReconnect</code>
parameter (see
<a class="xref" href="#connector-j-reference-configuration-properties" title="5.1. Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J">Section 5.1, “Driver/Datasource Class Names, URL Syntax and Configuration Properties
for Connector/J”</a>).
</p><p>
Also, catch <code class="literal">SQLExceptions</code> in your
application and deal 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
<code class="literal">SQLState</code> (see
<code class="literal">java.sql.SQLException.getSQLState()</code> in
your API docs) to <code class="literal">08S01</code> when it
encounters network-connectivity issues during the processing
of a query. Attempt to reconnect to MySQL at this point.
</p><p>
The following (simplistic) example shows what code that can
handle these exceptions might look like:
</p><p>
</p><div class="example"><a name="connector-j-examples-transaction-retry"></a><p class="title"><b>Example 14.1. Connector/J: Example of transaction with retry logic</b></p><div class="example-contents"><pre class="programlisting">
public void doBusinessOp() throws SQLException {
Connection conn = null;
Statement stmt = null;
ResultSet rs = null;
//
// How many times do you want to retry the transaction
// (or at least _getting_ a connection)?
//
int retryCount = 5;
boolean transactionCompleted = false;
do {
try {
conn = getConnection(); // assume getting this from a
// javax.sql.DataSource, or the
// java.sql.DriverManager
conn.setAutoCommit(false);
//
// Okay, at this point, the 'retry-ability' of the
// transaction really depends on your application logic,
// whether or not you're using autocommit (in this case
// not), and whether you're using transactional storage
// engines
//
// For this example, we'll assume that it's _not_ safe
// to retry the entire transaction, so we set retry
// count to 0 at this point
//
// If you were using exclusively transaction-safe tables,
// or your application could recover from a connection going
// bad in the middle of an operation, then you would not
// touch 'retryCount' here, and just let the loop repeat
// until retryCount == 0.
//
retryCount = 0;
stmt = conn.createStatement();
String query = "SELECT foo FROM bar ORDER BY baz";
rs = stmt.executeQuery(query);
while (rs.next()) {
}
rs.close();
rs = null;
stmt.close();
stmt = null;
conn.commit();
conn.close();
conn = null;
transactionCompleted = true;
} catch (SQLException sqlEx) {
//
// The two SQL states that are 'retry-able' are 08S01
// for a communications error, and 40001 for deadlock.
//
// Only retry if the error was due to a stale connection,
// communications problem or deadlock
//
String sqlState = sqlEx.getSQLState();
if ("08S01".equals(sqlState) || "40001".equals(sqlState)) {
retryCount -= 1;
} else {
retryCount = 0;
}
} finally {
if (rs != null) {
try {
rs.close();
} catch (SQLException sqlEx) {
// You'd probably want to log this...
}
}
if (stmt != null) {
try {
stmt.close();
} catch (SQLException sqlEx) {
// You'd probably want to log this as well...
}
}
if (conn != null) {
try {
//
// If we got here, and conn is not null, the
// transaction should be rolled back, as not
// all work has been done
try {
conn.rollback();
} finally {
conn.close();
}
} catch (SQLException sqlEx) {
//
// If we got an exception here, something
// pretty serious is going on, so we better
// pass it up the stack, rather than just
// logging it...
throw sqlEx;
}
}
}
} while (!transactionCompleted && (retryCount > 0));
}
</pre></div></div><p><br class="example-break">
</p><div xmlns="http://www.w3.org/1999/xhtml" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p xmlns="">
Use of the <code class="option">autoReconnect</code> option is not
recommended because there is no safe method of
reconnecting to the MySQL server without risking some
corruption of the connection state or database state
information. Instead, use a connection pool, which will
enable your application to connect to the MySQL server
using an available connection from the pool. The
<code class="option">autoReconnect</code> facility is deprecated, and
may be removed in a future release.
</p></div><p><a name="qandaitem-14-1-5"></a><span class="bold"><strong>14.5: </strong></span><span class="bold"><strong>
I'm trying to use JDBC 2.0 updatable result sets, and I get
an exception saying my result set is not updatable.
</strong></span></p><p>
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
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/glossary.html#glos_primary_key" target="_top">primary key</a>, the
query must select every primary key column, and the query
can only span one table (that is, no joins). This is
outlined in the JDBC specification.
</p><p>
Note that this issue only occurs when using updatable result
sets, and is caused because Connector/J is unable to
guarantee that it can identify the correct rows within the
result set to be updated without having a unique reference
to each row. There is no requirement to have a unique field
on a table if you are using
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/update.html" target="_top"><code class="literal">UPDATE</code></a> or
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/delete.html" target="_top"><code class="literal">DELETE</code></a> statements on a table
where you can individually specify the criteria to be
matched using a <code class="literal">WHERE</code> clause.
</p><p><a name="qandaitem-14-1-6"></a><span class="bold"><strong>14.6: </strong></span><span class="bold"><strong>
I cannot connect to the MySQL server using Connector/J, and
I'm sure the connection parameters are correct.
</strong></span></p><p>
Make sure that the
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/server-options.html#option_mysqld_skip-networking" target="_top"><code class="option">skip-networking</code></a> option has
not been enabled on your server. Connector/J must be able to
communicate with your server over TCP/IP; named sockets are
not supported. Also ensure that you are not filtering
connections through a firewall or other network security
system. For more information, see
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/can-not-connect-to-server.html" target="_top"><code class="literal">Can't connect to [local] MySQL server</code></a>.
</p><p><a name="qandaitem-14-1-7"></a><span class="bold"><strong>14.7: </strong></span><span class="bold"><strong>
I am trying to connect to my MySQL server within my
application, but I get the following error and stack trace:
</strong></span></p><pre class="programlisting">
java.net.SocketException
MESSAGE: Software caused connection abort: recv failed
STACKTRACE:
java.net.SocketException: Software caused connection abort: recv failed
at java.net.SocketInputStream.socketRead0(Native Method)
at java.net.SocketInputStream.read(Unknown Source)
at com.mysql.jdbc.MysqlIO.readFully(MysqlIO.java:1392)
at com.mysql.jdbc.MysqlIO.readPacket(MysqlIO.java:1414)
at com.mysql.jdbc.MysqlIO.doHandshake(MysqlIO.java:625)
at com.mysql.jdbc.Connection.createNewIO(Connection.java:1926)
at com.mysql.jdbc.Connection.<init>(Connection.java:452)
at com.mysql.jdbc.NonRegisteringDriver.connect(NonRegisteringDriver.java:411)
</pre><p>
The error probably indicates that you are using a older
version of the Connector/J JDBC driver (2.0.14 or 3.0.x) and
you are trying to connect to a MySQL server with version
4.1x or newer. The older drivers are not compatible with 4.1
or newer of MySQL as they do not support the newer
authentication mechanisms.
</p><p>
It is likely that the older version of the Connector/J
driver exists within your application directory or your
<code class="literal">CLASSPATH</code> includes the older Connector/J
package.
</p><p><a name="qandaitem-14-1-8"></a><span class="bold"><strong>14.8: </strong></span><span class="bold"><strong>
My application is deployed through JBoss and I am using
transactions to handle the statements on the MySQL database.
Under heavy loads, I am getting an error and stack trace,
but these only occur after a fixed period of heavy activity.
</strong></span></p><p>
This is a JBoss, not Connector/J, issue and is connected to
the use of transactions. Under heavy loads the time taken
for transactions to complete can increase, and the error is
caused because you have exceeded the predefined timeout.
</p><p>
You can increase the timeout value by setting the
<code class="literal">TransactionTimeout</code> attribute to the
<code class="literal">TransactionManagerService</code> within the
<code class="filename">/conf/jboss-service.xml</code> file
(pre-4.0.3) or <code class="filename">/deploy/jta-service.xml</code>
for JBoss 4.0.3 or later. See
<a class="ulink" href="http://wiki.jboss.org/wiki/Wiki.jsp?page=TransactionTimeout" target="_top">TransactionTimeout</a>
within the JBoss wiki for more information.
</p><p><a name="qandaitem-14-1-9"></a><span class="bold"><strong>14.9: </strong></span><span class="bold"><strong>
When using <span class="command"><strong>gcj</strong></span>, a
<code class="literal">java.io.CharConversionException</code> exception
is raised when working with certain character sequences.
</strong></span></p><p>
This is a known issue with <span class="command"><strong>gcj</strong></span> which
raises an exception when it reaches an unknown character or
one it cannot convert. Add
<code class="literal">useJvmCharsetConverters=true</code> to your
connection string to force character conversion outside of
the <span class="command"><strong>gcj</strong></span> libraries, or try a different
JDK.
</p><p><a name="qandaitem-14-1-10"></a><span class="bold"><strong>14.10: </strong></span><span class="bold"><strong>
Updating a table that contains a
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/glossary.html#glos_primary_key" target="_top">primary key</a> that is
either <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/floating-point-types.html" target="_top"><code class="literal">FLOAT</code></a> or compound
primary key that uses <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/floating-point-types.html" target="_top"><code class="literal">FLOAT</code></a>
fails to update the table and raises an exception.
</strong></span></p><p>
Connector/J adds conditions to the <code class="literal">WHERE</code>
clause during an <a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/update.html" target="_top"><code class="literal">UPDATE</code></a> to
check the old values of the primary key. If there is no
match, then Connector/J considers this a failure condition
and raises an exception.
</p><p>
The problem is that rounding differences between supplied
values and the values stored in the database may mean that
the values never match, and hence the update fails. The
issue will affect all queries, not just those from
Connector/J.
</p><p>
To prevent this issue, use a primary key that does not use
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/floating-point-types.html" target="_top"><code class="literal">FLOAT</code></a>. If you have to use a
floating point column in your primary key, use
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/floating-point-types.html" target="_top"><code class="literal">DOUBLE</code></a> or
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/fixed-point-types.html" target="_top"><code class="literal">DECIMAL</code></a> types in place of
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/floating-point-types.html" target="_top"><code class="literal">FLOAT</code></a>.
</p><p><a name="qandaitem-14-1-11"></a><span class="bold"><strong>14.11: </strong></span><span class="bold"><strong>
You get an
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/error-messages-server.html#error_er_net_packet_too_large" target="_top"><code class="literal">ER_NET_PACKET_TOO_LARGE</code></a>
exception, even though the binary blob size you want to
insert using JDBC is safely below the
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/server-system-variables.html#sysvar_max_allowed_packet" target="_top"><code class="literal">max_allowed_packet</code></a> size.
</strong></span></p><p>
This is because the <code class="literal">hexEscapeBlock()</code>
method in
<code class="literal">com.mysql.jdbc.PreparedStatement.streamToBytes()</code>
may almost double the size of your data.
</p><p><a name="qandaitem-14-1-12"></a><span class="bold"><strong>14.12: </strong></span><span class="bold"><strong>
What should you do if you receive error messages similar to
the following: <span class="quote">“<span class="quote">Communications link failure – Last
packet sent to the server was X ms ago</span>”</span>?
</strong></span></p><p>
Generally speaking, this error suggests that the network
connection has been closed. There can be several root
causes:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Firewalls or routers may clamp down on idle connections
(the MySQL client/server protocol does not ping).
</p></li><li class="listitem"><p>
The MySQL Server may be closing idle connections that
exceed the <code class="literal">wait_timeout</code> or
<code class="literal">interactive_timeout</code> threshold.
</p></li></ul></div><p>
To help troubleshoot these issues, the following tips can be
used. If a recent (5.1.13+) version of Connector/J is used,
you will see an improved level of information compared to
earlier versions. Older versions simply display the last
time a packet was sent to the server, which is frequently 0
ms ago. This is of limited use, as it may be that a packet
was just sent, while a packet from the server has not been
received for several hours. Knowing the period of time since
Connector/J last received a packet from the server is useful
information, so if this is not displayed in your exception
message, it is recommended that you update Connector/J.
</p><p>
Further, if the time a packet was last sent/received exceeds
the <code class="literal">wait_timeout</code> or
<code class="literal">interactive_timeout</code> threshold, this is
noted in the exception message.
</p><p>
Although network connections can be volatile, the following
can be helpful in avoiding problems:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Ensure connections are valid when used from the
connection pool. Use a query that starts with
<code class="literal">/* ping */</code> to execute a lightweight
ping instead of full query. Note, the syntax of the ping
needs to be exactly as specified here.
</p></li><li class="listitem"><p>
Minimize the duration a connection object is left idle
while other application logic is executed.
</p></li><li class="listitem"><p>
Explicitly validate the connection before using it if
the connection has been left idle for an extended period
of time.
</p></li><li class="listitem"><p>
Ensure that <code class="literal">wait_timeout</code> and
<code class="literal">interactive_timeout</code> are set
sufficiently high.
</p></li><li class="listitem"><p>
Ensure that <code class="literal">tcpKeepalive</code> is enabled.
</p></li><li class="listitem"><p>
Ensure that any configurable firewall or router timeout
settings allow for the maximum expected connection idle
time.
</p></li></ul></div><div xmlns="http://www.w3.org/1999/xhtml" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p xmlns="">
Do not expect to be able to reuse a connection without
problems, if it has being lying idle for a period. If a
connection is to be reused after being idle for any length
of time, ensure that you explicitly test it before reusing
it.
</p></div><p><a name="qandaitem-14-1-13"></a><span class="bold"><strong>14.13: </strong></span><span class="bold"><strong>
Why does Connector/J not reconnect to MySQL and re-issue the
statement after a communication failure, instead of throwing
an Exception, even though I use the
<code class="literal">autoReconnect</code> connection string option?
</strong></span></p><p>
There are several reasons for this. The first is
transactional integrity. The MySQL Reference Manual states
that <span class="quote">“<span class="quote">there is no safe method of reconnecting to the
MySQL server without risking some corruption of the
connection state or database state information</span>”</span>.
Consider the following series of statements for example:
</p><pre class="programlisting">
conn.createStatement().execute(
"UPDATE checking_account SET balance = balance - 1000.00 WHERE customer='Smith'");
conn.createStatement().execute(
"UPDATE savings_account SET balance = balance + 1000.00 WHERE customer='Smith'");
conn.commit();
</pre><p>
Consider the case where the connection to the server fails
after the <code class="literal">UPDATE</code> to
<code class="literal">checking_account</code>. If no exception is
thrown, and the application never learns about the problem,
it will continue executing. However, the server did not
commit the first transaction in this case, so that will get
rolled back. But execution continues with the next
transaction, and increases the
<code class="literal">savings_account</code> balance by 1000. The
application did not receive an exception, so it continued
regardless, eventually committing the second transaction, as
the commit only applies to the changes made in the new
connection. Rather than a transfer taking place, a deposit
was made in this example.
</p><p>
Note that running with <code class="literal">autocommit</code> enabled
does not solve this problem. When Connector/J encounters a
communication problem, there is no means to determine
whether the server processed the currently executing
statement or not. The following theoretical states are
equally possible:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The server never received the statement, and therefore
no related processing occurred on the server.
</p></li><li class="listitem"><p>
The server received the statement, executed it in full,
but the response was not received by the client.
</p></li></ul></div><p>
If you are running with <code class="literal">autocommit</code>
enabled, it is not possible to guarantee the state of data
on the server when a communication exception is encountered.
The statement may have reached the server, or it may not.
All you know is that communication failed at some point,
before the client received confirmation (or data) from the
server. This does not only affect
<code class="literal">autocommit</code> statements though. If the
communication problem occurred during
<code class="literal">Connection.commit()</code>, the question arises
of whether the transaction was committed on the server
before the communication failed, or whether the server
received the commit request at all.
</p><p>
The second reason for the generation of exceptions is that
transaction-scoped contextual data may be vulnerable, for
example:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Temporary tables.
</p></li><li class="listitem"><p>
User-defined variables.
</p></li><li class="listitem"><p>
Server-side prepared statements.
</p></li></ul></div><p>
These items are lost when a connection fails, and if the
connection silently reconnects without generating an
exception, this could be detrimental to the correct
execution of your application.
</p><p>
In summary, communication errors generate conditions that
may well be unsafe for Connector/J to simply ignore by
silently reconnecting. It is necessary for the application
to be notified. It is then for the application developer to
decide how to proceed in the event of connection errors and
failures.
</p><p><a name="qandaitem-14-1-14"></a><span class="bold"><strong>14.14: </strong></span><span class="bold"><strong>
How can I use 3-byte UTF8 with Connector/J?
</strong></span></p><p>
To use 3-byte UTF8 with Connector/J set
<code class="literal">characterEncoding=utf8</code> and set
<code class="literal">useUnicode=true</code> in the connection string.
</p><p><a name="qandaitem-14-1-15"></a><span class="bold"><strong>14.15: </strong></span><span class="bold"><strong>
How can I use 4-byte UTF8, <code class="literal">utf8mb4</code> with
Connector/J?
</strong></span></p><p>
To use 4-byte UTF8 with Connector/J configure the MySQL
server with <code class="literal">character_set_server=utf8mb4</code>.
Connector/J will then use that setting as long as
<code class="literal">characterEncoding</code> has not been set in the
connection string. This is equivalent to autodetection of
the character set.
</p><p><a name="qandaitem-14-1-16"></a><span class="bold"><strong>14.16: </strong></span><span class="bold"><strong>
Using <code class="literal">useServerPrepStmts=false</code> and
certain character encodings can lead to corruption when
inserting BLOBs. How can this be avoided?
</strong></span></p><p>
When using certain character encodings, such as SJIS, CP932,
and BIG5, it is possible that BLOB data contains characters
that can be interpreted as control characters, for example,
backslash, '\'. This can lead to corrupted data when
inserting BLOBs into the database. There are two things that
need to be done to avoid this:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Set the connection string option
<code class="literal">useServerPrepStmts</code> to
<code class="literal">true</code>.
</p></li><li class="listitem"><p>
Set <code class="literal">SQL_MODE</code> to
<code class="literal">NO_BACKSLASH_ESCAPES</code>.
</p></li></ol></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-known-issues-limitations"></a>Chapter 15. Known Issues and Limitations</h1></div></div></div><a class="indexterm" name="idm47020250000960"></a><a class="indexterm" name="idm47020249999744"></a><a class="indexterm" name="idm47020249998528"></a><a class="indexterm" name="idm47020249997312"></a><a class="indexterm" name="idm47020249996096"></a><p>
The following are some known issues and limitations for MySQL
Connector/J:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
When Connector/J retrieves timestamps for a daylight saving
time (DST) switch day using the
<code class="function">getTimeStamp()</code> method on the result set,
some of the returned values might be wrong. The errors can be
avoided by using the following connection options when
connecting to a database:
</p><pre class="programlisting">
useTimezone=true
useLegacyDatetimeCode=false
serverTimezone=UTC
</pre><p>
</p></li></ul></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-support"></a>Chapter 16. Connector/J Support</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-support-community">16.1. Connector/J Community Support</a></span></dt><dt><span class="section"><a href="#connector-j-support-bug-report">16.2. How to Report Connector/J Bugs or Problems</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-support-community"></a>16.1. Connector/J Community Support</h2></div></div></div><p>
Oracle provides assistance to the user community by means of its
mailing lists. For Connector/J related issues, you can get help
from experienced users by using the MySQL and Java mailing list.
Archives and subscription information is available online at
<a class="ulink" href="http://lists.mysql.com/java" target="_top">http://lists.mysql.com/java</a>.
</p><p>
For information about subscribing to MySQL mailing lists or to
browse list archives, visit
<a class="ulink" href="http://lists.mysql.com/" target="_top">http://lists.mysql.com/</a>. See
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/mailing-lists.html" target="_top">MySQL Mailing Lists</a>.
</p><p>
Community support from experienced users is also available
through the <a class="ulink" href="http://forums.mysql.com/list.php?39" target="_top">JDBC
Forum</a>. You may also find help from other users in the
other MySQL Forums, located at
<a class="ulink" href="http://forums.mysql.com" target="_top">http://forums.mysql.com</a>. See
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.6/en/forums.html" target="_top">MySQL Community Support at the MySQL Forums</a>.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-support-bug-report"></a>16.2. How to Report Connector/J Bugs or Problems</h2></div></div></div><a class="indexterm" name="idm47020249983008"></a><p>
The normal place to report bugs is
<a class="ulink" href="http://bugs.mysql.com/" target="_top">http://bugs.mysql.com/</a>, 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.
</p><p>
If you find a sensitive security bug in MySQL Server, please let
us know immediately by sending an email message to
<code class="email"><<a class="email" href="mailto:secalert_us@oracle.com">secalert_us@oracle.com</a>></code>. Exception: Support
customers should report all problems, including security bugs,
to Oracle Support at <a class="ulink" href="http://support.oracle.com/" target="_top">http://support.oracle.com/</a>.
</p><p>
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.
</p><p>
This section will help you write your report correctly so that
you do not waste your time doing things that may not help us
much or at all.
</p><p>
If you have a repeatable bug report, please report it to the
bugs database at <a class="ulink" href="http://bugs.mysql.com/" target="_top">http://bugs.mysql.com/</a>. Any bug
that we are able to repeat has a high chance of being fixed in
the next MySQL release.
</p><p>
To report other problems, you can use one of the MySQL mailing
lists.
</p><p>
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 do not matter.
</p><p>
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.
</p><p>
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).
</p><p>
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, <span class="quote">“<span class="quote">Why doesn't this work for me?</span>”</span>
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.
</p><p>
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.
</p><p>
If at all possible, create a repeatable, standalone testcase
that doesn't involve any third-party classes.
</p><p>
To streamline this process, we ship a base class for testcases
with Connector/J, named
'<code class="classname">com.mysql.jdbc.util.BaseBugReport</code>'. To
create a testcase for Connector/J using this class, create your
own class that inherits from
<code class="classname">com.mysql.jdbc.util.BaseBugReport</code> and
override the methods <code class="function">setUp()</code>,
<code class="function">tearDown()</code> and
<code class="function">runTest()</code>.
</p><p>
In the <code class="function">setUp()</code> method, create code that
creates your tables, and populates them with any data needed to
demonstrate the bug.
</p><p>
In the <code class="function">runTest()</code> method, create code that
demonstrates the bug using the tables and data you created in
the <code class="literal">setUp</code> method.
</p><p>
In the <code class="function">tearDown()</code> method, drop any tables
you created in the <code class="function">setUp()</code> method.
</p><p>
In any of the above three methods, use one of the variants of
the <code class="function">getConnection()</code> method to create a JDBC
connection to MySQL:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<code class="function">getConnection()</code> - Provides a connection
to the JDBC URL specified in <code class="function">getUrl()</code>.
If a connection already exists, that connection is returned,
otherwise a new connection is created.
</p></li><li class="listitem"><p>
<code class="function">getNewConnection()</code> - Use this if you
need to get a new connection for your bug report (that is,
there is more than one connection involved).
</p></li><li class="listitem"><p>
<code class="function">getConnection(String url)</code> - Returns a
connection using the given URL.
</p></li><li class="listitem"><p>
<code class="function">getConnection(String url, Properties
props)</code> - Returns a connection using the given URL
and properties.
</p></li></ul></div><p>
If you need to use a JDBC URL that is different from
'jdbc:mysql:///test', override the method
<code class="function">getUrl()</code> as well.
</p><p>
Use the <code class="function">assertTrue(boolean expression)</code> and
<code class="function">assertTrue(String failureMessage, boolean
expression)</code> 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).
</p><p>
Finally, create a <code class="function">main()</code> method that
creates a new instance of your testcase, and calls the
<code class="literal">run</code> method:
</p><pre class="programlisting">
public static void main(String[] args) throws Exception {
new MyBugReport().run();
}
</pre><p>
Once you have finished your testcase, and have verified that it
demonstrates the bug you are reporting, upload it with your bug
report to <a class="ulink" href="http://bugs.mysql.com/" target="_top">http://bugs.mysql.com/</a>.
</p></div></div><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-third-party-licenses"></a>Appendix A. Licenses for Third-Party Components</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#license-ant-contrib">A.1. Ant-Contrib License</a></span></dt><dt><span class="section"><a href="#license-c3p0-0-91">A.2. c3p0 JDBC Library License</a></span></dt><dt><span class="section"><a href="#license-gnu-lgpl-2-1">A.3. GNU Lesser General Public License Version 2.1, February 1999</a></span></dt><dt><span class="section"><a href="#license-jboss-common-jdbc-wrapper">A.4. jboss-common-jdbc-wrapper.jar License</a></span></dt><dt><span class="section"><a href="#license-nanoxml">A.5. NanoXML License</a></span></dt><dt><span class="section"><a href="#license-rox-jar">A.6. rox.jar License</a></span></dt><dt><span class="section"><a href="#license-slf4j">A.7. Simple Logging Facade for Java (SLF4J) License</a></span></dt></dl></div><h2><a name="idm47020249948128"></a>MySQL Connector/J</h2><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="#license-ant-contrib" title="A.1. Ant-Contrib License">Section A.1, “Ant-Contrib License”</a></p></li><li class="listitem"><p><a class="xref" href="#license-c3p0-0-91" title="A.2. c3p0 JDBC Library License">Section A.2, “c3p0 JDBC Library License”</a></p></li><li class="listitem"><p><a class="xref" href="#license-gnu-lgpl-2-1" title="A.3. GNU Lesser General Public License Version 2.1, February 1999">Section A.3, “GNU Lesser General Public License Version 2.1, February 1999”</a></p></li><li class="listitem"><p><a class="xref" href="#license-jboss-common-jdbc-wrapper" title="A.4. jboss-common-jdbc-wrapper.jar License">Section A.4, “jboss-common-jdbc-wrapper.jar License”</a></p></li><li class="listitem"><p><a class="xref" href="#license-nanoxml" title="A.5. NanoXML License">Section A.5, “NanoXML License”</a></p></li><li class="listitem"><p><a class="xref" href="#license-rox-jar" title="A.6. rox.jar License">Section A.6, “rox.jar License”</a></p></li><li class="listitem"><p><a class="xref" href="#license-slf4j" title="A.7. Simple Logging Facade for Java (SLF4J) License">Section A.7, “Simple Logging Facade for Java (SLF4J) License”</a></p></li></ul></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="license-ant-contrib"></a>A.1. Ant-Contrib License</h2></div></div></div><p>
The following software may be included in this product up to version 5.1.26: Ant-Contrib
</p><pre class="programlisting">
Ant-Contrib
Copyright (c) 2001-2003 Ant-Contrib project. All rights reserved.
Licensed under the Apache 1.1 License Agreement, a copy of which is reproduced below.
The Apache Software License, Version 1.1
Copyright (c) 2001-2003 Ant-Contrib project. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in
the documentation and/or other materials provided with the
distribution.
3. The end-user documentation included with the redistribution, if
any, must include the following acknowlegement:
"This product includes software developed by the
Ant-Contrib project (http://sourceforge.net/projects/ant-contrib)."
Alternately, this acknowlegement may appear in the software itself,
if and wherever such third-party acknowlegements normally appear.
4. The name Ant-Contrib must not be used to endorse or promote
products derived from this software without prior written
permission. For written permission, please contact
ant-contrib-developers@lists.sourceforge.net.
5. Products derived from this software may not be called "Ant-Contrib"
nor may "Ant-Contrib" appear in their names without prior written
permission of the Ant-Contrib project.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE ANT-CONTRIB PROJECT OR ITS
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="license-c3p0-0-91"></a>A.2. c3p0 JDBC Library License</h2></div></div></div><p>
You are receiving a copy of <code class="filename">c3p0-0.9.1-pre6.jar</code>
in both source and object code in the following
<code class="filename">/src/lib/c3p0-0.9.1-pre6.jar</code>. The terms of the
Oracle license do NOT apply to
<code class="filename">c3p0-0.9.1-pre6.jar</code>; it is licensed under the
following license, separately from the Oracle programs you receive.
If you do not wish to install this library, you may remove the file
<code class="filename">/src/lib/c3p0-0.9.1-pre6.jar</code>, but the Oracle
program might not operate properly or at all without the library.
</p><p>
This component is licensed under
<a class="xref" href="#license-gnu-lgpl-2-1" title="A.3. GNU Lesser General Public License Version 2.1, February 1999">Section A.3, “GNU Lesser General Public License Version 2.1, February 1999”</a>.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="license-gnu-lgpl-2-1"></a>A.3. GNU Lesser General Public License Version 2.1, February 1999</h2></div></div></div><pre class="programlisting">
The following applies to all products licensed under the
GNU Lesser General Public License, Version 2.1: You may
not use the identified files except in compliance with
the GNU Lesser General Public License, Version 2.1 (the
"License"). You may obtain a copy of the License at
http://www.gnu.org/licenses/lgpl-2.1.html. A copy of the
license is also reproduced below. Unless required by
applicable law or agreed to in writing, software distributed
under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
or implied. See the License for the specific language governing
permissions and limitations under the License.
GNU LESSER GENERAL PUBLIC LICENSE
Version 2.1, February 1999
Copyright (C) 1991, 1999 Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
[This is the first released version of the Lesser GPL. It also counts
as the successor of the GNU Library Public License, version 2, hence
the version number 2.1.]
Preamble
The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public
Licenses are intended to guarantee your freedom to share and change
free software--to make sure the software is free for all its users.
This license, the Lesser General Public License, applies to some
specially designated software packages--typically libraries--of the
Free Software Foundation and other authors who decide to use it. You
can use it too, but we suggest you first think carefully about whether
this license or the ordinary General Public License is the better
strategy to use in any particular case, based on the explanations below.
When we speak of free software, we are referring to freedom of use,
not price. Our General Public Licenses are designed to make sure that
you have the freedom to distribute copies of free software (and charge
for this service if you wish); that you receive source code or can get
it if you want it; that you can change the software and use pieces of
it in new free programs; and that you are informed that you can do
these things.
To protect your rights, we need to make restrictions that forbid
distributors to deny you these rights or to ask you to surrender these
rights. These restrictions translate to certain responsibilities for
you if you distribute copies of the library or if you modify it.
For example, if you distribute copies of the library, whether gratis
or for a fee, you must give the recipients all the rights that we gave
you. You must make sure that they, too, receive or can get the source
code. If you link other code with the library, you must provide
complete object files to the recipients, so that they can relink them
with the library after making changes to the library and recompiling
it. And you must show them these terms so they know their rights.
We protect your rights with a two-step method: (1) we copyright the
library, and (2) we offer you this license, which gives you legal
permission to copy, distribute and/or modify the library.
To protect each distributor, we want to make it very clear that
there is no warranty for the free library. Also, if the library is
modified by someone else and passed on, the recipients should know
that what they have is not the original version, so that the original
author's reputation will not be affected by problems that might be
introduced by others.
Finally, software patents pose a constant threat to the existence of
any free program. We wish to make sure that a company cannot
effectively restrict the users of a free program by obtaining a
restrictive license from a patent holder. Therefore, we insist that
any patent license obtained for a version of the library must be
consistent with the full freedom of use specified in this license.
Most GNU software, including some libraries, is covered by the
ordinary GNU General Public License. This license, the GNU Lesser
General Public License, applies to certain designated libraries, and
is quite different from the ordinary General Public License. We use
this license for certain libraries in order to permit linking those
libraries into non-free programs.
When a program is linked with a library, whether statically or using
a shared library, the combination of the two is legally speaking a
combined work, a derivative of the original library. The ordinary
General Public License therefore permits such linking only if the
entire combination fits its criteria of freedom. The Lesser General
Public License permits more lax criteria for linking other code with
the library.
We call this license the "Lesser" General Public License because it
does Less to protect the user's freedom than the ordinary General
Public License. It also provides other free software developers Less
of an advantage over competing non-free programs. These disadvantages
are the reason we use the ordinary General Public License for many
libraries. However, the Lesser license provides advantages in certain
special circumstances.
For example, on rare occasions, there may be a special need to
encourage the widest possible use of a certain library, so that it
becomes a de-facto standard. To achieve this, non-free programs
must be allowed to use the library. A more frequent case is that
a free library does the same job as widely used non-free libraries.
In this case, there is little to gain by limiting the free library
to free software only, so we use the Lesser General Public License.
In other cases, permission to use a particular library in non-free
programs enables a greater number of people to use a large body of
free software. For example, permission to use the GNU C Library in
non-free programs enables many more people to use the whole GNU
operating system, as well as its variant, the GNU/Linux operating
system.
Although the Lesser General Public License is Less protective of the
users' freedom, it does ensure that the user of a program that is
linked with the Library has the freedom and the wherewithal to run
that program using a modified version of the Library.
The precise terms and conditions for copying, distribution and
modification follow. Pay close attention to the difference between a
"work based on the library" and a "work that uses the library". The
former contains code derived from the library, whereas the latter must
be combined with the library in order to run.
GNU LESSER GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. This License Agreement applies to any software library or other
program which contains a notice placed by the copyright holder or
other authorized party saying it may be distributed under the terms of
this Lesser General Public License (also called "this License").
Each licensee is addressed as "you".
A "library" means a collection of software functions and/or data
prepared so as to be conveniently linked with application programs
(which use some of those functions and data) to form executables.
The "Library", below, refers to any such software library or work
which has been distributed under these terms. A "work based on the
Library" means either the Library or any derivative work under
copyright law: that is to say, a work containing the Library or a
portion of it, either verbatim or with modifications and/or translated
straightforwardly into another language. (Hereinafter, translation is
included without limitation in the term "modification".)
"Source code" for a work means the preferred form of the work for
making modifications to it. For a library, complete source code means
all the source code for all modules it contains, plus any associated
interface definition files, plus the scripts used to control
compilation and installation of the library.
Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of
running a program using the Library is not restricted, and output from
such a program is covered only if its contents constitute a work based
on the Library (independent of the use of the Library in a tool for
writing it). Whether that is true depends on what the Library does
and what the program that uses the Library does.
1. You may copy and distribute verbatim copies of the Library's
complete source code as you receive it, in any medium, provided that
you conspicuously and appropriately publish on each copy an
appropriate copyright notice and disclaimer of warranty; keep intact
all the notices that refer to this License and to the absence of any
warranty; and distribute a copy of this License along with the
Library.
You may charge a fee for the physical act of transferring a copy,
and you may at your option offer warranty protection in exchange for a
fee.
2. You may modify your copy or copies of the Library or any portion
of it, thus forming a work based on the Library, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:
a) The modified work must itself be a software library.
b) You must cause the files modified to carry prominent notices
stating that you changed the files and the date of any change.
c) You must cause the whole of the work to be licensed at no
charge to all third parties under the terms of this License.
d) If a facility in the modified Library refers to a function or a
table of data to be supplied by an application program that uses
the facility, other than as an argument passed when the facility
is invoked, then you must make a good faith effort to ensure that,
in the event an application does not supply such function or
table, the facility still operates, and performs whatever part of
its purpose remains meaningful.
(For example, a function in a library to compute square roots has
a purpose that is entirely well-defined independent of the
application. Therefore, Subsection 2d requires that any
application-supplied function or table used by this function must
be optional: if the application does not supply it, the square
root function must still compute square roots.)
These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Library,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works. But when you
distribute the same sections as part of a whole which is a work based
on the Library, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote
it.
Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Library.
In addition, mere aggregation of another work not based on the Library
with the Library (or with a work based on the Library) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.
3. You may opt to apply the terms of the ordinary GNU General Public
License instead of this License to a given copy of the Library. To do
this, you must alter all the notices that refer to this License, so
that they refer to the ordinary GNU General Public License, version 2,
instead of to this License. (If a newer version than version 2 of the
ordinary GNU General Public License has appeared, then you can specify
that version instead if you wish.) Do not make any other change in
these notices.
Once this change is made in a given copy, it is irreversible for
that copy, so the ordinary GNU General Public License applies to all
subsequent copies and derivative works made from that copy.
This option is useful when you wish to copy part of the code of
the Library into a program that is not a library.
4. You may copy and distribute the Library (or a portion or
derivative of it, under Section 2) in object code or executable form
under the terms of Sections 1 and 2 above provided that you accompany
it with the complete corresponding machine-readable source code, which
must be distributed under the terms of Sections 1 and 2 above on a
medium customarily used for software interchange.
If distribution of object code is made by offering access to copy
from a designated place, then offering equivalent access to copy the
source code from the same place satisfies the requirement to
distribute the source code, even though third parties are not
compelled to copy the source along with the object code.
5. A program that contains no derivative of any portion of the
Library, but is designed to work with the Library by being compiled or
linked with it, is called a "work that uses the Library". Such a
work, in isolation, is not a derivative work of the Library, and
therefore falls outside the scope of this License.
However, linking a "work that uses the Library" with the Library
creates an executable that is a derivative of the Library (because it
contains portions of the Library), rather than a "work that uses the
library". The executable is therefore covered by this License.
Section 6 states terms for distribution of such executables.
When a "work that uses the Library" uses material from a header file
that is part of the Library, the object code for the work may be a
derivative work of the Library even though the source code is not.
Whether this is true is especially significant if the work can be
linked without the Library, or if the work is itself a library. The
threshold for this to be true is not precisely defined by law.
If such an object file uses only numerical parameters, data
structure layouts and accessors, and small macros and small inline
functions (ten lines or less in length), then the use of the object
file is unrestricted, regardless of whether it is legally a derivative
work. (Executables containing this object code plus portions of the
Library will still fall under Section 6.)
Otherwise, if the work is a derivative of the Library, you may
distribute the object code for the work under the terms of Section 6.
Any executables containing that work also fall under Section 6,
whether or not they are linked directly with the Library itself.
6. As an exception to the Sections above, you may also combine or
link a "work that uses the Library" with the Library to produce a
work containing portions of the Library, and distribute that work
under terms of your choice, provided that the terms permit
modification of the work for the customer's own use and reverse
engineering for debugging such modifications.
You must give prominent notice with each copy of the work that the
Library is used in it and that the Library and its use are covered by
this License. You must supply a copy of this License. If the work
during execution displays copyright notices, you must include the
copyright notice for the Library among them, as well as a reference
directing the user to the copy of this License. Also, you must do one
of these things:
a) Accompany the work with the complete corresponding
machine-readable source code for the Library including whatever
changes were used in the work (which must be distributed under
Sections 1 and 2 above); and, if the work is an executable linked
with the Library, with the complete machine-readable "work that
uses the Library", as object code and/or source code, so that the
user can modify the Library and then relink to produce a modified
executable containing the modified Library. (It is understood
that the user who changes the contents of definitions files in the
Library will not necessarily be able to recompile the application
to use the modified definitions.)
b) Use a suitable shared library mechanism for linking with the
Library. A suitable mechanism is one that (1) uses at run time a
copy of the library already present on the user's computer system,
rather than copying library functions into the executable, and (2)
will operate properly with a modified version of the library, if
the user installs one, as long as the modified version is
interface-compatible with the version that the work was made with.
c) Accompany the work with a written offer, valid for at
least three years, to give the same user the materials
specified in Subsection 6a, above, for a charge no more
than the cost of performing this distribution.
d) If distribution of the work is made by offering access to copy
from a designated place, offer equivalent access to copy the above
specified materials from the same place.
e) Verify that the user has already received a copy of these
materials or that you have already sent this user a copy.
For an executable, the required form of the "work that uses the
Library" must include any data and utility programs needed for
reproducing the executable from it. However, as a special exception,
the materials to be distributed need not include anything that is
normally distributed (in either source or binary form) with the major
components (compiler, kernel, and so on) of the operating system on
which the executable runs, unless that component itself accompanies
the executable.
It may happen that this requirement contradicts the license
restrictions of other proprietary libraries that do not normally
accompany the operating system. Such a contradiction means you cannot
use both them and the Library together in an executable that you
distribute.
7. You may place library facilities that are a work based on the
Library side-by-side in a single library together with other library
facilities not covered by this License, and distribute such a combined
library, provided that the separate distribution of the work based on
the Library and of the other library facilities is otherwise
permitted, and provided that you do these two things:
a) Accompany the combined library with a copy of the same work
based on the Library, uncombined with any other library
facilities. This must be distributed under the terms of the
Sections above.
b) Give prominent notice with the combined library of the fact
that part of it is a work based on the Library, and explaining
where to find the accompanying uncombined form of the same work.
8. You may not copy, modify, sublicense, link with, or distribute
the Library except as expressly provided under this License. Any
attempt otherwise to copy, modify, sublicense, link with, or
distribute the Library is void, and will automatically terminate your
rights under this License. However, parties who have received copies,
or rights, from you under this License will not have their licenses
terminated so long as such parties remain in full compliance.
9. You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to modify or
distribute the Library or its derivative works. These actions are
prohibited by law if you do not accept this License. Therefore, by
modifying or distributing the Library (or any work based on the
Library), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Library or works based on it.
10. Each time you redistribute the Library (or any work based on the
Library), the recipient automatically receives a license from the
original licensor to copy, distribute, link with or modify the Library
subject to these terms and conditions. You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties with
this License.
11. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Library at all. For example, if a patent
license would not permit royalty-free redistribution of the Library by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Library.
If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended
to apply, and the section as a whole is intended to apply in other
circumstances.
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system which is
implemented by public license practices. Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
12. If the distribution and/or use of the Library is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Library under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded. In such case, this License incorporates
the limitation as if written in the body of this License.
13. The Free Software Foundation may publish revised and/or new
versions of the Lesser General Public License from time to time.
Such new versions will be similar in spirit to the present version,
but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Library
specifies a version number of this License which applies to it and
"any later version", you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation. If the Library does not specify a
license version number, you may choose any version ever published by
the Free Software Foundation.
14. If you wish to incorporate parts of the Library into other free
programs whose distribution conditions are incompatible with these,
write to the author to ask for permission. For software which is
copyrighted by the Free Software Foundation, write to the Free
Software Foundation; we sometimes make exceptions for this. Our
decision will be guided by the two goals of preserving the free status
of all derivatives of our free software and of promoting the sharing
and reuse of software generally.
NO WARRANTY
15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Libraries
If you develop a new library, and you want it to be of the greatest
possible use to the public, we recommend making it free software that
everyone can redistribute and change. You can do so by permitting
redistribution under these terms (or, alternatively, under the terms
of the ordinary General Public License).
To apply these terms, attach the following notices to the library.
It is safest to attach them to the start of each source file to most
effectively convey the exclusion of warranty; and each file should
have at least the "copyright" line and a pointer to where the full
notice is found.
<one line to give the library's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA
Also add information on how to contact you by electronic and paper mail.
You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the library, if
necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the
library `Frob' (a library for tweaking knobs) written by James
Random Hacker.
<signature of Ty Coon>, 1 April 1990
Ty Coon, President of Vice
That's all there is to it!
</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="license-jboss-common-jdbc-wrapper"></a>A.4. jboss-common-jdbc-wrapper.jar License</h2></div></div></div><p>
You are receiving a copy of
<code class="filename">jboss-common-jdbc-wrapper.jar</code> in both source
and object code in the following
<code class="filename">/src/lib/jboss-common-jdbc-wrapper.jar</code>. The
terms of the Oracle license do NOT apply to
<code class="filename">jboss-common-jdbc-wrapper.jar</code>; it is licensed
under the following license, separately from the Oracle programs you
receive. If you do not wish to install this library, you may remove
the file
<code class="filename">/src/lib/jboss-common-jdbc-wrapper.jar</code>, but the
Oracle program might not operate properly or at all without the
library.
</p><p>
This component is licensed under
<a class="xref" href="#license-gnu-lgpl-2-1" title="A.3. GNU Lesser General Public License Version 2.1, February 1999">Section A.3, “GNU Lesser General Public License Version 2.1, February 1999”</a>.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="license-nanoxml"></a>A.5. NanoXML License</h2></div></div></div><p>
The following software may be included in this product:
</p><p>
NanoXML
</p><pre class="programlisting">
* Copyright (C) 2000-2002 Marc De Scheemaecker, All Rights Reserved.
*
* This software is provided 'as-is', without any express or implied warranty.
* In no event will the authors be held liable for any damages arising from the
* use of this software.
*
* Permission is granted to anyone to use this software for any purpose,
* including commercial applications, and to alter it and redistribute it
* freely, subject to the following restrictions:
*
* 1. The origin of this software must not be misrepresented; you must not
* claim that you wrote the original software. If you use this software in
* a product, an acknowledgment in the product documentation would be
* appreciated but is not required.
*
* 2. Altered source versions must be plainly marked as such, and must not be
* misrepresented as being the original software.
*
* 3. This notice may not be removed or altered from any source distribution.
*
</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="license-rox-jar"></a>A.6. rox.jar License</h2></div></div></div><p>
The following software may be included in this product:
</p><p>
rox.jar
</p><pre class="programlisting">
Copyright (c) 2006, James Greenfield
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
* Neither the name of the <ORGANIZATION> nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="license-slf4j"></a>A.7. Simple Logging Facade for Java (SLF4J) License</h2></div></div></div><p>
The following software may be included in this product:
</p><pre class="programlisting">
Simple Logging Facade for Java (SLF4J)
Copyright (c) 2004-2008 QOS.ch
All rights reserved.
Permission is hereby granted, free of charge,
to any person obtaining a copy of this software
and associated documentation files (the "Software"),
to deal in the Software without restriction, including
without limitation the rights to use, copy, modify,
merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom
the Software is furnished to do so, subject to the
following conditions:
The above copyright notice and this permission notice
shall be included in all copies or substantial portions
of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY
OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
OR OTHER DEALINGS IN THE SOFTWARE.
</pre></div></div></div><div class="copyright-footer">
Copyright © 1998, 2014, Oracle and/or its affiliates. All
rights reserved.
<a href="#legalnotice">Legal Notices</a></div></body></html>