=head1 NAME

ASNMTAP::Asnmtap::Plugins::XML is a Perl module that provides XML functions used by ASNMTAP-based plugins.

=head1 SYNOPSIS

  use ASNMTAP::Asnmtap::Plugins v3.002.002;
  use ASNMTAP::Asnmtap::Plugins qw(:PLUGINS);

  my $objectPlugins = ASNMTAP::Asnmtap::Plugins->new (
    _programName        => 'check_template-WebTransact-XML.pl',
    _programDescription => "WebTransact-XML plugin template for testing the '$APPLICATION'",
    _programVersion     => '3.002.002',
    _programGetOptions  => ['environment|e:s', 'proxy:s', 'timeout|t:i', 'trendline|T:i'],
    _timeout            => 30,
    _debug              => 0);

  use ASNMTAP::Asnmtap::Plugins::WebTransact;
  use ASNMTAP::Asnmtap::Plugins::XML qw(&extract_XML);

  my @URLS = ();
  my $objectWebTransact = ASNMTAP::Asnmtap::Plugins::WebTransact->new ( \$objectPlugins, \@URLS );

  $objectPlugins->pluginValue ('message', "WebTransact-XML plugin template for testing the '$APPLICATION'");

  use constant HEADER1 => '<?xml version="1.0" encoding="UTF-8" ?>';
  use constant FOOTER1 => '</testsuites>';

  use constant HEADER2 => '<?xml version="1.0" encoding="UTF-8"?>';
  use constant FOOTER2 => '</MonitoringXML>';

  my ($returnCode, $result, $xml);

  @URLS = (
    { Method => 'GET',  Url => 'http://asnmtap.citap.com/ServletTestRunner.xml', Qs_var => [], Qs_fixed => [], Exp => "\Q<testsuites>\E", Exp_Fault => ">>>NIHIL<<<", Msg => "ServletTestRunner.xml", Msg_Fault => "ServletTestRunner.xml" },
  );

  $returnCode = $objectWebTransact->check ( { } );
  undef $objectWebTransact;
  $objectPlugins->exit (7) if ( $returnCode );

  $result = $objectPlugins->pluginValue ('result');
  ($returnCode, $xml) = extract_XML ( asnmtapInherited => \$objectPlugins, resultXML => $result, headerXML => HEADER1, footerXML => FOOTER1 );
  $objectPlugins->exit (7) if ( $returnCode );

  if ( $xml->{testsuite}->{failures} + $xml->{testsuite}->{errors} ) {
    $objectPlugins->pluginValues ( { stateValue => $ERRORS{CRITICAL}, error => 'failures or errors' }, $TYPE{APPEND} );
    $objectPlugins->exit (7);
  }

  ($returnCode, $xml) = extract_XML ( asnmtapInherited => \$objectPlugins, filenameXML => 'xml/Monitoring-1.0.xml', headerXML => HEADER2, footerXML => FOOTER2, validateDTD => 1, filenameDTD => 'dtd/Monitoring-1.0.dtd' );
  $objectPlugins->exit (7) if ( $returnCode );

  if ( $xml->{Monitoring}->{Schema}->{Value} ne "1.0" ) {
    $objectPlugins->pluginValues ( { stateValue => $ERRORS{CRITICAL}, error => 'wrong schema' }, $TYPE{APPEND} );
    $objectPlugins->exit (7);
  }

  $objectPlugins->pluginValues ( { stateValue => ( $objectPlugins->pluginValue ('stateValue') == $ERRORS{DEPENDENT} ? $ERRORS{OK} : $objectPlugins->pluginValue ('stateValue') ), alert => 'XML validated' }, $TYPE{APPEND} );
  $objectPlugins->exit (7);

=head1 Description

=head2 XML::LibXML & XML::Simple based functions

=over 4

=item extract_XML()

Extract one XML from resultXML and/or filenameXML between the XML HEADER and XML FOOTER.

Returns a status for $returnCode (OK..UNKNOWN) and when the status is OK for $xml the extracted XML, otherwise undef.

  ($returnCode, $xml) = extract_XML ( asnmtapInherited => \$objectPlugins, resultXML => $result, headerXML => HEADER1, footerXML => FOOTER1 );
  ($returnCode, $xml) = extract_XML ( asnmtapInherited => \$objectPlugins, filenameXML => 'xml/Monitoring-1.0.xml', headerXML => HEADER2, footerXML => FOOTER2, validateDTD => 1, filenameDTD => 'dtd/Monitoring-1.0.dtd' );
  ($returnCode, $xml) = extract_XML ( asnmtapInherited => \$objectPlugins, resultXML => $result, filenameXML => 'xml/Monitoring-1.0.xml', headerXML => HEADER2, footerXML => FOOTER2, validateDTD => 1, filenameDTD => 'dtd/Monitoring-1.0.dtd' );

=over 4

=item asnmtapInherited

A required reference to an ASNMTAP::Asnmtap::Plugins or ASNMTAP::Asnmtap::Plugins::Nagios subclass

Through this way of working we inherited the command line option I<--debug>.

=item custom

optional, is an reference to your own custom defined function

$xml: the extracted XML

  sub actionOnExtractedXML {
    my ($asnmtapInherited, $xml) = @_;

    my $returnCode;

    if ( $xml->{Monitoring}->{Results}->{Details}->{Status} ) {
      $returnCode = $ERRORS{CRITICAL};
      $objectPlugins->pluginValues ( { stateValue => $returnCode, error => 'BAD LUCK' }, $TYPE{APPEND} );
    } else {
      $returnCode = $ERRORS{OK};
      $asnmtapInherited->pluginValues ( { stateValue => $returnCode, alert => 'XML validated' }, $TYPE{APPEND} );
    }

    return ($returnCode);
  }

and now with customArguments:

  sub actionOnExtractedXML {
    my ($asnmtapInherited, $xml, $arguments) = @_;
    return ($ERRORS{OK});
  }

=item customArguments

optional, when you need to pass parameters to your own custom defined function, this can be done with customArguments.

  customArguments: SCALAR, ARRAY, HASH,
                   REF SCALAR, REF ARRAY, REF HASH

=item resultXML

a string from where the XML need to be extracted.

resultXML and/or filenameXML are required

=item filenameXML

a filename from where the XML need to be extracted.

resultXML and/or filenameXML are required

=item headerXML

a required XML HEADER

  XML HEADER: <?xml version="1.0" encoding="UTF-8"?>

=item footerXML

a required XML FOOTER

  XML FOOTER: </MonitoringXML>

=item validateDTD

optional, validateDTD can be 0 or 1

  0, without DTD validation (default)
  1, with DTD validation 

=item filenameDTD

required when validateDTD is 1

=back

=back
				   
=head1 EXPORT

=head2 TAGS

=over 4

=item ALL

 &extract_XML

=back

=head1 AUTHOR

Alex Peeters [alex.peeters@citap.be]

=head1 SEE ALSO

ASNMTAP::Asnmtap, ASNMTAP::Asnmtap::Plugins, ASNMTAP::Asnmtap::Plugins::Nagios

  check_xml.pl
  check_xml-monitoring.pl

  check_template-XML.pl
  check_template-WebTransact-XML.pl
  check_template-WebTransact-XML-Cactus-parser.pl

=head1 DEPENDENCIES

  ASNMTAP::Asnmtap::Plugins
  Data::Dumper 
  XML::Parser
  XML::LibXML
  XML::Simple

=head1 COPYRIGHT NOTICE

(c) Copyright 2000-2010 by Alex Peeters [alex.peeters@citap.be],
                        All Rights Reserved.

ASNMTAP is based on 'Process System daemons v1.60.17-01', Alex Peeters [alex.peeters@citap.be]

 Purpose: CronTab (CT, sysdCT),
          Disk Filesystem monitoring (DF, sysdDF),
          Intrusion Detection for FW-1 (ID, sysdID)
          Process System daemons (PS, sysdPS),
          Reachability of Remote Hosts on a network (RH, sysdRH),
          Rotate Logfiles (system activity files) (RL),
          Remote Socket monitoring (RS, sysdRS),
          System Activity monitoring (SA, sysdSA).

'Process System daemons' is based on 'sysdaemon 1.60' written by Trans-Euro I.T Ltd

=head1 LICENSE

This ASNMTAP CPAN library and Plugin templates are free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The other parts of ASNMTAP may be used and modified free of charge by anyone so long as this copyright notice and the comments above remain intact. By using this code you agree to indemnify Alex Peeters from any liability that might arise from it's use.

Selling the code for this program without prior written consent is expressly forbidden. In other words, please ask first before you try and make money off of my program.

Obtain permission before redistributing this software over the Internet or in any other medium. In all cases copyright and header must remain intact.

=cut
