1 /*
2 * EL4J, the Extension Library for the J2EE, adds incremental enhancements to
3 * the spring framework, http://el4j.sf.net
4 * Copyright (C) 2005 by ELCA Informatique SA, Av. de la Harpe 22-24,
5 * 1000 Lausanne, Switzerland, http://www.elca.ch
6 *
7 * EL4J is published under the GNU Lesser General Public License (LGPL)
8 * Version 2.1. See http://www.gnu.org/licenses/
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU Lesser General Public License for more details.
14 *
15 * For alternative licensing, please contact info@elca.ch
16 */
17 package ch.elca.el4j.core.exceptions;
18
19 import java.text.MessageFormat;
20
21 /**
22 * This is the parent exception of all the exceptions in EL4J. It provides a
23 * few functionalities, that may or may not be used by child exceptions:
24 * <ul>
25 * <li>Support to substitute parameters in an exception message.</li>
26 * </ul>
27 *
28 * Internationalizing exception messages can be performed (external to this
29 * class) with the help of the MessageSources of the spring framework.
30 *
31 *
32 * This class uses the exception wrapping mechanism of the java.lang.Exception
33 * class that was introduced with the JDK 1.4.
34 *
35 * @svnLink $Revision: 3873 $;$Date: 2009-08-04 13:59:45 +0200 (Di, 04. Aug 2009) $;$Author: swismer $;$URL: https://el4j.svn.sourceforge.net/svnroot/el4j/branches/el4j_3_1/el4j/framework/modules/core/src/main/java/ch/elca/el4j/core/exceptions/BaseException.java $
36 *
37 * @author Alain Borlet-Hote (ABH), Philipp Oser (POS), Paul E. Sevinç (PES),
38 * Yves Martin (YMA), Martin Zeltner (MZE)
39 *
40 * @see java.text.MessageFormat For more information on the format for the
41 * parameter substitution
42 */
43 public class BaseException extends Exception {
44 /**
45 * Contains either the message of the exception or when message format is
46 * used, the messageFormat. MessageFormat substitution is applied if the
47 * result of getFormatParameters() is not null. The message field in the
48 * Throwable class is not used (rationale: it cannot be set without creating
49 * a new object).
50 */
51 protected String m_message;
52
53 /**
54 * The parameters to substitute. In subclasses, you may either use this
55 * Object[] to hold the messageFormatParameters or (typically preferred)
56 * define your own (typed and named) attributes that you need.
57 */
58 protected Object[] m_messageFormatParameters;
59
60 /**
61 * The constructor with a message in MessageFormat, with parameters, and
62 * with a wrapped exception (with all the formal parameters).
63 *
64 * @param message
65 * the message of this exception
66 * @param parameters
67 * the parameters to substitute in the message
68 * @param wrappedException
69 * the exception that is wrapped in this exception
70 */
71 public BaseException(String message, Object[] parameters,
72 Throwable wrappedException) {
73 super(wrappedException);
74 m_message = message;
75 m_messageFormatParameters = parameters;
76 }
77
78 /**
79 * The constructor with a message in MessageFormat and parameters. No
80 * Throwable or Exception is transfered.
81 *
82 * @param message
83 * the message of this exception
84 * @param parameters
85 * the parameters to substitute in the message
86 */
87 public BaseException(String message, Object[] parameters) {
88 // do not initialize cause otherwise initCause doesn't work anymore.
89 super();
90 m_message = message;
91 m_messageFormatParameters = parameters;
92 }
93
94 /**
95 * Constructor with a message and an exception.
96 *
97 * @param message
98 * the message of this exception
99 * @param exception
100 * the exception that is wrapped in this exception
101 */
102 public BaseException(String message, Throwable exception) {
103 this(message, null, exception);
104 }
105
106 /**
107 * Constructor with a message.
108 *
109 * @param message
110 * the message of this exception
111 */
112 public BaseException(String message) {
113 this(message, (Object[]) null);
114 }
115
116 /**
117 * Constructor with an exception.
118 *
119 * @param exception
120 * the exception that is wrapped in this exception
121 */
122 public BaseException(Throwable exception) {
123 this("BaseException without message", null, exception);
124 }
125
126 /**
127 * Returns the message pattern for <code>MessageFormat</code> or the
128 * message of the exception.
129 *
130 * @return the message of this exception (without any parameters substituted
131 * in it).
132 */
133 public String getFormatString() {
134 return m_message;
135 }
136
137 /**
138 * Sets a new format String. It replaces the default formatString by an
139 * internationalized String.
140 *
141 * @param formatString
142 * replaces the message
143 */
144 public void setFormatString(String formatString) {
145 m_message = formatString;
146 }
147
148 /**
149 * Gets parameters defined for the message. This should be overridden if you
150 * have defined your own set of attributes.
151 *
152 * @return array of arguments for <code>MessageFormat</code>
153 */
154 public Object[] getFormatParameters() {
155 return m_messageFormatParameters;
156 }
157
158 /**
159 * Get the normal message for the exception.
160 *
161 * Please override the <code>Throwable.getLocalizedMessage()</code> to
162 * automatically get the message particular for your Locale.
163 *
164 * @return the message for the user (if necessary with the substituted
165 * parameters)
166 */
167 public String getMessage() {
168 Object[] formatParameters = getFormatParameters();
169 if (formatParameters != null) {
170 return MessageFormat.format(m_message, formatParameters);
171 } else {
172 return m_message;
173 }
174 }
175 }