1Config::DOMConfiguratorU(s3e)r Contributed Perl DocumentaCtoinofnig::DOMConfigurator(3)
2
6 Log::Log4perl::Config::DOMConfigurator - reads xml config files
7
9 --------------------------
10 --using the log4j DTD--
11 --------------------------
12 <?xml version="1.0" encoding="UTF-8"?>
14 <!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
15 <log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
17 <appender name="FileAppndr1" class="org.apache.log4j.FileAppender">
19 <layout class="Log::Log4perl::Layout::PatternLayout">
20 <param name="ConversionPattern"
21 value="%d %4r [%t] %-5p %c %t - %m%n"/>
22 </layout>
23 <param name="File" value="t/tmp/DOMtest"/>
24 <param name="Append" value="false"/>
25 </appender>
26 <category name="a.b.c.d" additivity="false">
28 <level value="warn"/> <!-- note lowercase! -->
29 <appender-ref ref="FileAppndr1"/>
30 </category>
31 <root>
33 <priority value="warn"/>
34 <appender-ref ref="FileAppndr1"/>
35 </root>
36 </log4j:configuration>
38 --------------------------
42 --using the log4perl DTD--
43 --------------------------
44 <?xml version="1.0" encoding="UTF-8"?>
46 <!DOCTYPE log4perl:configuration SYSTEM "log4perl.dtd">
47 <log4perl:configuration xmlns:log4perl="http://log4perl.sourceforge.net/"
49 threshold="debug" oneMessagePerAppender="true">
50 <log4perl:appender name="jabbender" class="Log::Dispatch::Jabber">
52 <param-nested name="login">
54 <param name="hostname" value="a.jabber.server"/>
55 <param name="password" value="12345"/>
56 <param name="port" value="5222"/>
57 <param name="resource" value="logger"/>
58 <param name="username" value="bobjones"/>
59 </param-nested>
60 <param name="to" value="bob@a.jabber.server"/>
62 <param-text name="to">
64 mary@another.jabber.server
65 </param-text>
66 <log4perl:layout class="org.apache.log4j.PatternLayout">
68 <param name="ConversionPattern" value = "%K xx %G %U"/>
69 <cspec name="K">
70 sub { return sprintf "%1x", $$}
71 </cspec>
72 <cspec name="G">
73 sub {return 'thisistheGcspec'}
74 </cspec>
75 </log4perl:layout>
76 </log4perl:appender>
77 <log4perl:appender name="DBAppndr2" class="Log::Log4perl::Appender::DBI">
79 <param name="warp_message" value="0"/>
80 <param name="datasource" value="DBI:CSV:f_dir=t/tmp"/>
81 <param name="bufferSize" value="2"/>
82 <param name="password" value="sub { $ENV{PWD} }"/>
83 <param name="username" value="bobjones"/>
84 <param-text name="sql">
86 INSERT INTO log4perltest
87 (loglevel, message, shortcaller, thingid,
88 category, pkg, runtime1, runtime2)
89 VALUES
90 (?,?,?,?,?,?,?,?)
91 </param-text>
92 <param-nested name="params">
94 <param name="1" value="%p"/>
95 <param name="3" value="%5.5l"/>
96 <param name="5" value="%c"/>
97 <param name="6" value="%C"/>
98 </param-nested>
99 <layout class="Log::Log4perl::Layout::NoopLayout"/>
101 </log4perl:appender>
102 <category name="animal.dog">
104 <priority value="info"/>
105 <appender-ref ref="jabbender"/>
106 <appender-ref ref="DBAppndr2"/>
107 </category>
108 <category name="plant">
110 <priority value="debug"/>
111 <appender-ref ref="DBAppndr2"/>
112 </category>
113 <PatternLayout>
115 <cspec name="U"><![CDATA[
116 sub {
117 return "UID $< GID $(";
118 }
119 ]]></cspec>
120 </PatternLayout>
121 </log4perl:configuration>
123
125 This module implements an XML config, complementing the properties-
126 style config described elsewhere.
127
129 "Why would I want my config in XML?" you ask. Well, there are a couple
130 reasons you might want to. Maybe you have a personal preference for
131 XML. Maybe you manage your config with other tools that have an
132 affinity for XML, like XML-aware editors or automated config
133 generators. Or maybe (and this is the big one) you don't like having
134 to run your application just to check the syntax of your config file.
135 By using an XML config and referencing a DTD, you can use a namespace-
137 aware validating parser to see if your XML config at least follows the
138 rules set in the DTD.
139
141 To reference a DTD, drop this in after the <?xml...> declaration in
142 your config file:
143 <!DOCTYPE log4perl:configuration SYSTEM "log4perl.dtd">
145 That tells the parser to validate your config against the DTD in
147 "log4perl.dtd", which is available in the xml/ directory of the
148 log4perl distribution. Note that you'll also need to grab the
149 log4j-1.2.dtd from there as well, since the it's included by
150 log4perl.dtd.
151 Namespace-aware validating parsers are not the norm in Perl. But the
153 Xerces project (http://xml.apache.org/xerces-c/index.html --lots of
154 binaries available, even rpm's) does provide just such a parser that
155 you can use like this:
156 StdInParse -ns -v < my-log4perl-config.xml
158 This module itself does not use a validating parser, the obvious one
160 XML::DOM::ValParser doesn't seem to handle namespaces.
161
163 The log4j DTD is from the log4j project, they designed it to handle
164 their needs. log4perl has added some extensions to the original log4j
165 functionality which needed some extensions to the log4j DTD. If you
166 aren't using these features then you can validate your config against
167 the log4j dtd and know that you're using unadulterated log4j config
168 tags.
169 The features added by the log4perl dtd are:
171 1 oneMessagePerAppender global setting
173 log4perl.oneMessagePerAppender=1
174 2 globally defined user conversion specifiers
176 log4perl.PatternLayout.cspec.G=sub { return "UID $< GID $("; }
177 3 appender-local custom conversion specifiers
179 log4j.appender.appndr1.layout.cspec.K = sub {return sprintf "%1x", $$ }
180 4 nested options
182 log4j.appender.jabbender = Log::Dispatch::Jabber
183 #(note how these are nested under 'login')
184 log4j.appender.jabbender.login.hostname = a.jabber.server
185 log4j.appender.jabbender.login.port = 5222
186 log4j.appender.jabbender.login.username = bobjones
187 5 the log4perl-specific filters, see Log::Log4perl::Filter, lots of
189 examples in t/044XML-Filter.t, here's a short one:
190 <?xml version="1.0" encoding="UTF-8"?>
191 <!DOCTYPE log4perl:configuration SYSTEM "log4perl.dtd">
192 <log4perl:configuration xmlns:log4perl="http://log4perl.sourceforge.net/">
194 <appender name="A1" class="Log::Log4perl::Appender::TestBuffer">
196 <layout class="Log::Log4perl::Layout::SimpleLayout"/>
197 <filter class="Log::Log4perl::Filter::Boolean">
198 <param name="logic" value="!Match3 && (Match1 || Match2)"/>
199 </filter>
200 </appender>
201 <appender name="A2" class="Log::Log4perl::Appender::TestBuffer">
203 <layout class="Log::Log4perl::Layout::SimpleLayout"/>
204 <filter-ref id="Match1"/>
205 </appender>
206 <log4perl:filter name="Match1" value="sub { /let this through/ }" />
208 <log4perl:filter name="Match2">
210 sub {
211 /and that, too/
212 }
213 </log4perl:filter>
214 <log4perl:filter name="Match3" class="Log::Log4perl::Filter::StringMatch">
216 <param name="StringToMatch" value="suppress"/>
217 <param name="AcceptOnMatch" value="true"/>
218 </log4perl:filter>
219 <log4perl:filter name="MyBoolean" class="Log::Log4perl::Filter::Boolean">
221 <param name="logic" value="!Match3 && (Match1 || Match2)"/>
222 </log4perl:filter>
223 <root>
226 <priority value="info"/>
227 <appender-ref ref="A1"/>
228 </root>
229 </log4perl:configuration>
231 So we needed to extend the log4j dtd to cover these additions. Now I
233 could have just taken a 'steal this code' approach and mixed parts of
234 the log4j dtd into a log4perl dtd, but that would be cut-n-paste
235 programming. So I've used namespaces and
236 • replaced three elements:
238 <log4perl:configuration>
240 handles #1) and accepts <PatternLayout>
241 <log4perl:appender>
243 accepts <param-nested> and <param-text>
244 <log4perl:layout>
246 accepts custom cspecs for #3)
247 • added a <param-nested> element (complementing the <param> element)
249 to handle #4)
250 • added a root <PatternLayout> element to handle #2)
252 • added <param-text> which lets you put things like perl code
254 into escaped CDATA between the tags, so you don't have to worry
255 about escaping characters and quotes
256 • added <cspec>
258 See the examples up in the "SYNOPSIS" for how all that gets used.
260
262 I liked the idea of using the log4j DTD in situ, so I used namespaces
263 to extend it. If you really don't like having to type
264 <log4perl:appender> instead of just <appender>, you can make your own
265 DTD combining the two DTDs and getting rid of the namespace prefixes.
266 Then you can validate against that, and log4perl should accept it just
267 fine.
268
270 This supports variable substitution like "${foobar}" in text and in
271 attribute values except for appender-ref. If an environment variable
272 is defined for that name, its value is substituted. So you can do stuff
273 like
274 <param name="${hostname}" value="${hostnameval}.foo.com"/>
276 <param-text name="to">${currentsysadmin}@foo.com</param-text>
277
279 To use this module you need XML::DOM installed.
280 To use the log4perl.dtd, you'll have to reference it in your XML
282 config, and you'll also need to note that log4perl.dtd references the
283 log4j dtd as "log4j-1.2.dtd", so your validator needs to be able to
284 find that file as well. If you don't like having to schlep two files
285 around, feel free to dump the contents of "log4j-1.2.dtd" into your
286 "log4perl.dtd" file.
287
289 You can't mix a multiple param-nesteds with the same name, I'm going to
290 leave that for now, there's presently no need for a list of structs in
291 the config.
292
294 0.03 2/26/2003 Added support for log4perl extensions to the log4j dtd
295
297 t/038XML-DOM1.t, t/039XML-DOM2.t for examples
298 xml/log4perl.dtd, xml/log4j-1.2.dtd
300 Log::Log4perl::Config
302 Log::Log4perl::Config::PropertyConfigurator
304 Log::Log4perl::Config::LDAPConfigurator (coming soon!)
306 The code is brazenly modeled on log4j's DOMConfigurator class, (by
308 Christopher Taylor, Ceki Gülcü, and Anders Kristensen) and any
309 perceived similarity is not coincidental.
310
312 Copyright 2002-2013 by Mike Schilli <m@perlmeister.com> and Kevin Goess
313 <cpan@goess.org>.
314 This library is free software; you can redistribute it and/or modify it
316 under the same terms as Perl itself.
317
319 Please contribute patches to the project on Github:
320 http://github.com/mschilli/log4perl
322 Send bug reports or requests for enhancements to the authors via our
324 MAILING LIST (questions, bug reports, suggestions/patches):
326 log4perl-devel@lists.sourceforge.net
327 Authors (please contact them via the list above, not directly): Mike
329 Schilli <m@perlmeister.com>, Kevin Goess <cpan@goess.org>
330 Contributors (in alphabetical order): Ateeq Altaf, Cory Bennett, Jens
332 Berthold, Jeremy Bopp, Hutton Davidson, Chris R. Donnelly, Matisse
333 Enzer, Hugh Esco, Anthony Foiani, James FitzGibbon, Carl Franks, Dennis
334 Gregorovic, Andy Grundman, Paul Harrington, Alexander Hartmaier David
335 Hull, Robert Jacobson, Jason Kohles, Jeff Macdonald, Markus Peter,
336 Brett Rann, Peter Rabbitson, Erik Selberg, Aaron Straup Cope, Lars
337 Thegler, David Viner, Mac Yang.
338perl v5.36.0 2023-01-20 Config::DOMConfigurator(3)