Source code: com/sonalb/IEnhancedException.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
33 /**
34 * Allows implementing classes to contain an
35 * application-specific error code, the class and
36 * method of origin, a data <code>Object</code>,
37 * and any underlying (causal) <code>Exception</code>.
38 * <p>
39 * These enhancements are described below :-<br>
40 * <ul>
41 * <li><b>Error Code</b>: A unique code is assigned
42 * to each application-specific error condition. This
43 * code may be useful for troubleshooting, or it may
44 * be used as a reference to allow the user to obtain
45 * more detailed information about the particular error
46 * condition.<br><br></li>
47 * <li><b>Class of origin</b>:</li>
48 * <li><b>Method of origin</b>: These two allow the
49 * convenient determination of the class and the method
50 * where this <code>IEnhancedException</code> instance was
51 * <u><i>created</i></u>.<br><br></li>
52 * <li><b>Data Object</b>: This <code>Object</code> allows
53 * this <code>IEnhancedException</code> instance to pass some
54 * information up the stack.<br><br></li>
55 * <li><b>Causal Exception</b>: This is the underlying exception
56 * which is the "root cause" of this <code>IEnhancedException</code>.
57 * "Exception chaining" is possible if the causal exception is also
58 * an instance of <code>IEnhancedException</code>.<br><br></li>
59 * </ul>
60 * <p>
61 * Following are some guidelines for implementations :-<br>
62 * <ul>
63 * <li>
64 * In order to be useful, any implementing class should
65 * extend <code>Exception</code> (or one of its subclasses).</li>
66 * <li>It is up to the implementing class to determine how it internally
67 * stores and represents the contained data (error code, data object, origin etc).
68 * These fields may be populated at construction time (via appropriate
69 * constructor arguments), or using "setter" methods, or both.</li>
70 * <li>In keeping with the purpose of the above enhancements, implementations are
71 * expected to take suitable measures to ensure that the fields are populated only
72 * once, at or near the time that this instance is created. The data Object can be
73 * removed at any time, even higher up in the call stack.</li>
74 * </ul>
75 * <p>
76 * <b>NOTE:</b> Direct implementing classes DO NOT follow the same hierarchy
77 * as followed by the <code>Exception</code>s in the core Java packages. For example,
78 * <code>EnhancedIOException</code> is NOT a direct subclass of <code>EnhancedException</code>,
79 * even though <code>IOException</code> is a direct subclass of <code>Exception</code>. In other
80 * words, <code>(EnhancedIOException instanceof EnhancedException)</code> returns <code>false</code>
81 * even though <code>(IOException instanceof Exception)</code> returns <code>true</code>.
82 *
83 * @author Sonal Bansal
84 * @see java.lang.Exception
85 * @see com.sonalb.EnhancedException
86 * @see com.sonalb.EnhancedIOException
87 */
88 public interface IEnhancedException {
89 /**
90 * Returns the fully-qualified name of the class which constructed
91 * this instance.
92 *
93 * @return the <code>String</code> representing the class of origin ;
94 * "UNKNOWN" if it was not set.
95 */
96 public String getOriginClass();
97
98 /**
99 * Returns the name of the method in which this instance was constructed.
100 *
101 * @return the <code>String</code> representing the method of origin ;
102 * "UNKNOWN" if it was not set.
103 */
104 public String getOriginMethod();
105
106 /**
107 * Returns the application-specific error code associated with this instance.
108 *
109 * @return the <code>String</code> representing the error code ;
110 * "UNSPECIFIED" if it was not set.
111 */
112 public String getCode();
113
114 /**
115 * Returns the underlying <code>Exception</code> (if any) for this instance.
116 *
117 * @return the underlying (causal) <code>Exception</code> ;
118 * <code>null</code> if there is none.
119 */
120 public Exception getCausalException();
121
122 /**
123 * Returns the data object (if any) set by the originator.
124 *
125 * @return the <code>Object</code> ; <code>null</code> if there is none.
126 */
127 public Object getDataObject();
128
129 /**
130 * Removes the data object (if any) contained in this instance.
131 *
132 */
133 public void removeDataObject();
134 }