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 18 package java.sql; 19 20 import 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 */ 41 public 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
