1 /* 2 * Copyright (c) 2006, 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 package java.sql; 26 27 import java.util.Map; 28 29 /** 30 * The subclass of {@link SQLException} is thrown when one or more client info properties 31 * could not be set on a <code>Connection</code>. In addition to the information provided 32 * by <code>SQLException</code>, a <code>SQLClientInfoException</code> provides a list of client info 33 * properties that were not set. 34 * 35 * Some databases do not allow multiple client info properties to be set 36 * atomically. For those databases, it is possible that some of the client 37 * info properties had been set even though the <code>Connection.setClientInfo</code> 38 * method threw an exception. An application can use the <code>getFailedProperties </code> 39 * method to retrieve a list of client info properties that were not set. The 40 * properties are identified by passing a 41 * <code>Map<String,ClientInfoStatus></code> to 42 * the appropriate <code>SQLClientInfoException</code> constructor. 43 * <p> 44 * @see ClientInfoStatus 45 * @see Connection#setClientInfo 46 * @since 1.6 47 */ 48 public class SQLClientInfoException extends SQLException { 49 50 51 52 53 private Map<String, ClientInfoStatus> failedProperties; 54 55 /** 56 * Constructs a <code>SQLClientInfoException</code> Object. 57 * The <code>reason</code>, 58 * <code>SQLState</code>, and failedProperties list are initialized to 59 * <code> null</code> and the vendor code is initialized to 0. 60 * The <code>cause</code> is not initialized, and may subsequently be 61 * initialized by a call to the 62 * {@link Throwable#initCause(java.lang.Throwable)} method. 63 * <p> 64 * 65 * @since 1.6 66 */ SQLClientInfoException()67 public SQLClientInfoException() { 68 69 this.failedProperties = null; 70 } 71 72 /** 73 * Constructs a <code>SQLClientInfoException</code> object initialized with a 74 * given <code>failedProperties</code>. 75 * The <code>reason</code> and <code>SQLState</code> are initialized 76 * to <code>null</code> and the vendor code is initialized to 0. 77 * 78 * The <code>cause</code> is not initialized, and may subsequently be 79 * initialized by a call to the 80 * {@link Throwable#initCause(java.lang.Throwable)} method. 81 * <p> 82 * 83 * @param failedProperties A Map containing the property values that could not 84 * be set. The keys in the Map 85 * contain the names of the client info 86 * properties that could not be set and 87 * the values contain one of the reason codes 88 * defined in <code>ClientInfoStatus</code> 89 * <p> 90 * @since 1.6 91 */ SQLClientInfoException(Map<String, ClientInfoStatus> failedProperties)92 public SQLClientInfoException(Map<String, ClientInfoStatus> failedProperties) { 93 94 this.failedProperties = failedProperties; 95 } 96 97 /** 98 * Constructs a <code>SQLClientInfoException</code> object initialized with 99 * a given <code>cause</code> and <code>failedProperties</code>. 100 * 101 * The <code>reason</code> is initialized to <code>null</code> if 102 * <code>cause==null</code> or to <code>cause.toString()</code> if 103 * <code>cause!=null</code> and the vendor code is initialized to 0. 104 * 105 * <p> 106 * 107 * @param failedProperties A Map containing the property values that could not 108 * be set. The keys in the Map 109 * contain the names of the client info 110 * properties that could not be set and 111 * the values contain one of the reason codes 112 * defined in <code>ClientInfoStatus</code> 113 * @param cause the (which is saved for later retrieval by the <code>getCause()</code> method); may be null indicating 114 * the cause is non-existent or unknown. 115 * <p> 116 * @since 1.6 117 */ SQLClientInfoException(Map<String, ClientInfoStatus> failedProperties, Throwable cause)118 public SQLClientInfoException(Map<String, ClientInfoStatus> failedProperties, 119 Throwable cause) { 120 121 super(cause != null?cause.toString():null); 122 initCause(cause); 123 this.failedProperties = failedProperties; 124 } 125 126 /** 127 * Constructs a <code>SQLClientInfoException</code> object initialized with a 128 * given <code>reason</code> and <code>failedProperties</code>. 129 * The <code>SQLState</code> is initialized 130 * to <code>null</code> and the vendor code is initialized to 0. 131 * 132 * The <code>cause</code> is not initialized, and may subsequently be 133 * initialized by a call to the 134 * {@link Throwable#initCause(java.lang.Throwable)} method. 135 * <p> 136 * 137 * @param reason a description of the exception 138 * @param failedProperties A Map containing the property values that could not 139 * be set. The keys in the Map 140 * contain the names of the client info 141 * properties that could not be set and 142 * the values contain one of the reason codes 143 * defined in <code>ClientInfoStatus</code> 144 * <p> 145 * @since 1.6 146 */ SQLClientInfoException(String reason, Map<String, ClientInfoStatus> failedProperties)147 public SQLClientInfoException(String reason, 148 Map<String, ClientInfoStatus> failedProperties) { 149 150 super(reason); 151 this.failedProperties = failedProperties; 152 } 153 154 /** 155 * Constructs a <code>SQLClientInfoException</code> object initialized with a 156 * given <code>reason</code>, <code>cause</code> and 157 * <code>failedProperties</code>. 158 * The <code>SQLState</code> is initialized 159 * to <code>null</code> and the vendor code is initialized to 0. 160 * <p> 161 * 162 * @param reason a description of the exception 163 * @param failedProperties A Map containing the property values that could not 164 * be set. The keys in the Map 165 * contain the names of the client info 166 * properties that could not be set and 167 * the values contain one of the reason codes 168 * defined in <code>ClientInfoStatus</code> 169 * @param cause the underlying reason for this <code>SQLException</code> (which is saved for later retrieval by the <code>getCause()</code> method); may be null indicating 170 * the cause is non-existent or unknown. 171 * <p> 172 * @since 1.6 173 */ SQLClientInfoException(String reason, Map<String, ClientInfoStatus> failedProperties, Throwable cause)174 public SQLClientInfoException(String reason, 175 Map<String, ClientInfoStatus> failedProperties, 176 Throwable cause) { 177 178 super(reason); 179 initCause(cause); 180 this.failedProperties = failedProperties; 181 } 182 183 /** 184 * Constructs a <code>SQLClientInfoException</code> object initialized with a 185 * given <code>reason</code>, <code>SQLState</code> and 186 * <code>failedProperties</code>. 187 * The <code>cause</code> is not initialized, and may subsequently be 188 * initialized by a call to the 189 * {@link Throwable#initCause(java.lang.Throwable)} method. The vendor code 190 * is initialized to 0. 191 * <p> 192 * 193 * @param reason a description of the exception 194 * @param SQLState an XOPEN or SQL:2003 code identifying the exception 195 * @param failedProperties A Map containing the property values that could not 196 * be set. The keys in the Map 197 * contain the names of the client info 198 * properties that could not be set and 199 * the values contain one of the reason codes 200 * defined in <code>ClientInfoStatus</code> 201 * <p> 202 * @since 1.6 203 */ SQLClientInfoException(String reason, String SQLState, Map<String, ClientInfoStatus> failedProperties)204 public SQLClientInfoException(String reason, 205 String SQLState, 206 Map<String, ClientInfoStatus> failedProperties) { 207 208 super(reason, SQLState); 209 this.failedProperties = failedProperties; 210 } 211 212 /** 213 * Constructs a <code>SQLClientInfoException</code> object initialized with a 214 * given <code>reason</code>, <code>SQLState</code>, <code>cause</code> 215 * and <code>failedProperties</code>. The vendor code is initialized to 0. 216 * <p> 217 * 218 * @param reason a description of the exception 219 * @param SQLState an XOPEN or SQL:2003 code identifying the exception 220 * @param failedProperties A Map containing the property values that could not 221 * be set. The keys in the Map 222 * contain the names of the client info 223 * properties that could not be set and 224 * the values contain one of the reason codes 225 * defined in <code>ClientInfoStatus</code> 226 * @param cause the underlying reason for this <code>SQLException</code> (which is saved for later retrieval by the <code>getCause()</code> method); may be null indicating 227 * the cause is non-existent or unknown. 228 * <p> 229 * @since 1.6 230 */ SQLClientInfoException(String reason, String SQLState, Map<String, ClientInfoStatus> failedProperties, Throwable cause)231 public SQLClientInfoException(String reason, 232 String SQLState, 233 Map<String, ClientInfoStatus> failedProperties, 234 Throwable cause) { 235 236 super(reason, SQLState); 237 initCause(cause); 238 this.failedProperties = failedProperties; 239 } 240 241 /** 242 * Constructs a <code>SQLClientInfoException</code> object initialized with a 243 * given <code>reason</code>, <code>SQLState</code>, 244 * <code>vendorCode</code> and <code>failedProperties</code>. 245 * The <code>cause</code> is not initialized, and may subsequently be 246 * initialized by a call to the 247 * {@link Throwable#initCause(java.lang.Throwable)} method. 248 * <p> 249 * 250 * @param reason a description of the exception 251 * @param SQLState an XOPEN or SQL:2003 code identifying the exception 252 * @param vendorCode a database vendor-specific exception code 253 * @param failedProperties A Map containing the property values that could not 254 * be set. The keys in the Map 255 * contain the names of the client info 256 * properties that could not be set and 257 * the values contain one of the reason codes 258 * defined in <code>ClientInfoStatus</code> 259 * <p> 260 * @since 1.6 261 */ SQLClientInfoException(String reason, String SQLState, int vendorCode, Map<String, ClientInfoStatus> failedProperties)262 public SQLClientInfoException(String reason, 263 String SQLState, 264 int vendorCode, 265 Map<String, ClientInfoStatus> failedProperties) { 266 267 super(reason, SQLState, vendorCode); 268 this.failedProperties = failedProperties; 269 } 270 271 /** 272 * Constructs a <code>SQLClientInfoException</code> object initialized with a 273 * given <code>reason</code>, <code>SQLState</code>, 274 * <code>cause</code>, <code>vendorCode</code> and 275 * <code>failedProperties</code>. 276 * <p> 277 * 278 * @param reason a description of the exception 279 * @param SQLState an XOPEN or SQL:2003 code identifying the exception 280 * @param vendorCode a database vendor-specific exception code 281 * @param failedProperties A Map containing the property values that could not 282 * be set. The keys in the Map 283 * contain the names of the client info 284 * properties that could not be set and 285 * the values contain one of the reason codes 286 * defined in <code>ClientInfoStatus</code> 287 * @param cause the underlying reason for this <code>SQLException</code> (which is saved for later retrieval by the <code>getCause()</code> method); may be null indicating 288 * the cause is non-existent or unknown. 289 * <p> 290 * @since 1.6 291 */ SQLClientInfoException(String reason, String SQLState, int vendorCode, Map<String, ClientInfoStatus> failedProperties, Throwable cause)292 public SQLClientInfoException(String reason, 293 String SQLState, 294 int vendorCode, 295 Map<String, ClientInfoStatus> failedProperties, 296 Throwable cause) { 297 298 super(reason, SQLState, vendorCode); 299 initCause(cause); 300 this.failedProperties = failedProperties; 301 } 302 303 /** 304 * Returns the list of client info properties that could not be set. The 305 * keys in the Map contain the names of the client info 306 * properties that could not be set and the values contain one of the 307 * reason codes defined in <code>ClientInfoStatus</code> 308 * <p> 309 * 310 * @return Map list containing the client info properties that could 311 * not be set 312 * <p> 313 * @since 1.6 314 */ getFailedProperties()315 public Map<String, ClientInfoStatus> getFailedProperties() { 316 317 return this.failedProperties; 318 } 319 320 private static final long serialVersionUID = -4319604256824655880L; 321 } 322