1 // Module: Log4CPLUS
2 // File: configurator.h
3 // Created: 3/2003
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
16 #ifndef _CONFIGURATOR_HEADER_
17 #define _CONFIGURATOR_HEADER_
18
19 #include <log4cplus/config.h>
20 #include <log4cplus/appender.h>
21 #include <log4cplus/hierarchy.h>
22 #include <log4cplus/logger.h>
23 #include <log4cplus/helpers/logloguser.h>
24 #include <log4cplus/helpers/pointer.h>
25 #include <log4cplus/helpers/property.h>
26
27 #include <map>
28
29
30 namespace log4cplus {
31
32 /**
33 * Provides configuration from an external file. See configure() for
34 * the expected format.
35 *
36 * <p><em>All option values admit variable substitution.</em> For
37 * example, if <code>userhome</code> environment property is set to
38 * <code>/home/xyz</code> and the File option is set to the string
39 * <code>${userhome}/test.log</code>, then File option will be
40 * interpreted as the string <code>/home/xyz/test.log</code>.
41 *
42 * <p>The syntax of variable substitution is similar to that of UNIX
43 * shells. The string between an opening <b>"${"</b> and
44 * closing <b>"}"</b> is interpreted as a key. Its value is
45 * searched in the environment properties. The corresponding value replaces
46 * the ${variableName} sequence.
47 */
48 class LOG4CPLUS_EXPORT PropertyConfigurator : protected log4cplus::helpers::LogLogUser
49 {
50 public:
51 // ctor and dtor
52 PropertyConfigurator(const log4cplus::tstring& propertyFile,
53 Hierarchy& h = Logger::getDefaultHierarchy());
54 PropertyConfigurator(const log4cplus::helpers::Properties& props,
55 Hierarchy& h = Logger::getDefaultHierarchy());
56 PropertyConfigurator(log4cplus::tistream& propertyStream,
57 Hierarchy& h = Logger::getDefaultHierarchy());
58 virtual ~PropertyConfigurator();
59
60 /**
61 * This method eliminates the need to create a temporary
62 * <code>PropertyConfigurator</code> to configure log4cplus.
63 * It is equivalent to the following:<br>
64 * <code>
65 * PropertyConfigurator config("filename");
66 * config.configure();
67 * </code>
68 */
69 static void doConfigure(const log4cplus::tstring& configFilename,
70 Hierarchy& h = Logger::getDefaultHierarchy());
71
72 /**
73 * Read configuration from a file. <b>The existing configuration is
74 * not cleared nor reset.</b> If you require a different behavior,
75 * then call {@link BasicConfigurator#resetConfiguration
76 * resetConfiguration} method before calling
77 * <code>doConfigure</code>.
78 *
79 * <p>The configuration file consists of statements in the format
80 * <code>key=value</code>. The syntax of different configuration
81 * elements are discussed below.
82 *
83 * <h3>Appender configuration</h3>
84 *
85 * <p>Appender configuration syntax is:
86 * <pre>
87 * # For appender named <i>appenderName</i>, set its class.
88 * # Note: The appender name can contain dots.
89 * log4cplus.appender.appenderName=fully.qualified.name.of.appender.class
90 *
91 * # Set appender specific options.
92 * log4cplus.appender.appenderName.option1=value1
93 * ...
94 * log4cplus.appender.appenderName.optionN=valueN
95 * </pre>
96 *
97 * For each named appender you can configure its {@link Layout}. The
98 * syntax for configuring an appender's layout is:
99 * <pre>
100 * log4cplus.appender.appenderName.layout=fully.qualified.name.of.layout.class
101 * log4cplus.appender.appenderName.layout.option1=value1
102 * ....
103 * log4cplus.appender.appenderName.layout.optionN=valueN
104 * </pre>
105 *
106 * <h3>Configuring loggers</h3>
107 *
108 * <p>The syntax for configuring the root logger is:
109 * <pre>
110 * log4cplus.rootLogger=[LogLevel], appenderName, appenderName, ...
111 * </pre>
112 *
113 * <p>This syntax means that an optional <em>LogLevel value</em> can
114 * be supplied followed by appender names separated by commas.
115 *
116 * <p>The LogLevel value can consist of the string values FATAL,
117 * ERROR, WARN, INFO, DEBUG or a <em>custom LogLevel</em> value.
118 *
119 * <p>If a LogLevel value is specified, then the root LogLevel is set
120 * to the corresponding LogLevel. If no LogLevel value is specified,
121 * then the root LogLevel remains untouched.
122 *
123 * <p>The root logger can be assigned multiple appenders.
124 *
125 * <p>Each <i>appenderName</i> (separated by commas) will be added to
126 * the root logger. The named appender is defined using the
127 * appender syntax defined above.
128 *
129 * <p>For non-root loggers the syntax is almost the same:
130 * <pre>
131 * log4cplus.logger.logger_name=[LogLevel|INHERITED], appenderName, appenderName, ...
132 * </pre>
133 *
134 * <p>The meaning of the optional LogLevel value is discussed above
135 * in relation to the root logger. In addition however, the value
136 * INHERITED can be specified meaning that the named logger should
137 * inherit its LogLevel from the logger hierarchy.
138 *
139 * <p>By default loggers inherit their LogLevel from the
140 * hierarchy. However, if you set the LogLevel of a logger and
141 * later decide that that logger should inherit its LogLevel, then
142 * you should specify INHERITED as the value for the LogLevel value.
143 *
144 * <p>Similar to the root logger syntax, each <i>appenderName</i>
145 * (separated by commas) will be attached to the named logger.
146 *
147 * <p>See the <a href="../../../../manual.html#additivity">appender
148 * additivity rule</a> in the user manual for the meaning of the
149 * <code>additivity</code> flag.
150 *
151 * <p>The user can override any of the {@link
152 * Hierarchy#disable} family of methods by setting the a key
153 * "log4cplus.disableOverride" to <code>true</code> or any value other
154 * than false. As in <pre>log4cplus.disableOverride=true </pre>
155 *
156 * <h3>Example</h3>
157 *
158 * <p>An example configuration is given below.
159 *
160 * <pre>
161 *
162 * # Set options for appender named "A1".
163 * # Appender "A1" will be a SyslogAppender
164 * log4cplus.appender.A1=log4cplus::SyslogAppender
165 *
166 * # The syslog daemon resides on www.abc.net
167 * log4cplus.appender.A1.SyslogHost=www.abc.net
168 *
169 * # A1's layout is a PatternLayout, using the conversion pattern
170 * # <b>%r %-5p %c{2} %M.%L %x - %m\n</b>. Thus, the log output will
171 * # include # the relative time since the start of the application in
172 * # milliseconds, followed by the LogLevel of the log request,
173 * # followed by the two rightmost components of the logger name,
174 * # followed by the callers method name, followed by the line number,
175 * # the nested disgnostic context and finally the message itself.
176 * # Refer to the documentation of {@link PatternLayout} for further information
177 * # on the syntax of the ConversionPattern key.
178 * log4cplus.appender.A1.layout=log4cplus::PatternLayout
179 * log4cplus.appender.A1.layout.ConversionPattern=%-4r %-5p %c{2} %M.%L %x - %m\n
180 *
181 * # Set options for appender named "A2"
182 * # A2 should be a RollingFileAppender, with maximum file size of 10 MB
183 * # using at most one backup file. A2's layout is TTCC, using the
184 * # ISO8061 date format with context printing enabled.
185 * log4cplus.appender.A2=log4cplus::RollingFileAppender
186 * log4cplus.appender.A2.MaxFileSize=10MB
187 * log4cplus.appender.A2.MaxBackupIndex=1
188 * log4cplus.appender.A2.layout=log4cplus::TTCCLayout
189 * log4cplus.appender.A2.layout.ContextPrinting=enabled
190 * log4cplus.appender.A2.layout.DateFormat=ISO8601
191 *
192 * # Root logger set to DEBUG using the A2 appender defined above.
193 * log4cplus.rootLogger=DEBUG, A2
194 *
195 * # Logger definitions:
196 * # The SECURITY logger inherits is LogLevel from root. However, it's output
197 * # will go to A1 appender defined above. It's additivity is non-cumulative.
198 * log4cplus.logger.SECURITY=INHERIT, A1
199 * log4cplus.additivity.SECURITY=false
200 *
201 * # Only warnings or above will be logged for the logger "SECURITY.access".
202 * # Output will go to A1.
203 * log4cplus.logger.SECURITY.access=WARN
204 *
205 *
206 * # The logger "class.of.the.day" inherits its LogLevel from the
207 * # logger hierarchy. Output will go to the appender's of the root
208 * # logger, A2 in this case.
209 * log4cplus.logger.class.of.the.day=INHERIT
210 * </pre>
211 *
212 * <p>Refer to the <b>setOption</b> method in each Appender and
213 * Layout for class specific options.
214 *
215 * <p>Use the <code>#</code> character at the beginning of a line for comments.
216 */
217 virtual void configure();
218
219 protected:
220 // Methods
221 void init(); // called by the ctor
222 void reconfigure();
223 void replaceEnvironVariables();
224 void configureLoggers();
225 void configureLogger(log4cplus::Logger logger, const log4cplus::tstring& config);
226 void configureAppenders();
227 void configureAdditivity();
228
229 virtual Logger getLogger(const log4cplus::tstring& name);
230 virtual void addAppender(Logger &logger, log4cplus::SharedAppenderPtr& appender);
231
232 // Types
233 typedef std::map<log4cplus::tstring, log4cplus::SharedAppenderPtr> AppenderMap;
234
235 // Data
236 Hierarchy& h;
237 log4cplus::tstring propertyFilename;
238 log4cplus::helpers::Properties properties;
239 AppenderMap appenders;
240
241 private:
242 // Disable copy
243 PropertyConfigurator(const PropertyConfigurator&);
244 PropertyConfigurator& operator=(PropertyConfigurator&);
245 };
246
247
248
249 /**
250 * Use this class to quickly configure the package. For file based
251 * configuration see PropertyConfigurator.
252 */
253 class LOG4CPLUS_EXPORT BasicConfigurator : public PropertyConfigurator {
254 public:
255 // ctor and dtor
256 BasicConfigurator(Hierarchy& h = Logger::getDefaultHierarchy());
257 virtual ~BasicConfigurator();
258
259 /**
260 * This method eliminates the need to create a temporary
261 * <code>BasicConfigurator</code> object to configure log4cplus.
262 * It is equivalent to the following:<br>
263 * <code>
264 * BasicConfigurator config();
265 * config.configure();
266 * </code>
267 */
268 static void doConfigure(Hierarchy& h = Logger::getDefaultHierarchy());
269
270 private:
271 // Disable copy
272 BasicConfigurator(const BasicConfigurator&);
273 BasicConfigurator& operator=(BasicConfigurator&);
274 };
275
276
277 #if !defined(LOG4CPLUS_SINGLE_THREADED)
278 // Forward Declarations
279 class ConfigurationWatchDogThread;
280
281
282 class LOG4CPLUS_EXPORT ConfigureAndWatchThread {
283 public:
284 // ctor and dtor
285 ConfigureAndWatchThread(const log4cplus::tstring& propertyFile,
286 unsigned int millis = 60 * 1000);
287 virtual ~ConfigureAndWatchThread();
288
289 private:
290 // Disallow copying of instances of this class
291 ConfigureAndWatchThread(const ConfigureAndWatchThread&);
292 ConfigureAndWatchThread& operator=(const ConfigureAndWatchThread&);
293
294 // Data
295 log4cplus::helpers::SharedObjectPtr<ConfigurationWatchDogThread> watchDogThread;
296 };
297 #endif
298
299 } // end namespace log4cplus
300
301 #endif // _CONFIGURATOR_HEADER_
syntax highlighted by Code2HTML, v. 0.9.1