Source code: com/mysql/jdbc/Connection.java

   /*
    Copyright (C) 2002-2004 MySQL AB
   
    This program is free software; you can redistribute it and/or modify
    it under the terms of version 2 of the GNU General Public License as
    published by the Free Software Foundation.
    
   
    There are special exceptions to the terms and conditions of the GPL 
   as it is applied to this software. View the full text of the 
   exception exception in file EXCEPTIONS-CONNECTOR-J in the directory of this 
   software distribution.
  
   This program 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 General Public License for more details.
  
   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  
   */
  package com.mysql.jdbc;
  
  import java.io.IOException;
  import java.io.InputStream;
  import java.io.Reader;
  import java.io.UnsupportedEncodingException;
  import java.math.BigDecimal;
  import java.net.URL;
  import java.sql.CallableStatement;
  import java.sql.Clob;
  import java.sql.Date;
  import java.sql.ParameterMetaData;
  import java.sql.Ref;
  import java.sql.SQLException;
  import java.sql.Savepoint;
  import java.sql.Time;
  import java.sql.Timestamp;
  import java.util.ArrayList;
  import java.util.Calendar;
  import java.util.HashMap;
  import java.util.Iterator;
  import java.util.List;
  import java.util.Map;
  import java.util.Properties;
  import java.util.TimeZone;
  import java.util.TreeMap;
  
  
  /**
   * A Connection represents a session with a specific database.  Within the
   * context of a Connection, SQL statements are executed and results are
   * returned.
   * 
   * <P>
   * A Connection's database is able to provide information describing its
   * tables, its supported SQL grammar, its stored procedures, the capabilities
   * of this connection, etc.  This information is obtained with the getMetaData
   * method.
   * </p>
   *
   * @author Mark Matthews
   * @version $Id: Connection.java,v 1.31.2.85 2004/11/15 00:23:07 mmatthew Exp $
   *
   * @see java.sql.Connection
   */
  public class Connection implements java.sql.Connection {
      // The command used to "ping" the database.
      // Newer versions of MySQL server have a ping() command,
      // but this works for everything
      private static final String PING_COMMAND = "SELECT 1";
  
      /**
       * Map mysql transaction isolation level name to
       * java.sql.Connection.TRANSACTION_XXX
       */
      private static Map mapTransIsolationName2Value = null;
  
      /**
       * The mapping between MySQL charset names and Java charset names.
       * Initialized by loadCharacterSetMapping()
       */
      private static Map charsetMap;
  
      /** Table of multi-byte charsets. Initialized by loadCharacterSetMapping() */
      private static Map multibyteCharsetsMap;
  
      /** Default socket factory classname */
      private static final String DEFAULT_SOCKET_FACTORY = StandardSocketFactory.class
          .getName();
  
      static {
          loadCharacterSetMapping();
          mapTransIsolationName2Value = new HashMap(8);
          mapTransIsolationName2Value.put("READ-UNCOMMITED",
              new Integer(TRANSACTION_READ_UNCOMMITTED));
          mapTransIsolationName2Value.put("READ-UNCOMMITTED",
             new Integer(TRANSACTION_READ_UNCOMMITTED));
         mapTransIsolationName2Value.put("READ-COMMITTED",
             new Integer(TRANSACTION_READ_COMMITTED));
         mapTransIsolationName2Value.put("REPEATABLE-READ",
             new Integer(TRANSACTION_REPEATABLE_READ));
         mapTransIsolationName2Value.put("SERIALIZABLE",
             new Integer(TRANSACTION_SERIALIZABLE));
     }
 
     /**
      * Marker for character set converter not being available (not written,
      * multibyte, etc)  Used to prevent multiple instantiation requests.
      */
     private final static Object CHARSET_CONVERTER_NOT_AVAILABLE_MARKER = new Object();
     boolean parserKnowsUnicode = false;
 
     /** Internal DBMD to use for various database-version specific features */
     private DatabaseMetaData dbmd = null;
 
     /** The list of host(s) to try and connect to */
     private List hostList = null;
 
     /** A map of SQL to parsed prepared statement parameters. */
     private Map cachedPreparedStatementParams;
 
     /**
      * Holds cached mappings to charset converters to avoid static
      * synchronization and at the same time save memory (each charset
      * converter takes approx 65K of static data).
      */
     private Map charsetConverterMap = new HashMap(CharsetMapping.JAVA_TO_MYSQL_CHARSET_MAP
             .size());
 
     /** A map of statements that have had setMaxRows() called on them */
     private Map statementsUsingMaxRows;
 
     /**
      * The type map for UDTs (not implemented, but used by some third-party
      * vendors, most notably IBM WebSphere)
      */
     private Map typeMap;
 
     /** The I/O abstraction interface (network conn to MySQL server */
     private MysqlIO io = null;
 
     /** Mutex */
     private final Object mutex = new Object();
 
     /** The map of server variables that we retrieve at connection init. */
     private Map serverVariables = null;
 
     /** The driver instance that created us */
     private NonRegisteringDriver myDriver;
 
     /** Properties for this connection specified by user */
     private Properties props = null;
 
     /** The database we're currently using (called Catalog in JDBC terms). */
     private String database = null;
 
     /** If we're doing unicode character conversions, what encoding do we use? */
     private String encoding = null;
 
     /** The hostname we're connected to */
     private String host = null;
 
     /** The JDBC URL we're using */
     private String myURL = null;
 
     /** What does MySQL call this encoding? */
     private String mysqlEncodingName = null;
     private String negativeInfinityRep = MysqlDefs.MIN_DOUBLE_VAL_STRING;
     private String notANumberRep = MysqlDefs.NAN_VAL_STRING;
 
     /** The password we used */
     private String password = null;
     private String positiveInfinityRep = MysqlDefs.MAX_DOUBLE_VAL_STRING;
 
     /** Classname for socket factory */
     private String socketFactoryClassName = null;
 
     /** The user we're connected as */
     private String user = null;
 
     /** Where was the connection _explicitly_ closed by the application? */
     private Throwable explicitCloseLocation;
 
     /** If the connection was forced closed, why was it  forced closed? */
     private Throwable forcedCloseReason;
     private TimeZone defaultTimeZone;
 
     /** The timezone of the server */
     private TimeZone serverTimezone = null;
 
     /**
      * We need this 'bootstrapped', because 4.1 and newer will send fields back
      * with this even before we fill this dynamically from the server.
      */
     private String[] indexToCharsetMapping = CharsetMapping.INDEX_TO_CHARSET;
 
     /** Allow LOAD LOCAL INFILE (defaults to true) */
     private boolean allowLoadLocalInfile = true;
 
     /** Should we clear the input stream each query? */
     private boolean alwaysClearStream = false;
 
     /** Are we in autoCommit mode? */
     private boolean autoCommit = true;
 
     /** SHould we cache the parsing of prepared statements? */
     private boolean cachePreparedStatements = false;
 
     /** Should we capitalize mysql types */
     private boolean capitalizeDBMDTypes = false;
 
     /** Should we clobber streaming results on new queries, or issue an error? */
     private boolean clobberStreamingResults = false;
 
     /**
      * Should we continue processing batch commands if one fails. The JDBC spec
      * allows either way, so we let the user choose
      */
     private boolean continueBatchOnError = true;
 
     /** Should we do unicode character conversions? */
     private boolean doUnicode = false;
 
     /** When failed-over, set connection to read-only? */
     private boolean failOverReadOnly = true;
 
     /** Are we failed-over to a non-master host */
     private boolean failedOver = false;
 
     /** Does the server suuport isolation levels? */
     private boolean hasIsolationLevels = false;
 
     /** Does this version of MySQL support quoted identifiers? */
     private boolean hasQuotedIdentifiers = false;
 
     //
     // This is for the high availability :) routines
     //
     private boolean highAvailability = false;
 
     /** Ignore non-transactional table warning for rollback? */
     private boolean ignoreNonTxTables = false;
 
     /** Has this connection been closed? */
     private boolean isClosed = true;
 
     /** Should we tell MySQL that we're an interactive client? */
     private boolean isInteractiveClient = false;
 
     /** Is the server configured to use lower-case table names only? */
     private boolean lowerCaseTableNames = false;
 
     /** Has the max-rows setting been changed from the default? */
     private boolean maxRowsChanged = false;
     private boolean needsPing = false;
     private boolean negativeInfinityRepIsClipped = true;
     private boolean notANumberRepIsClipped = true;
 
     /** Do we expose sensitive information in exception and error messages? */
     private boolean paranoid = false;
 
     /** Should we do 'extra' sanity checks? */
     private boolean pedantic = false;
     private boolean positiveInfinityRepIsClipped = true;
 
     /** Should we retrieve 'info' messages from the server? */
     private boolean readInfoMsg = false;
 
     /** Are we in read-only mode? */
     private boolean readOnly = false;
 
     /**
      * If autoReconnect == true, should we attempt to reconnect at transaction
      * boundaries?
      */
     private boolean reconnectAtTxEnd = false;
 
     /** Do we relax the autoCommit semantics? (For enhydra, for example) */
     private boolean relaxAutoCommit = false;
 
     /** Do we need to correct endpoint rounding errors */
     private boolean strictFloatingPoint = false;
 
     /** Do we check all keys for updatable result sets? */
     private boolean strictUpdates = true;
 
     /** Are transactions supported by the MySQL server we are connected to? */
     private boolean transactionsSupported = false;
 
     /** Has ANSI_QUOTES been enabled on the server? */
     private boolean useAnsiQuotes = false;
 
     /** Should we use compression? */
     private boolean useCompression = false;
 
     /** Can we use the "ping" command rather than a query? */
     private boolean useFastPing = false;
 
     /** Should we tack on hostname in DBMD.getTable/ColumnPrivileges()? */
     private boolean useHostsInPrivileges = true;
     
     /** Should we only use the error message from the server when reporting
      * errors?
      */
     private boolean useOnlyServerErrorMessages = true;
 
     /** Should we use SSL? */
     private boolean useSSL = false;
 
     /**
      * Should we use stream lengths in prepared statements? (true by default ==
      * JDBC compliant)
      */
     private boolean useStreamLengthsInPrepStmts = true;
 
     /** Should we use timezone information? */
     private boolean useTimezone = false;
 
     /** Should we return PreparedStatements for UltraDev's stupid bug? */
     private boolean useUltraDevWorkAround = false;
     private boolean useUnbufferedInput = true;
     private double initialTimeout = 2.0D;
 
     /** How many hosts are in the host list? */
     private int hostListSize = 0;
 
     /** isolation level */
     private int isolationLevel = java.sql.Connection.TRANSACTION_READ_COMMITTED;
 
     /**
      * The largest packet we can send (changed once we know what the server
      * supports, we get this at connection init).
      */
     private int maxAllowedPacket = 65536;
     private int maxReconnects = 3;
 
     /**
      * The max rows that a result set can contain. Defaults to -1, which
      * according to the JDBC spec means "all".
      */
     private int maxRows = -1;
     private int netBufferLength = 16384;
 
     /** The port number we're connected to (defaults to 3306) */
     private int port = 3306;
 
     /**
      * If prepared statement caching is enabled, what should the threshold
      * length of the SQL to prepare should be in order to _not_ cache?
      */
     private int preparedStatementCacheMaxSqlSize = 256;
 
     /** If prepared statement caching is enabled, how many should we cache? */
     private int preparedStatementCacheSize = 25;
 
     /**
      * How many queries should we wait before we try to re-connect to the
      * master, when we are failing over to replicated hosts Defaults to 50
      */
     private int queriesBeforeRetryMaster = 50;
 
     /** What should we set the socket timeout to? */
     private int socketTimeout = 0; // infinite
 
     /** When did the last query finish? */
     private long lastQueryFinishedTime = 0;
 
     /** When did the master fail? */
     private long masterFailTimeMillis = 0L;
 
     /** Number of queries we've issued since the master failed */
     private long queriesIssuedFailedOver = 0;
 
     /**
      * How many seconds should we wait before retrying to connect to the master
      * if failed over? We fall back when either queriesBeforeRetryMaster or
      * secondsBeforeRetryMaster is reached.
      */
     private long secondsBeforeRetryMaster = 30L;
 
     /**
      * Creates a connection to a MySQL Server.
      *
      * @param host the hostname of the database server
      * @param port the port number the server is listening on
      * @param info a Properties[] list holding the user and password
      * @param database the database to connect to
      * @param url the URL of the connection
      * @param d the Driver instantation of the connection
      *
      * @exception java.sql.SQLException if a database access error occurs
      * @throws SQLException DOCUMENT ME!
      */
     Connection(String host, int port, Properties info, String database,
         String url, NonRegisteringDriver d) throws java.sql.SQLException {
         if (Driver.TRACE) {
             Object[] args = { host, new Integer(port), info, database, url, d };
             Debug.methodCall(this, "constructor", args);
         }
 
         this.defaultTimeZone = TimeZone.getDefault();
 
         this.serverVariables = new HashMap();
 
         if (host == null) {
             this.host = "localhost";
             hostList = new ArrayList();
             hostList.add(this.host);
         } else if (host.indexOf(",") != -1) {
             // multiple hosts separated by commas (failover)
             hostList = StringUtils.split(host, ",", true);
         } else {
             this.host = host;
             hostList = new ArrayList();
             hostList.add(this.host);
         }
 
         hostListSize = hostList.size();
         this.port = port;
 
         if (database == null) {
             database = "";
         }
 
         this.database = database;
         this.myURL = url;
         this.myDriver = d;
         this.user = info.getProperty("user");
         this.password = info.getProperty("password");
 
         if ((this.user == null) || this.user.equals("")) {
             this.user = "nobody";
         }
 
         if (this.password == null) {
             this.password = "";
         }
 
         this.props = info;
         initializeDriverProperties(info);
 
         if (Driver.DEBUG) {
             System.out.println("Connect: " + this.user + " to " + this.database);
         }
 
         try {
             createNewIO(false);
             this.dbmd = new DatabaseMetaData(this, this.database);
         } catch (java.sql.SQLException ex) {
             cleanup(ex);
 
             // don't clobber SQL exceptions
             throw ex;
         } catch (Exception ex) {
             cleanup(ex);
 
             StringBuffer mesg = new StringBuffer();
 
             if (!useParanoidErrorMessages()) {
                 mesg.append("Cannot connect to MySQL server on ");
                 mesg.append(this.host);
                 mesg.append(":");
                 mesg.append(this.port);
                 mesg.append(".\n\n");
                 mesg.append("Make sure that there is a MySQL server ");
                 mesg.append("running on the machine/port you are trying ");
                 mesg.append(
                     "to connect to and that the machine this software is "
                     + "running on ");
                 mesg.append("is able to connect to this host/port "
                     + "(i.e. not firewalled). ");
                 mesg.append(
                     "Also make sure that the server has not been started "
                     + "with the --skip-networking ");
                 mesg.append("flag.\n\n");
             } else {
                 mesg.append("Unable to connect to database.");
             }
 
             mesg.append("Underlying exception: \n\n");
             mesg.append(ex.getClass().getName());
 
             if (!this.paranoid) {
                 mesg.append(Util.stackTraceToString(ex));
             }
 
             throw new java.sql.SQLException(mesg.toString(),
                 SQLError.SQL_STATE_COMMUNICATION_LINK_FAILURE);
         }
     }
 
     /**
      * If a connection is in auto-commit mode, than all its SQL statements will
      * be executed and committed as individual transactions.  Otherwise, its
      * SQL statements are grouped into transactions that are terminated by
      * either commit() or rollback().  By default, new connections are in
      * auto- commit mode.  The commit occurs when the statement completes or
      * the next execute occurs, whichever comes first.  In the case of
      * statements returning a ResultSet, the statement completes when the last
      * row of the ResultSet has been retrieved or the ResultSet has been
      * closed.  In advanced cases, a single statement may return multiple
      * results as well as output parameter values.  Here the commit occurs
      * when all results and output param values have been retrieved.
      * 
      * <p>
      * <b>Note:</b> MySQL does not support transactions, so this method is a
      * no-op.
      * </p>
      *
      * @param autoCommit - true enables auto-commit; false disables it
      *
      * @exception java.sql.SQLException if a database access error occurs
      * @throws SQLException DOCUMENT ME!
      */
     public void setAutoCommit(boolean autoCommit) throws java.sql.SQLException {
         if (Driver.TRACE) {
             Object[] args = { new Boolean(autoCommit) };
             Debug.methodCall(this, "setAutoCommit", args);
         }
 
         checkClosed();
 
         if (this.transactionsSupported) {
             // this internal value must be set first as failover depends on it
             // being set to true to fail over (which is done by most
             // app servers and connection pools at the end of
             // a transaction), and the driver issues an implicit set
             // based on this value when it (re)-connects to a server
             // so the value holds across connections
             //
             this.autoCommit = autoCommit;
 
             //
             // This is to catch the 'edge' case of
             // autoCommit going from true -> false
             //
             if ((this.highAvailability || this.failedOver) && !this.autoCommit
                     && this.needsPing) {
                 pingAndReconnect(true);
             }
 
             String sql = "SET autocommit=" + (autoCommit ? "1" : "0");
             execSQL(sql, -1, this.database);
         } else {
             if ((autoCommit == false) && (this.relaxAutoCommit == false)) {
                 throw new SQLException("MySQL Versions Older than 3.23.15 "
                     + "do not support transactions",
                     SQLError.SQL_STATE_DRIVER_NOT_CAPABLE);
             } else {
                 this.autoCommit = autoCommit;
             }
         }
 
         return;
     }
 
     /**
      * gets the current auto-commit state
      *
      * @return Current state of the auto-commit mode
      *
      * @exception java.sql.SQLException (why?)
      *
      * @see setAutoCommit
      */
     public boolean getAutoCommit() throws java.sql.SQLException {
         if (Driver.TRACE) {
             Object[] args = new Object[0];
             Debug.methodCall(this, "getAutoCommit", args);
             Debug.returnValue(this, "getAutoCommit",
                 new Boolean(this.autoCommit));
         }
 
         return this.autoCommit;
     }
 
     /**
      * A sub-space of this Connection's database may be selected by setting a
      * catalog name.  If the driver does not support catalogs, it will
      * silently ignore this request
      * 
      * <p>
      * <b>Note:</b> MySQL's notion of catalogs are individual databases.
      * </p>
      *
      * @param catalog the database for this connection to use
      *
      * @throws java.sql.SQLException if a database access error occurs
      */
     public void setCatalog(String catalog) throws java.sql.SQLException {
         if (Driver.TRACE) {
             Object[] args = { catalog };
             Debug.methodCall(this, "setCatalog", args);
         }
 
         checkClosed();
 
         String quotedId = this.dbmd.getIdentifierQuoteString();
 
         if ((quotedId == null) || quotedId.equals(" ")) {
             quotedId = "";
         }
 
         StringBuffer query = new StringBuffer("USE ");
         query.append(quotedId);
         query.append(catalog);
         query.append(quotedId);
 
         execSQL(query.toString(), -1, catalog);
         this.database = catalog;
     }
 
     /**
      * Return the connections current catalog name, or null if no catalog name
      * is set, or we dont support catalogs.
      * 
      * <p>
      * <b>Note:</b> MySQL's notion of catalogs are individual databases.
      * </p>
      *
      * @return the current catalog name or null
      *
      * @exception java.sql.SQLException if a database access error occurs
      */
     public String getCatalog() throws java.sql.SQLException {
         if (Driver.TRACE) {
             Object[] args = new Object[0];
             Debug.methodCall(this, "getCatalog", args);
             Debug.returnValue(this, "getCatalog", this.database);
         }
 
         return this.database;
     }
 
     /**
      * Returns whether we clobber streaming results on new queries, or issue an
      * error?
      *
      * @return true if we should implicitly close streaming result sets upon
      *         receiving a new query
      */
     public boolean getClobberStreamingResults() {
         return this.clobberStreamingResults;
     }
 
     /**
      * DOCUMENT ME!
      *
      * @return DOCUMENT ME!
      */
     public boolean isClosed() {
         if (Driver.TRACE) {
             Object[] args = new Object[0];
             Debug.methodCall(this, "isClosed", args);
             Debug.returnValue(this, "isClosed", new Boolean(this.isClosed));
         }
 
         return this.isClosed;
     }
 
     /**
      * Returns the character encoding for this Connection
      *
      * @return the character encoding for this connection.
      */
     public String getEncoding() {
         return this.encoding;
     }
 
     /**
      * @see Connection#setHoldability(int)
      */
     public void setHoldability(int arg0) throws SQLException {
         // do nothing
     }
 
     /**
      * @see Connection#getHoldability()
      */
     public int getHoldability() throws SQLException {
         return ResultSet.CLOSE_CURSORS_AT_COMMIT;
     }
 
     /**
      * NOT JDBC-Compliant, but clients can use this method to determine how
      * long this connection has been idle. This time (reported in
      * milliseconds) is updated once a query has completed.
      *
      * @return number of ms that this connection has been idle, 0 if the driver
      *         is busy retrieving results.
      */
     public long getIdleFor() {
         if (this.lastQueryFinishedTime == 0) {
             return 0;
         } else {
             long now = System.currentTimeMillis();
             long idleTime = now - this.lastQueryFinishedTime;
 
             return idleTime;
         }
     }
 
     /**
      * Should we tell MySQL that we're an interactive client
      *
      * @return true if isInteractiveClient was set to true.
      */
     public boolean isInteractiveClient() {
         return isInteractiveClient;
     }
 
     /**
      * A connection's database is able to provide information describing its
      * tables, its supported SQL grammar, its stored procedures, the
      * capabilities of this connection, etc.  This information is made
      * available through a DatabaseMetaData object.
      *
      * @return a DatabaseMetaData object for this connection
      *
      * @exception java.sql.SQLException if a database access error occurs
      */
     public java.sql.DatabaseMetaData getMetaData() throws java.sql.SQLException {
         checkClosed();
 
         return new DatabaseMetaData(this, this.database);
     }
 
     /**
      * DOCUMENT ME!
      *
      * @return
      */
     public String getNegativeInfinityRep() {
         return negativeInfinityRep;
     }
 
     /**
      * DOCUMENT ME!
      *
      * @return
      */
     public boolean isNegativeInfinityRepIsClipped() {
         return negativeInfinityRepIsClipped;
     }
 
     /**
      * DOCUMENT ME!
      *
      * @return
      */
     public String getNotANumberRep() {
         return notANumberRep;
     }
 
     /**
      * DOCUMENT ME!
      *
      * @return
      */
     public boolean isNotANumberRepIsClipped() {
         return notANumberRepIsClipped;
     }
 
     /**
      * DOCUMENT ME!
      *
      * @return
      */
     public String getPositiveInfinityRep() {
         return positiveInfinityRep;
     }
 
     /**
      * DOCUMENT ME!
      *
      * @return
      */
     public boolean isPositiveInfinityRepIsClipped() {
         return positiveInfinityRepIsClipped;
     }
 
     /**
      * Should the driver do profiling?
      *
      * @param flag set to true to enable profiling.
      *
      * @throws SQLException if the connection is closed.
      */
     public void setProfileSql(boolean flag) throws SQLException {
         // For re-connection
         this.props.setProperty("profileSql", String.valueOf(flag));
         getIO().setProfileSql(flag);
     }
 
     /**
      * You can put a connection in read-only mode as a hint to enable database
      * optimizations <B>Note:</B> setReadOnly cannot be called while in the
      * middle of a transaction
      *
      * @param readOnly - true enables read-only mode; false disables it
      *
      * @exception java.sql.SQLException if a database access error occurs
      */
     public void setReadOnly(boolean readOnly) throws java.sql.SQLException {
         if (Driver.TRACE) {
             Object[] args = { new Boolean(readOnly) };
             Debug.methodCall(this, "setReadOnly", args);
             Debug.returnValue(this, "setReadOnly", new Boolean(readOnly));
         }
 
         checkClosed();
         this.readOnly = readOnly;
     }
 
     /**
      * Tests to see if the connection is in Read Only Mode.  Note that we
      * cannot really put the database in read only mode, but we pretend we can
      * by returning the value of the readOnly flag
      *
      * @return true if the connection is read only
      *
      * @exception java.sql.SQLException if a database access error occurs
      */
     public boolean isReadOnly() throws java.sql.SQLException {
         if (Driver.TRACE) {
             Object[] args = new Object[0];
             Debug.methodCall(this, "isReadOnly", args);
             Debug.returnValue(this, "isReadOnly", new Boolean(this.readOnly));
         }
 
         return this.readOnly;
     }
 
     /**
      * @see Connection#setSavepoint()
      */
     public java.sql.Savepoint setSavepoint() throws SQLException {
         throw new NotImplemented();
     }
 
     /**
      * @see Connection#setSavepoint(String)
      */
     public java.sql.Savepoint setSavepoint(String arg0)
         throws SQLException {
         throw new NotImplemented();
     }
 
     /**
      * DOCUMENT ME!
      *
      * @return DOCUMENT ME!
      */
     public TimeZone getServerTimezone() {
         return this.serverTimezone;
     }
 
     /**
      * DOCUMENT ME!
      *
      * @param level DOCUMENT ME!
      *
      * @throws java.sql.SQLException DOCUMENT ME!
      * @throws SQLException DOCUMENT ME!
      */
     public void setTransactionIsolation(int level) throws java.sql.SQLException {
         if (Driver.TRACE) {
             Object[] args = { new Integer(level) };
             Debug.methodCall(this, "setTransactionIsolation", args);
         }
 
         checkClosed();
 
         if (this.hasIsolationLevels) {
             StringBuffer sql = new StringBuffer(
                     "SET SESSION TRANSACTION ISOLATION LEVEL ");
 
             switch (level) {
             case java.sql.Connection.TRANSACTION_NONE:
                 throw new SQLException("Transaction isolation level "
                     + "NONE not supported by MySQL");
 
             case java.sql.Connection.TRANSACTION_READ_COMMITTED:
                 sql.append("READ COMMITTED");
 
                 break;
 
             case java.sql.Connection.TRANSACTION_READ_UNCOMMITTED:
                 sql.append("READ UNCOMMITTED");
 
                 break;
 
             case java.sql.Connection.TRANSACTION_REPEATABLE_READ:
                 sql.append("REPEATABLE READ");
 
                 break;
 
             case java.sql.Connection.TRANSACTION_SERIALIZABLE:
                 sql.append("SERIALIZABLE");
 
                 break;
 
             default:
                 throw new SQLException("Unsupported transaction "
                     + "isolation level '" + level + "'", "S1C00");
             }
 
             execSQL(sql.toString(), -1, this.database);
             isolationLevel = level;
         } else {
             throw new java.sql.SQLException("Transaction Isolation Levels are "
                 + "not supported on MySQL versions older than 3.23.36.", "S1C00");
         }
     }
 
     /**
      * Get this Connection's current transaction isolation mode.
      *
      * @return the current TRANSACTION_ mode value
      *
      * @exception java.sql.SQLException if a database access error occurs
      * @throws SQLException DOCUMENT ME!
      */
     public int getTransactionIsolation() throws java.sql.SQLException {
         if (Driver.TRACE) {
             Object[] args = new Object[0];
             Debug.methodCall(this, "getTransactionIsolation", args);
             Debug.returnValue(this, "getTransactionIsolation",
                 new Integer(isolationLevel));
         }
 
         if (this.hasIsolationLevels) {
             java.sql.Statement stmt = null;
             java.sql.ResultSet rs = null;
 
             try {
                 stmt = this.createStatement();
 
                 if (stmt.getMaxRows() != 0) {
                     stmt.setMaxRows(0);
                 }
 
                 String query = null;
 
                 if (this.io.versionMeetsMinimum(4, 0, 3)) {
                     query = "SHOW VARIABLES LIKE 'tx_isolation'";
                 } else {
                     query = "SHOW VARIABLES LIKE 'transaction_isolation'";
                 }
 
                 rs = stmt.executeQuery(query);
 
                 if (rs.next()) {
                     String s = rs.getString(2);
 
                     if (s != null) {
                         Integer intTI = (Integer) mapTransIsolationName2Value
                             .get(s);
 
                         if (intTI != null) {
                             return intTI.intValue();
                         }
                     }
 
                     throw new SQLException(
                         "Could not map transaction isolation '" + s
                         + " to a valid JDBC level.",
                         SQLError.SQL_STATE_GENERAL_ERROR);
                 } else {
                     throw new SQLException("Could not retrieve transaction isolation level from server",
                         SQLError.SQL_STATE_GENERAL_ERROR);
                 }
             } finally {
                 if (rs != null) {
                     try {
                         rs.close();
                     } catch (Exception ex) {
                         // ignore
                     }
 
                     rs = null;
                 }
 
                 if (stmt != null) {
                     try {
                         stmt.close();
                     } catch (Exception ex) {
                         // ignore
                     }
 
                     stmt = null;
                 }
             }
         }
 
         return isolationLevel;
    }

    /**
     * JDBC 2.0 Install a type-map object as the default type-map for this
     * connection
     *
     * @param map the type mapping
     *
     * @throws SQLException if a database error occurs.
     */
    public void setTypeMap(java.util.Map map) throws SQLException {
        this.typeMap = map;
    }

    /**
     * JDBC 2.0 Get the type-map object associated with this connection. By
     * default, the map returned is empty.
     *
     * @return the type map
     *
     * @throws SQLException if a database error occurs
     */
    public synchronized java.util.Map getTypeMap() throws SQLException {
        if (this.typeMap == null) {
            this.typeMap = new HashMap();
        }

        return this.typeMap;
    }

    /**
     * The first warning reported by calls on this Connection is returned.
     * <B>Note:</B> Sebsequent warnings will be changed to this
     * java.sql.SQLWarning
     *
     * @return the first java.sql.SQLWarning or null
     *
     * @exception java.sql.SQLException if a database access error occurs
     */
    public java.sql.SQLWarning getWarnings() throws java.sql.SQLException {
        if (Driver.TRACE) {
            Object[] args = new Object[0];
            Debug.methodCall(this, "getWarnings", args);
            Debug.returnValue(this, "getWarnings", null);
        }

        return null;
    }

    /**
     * Allow use of LOAD LOCAL INFILE?
     *
     * @return true if allowLoadLocalInfile was set to true.
     */
    public boolean allowLoadLocalInfile() {
        return this.allowLoadLocalInfile;
    }

    /**
     * DOCUMENT ME!
     *
     * @return DOCUMENT ME!
     */
    public boolean capitalizeDBMDTypes() {
        return this.capitalizeDBMDTypes;
    }

    /**
     * Changes the user on this connection by performing a re-authentication.
     * If authentication fails, the connection will remain under the context
     * of the current user.
     *
     * @param userName the username to authenticate with
     * @param newPassword the password to authenticate with
     *
     * @throws SQLException if authentication fails, or some other error occurs
     *         while performing the command.
     */
    public void changeUser(String userName, String newPassword)
        throws SQLException {
        if ((userName == null) || userName.equals("")) {
            userName = "";
        }

        if (newPassword == null) {
            newPassword = "";
        }

        this.io.changeUser(userName, newPassword, this.database);
        this.user = userName;
        this.password = newPassword;
        
        if (this.io.versionMeetsMinimum(4, 1, 0)) {
          configureClientCharacterSet();
        }
    }

    /**
     * After this call, getWarnings returns null until a new warning is
     * reported for this connection.
     *
     * @exception java.sql.SQLException if a database access error occurs
     */
    public void clearWarnings() throws java.sql.SQLException {
        if (Driver.TRACE) {
            Object[] args = new Object[0];
            Debug.methodCall(this, "clearWarnings", args);
        }

        // firstWarning = null;
    }

    /**
     * In some cases, it is desirable to immediately release a Connection's
     * database and JDBC resources instead of waiting for them to be
     * automatically released (cant think why off the top of my head)
     * <B>Note:</B> A Connection is automatically closed when it is garbage
     * collected.  Certain fatal errors also result in a closed connection.
     *
     * @exception java.sql.SQLException if a database access error occurs
     */
    public void close() throws java.sql.SQLException {
        if (this.explicitCloseLocation == null) {
            this.explicitCloseLocation = new Throwable();
        }

        realClose(true, true);
    }

    /**
     * The method commit() makes all changes made since the previous
     * commit/rollback permanent and releases any database locks currently
     * held by the Connection.  This method should only be used when
     * auto-commit has been disabled.
     *
     * @exception java.sql.SQLException if a database access error occurs
     *
     * @see setAutoCommit
     */
    public void commit() throws java.sql.SQLException {
        if (Driver.TRACE) {
            Object[] args = new Object[0];
            Debug.methodCall(this, "commit", args);
        }

        checkClosed();

        try {
            // no-op if _relaxAutoCommit == true
            if (this.autoCommit && !this.relaxAutoCommit) {
                throw new SQLException("Can't call commit when autocommit=true",
                    SQLError.SQL_STATE_GENERAL_ERROR);
            } else if (this.transactionsSupported) {
                execSQL("commit", -1, this.database);
            }
        } finally {
            if (this.reconnectAtTxEnd) {
                pingAndReconnect(true);
            }
        }

        return;
    }

    //--------------------------JDBC 2.0-----------------------------

    /**
     * JDBC 2.0 Same as createStatement() above, but allows the default result
     * set type and result set concurrency type to be overridden.
     *
     * @param resultSetType a result set type, see ResultSet.TYPE_XXX
     * @param resultSetConcurrency a concurrency type, see ResultSet.CONCUR_XXX
     *
     * @return a new Statement object
     *
     * @exception SQLException if a database-access error occurs.
     */
    public java.sql.Statement createStatement(int resultSetType,
        int resultSetConcurrency) throws SQLException {
        checkClosed();

        Statement stmt = new com.mysql.jdbc.Statement(this, this.database);
        stmt.setResultSetType(resultSetType);
        stmt.setResultSetConcurrency(resultSetConcurrency);

        return stmt;
    }

    /**
     * SQL statements without parameters are normally executed using Statement
     * objects.  If the same SQL statement is executed many times, it is more
     * efficient to use a PreparedStatement
     *
     * @return a new Statement object
     *
     * @throws SQLException passed through from the constructor
     */
    public java.sql.Statement createStatement() throws SQLException {
        return createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY,
            java.sql.ResultSet.CONCUR_READ_ONLY);
    }

    /**
     * @see Connection#createStatement(int, int, int)
     */
    public java.sql.Statement createStatement(int resultSetType,
        int resultSetConcurrency, int resultSetHoldability)
        throws SQLException {
        if (this.pedantic) {
            if (resultSetHoldability != ResultSet.HOLD_CURSORS_OVER_COMMIT) {
                throw new SQLException("HOLD_CUSRORS_OVER_COMMIT is only supported holdability level",
                    SQLError.SQL_STATE_ILLEGAL_ARGUMENT);
            }
        }

        return createStatement(resultSetType, resultSetConcurrency);
    }

    /**
     * Cleanup the connection.
     *
     * @throws Throwable if an error occurs during cleanup.
     */
    protected void finalize() throws Throwable {
        cleanup(null);
    }

    /**
     * Is the server configured to use lower-case table names only?
     *
     * @return true if lower_case_table_names is 'on'
     */
    public boolean lowerCaseTableNames() {
        return this.lowerCaseTableNames;
    }

    /**
     * A driver may convert the JDBC sql grammar into its system's native SQL
     * grammar prior to sending it; nativeSQL returns the native form of the
     * statement that the driver would have sent.
     *
     * @param sql a SQL statement that may contain one or more '?' parameter
     *        placeholders
     *
     * @return the native form of this statement
     *
     * @exception java.sql.SQLException if a database access error occurs
     */
    public String nativeSQL(String sql) throws java.sql.SQLException {
        if (Driver.TRACE) {
            Object[] args = { sql };
            Debug.methodCall(this, "nativeSQL", args);
            Debug.returnValue(this, "nativeSQL", sql);
        }

        return EscapeProcessor.escapeSQL(sql,
            getIO().versionMeetsMinimum(4, 0, 2));
    }

    /**
     * DOCUMENT ME!
     *
     * @return DOCUMENT ME!
     */
    public boolean parserKnowsUnicode() {
        return this.parserKnowsUnicode;
    }

    /**
     * DOCUMENT ME!
     *
     * @param sql DOCUMENT ME!
     *
     * @return DOCUMENT ME!
     *
     * @throws java.sql.SQLException DOCUMENT ME!
     */
    public java.sql.CallableStatement prepareCall(String sql)
        throws java.sql.SQLException {
        if (this.getUseUltraDevWorkAround()) {
            return new UltraDevWorkAround(prepareStatement(sql));
        } else {
            throw new java.sql.SQLException("Callable statments not "
                + "supported.", "S1C00");
        }
    }

    /**
     * JDBC 2.0 Same as prepareCall() above, but allows the default result set
     * type and result set concurrency type to be overridden.
     *
     * @param sql the SQL representing the callable statement
     * @param resultSetType a result set type, see ResultSet.TYPE_XXX
     * @param resultSetConcurrency a concurrency type, see ResultSet.CONCUR_XXX
     *
     * @return a new CallableStatement object containing the pre-compiled SQL
     *         statement
     *
     * @exception SQLException if a database-access error occurs.
     */
    public java.sql.CallableStatement prepareCall(String sql,
        int resultSetType, int resultSetConcurrency) throws SQLException {
        return prepareCall(sql);
    }

    /**
     * @see Connection#prepareCall(String, int, int, int)
     */
    public java.sql.CallableStatement prepareCall(String sql,
        int resultSetType, int resultSetConcurrency, int resultSetHoldability)
        throws SQLException {
        if (this.pedantic) {
            if (resultSetHoldability != ResultSet.HOLD_CURSORS_OVER_COMMIT) {
                throw new SQLException("HOLD_CUSRORS_OVER_COMMIT is only supported holdability level",
                    SQLError.SQL_STATE_ILLEGAL_ARGUMENT);
            }
        }

        throw new NotImplemented();
    }

    /**
     * A SQL statement with or without IN parameters can be pre-compiled and
     * stored in a PreparedStatement object.  This object can then be used to
     * efficiently execute this statement multiple times.
     * 
     * <p>
     * <B>Note:</B> This method is optimized for handling parametric SQL
     * statements that benefit from precompilation if the driver supports
     * precompilation. In this case, the statement is not sent to the database
     * until the PreparedStatement is executed.  This has no direct effect on
     * users; however it does affect which method throws certain
     * java.sql.SQLExceptions
     * </p>
     * 
     * <p>
     * MySQL does not support precompilation of statements, so they are handled
     * by the driver.
     * </p>
     *
     * @param sql a SQL statement that may contain one or more '?' IN parameter
     *        placeholders
     *
     * @return a new PreparedStatement object containing the pre-compiled
     *         statement.
     *
     * @exception java.sql.SQLException if a database access error occurs.
     */
    public java.sql.PreparedStatement prepareStatement(String sql)
        throws java.sql.SQLException {
        return prepareStatement(sql, java.sql.ResultSet.TYPE_FORWARD_ONLY,
            java.sql.ResultSet.CONCUR_READ_ONLY);
    }

    /**
     * JDBC 2.0 Same as prepareStatement() above, but allows the default result
     * set type and result set concurrency type to be overridden.
     *
     * @param sql the SQL query containing place holders
     * @param resultSetType a result set type, see ResultSet.TYPE_XXX
     * @param resultSetConcurrency a concurrency type, see ResultSet.CONCUR_XXX
     *
     * @return a new PreparedStatement object containing the pre-compiled SQL
     *         statement
     *
     * @exception SQLException if a database-access error occurs.
     */
    public synchronized java.sql.PreparedStatement prepareStatement(
        String sql, int resultSetType, int resultSetConcurrency)
        throws SQLException {
        checkClosed();

        PreparedStatement pStmt = null;

        if (this.cachePreparedStatements) {
            PreparedStat