001 /*
002 * Copyright 2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025 package java.sql;
026
027 import java.util.Map;
028
029 /**
030 * The subclass of {@link SQLException} is thrown when one or more client info properties
031 * could not be set on a <code>Connection</code>. In addition to the information provided
032 * by <code>SQLException</code>, a <code>SQLClientInfoException</code> provides a list of client info
033 * properties that were not set.
034 *
035 * Some databases do not allow multiple client info properties to be set
036 * atomically. For those databases, it is possible that some of the client
037 * info properties had been set even though the <code>Connection.setClientInfo</code>
038 * method threw an exception. An application can use the <code>getFailedProperties </code>
039 * method to retrieve a list of client info properties that were not set. The
040 * properties are identified by passing a
041 * <code>Map<String,ClientInfoStatus></code> to
042 * the appropriate <code>SQLClientInfoException</code> constructor.
043 * <p>
044 * @see ClientInfoStatus
045 * @see Connection#setClientInfo
046 * @since 1.6
047 */
048 public class SQLClientInfoException extends SQLException {
049
050 private Map<String, ClientInfoStatus> failedProperties;
051
052 /**
053 * Constructs a <code>SQLClientInfoException</code> Object.
054 * The <code>reason</code>,
055 * <code>SQLState</code>, and failedProperties list are initialized to
056 * <code> null</code> and the vendor code is initialized to 0.
057 * The <code>cause</code> is not initialized, and may subsequently be
058 * initialized by a call to the
059 * {@link Throwable#initCause(java.lang.Throwable)} method.
060 * <p>
061 *
062 * @since 1.6
063 */
064 public SQLClientInfoException() {
065
066 this .failedProperties = null;
067 }
068
069 /**
070 * Constructs a <code>SQLClientInfoException</code> object initialized with a
071 * given <code>failedProperties</code>.
072 * The <code>reason</code> and <code>SQLState</code> are initialized
073 * to <code>null</code> and the vendor code is initialized to 0.
074 *
075 * The <code>cause</code> is not initialized, and may subsequently be
076 * initialized by a call to the
077 * {@link Throwable#initCause(java.lang.Throwable)} method.
078 * <p>
079 *
080 * @param failedProperties A Map containing the property values that could not
081 * be set. The keys in the Map
082 * contain the names of the client info
083 * properties that could not be set and
084 * the values contain one of the reason codes
085 * defined in <code>ClientInfoStatus</code>
086 * <p>
087 * @since 1.6
088 */
089 public SQLClientInfoException(
090 Map<String, ClientInfoStatus> failedProperties) {
091
092 this .failedProperties = failedProperties;
093 }
094
095 /**
096 * Constructs a <code>SQLClientInfoException</code> object initialized with
097 * a given <code>cause</code> and <code>failedProperties</code>.
098 *
099 * 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 * <p>
104 *
105 * @param failedProperties A Map containing the property values that could not
106 * be set. The keys in the Map
107 * contain the names of the client info
108 * properties that could not be set and
109 * the values contain one of the reason codes
110 * defined in <code>ClientInfoStatus</code>
111 * @param cause the (which is saved for later retrieval by the <code>getCause()</code> method); may be null indicating
112 * the cause is non-existent or unknown.
113 * <p>
114 * @since 1.6
115 */
116 public SQLClientInfoException(
117 Map<String, ClientInfoStatus> failedProperties,
118 Throwable cause) {
119
120 super (cause != null ? cause.toString() : null);
121 initCause(cause);
122 this .failedProperties = failedProperties;
123 }
124
125 /**
126 * Constructs a <code>SQLClientInfoException</code> object initialized with a
127 * given <code>reason</code> and <code>failedProperties</code>.
128 * The <code>SQLState</code> is initialized
129 * to <code>null</code> and the vendor code is initialized to 0.
130 *
131 * The <code>cause</code> is not initialized, and may subsequently be
132 * initialized by a call to the
133 * {@link Throwable#initCause(java.lang.Throwable)} method.
134 * <p>
135 *
136 * @param reason a description of the exception
137 * @param failedProperties A Map containing the property values that could not
138 * be set. The keys in the Map
139 * contain the names of the client info
140 * properties that could not be set and
141 * the values contain one of the reason codes
142 * defined in <code>ClientInfoStatus</code>
143 * <p>
144 * @since 1.6
145 */
146 public SQLClientInfoException(String reason,
147 Map<String, ClientInfoStatus> failedProperties) {
148
149 super (reason);
150 this .failedProperties = failedProperties;
151 }
152
153 /**
154 * Constructs a <code>SQLClientInfoException</code> object initialized with a
155 * given <code>reason</code>, <code>cause</code> and
156 * <code>failedProperties</code>.
157 * The <code>SQLState</code> is initialized
158 * to <code>null</code> and the vendor code is initialized to 0.
159 * <p>
160 *
161 * @param reason a description of the exception
162 * @param failedProperties A Map containing the property values that could not
163 * be set. The keys in the Map
164 * contain the names of the client info
165 * properties that could not be set and
166 * the values contain one of the reason codes
167 * defined in <code>ClientInfoStatus</code>
168 * @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
169 * the cause is non-existent or unknown.
170 * <p>
171 * @since 1.6
172 */
173 public SQLClientInfoException(String reason,
174 Map<String, ClientInfoStatus> failedProperties,
175 Throwable cause) {
176
177 super (reason);
178 initCause(cause);
179 this .failedProperties = failedProperties;
180 }
181
182 /**
183 * Constructs a <code>SQLClientInfoException</code> object initialized with a
184 * given <code>reason</code>, <code>SQLState</code> and
185 * <code>failedProperties</code>.
186 * The <code>cause</code> is not initialized, and may subsequently be
187 * initialized by a call to the
188 * {@link Throwable#initCause(java.lang.Throwable)} method. The vendor code
189 * is initialized to 0.
190 * <p>
191 *
192 * @param reason a description of the exception
193 * @param SQLState an XOPEN or SQL:2003 code identifying the exception
194 * @param failedProperties A Map containing the property values that could not
195 * be set. The keys in the Map
196 * contain the names of the client info
197 * properties that could not be set and
198 * the values contain one of the reason codes
199 * defined in <code>ClientInfoStatus</code>
200 * <p>
201 * @since 1.6
202 */
203 public SQLClientInfoException(String reason, String SQLState,
204 Map<String, ClientInfoStatus> failedProperties) {
205
206 super (reason, SQLState);
207 this .failedProperties = failedProperties;
208 }
209
210 /**
211 * Constructs a <code>SQLClientInfoException</code> object initialized with a
212 * given <code>reason</code>, <code>SQLState</code>, <code>cause</code>
213 * and <code>failedProperties</code>. The vendor code is initialized to 0.
214 * <p>
215 *
216 * @param reason a description of the exception
217 * @param SQLState an XOPEN or SQL:2003 code identifying the exception
218 * @param failedProperties A Map containing the property values that could not
219 * be set. The keys in the Map
220 * contain the names of the client info
221 * properties that could not be set and
222 * the values contain one of the reason codes
223 * defined in <code>ClientInfoStatus</code>
224 * @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
225 * the cause is non-existent or unknown.
226 * <p>
227 * @since 1.6
228 */
229 public SQLClientInfoException(String reason, String SQLState,
230 Map<String, ClientInfoStatus> failedProperties,
231 Throwable cause) {
232
233 super (reason, SQLState);
234 initCause(cause);
235 this .failedProperties = failedProperties;
236 }
237
238 /**
239 * Constructs a <code>SQLClientInfoException</code> object initialized with a
240 * given <code>reason</code>, <code>SQLState</code>,
241 * <code>vendorCode</code> and <code>failedProperties</code>.
242 * The <code>cause</code> is not initialized, and may subsequently be
243 * initialized by a call to the
244 * {@link Throwable#initCause(java.lang.Throwable)} method.
245 * <p>
246 *
247 * @param reason a description of the exception
248 * @param SQLState an XOPEN or SQL:2003 code identifying the exception
249 * @param vendorCode a database vendor-specific exception code
250 * @param failedProperties A Map containing the property values that could not
251 * be set. The keys in the Map
252 * contain the names of the client info
253 * properties that could not be set and
254 * the values contain one of the reason codes
255 * defined in <code>ClientInfoStatus</code>
256 * <p>
257 * @since 1.6
258 */
259 public SQLClientInfoException(String reason, String SQLState,
260 int vendorCode,
261 Map<String, ClientInfoStatus> failedProperties) {
262
263 super (reason, SQLState, vendorCode);
264 this .failedProperties = failedProperties;
265 }
266
267 /**
268 * Constructs a <code>SQLClientInfoException</code> object initialized with a
269 * given <code>reason</code>, <code>SQLState</code>,
270 * <code>cause</code>, <code>vendorCode</code> and
271 * <code>failedProperties</code>.
272 * <p>
273 *
274 * @param reason a description of the exception
275 * @param SQLState an XOPEN or SQL:2003 code identifying the exception
276 * @param vendorCode a database vendor-specific exception code
277 * @param failedProperties A Map containing the property values that could not
278 * be set. The keys in the Map
279 * contain the names of the client info
280 * properties that could not be set and
281 * the values contain one of the reason codes
282 * defined in <code>ClientInfoStatus</code>
283 * @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
284 * the cause is non-existent or unknown.
285 * <p>
286 * @since 1.6
287 */
288 public SQLClientInfoException(String reason, String SQLState,
289 int vendorCode,
290 Map<String, ClientInfoStatus> failedProperties,
291 Throwable cause) {
292
293 super (reason, SQLState, vendorCode);
294 initCause(cause);
295 this .failedProperties = failedProperties;
296 }
297
298 /**
299 * Returns the list of client info properties that could not be set. The
300 * keys in the Map contain the names of the client info
301 * properties that could not be set and the values contain one of the
302 * reason codes defined in <code>ClientInfoStatus</code>
303 * <p>
304 *
305 * @return Map list containing the client info properties that could
306 * not be set
307 * <p>
308 * @since 1.6
309 */
310 public Map<String, ClientInfoStatus> getFailedProperties() {
311
312 return this .failedProperties;
313 }
314
315 private static final long serialVersionUID = -4319604256824655880L;
316 }
|