BatchUpdateException provides the update
* counts for all commands that were executed successfully during the
* batch update, that is, all commands that were executed before the error
* occurred. The order of elements in an array of update counts
* corresponds to the order in which commands were added to the batch.
*
* After a command in a batch update fails to execute properly
* and a BatchUpdateException is thrown, the driver
* may or may not continue to process the remaining commands in
* the batch. If the driver continues processing after a failure,
* the array returned by the method
* BatchUpdateException.getUpdateCounts will have
* an element for every command in the batch rather than only
* elements for the commands that executed successfully before
* the error. In the case where the driver continues processing
* commands, the array element for any command
* that failed is Statement.EXECUTE_FAILED.
*
* 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. *
* 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
*/
public class BatchUpdateException extends SQLException {
/**
* Constructs a BatchUpdateException object initialized with a given
* reason, SQLState, vendorCode and
* updateCounts.
* The cause is not initialized, and may subsequently be
* initialized by a call to the
* {@link Throwable#initCause(java.lang.Throwable)} method.
*
* Note: 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) }. *
* @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 ofint, with each element
* indicating the update count, Statement.SUCCESS_NO_INFO or
* Statement.EXECUTE_FAILED for each SQL command in
* the batch for JDBC drivers that continue processing
* after a command failure; an update count or
* Statement.SUCCESS_NO_INFO for each SQL command in the batch
* 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);
}
/**
* Constructs a BatchUpdateException object initialized with a given
* reason, SQLState and
* updateCounts.
* The cause is not initialized, and may subsequently be
* initialized by a call to the
* {@link Throwable#initCause(java.lang.Throwable)} method. The vendor code
* is initialized to 0.
* * Note: 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) }. *
* @param reason a description of the exception * @param SQLState an XOPEN or SQL:2003 code identifying the exception * @param updateCounts an array ofint, with each element
* indicating the update count, Statement.SUCCESS_NO_INFO or
* Statement.EXECUTE_FAILED for each SQL command in
* the batch for JDBC drivers that continue processing
* after a command failure; an update count or
* Statement.SUCCESS_NO_INFO for each SQL command in the batch
* 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) {
this(reason, SQLState, 0, updateCounts);
}
/**
* Constructs a BatchUpdateException object initialized with a given
* reason and updateCounts.
* The cause is not initialized, and may subsequently be
* initialized by a call to the
* {@link Throwable#initCause(java.lang.Throwable)} method. The
* SQLState is initialized to null
* and the vendor code is initialized to 0.
* * Note: 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) }. *
* @param reason a description of the exception * @param updateCounts an array ofint, with each element
* indicating the update count, Statement.SUCCESS_NO_INFO or
* Statement.EXECUTE_FAILED for each SQL command in
* the batch for JDBC drivers that continue processing
* after a command failure; an update count or
* Statement.SUCCESS_NO_INFO for each SQL command in the batch
* 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);
}
/**
* Constructs a BatchUpdateException object initialized with a given
* updateCounts.
* initialized by a call to the
* {@link Throwable#initCause(java.lang.Throwable)} method. The reason
* and SQLState are initialized to null and the vendor code
* is initialized to 0.
* * Note: 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) }. *
* @param updateCounts an array ofint, with each element
* indicating the update count, Statement.SUCCESS_NO_INFO or
* Statement.EXECUTE_FAILED for each SQL command in
* the batch for JDBC drivers that continue processing
* after a command failure; an update count or
* Statement.SUCCESS_NO_INFO for each SQL command in the batch
* 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);
}
/**
* Constructs a BatchUpdateException object.
* The reason, SQLState and updateCounts
* are initialized to null and the vendor code is initialized to 0.
* The cause is not initialized, and may subsequently be
* initialized by a call to the
* {@link Throwable#initCause(java.lang.Throwable)} method.
*
* @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 BatchUpdateException object initialized with
* a given cause.
* The SQLState and updateCounts
* are initialized
* to null and the vendor code is initialized to 0.
* The reason is initialized to null if
* cause==null or to cause.toString() if
* cause!=null.
* @param cause the underlying reason for this SQLException
* (which is saved for later retrieval by the getCause() 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 BatchUpdateException object initialized with a
* given cause and updateCounts.
* The SQLState is initialized
* to null and the vendor code is initialized to 0.
* The reason is initialized to null if
* cause==null or to cause.toString() if
* cause!=null.
* * Note: 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) }. *
* @param updateCounts an array ofint, with each element
* indicating the update count, Statement.SUCCESS_NO_INFO or
* Statement.EXECUTE_FAILED for each SQL command in
* the batch for JDBC drivers that continue processing
* after a command failure; an update count or
* Statement.SUCCESS_NO_INFO 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 SQLException
* (which is saved for later retrieval by the getCause() 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 BatchUpdateException object initialized with
* a given reason, cause
* and updateCounts. The SQLState is initialized
* to null and the vendor code is initialized to 0.
* * Note: 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) }. *
* @param reason a description of the exception * @param updateCounts an array ofint, with each element
*indicating the update count, Statement.SUCCESS_NO_INFO or
* Statement.EXECUTE_FAILED for each SQL command in
* the batch for JDBC drivers that continue processing
* after a command failure; an update count or
* Statement.SUCCESS_NO_INFO 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 SQLException (which is saved for later retrieval by the getCause() 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 BatchUpdateException object initialized with
* a given reason, SQLState,cause, and
* updateCounts. 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 int, with each element
* indicating the update count, Statement.SUCCESS_NO_INFO or
* Statement.EXECUTE_FAILED for each SQL command in
* the batch for JDBC drivers that continue processing
* after a command failure; an update count or
* Statement.SUCCESS_NO_INFO for each SQL command in the batch
* prior to the failure for JDBC drivers that stop processing after a command
* failure
* * Note: 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) }. *
* @param cause the underlying reason for thisSQLException
* (which is saved for later retrieval by the getCause() 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 BatchUpdateException object initialized with
* a given reason, SQLState, vendorCode
* cause and updateCounts.
*
* @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 int, with each element
*indicating the update count, Statement.SUCCESS_NO_INFO or
* Statement.EXECUTE_FAILED for each SQL command in
* the batch for JDBC drivers that continue processing
* after a command failure; an update count or
* Statement.SUCCESS_NO_INFO for each SQL command in the batch
* prior to the failure for JDBC drivers that stop processing after a command
* failure
* * Note: 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) }. *
* @param cause the underlying reason for thisSQLException (which is saved for later retrieval by the getCause() 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
* 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 BatchUpdateException was thrown.
*
* The possible return values for this method were modified for
* the Java 2 SDK, Standard Edition, version 1.3. This was done to
* accommodate the new option of continuing to process commands
* in a batch update after a BatchUpdateException object
* has been thrown.
*
* @return an array of int 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:
*
Statement.SUCCESS_NO_INFO to indicate that the command
* executed successfully but the number of rows affected is unknown
* Statement.EXECUTE_FAILED to indicate that the command
* failed to execute successfully
* BatchUpdateException object initialized with
* a given reason, SQLState, vendorCode
* cause and updateCounts.
*
* This constructor should be used when the returned update count may exceed
* {@link Integer#MAX_VALUE}.
*
* @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 long, with each element
*indicating the update count, Statement.SUCCESS_NO_INFO or
* Statement.EXECUTE_FAILED for each SQL command in
* the batch for JDBC drivers that continue processing
* after a command failure; an update count or
* Statement.SUCCESS_NO_INFO 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 SQLException
* (which is saved for later retrieval by the getCause() 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 BatchUpdateException was thrown.
*
* This method should be used when {@code Statement.executeLargeBatch} is
* invoked and the returned update count may exceed {@link Integer#MAX_VALUE}.
*
* @return an array of long 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:
*
Statement.SUCCESS_NO_INFO to indicate that the command
* executed successfully but the number of rows affected is unknown
* Statement.EXECUTE_FAILED to indicate that the command
* failed to execute successfully
*