001 /*
002 // $Id: //open/mondrian/src/main/mondrian/recorder/MessageRecorder.java#5 $
003 // This software is subject to the terms of the Common Public License
004 // Agreement, available at the following URL:
005 // http://www.opensource.org/licenses/cpl.html.
006 // Copyright (C) 2005-2006 Julian Hyde and others.
007 // All Rights Reserved.
008 // You must accept the terms of that agreement to use this software.
009 */
010
011 package mondrian.recorder;
012
013 /**
014 * Records warnings and errors during the processing of a task.
015 * Contexts can be added and removed.
016 * This allows one to collect more than one warning/error, keep processing,
017 * and then the code that initiated the processing can determine what to do
018 * with the warnings/errors if they exist.
019 * <p>
020 * A typical usage might be:
021 * <pre><code>
022 * void process(MessageRecorder msgRecorder) {
023 * msgRecorder.pushContextName(getName());
024 * try {
025 * // prcess task
026 * ....
027 * // need to generate warning message
028 * String msg = ...
029 * msgRecorder.reportWarning(msg);
030 * ....
031 * } finally {
032 * msgRecorder.popContextName();
033 * }
034 * }
035 * <code></pre>
036 * <p>
037 * Implementations must provide the means for extracting the error/warning
038 * messages.
039 * <p>
040 * Code that is processing should not catch the MessageRecorder.RTException.
041 * This Exception is thrown by the MessageRecorder when too many errors have
042 * been seen. Throwing this Exception is the mechanism used to stop processing
043 * and return to the initiating code. The initiating code should expect to
044 * catch the MessageRecorder.RTException Exception.
045 * <pre><code>
046 * void initiatingCode(MessageRecorder msgRecorder) {
047 * // get MessageRecorder implementation
048 * MessageRecorder msgRecorder = ....
049 * try {
050 * processingCode(msgRecorder);
051 * } catch (MessageRecorder.RTException mrex) {
052 * // empty
053 * }
054 * if (msgRecorder.hasErrors()) {
055 * // handle errors
056 * } else if (msgRecorder.hasWarnings()) {
057 * // handle warnings
058 * }
059 * }
060 * <code></pre>
061 * <p>
062 * The reporting methods all have variations that take an "info" Object.
063 * This can be used to pass something, beyond a text message, from the point
064 * of warning/error to the initiating code.
065 * <p>
066 * Concerning logging, it is a rule that a message, if logged by the code
067 * creating the MessageRecorder implementation, is logged at is reporting level,
068 * errors are logged at the error log level, warnings at the warning level and
069 * info at the info level. This allows the client code to "know" what log level
070 * their messages might appear at.
071 *
072 * @author Richard M. Emberson
073 * @version $Id: //open/mondrian/src/main/mondrian/recorder/MessageRecorder.java#5 $
074 */
075 public interface MessageRecorder {
076
077 /**
078 * Clear all context, warnings and errors from the MessageRecorder.
079 * After calling this method the MessageRecorder implemenation should
080 * be in the same state as if it were just constructed.
081 */
082 void clear();
083
084 /**
085 * Get the time when the MessageRecorder was created or the last time that
086 * the clear method was called.
087 *
088 * @return the start time
089 */
090 long getStartTimeMillis();
091
092 /**
093 * How long the MessageRecorder has been running since it was created or the
094 * last time clear was called.
095 */
096 long getRunTimeMillis();
097
098 /**
099 * 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 getContext();
125
126 /**
127 * Add the name parameter to the current context.
128 *
129 * @param name
130 */
131 void pushContextName(final String 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 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 ex, final Object 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 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 msg, final Object 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 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 msg, final Object info);
197
198 /**
199 * Add an informational message.
200 *
201 * @param msg the text of the info message.
202 */
203 void reportInfo(final String 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 msg, final Object info);
212 }
213
214 // End MessageRecorder.java