0001 /*
0002 * Copyright 1996-2006 Sun Microsystems, Inc. All Rights Reserved.
0003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0004 *
0005 * This code is free software; you can redistribute it and/or modify it
0006 * under the terms of the GNU General Public License version 2 only, as
0007 * published by the Free Software Foundation. Sun designates this
0008 * particular file as subject to the "Classpath" exception as provided
0009 * by Sun in the LICENSE file that accompanied this code.
0010 *
0011 * This code is distributed in the hope that it will be useful, but WITHOUT
0012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0014 * version 2 for more details (a copy is included in the LICENSE file that
0015 * accompanied this code).
0016 *
0017 * You should have received a copy of the GNU General Public License version
0018 * 2 along with this work; if not, write to the Free Software Foundation,
0019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0020 *
0021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
0022 * CA 95054 USA or visit www.sun.com if you need additional information or
0023 * have any questions.
0024 */
0025
0026 package java.sql;
0027
0028 import java.util.Properties;
0029
0030 /**
0031 * <P>A connection (session) with a specific
0032 * database. SQL statements are executed and results are returned
0033 * within the context of a connection.
0034 * <P>
0035 * A <code>Connection</code> object's database is able to provide information
0036 * describing its tables, its supported SQL grammar, its stored
0037 * procedures, the capabilities of this connection, and so on. This
0038 * information is obtained with the <code>getMetaData</code> method.
0039 *
0040 * <P><B>Note:</B> When configuring a <code>Connection</code>, JDBC applications
0041 * should use the appropritate <code>Connection</code> method such as
0042 * <code>setAutoCommit</code> or <code>setTransactionIsolation</code>.
0043 * Applications should not invoke SQL commands directly to change the connection's
0044 * configuration when there is a JDBC method available. By default a <code>Connection</code> object is in
0045 * auto-commit mode, which means that it automatically commits changes
0046 * after executing each statement. If auto-commit mode has been
0047 * disabled, the method <code>commit</code> must be called explicitly in
0048 * order to commit changes; otherwise, database changes will not be saved.
0049 * <P>
0050 * A new <code>Connection</code> object created using the JDBC 2.1 core API
0051 * has an initially empty type map associated with it. A user may enter a
0052 * custom mapping for a UDT in this type map.
0053 * When a UDT is retrieved from a data source with the
0054 * method <code>ResultSet.getObject</code>, the <code>getObject</code> method
0055 * will check the connection's type map to see if there is an entry for that
0056 * UDT. If so, the <code>getObject</code> method will map the UDT to the
0057 * class indicated. If there is no entry, the UDT will be mapped using the
0058 * standard mapping.
0059 * <p>
0060 * A user may create a new type map, which is a <code>java.util.Map</code>
0061 * object, make an entry in it, and pass it to the <code>java.sql</code>
0062 * methods that can perform custom mapping. In this case, the method
0063 * will use the given type map instead of the one associated with
0064 * the connection.
0065 * <p>
0066 * For example, the following code fragment specifies that the SQL
0067 * type <code>ATHLETES</code> will be mapped to the class
0068 * <code>Athletes</code> in the Java programming language.
0069 * The code fragment retrieves the type map for the <code>Connection
0070 * </code> object <code>con</code>, inserts the entry into it, and then sets
0071 * the type map with the new entry as the connection's type map.
0072 * <pre>
0073 * java.util.Map map = con.getTypeMap();
0074 * map.put("mySchemaName.ATHLETES", Class.forName("Athletes"));
0075 * con.setTypeMap(map);
0076 * </pre>
0077 *
0078 * @see DriverManager#getConnection
0079 * @see Statement
0080 * @see ResultSet
0081 * @see DatabaseMetaData
0082 */
0083 public interface Connection extends Wrapper {
0084
0085 /**
0086 * Creates a <code>Statement</code> object for sending
0087 * SQL statements to the database.
0088 * SQL statements without parameters are normally
0089 * executed using <code>Statement</code> objects. If the same SQL statement
0090 * is executed many times, it may be more efficient to use a
0091 * <code>PreparedStatement</code> object.
0092 * <P>
0093 * Result sets created using the returned <code>Statement</code>
0094 * object will by default be type <code>TYPE_FORWARD_ONLY</code>
0095 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
0096 * The holdability of the created result sets can be determined by
0097 * calling {@link #getHoldability}.
0098 *
0099 * @return a new default <code>Statement</code> object
0100 * @exception SQLException if a database access error occurs
0101 * or this method is called on a closed connection
0102 */
0103 Statement createStatement() throws SQLException;
0104
0105 /**
0106 * Creates a <code>PreparedStatement</code> object for sending
0107 * parameterized SQL statements to the database.
0108 * <P>
0109 * A SQL statement with or without IN parameters can be
0110 * pre-compiled and stored in a <code>PreparedStatement</code> object. This
0111 * object can then be used to efficiently execute this statement
0112 * multiple times.
0113 *
0114 * <P><B>Note:</B> This method is optimized for handling
0115 * parametric SQL statements that benefit from precompilation. If
0116 * the driver supports precompilation,
0117 * the method <code>prepareStatement</code> will send
0118 * the statement to the database for precompilation. Some drivers
0119 * may not support precompilation. In this case, the statement may
0120 * not be sent to the database until the <code>PreparedStatement</code>
0121 * object is executed. This has no direct effect on users; however, it does
0122 * affect which methods throw certain <code>SQLException</code> objects.
0123 * <P>
0124 * Result sets created using the returned <code>PreparedStatement</code>
0125 * object will by default be type <code>TYPE_FORWARD_ONLY</code>
0126 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
0127 * The holdability of the created result sets can be determined by
0128 * calling {@link #getHoldability}.
0129 *
0130 * @param sql an SQL statement that may contain one or more '?' IN
0131 * parameter placeholders
0132 * @return a new default <code>PreparedStatement</code> object containing the
0133 * pre-compiled SQL statement
0134 * @exception SQLException if a database access error occurs
0135 * or this method is called on a closed connection
0136 */
0137 PreparedStatement prepareStatement(String sql) throws SQLException;
0138
0139 /**
0140 * Creates a <code>CallableStatement</code> object for calling
0141 * database stored procedures.
0142 * The <code>CallableStatement</code> object provides
0143 * methods for setting up its IN and OUT parameters, and
0144 * methods for executing the call to a stored procedure.
0145 *
0146 * <P><B>Note:</B> This method is optimized for handling stored
0147 * procedure call statements. Some drivers may send the call
0148 * statement to the database when the method <code>prepareCall</code>
0149 * is done; others
0150 * may wait until the <code>CallableStatement</code> object
0151 * is executed. This has no
0152 * direct effect on users; however, it does affect which method
0153 * throws certain SQLExceptions.
0154 * <P>
0155 * Result sets created using the returned <code>CallableStatement</code>
0156 * object will by default be type <code>TYPE_FORWARD_ONLY</code>
0157 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
0158 * The holdability of the created result sets can be determined by
0159 * calling {@link #getHoldability}.
0160 *
0161 * @param sql an SQL statement that may contain one or more '?'
0162 * parameter placeholders. Typically this statement is specified using JDBC
0163 * call escape syntax.
0164 * @return a new default <code>CallableStatement</code> object containing the
0165 * pre-compiled SQL statement
0166 * @exception SQLException if a database access error occurs
0167 * or this method is called on a closed connection
0168 */
0169 CallableStatement prepareCall(String sql) throws SQLException;
0170
0171 /**
0172 * Converts the given SQL statement into the system's native SQL grammar.
0173 * A driver may convert the JDBC SQL grammar into its system's
0174 * native SQL grammar prior to sending it. This method returns the
0175 * native form of the statement that the driver would have sent.
0176 *
0177 * @param sql an SQL statement that may contain one or more '?'
0178 * parameter placeholders
0179 * @return the native form of this statement
0180 * @exception SQLException if a database access error occurs
0181 * or this method is called on a closed connection
0182 */
0183 String nativeSQL(String sql) throws SQLException;
0184
0185 /**
0186 * Sets this connection's auto-commit mode to the given state.
0187 * If a connection is in auto-commit mode, then all its SQL
0188 * statements will be executed and committed as individual
0189 * transactions. Otherwise, its SQL statements are grouped into
0190 * transactions that are terminated by a call to either
0191 * the method <code>commit</code> or the method <code>rollback</code>.
0192 * By default, new connections are in auto-commit
0193 * mode.
0194 * <P>
0195 * The commit occurs when the statement completes. The time when the statement
0196 * completes depends on the type of SQL Statement:
0197 * <ul>
0198 * <li>For DML statements, such as Insert, Update or Delete, and DDL statements,
0199 * the statement is complete as soon as it has finished executing.
0200 * <li>For Select statements, the statement is complete when the associated result
0201 * set is closed.
0202 * <li>For <code>CallableStatement</code> objects or for statements that return
0203 * multiple results, the statement is complete
0204 * when all of the associated result sets have been closed, and all update
0205 * counts and output parameters have been retrieved.
0206 *</ul>
0207 * <P>
0208 * <B>NOTE:</B> If this method is called during a transaction and the
0209 * auto-commit mode is changed, the transaction is committed. If
0210 * <code>setAutoCommit</code> is called and the auto-commit mode is
0211 * not changed, the call is a no-op.
0212 *
0213 * @param autoCommit <code>true</code> to enable auto-commit mode;
0214 * <code>false</code> to disable it
0215 * @exception SQLException if a database access error occurs,
0216 * setAutoCommit(true) is called while participating in a distributed transaction,
0217 * or this method is called on a closed connection
0218 * @see #getAutoCommit
0219 */
0220 void setAutoCommit(boolean autoCommit) throws SQLException;
0221
0222 /**
0223 * Retrieves the current auto-commit mode for this <code>Connection</code>
0224 * object.
0225 *
0226 * @return the current state of this <code>Connection</code> object's
0227 * auto-commit mode
0228 * @exception SQLException if a database access error occurs
0229 * or this method is called on a closed connection
0230 * @see #setAutoCommit
0231 */
0232 boolean getAutoCommit() throws SQLException;
0233
0234 /**
0235 * Makes all changes made since the previous
0236 * commit/rollback permanent and releases any database locks
0237 * currently held by this <code>Connection</code> object.
0238 * This method should be
0239 * used only when auto-commit mode has been disabled.
0240 *
0241 * @exception SQLException if a database access error occurs,
0242 * this method is called while participating in a distributed transaction,
0243 * if this method is called on a closed conection or this
0244 * <code>Connection</code> object is in auto-commit mode
0245 * @see #setAutoCommit
0246 */
0247 void commit() throws SQLException;
0248
0249 /**
0250 * Undoes all changes made in the current transaction
0251 * and releases any database locks currently held
0252 * by this <code>Connection</code> object. This method should be
0253 * used only when auto-commit mode has been disabled.
0254 *
0255 * @exception SQLException if a database access error occurs,
0256 * this method is called while participating in a distributed transaction,
0257 * this method is called on a closed connection or this
0258 * <code>Connection</code> object is in auto-commit mode
0259 * @see #setAutoCommit
0260 */
0261 void rollback() throws SQLException;
0262
0263 /**
0264 * Releases this <code>Connection</code> object's database and JDBC resources
0265 * immediately instead of waiting for them to be automatically released.
0266 * <P>
0267 * Calling the method <code>close</code> on a <code>Connection</code>
0268 * object that is already closed is a no-op.
0269 * <P>
0270 * It is <b>strongly recommended</b> that an application explicitly
0271 * commits or rolls back an active transaction prior to calling the
0272 * <code>close</code> method. If the <code>close</code> method is called
0273 * and there is an active transaction, the results are implementation-defined.
0274 * <P>
0275 *
0276 * @exception SQLException SQLException if a database access error occurs
0277 */
0278 void close() throws SQLException;
0279
0280 /**
0281 * Retrieves whether this <code>Connection</code> object has been
0282 * closed. A connection is closed if the method <code>close</code>
0283 * has been called on it or if certain fatal errors have occurred.
0284 * This method is guaranteed to return <code>true</code> only when
0285 * it is called after the method <code>Connection.close</code> has
0286 * been called.
0287 * <P>
0288 * This method generally cannot be called to determine whether a
0289 * connection to a database is valid or invalid. A typical client
0290 * can determine that a connection is invalid by catching any
0291 * exceptions that might be thrown when an operation is attempted.
0292 *
0293 * @return <code>true</code> if this <code>Connection</code> object
0294 * is closed; <code>false</code> if it is still open
0295 * @exception SQLException if a database access error occurs
0296 */
0297 boolean isClosed() throws SQLException;
0298
0299 //======================================================================
0300 // Advanced features:
0301
0302 /**
0303 * Retrieves a <code>DatabaseMetaData</code> object that contains
0304 * metadata about the database to which this
0305 * <code>Connection</code> object represents a connection.
0306 * The metadata includes information about the database's
0307 * tables, its supported SQL grammar, its stored
0308 * procedures, the capabilities of this connection, and so on.
0309 *
0310 * @return a <code>DatabaseMetaData</code> object for this
0311 * <code>Connection</code> object
0312 * @exception SQLException if a database access error occurs
0313 * or this method is called on a closed connection
0314 */
0315 DatabaseMetaData getMetaData() throws SQLException;
0316
0317 /**
0318 * Puts this connection in read-only mode as a hint to the driver to enable
0319 * database optimizations.
0320 *
0321 * <P><B>Note:</B> This method cannot be called during a transaction.
0322 *
0323 * @param readOnly <code>true</code> enables read-only mode;
0324 * <code>false</code> disables it
0325 * @exception SQLException if a database access error occurs, this
0326 * method is called on a closed connection or this
0327 * method is called during a transaction
0328 */
0329 void setReadOnly(boolean readOnly) throws SQLException;
0330
0331 /**
0332 * Retrieves whether this <code>Connection</code>
0333 * object is in read-only mode.
0334 *
0335 * @return <code>true</code> if this <code>Connection</code> object
0336 * is read-only; <code>false</code> otherwise
0337 * @exception SQLException SQLException if a database access error occurs
0338 * or this method is called on a closed connection
0339 */
0340 boolean isReadOnly() throws SQLException;
0341
0342 /**
0343 * Sets the given catalog name in order to select
0344 * a subspace of this <code>Connection</code> object's database
0345 * in which to work.
0346 * <P>
0347 * If the driver does not support catalogs, it will
0348 * silently ignore this request.
0349 *
0350 * @param catalog the name of a catalog (subspace in this
0351 * <code>Connection</code> object's database) in which to work
0352 * @exception SQLException if a database access error occurs
0353 * or this method is called on a closed connection
0354 * @see #getCatalog
0355 */
0356 void setCatalog(String catalog) throws SQLException;
0357
0358 /**
0359 * Retrieves this <code>Connection</code> object's current catalog name.
0360 *
0361 * @return the current catalog name or <code>null</code> if there is none
0362 * @exception SQLException if a database access error occurs
0363 * or this method is called on a closed connection
0364 * @see #setCatalog
0365 */
0366 String getCatalog() throws SQLException;
0367
0368 /**
0369 * A constant indicating that transactions are not supported.
0370 */
0371 int TRANSACTION_NONE = 0;
0372
0373 /**
0374 * A constant indicating that
0375 * dirty reads, non-repeatable reads and phantom reads can occur.
0376 * This level allows a row changed by one transaction to be read
0377 * by another transaction before any changes in that row have been
0378 * committed (a "dirty read"). If any of the changes are rolled back,
0379 * the second transaction will have retrieved an invalid row.
0380 */
0381 int TRANSACTION_READ_UNCOMMITTED = 1;
0382
0383 /**
0384 * A constant indicating that
0385 * dirty reads are prevented; non-repeatable reads and phantom
0386 * reads can occur. This level only prohibits a transaction
0387 * from reading a row with uncommitted changes in it.
0388 */
0389 int TRANSACTION_READ_COMMITTED = 2;
0390
0391 /**
0392 * A constant indicating that
0393 * dirty reads and non-repeatable reads are prevented; phantom
0394 * reads can occur. This level prohibits a transaction from
0395 * reading a row with uncommitted changes in it, and it also
0396 * prohibits the situation where one transaction reads a row,
0397 * a second transaction alters the row, and the first transaction
0398 * rereads the row, getting different values the second time
0399 * (a "non-repeatable read").
0400 */
0401 int TRANSACTION_REPEATABLE_READ = 4;
0402
0403 /**
0404 * A constant indicating that
0405 * dirty reads, non-repeatable reads and phantom reads are prevented.
0406 * This level includes the prohibitions in
0407 * <code>TRANSACTION_REPEATABLE_READ</code> and further prohibits the
0408 * situation where one transaction reads all rows that satisfy
0409 * a <code>WHERE</code> condition, a second transaction inserts a row that
0410 * satisfies that <code>WHERE</code> condition, and the first transaction
0411 * rereads for the same condition, retrieving the additional
0412 * "phantom" row in the second read.
0413 */
0414 int TRANSACTION_SERIALIZABLE = 8;
0415
0416 /**
0417 * Attempts to change the transaction isolation level for this
0418 * <code>Connection</code> object to the one given.
0419 * The constants defined in the interface <code>Connection</code>
0420 * are the possible transaction isolation levels.
0421 * <P>
0422 * <B>Note:</B> If this method is called during a transaction, the result
0423 * is implementation-defined.
0424 *
0425 * @param level one of the following <code>Connection</code> constants:
0426 * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
0427 * <code>Connection.TRANSACTION_READ_COMMITTED</code>,
0428 * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or
0429 * <code>Connection.TRANSACTION_SERIALIZABLE</code>.
0430 * (Note that <code>Connection.TRANSACTION_NONE</code> cannot be used
0431 * because it specifies that transactions are not supported.)
0432 * @exception SQLException if a database access error occurs, this
0433 * method is called on a closed connection
0434 * or the given parameter is not one of the <code>Connection</code>
0435 * constants
0436 * @see DatabaseMetaData#supportsTransactionIsolationLevel
0437 * @see #getTransactionIsolation
0438 */
0439 void setTransactionIsolation(int level) throws SQLException;
0440
0441 /**
0442 * Retrieves this <code>Connection</code> object's current
0443 * transaction isolation level.
0444 *
0445 * @return the current transaction isolation level, which will be one
0446 * of the following constants:
0447 * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
0448 * <code>Connection.TRANSACTION_READ_COMMITTED</code>,
0449 * <code>Connection.TRANSACTION_REPEATABLE_READ</code>,
0450 * <code>Connection.TRANSACTION_SERIALIZABLE</code>, or
0451 * <code>Connection.TRANSACTION_NONE</code>.
0452 * @exception SQLException if a database access error occurs
0453 * or this method is called on a closed connection
0454 * @see #setTransactionIsolation
0455 */
0456 int getTransactionIsolation() throws SQLException;
0457
0458 /**
0459 * Retrieves the first warning reported by calls on this
0460 * <code>Connection</code> object. If there is more than one
0461 * warning, subsequent warnings will be chained to the first one
0462 * and can be retrieved by calling the method
0463 * <code>SQLWarning.getNextWarning</code> on the warning
0464 * that was retrieved previously.
0465 * <P>
0466 * This method may not be
0467 * called on a closed connection; doing so will cause an
0468 * <code>SQLException</code> to be thrown.
0469 *
0470 * <P><B>Note:</B> Subsequent warnings will be chained to this
0471 * SQLWarning.
0472 *
0473 * @return the first <code>SQLWarning</code> object or <code>null</code>
0474 * if there are none
0475 * @exception SQLException if a database access error occurs or
0476 * this method is called on a closed connection
0477 * @see SQLWarning
0478 */
0479 SQLWarning getWarnings() throws SQLException;
0480
0481 /**
0482 * Clears all warnings reported for this <code>Connection</code> object.
0483 * After a call to this method, the method <code>getWarnings</code>
0484 * returns <code>null</code> until a new warning is
0485 * reported for this <code>Connection</code> object.
0486 *
0487 * @exception SQLException SQLException if a database access error occurs
0488 * or this method is called on a closed connection
0489 */
0490 void clearWarnings() throws SQLException;
0491
0492 //--------------------------JDBC 2.0-----------------------------
0493
0494 /**
0495 * Creates a <code>Statement</code> object that will generate
0496 * <code>ResultSet</code> objects with the given type and concurrency.
0497 * This method is the same as the <code>createStatement</code> method
0498 * above, but it allows the default result set
0499 * type and concurrency to be overridden.
0500 * The holdability of the created result sets can be determined by
0501 * calling {@link #getHoldability}.
0502 *
0503 * @param resultSetType a result set type; one of
0504 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
0505 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
0506 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
0507 * @param resultSetConcurrency a concurrency type; one of
0508 * <code>ResultSet.CONCUR_READ_ONLY</code> or
0509 * <code>ResultSet.CONCUR_UPDATABLE</code>
0510 * @return a new <code>Statement</code> object that will generate
0511 * <code>ResultSet</code> objects with the given type and
0512 * concurrency
0513 * @exception SQLException if a database access error occurs, this
0514 * method is called on a closed connection
0515 * or the given parameters are not <code>ResultSet</code>
0516 * constants indicating type and concurrency
0517 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0518 * this method or this method is not supported for the specified result
0519 * set type and result set concurrency.
0520 * @since 1.2
0521 */
0522 Statement createStatement(int resultSetType,
0523 int resultSetConcurrency) throws SQLException;
0524
0525 /**
0526 *
0527 * Creates a <code>PreparedStatement</code> object that will generate
0528 * <code>ResultSet</code> objects with the given type and concurrency.
0529 * This method is the same as the <code>prepareStatement</code> method
0530 * above, but it allows the default result set
0531 * type and concurrency to be overridden.
0532 * The holdability of the created result sets can be determined by
0533 * calling {@link #getHoldability}.
0534 *
0535 * @param sql a <code>String</code> object that is the SQL statement to
0536 * be sent to the database; may contain one or more '?' IN
0537 * parameters
0538 * @param resultSetType a result set type; one of
0539 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
0540 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
0541 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
0542 * @param resultSetConcurrency a concurrency type; one of
0543 * <code>ResultSet.CONCUR_READ_ONLY</code> or
0544 * <code>ResultSet.CONCUR_UPDATABLE</code>
0545 * @return a new PreparedStatement object containing the
0546 * pre-compiled SQL statement that will produce <code>ResultSet</code>
0547 * objects with the given type and concurrency
0548 * @exception SQLException if a database access error occurs, this
0549 * method is called on a closed connection
0550 * or the given parameters are not <code>ResultSet</code>
0551 * constants indicating type and concurrency
0552 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0553 * this method or this method is not supported for the specified result
0554 * set type and result set concurrency.
0555 * @since 1.2
0556 */
0557 PreparedStatement prepareStatement(String sql, int resultSetType,
0558 int resultSetConcurrency) throws SQLException;
0559
0560 /**
0561 * Creates a <code>CallableStatement</code> object that will generate
0562 * <code>ResultSet</code> objects with the given type and concurrency.
0563 * This method is the same as the <code>prepareCall</code> method
0564 * above, but it allows the default result set
0565 * type and concurrency to be overridden.
0566 * The holdability of the created result sets can be determined by
0567 * calling {@link #getHoldability}.
0568 *
0569 * @param sql a <code>String</code> object that is the SQL statement to
0570 * be sent to the database; may contain on or more '?' parameters
0571 * @param resultSetType a result set type; one of
0572 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
0573 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
0574 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
0575 * @param resultSetConcurrency a concurrency type; one of
0576 * <code>ResultSet.CONCUR_READ_ONLY</code> or
0577 * <code>ResultSet.CONCUR_UPDATABLE</code>
0578 * @return a new <code>CallableStatement</code> object containing the
0579 * pre-compiled SQL statement that will produce <code>ResultSet</code>
0580 * objects with the given type and concurrency
0581 * @exception SQLException if a database access error occurs, this method
0582 * is called on a closed connection
0583 * or the given parameters are not <code>ResultSet</code>
0584 * constants indicating type and concurrency
0585 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0586 * this method or this method is not supported for the specified result
0587 * set type and result set concurrency.
0588 * @since 1.2
0589 */
0590 CallableStatement prepareCall(String sql, int resultSetType,
0591 int resultSetConcurrency) throws SQLException;
0592
0593 /**
0594 * Retrieves the <code>Map</code> object associated with this
0595 * <code>Connection</code> object.
0596 * Unless the application has added an entry, the type map returned
0597 * will be empty.
0598 *
0599 * @return the <code>java.util.Map</code> object associated
0600 * with this <code>Connection</code> object
0601 * @exception SQLException if a database access error occurs
0602 * or this method is called on a closed connection
0603 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0604 * this method
0605 * @since 1.2
0606 * @see #setTypeMap
0607 */
0608 java.util.Map<String, Class<?>> getTypeMap() throws SQLException;
0609
0610 /**
0611 * Installs the given <code>TypeMap</code> object as the type map for
0612 * this <code>Connection</code> object. The type map will be used for the
0613 * custom mapping of SQL structured types and distinct types.
0614 *
0615 * @param map the <code>java.util.Map</code> object to install
0616 * as the replacement for this <code>Connection</code>
0617 * object's default type map
0618 * @exception SQLException if a database access error occurs, this
0619 * method is called on a closed connection or
0620 * the given parameter is not a <code>java.util.Map</code>
0621 * object
0622 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0623 * this method
0624 * @since 1.2
0625 * @see #getTypeMap
0626 */
0627 void setTypeMap(java.util.Map<String, Class<?>> map)
0628 throws SQLException;
0629
0630 //--------------------------JDBC 3.0-----------------------------
0631
0632 /**
0633 * Changes the default holdability of <code>ResultSet</code> objects
0634 * created using this <code>Connection</code> object to the given
0635 * holdability. The default holdability of <code>ResultSet</code> objects
0636 * can be be determined by invoking
0637 * {@link DatabaseMetaData#getResultSetHoldability}.
0638 *
0639 * @param holdability a <code>ResultSet</code> holdability constant; one of
0640 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
0641 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
0642 * @throws SQLException if a database access occurs, this method is called
0643 * on a closed connection, or the given parameter
0644 * is not a <code>ResultSet</code> constant indicating holdability
0645 * @exception SQLFeatureNotSupportedException if the given holdability is not supported
0646 * @see #getHoldability
0647 * @see DatabaseMetaData#getResultSetHoldability
0648 * @see ResultSet
0649 * @since 1.4
0650 */
0651 void setHoldability(int holdability) throws SQLException;
0652
0653 /**
0654 * Retrieves the current holdability of <code>ResultSet</code> objects
0655 * created using this <code>Connection</code> object.
0656 *
0657 * @return the holdability, one of
0658 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
0659 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
0660 * @throws SQLException if a database access error occurs
0661 * or this method is called on a closed connection
0662 * @see #setHoldability
0663 * @see DatabaseMetaData#getResultSetHoldability
0664 * @see ResultSet
0665 * @since 1.4
0666 */
0667 int getHoldability() throws SQLException;
0668
0669 /**
0670 * Creates an unnamed savepoint in the current transaction and
0671 * returns the new <code>Savepoint</code> object that represents it.
0672 *
0673 *<p> if setSavepoint is invoked outside of an active transaction, a transaction will be started at this newly created
0674 *savepoint.
0675 *
0676 * @return the new <code>Savepoint</code> object
0677 * @exception SQLException if a database access error occurs,
0678 * this method is called while participating in a distributed transaction,
0679 * this method is called on a closed connection
0680 * or this <code>Connection</code> object is currently in
0681 * auto-commit mode
0682 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0683 * this method
0684 * @see Savepoint
0685 * @since 1.4
0686 */
0687 Savepoint setSavepoint() throws SQLException;
0688
0689 /**
0690 * Creates a savepoint with the given name in the current transaction
0691 * and returns the new <code>Savepoint</code> object that represents it.
0692 *
0693 * <p> if setSavepoint is invoked outside of an active transaction, a transaction will be started at this newly created
0694 *savepoint.
0695 *
0696 * @param name a <code>String</code> containing the name of the savepoint
0697 * @return the new <code>Savepoint</code> object
0698 * @exception SQLException if a database access error occurs,
0699 * this method is called while participating in a distributed transaction,
0700 * this method is called on a closed connection
0701 * or this <code>Connection</code> object is currently in
0702 * auto-commit mode
0703 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0704 * this method
0705 * @see Savepoint
0706 * @since 1.4
0707 */
0708 Savepoint setSavepoint(String name) throws SQLException;
0709
0710 /**
0711 * Undoes all changes made after the given <code>Savepoint</code> object
0712 * was set.
0713 * <P>
0714 * This method should be used only when auto-commit has been disabled.
0715 *
0716 * @param savepoint the <code>Savepoint</code> object to roll back to
0717 * @exception SQLException if a database access error occurs,
0718 * this method is called while participating in a distributed transaction,
0719 * this method is called on a closed connection,
0720 * the <code>Savepoint</code> object is no longer valid,
0721 * or this <code>Connection</code> object is currently in
0722 * auto-commit mode
0723 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0724 * this method
0725 * @see Savepoint
0726 * @see #rollback
0727 * @since 1.4
0728 */
0729 void rollback(Savepoint savepoint) throws SQLException;
0730
0731 /**
0732 * Removes the specified <code>Savepoint</code> and subsequent <code>Savepoint</code> objects from the current
0733 * transaction. Any reference to the savepoint after it have been removed
0734 * will cause an <code>SQLException</code> to be thrown.
0735 *
0736 * @param savepoint the <code>Savepoint</code> object to be removed
0737 * @exception SQLException if a database access error occurs, this
0738 * method is called on a closed connection or
0739 * the given <code>Savepoint</code> object is not a valid
0740 * savepoint in the current transaction
0741 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0742 * this method
0743 * @since 1.4
0744 */
0745 void releaseSavepoint(Savepoint savepoint) throws SQLException;
0746
0747 /**
0748 * Creates a <code>Statement</code> object that will generate
0749 * <code>ResultSet</code> objects with the given type, concurrency,
0750 * and holdability.
0751 * This method is the same as the <code>createStatement</code> method
0752 * above, but it allows the default result set
0753 * type, concurrency, and holdability to be overridden.
0754 *
0755 * @param resultSetType one of the following <code>ResultSet</code>
0756 * constants:
0757 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
0758 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
0759 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
0760 * @param resultSetConcurrency one of the following <code>ResultSet</code>
0761 * constants:
0762 * <code>ResultSet.CONCUR_READ_ONLY</code> or
0763 * <code>ResultSet.CONCUR_UPDATABLE</code>
0764 * @param resultSetHoldability one of the following <code>ResultSet</code>
0765 * constants:
0766 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
0767 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
0768 * @return a new <code>Statement</code> object that will generate
0769 * <code>ResultSet</code> objects with the given type,
0770 * concurrency, and holdability
0771 * @exception SQLException if a database access error occurs, this
0772 * method is called on a closed connection
0773 * or the given parameters are not <code>ResultSet</code>
0774 * constants indicating type, concurrency, and holdability
0775 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0776 * this method or this method is not supported for the specified result
0777 * set type, result set holdability and result set concurrency.
0778 * @see ResultSet
0779 * @since 1.4
0780 */
0781 Statement createStatement(int resultSetType,
0782 int resultSetConcurrency, int resultSetHoldability)
0783 throws SQLException;
0784
0785 /**
0786 * Creates a <code>PreparedStatement</code> object that will generate
0787 * <code>ResultSet</code> objects with the given type, concurrency,
0788 * and holdability.
0789 * <P>
0790 * This method is the same as the <code>prepareStatement</code> method
0791 * above, but it allows the default result set
0792 * type, concurrency, and holdability to be overridden.
0793 *
0794 * @param sql a <code>String</code> object that is the SQL statement to
0795 * be sent to the database; may contain one or more '?' IN
0796 * parameters
0797 * @param resultSetType one of the following <code>ResultSet</code>
0798 * constants:
0799 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
0800 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
0801 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
0802 * @param resultSetConcurrency one of the following <code>ResultSet</code>
0803 * constants:
0804 * <code>ResultSet.CONCUR_READ_ONLY</code> or
0805 * <code>ResultSet.CONCUR_UPDATABLE</code>
0806 * @param resultSetHoldability one of the following <code>ResultSet</code>
0807 * constants:
0808 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
0809 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
0810 * @return a new <code>PreparedStatement</code> object, containing the
0811 * pre-compiled SQL statement, that will generate
0812 * <code>ResultSet</code> objects with the given type,
0813 * concurrency, and holdability
0814 * @exception SQLException if a database access error occurs, this
0815 * method is called on a closed connection
0816 * or the given parameters are not <code>ResultSet</code>
0817 * constants indicating type, concurrency, and holdability
0818 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0819 * this method or this method is not supported for the specified result
0820 * set type, result set holdability and result set concurrency.
0821 * @see ResultSet
0822 * @since 1.4
0823 */
0824 PreparedStatement prepareStatement(String sql, int resultSetType,
0825 int resultSetConcurrency, int resultSetHoldability)
0826 throws SQLException;
0827
0828 /**
0829 * Creates a <code>CallableStatement</code> object that will generate
0830 * <code>ResultSet</code> objects with the given type and concurrency.
0831 * This method is the same as the <code>prepareCall</code> method
0832 * above, but it allows the default result set
0833 * type, result set concurrency type and holdability to be overridden.
0834 *
0835 * @param sql a <code>String</code> object that is the SQL statement to
0836 * be sent to the database; may contain on or more '?' parameters
0837 * @param resultSetType one of the following <code>ResultSet</code>
0838 * constants:
0839 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
0840 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
0841 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
0842 * @param resultSetConcurrency one of the following <code>ResultSet</code>
0843 * constants:
0844 * <code>ResultSet.CONCUR_READ_ONLY</code> or
0845 * <code>ResultSet.CONCUR_UPDATABLE</code>
0846 * @param resultSetHoldability one of the following <code>ResultSet</code>
0847 * constants:
0848 * <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
0849 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
0850 * @return a new <code>CallableStatement</code> object, containing the
0851 * pre-compiled SQL statement, that will generate
0852 * <code>ResultSet</code> objects with the given type,
0853 * concurrency, and holdability
0854 * @exception SQLException if a database access error occurs, this
0855 * method is called on a closed connection
0856 * or the given parameters are not <code>ResultSet</code>
0857 * constants indicating type, concurrency, and holdability
0858 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0859 * this method or this method is not supported for the specified result
0860 * set type, result set holdability and result set concurrency.
0861 * @see ResultSet
0862 * @since 1.4
0863 */
0864 CallableStatement prepareCall(String sql, int resultSetType,
0865 int resultSetConcurrency, int resultSetHoldability)
0866 throws SQLException;
0867
0868 /**
0869 * Creates a default <code>PreparedStatement</code> object that has
0870 * the capability to retrieve auto-generated keys. The given constant
0871 * tells the driver whether it should make auto-generated keys
0872 * available for retrieval. This parameter is ignored if the SQL statement
0873 * is not an <code>INSERT</code> statement, or an SQL statement able to return
0874 * auto-generated keys (the list of such statements is vendor-specific).
0875 * <P>
0876 * <B>Note:</B> This method is optimized for handling
0877 * parametric SQL statements that benefit from precompilation. If
0878 * the driver supports precompilation,
0879 * the method <code>prepareStatement</code> will send
0880 * the statement to the database for precompilation. Some drivers
0881 * may not support precompilation. In this case, the statement may
0882 * not be sent to the database until the <code>PreparedStatement</code>
0883 * object is executed. This has no direct effect on users; however, it does
0884 * affect which methods throw certain SQLExceptions.
0885 * <P>
0886 * Result sets created using the returned <code>PreparedStatement</code>
0887 * object will by default be type <code>TYPE_FORWARD_ONLY</code>
0888 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
0889 * The holdability of the created result sets can be determined by
0890 * calling {@link #getHoldability}.
0891 *
0892 * @param sql an SQL statement that may contain one or more '?' IN
0893 * parameter placeholders
0894 * @param autoGeneratedKeys a flag indicating whether auto-generated keys
0895 * should be returned; one of
0896 * <code>Statement.RETURN_GENERATED_KEYS</code> or
0897 * <code>Statement.NO_GENERATED_KEYS</code>
0898 * @return a new <code>PreparedStatement</code> object, containing the
0899 * pre-compiled SQL statement, that will have the capability of
0900 * returning auto-generated keys
0901 * @exception SQLException if a database access error occurs, this
0902 * method is called on a closed connection
0903 * or the given parameter is not a <code>Statement</code>
0904 * constant indicating whether auto-generated keys should be
0905 * returned
0906 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0907 * this method with a constant of Statement.RETURN_GENERATED_KEYS
0908 * @since 1.4
0909 */
0910 PreparedStatement prepareStatement(String sql, int autoGeneratedKeys)
0911 throws SQLException;
0912
0913 /**
0914 * Creates a default <code>PreparedStatement</code> object capable
0915 * of returning the auto-generated keys designated by the given array.
0916 * This array contains the indexes of the columns in the target
0917 * table that contain the auto-generated keys that should be made
0918 * available. The driver will ignore the array if the SQL statement
0919 * is not an <code>INSERT</code> statement, or an SQL statement able to return
0920 * auto-generated keys (the list of such statements is vendor-specific).
0921 *<p>
0922 * An SQL statement with or without IN parameters can be
0923 * pre-compiled and stored in a <code>PreparedStatement</code> object. This
0924 * object can then be used to efficiently execute this statement
0925 * multiple times.
0926 * <P>
0927 * <B>Note:</B> This method is optimized for handling
0928 * parametric SQL statements that benefit from precompilation. If
0929 * the driver supports precompilation,
0930 * the method <code>prepareStatement</code> will send
0931 * the statement to the database for precompilation. Some drivers
0932 * may not support precompilation. In this case, the statement may
0933 * not be sent to the database until the <code>PreparedStatement</code>
0934 * object is executed. This has no direct effect on users; however, it does
0935 * affect which methods throw certain SQLExceptions.
0936 * <P>
0937 * Result sets created using the returned <code>PreparedStatement</code>
0938 * object will by default be type <code>TYPE_FORWARD_ONLY</code>
0939 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
0940 * The holdability of the created result sets can be determined by
0941 * calling {@link #getHoldability}.
0942 *
0943 * @param sql an SQL statement that may contain one or more '?' IN
0944 * parameter placeholders
0945 * @param columnIndexes an array of column indexes indicating the columns
0946 * that should be returned from the inserted row or rows
0947 * @return a new <code>PreparedStatement</code> object, containing the
0948 * pre-compiled statement, that is capable of returning the
0949 * auto-generated keys designated by the given array of column
0950 * indexes
0951 * @exception SQLException if a database access error occurs
0952 * or this method is called on a closed connection
0953 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0954 * this method
0955 *
0956 * @since 1.4
0957 */
0958 PreparedStatement prepareStatement(String sql, int columnIndexes[])
0959 throws SQLException;
0960
0961 /**
0962 * Creates a default <code>PreparedStatement</code> object capable
0963 * of returning the auto-generated keys designated by the given array.
0964 * This array contains the names of the columns in the target
0965 * table that contain the auto-generated keys that should be returned.
0966 * The driver will ignore the array if the SQL statement
0967 * is not an <code>INSERT</code> statement, or an SQL statement able to return
0968 * auto-generated keys (the list of such statements is vendor-specific).
0969 * <P>
0970 * An SQL statement with or without IN parameters can be
0971 * pre-compiled and stored in a <code>PreparedStatement</code> object. This
0972 * object can then be used to efficiently execute this statement
0973 * multiple times.
0974 * <P>
0975 * <B>Note:</B> This method is optimized for handling
0976 * parametric SQL statements that benefit from precompilation. If
0977 * the driver supports precompilation,
0978 * the method <code>prepareStatement</code> will send
0979 * the statement to the database for precompilation. Some drivers
0980 * may not support precompilation. In this case, the statement may
0981 * not be sent to the database until the <code>PreparedStatement</code>
0982 * object is executed. This has no direct effect on users; however, it does
0983 * affect which methods throw certain SQLExceptions.
0984 * <P>
0985 * Result sets created using the returned <code>PreparedStatement</code>
0986 * object will by default be type <code>TYPE_FORWARD_ONLY</code>
0987 * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
0988 * The holdability of the created result sets can be determined by
0989 * calling {@link #getHoldability}.
0990 *
0991 * @param sql an SQL statement that may contain one or more '?' IN
0992 * parameter placeholders
0993 * @param columnNames an array of column names indicating the columns
0994 * that should be returned from the inserted row or rows
0995 * @return a new <code>PreparedStatement</code> object, containing the
0996 * pre-compiled statement, that is capable of returning the
0997 * auto-generated keys designated by the given array of column
0998 * names
0999 * @exception SQLException if a database access error occurs
1000 * or this method is called on a closed connection
1001 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1002 * this method
1003 *
1004 * @since 1.4
1005 */
1006 PreparedStatement prepareStatement(String sql, String columnNames[])
1007 throws SQLException;
1008
1009 /**
1010 * Constructs an object that implements the <code>Clob</code> interface. The object
1011 * returned initially contains no data. The <code>setAsciiStream</code>,
1012 * <code>setCharacterStream</code> and <code>setString</code> methods of
1013 * the <code>Clob</code> interface may be used to add data to the <code>Clob</code>.
1014 * @return An object that implements the <code>Clob</code> interface
1015 * @throws SQLException if an object that implements the
1016 * <code>Clob</code> interface can not be constructed, this method is
1017 * called on a closed connection or a database access error occurs.
1018 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1019 * this data type
1020 *
1021 * @since 1.6
1022 */
1023 Clob createClob() throws SQLException;
1024
1025 /**
1026 * Constructs an object that implements the <code>Blob</code> interface. The object
1027 * returned initially contains no data. The <code>setBinaryStream</code> and
1028 * <code>setBytes</code> methods of the <code>Blob</code> interface may be used to add data to
1029 * the <code>Blob</code>.
1030 * @return An object that implements the <code>Blob</code> interface
1031 * @throws SQLException if an object that implements the
1032 * <code>Blob</code> interface can not be constructed, this method is
1033 * called on a closed connection or a database access error occurs.
1034 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1035 * this data type
1036 *
1037 * @since 1.6
1038 */
1039 Blob createBlob() throws SQLException;
1040
1041 /**
1042 * Constructs an object that implements the <code>NClob</code> interface. The object
1043 * returned initially contains no data. The <code>setAsciiStream</code>,
1044 * <code>setCharacterStream</code> and <code>setString</code> methods of the <code>NClob</code> interface may
1045 * be used to add data to the <code>NClob</code>.
1046 * @return An object that implements the <code>NClob</code> interface
1047 * @throws SQLException if an object that implements the
1048 * <code>NClob</code> interface can not be constructed, this method is
1049 * called on a closed connection or a database access error occurs.
1050 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1051 * this data type
1052 *
1053 * @since 1.6
1054 */
1055 NClob createNClob() throws SQLException;
1056
1057 /**
1058 * Constructs an object that implements the <code>SQLXML</code> interface. The object
1059 * returned initially contains no data. The <code>createXmlStreamWriter</code> object and
1060 * <code>setString</code> method of the <code>SQLXML</code> interface may be used to add data to the <code>SQLXML</code>
1061 * object.
1062 * @return An object that implements the <code>SQLXML</code> interface
1063 * @throws SQLException if an object that implements the <code>SQLXML</code> interface can not
1064 * be constructed, this method is
1065 * called on a closed connection or a database access error occurs.
1066 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1067 * this data type
1068 * @since 1.6
1069 */
1070 SQLXML createSQLXML() throws SQLException;
1071
1072 /**
1073 * Returns true if the connection has not been closed and is still valid.
1074 * The driver shall submit a query on the connection or use some other
1075 * mechanism that positively verifies the connection is still valid when
1076 * this method is called.
1077 * <p>
1078 * The query submitted by the driver to validate the connection shall be
1079 * executed in the context of the current transaction.
1080 *
1081 * @param timeout - The time in seconds to wait for the database operation
1082 * used to validate the connection to complete. If
1083 * the timeout period expires before the operation
1084 * completes, this method returns false. A value of
1085 * 0 indicates a timeout is not applied to the
1086 * database operation.
1087 * <p>
1088 * @return true if the connection is valid, false otherwise
1089 * @exception SQLException if the value supplied for <code>timeout</code>
1090 * is less then 0
1091 * @since 1.6
1092 * <p>
1093 * @see java.sql.DatabaseMetaData#getClientInfoProperties
1094 */
1095 boolean isValid(int timeout) throws SQLException;
1096
1097 /**
1098 * Sets the value of the client info property specified by name to the
1099 * value specified by value.
1100 * <p>
1101 * Applications may use the <code>DatabaseMetaData.getClientInfoProperties</code>
1102 * method to determine the client info properties supported by the driver
1103 * and the maximum length that may be specified for each property.
1104 * <p>
1105 * The driver stores the value specified in a suitable location in the
1106 * database. For example in a special register, session parameter, or
1107 * system table column. For efficiency the driver may defer setting the
1108 * value in the database until the next time a statement is executed or
1109 * prepared. Other than storing the client information in the appropriate
1110 * place in the database, these methods shall not alter the behavior of
1111 * the connection in anyway. The values supplied to these methods are
1112 * used for accounting, diagnostics and debugging purposes only.
1113 * <p>
1114 * The driver shall generate a warning if the client info name specified
1115 * is not recognized by the driver.
1116 * <p>
1117 * If the value specified to this method is greater than the maximum
1118 * length for the property the driver may either truncate the value and
1119 * generate a warning or generate a <code>SQLClientInfoException</code>. If the driver
1120 * generates a <code>SQLClientInfoException</code>, the value specified was not set on the
1121 * connection.
1122 * <p>
1123 * The following are standard client info properties. Drivers are not
1124 * required to support these properties however if the driver supports a
1125 * client info property that can be described by one of the standard
1126 * properties, the standard property name should be used.
1127 * <p>
1128 * <ul>
1129 * <li>ApplicationName - The name of the application currently utilizing
1130 * the connection</li>
1131 * <li>ClientUser - The name of the user that the application using
1132 * the connection is performing work for. This may
1133 * not be the same as the user name that was used
1134 * in establishing the connection.</li>
1135 * <li>ClientHostname - The hostname of the computer the application
1136 * using the connection is running on.</li>
1137 * </ul>
1138 * <p>
1139 * @param name The name of the client info property to set
1140 * @param value The value to set the client info property to. If the
1141 * value is null, the current value of the specified
1142 * property is cleared.
1143 * <p>
1144 * @throws SQLClientInfoException if the database server returns an error while
1145 * setting the client info value on the database server or this method
1146 * is called on a closed connection
1147 * <p>
1148 * @since 1.6
1149 */
1150 void setClientInfo(String name, String value)
1151 throws SQLClientInfoException;
1152
1153 /**
1154 * Sets the value of the connection's client info properties. The
1155 * <code>Properties</code> object contains the names and values of the client info
1156 * properties to be set. The set of client info properties contained in
1157 * the properties list replaces the current set of client info properties
1158 * on the connection. If a property that is currently set on the
1159 * connection is not present in the properties list, that property is
1160 * cleared. Specifying an empty properties list will clear all of the
1161 * properties on the connection. See <code>setClientInfo (String, String)</code> for
1162 * more information.
1163 * <p>
1164 * If an error occurs in setting any of the client info properties, a
1165 * <code>SQLClientInfoException</code> is thrown. The <code>SQLClientInfoException</code>
1166 * contains information indicating which client info properties were not set.
1167 * The state of the client information is unknown because
1168 * some databases do not allow multiple client info properties to be set
1169 * atomically. For those databases, one or more properties may have been
1170 * set before the error occurred.
1171 * <p>
1172 *
1173 * @param properties the list of client info properties to set
1174 * <p>
1175 * @see java.sql.Connection#setClientInfo(String, String) setClientInfo(String, String)
1176 * @since 1.6
1177 * <p>
1178 * @throws SQLClientInfoException if the database server returns an error while
1179 * setting the clientInfo values on the database server or this method
1180 * is called on a closed connection
1181 * <p>
1182 */
1183 void setClientInfo(Properties properties)
1184 throws SQLClientInfoException;
1185
1186 /**
1187 * Returns the value of the client info property specified by name. This
1188 * method may return null if the specified client info property has not
1189 * been set and does not have a default value. This method will also
1190 * return null if the specified client info property name is not supported
1191 * by the driver.
1192 * <p>
1193 * Applications may use the <code>DatabaseMetaData.getClientInfoProperties</code>
1194 * method to determine the client info properties supported by the driver.
1195 * <p>
1196 * @param name The name of the client info property to retrieve
1197 * <p>
1198 * @return The value of the client info property specified
1199 * <p>
1200 * @throws SQLException if the database server returns an error when
1201 * fetching the client info value from the database
1202 *or this method is called on a closed connection
1203 * <p>
1204 * @since 1.6
1205 * <p>
1206 * @see java.sql.DatabaseMetaData#getClientInfoProperties
1207 */
1208 String getClientInfo(String name) throws SQLException;
1209
1210 /**
1211 * Returns a list containing the name and current value of each client info
1212 * property supported by the driver. The value of a client info property
1213 * may be null if the property has not been set and does not have a
1214 * default value.
1215 * <p>
1216 * @return A <code>Properties</code> object that contains the name and current value of
1217 * each of the client info properties supported by the driver.
1218 * <p>
1219 * @throws SQLException if the database server returns an error when
1220 * fetching the client info values from the database
1221 * or this method is called on a closed connection
1222 * <p>
1223 * @since 1.6
1224 */
1225 Properties getClientInfo() throws SQLException;
1226
1227 /**
1228 * Factory method for creating Array objects.
1229 *<p>
1230 * <b>Note: </b>When <code>createArrayOf</code> is used to create an array object
1231 * that maps to a primitive data type, then it is implementation-defined
1232 * whether the <code>Array</code> object is an array of that primitive
1233 * data type or an array of <code>Object</code>.
1234 * <p>
1235 * <b>Note: </b>The JDBC driver is responsible for mapping the elements
1236 * <code>Object</code> array to the default JDBC SQL type defined in
1237 * java.sql.Types for the given class of <code>Object</code>. The default
1238 * mapping is specified in Appendix B of the JDBC specification. If the
1239 * resulting JDBC type is not the appropriate type for the given typeName then
1240 * it is implementation defined whether an <code>SQLException</code> is
1241 * thrown or the driver supports the resulting conversion.
1242 *
1243 * @param typeName the SQL name of the type the elements of the array map to. The typeName is a
1244 * database-specific name which may be the name of a built-in type, a user-defined type or a standard SQL type supported by this database. This
1245 * is the value returned by <code>Array.getBaseTypeName</code>
1246 * @param elements the elements that populate the returned object
1247 * @return an Array object whose elements map to the specified SQL type
1248 * @throws SQLException if a database error occurs, the JDBC type is not
1249 * appropriate for the typeName and the conversion is not supported, the typeName is null or this method is called on a closed connection
1250 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this data type
1251 * @since 1.6
1252 */
1253 Array createArrayOf(String typeName, Object[] elements)
1254 throws SQLException;
1255
1256 /**
1257 * Factory method for creating Struct objects.
1258 *
1259 * @param typeName the SQL type name of the SQL structured type that this <code>Struct</code>
1260 * object maps to. The typeName is the name of a user-defined type that
1261 * has been defined for this database. It is the value returned by
1262 * <code>Struct.getSQLTypeName</code>.
1263
1264 * @param attributes the attributes that populate the returned object
1265 * @return a Struct object that maps to the given SQL type and is populated with the given attributes
1266 * @throws SQLException if a database error occurs, the typeName is null or this method is called on a closed connection
1267 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this data type
1268 * @since 1.6
1269 */
1270 Struct createStruct(String typeName, Object[] attributes)
1271 throws SQLException;
1272 }
|