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 */
80 public BatchUpdateException( String reason, String SQLState, int vendorCode,
81 int[] updateCounts ) {
82 this(reason, SQLState, vendorCode, updateCounts, null);
83 }
84
85 /**
86 * Constructs a <code>BatchUpdateException</code> object initialized with a given
87 * <code>reason</code>, <code>SQLState</code> and
88 * <code>updateCounts</code>.
89 * The <code>cause</code> is not initialized, and may subsequently be
90 * initialized by a call to the
91 * {@link Throwable#initCause(java.lang.Throwable)} method. The vendor code
92 * is intialized to 0.
93 * <p>
94 *
95 * @param reason a description of the exception
96 * @param SQLState an XOPEN or SQL:2003 code identifying the exception
97 * @param updateCounts an array of <code>int</code>, with each element
98 * indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or
99 * <code>Statement.EXECUTE_FAILED</code> for each SQL command in
100 * the batch for JDBC drivers that continue processing
101 * after a command failure; an update count or
102 * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch
103 * prior to the failure for JDBC drivers that stop processing after a command
104 * failure
105 * @since 1.2
106 */
107 public BatchUpdateException(String reason, String SQLState,
108 int[] updateCounts) {
109 this(reason, SQLState, 0, updateCounts, null);
110 }
111
112 /**
113 * Constructs a <code>BatchUpdateException</code> object initialized with a given
114 * <code>reason</code> and <code>updateCounts</code>.
115 * The <code>cause</code> is not initialized, and may subsequently be
116 * initialized by a call to the
117 * {@link Throwable#initCause(java.lang.Throwable)} method. The
118 * <code>SQLState</code> is initialized to <code>null</code>
119 * and the vender code is initialized to 0.
120 * <p>
121 *
122 *
123 * @param reason a description of the exception
124 * @param updateCounts an array of <code>int</code>, with each element
125 * indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or
126 * <code>Statement.EXECUTE_FAILED</code> for each SQL command in
127 * the batch for JDBC drivers that continue processing
128 * after a command failure; an update count or
129 * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch
130 * prior to the failure for JDBC drivers that stop processing after a command
131 * failure
132 * @since 1.2
133 */
134 public BatchUpdateException(String reason, int[] updateCounts) {
135 this(reason, null, 0, updateCounts, null);
136 }
137
138 /**
139 * Constructs a <code>BatchUpdateException</code> object initialized with a given
140 * <code>updateCounts</code>.
141 * initialized by a call to the
142 * {@link Throwable#initCause(java.lang.Throwable)} method. The <code>reason</code>
143 * and <code>SQLState</code> are initialized to null and the vendor code
144 * is initialized to 0.
145 * <p>
146 *
147 * @param updateCounts an array of <code>int</code>, with each element
148 * indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or
149 * <code>Statement.EXECUTE_FAILED</code> for each SQL command in
150 * the batch for JDBC drivers that continue processing
151 * after a command failure; an update count or
152 * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch
153 * prior to the failure for JDBC drivers that stop processing after a command
154 * failure
155 * @since 1.2
156 */
157 public BatchUpdateException(int[] updateCounts) {
158 this(null, null, 0, updateCounts, null);
159 }
160
161 /**
162 * Constructs a <code>BatchUpdateException</code> object.
163 * The <code>reason</code>, <code>SQLState</code> and <code>updateCounts</code>
164 * are initialized to <code>null</code> and the vendor code is initialized to 0.
165 * The <code>cause</code> is not initialized, and may subsequently be
166 * initialized by a call to the
167 * {@link Throwable#initCause(java.lang.Throwable)} method.
168 * <p>
169 *
170 * @since 1.2
171 */
172 public BatchUpdateException() {
173 this(null, null, 0, null, null);
174 }
175
176 /**
177 * Constructs a <code>BatchUpdateException</code> object initialized with
178 * a given <code>cause</code>.
179 * The <code>SQLState</code> and <code>updateCounts</code>
180 * are initialized
181 * to <code>null</code> and the vendor code is initialized to 0.
182 * The <code>reason</code> is initialized to <code>null</code> if
183 * <code>cause==null</code> or to <code>cause.toString()</code> if
184 * <code>cause!=null</code>.
185 * @param cause the underlying reason for this <code>SQLException</code>
186 * (which is saved for later retrieval by the <code>getCause()</code> method);
187 * may be null indicating the cause is non-existent or unknown.
188 * @since 1.6
189 */
190 public BatchUpdateException(Throwable cause) {
191 this(null, null, 0, null, cause);
192 }
193
194 /**
195 * Constructs a <code>BatchUpdateException</code> object initialized with a
196 * given <code>cause</code> and <code>updateCounts</code>.
197 * The <code>SQLState</code> is initialized
198 * to <code>null</code> and the vendor code is initialized to 0.
199 * The <code>reason</code> is initialized to <code>null</code> if
200 * <code>cause==null</code> or to <code>cause.toString()</code> if
201 * <code>cause!=null</code>.
202 *
203 * @param updateCounts an array of <code>int</code>, with each element
204 * indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or
205 * <code>Statement.EXECUTE_FAILED</code> for each SQL command in
206 * the batch for JDBC drivers that continue processing
207 * after a command failure; an update count or
208 * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch
209 * prior to the failure for JDBC drivers that stop processing after a command
210 * failure
211 * @param cause the underlying reason for this <code>SQLException</code>
212 * (which is saved for later retrieval by the <code>getCause()</code> method); may be null indicating
213 * the cause is non-existent or unknown.
214 * @since 1.6
215 */
216 public BatchUpdateException(int []updateCounts , Throwable cause) {
217 this(null, null, 0, updateCounts, cause);
218 }
219
220 /**
221 * Constructs a <code>BatchUpdateException</code> object initialized with
222 * a given <code>reason</code>, <code>cause</code>
223 * and <code>updateCounts</code>. The <code>SQLState</code> is initialized
224 * to <code>null</code> and the vendor code is initialized to 0.
225 *
226 * @param reason a description of the exception
227 * @param updateCounts an array of <code>int</code>, with each element
228 *indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or
229 * <code>Statement.EXECUTE_FAILED</code> for each SQL command in
230 * the batch for JDBC drivers that continue processing
231 * after a command failure; an update count or
232 * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch
233 * prior to the failure for JDBC drivers that stop processing after a command
234 * failure
235 * @param cause the underlying reason for this <code>SQLException</code> (which is saved for later retrieval by the <code>getCause()</code> method);
236 * may be null indicating
237 * the cause is non-existent or unknown.
238 * @since 1.6
239 */
240 public BatchUpdateException(String reason, int []updateCounts, Throwable cause) {
241 this(reason, null, 0, updateCounts, cause);
242 }
243
244 /**
245 * Constructs a <code>BatchUpdateException</code> object initialized with
246 * a given <code>reason</code>, <code>SQLState</code>,<code>cause</code>, and
247 * <code>updateCounts</code>. The vendor code is initialized to 0.
248 *
249 * @param reason a description of the exception
250 * @param SQLState an XOPEN or SQL:2003 code identifying the exception
251 * @param updateCounts an array of <code>int</code>, with each element
252 * indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or
253 * <code>Statement.EXECUTE_FAILED</code> for each SQL command in
254 * the batch for JDBC drivers that continue processing
255 * after a command failure; an update count or
256 * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch
257 * prior to the failure for JDBC drivers that stop processing after a command
258 * failure
259 * @param cause the underlying reason for this <code>SQLException</code> (which is saved for later retrieval by the <code>getCause()</code> method);
260 * may be null indicating
261 * the cause is non-existent or unknown.
262 * @since 1.6
263 */
264 public BatchUpdateException(String reason, String SQLState,
265 int []updateCounts, Throwable cause) {
266 this(reason, SQLState, 0, updateCounts, cause);
267 }
268
269 /**
270 * Constructs a <code>BatchUpdateException</code> object initialized with
271 * a given <code>reason</code>, <code>SQLState</code>, <code>vendorCode</code>
272 * <code>cause</code> and <code>updateCounts</code>.
273 *
274 * @param reason a description of the error
275 * @param SQLState an XOPEN or SQL:2003 code identifying the exception
276 * @param vendorCode an exception code used by a particular
277 * database vendor
278 * @param updateCounts an array of <code>int</code>, with each element
279 *indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or
280 * <code>Statement.EXECUTE_FAILED</code> for each SQL command in
281 * the batch for JDBC drivers that continue processing
282 * after a command failure; an update count or
283 * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch
284 * prior to the failure for JDBC drivers that stop processing after a command
285 * failure
286 * @param cause the underlying reason for this <code>SQLException</code> (which is saved for later retrieval by the <code>getCause()</code> method);
287 * may be null indicating
288 * the cause is non-existent or unknown.
289 * @since 1.6
290 */
291 public BatchUpdateException(String reason, String SQLState, int vendorCode,
292 int []updateCounts,Throwable cause) {
293 super(reason, SQLState, vendorCode, cause);
294 if(updateCounts != null) {
295 this.updateCounts = Arrays.copyOf(updateCounts, updateCounts.length);
296 }
297 }
298
299 /**
300 * Retrieves the update count for each update statement in the batch
301 * update that executed successfully before this exception occurred.
302 * A driver that implements batch updates may or may not continue to
303 * process the remaining commands in a batch when one of the commands
304 * fails to execute properly. If the driver continues processing commands,
305 * the array returned by this method will have as many elements as
306 * there are commands in the batch; otherwise, it will contain an
307 * update count for each command that executed successfully before
308 * the <code>BatchUpdateException</code> was thrown.
309 *<P>
310 * The possible return values for this method were modified for
311 * the Java 2 SDK, Standard Edition, version 1.3. This was done to
312 * accommodate the new option of continuing to process commands
313 * in a batch update after a <code>BatchUpdateException</code> object
314 * has been thrown.
315 *
316 * @return an array of <code>int</code> containing the update counts
317 * for the updates that were executed successfully before this error
318 * occurred. Or, if the driver continues to process commands after an
319 * error, one of the following for every command in the batch:
320 * <OL>
321 * <LI>an update count
322 * <LI><code>Statement.SUCCESS_NO_INFO</code> to indicate that the command
323 * executed successfully but the number of rows affected is unknown
324 * <LI><code>Statement.EXECUTE_FAILED</code> to indicate that the command
325 * failed to execute successfully
326 * </OL>
327 * @since 1.3
328 */
329 public int[] getUpdateCounts() {
330 return updateCounts != null ? Arrays.copyOf(updateCounts, updateCounts.length) : null;
331 }
332
333 /**
334 * The array that describes the outcome of a batch execution.
335 * @serial
336 * @since 1.2
337 */
338 private int[] updateCounts;
339
340 private static final long serialVersionUID = 5977529877145521757L;
341 }