1/*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements.  See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18package java.sql;
19
20import java.io.Serializable;
21
22/**
23 * This exception is thrown if a problem occurs during a batch update operation.
24 * <p>
25 * A {@code BatchUpdateException} provides additional information about the
26 * problem that occurred, compared with a standard {@code SQLException}. It
27 * supplies update counts for successful commands which were executed before the
28 * exception was encountered.
29 * <p>
30 * The element order in the array of update counts matches the order that the
31 * commands were added to the batch operation.
32 * <p>
33 * Once a batch update command fails and a {@code BatchUpdateException} is
34 * thrown, the JDBC driver may continue processing the remaining commands in the
35 * batch. If the driver does process more commands after the problem occurs, the
36 * array returned by {@code BatchUpdateException.getUpdateCounts} has an element
37 * for every command in the batch, not only those that executed successfully. In
38 * this case, the array element for any command which encountered a problem is
39 * set to {@code Statement.EXECUTE_FAILED}.
40 */
41public class BatchUpdateException extends SQLException implements Serializable {
42
43    private static final long serialVersionUID = 5977529877145521757L;
44
45    private int[] updateCounts = null;
46
47    /**
48     * Creates a default {@code BatchUpdateException} with the parameters
49     * <i>reason</i>, <i>SQLState</i>, and <i>update counts</i> set to {@code
50     * null} and the <i>vendor code</i> set to 0.
51     */
52    public BatchUpdateException() {
53    }
54
55    /**
56     * Creates an BatchUpdateException object. The reason is set to
57     * null if cause == null otherwise to cause.toString(), and the cause
58     * Throwable object is set to the given cause Throwable object.
59     *
60     * @param cause the Throwable object for the underlying reason this SQLException
61     *
62     * @since 1.6
63     */
64    public BatchUpdateException(Throwable cause) {
65        this(null, cause);
66    }
67
68    /**
69     * Creates an BatchUpdateException object. The Reason string is set to the
70     * null if cause == null otherwise to cause.toString(), and the cause
71     * Throwable object is set to the given cause Throwable object. SQLState is
72     * initialized to null while vendorCode is zero.
73     *
74     * @param cause the Throwable object for the underlying reason this SQLException
75     *
76     * @since 1.6
77     */
78    public BatchUpdateException(int[] updateCounts, Throwable cause) {
79        super(cause);
80        this.updateCounts = updateCounts;
81    }
82
83    /**
84     * Creates an BatchUpdateException object. The cause Throwable object is set
85     * to the given cause Throwable object. SQLState is initialized to null
86     * while vendorCode is zero.
87     *
88     * @param cause the Throwable object for the underlying reason this SQLException
89     *
90     * @since 1.6
91     */
92    public BatchUpdateException(String reason, int[] updateCounts,
93            Throwable cause) {
94        super(reason, cause);
95        this.updateCounts = updateCounts;
96    }
97
98    /**
99     * Creates an BatchUpdateException object. The cause Throwable object is set
100     * to the given cause Throwable object and the updateCounts array set to the
101     * int array parameter. SQLState is initialized to null while vendorCode is
102     * zero.
103     *
104     * @param cause the Throwable object for the underlying reason this SQLException
105     *
106     * @since 1.6
107     */
108    public BatchUpdateException(String reason, String SQLState,
109            int[] updateCounts, Throwable cause) {
110        super(reason, SQLState, cause);
111        this.updateCounts = updateCounts;
112    }
113
114    /**
115     * Creates an BatchUpdateException object. The cause Throwable object is set
116     * to the given cause Throwable object and the updateCounts array set to the
117     * int array parameter. VendorCode is set to the given vendorCode. SQLState
118     * is initialized to null while vendorCode is zero.
119     *
120     * @param cause the Throwable object for the underlying reason this SQLException
121     *
122     * @since 1.6
123     */
124    public BatchUpdateException(String reason, String SQLState, int vendorCode,
125            int[] updateCounts, Throwable cause) {
126        super(reason, SQLState, vendorCode, cause);
127        this.updateCounts = updateCounts;
128    }
129
130    /**
131     * Creates a {@code BatchUpdateException} with the {@code updateCounts} set
132     * to the supplied value. All other fields are set to their
133     * default values.
134     *
135     * @param updateCounts
136     *            the array of {@code updateCounts} giving the number of
137     *            successful updates (or another status code) for each command
138     *            in the batch that was attempted.
139     */
140    public BatchUpdateException(int[] updateCounts) {
141        this.updateCounts = updateCounts;
142    }
143
144    /**
145     * Creates a {@code BatchUpdateException} with the {@code updateCounts} and
146     * {@code reason} set to the supplied values. All other fields are set to their
147     * default values.
148     *
149     * @param reason
150     *            the message providing information about the source of this
151     *            exception.
152     * @param updateCounts
153     *            the array of {@code updateCounts} giving the number of
154     *            successful updates (or another status code) for each command
155     *            in the batch that was attempted.
156     */
157    public BatchUpdateException(String reason, int[] updateCounts) {
158        super(reason);
159        this.updateCounts = updateCounts;
160    }
161
162    /**
163     * Creates a {@code BatchUpdateException} with the {@code reason}, {@code
164     * SQLState} and {@code updateCounts} set to the supplied values. All other
165     * fields are set to their default values.
166     *
167     * @param reason
168     *            the message providing information about the source of this
169     *            exception.
170     * @param SQLState
171     *            the X/OPEN value to use for the {@code SQLState}
172     * @param updateCounts
173     *            the array of {@code updateCounts} giving the number of
174     *            successful updates (or another status code) for each command
175     *            in the batch that was attempted.
176     */
177    public BatchUpdateException(String reason, String SQLState,
178            int[] updateCounts) {
179        super(reason, SQLState);
180        this.updateCounts = updateCounts;
181    }
182
183    /**
184     * Creates a {@code BatchUpdateException} for the case where all relevant
185     * information is provided.
186     *
187     * @param reason
188     *            the message providing information about the source of this
189     *            exception.
190     * @param SQLState
191     *            the X/OPEN value to use for the {@code SQLState}.
192     * @param vendorCode
193     *            the value to use for the vendor error code.
194     * @param updateCounts
195     *            the array of {@code updateCounts} giving the number of
196     *            successful updates (or another status code) for each command
197     *            in the batch that was attempted.
198     */
199    public BatchUpdateException(String reason, String SQLState, int vendorCode,
200            int[] updateCounts) {
201        super(reason, SQLState, vendorCode);
202        this.updateCounts = updateCounts;
203    }
204
205    /**
206     * Gets the <i>update count</i> array giving status information for every
207     * command that was attempted in the batch.
208     * <p>
209     * If a batch update command fails and a {@code BatchUpdateException} is
210     * thrown, the JDBC driver may continue processing the remaining commands in
211     * the batch. If the driver does so, the array returned by {@code
212     * BatchUpdateException.getUpdateCounts} has an element for every command in
213     * the batch, not only those that executed successfully. In this case, the
214     * array element for any command which encountered a problem is set to
215     * {@code Statement.EXECUTE_FAILED}.
216     *
217     * @return an array that contains the successful update counts, before this
218     *         exception was thrown. Alternatively, if the driver continues to
219     *         process commands following an error, for each successive command
220     *         there is a corresponding element in the array giving one of the
221     *         following status values:
222     *         <ol>
223     *         <li>the number of successful updates</li> <li>{@code
224     *         Statement.SUCCESS_NO_INFO} indicating that the command completed
225     *         successfully, but the amount of altered rows is unknown.</li>
226     *         <li>{@code Statement.EXECUTE_FAILED} indicating that the command
227     *         was unsuccessful.</li>
228     *         </ol>
229     */
230    public int[] getUpdateCounts() {
231        return updateCounts;
232    }
233}
234