1 /*
2 * Copyright (c) 2006, 2019, 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 @SuppressWarnings("serial") // Not statically typed as Serializable
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 }