# Log::Log4perl::Config::DOMConfigurator - phpMan

## 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 &amp;&amp; (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 &amp;&amp; (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 Gülcü, and Anders Kristensen) and any perceived
    similarity is not coincidental.

## LICENSE
    Copyright 2002-2013 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.

## AUTHOR
    Please contribute patches to the project on Github:

        <http://github.com/mschilli/log4perl>

    Send bug reports or requests for enhancements to the authors via our

    MAILING LIST (questions, bug reports, suggestions/patches):
    <log4perl-devel@lists.sourceforge.net>

    Authors (please contact them via the list above, not directly): Mike
    Schilli <<m@perlmeister.com>>, Kevin Goess <<cpan@goess.org>>

    Contributors (in alphabetical order): Ateeq Altaf, Cory Bennett, Jens
    Berthold, Jeremy Bopp, Hutton Davidson, Chris R. Donnelly, Matisse
    Enzer, Hugh Esco, Anthony Foiani, James FitzGibbon, Carl Franks, Dennis
    Gregorovic, Andy Grundman, Paul Harrington, Alexander Hartmaier David
    Hull, Robert Jacobson, Jason Kohles, Jeff Macdonald, Markus Peter, Brett
    Rann, Peter Rabbitson, Erik Selberg, Aaron Straup Cope, Lars Thegler,
    David Viner, Mac Yang.