1 /*
2  * Copyright (c) 1998, 2011, Oracle and/or its affiliates. All rights reserved.
3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4  *
5  * This code is free software; you can redistribute it and/or modify it
6  * under the terms of the GNU General Public License version 2 only, as
7  * published by the Free Software Foundation.  Oracle designates this
8  * particular file as subject to the "Classpath" exception as provided
9  * by Oracle in the LICENSE file that accompanied this code.
10  *
11  * This code is distributed in the hope that it will be useful, but WITHOUT
12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14  * version 2 for more details (a copy is included in the LICENSE file that
15  * accompanied this code).
16  *
17  * You should have received a copy of the GNU General Public License version
18  * 2 along with this work; if not, write to the Free Software Foundation,
19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20  *
21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22  * or visit www.oracle.com if you need additional information or have any
23  * questions.
24  */
25 
26 package java.sql;
27 
28 import java.util.Arrays;
29 
30 /**
31  * The subclass of {@link SQLException} thrown when an error
32  * occurs during a batch update operation.  In addition to the
33  * information provided by {@link SQLException}, a
34  * <code>BatchUpdateException</code> provides the update
35  * counts for all commands that were executed successfully during the
36  * batch update, that is, all commands that were executed before the error
37  * occurred.  The order of elements in an array of update counts
38  * corresponds to the order in which commands were added to the batch.
39  * <P>
40  * After a command in a batch update fails to execute properly
41  * and a <code>BatchUpdateException</code> is thrown, the driver
42  * may or may not continue to process the remaining commands in
43  * the batch.  If the driver continues processing after a failure,
44  * the array returned by the method
45  * <code>BatchUpdateException.getUpdateCounts</code> will have
46  * an element for every command in the batch rather than only
47  * elements for the commands that executed successfully before
48  * the error.  In the case where the driver continues processing
49  * commands, the array element for any command
50  * that failed is <code>Statement.EXECUTE_FAILED</code>.
51  * <P>
52  * @since 1.2
53  */
54 
55 public class BatchUpdateException extends SQLException {
56 
57   /**
58    * Constructs a <code>BatchUpdateException</code> object initialized with a given
59    * <code>reason</code>, <code>SQLState</code>, <code>vendorCode</code> and
60    * <code>updateCounts</code>.
61    * The <code>cause</code> is not initialized, and may subsequently be
62    * initialized by a call to the
63    * {@link Throwable#initCause(java.lang.Throwable)} method.
64    * <p>
65    *
66    * @param reason a description of the error
67    * @param SQLState an XOPEN or SQL:2003 code identifying the exception
68    * @param vendorCode an exception code used by a particular
69    * database vendor
70    * @param updateCounts an array of <code>int</code>, with each element
71    * indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or
72    * <code>Statement.EXECUTE_FAILED</code> for each SQL command in
73    * the batch for JDBC drivers that continue processing
74    * after a command failure; an update count or
75    * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch
76    * prior to the failure for JDBC drivers that stop processing after a command
77    * failure
78    * @since 1.2
79    */
BatchUpdateException( String reason, String SQLState, int vendorCode, int[] updateCounts )80   public BatchUpdateException( String reason, String SQLState, int vendorCode,
81                                int[] updateCounts ) {
82       super(reason, SQLState, vendorCode);
83       this.updateCounts  = (updateCounts == null) ? null : Arrays.copyOf(updateCounts, updateCounts.length);
84   }
85 
86   /**
87    * Constructs a <code>BatchUpdateException</code> object initialized with a given
88    * <code>reason</code>, <code>SQLState</code> and
89    * <code>updateCounts</code>.
90    * The <code>cause</code> is not initialized, and may subsequently be
91    * initialized by a call to the
92    * {@link Throwable#initCause(java.lang.Throwable)} method. The vendor code
93    * is initialized to 0.
94    * <p>
95    *
96    * @param reason a description of the exception
97    * @param SQLState an XOPEN or SQL:2003 code identifying the exception
98    * @param updateCounts an array of <code>int</code>, with each element
99    * indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or
100    * <code>Statement.EXECUTE_FAILED</code> for each SQL command in
101    * the batch for JDBC drivers that continue processing
102    * after a command failure; an update count or
103    * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch
104    * prior to the failure for JDBC drivers that stop processing after a command
105    * failure
106    * @since 1.2
107    */
BatchUpdateException(String reason, String SQLState, int[] updateCounts)108   public BatchUpdateException(String reason, String SQLState,
109                               int[] updateCounts) {
110       this(reason, SQLState, 0, updateCounts);
111   }
112 
113   /**
114    * Constructs a <code>BatchUpdateException</code> object initialized with a given
115    * <code>reason</code> and <code>updateCounts</code>.
116    * The <code>cause</code> is not initialized, and may subsequently be
117    * initialized by a call to the
118    * {@link Throwable#initCause(java.lang.Throwable)} method.  The
119    * <code>SQLState</code> is initialized to <code>null</code>
120    * and the vender code is initialized to 0.
121    * <p>
122    *
123    *
124    * @param reason a description of the exception
125    * @param updateCounts an array of <code>int</code>, with each element
126    * indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or
127    * <code>Statement.EXECUTE_FAILED</code> for each SQL command in
128    * the batch for JDBC drivers that continue processing
129    * after a command failure; an update count or
130    * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch
131    * prior to the failure for JDBC drivers that stop processing after a command
132    * failure
133    * @since 1.2
134    */
BatchUpdateException(String reason, int[] updateCounts)135   public  BatchUpdateException(String reason, int[] updateCounts) {
136       this(reason, null, 0, updateCounts);
137   }
138 
139   /**
140    * Constructs a <code>BatchUpdateException</code> object initialized with a given
141    * <code>updateCounts</code>.
142    * initialized by a call to the
143    * {@link Throwable#initCause(java.lang.Throwable)} method. The  <code>reason</code>
144    * and <code>SQLState</code> are initialized to null and the vendor code
145    * is initialized to 0.
146    * <p>
147    *
148    * @param updateCounts an array of <code>int</code>, with each element
149    * indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or
150    * <code>Statement.EXECUTE_FAILED</code> for each SQL command in
151    * the batch for JDBC drivers that continue processing
152    * after a command failure; an update count or
153    * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch
154    * prior to the failure for JDBC drivers that stop processing after a command
155    * failure
156    * @since 1.2
157    */
BatchUpdateException(int[] updateCounts)158   public BatchUpdateException(int[] updateCounts) {
159       this(null, null, 0, updateCounts);
160   }
161 
162   /**
163    * Constructs a <code>BatchUpdateException</code> object.
164    * The <code>reason</code>, <code>SQLState</code> and <code>updateCounts</code>
165    *  are initialized to <code>null</code> and the vendor code is initialized to 0.
166    * The <code>cause</code> is not initialized, and may subsequently be
167    * initialized by a call to the
168    * {@link Throwable#initCause(java.lang.Throwable)} method.
169    * <p>
170    *
171    * @since 1.2
172    */
BatchUpdateException()173   public BatchUpdateException() {
174         this(null, null, 0, null);
175   }
176 
177     /**
178      * Constructs a <code>BatchUpdateException</code> object initialized with
179      *  a given <code>cause</code>.
180      * The <code>SQLState</code> and <code>updateCounts</code>
181      * are initialized
182      * to <code>null</code> and the vendor code is initialized to 0.
183      * The <code>reason</code>  is initialized to <code>null</code> if
184      * <code>cause==null</code> or to <code>cause.toString()</code> if
185      *  <code>cause!=null</code>.
186      * @param cause the underlying reason for this <code>SQLException</code>
187      * (which is saved for later retrieval by the <code>getCause()</code> method);
188      * may be null indicating the cause is non-existent or unknown.
189      * @since 1.6
190      */
BatchUpdateException(Throwable cause)191     public BatchUpdateException(Throwable cause) {
192         this((cause == null ? null : cause.toString()), null, 0, null, cause);
193     }
194 
195     /**
196      * Constructs a <code>BatchUpdateException</code> object initialized with a
197      * given <code>cause</code> and <code>updateCounts</code>.
198      * The <code>SQLState</code> is initialized
199      * to <code>null</code> and the vendor code is initialized to 0.
200      * The <code>reason</code>  is initialized to <code>null</code> if
201      * <code>cause==null</code> or to <code>cause.toString()</code> if
202      * <code>cause!=null</code>.
203      *
204      * @param updateCounts an array of <code>int</code>, with each element
205      * indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or
206    * <code>Statement.EXECUTE_FAILED</code> for each SQL command in
207    * the batch for JDBC drivers that continue processing
208    * after a command failure; an update count or
209    * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch
210    * prior to the failure for JDBC drivers that stop processing after a command
211    * failure
212      * @param cause the underlying reason for this <code>SQLException</code>
213      * (which is saved for later retrieval by the <code>getCause()</code> method); may be null indicating
214      * the cause is non-existent or unknown.
215      * @since 1.6
216      */
BatchUpdateException(int []updateCounts , Throwable cause)217     public BatchUpdateException(int []updateCounts , Throwable cause) {
218         this((cause == null ? null : cause.toString()), null, 0, updateCounts, cause);
219     }
220 
221     /**
222      * Constructs a <code>BatchUpdateException</code> object initialized with
223      * a given <code>reason</code>, <code>cause</code>
224      * and <code>updateCounts</code>. The <code>SQLState</code> is initialized
225      * to <code>null</code> and the vendor code is initialized to 0.
226      *
227      * @param reason a description of the exception
228      * @param updateCounts an array of <code>int</code>, with each element
229      *indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or
230    * <code>Statement.EXECUTE_FAILED</code> for each SQL command in
231    * the batch for JDBC drivers that continue processing
232    * after a command failure; an update count or
233    * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch
234    * prior to the failure for JDBC drivers that stop processing after a command
235    * failure
236      * @param cause the underlying reason for this <code>SQLException</code> (which is saved for later retrieval by the <code>getCause()</code> method);
237      * may be null indicating
238      * the cause is non-existent or unknown.
239      * @since 1.6
240      */
BatchUpdateException(String reason, int []updateCounts, Throwable cause)241     public BatchUpdateException(String reason, int []updateCounts, Throwable cause) {
242         this(reason, null, 0, updateCounts, cause);
243     }
244 
245     /**
246      * Constructs a <code>BatchUpdateException</code> object initialized with
247      * a given <code>reason</code>, <code>SQLState</code>,<code>cause</code>, and
248    * <code>updateCounts</code>. The vendor code is initialized to 0.
249      *
250      * @param reason a description of the exception
251      * @param SQLState an XOPEN or SQL:2003 code identifying the exception
252      * @param updateCounts an array of <code>int</code>, with each element
253      * indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or
254    * <code>Statement.EXECUTE_FAILED</code> for each SQL command in
255    * the batch for JDBC drivers that continue processing
256    * after a command failure; an update count or
257    * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch
258    * prior to the failure for JDBC drivers that stop processing after a command
259    * failure
260      * @param cause the underlying reason for this <code>SQLException</code> (which is saved for later retrieval by the <code>getCause()</code> method);
261      * may be null indicating
262      * the cause is non-existent or unknown.
263      * @since 1.6
264      */
BatchUpdateException(String reason, String SQLState, int []updateCounts, Throwable cause)265     public BatchUpdateException(String reason, String SQLState,
266                                 int []updateCounts, Throwable cause) {
267         this(reason, SQLState, 0, updateCounts, cause);
268     }
269 
270     /**
271      * Constructs a <code>BatchUpdateException</code> object initialized with
272      * a given <code>reason</code>, <code>SQLState</code>, <code>vendorCode</code>
273      * <code>cause</code> and <code>updateCounts</code>.
274      *
275      * @param reason a description of the error
276      * @param SQLState an XOPEN or SQL:2003 code identifying the exception
277      * @param vendorCode an exception code used by a particular
278      * database vendor
279      * @param updateCounts an array of <code>int</code>, with each element
280      *indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or
281    * <code>Statement.EXECUTE_FAILED</code> for each SQL command in
282    * the batch for JDBC drivers that continue processing
283    * after a command failure; an update count or
284    * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch
285    * prior to the failure for JDBC drivers that stop processing after a command
286    * failure
287      * @param cause the underlying reason for this <code>SQLException</code> (which is saved for later retrieval by the <code>getCause()</code> method);
288      * may be null indicating
289      * the cause is non-existent or unknown.
290      * @since 1.6
291      */
BatchUpdateException(String reason, String SQLState, int vendorCode, int []updateCounts,Throwable cause)292     public BatchUpdateException(String reason, String SQLState, int vendorCode,
293                                 int []updateCounts,Throwable cause) {
294         super(reason, SQLState, vendorCode, cause);
295         this.updateCounts  = (updateCounts == null) ? null : Arrays.copyOf(updateCounts, updateCounts.length);
296     }
297 
298   /**
299    * Retrieves the update count for each update statement in the batch
300    * update that executed successfully before this exception occurred.
301    * A driver that implements batch updates may or may not continue to
302    * process the remaining commands in a batch when one of the commands
303    * fails to execute properly. If the driver continues processing commands,
304    * the array returned by this method will have as many elements as
305    * there are commands in the batch; otherwise, it will contain an
306    * update count for each command that executed successfully before
307    * the <code>BatchUpdateException</code> was thrown.
308    *<P>
309    * The possible return values for this method were modified for
310    * the Java 2 SDK, Standard Edition, version 1.3.  This was done to
311    * accommodate the new option of continuing to process commands
312    * in a batch update after a <code>BatchUpdateException</code> object
313    * has been thrown.
314    *
315    * @return an array of <code>int</code> containing the update counts
316    * for the updates that were executed successfully before this error
317    * occurred.  Or, if the driver continues to process commands after an
318    * error, one of the following for every command in the batch:
319    * <OL>
320    * <LI>an update count
321    *  <LI><code>Statement.SUCCESS_NO_INFO</code> to indicate that the command
322    *     executed successfully but the number of rows affected is unknown
323    *  <LI><code>Statement.EXECUTE_FAILED</code> to indicate that the command
324    *     failed to execute successfully
325    * </OL>
326    * @since 1.3
327    */
getUpdateCounts()328   public int[] getUpdateCounts() {
329       return (updateCounts == null) ? null : Arrays.copyOf(updateCounts, updateCounts.length);
330   }
331 
332   /**
333    * The array that describes the outcome of a batch execution.
334    * @serial
335    * @since 1.2
336    */
337   private final int[] updateCounts;
338 
339   private static final long serialVersionUID = 5977529877145521757L;
340 }
341