diff options
author | lancea <none@none> | 2013-01-19 10:53:14 -0500 |
---|---|---|
committer | lancea <none@none> | 2013-01-19 10:53:14 -0500 |
commit | 0d9db280368c2ff492a5e9300ca4b9a32f304cdf (patch) | |
tree | 29a7980cb0e05948cfac4b3e6218aaa95c8cb6e7 /src/share/classes/java/sql | |
parent | 7ccae8a05afc1b003f735e78f67a49628bded50b (diff) | |
download | jdk8u_jdk-0d9db280368c2ff492a5e9300ca4b9a32f304cdf.tar.gz |
8005080: JDBC 4.2 Core changes
Reviewed-by: naoto
Diffstat (limited to 'src/share/classes/java/sql')
-rw-r--r-- | src/share/classes/java/sql/BatchUpdateException.java | 414 | ||||
-rw-r--r-- | src/share/classes/java/sql/CallableStatement.java | 366 | ||||
-rw-r--r-- | src/share/classes/java/sql/DatabaseMetaData.java | 41 | ||||
-rw-r--r-- | src/share/classes/java/sql/Driver.java | 19 | ||||
-rw-r--r-- | src/share/classes/java/sql/DriverManager.java | 38 | ||||
-rw-r--r-- | src/share/classes/java/sql/JDBCType.java | 251 | ||||
-rw-r--r-- | src/share/classes/java/sql/PreparedStatement.java | 145 | ||||
-rw-r--r-- | src/share/classes/java/sql/ResultSet.java | 147 | ||||
-rw-r--r-- | src/share/classes/java/sql/SQLTimeoutException.java | 8 | ||||
-rw-r--r-- | src/share/classes/java/sql/SQLType.java | 56 | ||||
-rw-r--r-- | src/share/classes/java/sql/Statement.java | 312 | ||||
-rw-r--r-- | src/share/classes/java/sql/Types.java | 12 | ||||
-rw-r--r-- | src/share/classes/java/sql/package.html | 44 |
13 files changed, 1675 insertions, 178 deletions
diff --git a/src/share/classes/java/sql/BatchUpdateException.java b/src/share/classes/java/sql/BatchUpdateException.java index 19742c82fa..9f5fb2e33b 100644 --- a/src/share/classes/java/sql/BatchUpdateException.java +++ b/src/share/classes/java/sql/BatchUpdateException.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2011, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2013, 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 @@ -25,6 +25,10 @@ package java.sql; +import java.io.IOException; +import java.io.InvalidObjectException; +import java.io.ObjectInputStream; +import java.io.ObjectOutputStream; import java.util.Arrays; /** @@ -49,6 +53,15 @@ import java.util.Arrays; * commands, the array element for any command * that failed is <code>Statement.EXECUTE_FAILED</code>. * <P> + * A JDBC driver implementation should use + * the constructor {@code BatchUpdateException(String reason, String SQLState, + * int vendorCode, long []updateCounts,Throwable cause) } instead of + * constructors that take {@code int[]} for the update counts to avoid the + * possibility of overflow. + * <p> + * If {@code Statement.executeLargeBatch} method is invoked it is recommended that + * {@code getLargeUpdateCounts} be called instead of {@code getUpdateCounts} + * in order to avoid a possible overflow of the integer update count. * @since 1.2 */ @@ -62,7 +75,11 @@ public class BatchUpdateException extends SQLException { * initialized by a call to the * {@link Throwable#initCause(java.lang.Throwable)} method. * <p> - * + * <strong>Note:</strong> There is no validation of {@code updateCounts} for + * overflow and because of this it is recommended that you use the constructor + * {@code BatchUpdateException(String reason, String SQLState, + * int vendorCode, long []updateCounts,Throwable cause) }. + * </p> * @param reason a description of the error * @param SQLState an XOPEN or SQL:2003 code identifying the exception * @param vendorCode an exception code used by a particular @@ -76,11 +93,14 @@ public class BatchUpdateException extends SQLException { * prior to the failure for JDBC drivers that stop processing after a command * failure * @since 1.2 + * @see #BatchUpdateException(java.lang.String, java.lang.String, int, long[], + * java.lang.Throwable) */ public BatchUpdateException( String reason, String SQLState, int vendorCode, int[] updateCounts ) { super(reason, SQLState, vendorCode); this.updateCounts = (updateCounts == null) ? null : Arrays.copyOf(updateCounts, updateCounts.length); + this.longUpdateCounts = (updateCounts == null) ? null : copyUpdateCount(updateCounts); } /** @@ -92,7 +112,11 @@ public class BatchUpdateException extends SQLException { * {@link Throwable#initCause(java.lang.Throwable)} method. The vendor code * is initialized to 0. * <p> - * + * <strong>Note:</strong> There is no validation of {@code updateCounts} for + * overflow and because of this it is recommended that you use the constructor + * {@code BatchUpdateException(String reason, String SQLState, + * int vendorCode, long []updateCounts,Throwable cause) }. + * </p> * @param reason a description of the exception * @param SQLState an XOPEN or SQL:2003 code identifying the exception * @param updateCounts an array of <code>int</code>, with each element @@ -104,6 +128,8 @@ public class BatchUpdateException extends SQLException { * prior to the failure for JDBC drivers that stop processing after a command * failure * @since 1.2 + * @see #BatchUpdateException(java.lang.String, java.lang.String, int, long[], + * java.lang.Throwable) */ public BatchUpdateException(String reason, String SQLState, int[] updateCounts) { @@ -119,8 +145,11 @@ public class BatchUpdateException extends SQLException { * <code>SQLState</code> is initialized to <code>null</code> * and the vender code is initialized to 0. * <p> - * - * + * <strong>Note:</strong> There is no validation of {@code updateCounts} for + * overflow and because of this it is recommended that you use the constructor + * {@code BatchUpdateException(String reason, String SQLState, + * int vendorCode, long []updateCounts,Throwable cause) }. + * </p> * @param reason a description of the exception * @param updateCounts an array of <code>int</code>, with each element * indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or @@ -131,6 +160,8 @@ public class BatchUpdateException extends SQLException { * prior to the failure for JDBC drivers that stop processing after a command * failure * @since 1.2 + * @see #BatchUpdateException(java.lang.String, java.lang.String, int, long[], + * java.lang.Throwable) */ public BatchUpdateException(String reason, int[] updateCounts) { this(reason, null, 0, updateCounts); @@ -144,7 +175,11 @@ public class BatchUpdateException extends SQLException { * and <code>SQLState</code> are initialized to null and the vendor code * is initialized to 0. * <p> - * + * <strong>Note:</strong> There is no validation of {@code updateCounts} for + * overflow and because of this it is recommended that you use the constructor + * {@code BatchUpdateException(String reason, String SQLState, + * int vendorCode, long []updateCounts,Throwable cause) }. + * </p> * @param updateCounts an array of <code>int</code>, with each element * indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or * <code>Statement.EXECUTE_FAILED</code> for each SQL command in @@ -154,6 +189,8 @@ public class BatchUpdateException extends SQLException { * prior to the failure for JDBC drivers that stop processing after a command * failure * @since 1.2 + * @see #BatchUpdateException(java.lang.String, java.lang.String, int, long[], + * java.lang.Throwable) */ public BatchUpdateException(int[] updateCounts) { this(null, null, 0, updateCounts); @@ -169,131 +206,167 @@ public class BatchUpdateException extends SQLException { * <p> * * @since 1.2 + * @see #BatchUpdateException(java.lang.String, java.lang.String, int, long[], + * java.lang.Throwable) */ public BatchUpdateException() { this(null, null, 0, null); } - /** - * Constructs a <code>BatchUpdateException</code> object initialized with - * a given <code>cause</code>. - * The <code>SQLState</code> and <code>updateCounts</code> - * are initialized - * to <code>null</code> and the vendor code is initialized to 0. - * The <code>reason</code> is initialized to <code>null</code> if - * <code>cause==null</code> or to <code>cause.toString()</code> if - * <code>cause!=null</code>. - * @param cause the underlying reason for this <code>SQLException</code> - * (which is saved for later retrieval by the <code>getCause()</code> method); - * may be null indicating the cause is non-existent or unknown. - * @since 1.6 - */ - public BatchUpdateException(Throwable cause) { - this((cause == null ? null : cause.toString()), null, 0, null, cause); - } + /** + * Constructs a <code>BatchUpdateException</code> object initialized with + * a given <code>cause</code>. + * The <code>SQLState</code> and <code>updateCounts</code> + * are initialized + * to <code>null</code> and the vendor code is initialized to 0. + * The <code>reason</code> is initialized to <code>null</code> if + * <code>cause==null</code> or to <code>cause.toString()</code> if + * <code>cause!=null</code>. + * @param cause the underlying reason for this <code>SQLException</code> + * (which is saved for later retrieval by the <code>getCause()</code> method); + * may be null indicating the cause is non-existent or unknown. + * @since 1.6 + * @see #BatchUpdateException(java.lang.String, java.lang.String, int, long[], + * java.lang.Throwable) + */ + public BatchUpdateException(Throwable cause) { + this((cause == null ? null : cause.toString()), null, 0, (int[])null, cause); + } - /** - * Constructs a <code>BatchUpdateException</code> object initialized with a - * given <code>cause</code> and <code>updateCounts</code>. - * The <code>SQLState</code> is initialized - * to <code>null</code> and the vendor code is initialized to 0. - * The <code>reason</code> is initialized to <code>null</code> if - * <code>cause==null</code> or to <code>cause.toString()</code> if - * <code>cause!=null</code>. - * - * @param updateCounts an array of <code>int</code>, with each element - * indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or + /** + * Constructs a <code>BatchUpdateException</code> object initialized with a + * given <code>cause</code> and <code>updateCounts</code>. + * The <code>SQLState</code> is initialized + * to <code>null</code> and the vendor code is initialized to 0. + * The <code>reason</code> is initialized to <code>null</code> if + * <code>cause==null</code> or to <code>cause.toString()</code> if + * <code>cause!=null</code>. + * <p> + * <strong>Note:</strong> There is no validation of {@code updateCounts} for + * overflow and because of this it is recommended that you use the constructor + * {@code BatchUpdateException(String reason, String SQLState, + * int vendorCode, long []updateCounts,Throwable cause) }. + * </p> + * @param updateCounts an array of <code>int</code>, with each element + * indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or * <code>Statement.EXECUTE_FAILED</code> for each SQL command in * the batch for JDBC drivers that continue processing * after a command failure; an update count or * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch * prior to the failure for JDBC drivers that stop processing after a command * failure - * @param cause the underlying reason for this <code>SQLException</code> - * (which is saved for later retrieval by the <code>getCause()</code> method); may be null indicating - * the cause is non-existent or unknown. - * @since 1.6 - */ - public BatchUpdateException(int []updateCounts , Throwable cause) { - this((cause == null ? null : cause.toString()), null, 0, updateCounts, cause); - } + * @param cause the underlying reason for this <code>SQLException</code> + * (which is saved for later retrieval by the <code>getCause()</code> method); may be null indicating + * the cause is non-existent or unknown. + * @since 1.6 + * @see #BatchUpdateException(java.lang.String, java.lang.String, int, long[], + * java.lang.Throwable) + */ + public BatchUpdateException(int []updateCounts , Throwable cause) { + this((cause == null ? null : cause.toString()), null, 0, updateCounts, cause); + } - /** - * Constructs a <code>BatchUpdateException</code> object initialized with - * a given <code>reason</code>, <code>cause</code> - * and <code>updateCounts</code>. The <code>SQLState</code> is initialized - * to <code>null</code> and the vendor code is initialized to 0. - * - * @param reason a description of the exception - * @param updateCounts an array of <code>int</code>, with each element - *indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or + /** + * Constructs a <code>BatchUpdateException</code> object initialized with + * a given <code>reason</code>, <code>cause</code> + * and <code>updateCounts</code>. The <code>SQLState</code> is initialized + * to <code>null</code> and the vendor code is initialized to 0. + * <p> + * <strong>Note:</strong> There is no validation of {@code updateCounts} for + * overflow and because of this it is recommended that you use the constructor + * {@code BatchUpdateException(String reason, String SQLState, + * int vendorCode, long []updateCounts,Throwable cause) }. + * </p> + * @param reason a description of the exception + * @param updateCounts an array of <code>int</code>, with each element + *indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or * <code>Statement.EXECUTE_FAILED</code> for each SQL command in * the batch for JDBC drivers that continue processing * after a command failure; an update count or * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch * prior to the failure for JDBC drivers that stop processing after a command * failure - * @param cause the underlying reason for this <code>SQLException</code> (which is saved for later retrieval by the <code>getCause()</code> method); - * may be null indicating - * the cause is non-existent or unknown. - * @since 1.6 - */ - public BatchUpdateException(String reason, int []updateCounts, Throwable cause) { - this(reason, null, 0, updateCounts, cause); - } + * @param cause the underlying reason for this <code>SQLException</code> (which is saved for later retrieval by the <code>getCause()</code> method); + * may be null indicating + * the cause is non-existent or unknown. + * @since 1.6 + * @see #BatchUpdateException(java.lang.String, java.lang.String, int, long[], + * java.lang.Throwable) + */ + public BatchUpdateException(String reason, int []updateCounts, Throwable cause) { + this(reason, null, 0, updateCounts, cause); + } - /** - * Constructs a <code>BatchUpdateException</code> object initialized with - * a given <code>reason</code>, <code>SQLState</code>,<code>cause</code>, and + /** + * Constructs a <code>BatchUpdateException</code> object initialized with + * a given <code>reason</code>, <code>SQLState</code>,<code>cause</code>, and * <code>updateCounts</code>. The vendor code is initialized to 0. - * - * @param reason a description of the exception - * @param SQLState an XOPEN or SQL:2003 code identifying the exception - * @param updateCounts an array of <code>int</code>, with each element - * indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or + * + * @param reason a description of the exception + * @param SQLState an XOPEN or SQL:2003 code identifying the exception + * @param updateCounts an array of <code>int</code>, with each element + * indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or * <code>Statement.EXECUTE_FAILED</code> for each SQL command in * the batch for JDBC drivers that continue processing * after a command failure; an update count or * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch * prior to the failure for JDBC drivers that stop processing after a command * failure - * @param cause the underlying reason for this <code>SQLException</code> (which is saved for later retrieval by the <code>getCause()</code> method); - * may be null indicating - * the cause is non-existent or unknown. - * @since 1.6 - */ - public BatchUpdateException(String reason, String SQLState, - int []updateCounts, Throwable cause) { - this(reason, SQLState, 0, updateCounts, cause); - } + * <p> + * <strong>Note:</strong> There is no validation of {@code updateCounts} for + * overflow and because of this it is recommended that you use the constructor + * {@code BatchUpdateException(String reason, String SQLState, + * int vendorCode, long []updateCounts,Throwable cause) }. + * </p> + * @param cause the underlying reason for this <code>SQLException</code> + * (which is saved for later retrieval by the <code>getCause()</code> method); + * may be null indicating + * the cause is non-existent or unknown. + * @since 1.6 + * @see #BatchUpdateException(java.lang.String, java.lang.String, int, long[], + * java.lang.Throwable) + */ + public BatchUpdateException(String reason, String SQLState, + int []updateCounts, Throwable cause) { + this(reason, SQLState, 0, updateCounts, cause); + } - /** - * Constructs a <code>BatchUpdateException</code> object initialized with - * a given <code>reason</code>, <code>SQLState</code>, <code>vendorCode</code> - * <code>cause</code> and <code>updateCounts</code>. - * - * @param reason a description of the error - * @param SQLState an XOPEN or SQL:2003 code identifying the exception - * @param vendorCode an exception code used by a particular - * database vendor - * @param updateCounts an array of <code>int</code>, with each element - *indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or + /** + * Constructs a <code>BatchUpdateException</code> object initialized with + * a given <code>reason</code>, <code>SQLState</code>, <code>vendorCode</code> + * <code>cause</code> and <code>updateCounts</code>. + * + * @param reason a description of the error + * @param SQLState an XOPEN or SQL:2003 code identifying the exception + * @param vendorCode an exception code used by a particular + * database vendor + * @param updateCounts an array of <code>int</code>, with each element + *indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or * <code>Statement.EXECUTE_FAILED</code> for each SQL command in * the batch for JDBC drivers that continue processing * after a command failure; an update count or * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch * prior to the failure for JDBC drivers that stop processing after a command * failure - * @param cause the underlying reason for this <code>SQLException</code> (which is saved for later retrieval by the <code>getCause()</code> method); - * may be null indicating - * the cause is non-existent or unknown. - * @since 1.6 - */ - public BatchUpdateException(String reason, String SQLState, int vendorCode, + * <p> + * <strong>Note:</strong> There is no validation of {@code updateCounts} for + * overflow and because of this it is recommended that you use the constructor + * {@code BatchUpdateException(String reason, String SQLState, + * int vendorCode, long []updateCounts,Throwable cause) }. + * </p> + * @param cause the underlying reason for this <code>SQLException</code> (which is saved for later retrieval by the <code>getCause()</code> method); + * may be null indicating + * the cause is non-existent or unknown. + * @since 1.6 + * @see #BatchUpdateException(java.lang.String, java.lang.String, int, long[], + * java.lang.Throwable) + */ + public BatchUpdateException(String reason, String SQLState, int vendorCode, int []updateCounts,Throwable cause) { super(reason, SQLState, vendorCode, cause); this.updateCounts = (updateCounts == null) ? null : Arrays.copyOf(updateCounts, updateCounts.length); - } + this.longUpdateCounts = (updateCounts == null) ? null : copyUpdateCount(updateCounts); + } /** * Retrieves the update count for each update statement in the batch @@ -324,17 +397,168 @@ public class BatchUpdateException extends SQLException { * failed to execute successfully * </OL> * @since 1.3 + * @see #getLargeUpdateCounts() */ public int[] getUpdateCounts() { return (updateCounts == null) ? null : Arrays.copyOf(updateCounts, updateCounts.length); } /** + * Constructs a <code>BatchUpdateException</code> object initialized with + * a given <code>reason</code>, <code>SQLState</code>, <code>vendorCode</code> + * <code>cause</code> and <code>updateCounts</code>. + * <p> + * This constructor should be used when the returned update count may exceed + * {@link Integer.MAX_VALUE}. + * <p> + * @param reason a description of the error + * @param SQLState an XOPEN or SQL:2003 code identifying the exception + * @param vendorCode an exception code used by a particular + * database vendor + * @param updateCounts an array of <code>long</code>, with each element + *indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or + * <code>Statement.EXECUTE_FAILED</code> for each SQL command in + * the batch for JDBC drivers that continue processing + * after a command failure; an update count or + * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch + * prior to the failure for JDBC drivers that stop processing after a command + * failure + * @param cause the underlying reason for this <code>SQLException</code> + * (which is saved for later retrieval by the <code>getCause()</code> method); + * may be null indicating the cause is non-existent or unknown. + * @since 1.8 + */ + public BatchUpdateException(String reason, String SQLState, int vendorCode, + long []updateCounts,Throwable cause) { + super(reason, SQLState, vendorCode, cause); + this.longUpdateCounts = (updateCounts == null) ? null : Arrays.copyOf(updateCounts, updateCounts.length); + this.updateCounts = (longUpdateCounts == null) ? null : copyUpdateCount(longUpdateCounts); + } + + /** + * Retrieves the update count for each update statement in the batch + * update that executed successfully before this exception occurred. + * A driver that implements batch updates may or may not continue to + * process the remaining commands in a batch when one of the commands + * fails to execute properly. If the driver continues processing commands, + * the array returned by this method will have as many elements as + * there are commands in the batch; otherwise, it will contain an + * update count for each command that executed successfully before + * the <code>BatchUpdateException</code> was thrown. + * <p> + * This method should be used when {@code Statement.executeLargeBatch} is + * invoked and the returned update count may exceed {@link Integer.MAX_VALUE}. + * <p> + * @return an array of <code>long</code> containing the update counts + * for the updates that were executed successfully before this error + * occurred. Or, if the driver continues to process commands after an + * error, one of the following for every command in the batch: + * <OL> + * <LI>an update count + * <LI><code>Statement.SUCCESS_NO_INFO</code> to indicate that the command + * executed successfully but the number of rows affected is unknown + * <LI><code>Statement.EXECUTE_FAILED</code> to indicate that the command + * failed to execute successfully + * </OL> + * @since 1.8 + */ + public long[] getLargeUpdateCounts() { + return (longUpdateCounts == null) ? null : + Arrays.copyOf(longUpdateCounts, longUpdateCounts.length); + } + + /** * The array that describes the outcome of a batch execution. * @serial * @since 1.2 */ - private final int[] updateCounts; + private int[] updateCounts; + + /* + * Starting with Java SE 8, JDBC has added support for returning an update + * count > Integer.MAX_VALUE. Because of this the following changes were made + * to BatchUpdateException: + * <ul> + * <li>Add field longUpdateCounts</li> + * <li>Add Constructorr which takes long[] for update counts</li> + * <li>Add getLargeUpdateCounts method</li> + * </ul> + * When any of the constructors are called, the int[] and long[] updateCount + * fields are populated by copying the one array to each other. + * + * As the JDBC driver passes in the updateCounts, there has always been the + * possiblity for overflow and BatchUpdateException does not need to account + * for that, it simply copies the arrays. + * + * JDBC drivers should always use the constructor that specifies long[] and + * JDBC application developers should call getLargeUpdateCounts. + */ + + /** + * The array that describes the outcome of a batch execution. + * @serial + * @since 1.8 + */ + private long[] longUpdateCounts; private static final long serialVersionUID = 5977529877145521757L; + + /* + * Utility method to copy int[] updateCount to long[] updateCount + */ + private static long[] copyUpdateCount(int[] uc) { + long[] copy = new long[uc.length]; + for(int i= 0; i< uc.length; i++) { + copy[i] = uc[i]; + } + return copy; + } + + /* + * Utility method to copy long[] updateCount to int[] updateCount. + * No checks for overflow will be done as it is expected a user will call + * getLargeUpdateCounts. + */ + private static int[] copyUpdateCount(long[] uc) { + int[] copy = new int[uc.length]; + for(int i= 0; i< uc.length; i++) { + copy[i] = (int) uc[i]; + } + return copy; + } + /** + * readObject is called to restore the state of the + * {@code BatchUpdateException} from a stream. + */ + private void readObject(ObjectInputStream s) + throws IOException, ClassNotFoundException { + + ObjectInputStream.GetField fields = s.readFields(); + int[] tmp = (int[])fields.get("updateCounts", null); + long[] tmp2 = (long[])fields.get("longUpdateCounts", null); + if(tmp != null && tmp2 != null && tmp.length != tmp2.length) + throw new InvalidObjectException("update counts are not the expected size"); + if (tmp != null) + updateCounts = tmp.clone(); + if (tmp2 != null) + longUpdateCounts = tmp2.clone(); + if(updateCounts == null && longUpdateCounts != null) + updateCounts = copyUpdateCount(longUpdateCounts); + if(longUpdateCounts == null && updateCounts != null) + longUpdateCounts = copyUpdateCount(updateCounts); + + } + + /** + * writeObject is called to save the state of the {@code BatchUpdateException} + * to a stream. + */ + private void writeObject(ObjectOutputStream s) + throws IOException, ClassNotFoundException { + + ObjectOutputStream.PutField fields = s.putFields(); + fields.put("updateCounts", updateCounts); + fields.put("longUpdateCounts", longUpdateCounts); + s.writeFields(); + } } diff --git a/src/share/classes/java/sql/CallableStatement.java b/src/share/classes/java/sql/CallableStatement.java index a86caa69eb..1200f771da 100644 --- a/src/share/classes/java/sql/CallableStatement.java +++ b/src/share/classes/java/sql/CallableStatement.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2012, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2013, 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 @@ -1079,9 +1079,7 @@ public interface CallableStatement extends PreparedStatement { int length) throws SQLException; /** - * Sets the value of the designated parameter with the given object. The second - * argument must be an object type; for integral values, the - * <code>java.lang</code> equivalent objects should be used. + * Sets the value of the designated parameter with the given object. * * <p>The given Java object will be converted to the given targetSqlType * before being sent to the database. @@ -1109,13 +1107,8 @@ public interface CallableStatement extends PreparedStatement { * @exception SQLException if parameterName does not correspond to a named * parameter; if a database access error occurs or * this method is called on a closed <code>CallableStatement</code> - * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is - * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>, - * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>, - * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>, - * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code> - * or <code>STRUCT</code> data type and the JDBC driver does not support - * this data type + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type * @see Types * @see #getObject * @since 1.4 @@ -1125,8 +1118,10 @@ public interface CallableStatement extends PreparedStatement { /** * Sets the value of the designated parameter with the given object. - * This method is like the method <code>setObject</code> - * above, except that it assumes a scale of zero. + * + * This method is similar to {@link #setObject(String parameterName, + * Object x, int targetSqlType, int scaleOrLength)}, + * except that it assumes a scale of zero. * * @param parameterName the name of the parameter * @param x the object containing the input parameter value @@ -1135,13 +1130,8 @@ public interface CallableStatement extends PreparedStatement { * @exception SQLException if parameterName does not correspond to a named * parameter; if a database access error occurs or * this method is called on a closed <code>CallableStatement</code> - * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is - * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>, - * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>, - * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>, - * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code> - * or <code>STRUCT</code> data type and the JDBC driver does not support - * this data type + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type * @see #getObject * @since 1.4 */ @@ -1150,8 +1140,6 @@ public interface CallableStatement extends PreparedStatement { /** * Sets the value of the designated parameter with the given object. - * The second parameter must be of type <code>Object</code>; therefore, the - * <code>java.lang</code> equivalent objects should be used for built-in types. * * <p>The JDBC specification specifies a standard mapping from * Java <code>Object</code> types to SQL types. The given argument @@ -2497,4 +2485,338 @@ public interface CallableStatement extends PreparedStatement { */ public <T> T getObject(String parameterName, Class<T> type) throws SQLException; + //------------------------- JDBC 4.2 ----------------------------------- + + /** + * <p>Sets the value of the designated parameter with the given object. + * + * If the second argument is an {@code InputStream} then the stream + * must contain the number of bytes specified by scaleOrLength. + * If the second argument is a {@code Reader} then the reader must + * contain the number of characters specified + * by scaleOrLength. If these conditions are not true the driver + * will generate a + * {@code SQLException} when the prepared statement is executed. + * + * <p>The given Java object will be converted to the given targetSqlType + * before being sent to the database. + * + * If the object has a custom mapping (is of a class implementing the + * interface {@code SQLData}), + * the JDBC driver should call the method {@code SQLData.writeSQL} to + * write it to the SQL data stream. + * If, on the other hand, the object is of a class implementing + * {@code Ref}, {@code Blob}, {@code Clob}, {@code NClob}, + * {@code Struct}, {@code java.net.URL}, + * or {@code Array}, the driver should pass it to the database as a + * value of the corresponding SQL type. + * + * <p>Note that this method may be used to pass database-specific + * abstract data types. + *<P> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param parameterName the name of the parameter + * @param x the object containing the input parameter value + * @param targetSqlType the SQL type to be + * sent to the database. The scale argument may further qualify this type. + * @param scaleOrLength for {@code java.sql.JDBCType.DECIMAL} + * or {@code java.sql.JDBCType.NUMERIC types}, + * this is the number of digits after the decimal point. For + * Java Object types {@code InputStream} and {@code Reader}, + * this is the length + * of the data in the stream or reader. For all other types, + * this value will be ignored. + * @exception SQLException if parameterName does not correspond to a named + * parameter; if a database access error occurs + * or this method is called on a closed {@code CallableStatement} or + * if the Java Object specified by x is an InputStream + * or Reader object and the value of the scale parameter is less + * than zero + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type + * @see JDBCType + * @see SQLType + * + * @since 1.8 + */ + default void setObject(String parameterName, Object x, SQLType targetSqlType, + int scaleOrLength) throws SQLException { + throw new SQLFeatureNotSupportedException("setObject not implemented"); + } + /** + * Sets the value of the designated parameter with the given object. + * + * This method is similar to {@link #setObject(String parameterName, + * Object x, SQLType targetSqlType, int scaleOrLength)}, + * except that it assumes a scale of zero. + *<P> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param parameterName the name of the parameter + * @param x the object containing the input parameter value + * @param targetSqlType the SQL type to be sent to the database + * @exception SQLException if parameterName does not correspond to a named + * parameter; if a database access error occurs + * or this method is called on a closed {@code CallableStatement} + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type + * @see JDBCType + * @see SQLType + * @since 1.8 + */ + default void setObject(String parameterName, Object x, SQLType targetSqlType) + throws SQLException { + throw new SQLFeatureNotSupportedException("setObject not implemented"); + } + + /** + * Registers the OUT parameter in ordinal position + * {@code parameterIndex} to the JDBC type + * {@code sqlType}. All OUT parameters must be registered + * before a stored procedure is executed. + * <p> + * The JDBC type specified by {@code sqlType} for an OUT + * parameter determines the Java type that must be used + * in the {@code get} method to read the value of that parameter. + * <p> + * If the JDBC type expected to be returned to this output parameter + * is specific to this particular database, {@code sqlType} + * may be {@code JDBCType.OTHER} or a {@code SQLType} that is supported by + * the JDBC driver. The method + * {@link #getObject} retrieves the value. + *<P> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param parameterIndex the first parameter is 1, the second is 2, + * and so on + * @param sqlType the JDBC type code defined by {@code SQLType} to use to + * register the OUT Parameter. + * If the parameter is of JDBC type {@code JDBCType.NUMERIC} + * or {@code JDBCType.DECIMAL}, the version of + * {@code registerOutParameter} that accepts a scale value + * should be used. + * + * @exception SQLException if the parameterIndex is not valid; + * if a database access error occurs or + * this method is called on a closed {@code CallableStatement} + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type + * @see JDBCType + * @see SQLType + * @since 1.8 + */ + default void registerOutParameter(int parameterIndex, SQLType sqlType) + throws SQLException { + throw new SQLFeatureNotSupportedException("registerOutParameter not implemented"); + } + + /** + * Registers the parameter in ordinal position + * {@code parameterIndex} to be of JDBC type + * {@code sqlType}. All OUT parameters must be registered + * before a stored procedure is executed. + * <p> + * The JDBC type specified by {@code sqlType} for an OUT + * parameter determines the Java type that must be used + * in the {@code get} method to read the value of that parameter. + * <p> + * This version of {@code registrOutParameter} should be + * used when the parameter is of JDBC type {@code JDBCType.NUMERIC} + * or {@code JDBCType.DECIMAL}. + *<P> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param parameterIndex the first parameter is 1, the second is 2, + * and so on + * @param sqlType the JDBC type code defined by {@code SQLType} to use to + * register the OUT Parameter. + * @param scale the desired number of digits to the right of the + * decimal point. It must be greater than or equal to zero. + * @exception SQLException if the parameterIndex is not valid; + * if a database access error occurs or + * this method is called on a closed {@code CallableStatement} + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type + * @see JDBCType + * @see SQLType + * @since 1.8 + */ + default void registerOutParameter(int parameterIndex, SQLType sqlType, + int scale) throws SQLException { + throw new SQLFeatureNotSupportedException("registerOutParameter not implemented"); + } + /** + * Registers the designated output parameter. + * This version of + * the method {@code registrOutParameter} + * should be used for a user-defined or {@code REF} output parameter. + * Examples + * of user-defined types include: {@code STRUCT}, {@code DISTINCT}, + * {@code JAVA_OBJECT}, and named array types. + *<p> + * All OUT parameters must be registered + * before a stored procedure is executed. + * <p> For a user-defined parameter, the fully-qualified SQL + * type name of the parameter should also be given, while a {@code REF} + * parameter requires that the fully-qualified type name of the + * referenced type be given. A JDBC driver that does not need the + * type code and type name information may ignore it. To be portable, + * however, applications should always provide these values for + * user-defined and {@code REF} parameters. + * + * Although it is intended for user-defined and {@code REF} parameters, + * this method may be used to register a parameter of any JDBC type. + * If the parameter does not have a user-defined or {@code REF} type, the + * <i>typeName</i> parameter is ignored. + * + * <P><B>Note:</B> When reading the value of an out parameter, you + * must use the getter method whose Java type corresponds to the + * parameter's registered SQL type. + *<P> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param parameterIndex the first parameter is 1, the second is 2,... + * @param sqlType the JDBC type code defined by {@code SQLType} to use to + * register the OUT Parameter. + * @param typeName the fully-qualified name of an SQL structured type + * @exception SQLException if the parameterIndex is not valid; + * if a database access error occurs or + * this method is called on a closed {@code CallableStatement} + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type + * @see JDBCType + * @see SQLType + * @since 1.8 + */ + default void registerOutParameter (int parameterIndex, SQLType sqlType, + String typeName) throws SQLException { + throw new SQLFeatureNotSupportedException("registerOutParameter not implemented"); + } + + /** + * Registers the OUT parameter named + * <code>parameterName</code> to the JDBC type + * {@code sqlType}. All OUT parameters must be registered + * before a stored procedure is executed. + * <p> + * The JDBC type specified by {@code sqlType} for an OUT + * parameter determines the Java type that must be used + * in the {@code get} method to read the value of that parameter. + * <p> + * If the JDBC type expected to be returned to this output parameter + * is specific to this particular database, {@code sqlType} + * should be {@code JDBCType.OTHER} or a {@code SQLType} that is supported + * by the JDBC driver.. The method + * {@link #getObject} retrieves the value. + *<P> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param parameterName the name of the parameter + * @param sqlType the JDBC type code defined by {@code SQLType} to use to + * register the OUT Parameter. + * If the parameter is of JDBC type {@code JDBCType.NUMERIC} + * or {@code JDBCType.DECIMAL}, the version of + * {@code registrOutParameter} that accepts a scale value + * should be used. + * @exception SQLException if parameterName does not correspond to a named + * parameter; if a database access error occurs or + * this method is called on a closed {@code CallableStatement} + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type + * or if the JDBC driver does not support + * this method + * @since 1.8 + * @see JDBCType + * @see SQLType + */ + default void registerOutParameter(String parameterName, SQLType sqlType) + throws SQLException { + throw new SQLFeatureNotSupportedException("registerOutParameter not implemented"); + } + + /** + * Registers the parameter named + * <code>parameterName</code> to be of JDBC type + * {@code sqlType}. All OUT parameters must be registered + * before a stored procedure is executed. + * <p> + * The JDBC type specified by {@code sqlType} for an OUT + * parameter determines the Java type that must be used + * in the {@code get} method to read the value of that parameter. + * <p> + * This version of {@code registrOutParameter} should be + * used when the parameter is of JDBC type {@code JDBCType.NUMERIC} + * or {@code JDBCType.DECIMAL}. + *<P> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param parameterName the name of the parameter + * @param sqlType the JDBC type code defined by {@code SQLType} to use to + * register the OUT Parameter. + * @param scale the desired number of digits to the right of the + * decimal point. It must be greater than or equal to zero. + * @exception SQLException if parameterName does not correspond to a named + * parameter; if a database access error occurs or + * this method is called on a closed {@code CallableStatement} + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type + * or if the JDBC driver does not support + * this method + * @since 1.8 + * @see JDBCType + * @see SQLType + */ + default void registerOutParameter(String parameterName, SQLType sqlType, + int scale) throws SQLException { + throw new SQLFeatureNotSupportedException("registerOutParameter not implemented"); + } + + /** + * Registers the designated output parameter. This version of + * the method {@code registrOutParameter} + * should be used for a user-named or REF output parameter. Examples + * of user-named types include: STRUCT, DISTINCT, JAVA_OBJECT, and + * named array types. + *<p> + * All OUT parameters must be registered + * before a stored procedure is executed. + * </p> + * For a user-named parameter the fully-qualified SQL + * type name of the parameter should also be given, while a REF + * parameter requires that the fully-qualified type name of the + * referenced type be given. A JDBC driver that does not need the + * type code and type name information may ignore it. To be portable, + * however, applications should always provide these values for + * user-named and REF parameters. + * + * Although it is intended for user-named and REF parameters, + * this method may be used to register a parameter of any JDBC type. + * If the parameter does not have a user-named or REF type, the + * typeName parameter is ignored. + * + * <P><B>Note:</B> When reading the value of an out parameter, you + * must use the {@code getXXX} method whose Java type XXX corresponds to the + * parameter's registered SQL type. + *<P> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param parameterName the name of the parameter + * @param sqlType the JDBC type code defined by {@code SQLType} to use to + * register the OUT Parameter. + * @param typeName the fully-qualified name of an SQL structured type + * @exception SQLException if parameterName does not correspond to a named + * parameter; if a database access error occurs or + * this method is called on a closed {@code CallableStatement} + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type + * or if the JDBC driver does not support this method + * @see JDBCType + * @see SQLType + * @since 1.8 + */ + default void registerOutParameter (String parameterName, SQLType sqlType, + String typeName) throws SQLException { + throw new SQLFeatureNotSupportedException("registerOutParameter not implemented"); + } } diff --git a/src/share/classes/java/sql/DatabaseMetaData.java b/src/share/classes/java/sql/DatabaseMetaData.java index 1ad5ea1735..7330b8eac0 100644 --- a/src/share/classes/java/sql/DatabaseMetaData.java +++ b/src/share/classes/java/sql/DatabaseMetaData.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2010, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2013, 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 @@ -2522,10 +2522,10 @@ public interface DatabaseMetaData extends Wrapper { * <LI><B>ASC_OR_DESC</B> String => column sort sequence, "A" => ascending, * "D" => descending, may be <code>null</code> if sort sequence is not supported; * <code>null</code> when TYPE is tableIndexStatistic - * <LI><B>CARDINALITY</B> int => When TYPE is tableIndexStatistic, then + * <LI><B>CARDINALITY</B> long => When TYPE is tableIndexStatistic, then * this is the number of rows in the table; otherwise, it is the * number of unique values in the index. - * <LI><B>PAGES</B> int => When TYPE is tableIndexStatisic then + * <LI><B>PAGES</B> long => When TYPE is tableIndexStatisic then * this is the number of pages used for the table, otherwise it * is the number of pages used for the current index. * <LI><B>FILTER_CONDITION</B> String => Filter condition, if any. @@ -2759,7 +2759,7 @@ public interface DatabaseMetaData extends Wrapper { /** * Retrieves whether this database supports batch updates. * - * @return <code>true</code> if this database supports batch upcates; + * @return <code>true</code> if this database supports batch updates; * <code>false</code> otherwise * @exception SQLException if a database access error occurs * @since 1.2 @@ -3652,4 +3652,37 @@ public interface DatabaseMetaData extends Wrapper { * @since 1.7 */ boolean generatedKeyAlwaysReturned() throws SQLException; + + //--------------------------JDBC 4.2 ----------------------------- + + /** + * + * Retrieves the maximum number of bytes this database allows for + * the logical size for a {@code LOB}. + *<p> + * The default implementation will return {@code 0} + * + * @return the maximum number of bytes allowed; a result of zero + * means that there is no limit or the limit is not known + * @exception SQLException if a database access error occurs + * @since 1.8 + */ + default long getMaxLogicalLobSize() throws SQLException { + return 0; + } + + /** + * Retrieves whether this database supports REF CURSOR. + *<p> + * The default implementation will return {@code false} + * + * @return {@code true} if this database supports REF CURSOR; + * {@code false} otherwise + * @exception SQLException if a database access error occurs + * @since 1.8 + */ + default boolean supportsRefCursors() throws SQLException{ + return false; + } + } diff --git a/src/share/classes/java/sql/Driver.java b/src/share/classes/java/sql/Driver.java index 4abc6b3c81..1682b75c91 100644 --- a/src/share/classes/java/sql/Driver.java +++ b/src/share/classes/java/sql/Driver.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2010, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2013, 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 @@ -65,10 +65,15 @@ public interface Driver { * driver to connect to the given URL but has trouble connecting to * the database. * - * <P>The <code>java.util.Properties</code> argument can be used to pass + * <P>The {@code Properties} argument can be used to pass * arbitrary string tag/value pairs as connection arguments. * Normally at least "user" and "password" properties should be - * included in the <code>Properties</code> object. + * included in the {@code Properties} object. + * <p> + * <B>Note:</B> If a property is specified as part of the {@code url} and + * is also specified in the {@code Properties} object, it is + * implementation-defined as to which value will take precedence. For + * maximum portability, an application should only specify a property once. * * @param url the URL of the database to which to connect * @param info a list of arbitrary string tag/value pairs as @@ -76,7 +81,8 @@ public interface Driver { * "password" property should be included. * @return a <code>Connection</code> object that represents a * connection to the URL - * @exception SQLException if a database access error occurs + * @exception SQLException if a database access error occurs or the url is + * {@code null} */ Connection connect(String url, java.util.Properties info) throws SQLException; @@ -84,13 +90,14 @@ public interface Driver { /** * Retrieves whether the driver thinks that it can open a connection * to the given URL. Typically drivers will return <code>true</code> if they - * understand the subprotocol specified in the URL and <code>false</code> if + * understand the sub-protocol specified in the URL and <code>false</code> if * they do not. * * @param url the URL of the database * @return <code>true</code> if this driver understands the given URL; * <code>false</code> otherwise - * @exception SQLException if a database access error occurs + * @exception SQLException if a database access error occurs or the url is + * {@code null} */ boolean acceptsURL(String url) throws SQLException; diff --git a/src/share/classes/java/sql/DriverManager.java b/src/share/classes/java/sql/DriverManager.java index 4021fa2443..b0ca1cd4de 100644 --- a/src/share/classes/java/sql/DriverManager.java +++ b/src/share/classes/java/sql/DriverManager.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2012, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2013, 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 @@ -172,6 +172,12 @@ public class DriverManager { * Attempts to establish a connection to the given database URL. * The <code>DriverManager</code> attempts to select an appropriate driver from * the set of registered JDBC drivers. + *<p> + * <B>Note:</B> If a property is specified as part of the {@code url} and + * is also specified in the {@code Properties} object, it is + * implementation-defined as to which value will take precedence. + * For maximum portability, an application should only specify a + * property once. * * @param url a database url of the form * <code> jdbc:<em>subprotocol</em>:<em>subname</em></code> @@ -179,7 +185,12 @@ public class DriverManager { * connection arguments; normally at least a "user" and * "password" property should be included * @return a Connection to the URL - * @exception SQLException if a database access error occurs + * @exception SQLException if a database access error occurs or the url is + * {@code null} + * @throws SQLTimeoutException when the driver has determined that the + * timeout value specified by the {@code setLoginTimeout} method + * has been exceeded and has at least tried to cancel the + * current database connection attempt */ public static Connection getConnection(String url, java.util.Properties info) throws SQLException { @@ -195,6 +206,12 @@ public class DriverManager { * Attempts to establish a connection to the given database URL. * The <code>DriverManager</code> attempts to select an appropriate driver from * the set of registered JDBC drivers. + *<p> + * <B>Note:</B> If a property is specified as part of the {@code url} and + * is also specified in the {@code Properties} object, it is + * implementation-defined as to which value will take precedence. + * For maximum portability, an application should only specify a + * property once. * * @param url a database url of the form * <code>jdbc:<em>subprotocol</em>:<em>subname</em></code> @@ -202,7 +219,12 @@ public class DriverManager { * made * @param password the user's password * @return a connection to the URL - * @exception SQLException if a database access error occurs + * @exception SQLException if a database access error occurs or the url is + * {@code null} + * @throws SQLTimeoutException when the driver has determined that the + * timeout value specified by the {@code setLoginTimeout} method + * has been exceeded and has at least tried to cancel the + * current database connection attempt */ public static Connection getConnection(String url, String user, String password) throws SQLException { @@ -230,7 +252,12 @@ public class DriverManager { * @param url a database url of the form * <code> jdbc:<em>subprotocol</em>:<em>subname</em></code> * @return a connection to the URL - * @exception SQLException if a database access error occurs + * @exception SQLException if a database access error occurs or the url is + * {@code null} + * @throws SQLTimeoutException when the driver has determined that the + * timeout value specified by the {@code setLoginTimeout} method + * has been exceeded and has at least tried to cancel the + * current database connection attempt */ public static Connection getConnection(String url) throws SQLException { @@ -380,7 +407,8 @@ public class DriverManager { /** * Sets the maximum time in seconds that a driver will wait - * while attempting to connect to a database. + * while attempting to connect to a database once the driver has + * been identified. * * @param seconds the login time limit in seconds; zero means there is no limit * @see #getLoginTimeout diff --git a/src/share/classes/java/sql/JDBCType.java b/src/share/classes/java/sql/JDBCType.java new file mode 100644 index 0000000000..f145305960 --- /dev/null +++ b/src/share/classes/java/sql/JDBCType.java @@ -0,0 +1,251 @@ +/* + * Copyright (c) 2013, 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 + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ +package java.sql; + +/** + * <P>Defines the constants that are used to identify generic + * SQL types, called JDBC types. + * <p> + * @see SQLType + * @since 1.8 + */ +public enum JDBCType implements SQLType { + + /** + * Identifies the generic SQL type {@code BIT}. + */ + BIT(Types.BIT), + /** + * Identifies the generic SQL type {@code TINYINT}. + */ + TINYINT(Types.TINYINT), + /** + * Identifies the generic SQL type {@code SMALLINT}. + */ + SMALLINT(Types.SMALLINT), + /** + * Identifies the generic SQL type {@code INTEGER}. + */ + INTEGER(Types.INTEGER), + /** + * Identifies the generic SQL type {@code BIGINT}. + */ + BIGINT(Types.BIGINT), + /** + * Identifies the generic SQL type {@code FLOAT}. + */ + FLOAT(Types.FLOAT), + /** + * Identifies the generic SQL type {@code REAL}. + */ + REAL(Types.REAL), + /** + * Identifies the generic SQL type {@code DOUBLE}. + */ + DOUBLE(Types.DOUBLE), + /** + * Identifies the generic SQL type {@code NUMERIC}. + */ + NUMERIC(Types.NUMERIC), + /** + * Identifies the generic SQL type {@code DECIMAL}. + */ + DECIMAL(Types.DECIMAL), + /** + * Identifies the generic SQL type {@code CHAR}. + */ + CHAR(Types.CHAR), + /** + * Identifies the generic SQL type {@code VARCHAR}. + */ + VARCHAR(Types.VARCHAR), + /** + * Identifies the generic SQL type {@code LONGVARCHAR}. + */ + LONGVARCHAR(Types.LONGVARCHAR), + /** + * Identifies the generic SQL type {@code DATE}. + */ + DATE(Types.DATE), + /** + * Identifies the generic SQL type {@code TIME}. + */ + TIME(Types.TIME), + /** + * Identifies the generic SQL type {@code TIMESTAMP}. + */ + TIMESTAMP(Types.TIMESTAMP), + /** + * Identifies the generic SQL type {@code BINARY}. + */ + BINARY(Types.BINARY), + /** + * Identifies the generic SQL type {@code VARBINARY}. + */ + VARBINARY(Types.VARBINARY), + /** + * Identifies the generic SQL type {@code LONGVARBINARY}. + */ + LONGVARBINARY(Types.LONGVARBINARY), + /** + * Identifies the generic SQL value {@code NULL}. + */ + NULL(Types.NULL), + /** + * Indicates that the SQL type + * is database-specific and gets mapped to a Java object that can be + * accessed via the methods getObject and setObject. + */ + OTHER(Types.OTHER), + /** + * Indicates that the SQL type + * is database-specific and gets mapped to a Java object that can be + * accessed via the methods getObject and setObject. + */ + JAVA_OBJECT(Types.JAVA_OBJECT), + /** + * Identifies the generic SQL type {@code DISTINCT}. + */ + DISTINCT(Types.DISTINCT), + /** + * Identifies the generic SQL type {@code STRUCT}. + */ + STRUCT(Types.STRUCT), + /** + * Identifies the generic SQL type {@code ARRAY}. + */ + ARRAY(Types.ARRAY), + /** + * Identifies the generic SQL type {@code BLOB}. + */ + BLOB(Types.BLOB), + /** + * Identifies the generic SQL type {@code CLOB}. + */ + CLOB(Types.CLOB), + /** + * Identifies the generic SQL type {@code REF}. + */ + REF(Types.REF), + /** + * Identifies the generic SQL type {@code DATALINK}. + */ + DATALINK(Types.DATALINK), + /** + * Identifies the generic SQL type {@code BOOLEAN}. + */ + BOOLEAN(Types.BOOLEAN), + + /* JDBC 4.0 Types */ + + /** + * Identifies the SQL type {@code ROWID}. + */ + ROWID(Types.ROWID), + /** + * Identifies the generic SQL type {@code NCHAR}. + */ + NCHAR(Types.NCHAR), + /** + * Identifies the generic SQL type {@code NVARCHAR}. + */ + NVARCHAR(Types.NVARCHAR), + /** + * Identifies the generic SQL type {@code LONGNVARCHAR}. + */ + LONGNVARCHAR(Types.LONGNVARCHAR), + /** + * Identifies the generic SQL type {@code NCLOB}. + */ + NCLOB(Types.NCLOB), + /** + * Identifies the generic SQL type {@code SQLXML}. + */ + SQLXML(Types.SQLXML), + + /* JDBC 4.2 Types */ + + /** + * Identifies the generic SQL type {@code REF_CURSOR}. + */ + REF_CURSOR(Types.REF_CURSOR); + + /** + * The Integer value for the JDBCType. It maps to a value in + * {@code Types.java} + */ + private Integer type; + + /** + * Constructor to specify the data type value from {@code Types) for + * this data type. + * @param type The value from {@code Types) for this data type + */ + JDBCType(final Integer type) { + this.type = type; + } + + /** + * Returns the name of the data type. + * @return The name of the data type. + */ + public String getName() { + return name(); + } + /** + * Returns the name of the vendor that supports this data type. + * @return The name of the vendor for this data type which is + * {@literal java.sql} for JDBCType. + */ + public String getVendor() { + return "java.sql"; + } + + /** + * Returns the vendor specific type number for the data type. + * @return An Integer representing the data type. For {@code JDBCType}, + * the value will be the same value as in {@code Types} for the data type. + */ + public Integer getVendorTypeNumber() { + return type; + } + /** + * Returns the {@code JDBCType} that corresponds to the specified + * {@code Types} value + * @param type {@code Types} value + * @return The {@code JDBCType} constant + * @throws IllegalArgumentException if this enum type has no constant with + * the specified {@code Types} value + * @see Types + */ + public static JDBCType valueOf(int type) { + for( JDBCType sqlType : JDBCType.class.getEnumConstants()) { + if(type == sqlType.type) + return sqlType; + } + throw new IllegalArgumentException("Type:" + type + " is not a valid " + + "Types.java value."); + } +} diff --git a/src/share/classes/java/sql/PreparedStatement.java b/src/share/classes/java/sql/PreparedStatement.java index b7b8211b53..22b170777c 100644 --- a/src/share/classes/java/sql/PreparedStatement.java +++ b/src/share/classes/java/sql/PreparedStatement.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2012, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2013, 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 @@ -388,23 +388,20 @@ public interface PreparedStatement extends Statement { /** * Sets the value of the designated parameter with the given object. - * This method is like the method <code>setObject</code> - * above, except that it assumes a scale of zero. + * + * This method is similar to {@link #setObject(int parameterIndex, + * Object x, int targetSqlType, int scaleOrLength)}, + * except that it assumes a scale of zero. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the object containing the input parameter value * @param targetSqlType the SQL type (as defined in java.sql.Types) to be * sent to the database * @exception SQLException if parameterIndex does not correspond to a parameter - * marker in the SQL statement; if a database access error occurs or - * this method is called on a closed <code>PreparedStatement</code> - * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is - * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>, - * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>, - * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>, - * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code> - * or <code>STRUCT</code> data type and the JDBC driver does not support - * this data type + * marker in the SQL statement; if a database access error occurs or this + * method is called on a closed PreparedStatement + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type * @see Types */ void setObject(int parameterIndex, Object x, int targetSqlType) @@ -412,8 +409,6 @@ public interface PreparedStatement extends Statement { /** * <p>Sets the value of the designated parameter using the given object. - * The second parameter must be of type <code>Object</code>; therefore, the - * <code>java.lang</code> equivalent objects should be used for built-in types. * * <p>The JDBC specification specifies a standard mapping from * Java <code>Object</code> types to SQL types. The given argument @@ -914,9 +909,7 @@ public interface PreparedStatement extends Statement { void setSQLXML(int parameterIndex, SQLXML xmlObject) throws SQLException; /** - * <p>Sets the value of the designated parameter with the given object. The second - * argument must be an object type; for integral values, the - * <code>java.lang</code> equivalent objects should be used. + * <p>Sets the value of the designated parameter with the given object. * * If the second argument is an <code>InputStream</code> then the stream must contain * the number of bytes specified by scaleOrLength. If the second argument is a @@ -957,13 +950,8 @@ public interface PreparedStatement extends Statement { * if the Java Object specified by x is an InputStream * or Reader object and the value of the scale parameter is less * than zero - * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is - * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>, - * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>, - * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>, - * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code> - * or <code>STRUCT</code> data type and the JDBC driver does not support - * this data type + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type * @see Types * * @since 1.6 @@ -1220,5 +1208,114 @@ public interface PreparedStatement extends Statement { void setNClob(int parameterIndex, Reader reader) throws SQLException; + //------------------------- JDBC 4.2 ----------------------------------- + + /** + * <p>Sets the value of the designated parameter with the given object. + * + * If the second argument is an {@code InputStream} then the stream + * must contain the number of bytes specified by scaleOrLength. + * If the second argument is a {@code Reader} then the reader must + * contain the number of characters specified by scaleOrLength. If these + * conditions are not true the driver will generate a + * {@code SQLException} when the prepared statement is executed. + * + * <p>The given Java object will be converted to the given targetSqlType + * before being sent to the database. + * + * If the object has a custom mapping (is of a class implementing the + * interface {@code SQLData}), + * the JDBC driver should call the method {@code SQLData.writeSQL} to + * write it to the SQL data stream. + * If, on the other hand, the object is of a class implementing + * {@code Ref}, {@code Blob}, {@code Clob}, {@code NClob}, + * {@code Struct}, {@code java.net.URL}, + * or {@code Array}, the driver should pass it to the database as a + * value of the corresponding SQL type. + * + * <p>Note that this method may be used to pass database-specific + * abstract data types. + *<P> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param parameterIndex the first parameter is 1, the second is 2, ... + * @param x the object containing the input parameter value + * @param targetSqlType the SQL type to be sent to the database. The + * scale argument may further qualify this type. + * @param scaleOrLength for {@code java.sql.JDBCType.DECIMAL} + * or {@code java.sql.JDBCType.NUMERIC types}, + * this is the number of digits after the decimal point. For + * Java Object types {@code InputStream} and {@code Reader}, + * this is the length + * of the data in the stream or reader. For all other types, + * this value will be ignored. + * @exception SQLException if parameterIndex does not correspond to a + * parameter marker in the SQL statement; if a database access error occurs + * or this method is called on a closed {@code PreparedStatement} or + * if the Java Object specified by x is an InputStream + * or Reader object and the value of the scale parameter is less + * than zero + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type + * @see JDBCType + * @see SQLType + * @since 1.8 + */ + default void setObject(int parameterIndex, Object x, SQLType targetSqlType, + int scaleOrLength) throws SQLException { + throw new SQLFeatureNotSupportedException("setObject not implemented"); + } + + /** + * Sets the value of the designated parameter with the given object. + * + * This method is similar to {@link #setObject(int parameterIndex, + * Object x, SQLType targetSqlType, int scaleOrLength)}, + * except that it assumes a scale of zero. + *<P> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param parameterIndex the first parameter is 1, the second is 2, ... + * @param x the object containing the input parameter value + * @param targetSqlType the SQL type to be sent to the database + * @exception SQLException if parameterIndex does not correspond to a + * parameter marker in the SQL statement; if a database access error occurs + * or this method is called on a closed {@code PreparedStatement} + * @exception SQLFeatureNotSupportedException if + * the JDBC driver does not support this data type + * @see JDBCType + * @see SQLType + * @since 1.8 + */ + default void setObject(int parameterIndex, Object x, SQLType targetSqlType) + throws SQLException { + throw new SQLFeatureNotSupportedException("setObject not implemented"); + } + /** + * Executes the SQL statement in this <code>PreparedStatement</code> object, + * which must be an SQL Data Manipulation Language (DML) statement, + * such as <code>INSERT</code>, <code>UPDATE</code> or + * <code>DELETE</code>; or an SQL statement that returns nothing, + * such as a DDL statement. + * <p> + * This method should be used when the returned row count may exceed + * {@link Integer.MAX_VALUE}. + * <p> + * The default implementation will throw {@code UnsupportedOperationException} + * + * @return either (1) the row count for SQL Data Manipulation Language + * (DML) statements or (2) 0 for SQL statements that return nothing + * @exception SQLException if a database access error occurs; + * this method is called on a closed <code>PreparedStatement</code> + * or the SQL statement returns a <code>ResultSet</code> object + * @throws SQLTimeoutException when the driver has determined that the + * timeout value that was specified by the {@code setQueryTimeout} + * method has been exceeded and has at least attempted to cancel + * the currently running {@code Statement} + * @since 1.8 + */ + default long executeLargeUpdate() throws SQLException { + throw new UnsupportedOperationException("executeLargeUpdate not implemented"); + } } diff --git a/src/share/classes/java/sql/ResultSet.java b/src/share/classes/java/sql/ResultSet.java index c4beabac5b..ab54773312 100644 --- a/src/share/classes/java/sql/ResultSet.java +++ b/src/share/classes/java/sql/ResultSet.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2012, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2013, 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 @@ -1834,6 +1834,7 @@ public interface ResultSet extends Wrapper, AutoCloseable { /** * Updates the designated column with an <code>Object</code> value. + * * The updater methods are used to update column values in the * current row or the insert row. The updater methods do not * update the underlying database; instead the <code>updateRow</code> or @@ -1866,6 +1867,7 @@ public interface ResultSet extends Wrapper, AutoCloseable { /** * Updates the designated column with an <code>Object</code> value. + * * The updater methods are used to update column values in the * current row or the insert row. The updater methods do not * update the underlying database; instead the <code>updateRow</code> or @@ -2224,6 +2226,7 @@ public interface ResultSet extends Wrapper, AutoCloseable { /** * Updates the designated column with an <code>Object</code> value. + * * The updater methods are used to update column values in the * current row or the insert row. The updater methods do not * update the underlying database; instead the <code>updateRow</code> or @@ -2256,6 +2259,7 @@ public interface ResultSet extends Wrapper, AutoCloseable { /** * Updates the designated column with an <code>Object</code> value. + * * The updater methods are used to update column values in the * current row or the insert row. The updater methods do not * update the underlying database; instead the <code>updateRow</code> or @@ -4142,4 +4146,145 @@ public interface ResultSet extends Wrapper, AutoCloseable { */ public <T> T getObject(String columnLabel, Class<T> type) throws SQLException; + //------------------------- JDBC 4.2 ----------------------------------- + + /** + * Updates the designated column with an {@code Object} value. + * + * The updater methods are used to update column values in the + * current row or the insert row. The updater methods do not + * update the underlying database; instead the {@code updateRow} or + * {@code insertRow} methods are called to update the database. + *<p> + * If the second argument is an {@code InputStream} then the stream must contain + * the number of bytes specified by scaleOrLength. If the second argument is a + * {@code Reader} then the reader must contain the number of characters specified + * by scaleOrLength. If these conditions are not true the driver will generate a + * {@code SQLException} when the statement is executed. + *<p> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param columnIndex the first column is 1, the second is 2, ... + * @param x the new column value + * @param targetSqlType the SQL type to be sent to the database + * @param scaleOrLength for an object of {@code java.math.BigDecimal} , + * this is the number of digits after the decimal point. For + * Java Object types {@code InputStream} and {@code Reader}, + * this is the length + * of the data in the stream or reader. For all other types, + * this value will be ignored. + * @exception SQLException if the columnIndex is not valid; + * if a database access error occurs; + * the result set concurrency is {@code CONCUR_READ_ONLY} + * or this method is called on a closed result set + * @exception SQLFeatureNotSupportedException if the JDBC driver does not + * support this method; if the JDBC driver does not support this data type + * @see JDBCType + * @see SQLType + * @since 1.8 + */ + default void updateObject(int columnIndex, Object x, + SQLType targetSqlType, int scaleOrLength) throws SQLException { + throw new SQLFeatureNotSupportedException("updateObject not implemented"); + } + + /** + * Updates the designated column with an {@code Object} value. + * + * The updater methods are used to update column values in the + * current row or the insert row. The updater methods do not + * update the underlying database; instead the {@code updateRow} or + * {@code insertRow} methods are called to update the database. + *<p> + * If the second argument is an {@code InputStream} then the stream must + * contain number of bytes specified by scaleOrLength. If the second + * argument is a {@code Reader} then the reader must contain the number + * of characters specified by scaleOrLength. If these conditions are not + * true the driver will generate a + * {@code SQLException} when the statement is executed. + *<p> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param columnLabel the label for the column specified with the SQL AS + * clause. If the SQL AS clause was not specified, then the label is + * the name of the column + * @param targetSqlType the SQL type to be sent to the database + * @param scaleOrLength for an object of {@code java.math.BigDecimal} , + * this is the number of digits after the decimal point. For + * Java Object types {@code InputStream} and {@code Reader}, + * this is the length + * of the data in the stream or reader. For all other types, + * this value will be ignored. + * @exception SQLException if the columnLabel is not valid; + * if a database access error occurs; + * the result set concurrency is {@code CONCUR_READ_ONLY} + * or this method is called on a closed result set + * @exception SQLFeatureNotSupportedException if the JDBC driver does not + * support this method; if the JDBC driver does not support this data type + * @see JDBCType + * @see SQLType + * @since 1.8 + */ + default void updateObject(String columnLabel, Object x, + SQLType targetSqlType, int scaleOrLength) throws SQLException { + throw new SQLFeatureNotSupportedException("updateObject not implemented"); + } + + /** + * Updates the designated column with an {@code Object} value. + * + * The updater methods are used to update column values in the + * current row or the insert row. The updater methods do not + * update the underlying database; instead the {@code updateRow} or + * {@code insertRow} methods are called to update the database. + *<p> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param columnIndex the first column is 1, the second is 2, ... + * @param x the new column value + * @param targetSqlType the SQL type to be sent to the database + * @exception SQLException if the columnIndex is not valid; + * if a database access error occurs; + * the result set concurrency is {@code CONCUR_READ_ONLY} + * or this method is called on a closed result set + * @exception SQLFeatureNotSupportedException if the JDBC driver does not + * support this method; if the JDBC driver does not support this data type + * @see JDBCType + * @see SQLType + * @since 1.8 + */ + default void updateObject(int columnIndex, Object x, SQLType targetSqlType) + throws SQLException { + throw new SQLFeatureNotSupportedException("updateObject not implemented"); + } + + /** + * Updates the designated column with an {@code Object} value. + * + * The updater methods are used to update column values in the + * current row or the insert row. The updater methods do not + * update the underlying database; instead the {@code updateRow} or + * {@code insertRow} methods are called to update the database. + *<p> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param columnLabel the label for the column specified with the SQL AS + * clause. If the SQL AS clause was not specified, then the label is + * the name of the column + * @param x the new column value + * @param targetSqlType the SQL type to be sent to the database + * @exception SQLException if the columnLabel is not valid; + * if a database access error occurs; + * the result set concurrency is {@code CONCUR_READ_ONLY} + * or this method is called on a closed result set + * @exception SQLFeatureNotSupportedException if the JDBC driver does not + * support this method; if the JDBC driver does not support this data type + * @see JDBCType + * @see SQLType + * @since 1.8 + */ + default void updateObject(String columnLabel, Object x, + SQLType targetSqlType) throws SQLException { + throw new SQLFeatureNotSupportedException("updateObject not implemented"); + } } diff --git a/src/share/classes/java/sql/SQLTimeoutException.java b/src/share/classes/java/sql/SQLTimeoutException.java index 57abd3be18..a55ee05a74 100644 --- a/src/share/classes/java/sql/SQLTimeoutException.java +++ b/src/share/classes/java/sql/SQLTimeoutException.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2013, 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 @@ -26,8 +26,10 @@ package java.sql; /** - * <P>The subclass of {@link SQLException} thrown when the timeout specified by <code>Statement</code> - * has expired. + * <P>The subclass of {@link SQLException} thrown when the timeout specified by + * {@code Statement.setQueryTimeout}, {@code DriverManager.setLoginTimeout}, + * {@code DataSource.setLoginTimeout},{@code XADataSource.setLoginTimeout} + * has expired. * <P> This exception does not correspond to a standard SQLState. * * @since 1.6 diff --git a/src/share/classes/java/sql/SQLType.java b/src/share/classes/java/sql/SQLType.java new file mode 100644 index 0000000000..c0a2b6a6c5 --- /dev/null +++ b/src/share/classes/java/sql/SQLType.java @@ -0,0 +1,56 @@ +/* + * Copyright (c) 2013, 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 + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ +package java.sql; + +/** + * An object that is used to identify a generic SQL type, called a JDBC type or + * a vendor specific data type. + * + * @since 1.8 + */ +public interface SQLType { + + /** + * Returns the {@code SQLType} name that represents a SQL data type. + * + * @return The name of this {@code SQLType}. + */ + String getName(); + + /** + * Returns the name of the vendor that supports this data type. The value + * returned typically is the package name for this vendor. + * + * @return The name of the vendor for this data type + */ + String getVendor(); + + /** + * Returns the vendor specific type number for the data type. + * + * @return An Integer representing the vendor specific data type + */ + Integer getVendorTypeNumber(); +} diff --git a/src/share/classes/java/sql/Statement.java b/src/share/classes/java/sql/Statement.java index d249a2f46a..584f17c0a1 100644 --- a/src/share/classes/java/sql/Statement.java +++ b/src/share/classes/java/sql/Statement.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2011, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2013, 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 @@ -183,7 +183,15 @@ public interface Statement extends Wrapper, AutoCloseable { * Sets escape processing on or off. * If escape scanning is on (the default), the driver will do * escape substitution before sending the SQL statement to the database. - * + *<p> + * The {@code Connection} and {@code DataSource} property + * {@code escapeProcessing} may be used to change the default escape processing + * behavior. A value of true (the default) enables escape Processing for + * all {@code Statement} objects. A value of false disables escape processing + * for all {@code Statement} objects. The {@code setEscapeProcessing} + * method may be used to specify the escape processing behavior for an + * individual {@code Statement} object. + * <p> * Note: Since prepared statements have usually been parsed prior * to making this call, disabling escape processing for * <code>PreparedStatements</code> objects will have no effect. @@ -1060,4 +1068,304 @@ public interface Statement extends Wrapper, AutoCloseable { */ public boolean isCloseOnCompletion() throws SQLException; + + //--------------------------JDBC 4.2 ----------------------------- + + /** + * Retrieves the current result as an update count; if the result + * is a <code>ResultSet</code> object or there are no more results, -1 + * is returned. This method should be called only once per result. + * <p> + * This method should be used when the returned row count may exceed + * {@link Integer.MAX_VALUE}. + *<p> + * The default implementation will throw {@code UnsupportedOperationException} + * + * @return the current result as an update count; -1 if the current result + * is a <code>ResultSet</code> object or there are no more results + * @exception SQLException if a database access error occurs or + * this method is called on a closed <code>Statement</code> + * @see #execute + * @since 1.8 + */ + default long getLargeUpdateCount() throws SQLException { + throw new UnsupportedOperationException("getLargeUpdateCount not implemented"); + } + + /** + * Sets the limit for the maximum number of rows that any + * <code>ResultSet</code> object generated by this <code>Statement</code> + * object can contain to the given number. + * If the limit is exceeded, the excess + * rows are silently dropped. + * <p> + * This method should be used when the row limit may exceed + * {@link Integer.MAX_VALUE}. + *<p> + * The default implementation will throw {@code UnsupportedOperationException} + * + * @param max the new max rows limit; zero means there is no limit + * @exception SQLException if a database access error occurs, + * this method is called on a closed <code>Statement</code> + * or the condition max >= 0 is not satisfied + * @see #getMaxRows + * @since 1.8 + */ + default void setLargeMaxRows(long max) throws SQLException { + throw new UnsupportedOperationException("setLargeMaxRows not implemented"); + } + + /** + * Retrieves the maximum number of rows that a + * <code>ResultSet</code> object produced by this + * <code>Statement</code> object can contain. If this limit is exceeded, + * the excess rows are silently dropped. + * <p> + * This method should be used when the returned row limit may exceed + * {@link Integer.MAX_VALUE}. + *<p> + * The default implementation will return {@code 0} + * + * @return the current maximum number of rows for a <code>ResultSet</code> + * object produced by this <code>Statement</code> object; + * zero means there is no limit + * @exception SQLException if a database access error occurs or + * this method is called on a closed <code>Statement</code> + * @see #setMaxRows + * @since 1.8 + */ + default long getLargeMaxRows() throws SQLException { + return 0; + } + + /** + * Submits a batch of commands to the database for execution and + * if all commands execute successfully, returns an array of update counts. + * The <code>long</code> elements of the array that is returned are ordered + * to correspond to the commands in the batch, which are ordered + * according to the order in which they were added to the batch. + * The elements in the array returned by the method {@code executeLargeBatch} + * may be one of the following: + * <OL> + * <LI>A number greater than or equal to zero -- indicates that the + * command was processed successfully and is an update count giving the + * number of rows in the database that were affected by the command's + * execution + * <LI>A value of <code>SUCCESS_NO_INFO</code> -- indicates that the command was + * processed successfully but that the number of rows affected is + * unknown + * <P> + * If one of the commands in a batch update fails to execute properly, + * this method throws a <code>BatchUpdateException</code>, and a JDBC + * driver may or may not continue to process the remaining commands in + * the batch. However, the driver's behavior must be consistent with a + * particular DBMS, either always continuing to process commands or never + * continuing to process commands. If the driver continues processing + * after a failure, the array returned by the method + * <code>BatchUpdateException.getLargeUpdateCounts</code> + * will contain as many elements as there are commands in the batch, and + * at least one of the elements will be the following: + * <P> + * <LI>A value of <code>EXECUTE_FAILED</code> -- indicates that the command failed + * to execute successfully and occurs only if a driver continues to + * process commands after a command fails + * </OL> + * <p> + * This method should be used when the returned row count may exceed + * {@link Integer.MAX_VALUE}. + *<p> + * The default implementation will throw {@code UnsupportedOperationException} + * + * @return an array of update counts containing one element for each + * command in the batch. The elements of the array are ordered according + * to the order in which commands were added to the batch. + * @exception SQLException if a database access error occurs, + * this method is called on a closed <code>Statement</code> or the + * driver does not support batch statements. Throws {@link BatchUpdateException} + * (a subclass of <code>SQLException</code>) if one of the commands sent to the + * database fails to execute properly or attempts to return a result set. + * @throws SQLTimeoutException when the driver has determined that the + * timeout value that was specified by the {@code setQueryTimeout} + * method has been exceeded and has at least attempted to cancel + * the currently running {@code Statement} + * + * @see #addBatch + * @see DatabaseMetaData#supportsBatchUpdates + * @since 1.8 + */ + default long[] executeLargeBatch() throws SQLException { + throw new UnsupportedOperationException("executeLargeBatch not implemented"); + } + + /** + * Executes the given SQL statement, which may be an <code>INSERT</code>, + * <code>UPDATE</code>, or <code>DELETE</code> statement or an + * SQL statement that returns nothing, such as an SQL DDL statement. + * <p> + * This method should be used when the returned row count may exceed + * {@link Integer.MAX_VALUE}. + * <p> + * <strong>Note:</strong>This method cannot be called on a + * <code>PreparedStatement</code> or <code>CallableStatement</code>. + *<p> + * The default implementation will throw {@code UnsupportedOperationException} + * + * @param sql an SQL Data Manipulation Language (DML) statement, + * such as <code>INSERT</code>, <code>UPDATE</code> or + * <code>DELETE</code>; or an SQL statement that returns nothing, + * such as a DDL statement. + * + * @return either (1) the row count for SQL Data Manipulation Language + * (DML) statements or (2) 0 for SQL statements that return nothing + * + * @exception SQLException if a database access error occurs, + * this method is called on a closed <code>Statement</code>, the given + * SQL statement produces a <code>ResultSet</code> object, the method is called on a + * <code>PreparedStatement</code> or <code>CallableStatement</code> + * @throws SQLTimeoutException when the driver has determined that the + * timeout value that was specified by the {@code setQueryTimeout} + * method has been exceeded and has at least attempted to cancel + * the currently running {@code Statement} + * @since 1.8 + */ + default long executeLargeUpdate(String sql) throws SQLException { + throw new UnsupportedOperationException("executeLargeUpdate not implemented"); + } + + /** + * Executes the given SQL statement and signals the driver with the + * given flag about whether the + * auto-generated keys produced by this <code>Statement</code> object + * should be made available for retrieval. The driver will ignore the + * flag if the SQL statement + * is not an <code>INSERT</code> statement, or an SQL statement able to return + * auto-generated keys (the list of such statements is vendor-specific). + * <p> + * This method should be used when the returned row count may exceed + * {@link Integer.MAX_VALUE}. + * <p> + * <strong>Note:</strong>This method cannot be called on a + * <code>PreparedStatement</code> or <code>CallableStatement</code>. + *<p> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param sql an SQL Data Manipulation Language (DML) statement, + * such as <code>INSERT</code>, <code>UPDATE</code> or + * <code>DELETE</code>; or an SQL statement that returns nothing, + * such as a DDL statement. + * + * @param autoGeneratedKeys a flag indicating whether auto-generated keys + * should be made available for retrieval; + * one of the following constants: + * <code>Statement.RETURN_GENERATED_KEYS</code> + * <code>Statement.NO_GENERATED_KEYS</code> + * @return either (1) the row count for SQL Data Manipulation Language (DML) statements + * or (2) 0 for SQL statements that return nothing + * + * @exception SQLException if a database access error occurs, + * this method is called on a closed <code>Statement</code>, the given + * SQL statement returns a <code>ResultSet</code> object, + * the given constant is not one of those allowed, the method is called on a + * <code>PreparedStatement</code> or <code>CallableStatement</code> + * @exception SQLFeatureNotSupportedException if the JDBC driver does not support + * this method with a constant of Statement.RETURN_GENERATED_KEYS + * @throws SQLTimeoutException when the driver has determined that the + * timeout value that was specified by the {@code setQueryTimeout} + * method has been exceeded and has at least attempted to cancel + * the currently running {@code Statement} + * @since 1.8 + */ + default long executeLargeUpdate(String sql, int autoGeneratedKeys) + throws SQLException { + throw new SQLFeatureNotSupportedException("executeLargeUpdate not implemented"); + } + + /** + * Executes the given SQL statement and signals the driver that the + * auto-generated keys indicated in the given array should be made available + * for retrieval. This array contains the indexes of the columns in the + * target table that contain the auto-generated keys that should be made + * available. The driver will ignore the array if the SQL statement + * is not an <code>INSERT</code> statement, or an SQL statement able to return + * auto-generated keys (the list of such statements is vendor-specific). + * <p> + * This method should be used when the returned row count may exceed + * {@link Integer.MAX_VALUE}. + * <p> + * <strong>Note:</strong>This method cannot be called on a + * <code>PreparedStatement</code> or <code>CallableStatement</code>. + *<p> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param sql an SQL Data Manipulation Language (DML) statement, + * such as <code>INSERT</code>, <code>UPDATE</code> or + * <code>DELETE</code>; or an SQL statement that returns nothing, + * such as a DDL statement. + * + * @param columnIndexes an array of column indexes indicating the columns + * that should be returned from the inserted row + * @return either (1) the row count for SQL Data Manipulation Language (DML) statements + * or (2) 0 for SQL statements that return nothing + * + * @exception SQLException if a database access error occurs, + * this method is called on a closed <code>Statement</code>, the SQL + * statement returns a <code>ResultSet</code> object,the second argument + * supplied to this method is not an + * <code>int</code> array whose elements are valid column indexes, the method is called on a + * <code>PreparedStatement</code> or <code>CallableStatement</code> + * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method + * @throws SQLTimeoutException when the driver has determined that the + * timeout value that was specified by the {@code setQueryTimeout} + * method has been exceeded and has at least attempted to cancel + * the currently running {@code Statement} + * @since 1.8 + */ + default long executeLargeUpdate(String sql, int columnIndexes[]) throws SQLException { + throw new SQLFeatureNotSupportedException("executeLargeUpdate not implemented"); + } + + /** + * Executes the given SQL statement and signals the driver that the + * auto-generated keys indicated in the given array should be made available + * for retrieval. This array contains the names of the columns in the + * target table that contain the auto-generated keys that should be made + * available. The driver will ignore the array if the SQL statement + * is not an <code>INSERT</code> statement, or an SQL statement able to return + * auto-generated keys (the list of such statements is vendor-specific). + * <p> + * This method should be used when the returned row count may exceed + * {@link Integer.MAX_VALUE}. + * <p> + * <strong>Note:</strong>This method cannot be called on a + * <code>PreparedStatement</code> or <code>CallableStatement</code>. + *<p> + * The default implementation will throw {@code SQLFeatureNotSupportedException} + * + * @param sql an SQL Data Manipulation Language (DML) statement, + * such as <code>INSERT</code>, <code>UPDATE</code> or + * <code>DELETE</code>; or an SQL statement that returns nothing, + * such as a DDL statement. + * @param columnNames an array of the names of the columns that should be + * returned from the inserted row + * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>, + * or <code>DELETE</code> statements, or 0 for SQL statements + * that return nothing + * @exception SQLException if a database access error occurs, + * this method is called on a closed <code>Statement</code>, the SQL + * statement returns a <code>ResultSet</code> object, the + * second argument supplied to this method is not a <code>String</code> array + * whose elements are valid column names, the method is called on a + * <code>PreparedStatement</code> or <code>CallableStatement</code> + * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method + * @throws SQLTimeoutException when the driver has determined that the + * timeout value that was specified by the {@code setQueryTimeout} + * method has been exceeded and has at least attempted to cancel + * the currently running {@code Statement} + * @since 1.8 + */ + default long executeLargeUpdate(String sql, String columnNames[]) + throws SQLException { + throw new SQLFeatureNotSupportedException("executeLargeUpdate not implemented"); + } } + diff --git a/src/share/classes/java/sql/Types.java b/src/share/classes/java/sql/Types.java index 5b800a926f..d6fc80a323 100644 --- a/src/share/classes/java/sql/Types.java +++ b/src/share/classes/java/sql/Types.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2006, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2013, 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 @@ -309,6 +309,16 @@ public class Types { */ public static final int SQLXML = 2009; + //--------------------------JDBC 4.2 ----------------------------- + + /** + * The constant in the Java programming language, sometimes referred to + * as a type code, that identifies the generic SQL type {@code REF CURSOR}. + * + * @since 1.8 + */ + public static final int REF_CURSOR = 2012; + // Prevent instantiation private Types() {} } diff --git a/src/share/classes/java/sql/package.html b/src/share/classes/java/sql/package.html index 65d906b9a6..d6c97126a2 100644 --- a/src/share/classes/java/sql/package.html +++ b/src/share/classes/java/sql/package.html @@ -2,7 +2,7 @@ <html> <head> <!-- - Copyright (c) 1998, 2011, Oracle and/or its affiliates. All rights reserved. + Copyright (c) 1998, 2013, 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 @@ -45,8 +45,8 @@ The reader/writer facility, available through the use and update data from a spread sheet, flat file, or any other tabular data source. <P> -<h2>What the JDBC<sup><font size=-2>TM</font></sup> 4.1 API Includes</h2> -The JDBC<sup><font size=-2>TM</font></sup> 4.1 API includes both +<h2>What the JDBC<sup><font size=-2>TM</font></sup> 4.2 API Includes</h2> +The JDBC<sup><font size=-2>TM</font></sup> 4.2 API includes both the <code>java.sql</code> package, referred to as the JDBC core API, and the <code>javax.sql</code> package, referred to as the JDBC Optional Package API. This complete JDBC API @@ -58,16 +58,17 @@ of the Java<sup><font size=-2>TM</font></sup> Enterprise Edition (Java EE<sup><font size=-2>TM</font></sup>) technology. <P> <h2>Versions</h2> -The JDBC 4.1 API incorporates all of the previous JDBC API versions: +The JDBC 4.2 API incorporates all of the previous JDBC API versions: <UL> - <LI> The JDBC 4.0 API - <LI> The JDBC 3.0 API - <LI> The JDBC 2.1 core API + <LI> The JDBC 4.1 API</li> + <LI> The JDBC 4.0 API</li> + <LI> The JDBC 3.0 API</li> + <LI> The JDBC 2.1 core API</li> <LI> The JDBC 2.0 Optional Package API<br> (Note that the JDBC 2.1 core API and the JDBC 2.0 Optional Package - API together are referred to as the JDBC 2.0 API.) - <LI> The JDBC 1.2 API - <LI> The JDBC 1.0 API + API together are referred to as the JDBC 2.0 API.)</li> + <LI> The JDBC 1.2 API</li> + <LI> The JDBC 1.0 API</li> </UL> <P> Classes, interfaces, methods, fields, constructors, and exceptions @@ -76,16 +77,18 @@ into the Java platform. When these "since" tags are used in Javadoc<sup><font size=-2>TM</font></sup> comments for the JDBC API, they indicate the following: <UL> + <LI>Since 1.8 -- new in the JDBC 4.2 API and part of the Java SE platform, + version 8</li> <LI>Since 1.7 -- new in the JDBC 4.1 API and part of the Java SE platform, - version 7 + version 7</li> <LI>Since 1.6 -- new in the JDBC 4.0 API and part of the Java SE platform, - version 6 + version 6</li> <LI>Since 1.4 -- new in the JDBC 3.0 API and part of the J2SE platform, - version 1.4 + version 1.4</li> <LI>Since 1.2 -- new in the JDBC 2.0 API and part of the J2SE platform, - version 1.2 + version 1.2</li> <LI>Since 1.1 or no "since" tag -- in the original JDBC 1.0 API and part of - the JDK<sup><font size=-2>TM</font></sup>, version 1.1 + the JDK<sup><font size=-2>TM</font></sup>, version 1.1</li> </UL> <P> <b>NOTE:</b> Many of the new features are optional; consequently, there is @@ -179,6 +182,17 @@ The <code>java.sql</code> package contains API for the following: </UL> </UL> <P> + <h3><code>java.sql</code> and <code>javax.sql</code> Features Introduced in the JDBC 4.2 API</h3> +<UL> + <LI>Added <code>JDBCType</code> enum and <code>SQLType</code> interface</li> + <LI>Support for <code>REF CURSORS</code> in <code>CallableStatement</code> + </LI> + <LI><code>DatabaseMetaData</code> methods to return maximum Logical LOB size + and if Ref Cursors are supported</LI> + <LI>Added support for large update counts</LI> + +</UL> +<P> <h3><code>java.sql</code> and <code>javax.sql</code> Features Introduced in the JDBC 4.1 API</h3> <UL> <LI>Allow <code>Connection</code>, |