diff --git a/src/java.sql/share/classes/java/sql/Connection.java b/src/java.sql/share/classes/java/sql/Connection.java index f1de63bd51b..19f283f5762 100644 --- a/src/java.sql/share/classes/java/sql/Connection.java +++ b/src/java.sql/share/classes/java/sql/Connection.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2024, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2025, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -27,6 +27,7 @@ package java.sql; import java.util.Properties; import java.util.concurrent.Executor; +import java.util.Map; /** *

A connection (session) with a specific @@ -82,7 +83,7 @@ import java.util.concurrent.Executor; * @see DatabaseMetaData * @since 1.1 */ -public interface Connection extends Wrapper, AutoCloseable { +public interface Connection extends Wrapper, AutoCloseable { /** * Creates a {@code Statement} object for sending @@ -136,8 +137,7 @@ public interface Connection extends Wrapper, AutoCloseable { * @throws SQLException if a database access error occurs * or this method is called on a closed connection */ - PreparedStatement prepareStatement(String sql) - throws SQLException; + PreparedStatement prepareStatement(String sql) throws SQLException; /** * Creates a {@code CallableStatement} object for calling @@ -498,7 +498,6 @@ public interface Connection extends Wrapper, AutoCloseable { */ void clearWarnings() throws SQLException; - //--------------------------JDBC 2.0----------------------------- /** @@ -529,8 +528,7 @@ public interface Connection extends Wrapper, AutoCloseable { * set type and result set concurrency. * @since 1.2 */ - Statement createStatement(int resultSetType, int resultSetConcurrency) - throws SQLException; + Statement createStatement(int resultSetType, int resultSetConcurrency) throws SQLException; /** * @@ -626,7 +624,7 @@ public interface Connection extends Wrapper, AutoCloseable { * @since 1.2 * @see #setTypeMap */ - java.util.Map> getTypeMap() throws SQLException; + Map> getTypeMap() throws SQLException; /** * Installs the given {@code TypeMap} object as the type map for @@ -654,11 +652,10 @@ public interface Connection extends Wrapper, AutoCloseable { * @since 1.2 * @see #getTypeMap */ - void setTypeMap(java.util.Map> map) throws SQLException; + void setTypeMap(Map> map) throws SQLException; //--------------------------JDBC 3.0----------------------------- - /** * Changes the default holdability of {@code ResultSet} objects * created using this {@code Connection} object to the given @@ -894,7 +891,6 @@ public interface Connection extends Wrapper, AutoCloseable { int resultSetConcurrency, int resultSetHoldability) throws SQLException; - /** * Creates a default {@code PreparedStatement} object that has * the capability to retrieve auto-generated keys. The given constant @@ -937,8 +933,7 @@ public interface Connection extends Wrapper, AutoCloseable { * this method with a constant of Statement.RETURN_GENERATED_KEYS * @since 1.4 */ - PreparedStatement prepareStatement(String sql, int autoGeneratedKeys) - throws SQLException; + PreparedStatement prepareStatement(String sql, int autoGeneratedKeys) throws SQLException; /** * Creates a default {@code PreparedStatement} object capable @@ -985,8 +980,7 @@ public interface Connection extends Wrapper, AutoCloseable { * * @since 1.4 */ - PreparedStatement prepareStatement(String sql, int columnIndexes[]) - throws SQLException; + PreparedStatement prepareStatement(String sql, int columnIndexes[]) throws SQLException; /** * Creates a default {@code PreparedStatement} object capable @@ -1033,8 +1027,7 @@ public interface Connection extends Wrapper, AutoCloseable { * * @since 1.4 */ - PreparedStatement prepareStatement(String sql, String columnNames[]) - throws SQLException; + PreparedStatement prepareStatement(String sql, String columnNames[]) throws SQLException; /** * Constructs an object that implements the {@code Clob} interface. The object @@ -1099,87 +1092,86 @@ public interface Connection extends Wrapper, AutoCloseable { */ SQLXML createSQLXML() throws SQLException; - /** - * Returns true if the connection has not been closed and is still valid. - * The driver shall submit a query on the connection or use some other - * mechanism that positively verifies the connection is still valid when - * this method is called. - *

- * The query submitted by the driver to validate the connection shall be - * executed in the context of the current transaction. - * - * @param timeout The time in seconds to wait for the database operation - * used to validate the connection to complete. If the - * timeout period expires before the operationcompletes, - * this method returns false. A value of 0 indicates a - * timeout is not applied to the database operation. - * - * @return true if the connection is valid, false otherwise - * @throws SQLException if the value supplied for {@code timeout} - * is less than 0 - * @since 1.6 - * - * @see java.sql.DatabaseMetaData#getClientInfoProperties - */ - boolean isValid(int timeout) throws SQLException; + /** + * Returns true if the connection has not been closed and is still valid. + * The driver shall submit a query on the connection or use some other + * mechanism that positively verifies the connection is still valid when + * this method is called. + *

+ * The query submitted by the driver to validate the connection shall be + * executed in the context of the current transaction. + * + * @param timeout The time in seconds to wait for the database operation + * used to validate the connection to complete. If the + * timeout period expires before the operationcompletes, + * this method returns false. A value of 0 indicates a + * timeout is not applied to the database operation. + * + * @return true if the connection is valid, false otherwise + * @throws SQLException if the value supplied for {@code timeout} + * is less than 0 + * @since 1.6 + * + * @see java.sql.DatabaseMetaData#getClientInfoProperties + */ + boolean isValid(int timeout) throws SQLException; - /** - * Sets the value of the client info property specified by name to the - * value specified by value. - *

- * Applications may use the {@code DatabaseMetaData.getClientInfoProperties} - * method to determine the client info properties supported by the driver - * and the maximum length that may be specified for each property. - *

- * The driver stores the value specified in a suitable location in the - * database. For example in a special register, session parameter, or - * system table column. For efficiency the driver may defer setting the - * value in the database until the next time a statement is executed or - * prepared. Other than storing the client information in the appropriate - * place in the database, these methods shall not alter the behavior of - * the connection in anyway. The values supplied to these methods are - * used for accounting, diagnostics and debugging purposes only. - *

- * The driver shall generate a warning if the client info name specified - * is not recognized by the driver. - *

- * If the value specified to this method is greater than the maximum - * length for the property the driver may either truncate the value and - * generate a warning or generate a {@code SQLClientInfoException}. If the driver - * generates a {@code SQLClientInfoException}, the value specified was not set on the - * connection. - *

- * The following are standard client info properties. Drivers are not - * required to support these properties however if the driver supports a - * client info property that can be described by one of the standard - * properties, the standard property name should be used. - * - *

- * - * @param name The name of the client info property to set - * @param value The value to set the client info property to. If the - * value is null, the current value of the specified - * property is cleared. - * - * @throws SQLClientInfoException if the database server returns an error while - * setting the client info value on the database server or this method - * is called on a closed connection - * - * @since 1.6 - */ - void setClientInfo(String name, String value) - throws SQLClientInfoException; + /** + * Sets the value of the client info property specified by name to the + * value specified by value. + *

+ * Applications may use the {@code DatabaseMetaData.getClientInfoProperties} + * method to determine the client info properties supported by the driver + * and the maximum length that may be specified for each property. + *

+ * The driver stores the value specified in a suitable location in the + * database. For example in a special register, session parameter, or + * system table column. For efficiency the driver may defer setting the + * value in the database until the next time a statement is executed or + * prepared. Other than storing the client information in the appropriate + * place in the database, these methods shall not alter the behavior of + * the connection in anyway. The values supplied to these methods are + * used for accounting, diagnostics and debugging purposes only. + *

+ * The driver shall generate a warning if the client info name specified + * is not recognized by the driver. + *

+ * If the value specified to this method is greater than the maximum + * length for the property the driver may either truncate the value and + * generate a warning or generate a {@code SQLClientInfoException}. If the driver + * generates a {@code SQLClientInfoException}, the value specified was not set on the + * connection. + *

+ * The following are standard client info properties. Drivers are not + * required to support these properties however if the driver supports a + * client info property that can be described by one of the standard + * properties, the standard property name should be used. + * + *

+ * + * @param name The name of the client info property to set + * @param value The value to set the client info property to. If the + * value is null, the current value of the specified + * property is cleared. + * + * @throws SQLClientInfoException if the database server returns an error while + * setting the client info value on the database server or this method + * is called on a closed connection + * + * @since 1.6 + */ + void setClientInfo(String name, String value) throws SQLClientInfoException; - /** + /** * Sets the value of the connection's client info properties. The * {@code Properties} object contains the names and values of the client info * properties to be set. The set of client info properties contained in @@ -1209,97 +1201,92 @@ public interface Connection extends Wrapper, AutoCloseable { * is called on a closed connection * */ - void setClientInfo(Properties properties) - throws SQLClientInfoException; + void setClientInfo(Properties properties) throws SQLClientInfoException; - /** - * Returns the value of the client info property specified by name. This - * method may return null if the specified client info property has not - * been set and does not have a default value. This method will also - * return null if the specified client info property name is not supported - * by the driver. - *

- * Applications may use the {@code DatabaseMetaData.getClientInfoProperties} - * method to determine the client info properties supported by the driver. - * - * @param name The name of the client info property to retrieve - * - * @return The value of the client info property specified - * - * @throws SQLException if the database server returns an error when - * fetching the client info value from the database - * or this method is called on a closed connection - * - * @since 1.6 - * - * @see java.sql.DatabaseMetaData#getClientInfoProperties - */ - String getClientInfo(String name) - throws SQLException; + /** + * Returns the value of the client info property specified by name. This + * method may return null if the specified client info property has not + * been set and does not have a default value. This method will also + * return null if the specified client info property name is not supported + * by the driver. + *

+ * Applications may use the {@code DatabaseMetaData.getClientInfoProperties} + * method to determine the client info properties supported by the driver. + * + * @param name The name of the client info property to retrieve + * + * @return The value of the client info property specified + * + * @throws SQLException if the database server returns an error when + * fetching the client info value from the database + * or this method is called on a closed connection + * + * @since 1.6 + * + * @see java.sql.DatabaseMetaData#getClientInfoProperties + */ + String getClientInfo(String name) throws SQLException; - /** - * Returns a list containing the name and current value of each client info - * property supported by the driver. The value of a client info property - * may be null if the property has not been set and does not have a - * default value. - * - * @return A {@code Properties} object that contains the name and current value of - * each of the client info properties supported by the driver. - * - * @throws SQLException if the database server returns an error when - * fetching the client info values from the database - * or this method is called on a closed connection - * - * @since 1.6 - */ - Properties getClientInfo() - throws SQLException; + /** + * Returns a list containing the name and current value of each client info + * property supported by the driver. The value of a client info property + * may be null if the property has not been set and does not have a + * default value. + * + * @return A {@code Properties} object that contains the name and current value of + * each of the client info properties supported by the driver. + * + * @throws SQLException if the database server returns an error when + * fetching the client info values from the database + * or this method is called on a closed connection + * + * @since 1.6 + */ + Properties getClientInfo() throws SQLException; -/** - * Factory method for creating Array objects. - *

- * Note: When {@code createArrayOf} is used to create an array object - * that maps to a primitive data type, then it is implementation-defined - * whether the {@code Array} object is an array of that primitive - * data type or an array of {@code Object}. - *

- * Note: The JDBC driver is responsible for mapping the elements - * {@code Object} array to the default JDBC SQL type defined in - * java.sql.Types for the given class of {@code Object}. The default - * mapping is specified in Appendix B of the JDBC specification. If the - * resulting JDBC type is not the appropriate type for the given typeName then - * it is implementation defined whether an {@code SQLException} is - * thrown or the driver supports the resulting conversion. - * - * @param typeName the SQL name of the type the elements of the array map to. The typeName is a - * 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 - * is the value returned by {@code Array.getBaseTypeName} - * @param elements the elements that populate the returned object - * @return an Array object whose elements map to the specified SQL type - * @throws SQLException if a database error occurs, the JDBC type is not - * appropriate for the typeName and the conversion is not supported, the typeName is null or this method is called on a closed connection - * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this data type - * @since 1.6 - */ - Array createArrayOf(String typeName, Object[] elements) throws -SQLException; + /** + * Factory method for creating Array objects. + *

+ * Note: When {@code createArrayOf} is used to create an array object + * that maps to a primitive data type, then it is implementation-defined + * whether the {@code Array} object is an array of that primitive + * data type or an array of {@code Object}. + *

+ * Note: The JDBC driver is responsible for mapping the elements + * {@code Object} array to the default JDBC SQL type defined in + * java.sql.Types for the given class of {@code Object}. The default + * mapping is specified in Appendix B of the JDBC specification. If the + * resulting JDBC type is not the appropriate type for the given typeName then + * it is implementation defined whether an {@code SQLException} is + * thrown or the driver supports the resulting conversion. + * + * @param typeName the SQL name of the type the elements of the array map to. The typeName is a + * 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 + * is the value returned by {@code Array.getBaseTypeName} + * @param elements the elements that populate the returned object + * @return an Array object whose elements map to the specified SQL type + * @throws SQLException if a database error occurs, the JDBC type is not + * appropriate for the typeName and the conversion is not supported, the typeName is null or this method is called on a closed connection + * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this data type + * @since 1.6 + */ + Array createArrayOf(String typeName, Object[] elements) throws SQLException; -/** - * Factory method for creating Struct objects. - * - * @param typeName the SQL type name of the SQL structured type that this {@code Struct} - * object maps to. The typeName is the name of a user-defined type that - * has been defined for this database. It is the value returned by - * {@code Struct.getSQLTypeName}. - - * @param attributes the attributes that populate the returned object - * @return a Struct object that maps to the given SQL type and is populated with the given attributes - * @throws SQLException if a database error occurs, the typeName is null or this method is called on a closed connection - * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this data type - * @since 1.6 - */ - Struct createStruct(String typeName, Object[] attributes) -throws SQLException; + /** + * Factory method for creating Struct objects. + * + * @param typeName the SQL type name of the SQL structured type that this {@code Struct} + * object maps to. The typeName is the name of a user-defined type that + * has been defined for this database. It is the value returned by + * {@code Struct.getSQLTypeName}. + * + * @param attributes the attributes that populate the returned object + * @return a Struct object that maps to the given SQL type and is populated with the given attributes + * @throws SQLException if a database error occurs, the typeName is null or this method is called on a closed connection + * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this data type + * @since 1.6 + */ + Struct createStruct(String typeName, Object[] attributes) throws SQLException; //--------------------------JDBC 4.1 ----------------------------- @@ -1463,7 +1450,7 @@ throws SQLException; // JDBC 4.3 - /** + /** * Hints to the driver that a request, an independent unit of work, is beginning * on this connection. Each request is independent of all other requests * with regard to state local to the connection either on the client or the @@ -1534,7 +1521,7 @@ throws SQLException; * marks the request completed and subsequent calls are treated as * a no-op. If {@code endRequest} is called without an initial call to * {@code beginRequest} is a no-op. - *

+ *

* The exact behavior of this method is vendor specific. In particular * implementations may detect conditions that indicate dependence on * other work such as an open transaction. It is recommended though not @@ -1565,7 +1552,7 @@ throws SQLException; * @see javax.sql.PooledConnection */ default void endRequest() throws SQLException { - // Default method takes no action + // Default method takes no action } /** @@ -1686,8 +1673,8 @@ throws SQLException; * @see ShardingKey * @see ShardingKeyBuilder */ - default void setShardingKey(ShardingKey shardingKey) - throws SQLException { + default void setShardingKey(ShardingKey shardingKey) throws SQLException { throw new SQLFeatureNotSupportedException("setShardingKey not implemented"); } + }