NAME¶
Log::Log4perl::Config::DOMConfigurator - reads xml config files
SYNOPSIS¶
--------------------------
--using the log4j DTD--
--------------------------
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
<appender name="FileAppndr1" class="org.apache.log4j.FileAppender">
<layout class="Log::Log4perl::Layout::PatternLayout">
<param name="ConversionPattern"
value="%d %4r [%t] %-5p %c %t - %m%n"/>
</layout>
<param name="File" value="t/tmp/DOMtest"/>
<param name="Append" value="false"/>
</appender>
<category name="a.b.c.d" additivity="false">
<level value="warn"/> <!-- note lowercase! -->
<appender-ref ref="FileAppndr1"/>
</category>
<root>
<priority value="warn"/>
<appender-ref ref="FileAppndr1"/>
</root>
</log4j:configuration>
--------------------------
--using the log4perl DTD--
--------------------------
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4perl:configuration SYSTEM "log4perl.dtd">
<log4perl:configuration xmlns:log4perl="http://log4perl.sourceforge.net/"
threshold="debug" oneMessagePerAppender="true">
<log4perl:appender name="jabbender" class="Log::Dispatch::Jabber">
<param-nested name="login">
<param name="hostname" value="a.jabber.server"/>
<param name="password" value="12345"/>
<param name="port" value="5222"/>
<param name="resource" value="logger"/>
<param name="username" value="bobjones"/>
</param-nested>
<param name="to" value="bob@a.jabber.server"/>
<param-text name="to">
mary@another.jabber.server
</param-text>
<log4perl:layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value = "%K xx %G %U"/>
<cspec name="K">
sub { return sprintf "%1x", $$}
</cspec>
<cspec name="G">
sub {return 'thisistheGcspec'}
</cspec>
</log4perl:layout>
</log4perl:appender>
<log4perl:appender name="DBAppndr2" class="Log::Log4perl::Appender::DBI">
<param name="warp_message" value="0"/>
<param name="datasource" value="DBI:CSV:f_dir=t/tmp"/>
<param name="bufferSize" value="2"/>
<param name="password" value="sub { $ENV{PWD} }"/>
<param name="username" value="bobjones"/>
<param-text name="sql">
INSERT INTO log4perltest
(loglevel, message, shortcaller, thingid,
category, pkg, runtime1, runtime2)
VALUES
(?,?,?,?,?,?,?,?)
</param-text>
<param-nested name="params">
<param name="1" value="%p"/>
<param name="3" value="%5.5l"/>
<param name="5" value="%c"/>
<param name="6" value="%C"/>
</param-nested>
<layout class="Log::Log4perl::Layout::NoopLayout"/>
</log4perl:appender>
<category name="animal.dog">
<priority value="info"/>
<appender-ref ref="jabbender"/>
<appender-ref ref="DBAppndr2"/>
</category>
<category name="plant">
<priority value="debug"/>
<appender-ref ref="DBAppndr2"/>
</category>
<PatternLayout>
<cspec name="U"><![CDATA[
sub {
return "UID $< GID $(";
}
]]></cspec>
</PatternLayout>
</log4perl:configuration>
DESCRIPTION¶
This module implements an XML config, complementing the properties-style config
described elsewhere.
WHY¶
"Why would I want my config in XML?" you ask. Well, there are a couple
reasons you might want to. Maybe you have a personal preference for XML. Maybe
you manage your config with other tools that have an affinity for XML, like
XML-aware editors or automated config generators. Or maybe (and this is the
big one) you don't like having to run your application just to check the
syntax of your config file.
By using an XML config and referencing a DTD, you can use a namespace-aware
validating parser to see if your XML config at least follows the rules set in
the DTD.
HOW¶
To reference a DTD, drop this in after the <?xml...> declaration in your
config file:
<!DOCTYPE log4perl:configuration SYSTEM "log4perl.dtd">
That tells the parser to validate your config against the DTD in
"log4perl.dtd", which is available in the xml/ directory of the
log4perl distribution. Note that you'll also need to grab the log4j-1.2.dtd
from there as well, since the it's included by log4perl.dtd.
Namespace-aware validating parsers are not the norm in Perl. But the Xerces
project (
http://xml.apache.org/xerces-c/index.html --lots of binaries
available, even rpm's) does provide just such a parser that you can use like
this:
StdInParse -ns -v < my-log4perl-config.xml
This module itself does not use a validating parser, the obvious one
XML::DOM::ValParser doesn't seem to handle namespaces.
WHY TWO DTDs¶
The log4j DTD is from the log4j project, they designed it to handle their needs.
log4perl has added some extensions to the original log4j functionality which
needed some extensions to the log4j DTD. If you aren't using these features
then you can validate your config against the log4j dtd and know that you're
using unadulterated log4j config tags.
The features added by the log4perl dtd are:
- 1 oneMessagePerAppender global setting
-
log4perl.oneMessagePerAppender=1
- 2 globally defined user conversion specifiers
-
log4perl.PatternLayout.cspec.G=sub { return "UID $< GID $("; }
- 3 appender-local custom conversion specifiers
-
log4j.appender.appndr1.layout.cspec.K = sub {return sprintf "%1x", $$ }
- 4 nested options
-
log4j.appender.jabbender = Log::Dispatch::Jabber
#(note how these are nested under 'login')
log4j.appender.jabbender.login.hostname = a.jabber.server
log4j.appender.jabbender.login.port = 5222
log4j.appender.jabbender.login.username = bobjones
- 5 the log4perl-specific filters, see Log::Log4perl::Filter,
lots of examples in t/044XML-Filter.t, here's a short one:
-
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4perl:configuration SYSTEM "log4perl.dtd">
<log4perl:configuration xmlns:log4perl="http://log4perl.sourceforge.net/">
<appender name="A1" class="Log::Log4perl::Appender::TestBuffer">
<layout class="Log::Log4perl::Layout::SimpleLayout"/>
<filter class="Log::Log4perl::Filter::Boolean">
<param name="logic" value="!Match3 && (Match1 || Match2)"/>
</filter>
</appender>
<appender name="A2" class="Log::Log4perl::Appender::TestBuffer">
<layout class="Log::Log4perl::Layout::SimpleLayout"/>
<filter-ref id="Match1"/>
</appender>
<log4perl:filter name="Match1" value="sub { /let this through/ }" />
<log4perl:filter name="Match2">
sub {
/and that, too/
}
</log4perl:filter>
<log4perl:filter name="Match3" class="Log::Log4perl::Filter::StringMatch">
<param name="StringToMatch" value="suppress"/>
<param name="AcceptOnMatch" value="true"/>
</log4perl:filter>
<log4perl:filter name="MyBoolean" class="Log::Log4perl::Filter::Boolean">
<param name="logic" value="!Match3 && (Match1 || Match2)"/>
</log4perl:filter>
<root>
<priority value="info"/>
<appender-ref ref="A1"/>
</root>
</log4perl:configuration>
So we needed to extend the log4j dtd to cover these additions. Now I could have
just taken a 'steal this code' approach and mixed parts of the log4j dtd into
a log4perl dtd, but that would be cut-n-paste programming. So I've used
namespaces and
- •
- replaced three elements:
- <log4perl:configuration>
- handles #1) and accepts <PatternLayout>
- <log4perl:appender>
- accepts <param-nested> and <param-text>
- <log4perl:layout>
- accepts custom cspecs for #3)
- •
- added a <param-nested> element (complementing the
<param> element)
to handle #4)
- •
- added a root <PatternLayout> element to handle
#2)
- •
- added <param-text> which lets you put things like
perl code
into escaped CDATA between the tags, so you don't have to worry
about escaping characters and quotes
- •
- added <cspec>
See the examples up in the "SYNOPSIS" for how all that gets used.
WHY NAMESPACES¶
I liked the idea of using the log4j DTD
in situ, so I used namespaces to
extend it. If you really don't like having to type <log4perl:appender>
instead of just <appender>, you can make your own DTD combining the two
DTDs and getting rid of the namespace prefixes. Then you can validate against
that, and log4perl should accept it just fine.
VARIABLE SUBSTITUTION¶
This supports variable substitution like "${foobar}" in text and in
attribute values except for appender-ref. If an environment variable is
defined for that name, its value is substituted. So you can do stuff like
<param name="${hostname}" value="${hostnameval}.foo.com"/>
<param-text name="to">${currentsysadmin}@foo.com</param-text>
REQUIRES¶
To use this module you need XML::DOM installed.
To use the log4perl.dtd, you'll have to reference it in your XML config, and
you'll also need to note that log4perl.dtd references the log4j dtd as
"log4j-1.2.dtd", so your validator needs to be able to find that
file as well. If you don't like having to schlep two files around, feel free
to dump the contents of "log4j-1.2.dtd" into your
"log4perl.dtd" file.
CAVEATS¶
You can't mix a multiple param-nesteds with the same name, I'm going to leave
that for now, there's presently no need for a list of structs in the config.
CHANGES¶
0.03 2/26/2003 Added support for log4perl extensions to the log4j dtd
SEE ALSO¶
t/038XML-DOM1.t, t/039XML-DOM2.t for examples
xml/log4perl.dtd, xml/log4j-1.2.dtd
Log::Log4perl::Config
Log::Log4perl::Config::PropertyConfigurator
Log::Log4perl::Config::LDAPConfigurator (coming soon!)
The code is brazenly modeled on log4j's DOMConfigurator class, (by Christopher
Taylor, Ceki GA~XlcA~X, and Anders Kristensen) and any perceived similarity is
not coincidental.
COPYRIGHT AND LICENSE¶
Copyright 2002-2009 by Mike Schilli <m@perlmeister.com> and Kevin Goess
<cpan@goess.org>.
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.