Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Config::DOMConfiguratoUser Contributed Perl DocumentConfig::DOMConfigurator(3)

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

       o   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)

       o   added a <param-nested> element (complementing the <param> element)
	       to handle #4)

       o   added a root	<PatternLayout>	element	to handle #2)

       o   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

       o   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	GA1/4lcA1/4, 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.

perl v5.32.0			  2020-07-22	    Config::DOMConfigurator(3)

NAME | SYNOPSIS | DESCRIPTION | WHY | HOW | WHY TWO DTDs | WHY NAMESPACES | VARIABLE SUBSTITUTION | REQUIRES | CAVEATS | CHANGES | SEE ALSO | LICENSE | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Log::Log4perl::Config::DOMConfigurator&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help