/*
 Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved.
 

  The MySQL Connector/J is licensed under the terms of the GPLv2
  <http://www.gnu.org/licenses/old-licenses/gpl-2.0.html>, like most MySQL Connectors.
  There are special exceptions to the terms and conditions of the GPLv2 as it is applied to
  this software, see the FLOSS License Exception
  <http://www.mysql.com/about/legal/licensing/foss-exception.html>.

  This program is free software; you can redistribute it and/or modify it under the terms
  of the GNU General Public License as published by the Free Software Foundation; version 2
  of the License.

  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., 51 Franklin St, Fifth
  Floor, Boston, MA 02110-1301  USA

*/

package com.mysql.jdbc;

import java.sql.SQLException;
import java.util.Properties;
import java.util.TimeZone;
import java.util.concurrent.Executor;

import com.mysql.jdbc.log.Log;

/**
 * This interface contains methods that are considered the "vendor extension"
 * to the JDBC API for MySQL's implementation of java.sql.Connection.
 * 
 * For those looking further into the driver implementation, it is not
 * an API that is used for plugability of implementations inside our driver
 * (which is why there are still references to ConnectionImpl throughout the
 * code).
 * 
 * @version $Id: $
 *
 */
public interface Connection extends java.sql.Connection, ConnectionProperties {

	/**
	 * 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 abstract void changeUser(String userName, String newPassword)
			throws SQLException;

	public abstract void clearHasTriedMaster();

	/**
	 * Prepares a statement on the client, using client-side emulation 
	 * (irregardless of the configuration property 'useServerPrepStmts') 
	 * with the same semantics as the java.sql.Connection.prepareStatement() 
	 * method with the same argument types.
	 * 
	 * @see java.sql.Connection#prepareStatement(String)
	 */
	public abstract java.sql.PreparedStatement clientPrepareStatement(String sql)
			throws SQLException;

	/**
	 * Prepares a statement on the client, using client-side emulation 
	 * (irregardless of the configuration property 'useServerPrepStmts') 
	 * with the same semantics as the java.sql.Connection.prepareStatement() 
	 * method with the same argument types.
	 * 
	 * @see java.sql.Connection#prepareStatement(String, int)
	 */
	public abstract java.sql.PreparedStatement clientPrepareStatement(String sql,
			int autoGenKeyIndex) throws SQLException;

	/**
	 * Prepares a statement on the client, using client-side emulation 
	 * (irregardless of the configuration property 'useServerPrepStmts') 
	 * with the same semantics as the java.sql.Connection.prepareStatement() 
	 * method with the same argument types.
	 * 
	 * @see java.sql.Connection#prepareStatement(String, int, int)
	 */
	public abstract java.sql.PreparedStatement clientPrepareStatement(String sql,
			int resultSetType, int resultSetConcurrency) throws SQLException;

	/**
	 * Prepares a statement on the client, using client-side emulation 
	 * (irregardless of the configuration property 'useServerPrepStmts') 
	 * with the same semantics as the java.sql.Connection.prepareStatement() 
	 * method with the same argument types.
	 * 
	 * @see java.sql.Connection#prepareStatement(String, int[])
	 */
	public abstract java.sql.PreparedStatement clientPrepareStatement(String sql,
			int[] autoGenKeyIndexes) throws SQLException;

	/**
	 * Prepares a statement on the client, using client-side emulation 
	 * (irregardless of the configuration property 'useServerPrepStmts') 
	 * with the same semantics as the java.sql.Connection.prepareStatement() 
	 * method with the same argument types.
	 * 
	 * @see java.sql.Connection#prepareStatement(String, int, int, int)
	 */
	public abstract java.sql.PreparedStatement clientPrepareStatement(String sql,
			int resultSetType, int resultSetConcurrency,
			int resultSetHoldability) throws SQLException;
	
	/**
	 * Prepares a statement on the client, using client-side emulation 
	 * (irregardless of the configuration property 'useServerPrepStmts') 
	 * with the same semantics as the java.sql.Connection.prepareStatement() 
	 * method with the same argument types.
	 * 
	 * @see java.sql.Connection#prepareStatement(String, String[])
	 */
	public abstract java.sql.PreparedStatement clientPrepareStatement(String sql,
			String[] autoGenKeyColNames) throws SQLException;

	/**
	 * Returns the number of statements active on this connection, which
	 * haven't been .close()d.
	 */
	public abstract int getActiveStatementCount();

	/**
	 * Reports 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 abstract long getIdleFor();

	/**
	 * Returns the log mechanism that should be used to log information from/for
	 * this Connection.
	 * 
	 * @return the Log instance to use for logging messages.
	 * @throws SQLException
	 *             if an error occurs
	 */
	public abstract Log getLog() throws SQLException;

	/**
	 * Returns the server's character set
	 * 
	 * @return the server's character set.
	 */
	public abstract String getServerCharacterEncoding();

	/**
	 * Returns the TimeZone that represents the configured
	 * timezone for the server.
	 */
	public abstract TimeZone getServerTimezoneTZ();

	/**
	 * Returns the comment that will be prepended to all statements
	 * sent to the server.
	 * 
	 * @return the comment that will be prepended to all statements
	 * sent to the server.
	 */
	public abstract String getStatementComment();

	/**
	 * Has this connection tried to execute a query on the "master"
	 * server (first host in a multiple host list).
	 */
	public abstract boolean hasTriedMaster();

	/**
	 * Is this connection currently a participant in an XA transaction?
	 */
	public abstract boolean isInGlobalTx();
	
	/**
	 * Set the state of being in a global (XA) transaction.
	 * @param flag
	 */
	public void setInGlobalTx(boolean flag);

	/**
	 * Is this connection connected to the first host in the list if
	 * there is a list of servers in the URL?
	 * 
	 * @return true if this connection is connected to the first in 
	 * the list.
	 */
	public abstract boolean isMasterConnection();

	/**
	 * Is the server in a sql_mode that doesn't allow us to use \\ to escape
	 * things?
	 * 
	 * @return Returns the noBackslashEscapes.
	 */
	public abstract boolean isNoBackslashEscapesSet();

	/**
	 * Does this connection have the same resource name as the given
	 * connection (for XA)?
	 * 
	 * @param c
	 * @return
	 */
	public abstract boolean isSameResource(Connection c);
	
	/**
	 * Is the server configured to use lower-case table names only?
	 * 
	 * @return true if lower_case_table_names is 'on'
	 */
	public abstract boolean lowerCaseTableNames();

	/**
	 * Does the server this connection is connected to
	 * support unicode?
	 */
	public abstract boolean parserKnowsUnicode();

	/**
	 * Detect if the connection is still good by sending a ping command
	 * to the server.
	 * 
	 * @throws SQLException
	 *             if the ping fails
	 */
	public abstract void ping() throws SQLException;

	/**
	 * Resets the server-side state of this connection. Doesn't work for MySQL
	 * versions older than 4.0.6 or if isParanoid() is set (it will become a
	 * no-op in these cases). Usually only used from connection pooling code.
	 * 
	 * @throws SQLException
	 *             if the operation fails while resetting server state.
	 */
	public abstract void resetServerState() throws SQLException;

	/**
	 * Prepares a statement on the server (irregardless of the 
	 * configuration property 'useServerPrepStmts') with the same semantics
	 * as the java.sql.Connection.prepareStatement() method with the 
	 * same argument types.
	 * 
	 * @see java.sql.Connection#prepareStatement(String)
	 */
	public abstract java.sql.PreparedStatement serverPrepareStatement(String sql)
		throws SQLException;

	/**
	 * Prepares a statement on the server (irregardless of the 
	 * configuration property 'useServerPrepStmts') with the same semantics
	 * as the java.sql.Connection.prepareStatement() method with the 
	 * same argument types.
	 * 
	 * @see java.sql.Connection#prepareStatement(String, int)
	 */
	public abstract java.sql.PreparedStatement serverPrepareStatement(String sql,
			int autoGenKeyIndex) throws SQLException;

	/**
	 * Prepares a statement on the server (irregardless of the 
	 * configuration property 'useServerPrepStmts') with the same semantics
	 * as the java.sql.Connection.prepareStatement() method with the 
	 * same argument types.
	 * 
	 * @see java.sql.Connection#prepareStatement(String, int, int)
	 */
	public abstract java.sql.PreparedStatement serverPrepareStatement(String sql,
			int resultSetType, int resultSetConcurrency) throws SQLException;
	/**
	 * Prepares a statement on the server (irregardless of the 
	 * configuration property 'useServerPrepStmts') with the same semantics
	 * as the java.sql.Connection.prepareStatement() method with the 
	 * same argument types.
	 * 
	 * @see java.sql.Connection#prepareStatement(String, int, int, int)
	 */
	public abstract java.sql.PreparedStatement serverPrepareStatement(String sql,
			int resultSetType, int resultSetConcurrency,
			int resultSetHoldability) throws SQLException;
	
	/**
	 * Prepares a statement on the server (irregardless of the 
	 * configuration property 'useServerPrepStmts') with the same semantics
	 * as the java.sql.Connection.prepareStatement() method with the 
	 * same argument types.
	 * 
	 * @see java.sql.Connection#prepareStatement(String, int[])
	 */
	public abstract java.sql.PreparedStatement serverPrepareStatement(String sql,
			int[] autoGenKeyIndexes) throws SQLException;
	
	/**
	 * Prepares a statement on the server (irregardless of the 
	 * configuration property 'useServerPrepStmts') with the same semantics
	 * as the java.sql.Connection.prepareStatement() method with the 
	 * same argument types.
	 * 
	 * @see java.sql.Connection#prepareStatement(String, String[])
	 */
	public abstract java.sql.PreparedStatement serverPrepareStatement(String sql,
			String[] autoGenKeyColNames) throws SQLException;

	/**
	 * @param failedOver
	 *            The failedOver to set.
	 */
	public abstract void setFailedOver(boolean flag);

	/**
	 * @param preferSlaveDuringFailover
	 *            The preferSlaveDuringFailover to set.
	 */
	public abstract void setPreferSlaveDuringFailover(boolean flag);

	/**
	 * Sets the comment that will be prepended to all statements
	 * sent to the server. Do not use slash-star or star-slash tokens 
	 * in the comment as these will be added by the driver itself.
	 * 
	 * @param comment  the comment that will be prepended to all statements
	 * sent to the server.
	 */
	public abstract void setStatementComment(String comment);

	/**
	 * Used by MiniAdmin to shutdown a MySQL server
	 * 
	 * @throws SQLException
	 *             if the command can not be issued.
	 */
	public abstract void shutdownServer() throws SQLException;

	/**
	 * Does the server this connection is connected to
	 * support quoted isolation levels?
	 */
	public abstract boolean supportsIsolationLevel();

	/**
	 * Does the server this connection is connected to
	 * support quoted identifiers?
	 */
	public abstract boolean supportsQuotedIdentifiers();

	/**
	 * Does the server this connection is connected to
	 * support quoted identifiers?
	 */
	public abstract boolean supportsTransactions();

	/**
	 * Does the server this connection is connected to
	 * meet or exceed the given version?
	 */
	public abstract boolean versionMeetsMinimum(int major, int minor,
			int subminor) throws SQLException;
	
	public abstract void reportQueryTime(long millisOrNanos);
	
	public abstract boolean isAbonormallyLongQuery(long millisOrNanos);

	public abstract void initializeExtension(Extension ex) throws SQLException;
	
	/** Returns the -session- value of 'auto_increment_increment' from the server if it exists,
	 * or '1' if not.
	 */
	public abstract int getAutoIncrementIncrement();

	/**
	 * Does this connection have the same properties as another?
	 */
	public boolean hasSameProperties(Connection c);
	
	/**
	 * Returns the parsed and passed in properties for this connection.
	 * @return
	 */
	public Properties getProperties();

   public String getHost();

   public void setProxy(MySQLConnection proxy);
   
   /**
    * Is the server this connection is connected to "local" (i.e. same host)
    * as the application?
    * @return
    */
   public boolean isServerLocal() throws SQLException;
   
	// JDBC-4.1
	// until we flip catalog/schema, this is a no-op
	void setSchema(String schema) throws SQLException;
	
	String getSchema() throws SQLException;
	
	// JDBC-4.1
	void abort(Executor executor) throws SQLException;
	
	// JDBC-4.1
	void setNetworkTimeout(Executor executor, final int milliseconds) throws SQLException;
	
	int getNetworkTimeout() throws SQLException;

	// **************************
	// moved from MySQLConnection
	// **************************

	void abortInternal() throws SQLException;

	void checkClosed() throws SQLException;

	Object getConnectionMutex();

}