Log::Log4perl::Layout::XMLLayout version 0.1
============================================

NAME
    Log::Log4perl::Layout::XMLLayout - XML Layout

SYNOPSIS
      use Log::Log4perl::Layout::XMLLayout;

      my $app = Log::Log4perl::Appender->new("Log::Log4perl::Appender::File");

      my $logger = Log::Log4perl->get_logger("abc.def.ghi");
      $logger->add_appender($app);

      # Log with LocationInfo
      my $layout = Log::Log4perl::Layout::XMLLayout->new(
        { LocationInfo => { value => 'TRUE' },
          Encoding     => { value => 'iso8859-1'}});
      
      $app->layout($layout);
      $logger->debug("That's the message");

      ########################### Log4perl Config File entries for XMLLayout
      log4perl.appender.A1.layout                   = Log::Log4perl::Layout::XMLLayout
      log4perl.appender.A1.layout.LocationInfo      = TRUE
      log4perl.appender.A1.layout.Encoding          =iso8859-1
      ###########################

DESCRIPTION
    Creates a XML layout according to
    http://jakarta.apache.org/log4j/docs/api/org/apache/log4j/xml/XMLLayout.
    html

    Logfiles generated based on XMLLayout can be viewed and filtered within
    the log4j chainsaw graphical user interface. chainsaw is part of the
    JAVA based log4j package and can be downloaded from
    http://jakarta.apache.org/

    The output of the XMLLayout consists of a series of log4j:event elements
    as defined in the log4j.dtd. It does not output a complete well-formed
    XML file. The output is designed to be included as an external entity in
    a separate file to form a correct XML file.

    For example, if abc is the name of the file where the XMLLayout ouput
    goes, then a well-formed XML file would be:

    <?xml version="1.0" ?>

    <!DOCTYPE log4j:eventSet SYSTEM "log4j.dtd" [<!ENTITY data SYSTEM
    "abc">]>

    <log4j:eventSet version="1.2"
    xmlns:log4j="http://jakarta.apache.org/log4j/"> &data; </log4j:eventSet>

    This approach enforces the independence of the XMLLayout and the
    appender where it is embedded.

    The version attribute helps components to correctly intrepret output
    generated by XMLLayout. The value of this attribute should be "1.1" for
    output generated by log4j versions prior to log4j 1.2 (final release)
    and "1.2" for relase 1.2 and later.

  Methods

    new()
    The "new()" method creates a XMLLayout object, specifying its log
    contents. NDC is explained in the section on "Nested Diagnostic Context
    (NDC)" in the Log::Log4perl manpage.

  Attributes

    LocationInfo
    If LocationInfo is set to TRUE, source code location info is added to
    each logging event.

    Encoding
    adds XML version and character encoding attributes to the log.

    Following line is generated only when the first logger call is done:

    <?xml version = "1.0" encoding = "iso8859-1"?>

  XML Document Type Definition

    <!ELEMENT log4j:eventSet (log4j:event*)>

    <!ATTLIST log4j:eventSet

      includesLocationInfo   (true|false) "true"
  
    >

    <!ELEMENT log4j:event (log4j:message, log4j:NDC?, log4j:throwable?,
    log4j:locationInfo?) >

    <!-- The timestamp format is application dependent. -->

    <!ATTLIST log4j:event

        logger     CDATA #REQUIRED
    
        priority   CDATA #REQUIRED
    
        thread     CDATA #REQUIRED
    
        timestamp  CDATA #REQUIRED
    
    >

    <!ELEMENT log4j:message (#PCDATA)>

    <!ELEMENT log4j:NDC (#PCDATA)>

    <!ELEMENT log4j:throwable (#PCDATA)>

    <!ELEMENT log4j:locationInfo EMPTY>

    <!ATTLIST log4j:locationInfo

      class  CDATA  #REQUIRED
  
      method CDATA  #REQUIRED
  
      file   CDATA  #REQUIRED
  
      line   CDATA  #REQUIRED
  
    >

INSTALLATION
    To install this module type the following:

       perl Makefile.PL
   
       make
   
       make test
   
       make install

KNOWN BUGS
    Some older versions of chainsaw use a different DTD. Consequently, these
    versions do not display log events generated via XMLLayout.

AUTHOR
            Guido Carls <gcarls@cpan.org>

COPYRIGHT AND LICENCE
    Copyright (C) 2003 G. Carls

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

SEE ALSO
    the Log::Log4perl manpage

