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.core.BasicInterface; 18 19 /** 20 * {@code Logger} declares all methods needed to log messages in a well defined 21 * and performant way. 22 * 23 * <p>The basic methods to log messages are {@link #debug}, {@link #info}, 24 * {@link #warning} and {@link #fatal}. 25 * 26 * <p>The first thing to note is that you can log messages at different levels. 27 * These levels are {@code DEBUG}, {@code INFO}, {@code WARNING}, {@code ERROR} 28 * and {@code FATAL}. Depending on what level has been set only messages at a 29 * given level are logged. The levels are organized in a hierarchical manner. That 30 * means if you set the log level to {@code ALL} every messages is logged. If you 31 * set it to {@code ERROR} only messages at {@code ERROR} and {@code FATAL} level 32 * are logged and so on. 33 * 34 * <p>To do not waste unnecessary performance in constructing log messages that are 35 * not logged you can use the {@link #isDebugEnabled}, {@link #isInfoEnabled}, 36 * {@link #isWarningEnabled}, {@link #isErrorEnabled} and {@link #isFatalEnabled} 37 * methods. 38 * 39 * <p>Note that the message does in neither case have to be a string. That means 40 * you can pass-in messages and let the actual handler or logger decide how to 41 * produce a string representation of the message. That is in most cases done by 42 * using the {@code toString} method of the specific message. You can use this 43 * method to do not lose performance in cases where the message is not logged. 44 * 45 * <p>The basic workflow of using loggers is as follows: 46 * <code> 47 * // MyLogger is an implementation of this interface 48 * var logger:Logger = new MyLogger(); 49 * if (logger.isInfoEnabled()) { 50 * logger.info("This is an information message."); 51 * } 52 * </code> 53 * 54 * <p>Note that we are in the above example not setting a log level. This depends 55 * on what configuration methods the implementation of this interface offers. 56 * 57 * <p>Note also that depending on the concrete implementation and the message it 58 * may be faster to do not call any of the {@code is*Enabled} methods. 59 * 60 * @author Simon Wacker 61 */ 62 interface org.as2lib.env.log.Logger extends BasicInterface { 63 64 /** 65 * Checks if this logger is enabled for debug level log messages. 66 * 67 * <p>Using this method as shown in the class documentation may improve performance 68 * depending on how long the log message construction takes. 69 * 70 * @return {@code true} if debug messagess are logged 71 * @see org.as2lib.env.log.level.AbstractLogLevel#DEBUG 72 * @see #debug 73 */ 74 public function isDebugEnabled(Void):Boolean; 75 76 /** 77 * Checks if this logger is enabled for info level log messages. 78 * 79 * <p>Using this method as shown in the class documentation may improve performance 80 * depending on how long the log message construction takes. 81 * 82 * @return {@code true} if info messages are logged 83 * @see org.as2lib.env.log.level.AbstractLogLevel#INFO 84 * @see #info 85 */ 86 public function isInfoEnabled(Void):Boolean; 87 88 /** 89 * Checks if this logger is enabled for warning level log messages. 90 * 91 * <p>Using this method as shown in the class documentation may improve performance 92 * depending on how long the log message construction takes. 93 * 94 * @return {@code true} if warning messages are logged 95 * @see org.as2lib.env.log.level.AbstractLogLevel#WARNING 96 * @see #warning 97 */ 98 public function isWarningEnabled(Void):Boolean; 99 100 /** 101 * Checks if this logger is enabled for error level log messages. 102 * 103 * <p>Using this method as shown in the class documentation may improve performance 104 * depending on how long the log message construction takes. 105 * 106 * @return {@code true} if error messages are logged 107 * @see org.as2lib.env.log.level.AbstractLogLevel#ERROR 108 * @see #error 109 */ 110 public function isErrorEnabled(Void):Boolean; 111 112 /** 113 * Checks if this logger is enabled for fatal level log messages. 114 * 115 * <p>Using this method as shown in the class documentation may improve performance 116 * depending on how long the log message construction takes. 117 * 118 * @return {@code true} if fatal messages are logged 119 * @see org.as2lib.env.log.level.AbstractLogLevel#FATAL 120 * @see #fatal 121 */ 122 public function isFatalEnabled(Void):Boolean; 123 124 /** 125 * Logs the passed-in {@code message} at debug level. 126 * 127 * <p>The message is only logged when the level is set to {@code DEBUG} or a level 128 * above. 129 * 130 * @param message the message object to log 131 * @see #isDebugEnabled 132 */ 133 public function debug(message):Void; 134 135 /** 136 * Logs the passed-in {@code message} at info level. 137 * 138 * <p>The message is only logged when the level is set to {@code INFO} or a level 139 * above. 140 * 141 * @param message the message object to log 142 * @see #isInfoEnabled 143 */ 144 public function info(message):Void; 145 146 /** 147 * Logs the passed-in {@code message} at warning level. 148 * 149 * <p>The message is only logged when the level is set to {@code WARNING} or a 150 * level above. 151 * 152 * @param message the message object to log 153 * @see #isWarningEnabled 154 */ 155 public function warning(message):Void; 156 157 /** 158 * Logs the passed-in {@code message} at error level. 159 * 160 * <p>The message is only logged when the level is set to {@code ERROR} or a level 161 * above. 162 * 163 * @param message the message object to log 164 * @see #isErrorEnabled 165 */ 166 public function error(message):Void; 167 168 /** 169 * Logs the passed-in {@code message} at fatal level. 170 * 171 * <p>The message is only logged when the level is set to {@code FATAL} or a level 172 * above. 173 * 174 * @param message the message object to log 175 * @see #isFatalEnabled 176 */ 177 public function fatal(message):Void; 178 179 }