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 runtime exception of all the runtime exceptions in EL4J.
23 * It provides a few functionalities, that may or may not be used by child
24 * exceptions:
25 * <ul>
26 * <li>Support to substitute parameters in an exception message.</li>
27 * </ul>
28 *
29 * Internationalizing exception messages can be performed (external to this
30 * class) with the help of the MessageSources of the spring framework.
31 *
32 *
33 * This class uses the exception wrapping mechanism of the java.lang.Exception
34 * class that was introduced with the JDK 1.4.
35 *
36 * @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/BaseRTException.java $
37 *
38 * @author Alain Borlet-Hote (ABH), Philipp Oser (POS), Paul E. Sevinç (PES),
39 * Yves Martin (YMA), Martin Zeltner (MZE)
40 *
41 * @see java.text.MessageFormat For more information on the format for the
42 * parameter substitution
43 */
44 public class BaseRTException extends RuntimeException {
45 /**
46 * Contains either the message of the exception or when message format is
47 * used, the messageFormat. MessageFormat substitution is applied if the
48 * result of getFormatParameters() is not null. The message field in the
49 * Throwable class is not used (rationale: it cannot be set without creating
50 * a new object).
51 */
52 protected String m_message;
53
54 /**
55 * The parameters to substitute. In subclasses, you may either use this
56 * Object[] to hold the messageFormatParameters or (typically preferred)
57 * define your own (typed and named) attributes that you need.
58 */
59 protected Object[] m_messageFormatParameters;
60
61 /**
62 * The constructor with a message in MessageFormat, with parameters, and
63 * with a wrapped exception (with all the formal parameters).
64 *
65 * @param message
66 * the message of this exception
67 * @param parameters
68 * the parameters to substitute in the message
69 * @param wrappedException
70 * the exception that is wrapped in this exception
71 */
72 public BaseRTException(String message, Object[] parameters,
73 Throwable wrappedException) {
74 super(wrappedException);
75 m_message = message;
76 m_messageFormatParameters = parameters;
77 }
78
79 /**
80 * The constructor with a message in MessageFormat and parameters. No
81 * Throwable or Exception is transfered.
82 *
83 * @param message
84 * the message of this exception
85 * @param parameters
86 * the parameters to substitute in the message
87 */
88 public BaseRTException(String message, Object[] parameters) {
89 this(message, parameters, null);
90 }
91
92 /**
93 * Constructor with a message and an exception.
94 *
95 * @param message
96 * the message of this exception
97 * @param exception
98 * the exception that is wrapped in this exception
99 */
100 public BaseRTException(String message, Throwable exception) {
101 this(message, null, exception);
102 }
103
104 /**
105 * Constructor with a message.
106 *
107 * @param message
108 * the message of this exception
109 */
110 public BaseRTException(String message) {
111 this(message, null, null);
112 }
113
114 /**
115 * Constructor with an exception.
116 *
117 * @param exception
118 * the exception that is wrapped in this exception
119 */
120 public BaseRTException(Throwable exception) {
121 this("BaseRTException without message", null, exception);
122 }
123
124 /**
125 * Returns the message pattern for <code>MessageFormat</code> or the
126 * message of the exception.
127 *
128 * @return the message of this exception (without any parameters substituted
129 * in it).
130 */
131 public String getFormatString() {
132 return m_message;
133 }
134
135 /**
136 * Sets a new format String. It replaces the default formatString by an
137 * internationalized String.
138 *
139 * @param formatString
140 * replaces the message
141 */
142 public void setFormatString(String formatString) {
143 m_message = formatString;
144 }
145
146 /**
147 * Gets parameters defined for the message. This should be overridden if you
148 * have defined your own set of attributes.
149 *
150 * @return array of arguments for <code>MessageFormat</code>
151 */
152 public Object[] getFormatParameters() {
153 return m_messageFormatParameters;
154 }
155
156 /**
157 * Get the normal message for the exception.
158 *
159 * Please override the <code>Throwable.getLocalizedMessage()</code> to
160 * automatically get the message particular for your Locale.
161 *
162 * @return the message for the user (if necessary with the substituted
163 * parameters)
164 */
165 public String getMessage() {
166 Object[] formatParameters = getFormatParameters();
167 if (formatParameters != null) {
168 return MessageFormat.format(m_message, formatParameters);
169 } else {
170 return m_message;
171 }
172 }
173 }