001: /*
002: * Copyright 2000-2001,2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: /*
018:
019: */
020:
021: package org.apache.wsrp4j.log;
022:
023: /**
024: <CODE>Logger</CODE> defines the methods which are used to create logging messages.
025: <P>
026: Logging levels are: <BR>
027: <DL>
028: <DT><CODE>ERROR</CODE>
029: <DD>A serious failure in the execution of the application
030: <DT><CODE>WARN</CODE>
031: <DD>An abnormal condition has been detected. The user may have to take action, but the
032: running code is able to handle this condition without ultimately failing.
033: <DT><CODE>INFO</CODE>
034: <DD>A condition that is worth noting but that does not require the user to perform
035: an action.
036: <DT><CODE>TRACE_LOW</CODE>
037: <DD>A low-detail trace message.
038: <DT><CODE>TRACE_MEDIUM</CODE>
039: <DD>A medium-detail trace message.
040: <DT><CODE>TRACE_HIGH</CODE>
041: <DD>A high-detail trace message.
042: </DL>
043: <BR>
044:
045: Plain-text messages can be logged through the <CODE>text(...)</CODE> methods. These
046: messages are generally hard-coded into the application.<BR>
047: These methods should only be used for logging trace data.
048: <P>
049: In addition, the following specialized methods are available to log trace information.
050: Each of these trace methods is a convenience to the application programmer:
051: <DL>
052: <DT><CODE>entry</CODE>
053: <DD>Logs entry into a method.
054: <DT><CODE>exit</CODE>
055: <DD>Logs exit from a method.
056: <DT><CODE>stackTrace</CODE>
057: <DD>Logs the call stack.
058: </DL>
059: <P>
060: For performance reasons the method <CODE>isLogging(int logLevel)</CODE> should be used
061: to check if a given logging level is written at all to the output. The method should
062: be used for the log message level entries, but is absolutely required to be called for
063: trace messages to avoid unnecessary round-trips and object creation.<BR>
064: <P>
065: */
066:
067: public interface Logger {
068: /**
069: Defines an error message.<BR>
070: Use this type to inform the user of a serious failure in the execution of the application.
071: */
072: public static final int ERROR = 10;
073:
074: /**
075: Defines a warning message.<BR>
076: Use this type to inform a user that an abnormal condition has been detected. The user
077: may have to take action, but the running code is able to handle this condition without
078: ultimately failing.<BR>
079: A warning message is less severe than an error message.
080: */
081: public static final int WARN = 20;
082:
083: /**
084: Defines an informational message.<BR>
085: Use this type to indicate conditions that are worth noting but that do not require a
086: user to take any precautions or perform an action. Do not use this log level for
087: repeating events.<BR>
088: An informational message is less severe than a warning message.
089: */
090: public static final int INFO = 30;
091:
092: /**
093: Defines a low-detail trace message.
094: */
095: public static final int TRACE_LOW = 40;
096:
097: /**
098: Defines a medium-detail trace message.
099: */
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,
275: boolean retValue);
276:
277: /**
278: Logs exit from a method.
279: *
280: @param logLevel The level of the log entry.
281: @param loggingMethod The name of the logging method.
282: @param retValue The returned value.
283: */
284: public void exit(int logLevel, String loggingMethod, Object retValue);
285:
286: /**
287: Logs the call stack.
288: *
289: @param logLevel The level of the log entry.
290: @param loggingMethod The name of the logging method.
291: @param text The message text.
292: */
293: public void stackTrace(int logLevel, String loggingMethod,
294: String text);
295: }
|