Back to index...

	/*
	* Copyright (c) 1998, 2014, 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;

	import java.io.IOException;
	import java.io.InvalidObjectException;
	import java.io.ObjectInputStream;
	import java.io.ObjectOutputStream;
	import java.util.Arrays;

	/**
	* The subclass of {@link SQLException} thrown when an error
	* occurs during a batch update operation. In addition to the
	* information provided by {@link SQLException}, a
	* <code>BatchUpdateException</code> 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.
	* <P>
	* After a command in a batch update fails to execute properly
	* and a <code>BatchUpdateException</code> 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
	* <code>BatchUpdateException.getUpdateCounts</code> 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 <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
	*/

	public class BatchUpdateException extends SQLException {

	/**
	* Constructs a <code>BatchUpdateException</code> object initialized with a given
	* <code>reason</code>, <code>SQLState</code>, <code>vendorCode</code> and
	* <code>updateCounts</code>.
	* The <code>cause</code> is not initialized, and may subsequently be
	* 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
	* 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
	* @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 <code>BatchUpdateException</code> object initialized with a given
	* <code>reason</code>, <code>SQLState</code> and
	* <code>updateCounts</code>.
	* The <code>cause</code> 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.
	* <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
	* 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
	* @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 <code>BatchUpdateException</code> object initialized with a given
	* <code>reason</code> and <code>updateCounts</code>.
	* The <code>cause</code> is not initialized, and may subsequently be
	* initialized by a call to the
	* {@link Throwable#initCause(java.lang.Throwable)} method. 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
	* @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 <code>BatchUpdateException</code> object initialized with a given
	* <code>updateCounts</code>.
	* initialized by a call to the
	* {@link Throwable#initCause(java.lang.Throwable)} method. The <code>reason</code>
	* 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
	* 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
	* @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 <code>BatchUpdateException</code> object.
	* The <code>reason</code>, <code>SQLState</code> and <code>updateCounts</code>
	* are initialized to <code>null</code> and the vendor code is initialized to 0.
	* The <code>cause</code> 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 <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>.
	* <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
	* @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.
	* <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
	* @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
	* <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
	* <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
	* <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
	* <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
	* <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
	* 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>
	* 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 <code>BatchUpdateException</code> object
	* has been thrown.
	*
	* @return an array of <code>int</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.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}.
	*
	* @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}.
	*
	* @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 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 Constructor 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
	* possibility 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();
	}
	}

Back to index...