1 /* 2 * Copyright the original author or authors. 3 * 4 * Licensed under the MOZILLA PUBLIC LICENSE, Version 1.1 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.mozilla.org/MPL/MPL-1.1.html 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 import org.as2lib.env.log.Logger; 18 import org.as2lib.env.log.LogLevel; 19 import org.as2lib.env.log.LogMessage; 20 import org.as2lib.env.log.logger.AbstractLogger; 21 22 /** 23 * {@code TraceLogger} logs messages using {@code trace}. 24 * 25 * <p>The actual logging is always made using {@code trace}. No other output 26 * devices are supported. Use the {@link SimpleLogger} to be able to add log 27 * handlers as you please which allows you to log to every device you want. 28 * 29 * <p>The basic methods to write the log messages are {@link #log}, {@link #debug}, 30 * {@link #info}, {@link #warning} and {@link #fatal}. 31 * 32 * <p>The first thing to note is that you can log messages at different levels. 33 * These levels are {@code DEBUG}, {@code INFO}, {@code WARNING}, {@code ERROR} 34 * and {@code FATAL}. Depending on what level has been set only messages at a 35 * given level are logged. The levels are organized in a hierarchical manner. That 36 * means if you set the log level to {@code ALL} every messages is logged. If you 37 * set it to {@code ERROR} only messages at {@code ERROR} and {@code FATAL} level 38 * are logged and so on. 39 * 40 * <p>To do not waste unnecessary performance in constructing log messages that are 41 * not logged you can use the {@link #isDebugEnabled}, {@link #isInfoEnabled}, 42 * {@link #isWarningEnabled}, {@link #isErrorEnabled} and {@link #isFatalEnabled} 43 * methods. 44 * 45 * <p>Note that the message does in neither case have to be a string. That means 46 * you can pass-in messages and let the actual handler or logger decide how to 47 * produce a string representation of the message. That is in most cases done by 48 * using the {@code toString} method of the specific message. You can use this 49 * method to do not lose performance in cases where the message is not logged. 50 * 51 * <p>Example: 52 * <code> 53 * var logger:TraceLogger = new TraceLogger("myTraceLogger"); 54 * // checks if the output gets actually made 55 * if (logger.isInfoEnabled()) { 56 // log the message at the info level 57 * logger.info("This is a informative log message."); 58 * } 59 * </code> 60 * 61 * <p>This logger cannot be used with the {@ling LoggerHierarchy} because it does 62 * not offer hierarchy support. If you want to use your logger in a hierarchy use 63 * the {@link SimpleHierarchicalLogger} instead. 64 * 65 * @author Simon Wacker 66 */ 67 class org.as2lib.env.log.logger.TraceLogger extends AbstractLogger implements Logger { 68 69 /** Makes the static variables of the super-class accessible through this class. */ 70 private static var __proto__:Function = AbstractLogger; 71 72 /** The set level. */ 73 private var level:LogLevel; 74 75 /** The set level as number. */ 76 private var levelAsNumber:Number; 77 78 /** The name of this logger. */ 79 private var name:String; 80 81 /** 82 * Constructs a new {@code TraceLogger} instance. 83 * 84 * <p>The default log level is {@code ALL}. This means all messages regardless of 85 * their level are logged. 86 * 87 * <p>The {@code name} is by default shown in the log message to identify where 88 * the message came from. 89 * 90 * @param name (optional) the name of this logger 91 */ 92 public function TraceLogger(name:String) { 93 this.name = name; 94 level = ALL; 95 levelAsNumber = level.toNumber(); 96 } 97 98 /** 99 * Returns the name of this logger. 100 * 101 * <p>This method returns {@code null} if no name has been set via the 102 * {@link #setName} method nor on construction. 103 * 104 * @return the name of this logger 105 */ 106 public function getName(Void):String { 107 return name; 108 } 109 110 /** 111 * Sets the name of this logger. 112 * 113 * <p>The name is by default shown in the log message. 114 * 115 * @param name the new name of this logger 116 */ 117 public function setName(name:String):Void { 118 this.name = name; 119 } 120 121 /** 122 * Sets the log level. 123 * 124 * <p>The log level determines which messages are logged and which are not. 125 * 126 * <p>A level of value {@code null} or {@code undefined} is interpreted as level 127 * {@code ALL} which is also the default level. 128 * 129 * @param level the new log level 130 */ 131 public function setLevel(level:LogLevel):Void { 132 if (level) { 133 this.level = level; 134 } else { 135 this.level = ALL; 136 } 137 this.levelAsNumber = this.level.toNumber(); 138 } 139 140 /** 141 * Returns the set level. 142 * 143 * @return the set level 144 */ 145 public function getLevel(Void):LogLevel { 146 return level; 147 } 148 149 /** 150 * Checks whether this logger is enabled for the passed-in {@code level}. 151 * 152 * <p>{@code false} will be returned if: 153 * <ul> 154 * <li>This logger is not enabled for the passed-in {@code level}.</li> 155 * <li>The passed-in {@code level} is {@code null} or {@code undefined}.</li> 156 * </ul> 157 * 158 * <p>Using this method as shown in the class documentation may improve performance 159 * depending on how long the log message construction takes. 160 * 161 * @param level the level to make the check upon 162 * @return {@code true} if this logger is enabled for the given {@code level} else 163 * {@code false} 164 * @see #log 165 */ 166 public function isEnabled(level:LogLevel):Boolean { 167 if (!level) return false; 168 return (levelAsNumber >= level.toNumber()); 169 } 170 171 /** 172 * Checks if this logger is enabled for debug level log messages. 173 * 174 * <p>Using this method as shown in the class documentation may improve performance 175 * depending on how long the log message construction takes. 176 * 177 * @return {@code true} if debug messages are logged 178 * @see org.as2lib.env.log.level.AbstractLogLevel#DEBUG 179 * @see #debug 180 */ 181 public function isDebugEnabled(Void):Boolean { 182 return (levelAsNumber >= debugLevelAsNumber); 183 } 184 185 /** 186 * Checks if this logger is enabled for info level log messages. 187 * 188 * <p>Using this method as shown in the class documentation may improve performance 189 * depending on how long the log message construction takes. 190 * 191 * @return {@code true} if info messages are logged 192 * @see org.as2lib.env.log.level.AbstractLogLevel#INFO 193 * @see #info 194 */ 195 public function isInfoEnabled(Void):Boolean { 196 return (levelAsNumber >= infoLevelAsNumber); 197 } 198 199 /** 200 * Checks if this logger is enabled for warning level log messages. 201 * 202 * <p>Using this method as shown in the class documentation may improve performance 203 * depending on how long the log message construction takes. 204 * 205 * @return {@code true} if warning messages are logged 206 * @see org.as2lib.env.log.level.AbstractLogLevel#WARNING 207 * @see #warning 208 */ 209 public function isWarningEnabled(Void):Boolean { 210 return (levelAsNumber >= warningLevelAsNumber); 211 } 212 213 /** 214 * Checks if this logger is enabled for error level log messages. 215 * 216 * <p>Using this method as shown in the class documentation may improve performance 217 * depending on how long the log message construction takes. 218 * 219 * @return {@code true} if error messages are logged 220 * @see org.as2lib.env.log.level.AbstractLogLevel#ERROR 221 * @see #error 222 */ 223 public function isErrorEnabled(Void):Boolean { 224 return (levelAsNumber >= errorLevelAsNumber); 225 } 226 227 /** 228 * Checks if this logger is enabled for fatal level log messages. 229 * 230 * <p>Using this method as shown in the class documentation may improve performance 231 * depending on how long the log message construction takes. 232 * 233 * @return {@code true} if fatal messages are logged 234 * @see org.as2lib.env.log.level.AbstractLogLevel#FATAL 235 * @see #fatal 236 */ 237 public function isFatalEnabled(Void):Boolean { 238 return (levelAsNumber >= fatalLevelAsNumber); 239 } 240 241 /** 242 * Logs the passed-in {@code message} at the given {@code level}. 243 * 244 * <p>The {@code message} is only logged when this logger is enabled for the 245 * passed-in {@code level}. 246 * 247 * <p>The {@code message} is always logged using {@code trace}. 248 * 249 * @param message the message object to log 250 * @param level the specific level at which the {@code message} shall be logged 251 * @see #isEnabled 252 */ 253 public function log(message, level:LogLevel):Void { 254 if (isEnabled(level)) { 255 trace(new LogMessage(message, level, name)); 256 } 257 } 258 259 /** 260 * Logs the passed-in {@code message} at debug level. 261 * 262 * <p>The {@code message} is only logged when the level is set to {@code DEBUG} or 263 * a level above. 264 * 265 * <p>The {@code message} is always logged using {@code trace}. 266 * 267 * @param message the message object to log 268 * @see #isDebugEnabled 269 */ 270 public function debug(message):Void { 271 if (isDebugEnabled()) { 272 trace(new LogMessage(message, debugLevel, name)); 273 } 274 } 275 276 /** 277 * Logs the passed-in {@code message} at info level. 278 * 279 * <p>The {@code message} is only logged when the level is set to {@code INFO} or 280 * a level above. 281 * 282 * <p>The {@code message} is always logged using {@code trace}. 283 * 284 * @param message the message object to log 285 * @see #isInfoEnabled 286 */ 287 public function info(message):Void { 288 if (isInfoEnabled()) { 289 trace(new LogMessage(message, infoLevel, name)); 290 } 291 } 292 293 /** 294 * Logs the passed-in {@code message} at warning level. 295 * 296 * <p>The {@code message} is only logged when the level is set to {@code WARNING} 297 * or a level above. 298 * 299 * <p>The {@code message} is always logged using {@code trace}. 300 * 301 * @param message the message object to log 302 * @see #isWarningEnabled 303 */ 304 public function warning(message):Void { 305 if (isWarningEnabled()) { 306 trace(new LogMessage(message, warningLevel, name)); 307 } 308 } 309 310 /** 311 * Logs the passed-in {@code message} at error level. 312 * 313 * <p>The {@code message} is only logged when the level is set to {@code ERROR} or 314 * a level above. 315 * 316 * <p>The {@code message} is always logged using {@code trace}. 317 * 318 * @param message the message object to log 319 * @see #isErrorEnabled 320 */ 321 public function error(message):Void { 322 if (isErrorEnabled()) { 323 trace(new LogMessage(message, errorLevel, name)); 324 } 325 } 326 327 /** 328 * Logs the passed-in {@code message} at fatal level. 329 * 330 * <p>The {@code message} is only logged when the level is set to {@code FATAL} or 331 * a level above. 332 * 333 * <p>The {@code message} is always logged using {@code trace}. 334 * 335 * @param message the message object to log 336 * @see #isFatalEnabled 337 */ 338 public function fatal(message):Void { 339 if (isFatalEnabled()) { 340 trace(new LogMessage(message, fatalLevel, name)); 341 } 342 } 343 344 }