#################### main pod documentation begin ###################

=head1 NAME

  Zymonic::Client - Zymonic Webservice Client

=head1 SYNOPSIS

  my $zc = Zymonic::Client->new(URL => 'https://www.zymonic.com/zymonicmp/',
                                system => 'zymonic.test',   
                                credentials => {
                                  username => 'alex',
                                  password => 'password',
                                },
                               );
   
  my $r = $zc->sample_filter( 'filter', $filter_args );

Is a simple perl wrapper for connecting to remote Zymonic Systems
using Zymonic's native API.

=head1 DESCRIPTION

Is a simple perl wrapper for connecting to remote Zymonic Systems
using Zymonic's native API. Processes or filters from the remote
system can then be called by their ZName.

Whilst this is a module within the Zymonic namespace it does
not use any Zymonic modules, so it can be used in other projects
without the attribution license or having to install all of 
Zymonic.

=head1 USAGE

Load the object:

  my $zc = Zymonic::Client->new(URL => 'https://www.zymonic.com/zymonicmp/',
                                system => 'zymonic.test',   
                                credentials => {
                                  username => 'alex',
                                  password => 'password',
                                },
                               );

Call the Process or Filter by its ZName:

  my $r = $zc->sample_filter( 'filter', $filter_args );

The filter args should be constructed for processing by XML::Simple.
Likewise the response will be the Zymonic XML response processed by
XML::Simple.

=head1 BUGS

None we're aware of...

=head1 SUPPORT

As in the license, Zymonic is provided without warranty or support
unless purchased separately, however... If you email 
zymonic-support@zednax.com your issue will   be noted and may 
receive a response.

For security issues, please contact zymonic-security@zednax.com and
someone will respond within 8 working hours.


=head1 AUTHOR

    Alex Masidlover et al.
    CPAN ID: MODAUTHOR
    Zednax Limited
    alex.masidlover@zednax.com
    http://www.zednax.com

=head1 COPYRIGHT

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.10.0 or,
at your option, any later version of Perl 5 you may have available.

=head1 SEE ALSO

perl(1).

=cut

#################### main pod documentation end ###################

package Zymonic::Client;

use strict;
use warnings;

BEGIN
{
    use Exporter ();
    use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
    $VERSION = '0.01';
    @ISA     = qw(Exporter);

    #Give a hoot don't pollute, do not export more than needed by default
    @EXPORT      = qw();
    @EXPORT_OK   = qw();
    %EXPORT_TAGS = ();
}

use LWP::UserAgent;
use XML::Simple;

our $AUTOLOAD;

#################### subroutine header begin ####################

=head2 new

 Usage     :  my $zc = Zymonic::Client
                         ->new(URL => 
                                 'https://www.zymonic.com/zymonicmp/',
                                system => 'zymonic.test',   
                                credentials => {
                                  username => 'alex',
                                  password => 'password',
                                },
                               );
 Purpose   : This is the constructor for the Zymonic Client.
 Returns   : a Zymonic::Client object
 Argument  : expects a URL, a system name,
 timeout(optional) and authentication credentials.
 Throws    : nothing
 Comment   : 

See Also   : Zymonic::Client::init

=cut

#################### subroutine header end ####################

sub new
{
    my $invocant = shift;
    my $class    = ref($invocant) || $invocant;
    my $self     = {@_};                          # Remaining args become attributes

    bless $self, $class;

    $self->init;

    return $self;

}

#################### subroutine header begin ####################

=head2 init

 Usage     :  $zc->init
 Purpose   : This is called by the constructor for the Zymonic 
 Client to perform initialisation tasks.
 Returns   : nothing
 Argument  : nothing
 Throws    : nothing
 Comment   : 

See Also   : Zymonic::Client::new

=cut

#################### subroutine header end ####################

sub init
{
    my $self = shift;

    # Check that System, URL and authentication parameters have
    #Ębeen included.
    die "No system parameter set" unless $self->{system};
    die "No URL set"              unless $self->{URL};
    die "No Credentials provided" unless ref( $self->{credentials} ) eq 'HASH';

}

#################### subroutine header begin ####################

=head2 autoloader

 Usage     : my $value = $object->property($new_value);
 Purpose   : Provides method style access to the 
 Returns   : A hashref containing the response from the webservice
 Argument  : A type (process or filter), 
 A hashref of data to pass to the webservice
 Throws    : none
 Comment   : 
       : Methods that are all caps and don't exist in $self's definition
       : are special perl methods, like DESTROY, and shouldn't be handled
       : by the autolader.

See Also   :

=cut

#################### subroutine header end ####################

sub AUTOLOAD
{
    my $self       = shift;
    my $type       = shift;
    my $parameters = shift;

    my ($service) = ( $AUTOLOAD =~ /::(\w+)$/ );

    # Don't handle special methods
    # Methods that are all caps and don't exist in $self's definition
    # are spcial perl methods, like DESTROY, and shouldn't be handled
    # by the autolader.
    return if ( $service =~ /^[A-Z]*$/ );

    die "Type must be set to filter or process" unless $type and $type =~ /process|filter/;

    # Build XML to send
    my $xml = XMLout(
        {
            Authentication =>
              { map { $_ => { content => $self->{credentials}->{$_} } } keys( %{ $self->{credentials} } ) },
            ZymonicHeader => { system => { content => $self->{system} }, webservicemode => { content => $type } },
            $service      => $parameters,
        },
        KeyAttr  => [],
        RootName => "ZymonicRequest",
        NoEscape => 1
    );

    # POST to the service
    my $ua = LWP::UserAgent->new;
    $ua->timeout( $self->{timeout} || 10 );
    $ua->env_proxy;

    my $response = $ua->post( $self->{URL}, { xmldata => $xml } );

    if ( $response->is_success )
    {

        # Convert XML and return
        return XMLin( $response->content, ForceContent => 1 );
    }
    else
    {

        # Check for server errors...
        die $response->status_line;
    }

}

1;