KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > mondrian > recorder > MessageRecorder


1 /*
2 // $Id: //open/mondrian/src/main/mondrian/recorder/MessageRecorder.java#5 $
3 // This software is subject to the terms of the Common Public License
4 // Agreement, available at the following URL:
5 // http://www.opensource.org/licenses/cpl.html.
6 // Copyright (C) 2005-2006 Julian Hyde and others.
7 // All Rights Reserved.
8 // You must accept the terms of that agreement to use this software.
9 */

10
11 package mondrian.recorder;
12
13 /**
14  * Records warnings and errors during the processing of a task.
15  * Contexts can be added and removed.
16  * This allows one to collect more than one warning/error, keep processing,
17  * and then the code that initiated the processing can determine what to do
18  * with the warnings/errors if they exist.
19  * <p>
20  * A typical usage might be:
21  * <pre><code>
22  * void process(MessageRecorder msgRecorder) {
23  * msgRecorder.pushContextName(getName());
24  * try {
25  * // prcess task
26  * ....
27  * // need to generate warning message
28  * String msg = ...
29  * msgRecorder.reportWarning(msg);
30  * ....
31  * } finally {
32  * msgRecorder.popContextName();
33  * }
34  * }
35  * <code></pre>
36  * <p>
37  * Implementations must provide the means for extracting the error/warning
38  * messages.
39  * <p>
40  * Code that is processing should not catch the MessageRecorder.RTException.
41  * This Exception is thrown by the MessageRecorder when too many errors have
42  * been seen. Throwing this Exception is the mechanism used to stop processing
43  * and return to the initiating code. The initiating code should expect to
44  * catch the MessageRecorder.RTException Exception.
45  * <pre><code>
46  * void initiatingCode(MessageRecorder msgRecorder) {
47  * // get MessageRecorder implementation
48  * MessageRecorder msgRecorder = ....
49  * try {
50  * processingCode(msgRecorder);
51  * } catch (MessageRecorder.RTException mrex) {
52  * // empty
53  * }
54  * if (msgRecorder.hasErrors()) {
55  * // handle errors
56  * } else if (msgRecorder.hasWarnings()) {
57  * // handle warnings
58  * }
59  * }
60  * <code></pre>
61  * <p>
62  * The reporting methods all have variations that take an "info" Object.
63  * This can be used to pass something, beyond a text message, from the point
64  * of warning/error to the initiating code.
65  * <p>
66  * Concerning logging, it is a rule that a message, if logged by the code
67  * creating the MessageRecorder implementation, is logged at is reporting level,
68  * errors are logged at the error log level, warnings at the warning level and
69  * info at the info level. This allows the client code to "know" what log level
70  * their messages might appear at.
71  *
72  * @author Richard M. Emberson
73  * @version $Id: //open/mondrian/src/main/mondrian/recorder/MessageRecorder.java#5 $
74  */

75 public interface MessageRecorder {
76
77     /**
78      * Clear all context, warnings and errors from the MessageRecorder.
79      * After calling this method the MessageRecorder implemenation should
80      * be in the same state as if it were just constructed.
81      */

82     void clear();
83
84     /**
85      * Get the time when the MessageRecorder was created or the last time that
86      * the clear method was called.
87      *
88      * @return the start time
89      */

90     long getStartTimeMillis();
91
92     /**
93      * How long the MessageRecorder has been running since it was created or the
94      * last time clear was called.
95      */

96     long getRunTimeMillis();
97
98     /**
99      * Returns true if there are one or more informational messages.
100      *
101      * @return true if there are one or more infos.
102      */

103     boolean hasInformation();
104
105     /**
106      * Returns true if there are one or more warning messages.
107      *
108      * @return true if there are one or more warnings.
109      */

110     boolean hasWarnings();
111
112     /**
113      * Returns true if there are one or more error messages.
114      *
115      * @return true if there are one or more errors.
116      */

117     boolean hasErrors();
118
119     /**
120      * Get the current context string.
121      *
122      * @return the context string.
123      */

124     String JavaDoc getContext();
125
126     /**
127      * Add the name parameter to the current context.
128      *
129      * @param name
130      */

131     void pushContextName(final String JavaDoc name);
132
133     /**
134      * Remove the last context name added.
135      */

136     void popContextName();
137
138     /**
139      * This simply throws a RTException. A client calls this if 1) there is one
140      * or more error messages reported and 2) the client wishes to stop
141      * processing. Implementations of this method should only throw the
142      * RTException if there have been errors reported - if there are no errors,
143      * then this method does nothing.
144      *
145      * @throws RecorderException
146      */

147     void throwRTException() throws RecorderException;
148
149     /**
150      * Add an Exception.
151      *
152      * @param ex the Exception added.
153      * @throws RecorderException if too many error messages have been added.
154      */

155     void reportError(final Exception JavaDoc ex) throws RecorderException;
156
157     /**
158      * Add an Exception and extra informaton.
159      *
160      * @param ex the Exception added.
161      * @param info extra information (not meant to be part of printed message)
162      * @throws RecorderException if too many error messages have been added.
163      */

164     void reportError(final Exception JavaDoc ex, final Object JavaDoc info) throws RecorderException;
165
166     /**
167      * Add an error message.
168      *
169      * @param msg the text of the error message.
170      * @throws RecorderException if too many error messages have been added.
171      */

172     void reportError(final String JavaDoc msg) throws RecorderException;
173
174     /**
175      * Add an error message and extra information.
176      *
177      * @param msg the text of the error message.
178      * @param info extra information (not meant to be part of printed message)
179      * @throws RecorderException if too many error messages have been added.
180      */

181     void reportError(final String JavaDoc msg, final Object JavaDoc info) throws RecorderException;
182
183     /**
184      * Add a warning message.
185      *
186      * @param msg the text of the warning message.
187      */

188     void reportWarning(final String JavaDoc msg);
189
190     /**
191      * Add a warning message and extra information.
192      *
193      * @param msg the text of the warning message.
194      * @param info extra information (not meant to be part of printed message)
195      */

196     void reportWarning(final String JavaDoc msg, final Object JavaDoc info);
197
198     /**
199      * Add an informational message.
200      *
201      * @param msg the text of the info message.
202      */

203     void reportInfo(final String JavaDoc msg);
204
205     /**
206      * Add an informational message and extra information.
207      *
208      * @param msg the text of the info message.
209      * @param info extra information (not meant to be part of printed message)
210      */

211     void reportInfo(final String JavaDoc msg, final Object JavaDoc info);
212 }
213
214 // End MessageRecorder.java
215
Popular Tags