Source code: com/sonalb/EnhancedIOException.java
1 /*
2 * -*- mode: java; c-basic-indent: 4; indent-tabs-mode: nil -*-
3 * :indentSize=4:noTabs=true:tabSize=4:indentOnTab=true:indentOnEnter=true:mode=java:
4 * ex: set tabstop=4 expandtab:
5 *
6 * MrPostman - webmail <-> email gateway
7 * Copyright (C) 2002-2003 MrPostman Development Group
8 * Projectpage: http://mrbook.org/mrpostman/
9 *
10 *
11 * This program is free software; you can redistribute it and/or modify
12 * it under the terms of the GNU General Public License as published by
13 * the Free Software Foundation; either version 2 of the License, or
14 * (at your option) any later version.
15 *
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU General Public License for more details.
20 * In particular, this implies that users are responsible for
21 * using MrPostman after reading the terms and conditions given
22 * by their web-mail provider.
23 *
24 * You should have received a copy of the GNU General Public License
25 * Named LICENSE in the base directory of this distribution,
26 * if not, write to the Free Software
27 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
28 */
29
30 package com.sonalb;
31
32 import java.util.logging.Level;
33 import java.util.logging.Logger;
34
35
36 /**
37
38 * Convenience implementation of <code>IEnhancedException</code>
39
40 * interface, and subclass of <code>java.io.IOException</code>.<p>
41
42 * Setter methods for the error code, causal Exception, class and
43
44 * method of origin, and data Object are provided. However, once these
45
46 * fields have been set, any subsequent calls to the respective setters
47
48 * throws an <code>UnsupportedOperationException</code>.
49
50 *
51
52 * @author Sonal Bansal
53
54 * @see com.sonalb.IEnhancedException
55
56 * @see java.io.IOException
57
58 */
59 public class EnhancedIOException extends java.io.IOException implements IEnhancedException {
60 public static final String CVSID = "$Id: EnhancedIOException.java,v 1.6 2003/02/09 23:38:09 lbruand Exp $";
61 private static Logger logger = Logger.getLogger("com.sonalb.EnhancedIOException");
62 private Exception causalException;
63 private String exceptionCode;
64 private String originClass;
65 private String originMethod;
66 private Object data;
67 private boolean bDataSet = false;
68 private boolean bClassSet = false;
69 private boolean bMethodSet = false;
70 private boolean bCodeSet = false;
71 private boolean bCausalSet = false;
72
73 /**
74
75 * Constructs a "plain vanilla" EnhancedIOException.
76
77 */
78 public EnhancedIOException() {
79 super();
80 }
81
82 /**
83
84 * Constructs an EnhancedIOException with a short detail message.
85
86 *
87
88 * @param s the detail message.
89
90 */
91 public EnhancedIOException(String s) {
92 super(s);
93 }
94
95 /**
96
97 * Constructs an EnhancedIOException with the specified causal Exception.
98
99 *
100
101 * @param under the causal Exception.
102
103 * @see java.lang.Exception
104
105 */
106 public EnhancedIOException(Exception under) {
107 super();
108
109 setCausalException(under);
110 }
111
112 /**
113
114 * Constructs an EnhancedIOException with the specified detail message and causal Exception.
115
116 *
117
118 * @param under the causal Exception.
119
120 * @param s the detail message.
121
122 * @see java.lang.Exception
123
124 */
125 public EnhancedIOException(String s, Exception under) {
126 super(s);
127
128 setCausalException(under);
129 }
130
131 /**
132
133 * Constructs an EnhancedIOException with a detail message, causal Exception, error code,
134
135 * class and method of origin. For example,<br>
136
137 * <code>
138
139 * ...<br>
140
141 * throw new EnhancedIOException("Failed to connect to server", excp, "SVR_0090", this, "connect");<br>
142
143 * ...</code>
144
145 *
146
147 * @param under the causal Exception.
148
149 * @param s the detail message.
150
151 * @param code the error-code.
152
153 * @param o the Object from which the class of origin is determined.
154
155 * @param method the method of origin.
156
157 * @see java.lang.Exception
158
159 */
160 public EnhancedIOException(String s, Exception under, String code, Object o, String method) {
161 super(s);
162
163 setCausalException(under);
164
165 setCode(code);
166
167 setOriginClass(o);
168
169 setOriginMethod(method);
170 }
171
172 /**
173
174 * Constructs an EnhancedIOException with an error code and, class and method of origin. For example,<br>
175
176 * <code>
177
178 * ...<br>
179
180 * throw new EnhancedIOException("SVR_0090", this, "connect");<br>
181
182 * ...</code>
183
184 *
185
186 * @param code the error-code.
187
188 * @param o the Object from which the class of origin is determined.
189
190 * @param method the method of origin.
191
192 */
193 public EnhancedIOException(String code, Object o, String method) {
194 super();
195
196 setCode(code);
197
198 setOriginClass(o);
199
200 setOriginMethod(method);
201 }
202
203 /**
204
205 * Constructs an EnhancedIOException with a detail message, error code,
206
207 * class and method of origin. For example,<br>
208
209 * <code>
210
211 * ...<br>
212
213 * throw new EnhancedIOException("Failed to connect to server", "SVR_0090", this, "connect");<br>
214
215 * ...</code>
216
217 *
218
219 * @param under the causal Exception.
220
221 * @param s the detail message.
222
223 * @param code the error-code.
224
225 * @param o the Object from which the class of origin is determined.
226
227 * @param method the method of origin.
228
229 * @see java.lang.Exception
230
231 */
232 public EnhancedIOException(String s, String code, Object o, String method) {
233 super(s);
234
235 setCode(code);
236
237 setOriginClass(o);
238
239 setOriginMethod(method);
240 }
241
242 public Exception getCausalException() {
243 return (causalException);
244 }
245
246 public String getOriginClass() {
247 return ((originClass == null) ? "UNKNOWN" : originClass);
248 }
249
250 public String getOriginMethod() {
251 return ((originMethod == null) ? "UNKNOWN" : originMethod);
252 }
253
254 public String getCode() {
255 return ((exceptionCode == null) ? "UNSPECIFIED" : exceptionCode);
256 }
257
258 /**
259
260 * Sets the data Object which will be passed up the call stack.
261
262 *
263
264 * @param o the data Object.
265
266 * @throws UnsupportedOperationException Thrown if the data Object has already been set.
267
268 */
269 public void setDataObject(Object o) throws UnsupportedOperationException {
270 if (bDataSet) {
271 throw new UnsupportedOperationException("Data Object has already been set.");
272 }
273
274 internalSetDataObject(o);
275
276 bDataSet = true;
277 }
278
279 public Object getDataObject() {
280 return (data);
281 }
282
283 public void removeDataObject() {
284 data = null;
285 }
286
287 /**
288
289 * Sets the error-code which identifies the particular error condition that
290
291 * triggered this exception.
292
293 *
294
295 * @param c the error code.
296
297 * @throws UnsupportedOperationException Thrown if the error code has already been set.
298
299 */
300 public void setCode(String c) throws UnsupportedOperationException {
301 if (bCodeSet) {
302 throw new UnsupportedOperationException("Error-code has already been set.");
303 }
304
305 internalSetCode(c);
306
307 bCodeSet = true;
308 }
309
310 /**
311
312 * Sets the class of origin for this instance. The class of origin is taken as
313
314 * the value returned by o.getClass().getName(). However, if the parameter
315
316 * is itself an instance of <code>Class</code>, then the class of origin is taken as
317
318 * o.getName().
319
320 *
321
322 * @param o the Object representing the class of origin.
323
324 * @throws UnsupportedOperationException Thrown if the class of origin has already been set.
325
326 * @see java.lang.Class
327
328 */
329 public void setOriginClass(Object o) throws UnsupportedOperationException {
330 if (bClassSet) {
331 throw new UnsupportedOperationException("Class of origin has already been set.");
332 }
333
334 internalSetOriginClass(o);
335
336 bClassSet = true;
337 }
338
339 /**
340
341 * Sets the method of origin for this instance.
342
343 *
344
345 * @param meth the String representing the method of origin.
346
347 * @throws UnsupportedOperationException Thrown if the method of origin has already been set.
348
349 */
350 public void setOriginMethod(String meth) throws UnsupportedOperationException {
351 if (bMethodSet) {
352 throw new UnsupportedOperationException("Method of origin has already been set.");
353 }
354
355 internalSetOriginMethod(meth);
356
357 bMethodSet = true;
358 }
359
360 /**
361
362 * Sets the underlying (causal) Exception for this instance.
363
364 *
365
366 * @param e the Exception representing the causal Exception.
367
368 * @throws UnsupportedOperationException Thrown if the causal Exception has already been set.
369
370 */
371 public void setCausalException(Exception e) throws UnsupportedOperationException {
372 if (bCausalSet) {
373 throw new UnsupportedOperationException("Causal Exception has already been set.");
374 }
375
376 internalSetCausalException(e);
377
378 bCausalSet = true;
379 }
380
381 /**
382
383 * Returns a short description of this instance. If this instance
384
385 * does not contain the error code or the origin info, the returned String
386
387 * is same as would be returned by <code>IOException.toString()</code>.
388
389 * Otherwise, the returned String is formed by concatenating the following :-<br>
390
391 * <ul>
392
393 * <li>The name of the actual class of this object </li>
394
395 * <li>": " (a colon and a space) </li>
396
397 * <li>The result of the {@link #getMessage} method for this object</li>
398
399 * <li>" : Code="</li>
400
401 * <li>The error-code</li>
402
403 * <li>" : OriginClass="</li>
404
405 * <li>The class of origin</li>
406
407 * <li>" : OriginMethod="</li>
408
409 * <li>The method of origin</li>
410
411 * <li>" : CausalException="</li>
412
413 * <li>The name of the class of the causal Exception (if any)</li>
414
415 * </ul>
416
417 *
418
419 * @return the <code>String</code> representation of this <code>EnhancedIOException</code>.
420
421 * @see java.io.IOException#toString()
422
423 */
424 public String toString() {
425 if ((exceptionCode == null) && (originClass == null) && (originMethod == null)) {
426 return (super.toString());
427 }
428
429 StringBuffer sb = new StringBuffer();
430
431 sb.append(getClass().getName());
432
433 sb.append(": ");
434
435 sb.append((getLocalizedMessage() == null) ? "" : getLocalizedMessage());
436
437 sb.append(" : Code=");
438
439 sb.append(getCode());
440
441 sb.append(" : OriginClass=");
442
443 sb.append(getOriginClass());
444
445 sb.append(" : OriginMethod=");
446
447 sb.append(getOriginMethod());
448
449 sb.append(" : CausalException=");
450
451 sb.append((getCausalException() == null) ? "" : getCausalException().getClass().getName());
452
453 if (getCausalException() != null) {
454 try {
455 java.io.StringWriter sw = new java.io.StringWriter();
456
457 getCausalException().printStackTrace(new java.io.PrintWriter(sw));
458
459 sb.append("\n");
460
461 sb.append(sw.toString());
462 } catch (Exception e) {
463 logger.log(Level.SEVERE, "should not happen", e);
464 }
465 }
466
467 return (sb.toString());
468 }
469
470 /**
471
472 * Sets the underlying (causal) Exception for this instance. Allows subclasses to have
473
474 * unrestricted access to "causal exception" field.
475
476 *
477
478 * @param e the Exception representing the causal Exception.
479
480 */
481 protected void internalSetCausalException(Exception e) {
482 causalException = e;
483 }
484
485 /**
486
487 * Sets the method of origin for this instance. Allows subclasses to have
488
489 * unrestricted access to "method of origin" field.
490
491 *
492
493 * @param meth the String representing the method of origin.
494
495 */
496 protected void internalSetOriginMethod(String meth) {
497 originMethod = meth;
498 }
499
500 /**
501
502 * Sets the class of origin for this instance. The class of origin is taken as
503
504 * the value returned by o.getClass().getName(). However, if the parameter
505
506 * is itself an instance of <code>Class</code>, then the class of origin is taken as
507
508 * o.getName(). Allows subclasses to have unrestricted access to "class of origin" field.
509
510 *
511
512 * @param o the Object representing the class of origin.
513
514 * @see java.lang.Class
515
516 */
517 protected void internalSetOriginClass(Object o) {
518 if (o != null) {
519 if (o instanceof Class) {
520 originClass = ((Class) o).getName();
521 } else {
522 originClass = o.getClass().getName();
523 }
524 } else {
525 originClass = null;
526 }
527 }
528
529 /**
530
531 * Sets the error-code which identifies the particular error condition that
532
533 * triggered this exception. Allows subclasses to have unrestricted access
534
535 * to "error code" field.
536
537 *
538
539 * @param c the error code.
540
541 */
542 protected void internalSetCode(String c) {
543 exceptionCode = c;
544 }
545
546 /**
547
548 * Sets the data Object which will be passed up the call stack. Allows subclasses to have
549
550 * unrestricted access to "data Object" field.
551
552 *
553
554 * @param o the data Object.
555
556 */
557 protected void internalSetDataObject(Object o) {
558 data = o;
559 }
560 }