Mercurial > projects > ldc

comparison tango/tango/util/log/Logger.d @ 132:1700239cab2e trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[svn r136] MAJOR UNSTABLE UPDATE!!! Initial commit after moving to Tango instead of Phobos. Lots of bugfixes... This build is not suitable for most things.
author lindquist
date Fri, 11 Jan 2008 17:57:40 +0100
parents
children
comparison
equal deleted inserted replaced
131:5825d48b27d1 132:1700239cab2e
1 /*******************************************************************************
2
3 copyright: Copyright (c) 2004 Kris Bell. All rights reserved
4
5 license: BSD style: $(LICENSE)
6
7 version: May 2004: Initial release
8 version: Feb 2007: Switched to lazy expr
9
10 author: Kris
11
12 *******************************************************************************/
13
14 module tango.util.log.Logger;
15
16 private import tango.time.Time;
17
18 private import tango.util.log.Appender;
19
20 private import tango.util.log.model.ILevel;
21
22 /*******************************************************************************
23
24 Loggers are named entities, sometimes shared, sometimes specific to
25 a particular portion of code. The names are generally hierarchical in
26 nature, using dot notation (with '.') to separate each named section.
27 For example, a typical name might be something like "mail.send.writer"
28 ---
29 import tango.util.log.Log;
30
31 auto log = Log.getLogger ("mail.send.writer");
32
33 log.info ("an informational message");
34 log.error ("an exception message: " ~ exception.toString);
35
36 etc ...
37 ---
38
39 It is considered good form to pass a logger instance as a function or
40 class-ctor argument, or to assign a new logger instance during static
41 class construction. For example: if it were considered appropriate to
42 have one logger instance per class, each might be constructed like so:
43 ---
44 private Logger log;
45
46 static this()
47 {
48 log = Log.getLogger (nameOfThisClassOrStructOrModule);
49 }
50 ---
51
52 Messages passed to a Logger are assumed to be pre-formatted. You
53 may find that the format() methos is handy for collating various
54 components of the message:
55 ---
56 char tmp[128] = void;
57 ...
58 log.warn (log.format (tmp, "temperature is {} degrees!", 101));
59 ---
60
61 Note that a provided workspace is used to format the message, which
62 should generally be located on the stack so as to support multiple
63 threads of execution. In the example above we indicate assignment as
64 "tmp = void", although this is an optional attribute (see the language
65 manual for more information).
66
67 To avoid overhead when constructing formatted messages, the logging
68 system employs lazy expressions such that the message is not constructed
69 unless the logger is actually active. You can also explicitly check to
70 see whether a logger is active or not:
71 ---
72 if (log.isEnabled (log.Level.Warn))
73 log.warn (log.format (tmp, "temperature is {} degrees!", 101));
74 ---
75
76 You might optionally configure various layout & appender implementations
77 to support specific exact rendering needs.
78
79 tango.log closely follows both the API and the behaviour as documented
80 at the official Log4J site, where you'll find a good tutorial. Those
81 pages are hosted over
82 <A HREF="http://logging.apache.org/log4j/docs/documentation.html">here</A>.
83
84 *******************************************************************************/
85
86 public class Logger : ILevel
87 {
88 /***********************************************************************
89
90 Add a trace message. This is called 'debug' in Log4J but
91 that is a reserved word in the D language
92
93 ***********************************************************************/
94
95 abstract Logger trace (lazy char[] exp);
96
97 /***********************************************************************
98
99 Add an info message
100
101 ***********************************************************************/
102
103 abstract Logger info (lazy char[] exp);
104
105 /***********************************************************************
106
107 Add a warning message
108
109 ***********************************************************************/
110
111 abstract Logger warn (lazy char[] exp);
112
113 /***********************************************************************
114
115 Add an error message
116
117 ***********************************************************************/
118
119 abstract Logger error (lazy char[] exp);
120
121 /***********************************************************************
122
123 Add a fatal message
124
125 ***********************************************************************/
126
127 abstract Logger fatal (lazy char[] exp);
128
129 /***********************************************************************
130
131 Append a message to this logger via its appender list.
132
133 ***********************************************************************/
134
135 abstract Logger append (Level level, lazy char[] exp);
136
137 /***********************************************************************
138
139 Format text using the formatter configured in the associated
140 hierarchy (see Hierarchy.setFormat)
141
142 ***********************************************************************/
143
144 abstract char[] format (char[] buffer, char[] formatStr, ...);
145
146 /***********************************************************************
147
148 Return the name of this Logger
149
150 ***********************************************************************/
151
152 abstract char[] name ();
153
154 /***********************************************************************
155
156 Return the current level assigned to this logger
157
158 ***********************************************************************/
159
160 abstract Level level ();
161
162 /***********************************************************************
163
164 Set the activity level of this logger. Levels control how
165 much information is emitted during runtime, and relate to
166 each other as follows:
167 ---
168 Trace < Info < Warn < Error < Fatal < None
169 ---
170 That is, if the level is set to Error, only calls to the
171 error() and fatal() methods will actually produce output:
172 all others will be inhibited.
173
174 Note that Log4J is a hierarchical environment, and each
175 logger defaults to inheriting a level from its parent.
176
177
178 ***********************************************************************/
179
180 abstract Logger setLevel (Level level = Level.Trace);
181
182 /***********************************************************************
183
184 same as setLevel (Level), but with additional control over
185 whether the children are forced to accept the changed level
186 or not. If 'force' is false, then children adopt the parent
187 level only if they have their own level set to Level.None
188
189 ***********************************************************************/
190
191 abstract Logger setLevel (Level level, bool force);
192
193 /***********************************************************************
194
195 Is this logger enabled for the provided level?
196
197 ***********************************************************************/
198
199 abstract bool isEnabled (Level level = Level.Fatal);
200
201 /***********************************************************************
202
203 Return whether this logger uses additive appenders or not.
204 See setAdditive().
205
206 ***********************************************************************/
207
208 abstract bool isAdditive ();
209
210 /***********************************************************************
211
212 Specify whether or not this logger has additive behaviour.
213 This is enabled by default, and causes a logger to invoke
214 all appenders within its ancestry (until an ancestor is
215 found with an additive attribute of false).
216
217 ***********************************************************************/
218
219 abstract Logger setAdditive (bool enabled);
220
221 /***********************************************************************
222
223 Add an appender to this logger. You may add multiple
224 appenders to appropriate loggers, and each of them
225 will be invoked for that given logger, and for each
226 of its child loggers (assuming isAdditive() is true
227 for those children). Note that multiple instances
228 of the same appender, regardless of where they may
229 reside within the tree, are not invoked at runtime.
230 That is, only one from a set of identical loggers
231 will execute.
232
233 Use clearAppenders() to remove all from a given logger.
234
235 ***********************************************************************/
236
237 abstract Logger addAppender (Appender appender);
238
239 /***********************************************************************
240
241 Remove all appenders from this logger.
242
243 ***********************************************************************/
244
245 abstract Logger clearAppenders ();
246
247 /***********************************************************************
248
249 Get number of milliseconds since this application started
250
251 ***********************************************************************/
252
253 abstract TimeSpan runtime ();
254 }