001/*
002// This software is subject to the terms of the Eclipse Public License v1.0
003// Agreement, available at the following URL:
004// http://www.eclipse.org/legal/epl-v10.html.
005// You must accept the terms of that agreement to use this software.
006//
007// Copyright (C) 2005-2005 Julian Hyde
008// Copyright (C) 2005-2009 Pentaho and others
009// All Rights Reserved.
010*/
011package 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 */
074public interface MessageRecorder {
075
076    /**
077     * Clear all context, warnings and errors from the MessageRecorder.
078     * After calling this method the MessageRecorder implemenation should
079     * be in the same state as if it were just constructed.
080     */
081    void clear();
082
083    /**
084     * Get the time when the MessageRecorder was created or the last time that
085     * the clear method was called.
086     *
087     * @return the start time
088     */
089    long getStartTimeMillis();
090
091    /**
092     * How long the MessageRecorder has been running since it was created or the
093     * last time clear was called.
094     */
095    long getRunTimeMillis();
096
097    /**
098     * Returns true if there are one or more informational messages.
099     *
100     * @return true if there are one or more infos.
101     */
102    boolean hasInformation();
103
104    /**
105     * Returns true if there are one or more warning messages.
106     *
107     * @return true if there are one or more warnings.
108     */
109    boolean hasWarnings();
110
111    /**
112     * Returns true if there are one or more error messages.
113     *
114     * @return true if there are one or more errors.
115     */
116    boolean hasErrors();
117
118    /**
119     * Get the current context string.
120     *
121     * @return the context string.
122     */
123    String getContext();
124
125    /**
126     * Add the name parameter to the current context.
127     *
128     * @param name
129     */
130    void pushContextName(final String name);
131
132    /**
133     * Remove the last context name added.
134     */
135    void popContextName();
136
137    /**
138     * This simply throws a RTException. A client calls this if 1) there is one
139     * or more error messages reported and 2) the client wishes to stop
140     * processing. Implementations of this method should only throw the
141     * RTException if there have been errors reported - if there are no errors,
142     * then this method does nothing.
143     *
144     * @throws RecorderException
145     */
146    void throwRTException() throws RecorderException;
147
148    /**
149     * Add an Exception.
150     *
151     * @param ex the Exception added.
152     * @throws RecorderException if too many error messages have been added.
153     */
154    void reportError(final Exception ex) throws RecorderException;
155
156    /**
157     * Add an Exception and extra informaton.
158     *
159     * @param ex the Exception added.
160     * @param info extra information (not meant to be part of printed message)
161     * @throws RecorderException if too many error messages have been added.
162     */
163    void reportError(final Exception ex, final Object info)
164        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)
182        throws RecorderException;
183
184    /**
185     * Add a warning message.
186     *
187     * @param msg  the text of the warning message.
188     */
189    void reportWarning(final String msg);
190
191    /**
192     * Add a warning message and extra information.
193     *
194     * @param msg  the text of the warning message.
195     * @param info extra information (not meant to be part of printed message)
196     */
197    void reportWarning(final String msg, final Object info);
198
199    /**
200     * Add an informational message.
201     *
202     * @param msg  the text of the info message.
203     */
204    void reportInfo(final String msg);
205
206    /**
207     * Add an informational message  and extra information.
208     *
209     * @param msg  the text of the info message.
210     * @param info extra information (not meant to be part of printed message)
211     */
212    void reportInfo(final String msg, final Object info);
213}
214
215// End MessageRecorder.java