1 // Module: Log4CPLUS
2 // File: logger.h
3 // Created: 6/2001
4 // Author: Tad E. Smith
5 //
6 //
7 // Copyright (C) Tad E. Smith All rights reserved.
8 //
9 // This software is published under the terms of the Apache Software
10 // License version 1.1, a copy of which has been included with this
11 // distribution in the LICENSE.APL file.
12 //
13
14 /** @file
15 * This header defines the Logger class and the logging macros. */
16
17 #ifndef _LOG4CPLUS_LOGGERHEADER_
18 #define _LOG4CPLUS_LOGGERHEADER_
19
20 #include <log4cplus/config.h>
21 #include <log4cplus/loglevel.h>
22 #include <log4cplus/loggingmacros.h>
23 #include <log4cplus/tstring.h>
24 #include <log4cplus/streams.h>
25 #include <log4cplus/helpers/pointer.h>
26 #include <log4cplus/spi/appenderattachable.h>
27 #include <log4cplus/spi/loggerfactory.h>
28
29 #include <memory>
30 #include <vector>
31
32 namespace log4cplus {
33 // Forward declarations
34 namespace spi {
35 class LoggerImpl;
36 typedef helpers::SharedObjectPtr<LoggerImpl> SharedLoggerImplPtr;
37 }
38 class Appender;
39 class Hierarchy;
40 class HierarchyLocker;
41 class DefaultLoggerFactory;
42
43
44 /** \typedef std::vector<Logger> LoggerList
45 * This is a list of {@link Logger Loggers}. */
46 typedef std::vector<Logger> LoggerList;
47
48
49 /**
50 * This is the central class in the log4cplus package. One of the
51 * distintive features of log4cplus are hierarchical loggers and their
52 * evaluation.
53 * <p>
54 * See the <a href="../../../../manual.html">user manual</a> for an
55 * introduction on this class.
56 */
57 class LOG4CPLUS_EXPORT Logger : public log4cplus::spi::AppenderAttachable {
58 public:
59 // Static Methods
60 /**
61 * Returns <code>true </code>if the named logger exists
62 * (in the default hierarchy).
63 *
64 * @param name The name of the logger to search for.
65 */
66 static bool exists(const log4cplus::tstring& name);
67
68 /*
69 * Returns all the currently defined loggers in the default
70 * hierarchy.
71 * <p>
72 * The root logger is <em>not</em> included in the returned
73 * list.
74 */
75 static LoggerList getCurrentLoggers();
76
77 /**
78 * Return the default Hierarchy instance.
79 */
80 static Hierarchy& getDefaultHierarchy();
81
82 /**
83 * Retrieve a logger with name <code>name</code>. If the named
84 * logger already exists, then the existing instance will be returned.
85 * Otherwise, a new instance is created.
86 * <p>
87 * By default, loggers do not have a set LogLevel but inherit
88 * it from the hierarchy. This is one of the central features of
89 * log4cplus.
90 * <p>
91 * @param name The name of the logger to retrieve.
92 */
93 static Logger getInstance(const log4cplus::tstring& name);
94
95 /**
96 * Like {@link #getInstance(log4cplus::tstring)} except that the type of logger
97 * instantiated depends on the type returned by the {@link
98 * spi::LoggerFactory#makeNewLoggerInstance} method of the
99 * <code>factory</code> parameter.
100 * <p>
101 * This method is intended to be used by sub-classes.
102 * <p>
103 * @param name The name of the logger to retrieve.
104 * @param factory A {@link spi::LoggerFactory} implementation that will
105 * actually create a new Instance.
106 */
107 static Logger getInstance(const log4cplus::tstring& name, spi::LoggerFactory& factory);
108
109 /**
110 * Return the root of the default logger hierrachy.
111 * <p>
112 * The root logger is always instantiated and available. It's
113 * name is "root".
114 * <p>
115 * Nevertheless, calling {@link #getInstance
116 * Logger.getInstance("root")} does not retrieve the root logger
117 * but a logger just under root named "root".
118 */
119 static Logger getRoot();
120
121 /**
122 * Calling this method will <em>safely</em> close and remove all
123 * appenders in all the loggers including root contained in the
124 * default hierachy.
125 * <p>
126 * Some appenders such as SocketAppender need to be closed before the
127 * application exits. Otherwise, pending logging events might be
128 * lost.
129 * <p>
130 * The <code>shutdown</code> method is careful to close nested
131 * appenders before closing regular appenders. This is allows
132 * configurations where a regular appender is attached to a logger
133 * and again to a nested appender.
134 */
135 static void shutdown();
136
137 // Non-Static Methods
138 /**
139 * If <code>assertion</code> parameter is <code>false</code>, then
140 * logs <code>msg</code> as an {@link #error(const log4cplus::tstring&) error}
141 * statement.
142 *
143 * @param assertion
144 * @param msg The message to print if <code>assertion</code> is
145 * false.
146 */
147 void assertion(bool assertionVal, const log4cplus::tstring& msg) {
148 if(!assertionVal) {
149 log(FATAL_LOG_LEVEL, msg);
150 }
151 }
152
153 /**
154 * Close all attached appenders implementing the AppenderAttachable
155 * interface.
156 */
157 void closeNestedAppenders();
158
159 /**
160 * Check whether this logger is enabled for a given {@link
161 * LogLevel} passed as parameter.
162 *
163 * @return boolean True if this logger is enabled for <code>ll</code>.
164 */
165 bool isEnabledFor(LogLevel ll) const;
166
167 /**
168 * This generic form is intended to be used by wrappers.
169 */
170 void log(LogLevel ll, const log4cplus::tstring& message,
171 const char* file=NULL, int line=-1);
172
173 /**
174 * This method creates a new logging event and logs the event
175 * without further checks.
176 */
177 void forcedLog(LogLevel ll, const log4cplus::tstring& message,
178 const char* file=NULL, int line=-1);
179
180 /**
181 * Call the appenders in the hierrachy starting at
182 * <code>this</code>. If no appenders could be found, emit a
183 * warning.
184 * <p>
185 * This method calls all the appenders inherited from the
186 * hierarchy circumventing any evaluation of whether to log or not
187 * to log the particular log request.
188 *
189 * @param spi::InternalLoggingEvent the event to log.
190 */
191 void callAppenders(const spi::InternalLoggingEvent& event);
192
193 /**
194 * Starting from this logger, search the logger hierarchy for a
195 * "set" LogLevel and return it. Otherwise, return the LogLevel of the
196 * root logger.
197 * <p>
198 * The Logger class is designed so that this method executes as
199 * quickly as possible.
200 */
201 LogLevel getChainedLogLevel() const;
202
203 /**
204 * Returns the assigned {@link LogLevel}, if any, for this Logger.
205 *
206 * @return LogLevel - the assigned LogLevel, can be <code>NOT_SET_LOG_LEVEL</code>.
207 */
208 LogLevel getLogLevel() const;
209
210 /**
211 * Set the LogLevel of this Logger.
212 */
213 void setLogLevel(LogLevel);
214
215 /**
216 * Return the the {@link Hierarchy} where this <code>Logger</code> instance is
217 * attached.
218 */
219 Hierarchy& getHierarchy() const;
220
221 /**
222 * Return the logger name.
223 */
224 log4cplus::tstring getName() const;
225
226 /**
227 * Get the additivity flag for this Logger instance.
228 */
229 bool getAdditivity() const;
230
231 /**
232 * Set the additivity flag for this Logger instance.
233 */
234 void setAdditivity(bool additive);
235
236
237 // AppenderAttachable Methods
238 virtual void addAppender(SharedAppenderPtr newAppender);
239
240 virtual SharedAppenderPtrList getAllAppenders();
241
242 virtual SharedAppenderPtr getAppender(const log4cplus::tstring& name);
243
244 virtual void removeAllAppenders();
245
246 virtual void removeAppender(SharedAppenderPtr appender);
247
248 virtual void removeAppender(const log4cplus::tstring& name);
249
250 // Copy Ctor
251 Logger(const Logger& rhs);
252 Logger& operator=(const Logger& rhs);
253
254 // Dtor
255 ~Logger();
256
257 /**
258 * Used to retrieve the parent of this Logger in the
259 * Logger tree.
260 */
261 Logger getParent();
262
263 protected:
264 // Data
265 /** This is a pointer to the implementation class. */
266 spi::LoggerImpl *value;
267
268 private:
269 // Ctors
270 /**
271 * This constructor created a new <code>Logger</code> instance
272 * with a pointer to a Logger implementation.
273 * <p>
274 * You should not create loggers directly.
275 *
276 * @param ptr A pointer to the Logger implementation. This value
277 * cannot be NULL.
278 */
279 Logger(spi::LoggerImpl *ptr);
280 Logger(const spi::SharedLoggerImplPtr& val);
281
282 // Methods
283 void init();
284 void validate(const char *file, int line) const;
285
286 // Friends
287 friend class log4cplus::spi::LoggerImpl;
288 friend class log4cplus::Hierarchy;
289 friend class log4cplus::HierarchyLocker;
290 friend class log4cplus::DefaultLoggerFactory;
291 };
292
293
294 /**
295 * This class is used to create the default implementation of
296 * the Logger class
297 */
298 class LOG4CPLUS_EXPORT DefaultLoggerFactory : public spi::LoggerFactory {
299 public:
300 Logger makeNewLoggerInstance(const log4cplus::tstring& name, Hierarchy& h);
301 };
302
303
304
305 /**
306 * This class is used to produce "Trace" logging. When an instance of
307 * this class is created, it will log a <code>"ENTER: " + msg</code>
308 * log message if TRACE_LOG_LEVEL is enabled for <code>logger</code>.
309 * When an instance of this class is destroyed, it will log a
310 * <code>"ENTER: " + msg</code> log message if TRACE_LOG_LEVEL is enabled
311 * for <code>logger</code>.
312 * <p>
313 * @see LOG4CPLUS_TRACE
314 */
315 class LOG4CPLUS_EXPORT TraceLogger {
316 public:
317 TraceLogger(const Logger& l, const log4cplus::tstring& _msg,
318 const char* _file=NULL, int _line=-1)
319 : logger(l), msg(_msg), file(_file), line(_line)
320 { if(logger.isEnabledFor(TRACE_LOG_LEVEL))
321 logger.forcedLog(TRACE_LOG_LEVEL, LOG4CPLUS_TEXT("ENTER: ") + msg, file, line);
322 }
323
324 ~TraceLogger()
325 { if(logger.isEnabledFor(TRACE_LOG_LEVEL))
326 logger.forcedLog(TRACE_LOG_LEVEL, LOG4CPLUS_TEXT("EXIT: ") + msg, file, line);
327 }
328
329 private:
330 Logger logger;
331 log4cplus::tstring msg;
332 const char* file;
333 int line;
334 };
335
336 } // end namespace log4cplus
337
338
339 #endif // _LOG4CPLUS_LOGGERHEADER_
syntax highlighted by Code2HTML, v. 0.9.1