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 --------------------------
40 --using the log4perl DTD--
41 --------------------------
42 <?xml version="1.0" encoding="UTF-8"?>
44 <!DOCTYPE log4perl:configuration SYSTEM "log4perl.dtd">
45 <log4perl:configuration xmlns:log4perl="http://log4perl.sourceforge.net/"
47 threshold="debug" oneMessagePerAppender="true">
48 <log4perl:appender name="jabbender" class="Log::Dispatch::Jabber">
50 <param-nested name="login">
52 <param name="hostname" value="a.jabber.server"/>
53 <param name="password" value="12345"/>
54 <param name="port" value="5222"/>
55 <param name="resource" value="logger"/>
56 <param name="username" value="bobjones"/>
57 </param-nested>
58 <param name="to" value="bob@a.jabber.server"/>
60 <param-text name="to">
62 mary@another.jabber.server
63 </param-text>
64 <log4perl:layout class="org.apache.log4j.PatternLayout">
66 <param name="ConversionPattern" value = "%K xx %G %U"/>
67 <cspec name="K">
68 sub { return sprintf "%1x", $$}
69 </cspec>
70 <cspec name="G">
71 sub {return 'thisistheGcspec'}
72 </cspec>
73 </log4perl:layout>
74 </log4perl:appender>
75 <log4perl:appender name="DBAppndr2" class="Log::Log4perl::Appender::DBI">
77 <param name="warp_message" value="0"/>
78 <param name="datasource" value="DBI:CSV:f_dir=t/tmp"/>
79 <param name="bufferSize" value="2"/>
80 <param name="password" value="sub { $ENV{PWD} }"/>
81 <param name="username" value="bobjones"/>
82 <param-text name="sql">
84 INSERT INTO log4perltest
85 (loglevel, message, shortcaller, thingid,
86 category, pkg, runtime1, runtime2)
87 VALUES
88 (?,?,?,?,?,?,?,?)
89 </param-text>
90 <param-nested name="params">
92 <param name="1" value="%p"/>
93 <param name="3" value="%5.5l"/>
94 <param name="5" value="%c"/>
95 <param name="6" value="%C"/>
96 </param-nested>
97 <layout class="Log::Log4perl::Layout::NoopLayout"/>
99 </log4perl:appender>
100 <category name="animal.dog">
102 <priority value="info"/>
103 <appender-ref ref="jabbender"/>
104 <appender-ref ref="DBAppndr2"/>
105 </category>
106 <category name="plant">
108 <priority value="debug"/>
109 <appender-ref ref="DBAppndr2"/>
110 </category>
111 <PatternLayout>
113 <cspec name="U"><![CDATA[
114 sub {
115 return "UID $< GID $(";
116 }
117 ]]></cspec>
118 </PatternLayout>
119 </log4perl:configuration>
121
123 This module implements an XML config, complementing the properties-
124 style config described elsewhere.
125
127 "Why would I want my config in XML?" you ask. Well, there are a couple
128 reasons you might want to. Maybe you have a personal preference for
129 XML. Maybe you manage your config with other tools that have an affin‐
130 ity for XML, like XML-aware editors or automated config generators. Or
131 maybe (and this is the big one) you don't like having to run your
132 application just to check the syntax of your config file.
133 By using an XML config and referencing a DTD, you can use a namespace-
135 aware validating parser to see if your XML config at least follows the
136 rules set in the DTD.
137
139 To reference a DTD, drop this in after the <?xml...> declaration in
140 your config file:
141 <!DOCTYPE log4perl:configuration SYSTEM "log4perl.dtd">
143 That tells the parser to validate your config against the DTD in
145 "log4perl.dtd", which is available in the xml/ directory of the
146 log4perl distribution. Note that you'll also need to grab the
147 log4j-1.2.dtd from there as well, since the it's included by
148 log4perl.dtd.
149 Namespace-aware validating parsers are not the norm in Perl. But the
151 Xerces project (http://xml.apache.org/xerces-c/index.html --lots of
152 binaries available, even rpm's) does provide just such a parser that
153 you can use like this:
154 StdInParse -ns -v < my-log4perl-config.xml
156 This module itself does not use a validating parser, the obvious one
158 XML::DOM::ValParser doesn't seem to handle namespaces.
159
161 The log4j DTD is from the log4j project, they designed it to handle
162 their needs. log4perl has added some extensions to the original log4j
163 functionality which needed some extensions to the log4j DTD. If you
164 aren't using these features then you can validate your config against
165 the log4j dtd and know that you're using unadulterated log4j config
166 tags.
167 The features added by the log4perl dtd are:
169 1 oneMessagePerAppender global setting
171 log4perl.oneMessagePerAppender=1
172 2 globally defined user conversion specifiers
174 log4perl.PatternLayout.cspec.G=sub { return "UID $< GID $("; }
175 3 appender-local custom conversion specifiers
177 log4j.appender.appndr1.layout.cspec.K = sub {return sprintf "%1x", $$ }
178 4 nested options
180 log4j.appender.jabbender = Log::Dispatch::Jabber
181 #(note how these are nested under 'login')
182 log4j.appender.jabbender.login.hostname = a.jabber.server
183 log4j.appender.jabbender.login.port = 5222
184 log4j.appender.jabbender.login.username = bobjones
185 5 the log4perl-specific filters, see Log::Log4perl::Filter, lots of
187 examples in t/044XML-Filter.t, here's a short one:
188 <?xml version="1.0" encoding="UTF-8"?>
189 <!DOCTYPE log4perl:configuration SYSTEM "log4perl.dtd">
190 <log4perl:configuration xmlns:log4perl="http://log4perl.sourceforge.net/">
192 <appender name="A1" class="Log::Log4perl::Appender::TestBuffer">
194 <layout class="Log::Log4perl::Layout::SimpleLayout"/>
195 <filter class="Log::Log4perl::Filter::Boolean">
196 <param name="logic" value="!Match3 && (Match1 ⎪⎪ Match2)"/>
197 </filter>
198 </appender>
199 <appender name="A2" class="Log::Log4perl::Appender::TestBuffer">
201 <layout class="Log::Log4perl::Layout::SimpleLayout"/>
202 <filter-ref id="Match1"/>
203 </appender>
204 <log4perl:filter name="Match1" value="sub { /let this through/ }" />
206 <log4perl:filter name="Match2">
208 sub {
209 /and that, too/
210 }
211 </log4perl:filter>
212 <log4perl:filter name="Match3" class="Log::Log4perl::Filter::StringMatch">
214 <param name="StringToMatch" value="suppress"/>
215 <param name="AcceptOnMatch" value="true"/>
216 </log4perl:filter>
217 <log4perl:filter name="MyBoolean" class="Log::Log4perl::Filter::Boolean">
219 <param name="logic" value="!Match3 && (Match1 ⎪⎪ Match2)"/>
220 </log4perl:filter>
221 <root>
223 <priority value="info"/>
224 <appender-ref ref="A1"/>
225 </root>
226 </log4perl:configuration>
228 So we needed to extend the log4j dtd to cover these additions. Now I
230 could have just taken a 'steal this code' approach and mixed parts of
231 the log4j dtd into a log4perl dtd, but that would be cut-n-paste pro‐
232 gramming. So I've used namespaces and
233 · replaced three elements:
235 <log4perl:configuration>
237 handles #1) and accepts <PatternLayout>
238 <log4perl:appender>
240 accepts <param-nested> and <param-text>
241 <log4perl:layout>
243 accepts custom cspecs for #3)
244 · added a <param-nested> element (complementing the <param> element)
246 to handle #4)
247 · added a root <PatternLayout> element to handle #2)
249 · added <param-text> which lets you put things like perl code
251 into escaped CDATA between the tags, so you don't have to worry
252 about escaping characters and quotes
253 · added <cspec>
255 See the examples up in the "SYNOPSIS" for how all that gets used.
257
259 I liked the idea of using the log4j DTD in situ, so I used namespaces
260 to extend it. If you really don't like having to type <log4perl:appen‐
261 der> instead of just <appender>, you can make your own DTD combining
262 the two DTDs and getting rid of the namespace prefixes. Then you can
263 validate against that, and log4perl should accept it just fine.
264
266 This supports variable substitution like "${foobar}" in text and in
267 attribute values except for appender-ref. If an environment variable
268 is defined for that name, its value is substituted. So you can do stuff
269 like
270 <param name="${hostname}" value="${hostnameval}.foo.com"/>
272 <param-text name="to">${currentsysadmin}@foo.com</param-text>
273
275 To use this module you need XML::DOM installed.
276 To use the log4perl.dtd, you'll have to reference it in your XML con‐
278 fig, and you'll also need to note that log4perl.dtd references the
279 log4j dtd as "log4j-1.2.dtd", so your validator needs to be able to
280 find that file as well. If you don't like having to schlep two files
281 around, feel free to dump the contents of "log4j-1.2.dtd" into your
282 "log4perl.dtd" file.
283
285 You can't mix a multiple param-nesteds with the same name, I'm going to
286 leave that for now, there's presently no need for a list of structs in
287 the config.
288
290 0.03 2/26/2003 Added support for log4perl extensions to the log4j dtd
291
293 t/038XML-DOM1.t, t/039XML-DOM2.t for examples
294 xml/log4perl.dtd, xml/log4j-1.2.dtd
296 Log::Log4perl::Config
298 Log::Log4perl::Config::PropertyConfigurator
300 Log::Log4perl::Config::LDAPConfigurator (coming soon!)
302
304 Kevin Goess, <cpan@goess.org> Jan-2003
305 The code is brazenly modeled on log4j's DOMConfigurator class, (by
307 Christopher Taylor, Ceki Gülcü, and Anders Kristensen) and any per‐
308 ceived similarity is not coincidental.
309perl v5.8.8 2002-07-10 Config::DOMConfigurator(3)