1 /*
2 * Copyright (c) 1998, 2005, 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 /**
29 * The subclass of {@link SQLException} thrown when an error
30 * occurs during a batch update operation. In addition to the
31 * information provided by {@link SQLException}, a
32 * <code>BatchUpdateException</code> provides the update
33 * counts for all commands that were executed successfully during the
34 * batch update, that is, all commands that were executed before the error
35 * occurred. The order of elements in an array of update counts
36 * corresponds to the order in which commands were added to the batch.
37 * <P>
38 * After a command in a batch update fails to execute properly
39 * and a <code>BatchUpdateException</code> is thrown, the driver
40 * may or may not continue to process the remaining commands in
41 * the batch. If the driver continues processing after a failure,
42 * the array returned by the method
43 * <code>BatchUpdateException.getUpdateCounts</code> will have
44 * an element for every command in the batch rather than only
45 * elements for the commands that executed successfully before
46 * the error. In the case where the driver continues processing
47 * commands, the array element for any command
48 * that failed is <code>Statement.EXECUTE_FAILED</code>.
49 * <P>
50 * @since 1.2
51 */
52
53 public class BatchUpdateException extends SQLException {
54
55 /**
56 * Constructs a <code>BatchUpdateException</code> object initialized with a given
57 * <code>reason</code>, <code>SQLState</code>, <code>vendorCode</code> and
58 * <code>updateCounts</code>.
59 * The <code>cause</code> is not initialized, and may subsequently be
60 * initialized by a call to the
61 * {@link Throwable#initCause(java.lang.Throwable)} method.
62 * <p>
63 *
64 * @param reason a description of the error
65 * @param SQLState an XOPEN or SQL:2003 code identifying the exception
66 * @param vendorCode an exception code used by a particular
67 * database vendor
68 * @param updateCounts an array of <code>int</code>, with each element
69 * indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or
70 * <code>Statement.EXECUTE_FAILED</code> for each SQL command in
71 * the batch for JDBC drivers that continue processing
72 * after a command failure; an update count or
73 * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch
74 * prior to the failure for JDBC drivers that stop processing after a command
75 * failure
76 * @since 1.2
77 */
78 public BatchUpdateException( String reason, String SQLState, int vendorCode,
79 int[] updateCounts ) {
80 super(reason, SQLState, vendorCode);
81 this.updateCounts = updateCounts;
82 }
83
84 /**
85 * Constructs a <code>BatchUpdateException</code> object initialized with a given
86 * <code>reason</code>, <code>SQLState</code> and
87 * <code>updateCounts</code>.
88 * The <code>cause</code> is not initialized, and may subsequently be
89 * initialized by a call to the
90 * {@link Throwable#initCause(java.lang.Throwable)} method. The vendor code
91 * is intialized to 0.
92 * <p>
93 *
94 * @param reason a description of the exception
95 * @param SQLState an XOPEN or SQL:2003 code identifying the exception
96 * @param updateCounts an array of <code>int</code>, with each element
97 * indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or
98 * <code>Statement.EXECUTE_FAILED</code> for each SQL command in
99 * the batch for JDBC drivers that continue processing
100 * after a command failure; an update count or
101 * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch
102 * prior to the failure for JDBC drivers that stop processing after a command
103 * failure
104 * @since 1.2
105 */
106 public BatchUpdateException(String reason, String SQLState,
107 int[] updateCounts) {
108 super(reason, SQLState);
109 this.updateCounts = updateCounts;
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 super(reason);
136 this.updateCounts = 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 */
158 public BatchUpdateException(int[] updateCounts) {
159 super();
160 this.updateCounts = updateCounts;
161 }
162
163 /**
164 * Constructs a <code>BatchUpdateException</code> object.
165 * The <code>reason</code>, <code>SQLState</code> and <code>updateCounts</code>
166 * are initialized to <code>null</code> and the vendor code is initialized to 0.
167 * The <code>cause</code> is not initialized, and may subsequently be
168 * initialized by a call to the
169 * {@link Throwable#initCause(java.lang.Throwable)} method.
170 * <p>
171 *
172 * @since 1.2
173 */
174 public BatchUpdateException() {
175 super();
176 this.updateCounts = null;
177 }
178
179 /**
180 * Constructs a <code>BatchUpdateException</code> object initialized with
181 * a given <code>cause</code>.
182 * The <code>SQLState</code> and <code>updateCounts</code>
183 * are initialized
184 * to <code>null</code> and the vendor code is initialized to 0.
185 * The <code>reason</code> is initialized to <code>null</code> if
186 * <code>cause==null</code> or to <code>cause.toString()</code> if
187 * <code>cause!=null</code>.
188 * @param cause the underlying reason for this <code>SQLException</code>
189 * (which is saved for later retrieval by the <code>getCause()</code> method);
190 * may be null indicating the cause is non-existent or unknown.
191 * @since 1.6
192 */
193 public BatchUpdateException(Throwable cause) {
194 super(cause);
195 this.updateCounts = null;
196 }
197
198 /**
199 * Constructs a <code>BatchUpdateException</code> object initialized with a
200 * given <code>cause</code> and <code>updateCounts</code>.
201 * The <code>SQLState</code> is initialized
202 * to <code>null</code> and the vendor code is initialized to 0.
203 * The <code>reason</code> is initialized to <code>null</code> if
204 * <code>cause==null</code> or to <code>cause.toString()</code> if
205 * <code>cause!=null</code>.
206 *
207 * @param updateCounts an array of <code>int</code>, with each element
208 * indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or
209 * <code>Statement.EXECUTE_FAILED</code> for each SQL command in
210 * the batch for JDBC drivers that continue processing
211 * after a command failure; an update count or
212 * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch
213 * prior to the failure for JDBC drivers that stop processing after a command
214 * failure
215 * @param cause the underlying reason for this <code>SQLException</code>
216 * (which is saved for later retrieval by the <code>getCause()</code> method); may be null indicating
217 * the cause is non-existent or unknown.
218 * @since 1.6
219 */
220 public BatchUpdateException(int []updateCounts , Throwable cause) {
221 super(cause);
222 this.updateCounts = updateCounts;
223 }
224
225 /**
226 * Constructs a <code>BatchUpdateException</code> object initialized with
227 * a given <code>reason</code>, <code>cause</code>
228 * and <code>updateCounts</code>. The <code>SQLState</code> is initialized
229 * to <code>null</code> and the vendor code is initialized to 0.
230 *
231 * @param reason a description of the exception
232 * @param updateCounts an array of <code>int</code>, with each element
233 *indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or
234 * <code>Statement.EXECUTE_FAILED</code> for each SQL command in
235 * the batch for JDBC drivers that continue processing
236 * after a command failure; an update count or
237 * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch
238 * prior to the failure for JDBC drivers that stop processing after a command
239 * failure
240 * @param cause the underlying reason for this <code>SQLException</code> (which is saved for later retrieval by the <code>getCause()</code> method);
241 * may be null indicating
242 * the cause is non-existent or unknown.
243 * @since 1.6
244 */
245 public BatchUpdateException(String reason, int []updateCounts, Throwable cause) {
246 super(reason,cause);
247 this.updateCounts = updateCounts;
248 }
249
250 /**
251 * Constructs a <code>BatchUpdateException</code> object initialized with
252 * a given <code>reason</code>, <code>SQLState</code>,<code>cause</code>, and
253 * <code>updateCounts</code>. The vendor code is initialized to 0.
254 *
255 * @param reason a description of the exception
256 * @param SQLState an XOPEN or SQL:2003 code identifying the exception
257 * @param updateCounts an array of <code>int</code>, with each element
258 * indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or
259 * <code>Statement.EXECUTE_FAILED</code> for each SQL command in
260 * the batch for JDBC drivers that continue processing
261 * after a command failure; an update count or
262 * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch
263 * prior to the failure for JDBC drivers that stop processing after a command
264 * failure
265 * @param cause the underlying reason for this <code>SQLException</code> (which is saved for later retrieval by the <code>getCause()</code> method);
266 * may be null indicating
267 * the cause is non-existent or unknown.
268 * @since 1.6
269 */
270 public BatchUpdateException(String reason, String SQLState,
271 int []updateCounts, Throwable cause) {
272 super(reason,SQLState,cause);
273 this.updateCounts = updateCounts;
274 }
275
276 /**
277 * Constructs a <code>BatchUpdateException</code> object initialized with
278 * a given <code>reason</code>, <code>SQLState</code>, <code>vendorCode</code>
279 * <code>cause</code> and <code>updateCounts</code>.
280 *
281 * @param reason a description of the error
282 * @param SQLState an XOPEN or SQL:2003 code identifying the exception
283 * @param vendorCode an exception code used by a particular
284 * database vendor
285 * @param updateCounts an array of <code>int</code>, with each element
286 *indicating the update count, <code>Statement.SUCCESS_NO_INFO</code> or
287 * <code>Statement.EXECUTE_FAILED</code> for each SQL command in
288 * the batch for JDBC drivers that continue processing
289 * after a command failure; an update count or
290 * <code>Statement.SUCCESS_NO_INFO</code> for each SQL command in the batch
291 * prior to the failure for JDBC drivers that stop processing after a command
292 * failure
293 * @param cause the underlying reason for this <code>SQLException</code> (which is saved for later retrieval by the <code>getCause()</code> method);
294 * may be null indicating
295 * the cause is non-existent or unknown.
296 * @since 1.6
297 */
298 public BatchUpdateException(String reason, String SQLState, int vendorCode,
299 int []updateCounts,Throwable cause) {
300 super(reason,SQLState,vendorCode,cause);
301 this.updateCounts = updateCounts;
302 }
303
304 /**
305 * Retrieves the update count for each update statement in the batch
306 * update that executed successfully before this exception occurred.
307 * A driver that implements batch updates may or may not continue to
308 * process the remaining commands in a batch when one of the commands
309 * fails to execute properly. If the driver continues processing commands,
310 * the array returned by this method will have as many elements as
311 * there are commands in the batch; otherwise, it will contain an
312 * update count for each command that executed successfully before
313 * the <code>BatchUpdateException</code> was thrown.
314 *<P>
315 * The possible return values for this method were modified for
316 * the Java 2 SDK, Standard Edition, version 1.3. This was done to
317 * accommodate the new option of continuing to process commands
318 * in a batch update after a <code>BatchUpdateException</code> object
319 * has been thrown.
320 *
321 * @return an array of <code>int</code> containing the update counts
322 * for the updates that were executed successfully before this error
323 * occurred. Or, if the driver continues to process commands after an
324 * error, one of the following for every command in the batch:
325 * <OL>
326 * <LI>an update count
327 * <LI><code>Statement.SUCCESS_NO_INFO</code> to indicate that the command
328 * executed successfully but the number of rows affected is unknown
329 * <LI><code>Statement.EXECUTE_FAILED</code> to indicate that the command
330 * failed to execute successfully
331 * </OL>
332 * @since 1.3
333 */
334 public int[] getUpdateCounts() {
335 return updateCounts;
336 }
337
338 /**
339 * The array that describes the outcome of a batch execution.
340 * @serial
341 * @since 1.2
342 */
343 private int[] updateCounts;
344
345 private static final long serialVersionUID = 5977529877145521757L;
346 }