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 * 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 * 64 * @since 1.6 65 */ 66 public SQLClientInfoException() { 67 68 this.failedProperties = null; 69 } 70 71 /** 72 * Constructs a <code>SQLClientInfoException</code> object initialized with a 73 * given <code>failedProperties</code>. 74 * The <code>reason</code> and <code>SQLState</code> are initialized 75 * to <code>null</code> and the vendor code is initialized to 0. 76 * 77 * The <code>cause</code> is not initialized, and may subsequently be 78 * initialized by a call to the 79 * {@link Throwable#initCause(java.lang.Throwable)} method. 80 * 81 * @param failedProperties A Map containing the property values that could not 82 * be set. The keys in the Map 83 * contain the names of the client info 84 * properties that could not be set and 85 * the values contain one of the reason codes 86 * defined in <code>ClientInfoStatus</code> 87 * 88 * @since 1.6 89 */ 90 public SQLClientInfoException(Map<String, ClientInfoStatus> failedProperties) { 91 92 this.failedProperties = failedProperties; 93 } 94 95 /** 96 * Constructs a <code>SQLClientInfoException</code> object initialized with 97 * a given <code>cause</code> and <code>failedProperties</code>. 98 * 99 * The <code>reason</code> is initialized to <code>null</code> if 100 * <code>cause==null</code> or to <code>cause.toString()</code> if 101 * <code>cause!=null</code> and the vendor code is initialized to 0. 102 * 103 * @param failedProperties A Map containing the property values that could not 104 * be set. The keys in the Map 105 * contain the names of the client info 106 * properties that could not be set and 107 * the values contain one of the reason codes 108 * defined in <code>ClientInfoStatus</code> 109 * @param cause the (which is saved for later retrieval by the <code>getCause()</code> method); may be null indicating 110 * the cause is non-existent or unknown. 111 * 112 * @since 1.6 113 */ 114 public SQLClientInfoException(Map<String, ClientInfoStatus> failedProperties, 115 Throwable cause) { 116 117 super(cause != null?cause.toString():null); 118 initCause(cause); 119 this.failedProperties = failedProperties; 120 } 121 122 /** 123 * Constructs a <code>SQLClientInfoException</code> object initialized with a 124 * given <code>reason</code> and <code>failedProperties</code>. 125 * The <code>SQLState</code> is initialized 126 * to <code>null</code> and the vendor code is initialized to 0. 127 * 128 * The <code>cause</code> is not initialized, and may subsequently be 129 * initialized by a call to the 130 * {@link Throwable#initCause(java.lang.Throwable)} method. 131 * 132 * @param reason a description of the exception 133 * @param failedProperties A Map containing the property values that could not 134 * be set. The keys in the Map 135 * contain the names of the client info 136 * properties that could not be set and 137 * the values contain one of the reason codes 138 * defined in <code>ClientInfoStatus</code> 139 * 140 * @since 1.6 141 */ 142 public SQLClientInfoException(String reason, 143 Map<String, ClientInfoStatus> failedProperties) { 144 145 super(reason); 146 this.failedProperties = failedProperties; 147 } 148 149 /** 150 * Constructs a <code>SQLClientInfoException</code> object initialized with a 151 * given <code>reason</code>, <code>cause</code> and 152 * <code>failedProperties</code>. 153 * The <code>SQLState</code> is initialized 154 * to <code>null</code> and the vendor code is initialized to 0. 155 * 156 * @param reason a description of the exception 157 * @param failedProperties A Map containing the property values that could not 158 * be set. The keys in the Map 159 * contain the names of the client info 160 * properties that could not be set and 161 * the values contain one of the reason codes 162 * defined in <code>ClientInfoStatus</code> 163 * @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 164 * the cause is non-existent or unknown. 165 * 166 * @since 1.6 167 */ 168 public SQLClientInfoException(String reason, 169 Map<String, ClientInfoStatus> failedProperties, 170 Throwable cause) { 171 172 super(reason); 173 initCause(cause); 174 this.failedProperties = failedProperties; 175 } 176 177 /** 178 * Constructs a <code>SQLClientInfoException</code> object initialized with a 179 * given <code>reason</code>, <code>SQLState</code> and 180 * <code>failedProperties</code>. 181 * The <code>cause</code> is not initialized, and may subsequently be 182 * initialized by a call to the 183 * {@link Throwable#initCause(java.lang.Throwable)} method. The vendor code 184 * is initialized to 0. 185 * 186 * @param reason a description of the exception 187 * @param SQLState an XOPEN or SQL:2003 code identifying the exception 188 * @param failedProperties A Map containing the property values that could not 189 * be set. The keys in the Map 190 * contain the names of the client info 191 * properties that could not be set and 192 * the values contain one of the reason codes 193 * defined in <code>ClientInfoStatus</code> 194 * 195 * @since 1.6 196 */ 197 public SQLClientInfoException(String reason, 198 String SQLState, 199 Map<String, ClientInfoStatus> failedProperties) { 200 201 super(reason, SQLState); 202 this.failedProperties = failedProperties; 203 } 204 205 /** 206 * Constructs a <code>SQLClientInfoException</code> object initialized with a 207 * given <code>reason</code>, <code>SQLState</code>, <code>cause</code> 208 * and <code>failedProperties</code>. The vendor code is initialized to 0. 209 * 210 * @param reason a description of the exception 211 * @param SQLState an XOPEN or SQL:2003 code identifying the exception 212 * @param failedProperties A Map containing the property values that could not 213 * be set. The keys in the Map 214 * contain the names of the client info 215 * properties that could not be set and 216 * the values contain one of the reason codes 217 * defined in <code>ClientInfoStatus</code> 218 * @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 219 * the cause is non-existent or unknown. 220 * 221 * @since 1.6 222 */ 223 public SQLClientInfoException(String reason, 224 String SQLState, 225 Map<String, ClientInfoStatus> failedProperties, 226 Throwable cause) { 227 228 super(reason, SQLState); 229 initCause(cause); 230 this.failedProperties = failedProperties; 231 } 232 233 /** 234 * Constructs a <code>SQLClientInfoException</code> object initialized with a 235 * given <code>reason</code>, <code>SQLState</code>, 236 * <code>vendorCode</code> and <code>failedProperties</code>. 237 * The <code>cause</code> is not initialized, and may subsequently be 238 * initialized by a call to the 239 * {@link Throwable#initCause(java.lang.Throwable)} method. 240 * 241 * @param reason a description of the exception 242 * @param SQLState an XOPEN or SQL:2003 code identifying the exception 243 * @param vendorCode a database vendor-specific exception code 244 * @param failedProperties A Map containing the property values that could not 245 * be set. The keys in the Map 246 * contain the names of the client info 247 * properties that could not be set and 248 * the values contain one of the reason codes 249 * defined in <code>ClientInfoStatus</code> 250 * 251 * @since 1.6 252 */ 253 public SQLClientInfoException(String reason, 254 String SQLState, 255 int vendorCode, 256 Map<String, ClientInfoStatus> failedProperties) { 257 258 super(reason, SQLState, vendorCode); 259 this.failedProperties = failedProperties; 260 } 261 262 /** 263 * Constructs a <code>SQLClientInfoException</code> object initialized with a 264 * given <code>reason</code>, <code>SQLState</code>, 265 * <code>cause</code>, <code>vendorCode</code> and 266 * <code>failedProperties</code>. 267 * 268 * @param reason a description of the exception 269 * @param SQLState an XOPEN or SQL:2003 code identifying the exception 270 * @param vendorCode a database vendor-specific exception code 271 * @param failedProperties A Map containing the property values that could not 272 * be set. The keys in the Map 273 * contain the names of the client info 274 * properties that could not be set and 275 * the values contain one of the reason codes 276 * defined in <code>ClientInfoStatus</code> 277 * @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 278 * the cause is non-existent or unknown. 279 * 280 * @since 1.6 281 */ 282 public SQLClientInfoException(String reason, 283 String SQLState, 284 int vendorCode, 285 Map<String, ClientInfoStatus> failedProperties, 286 Throwable cause) { 287 288 super(reason, SQLState, vendorCode); 289 initCause(cause); 290 this.failedProperties = failedProperties; 291 } 292 293 /** 294 * Returns the list of client info properties that could not be set. The 295 * keys in the Map contain the names of the client info 296 * properties that could not be set and the values contain one of the 297 * reason codes defined in <code>ClientInfoStatus</code> 298 * 299 * @return Map list containing the client info properties that could 300 * not be set 301 * 302 * @since 1.6 303 */ 304 public Map<String, ClientInfoStatus> getFailedProperties() { 305 306 return this.failedProperties; 307 } 308 309 private static final long serialVersionUID = -4319604256824655880L; 310 }