1//
2// LoggingConfigurator.h
3//
4// Library: Util
5// Package: Configuration
6// Module: LoggingConfigurator
7//
8// Definition of the LoggingConfigurator class.
9//
10// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
11// and Contributors.
12//
13// SPDX-License-Identifier: BSL-1.0
14//
15
16
17#ifndef Util_LoggingConfigurator_INCLUDED
18#define Util_LoggingConfigurator_INCLUDED
19
20
21#include "Poco/Util/Util.h"
22#include "Poco/Formatter.h"
23#include "Poco/Channel.h"
24
25
26namespace Poco {
27namespace Util {
28
29
30class AbstractConfiguration;
31
32
33class Util_API LoggingConfigurator
34 /// This utility class uses a configuration object to configure the
35 /// logging subsystem of an application.
36 ///
37 /// The LoggingConfigurator sets up and connects formatters, channels
38 /// and loggers. To accomplish its work, the LoggingConfigurator relies on the
39 /// functionality provided by the LoggingFactory and LoggingRegistry classes.
40 ///
41 /// The LoggingConfigurator expects all configuration data to be under a root
42 /// property named "logging".
43 ///
44 /// Configuring Formatters
45 ///
46 /// A formatter is configured using the "logging.formatters" property. Every
47 /// formatter has an internal name, which is only used for referring to it
48 /// during configuration time. This name becomes part of the property name.
49 /// Every formatter has a mandatory "class" property, which specifies the actual
50 /// class implementing the formatter. Any other properties are passed on to
51 /// the formatter by calling its setProperty() method.
52 ///
53 /// A typical formatter definition looks as follows:
54 /// logging.formatters.f1.class = PatternFormatter
55 /// logging.formatters.f1.pattern = %s: [%p] %t
56 /// logging.formatters.f1.times = UTC
57 ///
58 /// Configuring Channels
59 ///
60 /// A channel is configured using the "logging.channels" property. Like with
61 /// Formatters, every channel has an internal name, which is used during
62 /// configuration only. The name becomes part of the property name.
63 /// Every channel has a mandatory "class" property, which specifies the actual
64 /// class implementing the channel. Any other properties are passed on to
65 /// the formatter by calling its setProperty() method.
66 ///
67 /// For convenience, the "formatter" property of a channel is treated
68 /// specifically. The "formatter" property can either be used to refer to
69 /// an already defined formatter, or it can be used to specify an "inline"
70 /// formatter definition. In either case, when a "formatter" property is
71 /// present, the channel is automatically "wrapped" in a FormattingChannel
72 /// object.
73 ///
74 /// Similarly, a channel supports also a "pattern" property, which results
75 /// in the automatic instantiation of a FormattingChannel object with a
76 /// connected PatternFormatter.
77 ///
78 /// Examples:
79 /// logging.channels.c1.class = ConsoleChannel
80 /// logging.channels.c1.formatter = f1
81 /// logging.channels.c2.class = FileChannel
82 /// logging.channels.c2.path = ${system.tempDir}/sample.log
83 /// logging.channels.c2.formatter.class = PatternFormatter
84 /// logging.channels.c2.formatter.pattern = %s: [%p] %t
85 /// logging.channels.c3.class = ConsoleChannel
86 /// logging.channels.c3.pattern = %s: [%p] %t
87 ///
88 /// Configuring Loggers
89 ///
90 /// A logger is configured using the "logging.loggers" property. Like with
91 /// channels and formatters, every logger has an internal name, which, however,
92 /// is only used to ensure the uniqueness of the property names. Note that this
93 /// name is different from the logger's full name, which is used to access
94 /// the logger at runtime.
95 /// Every logger except the root logger has a mandatory "name" property which
96 /// is used to specify the logger's full name.
97 /// Furthermore, a "channel" property is supported, which can either refer
98 /// to a named channel, or which can contain an inline channel definition.
99 ///
100 /// Examples:
101 /// logging.loggers.root.channel = c1
102 /// logging.loggers.root.level = warning
103 /// logging.loggers.l1.name = logger1
104 /// logging.loggers.l1.channel.class = ConsoleChannel
105 /// logging.loggers.l1.channel.pattern = %s: [%p] %t
106 /// logging.loggers.l1.level = information
107{
108public:
109 LoggingConfigurator();
110 /// Creates the LoggingConfigurator.
111
112 ~LoggingConfigurator();
113 /// Destroys the LoggingConfigurator.
114
115 void configure(AbstractConfiguration* pConfig);
116 /// Configures the logging subsystem based on
117 /// the given configuration.
118 ///
119 /// A ConfigurationView can be used to pass only
120 /// a part of a larger configuration.
121
122private:
123 void configureFormatters(AbstractConfiguration* pConfig);
124 void configureChannels(AbstractConfiguration* pConfig);
125 void configureLoggers(AbstractConfiguration* pConfig);
126 Poco::Formatter* createFormatter(AbstractConfiguration* pConfig);
127 Poco::Channel* createChannel(AbstractConfiguration* pConfig);
128 void configureChannel(Channel* pChannel, AbstractConfiguration* pConfig);
129 void configureLogger(AbstractConfiguration* pConfig);
130
131 LoggingConfigurator(const LoggingConfigurator&);
132 LoggingConfigurator& operator = (const LoggingConfigurator&);
133};
134
135
136} } // namespace Poco::Util
137
138
139#endif // Util_LoggingConfigurator_INCLUDED
140