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