/*

* Licensed to the Apache Software Foundation (ASF) under one or more

* contributor license agreements. See the NOTICE file distributed with

* this work for additional information regarding copyright ownership.

* The ASF licenses this file to You under the Apache License, Version 2.0

* (the "License"); you may not use this file except in compliance with

* the License. You may obtain a copy of the License at

*

* http://www.apache.org/licenses/LICENSE-2.0

*

* 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.

*/

package java.sql;

import java.util.Map;

import java.util.Properties;

/**

* A connection represents a link from a Java application to a database. All SQL

* statements and results are returned within the context of a connection.

* Database statements that are executed within this context form a

* database session which forms one or more closed transactions. Especially in

* distributed applications, multiple concurrent connections may exist accessing

* the same values of the database. which may lead to the following phenomena

* (referred to as <i>transaction isolation levels</i>):

* <ul>

* <li><i>dirty reads</i>:<br>

* reading values from table rows that are not committed.</br></li>

* <li><i>non-repeatable reads</i>:<br>

* reading table rows more than once in a transaction but getting back different

* data because other transactions have altered the rows between the reads.</br></li>

* <li><i>phantom reads</i>:<br>

* retrieving additional "phantom" rows in the course of repeated table reads

* because other transactions have inserted additional rows that satisfy an

* SQL {@code WHERE} clause</br></li>

* </ul>

*/

public interface Connection extends Wrapper {

/**

* A constant indicating that transactions are not supported.

*/

public static final int TRANSACTION_NONE = 0;

/**

* No <i>dirty reads</i> are permitted, therefore transactions may not read

* a row containing uncommitted values - but does not prevent an application

* from <i>non-repeatable reads</i> and <i>phantom reads</i>.

*/

public static final int TRANSACTION_READ_COMMITTED = 2;

/**

* In the case that reading uncommitted values is allowed, the following

* incidents may happen which may lead to an invalid results:

* <ul>

* <li><i>dirty reads</i></li>

* <li><i>non-repeatable reads</i></li>

* <li><i>phantom reads</i></li>

* </ul>

*/

public static final int TRANSACTION_READ_UNCOMMITTED = 1;

/**

* A constant indicating that <i>dirty reads</i> and <i>non-repeatable

* reads</i> are <b>prevented</b> but <i>phantom reads</i> can occur.

*/

public static final int TRANSACTION_REPEATABLE_READ = 4;

/**

* The constant that indicates that the following incidents are <b>all

* prevented</b> (the opposite of {@link #TRANSACTION_READ_UNCOMMITTED}):

* <ul>

* <li><i>dirty reads</i></li>

* <li><i>non-repeatable reads</i></li>

* <li><i>phantom reads</i></li>

* </ul>

*/

public static final int TRANSACTION_SERIALIZABLE = 8;

/**

* Discards all warnings that may have arisen for this connection.

* Subsequent calls to {@link #getWarnings()} will return {@code null}

* up until a new warning condition occurs.

*

* @throws SQLException

* if there is a problem accessing the database.

*/

public void clearWarnings() throws SQLException;

/**

* Causes the instant release of all database and driver connection

* resources associated with this object. Any subsequent invocations of this

* method have no effect.

* <p>

* It is strongly recommended that all connections are closed before they

* are dereferenced by the application ready for garbage collection.

* Although the {@code finalize} method of the connection closes the

* connection before garbage collection takes place, it is not advisable to

* leave the {@code close} operation to take place in this way. Mainly

* because undesired side-effects may appear.

*

* @throws SQLException

* if there is a problem accessing the database.

*/

public void close() throws SQLException;

/**

* Commits all of the changes made since the last {@code commit} or

* {@code rollback} of the associated transaction. All locks in the database

* held by this connection are also relinquished. Calling this operation on

* connection objects in {@code auto-commit} mode leads to an error.

*

* @throws SQLException

* if there is a problem accessing the database or if the target

* connection instance is in auto-commit mode.

*/

public void commit() throws SQLException;

/**

* Returns a new instance of {@code Statement} for issuing SQL commands to

* the remote database.

* <p>

* {@code ResultSets} generated by the returned statement will default to

* type {@code ResultSet.TYPE_FORWARD_ONLY} and concurrency level {@code

* ResultSet.CONCUR_READ_ONLY}.

*

* @return a {@code Statement} object with default settings.

* @throws SQLException

* if there is a problem accessing the database.

* @see ResultSet

*/

public Statement createStatement() throws SQLException;

/**

* Returns a new instance of {@code Statement} whose associated {@code

* ResultSet}s have the characteristics specified in the type and

* concurrency arguments.

*

* @param resultSetType

* one of the following type specifiers:

* <ul>

* <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE} </li> <li>

* {@link ResultSet#TYPE_SCROLL_INSENSITIVE} </li> <li>

* {@link ResultSet#TYPE_FORWARD_ONLY}</li>

* </ul>

* @param resultSetConcurrency

* one of the following concurrency mode specifiers:

* <ul>

* <li>{@link ResultSet#CONCUR_UPDATABLE}</li> <li>

* {@link ResultSet#CONCUR_READ_ONLY}</li>

* </ul>

* @return a new instance of {@code Statement} capable of manufacturing

* {@code ResultSet}s that satisfy the specified {@code

* resultSetType} and {@code resultSetConcurrency} values.

* @throws SQLException

* if there is a problem accessing the database

*/

public Statement createStatement(int resultSetType, int resultSetConcurrency)

throws SQLException;

/**

* Returns a new instance of {@code Statement} whose associated

* {@code ResultSet}s will have the characteristics specified in the

* type, concurrency and holdability arguments.

*

* @param resultSetType

* one of the following type specifiers:

* <ul>

* <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}</li>

* <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}</li>

* <li>{@link ResultSet#TYPE_FORWARD_ONLY}</li>

* </ul>

* @param resultSetConcurrency

* one of the following concurrency mode specifiers:

* <ul>

* <li>{@link ResultSet#CONCUR_UPDATABLE}</li>

* <li>{@link ResultSet#CONCUR_READ_ONLY}</li>

* </ul>

* @param resultSetHoldability

* one of the following holdability mode specifiers:

* <ul>

* <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}</li>

* <li>{@link ResultSet#CLOSE_CURSORS_AT_COMMIT}</li>

* </ul>

* @return a new instance of {@code Statement} capable of

* manufacturing {@code ResultSet}s that satisfy the

* specified {@code resultSetType},

* {@code resultSetConcurrency} and

* {@code resultSetHoldability} values.

* @throws SQLException

* if there is a problem accessing the database.

*/

public Statement createStatement(int resultSetType,

int resultSetConcurrency, int resultSetHoldability)

throws SQLException;

/**

* Returns a {@code boolean} indicating whether or not this connection is in

* the {@code auto-commit} operating mode.

*

* @return {@code true} if {@code auto-commit} is on, otherwise {@code

* false}.

* @throws SQLException

* if there is a problem accessing the database.

*/

public boolean getAutoCommit() throws SQLException;

/**

* Gets this {@code Connection} object's current catalog name.

*

* @return the catalog name. {@code null} if there is no catalog

* name.

* @throws SQLException

* if there is a problem accessing the database.

*/

public String getCatalog() throws SQLException;

/**

* Returns the holdability property that any {@code ResultSet} produced by

* this instance will have.

*

* @return one of the following holdability mode specifiers:

* <ul>

* <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}</li> <li>

* {@link ResultSet#CLOSE_CURSORS_AT_COMMIT}</li>

* </ul>

* @throws SQLException

* if there is a problem accessing the a database.

*/

public int getHoldability() throws SQLException;

/**

* Gets the metadata about the database referenced by this connection. The

* returned {@code DatabaseMetaData} describes the database topography,

* available stored procedures, SQL syntax and so on.

*

* @return a {@code DatabaseMetaData} object containing the database

* description.

* @throws SQLException

* if there is a problem accessing the a database.

*/

public DatabaseMetaData getMetaData() throws SQLException;

/**

* Returns the transaction isolation level for this connection.

*

* @return the transaction isolation value.

* @throws SQLException

* if there is a problem accessing the database.

* @see #TRANSACTION_NONE

* @see #TRANSACTION_READ_COMMITTED

* @see #TRANSACTION_READ_UNCOMMITTED

* @see #TRANSACTION_REPEATABLE_READ

* @see #TRANSACTION_SERIALIZABLE

*/

public int getTransactionIsolation() throws SQLException;

/**

* Returns the type mapping associated with this {@code Connection} object.

* The type mapping must be set on the application level.

*

* @return the Type Map as a {@code java.util.Map}.

* @throws SQLException

* if there is a problem accessing the database.

*/

public Map<String, Class<?>> getTypeMap() throws SQLException;

/**

* Gets the first instance of any {@code SQLWarning} objects that may have

* been created in the use of this connection. If at least one warning has

* occurred then this operation returns the first one reported. A {@code

* null} indicates that no warnings have occurred.

* <p>

* By invoking the {@link SQLWarning#getNextWarning()} method of the

* returned {@code SQLWarning} object it is possible to obtain all of

* this connection's warning objects.

*

* @return the first warning as an SQLWarning object (may be {@code null}).

* @throws SQLException

* if there is a problem accessing the database or if the call

* has been made on a connection which has been previously

* closed.

*/

public SQLWarning getWarnings() throws SQLException;

/**

* Returns a {@code boolean} indicating whether or not this connection is in

* the {@code closed} state. The {@code closed} state may be entered into as

* a consequence of a successful invocation of the {@link #close()} method

* or else if an error has occurred that prevents the connection from

* functioning normally.

*

* @return {@code true} if closed, otherwise {@code false}.

* @throws SQLException

* if there is a problem accessing the database.

*/

public boolean isClosed() throws SQLException;

/**

* Returns a {@code boolean} indicating whether or not this connection is

* currently in the {@code read-only} state.

*

* @return {@code true} if in read-only state, otherwise {@code false}.

* @throws SQLException

* if there is a problem accessing the database.

*/

public boolean isReadOnly() throws SQLException;

/**

* Returns a string representation of the input SQL statement

* {@code sql} expressed in the underlying system's native SQL

* syntax.

*

* @param sql

* the JDBC form of an SQL statement.

* @return the SQL statement in native database format.

* @throws SQLException

* if there is a problem accessing the database

*/

public String nativeSQL(String sql) throws SQLException;

/**

* Returns a new instance of {@code CallableStatement} that may be used for

* making stored procedure calls to the database.

*

* @param sql

* the SQL statement that calls the stored function

* @return a new instance of {@code CallableStatement} representing the SQL

* statement. {@code ResultSet}s emitted from this {@code

* CallableStatement} will default to type

* {@link ResultSet#TYPE_FORWARD_ONLY} and concurrency

* {@link ResultSet#CONCUR_READ_ONLY}.

* @throws SQLException

* if a problem occurs accessing the database.

*/

public CallableStatement prepareCall(String sql) throws SQLException;

/**

* Returns a new instance of {@code CallableStatement} that may be used for

* making stored procedure calls to the database. {@code ResultSet}s emitted

* from this {@code CallableStatement} will satisfy the specified {@code

* resultSetType} and {@code resultSetConcurrency} values.

*

* @param sql

* the SQL statement

* @param resultSetType

* one of the following type specifiers:

* <ul>

* <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}</li>

* <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}</li>

* <li>{@link ResultSet#TYPE_FORWARD_ONLY}</li>

* </ul>

* @param resultSetConcurrency

* one of the following concurrency mode specifiers:

* <ul>

* <li>{@link ResultSet#CONCUR_READ_ONLY}</li>

* <li>{@link ResultSet#CONCUR_UPDATABLE}</li>

* </ul>

* @return a new instance of {@code CallableStatement} representing the

* precompiled SQL statement. {@code ResultSet}s emitted from this

* {@code CallableStatement} will satisfy the specified {@code

* resultSetType} and {@code resultSetConcurrency} values.

* @throws SQLException

* if a problem occurs accessing the database

*/

public CallableStatement prepareCall(String sql, int resultSetType,

int resultSetConcurrency) throws SQLException;

/**

* Returns a new instance of {@code CallableStatement} that may be used for

* making stored procedure calls to the database. {@code ResultSet}s created

* from this {@code CallableStatement} will have characteristics determined

* by the specified type, concurrency and holdability arguments.

*

* @param sql

* the SQL statement

* @param resultSetType

* one of the following type specifiers:

* <ul>

* <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}</li>

* <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}</li>

* <li>{@link ResultSet#TYPE_FORWARD_ONLY}</li>

* </ul>

* @param resultSetConcurrency

* one of the following concurrency mode specifiers:

* <ul>

* <li>{@link ResultSet#CONCUR_READ_ONLY}</li>

* <li>{@link ResultSet#CONCUR_UPDATABLE}</li>

* </ul>

* @param resultSetHoldability

* one of the following holdability mode specifiers:

* <ul>

* <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}</li>

* <li>{@link ResultSet#CLOSE_CURSORS_AT_COMMIT}</li>

* </ul>

* @return a new instance of {@code CallableStatement} representing the

* precompiled SQL statement. {@code ResultSet}s emitted from this

* {@code CallableStatement} will satisfy the specified {@code

* resultSetType}, {@code resultSetConcurrency} and {@code

* resultSetHoldability} values.

* @throws SQLException

* if a problem occurs accessing the database.

*/

public CallableStatement prepareCall(String sql, int resultSetType,

int resultSetConcurrency, int resultSetHoldability)

throws SQLException;

/**

* Returns a new instance of {@code PreparedStatement} that may be used any

* number of times to execute parameterized requests on the database server.

* <p>

* Subject to JDBC driver support, this operation will attempt to send the

* precompiled version of the statement to the database. If

* the driver does not support precompiled statements, the statement will

* not reach the database server until it is executed. This distinction

* determines the moment when {@code SQLException}s get raised.

* <p>

* By default, {@code ResultSet}s from the returned object will be

* {@link ResultSet#TYPE_FORWARD_ONLY} type with a

* {@link ResultSet#CONCUR_READ_ONLY} mode of concurrency.

*

* @param sql

* the SQL statement.

* @return the {@code PreparedStatement} containing the supplied SQL

* statement.

* @throws SQLException

* if there is a problem accessing the database.

*/

public PreparedStatement prepareStatement(String sql) throws SQLException;

/**

* Creates a default {@code PreparedStatement} that can retrieve

* automatically generated keys. Parameter {@code autoGeneratedKeys} may be

* used to tell the driver whether such keys should be made accessible.

* This is only relevant when the {@code sql} statement is an {@code insert}

* statement.

* <p>

* An SQL statement which may have {@code IN} parameters can be stored and

* precompiled in a {@code PreparedStatement}. The {@code PreparedStatement}

* can then be then be used to execute the statement multiple times in an

* efficient way.

* <p>

* Subject to JDBC driver support, this operation will attempt to send the

* precompiled version of the statement to the database. If

* the driver does not support precompiled statements, the statement will

* not reach the database server until it is executed. This distinction

* determines the moment when {@code SQLException}s get raised.

* <p>

* By default, {@code ResultSet}s from the returned object will be

* {@link ResultSet#TYPE_FORWARD_ONLY} type with a

* {@link ResultSet#CONCUR_READ_ONLY} mode of concurrency.

*

* @param sql

* the SQL statement.

* @param autoGeneratedKeys

* one of the following generated key options:

* <ul>

* <li>{@link Statement#RETURN_GENERATED_KEYS}</li>

* <li>{@link Statement#NO_GENERATED_KEYS}</li>

* </ul>

* @return a new {@code PreparedStatement} instance representing the input

* SQL statement.

* @throws SQLException

* if there is a problem accessing the database.

*/

public PreparedStatement prepareStatement(String sql, int autoGeneratedKeys)

throws SQLException;

/**

* Creates a default {@code PreparedStatement} that can retrieve the

* auto-generated keys designated by a supplied array. If {@code sql} is an

* SQL {@code INSERT} statement, the parameter {@code columnIndexes} is expected

* to hold the index values for each column in the statement's intended

* database table containing the autogenerated-keys of interest. Otherwise

* {@code columnIndexes} is ignored.

* <p>

* Subject to JDBC driver support, this operation will attempt to send the

* precompiled version of the statement to the database. If

* the driver does not support precompiled statements, the statement will

* not reach the database server until it is executed. This distinction

* determines the moment when {@code SQLException}s get raised.

* <p>

* By default, {@code ResultSet}s from the returned object will be

* {@link ResultSet#TYPE_FORWARD_ONLY} type with a

* {@link ResultSet#CONCUR_READ_ONLY} concurrency mode.

*

* @param sql

* the SQL statement.

* @param columnIndexes

* the indexes of the columns for which auto-generated keys

* should be made available.

* @return the PreparedStatement containing the supplied SQL statement.

* @throws SQLException

* if a problem occurs accessing the database.

*/

public PreparedStatement prepareStatement(String sql, int[] columnIndexes)

throws SQLException;

/**

* Creates a {@code PreparedStatement} that generates {@code ResultSet}s

* with the specified values of {@code resultSetType} and {@code

* resultSetConcurrency}.

*

* @param sql

* the SQL statement. It can contain one or more {@code '?'}

* {@code IN} parameter placeholders.

* @param resultSetType

* one of the following type specifiers:

* <ul>

* <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}</li>

* <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}</li>

* <li>{@link ResultSet#TYPE_FORWARD_ONLY}</li>

* </ul>

* @param resultSetConcurrency

* one of the following concurrency mode specifiers:

* <ul>

* <li>{@link ResultSet#CONCUR_READ_ONLY}</li>

* <li>{@link ResultSet#CONCUR_UPDATABLE}</li>

* </ul>

* @return a new instance of {@code PreparedStatement} containing the SQL

* statement {@code sql}. {@code ResultSet}s emitted from this

* {@code PreparedStatement} will satisfy the specified {@code

* resultSetType} and {@code resultSetConcurrency} values.

* @throws SQLException

* if a problem occurs accessing the database.

*/

public PreparedStatement prepareStatement(String sql, int resultSetType,

int resultSetConcurrency) throws SQLException;

/**

* Creates a {@code PreparedStatement} that generates {@code ResultSet}s

* with the specified type, concurrency and holdability

*

* @param sql

* the SQL statement. It can contain one or more {@code '?' IN}

* parameter placeholders.

* @param resultSetType

* one of the following type specifiers:

* <ul>

* <li>{@link ResultSet#TYPE_SCROLL_SENSITIVE}</li>

* <li>{@link ResultSet#TYPE_SCROLL_INSENSITIVE}</li>

* <li>{@link ResultSet#TYPE_FORWARD_ONLY}</li>

* </ul>

* @param resultSetConcurrency

* one of the following concurrency mode specifiers:

* <ul>

* <li>{@link ResultSet#CONCUR_READ_ONLY}</li>

* <li>{@link ResultSet#CONCUR_UPDATABLE}</li>

* </ul>

* @param resultSetHoldability

* one of the following holdability mode specifiers:

* <ul>

* <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}</li>

* <li>{@link ResultSet#CLOSE_CURSORS_AT_COMMIT}</li>

* </ul>

* @return a new instance of {@code PreparedStatement} containing the SQL

* statement {@code sql}. {@code ResultSet}s emitted from this

* {@code PreparedStatement} will satisfy the specified {@code

* resultSetType}, {@code resultSetConcurrency} and {@code

* resultSetHoldability} values.

* @throws SQLException

* if a problem occurs accessing the database.

*/

public PreparedStatement prepareStatement(String sql, int resultSetType,

int resultSetConcurrency, int resultSetHoldability)

throws SQLException;

/**

* Creates a default {@code PreparedStatement} that can retrieve the

* auto-generated keys designated by a supplied array. If {@code sql} is an

* SQL {@code INSERT} statement, {@code columnNames} is expected to hold the

* names of each column in the statement's associated database table

* containing the autogenerated-keys of interest. Otherwise {@code

* columnNames} is ignored.

* <p>

* Subject to JDBC driver support, this operation will attempt to send the

* precompiled version of the statement to the database. Alternatively, if

* the driver is not capable of handling precompiled statements, the

* statement will not reach the database server until it is executed. This

* will have a bearing on precisely <i>when</i> {@code SQLException}

* instances get raised.

* <p>

* By default, ResultSets from the returned object will be

* {@link ResultSet#TYPE_FORWARD_ONLY} type with a

* {@link ResultSet#CONCUR_READ_ONLY} concurrency mode.

*

* @param sql

* the SQL statement.

* @param columnNames

* the names of the columns for which auto-generated keys should

* be made available.

* @return the PreparedStatement containing the supplied SQL statement.

* @throws SQLException

* if a problem occurs accessing the database.

*/

public PreparedStatement prepareStatement(String sql, String[] columnNames)

throws SQLException;

/**

* Releases the specified {@code savepoint} from the present transaction. Once removed,

* the {@code Savepoint} is considered invalid and should not be referenced

* further.

*

* @param savepoint

* the object targeted for removal.

* @throws SQLException

* if there is a problem with accessing the database or if

* {@code savepoint} is considered not valid in this

* transaction.

*/

public void releaseSavepoint(Savepoint savepoint) throws SQLException;

/**

* Rolls back all updates made so far in this transaction and

* relinquishes all acquired database locks. It is an error to invoke this

* operation when in auto-commit mode.

*

* @throws SQLException

* if there is a problem with the database or if the method is

* called while in auto-commit mode of operation.

*/

public void rollback() throws SQLException;

/**

* Undoes all changes made after the supplied {@code Savepoint} object was

* set. This method should only be used when auto-commit mode is disabled.

*

* @param savepoint

* the Savepoint to roll back to

* @throws SQLException

* if there is a problem accessing the database.

*/

public void rollback(Savepoint savepoint) throws SQLException;

/**

* Sets this connection's auto-commit mode {@code on} or {@code off}.

* <p>

* Putting a Connection into auto-commit mode means that all associated SQL

* statements are run and committed as separate transactions.

* By contrast, setting auto-commit to {@code off} means that associated SQL

* statements get grouped into transactions that need to be completed by

* explicit calls to either the {@link #commit()} or {@link #rollback()}

* methods.

* <p>

* Auto-commit is the default mode for new connection instances.

* <p>

* When in this mode, commits will automatically occur upon successful SQL

* statement completion or upon successful completion of an execute.

* Statements are not considered successfully completed until all associated

* {@code ResultSet}s and output parameters have been obtained or closed.

* <p>

* Calling this operation during an uncommitted transaction will result in

* it being committed.

*

* @param autoCommit

* {@code boolean} indication of whether to put the target

* connection into auto-commit mode ({@code true}) or not (

* {@code false}).

* @throws SQLException

* if there is a problem accessing the database.

*/

public void setAutoCommit(boolean autoCommit) throws SQLException;

/**

* Sets the catalog name for this connection. This is used to select a

* subspace of the database for future work. If the driver does not support

* catalog names, this method is ignored.

*

* @param catalog

* the catalog name to use.

* @throws SQLException

* if there is a problem accessing the database.

*/

public void setCatalog(String catalog) throws SQLException;

/**

* Sets the holdability of the {@code ResultSet}s created by this Connection.

*

* @param holdability

* one of the following holdability mode specifiers:

* <ul>

* <li>{@link ResultSet#CLOSE_CURSORS_AT_COMMIT}</li>

* <li>{@link ResultSet#HOLD_CURSORS_OVER_COMMIT}</li>

* <li>

* </ul>

* @throws SQLException

* if there is a problem accessing the database

*/

public void setHoldability(int holdability) throws SQLException;

/**

* Sets this connection to read-only mode.

* <p>

* This serves as a hint to the driver, which can enable database

* optimizations.

*

* @param readOnly

* {@code true} to set the Connection to read only mode. {@code

* false} disables read-only mode.

* @throws SQLException

* if there is a problem accessing the database.

*/

public void setReadOnly(boolean readOnly) throws SQLException;

/**

* Creates an unnamed {@code Savepoint} in the current transaction.

*

* @return a {@code Savepoint} object for this savepoint.

* @throws SQLException

* if there is a problem accessing the database.

*/

public Savepoint setSavepoint() throws SQLException;

/**

* Creates a named {@code Savepoint} in the current transaction.

*

* @param name

* the name to use for the new {@code Savepoint}.

* @return a {@code Savepoint} object for this savepoint.

* @throws SQLException

* if there is a problem accessing the database.

*/

public Savepoint setSavepoint(String name) throws SQLException;

/**

* Sets the transaction isolation level for this Connection.

* <p>

* If this method is called during a transaction, the results are

* implementation defined.

*

* @param level

* the new transaction isolation level to use from the following

* list of possible values:

* <ul>

* <li>{@link #TRANSACTION_READ_COMMITTED}

* <li>{@link #TRANSACTION_READ_UNCOMMITTED}

* <li>{@link #TRANSACTION_REPEATABLE_READ}

* <li>{@link #TRANSACTION_SERIALIZABLE}

* </ul>

* @throws SQLException

* if there is a problem with the database or if the value of

* {@code level} is not one of the expected constant values.

*/

public void setTransactionIsolation(int level) throws SQLException;

/**

* Sets the {@code TypeMap} for this connection. The input {@code map}

* should contain mappings between complex Java and SQL types.

*

* @param map

* the new type map.

* @throws SQLException

* if there is a problem accessing the database or if {@code

* map} is not an instance of {@link Map}.

*/

public void setTypeMap(Map<String, Class<?>> map) throws SQLException;

/**

* Returns a new empty Clob.

* @throws SQLException if this connection is closed, or there's a problem creating a new clob.

*/

public Clob createClob() throws SQLException;

/**

* Returns a new empty Blob.

* @throws SQLException if this connection is closed, or there's a problem creating a new blob.

*/

public Blob createBlob() throws SQLException;

/**

* Returns a new empty NClob.

* @throws SQLException if this connection is closed, or there's a problem creating a new nclob.

*/

public NClob createNClob() throws SQLException;

/**

* Returns a new empty SQLXML.

* @throws SQLException if this connection is closed, or there's a problem creating a new XML.

*/

public SQLXML createSQLXML() throws SQLException;

/**

* Returns true if this connection is still open and valid, false otherwise.

* @param timeout number of seconds to wait for a response before giving up and returning false,

* 0 to wait forever

* @throws SQLException if {@code timeout < 0}

*/

public boolean isValid(int timeout) throws SQLException;

/**

* Sets the client info property {@code name} to {@code value}. A value of null clears the

* client info property.

* @throws SQLClientInfoException if this connection is closed, or there's a problem setting

* the property.

*/

public void setClientInfo(String name, String value) throws SQLClientInfoException;

/**

* Replaces all client info properties with the name/value pairs from {@code properties}.

* All existing properties are removed. If an exception is thrown, the resulting state of

* this connection's client info properties is undefined.

* @throws SQLClientInfoException if this connection is closed, or there's a problem setting

* a property.

*/

public void setClientInfo(Properties properties) throws SQLClientInfoException;

/**

* Returns the value corresponding to the given client info property, or null if unset.

* @throws SQLClientInfoException if this connection is closed, or there's a problem getting

* the property.

*/

public String getClientInfo(String name) throws SQLException;

/**

* Returns a {@link Properties} object containing all client info properties.

* @throws SQLClientInfoException if this connection is closed, or there's a problem getting

* a property.

*/

public Properties getClientInfo() throws SQLException;

/**

* Returns a new {@link Array} containing the given {@code elements}.

* @param typeName the SQL name of the type of the array elements

* @throws SQLClientInfoException if this connection is closed, or there's a problem creating

* the array.

*/

public Array createArrayOf(String typeName, Object[] elements) throws SQLException;

/**

* Returns a new {@link Struct} containing the given {@code attributes}.

* @param typeName the SQL name of the type of the struct attributes

* @throws SQLClientInfoException if this connection is closed, or there's a problem creating

* the array.

*/

public Struct createStruct(String typeName, Object[] attributes) throws SQLException;

}