Logger.java |
1 /* 2 * Copyright 2000-2001,2004 The Apache Software Foundation. 3 * 4 * Licensed under the Apache License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0 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 /* 18 19 */ 20 21 package org.apache.wsrp4j.log; 22 23 /** 24 <CODE>Logger</CODE> defines the methods which are used to create logging messages. 25 <P> 26 Logging levels are: <BR> 27 <DL> 28 <DT><CODE>ERROR</CODE> 29 <DD>A serious failure in the execution of the application 30 <DT><CODE>WARN</CODE> 31 <DD>An abnormal condition has been detected. The user may have to take action, but the 32 running code is able to handle this condition without ultimately failing. 33 <DT><CODE>INFO</CODE> 34 <DD>A condition that is worth noting but that does not require the user to perform 35 an action. 36 <DT><CODE>TRACE_LOW</CODE> 37 <DD>A low-detail trace message. 38 <DT><CODE>TRACE_MEDIUM</CODE> 39 <DD>A medium-detail trace message. 40 <DT><CODE>TRACE_HIGH</CODE> 41 <DD>A high-detail trace message. 42 </DL> 43 <BR> 44 45 Plain-text messages can be logged through the <CODE>text(...)</CODE> methods. These 46 messages are generally hard-coded into the application.<BR> 47 These methods should only be used for logging trace data. 48 <P> 49 In addition, the following specialized methods are available to log trace information. 50 Each of these trace methods is a convenience to the application programmer: 51 <DL> 52 <DT><CODE>entry</CODE> 53 <DD>Logs entry into a method. 54 <DT><CODE>exit</CODE> 55 <DD>Logs exit from a method. 56 <DT><CODE>stackTrace</CODE> 57 <DD>Logs the call stack. 58 </DL> 59 <P> 60 For performance reasons the method <CODE>isLogging(int logLevel)</CODE> should be used 61 to check if a given logging level is written at all to the output. The method should 62 be used for the log message level entries, but is absolutely required to be called for 63 trace messages to avoid unnecessary round-trips and object creation.<BR> 64 <P> 65 */ 66 67 public interface Logger { 68 /** 69 Defines an error message.<BR> 70 Use this type to inform the user of a serious failure in the execution of the application. 71 */ 72 public static final int ERROR = 10; 73 74 /** 75 Defines a warning message.<BR> 76 Use this type to inform a user that an abnormal condition has been detected. The user 77 may have to take action, but the running code is able to handle this condition without 78 ultimately failing.<BR> 79 A warning message is less severe than an error message. 80 */ 81 public static final int WARN = 20; 82 83 /** 84 Defines an informational message.<BR> 85 Use this type to indicate conditions that are worth noting but that do not require a 86 user to take any precautions or perform an action. Do not use this log level for 87 repeating events.<BR> 88 An informational message is less severe than a warning message. 89 */ 90 public static final int INFO = 30; 91 92 /** 93 Defines a low-detail trace message. 94 */ 95 public static final int TRACE_LOW = 40; 96 97 /** 98 Defines a medium-detail trace message. 99 */ 100 public static final int TRACE_MEDIUM = 50; 101 102 /** 103 Defines a high-detail trace message. 104 */ 105 public static final int TRACE_HIGH = 60; 106 107 /** 108 Determines if this logger is logging data for a given log level or not. 109 * 110 @param logLevel The log level to be checked. 111 @return <code>true</code> when the object is logging the log level; 112 <code>false</code> otherwise. 113 */ 114 public boolean isLogging(int logLevel); 115 116 /** 117 Logs a text message with no parameters. 118 * 119 @param logLevel The level of the log entry. 120 @param loggingMethod The name of the logging method. 121 @param text The message text. 122 */ 123 public void text(int logLevel, String loggingMethod, String text); 124 125 /** 126 Logs a text message with one parameter. 127 * 128 @param logLevel The level of the log entry. 129 @param loggingMethod The name of the logging method. 130 @param text The message text. 131 @param parm1 An element to be displayed with the message. 132 */ 133 public void text(int logLevel, String loggingMethod, String text, 134 Object parm1); 135 136 /** 137 Logs a text message with an array of parameters. 138 * 139 @param logLevel The level of the log entry. 140 @param loggingMethod The name of the logging method. 141 @param text The message text. 142 @param parms An array of elements to be displayed with the message. 143 */ 144 public void text(int logLevel, String loggingMethod, String text, 145 Object[] parms); 146 147 /** 148 Logs a text message with no parameters. 149 * 150 @param logLevel The level of the log entry. 151 @param loggingMethod The name of the logging method. 152 @param t The throwable that is cause for this log entry. 153 @param text The message text. 154 */ 155 public void text(int logLevel, String loggingMethod, Throwable t, 156 String text); 157 158 /** 159 Logs a text message with an array of parameters. 160 * 161 @param logLevel The level of the log entry. 162 @param loggingMethod The name of the logging method. 163 @param t The throwable that is cause for this log entry. 164 @param text The message text. 165 @param parms An array of elements to be displayed with the message. 166 */ 167 public void text(int logLevel, String loggingMethod, Throwable t, 168 String text, Object[] parms); 169 170 /** 171 Logs entry into a method. 172 * 173 @param logLevel The level of the log entry. 174 @param loggingMethod The name of the logging method. 175 */ 176 public void entry(int logLevel, String loggingMethod); 177 178 /** 179 Logs entry into a method. 180 * 181 @param logLevel The level of the log entry. 182 @param loggingMethod The name of the logging method. 183 @param parm1 An element to be displayed as trace data. 184 */ 185 public void entry(int logLevel, String loggingMethod, Object parm1); 186 187 /** 188 Logs entry into a method. 189 * 190 @param logLevel The level of the log entry. 191 @param loggingMethod The name of the logging method. 192 @param parms An array of parameters passed to the method. 193 */ 194 public void entry(int logLevel, String loggingMethod, Object[] parms); 195 196 /** 197 Logs exit from a method. 198 * 199 @param logLevel The level of the log entry. 200 @param loggingMethod The name of the logging method. 201 */ 202 public void exit(int logLevel, String loggingMethod); 203 204 /** 205 Logs exit from a method. 206 * 207 @param logLevel The level of the log entry. 208 @param loggingMethod The name of the logging method. 209 @param retValue The returned value. 210 */ 211 public void exit(int logLevel, String loggingMethod, byte retValue); 212 213 /** 214 Logs exit from a method. 215 * 216 @param logLevel The level of the log entry. 217 @param loggingMethod The name of the logging method. 218 @param retValue The returned value. 219 */ 220 public void exit(int logLevel, String loggingMethod, short retValue); 221 222 /** 223 Logs exit from a method. 224 * 225 @param logLevel The level of the log entry. 226 @param loggingMethod The name of the logging method. 227 @param retValue The returned value. 228 */ 229 public void exit(int logLevel, String loggingMethod, int retValue); 230 231 /** 232 Logs exit from a method. 233 * 234 @param logLevel The level of the log entry. 235 @param loggingMethod The name of the logging method. 236 @param retValue The returned value. 237 */ 238 public void exit(int logLevel, String loggingMethod, long retValue); 239 240 /** 241 Logs exit from a method. 242 * 243 @param logLevel The level of the log entry. 244 @param loggingMethod The name of the logging method. 245 @param retValue The returned value. 246 */ 247 public void exit(int logLevel, String loggingMethod, float retValue); 248 249 /** 250 Logs exit from a method. 251 * 252 @param logLevel The level of the log entry. 253 @param loggingMethod The name of the logging method. 254 @param retValue The returned value. 255 */ 256 public void exit(int logLevel, String loggingMethod, double retValue); 257 258 /** 259 Logs exit from a method. 260 * 261 @param logLevel The level of the log entry. 262 @param loggingMethod The name of the logging method. 263 @param retValue The returned value. 264 */ 265 public void exit(int logLevel, String loggingMethod, char retValue); 266 267 /** 268 Logs exit from a method. 269 * 270 @param logLevel The level of the log entry. 271 @param loggingMethod The name of the logging method. 272 @param retValue The returned value. 273 */ 274 public void exit(int logLevel, String loggingMethod, boolean retValue); 275 276 /** 277 Logs exit from a method. 278 * 279 @param logLevel The level of the log entry. 280 @param loggingMethod The name of the logging method. 281 @param retValue The returned value. 282 */ 283 public void exit(int logLevel, String loggingMethod, Object retValue); 284 285 /** 286 Logs the call stack. 287 * 288 @param logLevel The level of the log entry. 289 @param loggingMethod The name of the logging method. 290 @param text The message text. 291 */ 292 public void stackTrace(int logLevel, String loggingMethod, String text); 293 }