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 }