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: }
|
