1. /*

  2.  * @(#)BatchUpdateException.java	1.17 00/02/02

  3.  *

  4.  * Copyright 1998-2000 Sun Microsystems, Inc. All Rights Reserved.

  5.  * 

  6.  * This software is the proprietary information of Sun Microsystems, Inc.  

  7.  * Use is subject to license terms.

  8.  * 

  9.  */

  10. 

  11. package java.sql;

  12. 

  13. /**

  14.  * An exception thrown when an error

  15.  * occurs during a batch update operation.  In addition to the

  16.  * information provided by {@link SQLException}, a 

  17.  * <code>BatchUpdateException</code> provides the update

  18.  * counts for all commands that were executed successfully during the

  19.  * batch update, that is, all commands that were executed before the error 

  20.  * occurred.  The order of elements in an array of update counts

  21.  * corresponds to the order in which commands were added to the batch.

  22.  * <P>

  23.  * After a command in a batch update fails to execute properly

  24.  * and a <code>BatchUpdateException</code> is thrown, the driver

  25.  * may or may not continue to process the remaining commands in

  26.  * the batch.  If the driver continues processing after a failure,

  27.  * the array returned by the method 

  28.  * <code>BatchUpdateException.getUpdateCounts</code> will have 

  29.  * an element for every command in the batch rather than only

  30.  * elements for the commands that executed successfully before 

  31.  * the error.  In the case where the driver continues processing

  32.  * commands, the array element for any command

  33.  * that failed is <code>-3</code>.

  34.  * <P>

  35.  * This class is new in the JDBC 2.0 API.

  36.  */

  37. 

  38. public class BatchUpdateException extends SQLException {

  39. 

  40.   /**

  41.    * Constructs a fully-specified <code>BatchUpdateException</code> object,

  42.    * initializing it with the given values.

  43.    * @param reason a description of the error 

  44.    * @param SQLState an X/OPEN code identifying the error

  45.    * @param vendorCode an exception code used by a particular

  46.    * database vendor

  47.    * @param updateCounts an array of <code>int</code>, with each element

  48.    * indicating the update count for a SQL command that executed 

  49.    * successfully before the exception was thrown

  50.    * @since 1.2

  51.    * @see <a href="package-summary.html#2.0 API">What Is in the JDBC 2.0 API</a>

  52.    */

  53.   public BatchUpdateException( String reason, String SQLState, int vendorCode, 

  54. 			       int[] updateCounts ) {

  55.     super(reason, SQLState, vendorCode);

  56.     this.updateCounts = updateCounts;

  57.   }

  58. 

  59.   /**

  60.    * Constructs a <code>BatchUpdateException</code> initialized with 

  61.    * the given arguments (<code>reason</code>,

  62.    * <code>SQLState</code>, and <code>updateCounts</code>) and 0 for the vendor

  63.    * code.

  64.    * @param reason a description of the exception 

  65.    * @param SQLState an X/OPEN code identifying the exception 

  66.    * @param updateCounts an array of <code>int</code>, with each element  

  67.    * indicating the update count for a SQL command that executed

  68.    * successfully before the exception was thrown  

  69.    * @since 1.2

  70.    * @see <a href="package-summary.html#2.0 API">What Is in the JDBC 2.0 API</a>

  71.    */

  72.   public BatchUpdateException(String reason, String SQLState, 

  73. 			      int[] updateCounts) {

  74.     super(reason, SQLState);

  75.     this.updateCounts = updateCounts;

  76.   }

  77. 

  78.   /**

  79.    * Constructs a <code>BatchUpdateException</code> initialized with

  80.    * <code>reason</code>, <code>updateCounts</code> and <code>null</code>

  81.    * for the SQLState and 0 for the vendorCode.

  82.    * @param reason a description of the exception 

  83.    * @param updateCounts an array of <code>int</code>, with each element

  84.    * indicating the update count for a SQL command that executed

  85.    * successfully before the exception was thrown

  86.    * @since 1.2

  87.    * @see <a href="package-summary.html#2.0 API">What Is in the JDBC 2.0 API</a>

  88.    */

  89.   public  BatchUpdateException(String reason, int[] updateCounts) {

  90.     super(reason);

  91.     this.updateCounts = updateCounts;

  92.   }

  93. 

  94.   /**

  95.    * Constructs a <code>BatchUpdateException</code> initialized to 

  96.    * <code>null</code> for the reason and SQLState and 0 for the

  97.    * vendor code.

  98.    * @param updateCounts an array of <code>int</code>, with each element

  99.    * indicating the update count for a SQL command that executed

  100.    * successfully before the exception was thrown

  101.    * @since 1.2

  102.    * @see <a href="package-summary.html#2.0 API">What Is in the JDBC 2.0 API</a>

  103.    */

  104.   public BatchUpdateException(int[] updateCounts) {

  105.     super();

  106.     this.updateCounts = updateCounts;

  107.   }

  108. 

  109.   /**

  110.    * Constructs a <code>BatchUpdateException</code> object 

  111.    * with the reason, SQLState, and update count initialized to

  112.    * <code>null</code> and the vendor code initialized to 0.

  113.    * @since 1.2

  114.    * @see <a href="package-summary.html#2.0 API">What Is in the JDBC 2.0 API</a>

  115.    */

  116.   public BatchUpdateException() {

  117.     super();

  118.     this.updateCounts = null;

  119.   }

  120. 

  121.   /**

  122.    * Retrieves the update count for each update statement in the batch

  123.    * update that executed successfully before this exception occurred.

  124.    * A driver that implements batch updates may or may not continue to

  125.    * process the remaining commands in a batch when one of the commands

  126.    * fails to execute properly. If the driver continues processing commands,

  127.    * the array returned by this method will have as many elements as

  128.    * there are commands in the batch; otherwise, it will contain an

  129.    * update count for each command that executed successfully before

  130.    * the <code>BatchUpdateException</code> was thrown.

  131.    *<P>

  132.    * The possible return values for this method were modified for

  133.    * the Java 2 SDK, Standard Edition, version 1.3.  This was done to

  134.    * accommodate the new option of continuing to process commands

  135.    * in a batch update after a <code>BatchUpdateException</code> object

  136.    * has been thrown.

  137.    *

  138.    * @return an array of <code>int</code> containing the update counts

  139.    * for the updates that were executed successfully before this error

  140.    * occurred.  Or, if the driver continues to process commands after an

  141.    * error, one of the following for every command in the batch:

  142.    * <OL>

  143.    * <LI>an update count

  144.    * <LI><code>-2</code> to indicate that the command

  145.    * executed successfully but the number of rows affected is unknown

  146.    * <LI><code>-3</code> to indicate that the command failed to 

  147.    * execute successfully

  148.    * </OL>

  149.    * @since 1.3

  150.    * @see <a href="package-summary.html#2.0 API">What Is in the JDBC 2.0 API</a>

  151.    */

  152.   public int[] getUpdateCounts() {

  153.     return updateCounts;

  154.   }

  155. 

  156.   /**

  157.    * The array that describes the outcome of a batch execution.

  158.    * @serial

  159.    * @since 1.2

  160.    * @see <a href="package-summary.html#2.0 API">What Is in the JDBC 2.0 API</a>

  161.    */

  162.   private int[] updateCounts;

  163. }