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