Source code: com/eireneh/util/LucidException.java
1
2 package com.eireneh.util;
3
4 import java.util.ResourceBundle;
5 import java.text.*;
6
7 /**
8 * A LucidException adds 3 concepts to a base Exception, that of a wrapped
9 * Exception, that of internationalised (i18n) messages, and that of an internal
10 * string which is for debugging/logging purposes.
11 *
12 * <p>The first addition is the concept of an optional wrapped Exception
13 * (actually a Throwable), which describes what caused this to happen. Any well
14 * defined interface will define the exact exceptions that the methods of that
15 * interface will throw, and not leave it to the ambiguous "throws Exception".
16 * However the interface should have no idea how it will be implemented and so
17 * the details of exactly what broke under the covers gets lost. With
18 * LucidException this detail is kept in the wrapped Exception. This
19 * functionallity is expected to be added to the base Exception class in JDK
20 * 1.4</p>
21 *
22 * <p>The second addition is the concept of i18n messages. Normal Exceptions are
23 * created with an almost random string in the message field, LucidExceptions
24 * define this string to be a key into a resource bundle, and to help formatting
25 * this string there is an optional Object array of format options.</p>
26 *
27 * <p>The third addition is that of a debug/logging string. Some information
28 * about what went wrong is not for the eyes of the user (especially in a web
29 * environment) but we may like to remember what broke.</p>
30 *
31 * <table border='1' cellPadding='3' cellSpacing='0' width="100%">
32 * <tr><td bgColor='white'class='TableRowColor'><font size='-7'>
33 * Distribution Licence:<br />
34 * Project B is free software; you can redistribute it
35 * and/or modify it under the terms of the GNU General Public License,
36 * version 2 as published by the Free Software Foundation.<br />
37 * This program is distributed in the hope that it will be useful,
38 * but WITHOUT ANY WARRANTY; without even the implied warranty of
39 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
40 * General Public License for more details.<br />
41 * The License is available on the internet
42 * <a href='http://www.gnu.org/copyleft/gpl.html'>here</a>, by writing to
43 * <i>Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
44 * MA 02111-1307, USA</i>, Or locally at the Licence link below.<br />
45 * The copyright to this program is held by it's authors.
46 * </font></td></tr></table>
47 * @see <a href='http://www.eireneh.com/servlets/Web'>Project B Home</a>
48 * @see docs.Licence
49 * @see EventException
50 * @see LogicError
51 * @author Joe Walker
52 * @version D0.I0.T0
53 */
54 public class LucidException extends Exception
55 {
56 /**
57 * All LucidExceptions are constructed with references to resources in
58 * an I18N properties file.
59 * @param msg The resource id to read
60 */
61 public LucidException(String msg)
62 {
63 super(msg);
64
65 this.ex = null;
66 this.params = null;
67 this.internal = null;
68 }
69
70 /**
71 * All LucidExceptions are constructed with references to resources in
72 * an I18N properties file.
73 * @param msg The resource id to read
74 */
75 public LucidException(String msg, Throwable ex)
76 {
77 super(msg);
78
79 this.ex = ex;
80 this.params = null;
81 this.internal = null;
82 }
83
84 /**
85 * All LucidExceptions are constructed with references to resources in
86 * an I18N properties file. This version allows us to add parameters
87 * @param msg The resource id to read
88 * @param params An array of parameters
89 */
90 public LucidException(String msg, Object[] params)
91 {
92 super(msg);
93
94 this.ex = null;
95 this.params = params;
96 this.internal = null;
97 }
98
99 /**
100 * All LucidExceptions are constructed with references to resources in
101 * an I18N properties file. This version allows us to add parameters
102 * @param msg The resource id to read
103 * @param params An array of parameters
104 */
105 public LucidException(String msg, Throwable ex, Object[] params)
106 {
107 super(msg);
108
109 this.ex = ex;
110 this.params = params;
111 this.internal = null;
112 }
113
114 /**
115 * All LucidExceptions are constructed with references to resources in
116 * an I18N properties file.
117 * @param msg The resource id to read
118 */
119 public LucidException(String msg, String internal)
120 {
121 super(msg);
122
123 this.ex = null;
124 this.params = null;
125 this.internal = internal;
126 }
127
128 /**
129 * All LucidExceptions are constructed with references to resources in
130 * an I18N properties file.
131 * @param msg The resource id to read
132 */
133 public LucidException(String msg, Throwable ex, String internal)
134 {
135 super(msg);
136
137 this.ex = ex;
138 this.params = null;
139 this.internal = internal;
140 }
141
142 /**
143 * All LucidExceptions are constructed with references to resources in
144 * an I18N properties file. This version allows us to add parameters
145 * @param msg The resource id to read
146 * @param params An array of parameters
147 */
148 public LucidException(String msg, Object[] params, String internal)
149 {
150 super(msg);
151
152 this.ex = null;
153 this.params = params;
154 this.internal = internal;
155 }
156
157 /**
158 * All LucidExceptions are constructed with references to resources in
159 * an I18N properties file. This version allows us to add parameters
160 * @param msg The resource id to read
161 * @param params An array of parameters
162 */
163 public LucidException(String msg, Throwable ex, Object[] params, String internal)
164 {
165 super(msg);
166
167 this.ex = ex;
168 this.params = params;
169 this.internal = internal;
170 }
171
172 /**
173 * We only unravel the message when we need to to save time
174 * @return The unraveled I18N string
175 */
176 public String getMessage()
177 {
178 String id = super.getMessage();
179 String out;
180
181 try
182 {
183 out = res.getString(id);
184 }
185 catch (Exception ex)
186 {
187 return "Error fetching resource for '"+id+"'";
188 }
189
190 try
191 {
192 MessageFormat formatter = new MessageFormat(out);
193 return formatter.format(params);
194 }
195 catch (Exception ex)
196 {
197 return "Error formatting message '"+out+"'";
198 }
199 }
200
201 /**
202 * Accessor of the full detailed version of the string
203 * @return The full unraveled I18N string
204 */
205 public String getDetailedMessage()
206 {
207 if (ex == null)
208 return getMessage();
209
210 String reason = res.getString("reason");
211 if (reason == null)
212 reason = " The cause of this is ...";
213
214 if (ex instanceof LucidException)
215 {
216 LucidException lex = (LucidException) ex;
217 return getMessage() + reason + lex.getDetailedMessage();
218 }
219 else
220 {
221 return getMessage() + reason + ex.getMessage();
222 }
223 }
224
225 /**
226 * Accessor for the message private to the developers
227 * @return The internal message
228 */
229 public String getInternalMessage()
230 {
231 return internal;
232 }
233
234 /**
235 * The nested Exception (is any)
236 * @return The Exception
237 */
238 public Throwable getException()
239 {
240 return ex;
241 }
242
243 /**
244 * A way of setting the name of the resource bundle to use. The default
245 * bundle is named com.eireneh.resources.Exception
246 * @param name The new resource bundle name
247 */
248 public static final void setResourceBundleName(String name)
249 {
250 res = ResourceBundle.getBundle(name);
251 }
252
253 /** An embedded exception */
254 protected Throwable ex;
255
256 /** The array of parameters */
257 protected Object[] params;
258
259 /** The array of parameters */
260 protected String internal;
261
262 /** The resource hash */
263 protected static ResourceBundle res = ResourceBundle.getBundle("com.eireneh.resources.Exception");
264 }