1Config::DOMConfiguratorU(s3e)r Contributed Perl DocumentaCtoinofnig::DOMConfigurator(3)
2
3
4

NAME

6       Log::Log4perl::Config::DOMConfigurator - reads xml config files
7

SYNOPSIS

9           --------------------------
10           --using the log4j DTD--
11           --------------------------
12
13           <?xml version="1.0" encoding="UTF-8"?>
14           <!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
15
16           <log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
17
18           <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
27           <category name="a.b.c.d" additivity="false">
28               <level value="warn"/>  <!-- note lowercase! -->
29               <appender-ref ref="FileAppndr1"/>
30           </category>
31
32          <root>
33               <priority value="warn"/>
34               <appender-ref ref="FileAppndr1"/>
35          </root>
36
37          </log4j:configuration>
38
39
40
41          --------------------------
42          --using the log4perl DTD--
43          --------------------------
44
45          <?xml version="1.0" encoding="UTF-8"?>
46           <!DOCTYPE log4perl:configuration SYSTEM "log4perl.dtd">
47
48           <log4perl:configuration xmlns:log4perl="http://log4perl.sourceforge.net/"
49               threshold="debug" oneMessagePerAppender="true">
50
51           <log4perl:appender name="jabbender" class="Log::Dispatch::Jabber">
52
53                   <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
61                   <param name="to" value="bob@a.jabber.server"/>
62
63                   <param-text name="to">
64                         mary@another.jabber.server
65                   </param-text>
66
67                   <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
78           <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
85                     <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
93                      <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
100                      <layout class="Log::Log4perl::Layout::NoopLayout"/>
101           </log4perl:appender>
102
103           <category name="animal.dog">
104                      <priority value="info"/>
105                      <appender-ref ref="jabbender"/>
106                      <appender-ref ref="DBAppndr2"/>
107           </category>
108
109           <category name="plant">
110                   <priority value="debug"/>
111                   <appender-ref ref="DBAppndr2"/>
112           </category>
113
114           <PatternLayout>
115               <cspec name="U"><![CDATA[
116                   sub {
117                       return "UID $< GID $(";
118                   }
119               ]]></cspec>
120           </PatternLayout>
121
122           </log4perl:configuration>
123

DESCRIPTION

125       This module implements an XML config, complementing the properties-
126       style config described elsewhere.
127

WHY

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
136       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

HOW

141       To reference a DTD, drop this in after the <?xml...> declaration in
142       your config file:
143
144           <!DOCTYPE log4perl:configuration SYSTEM "log4perl.dtd">
145
146       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
152       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
157           StdInParse -ns -v < my-log4perl-config.xml
158
159       This module itself does not use a validating parser, the obvious one
160       XML::DOM::ValParser doesn't seem to handle namespaces.
161

WHY TWO DTDs

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
170       The features added by the log4perl dtd are:
171
172       1 oneMessagePerAppender global setting
173               log4perl.oneMessagePerAppender=1
174
175       2 globally defined user conversion specifiers
176               log4perl.PatternLayout.cspec.G=sub { return "UID $< GID $("; }
177
178       3 appender-local custom conversion specifiers
179                log4j.appender.appndr1.layout.cspec.K = sub {return sprintf "%1x", $$ }
180
181       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
188       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
193             <log4perl:configuration xmlns:log4perl="http://log4perl.sourceforge.net/">
194
195             <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 &amp;&amp; (Match1 || Match2)"/>
199                   </filter>
200             </appender>
201
202             <appender name="A2" class="Log::Log4perl::Appender::TestBuffer">
203                   <layout class="Log::Log4perl::Layout::SimpleLayout"/>
204                   <filter-ref id="Match1"/>
205             </appender>
206
207             <log4perl:filter name="Match1" value="sub { /let this through/ }" />
208
209             <log4perl:filter name="Match2">
210                   sub {
211                       /and that, too/
212                   }
213              </log4perl:filter>
214
215             <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
220             <log4perl:filter name="MyBoolean" class="Log::Log4perl::Filter::Boolean">
221               <param name="logic" value="!Match3 &amp;&amp; (Match1 || Match2)"/>
222             </log4perl:filter>
223
224
225              <root>
226                      <priority value="info"/>
227                      <appender-ref ref="A1"/>
228              </root>
229
230              </log4perl:configuration>
231
232       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
237       •   replaced three elements:
238
239           <log4perl:configuration>
240               handles #1) and accepts <PatternLayout>
241
242           <log4perl:appender>
243               accepts <param-nested> and <param-text>
244
245           <log4perl:layout>
246               accepts custom cspecs for #3)
247
248       •   added a <param-nested> element (complementing the <param> element)
249               to handle #4)
250
251       •   added a root <PatternLayout> element to handle #2)
252
253       •   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
257       •   added <cspec>
258
259       See the examples up in the "SYNOPSIS" for how all that gets used.
260

WHY NAMESPACES

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

VARIABLE SUBSTITUTION

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
275               <param name="${hostname}" value="${hostnameval}.foo.com"/>
276               <param-text name="to">${currentsysadmin}@foo.com</param-text>
277

REQUIRES

279       To use this module you need XML::DOM installed.
280
281       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

CAVEATS

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

CHANGES

294       0.03 2/26/2003 Added support for log4perl extensions to the log4j dtd
295

SEE ALSO

297       t/038XML-DOM1.t, t/039XML-DOM2.t for examples
298
299       xml/log4perl.dtd, xml/log4j-1.2.dtd
300
301       Log::Log4perl::Config
302
303       Log::Log4perl::Config::PropertyConfigurator
304
305       Log::Log4perl::Config::LDAPConfigurator (coming soon!)
306
307       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

LICENSE

312       Copyright 2002-2013 by Mike Schilli <m@perlmeister.com> and Kevin Goess
313       <cpan@goess.org>.
314
315       This library is free software; you can redistribute it and/or modify it
316       under the same terms as Perl itself.
317

AUTHOR

319       Please contribute patches to the project on Github:
320
321           http://github.com/mschilli/log4perl
322
323       Send bug reports or requests for enhancements to the authors via our
324
325       MAILING LIST (questions, bug reports, suggestions/patches):
326       log4perl-devel@lists.sourceforge.net
327
328       Authors (please contact them via the list above, not directly): Mike
329       Schilli <m@perlmeister.com>, Kevin Goess <cpan@goess.org>
330
331       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.
338
339
340
341perl v5.36.0                      2023-01-20        Config::DOMConfigurator(3)
Impressum