/*
* 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, AutoCloseable {
/**
* 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;
}