view release on metacpan or  search on metacpan

lib/SOAP/XML/Client.pm  view on Meta::CPAN

}

1;

__END__

=head1 NAME

SOAP::XML::Client - Simple frame work for talking with web services

=head1 DESCRIPTION

This package is the base class for talking with web services,
there are specific modules to use depending on the type
of service you are calling, e.g. C<SOAP::XML::Client::DotNet> or
C<SOAP::XML::Client::Generic>

This package helps in talking with web services, it just needs
a bit of XML thrown at it and you get some XML back.
It's designed to be REALLY simple to use.

=head1 SYNOPSIS

  See SOAP::XML::Client::DotNet or SOAP::XML::Client::Generic for usage example.

  If you are creating a child class you just need to
  impliment the actual _call() - see pod below.

=head1 METHODS

=head2 new()

  my $soap_client = SOAP::XML::Client::DotNet->new(
    {   uri   => 'http://www.yourdomain.com/services',
        proxy => 'http://www.yourproxy.com/services/services.asmx',
        xmlns => 'http://www.yourdomain.com/services',
        soapversion         => '1.1',    # defaults to 1.1
        timeout             => '30',     # defaults to 30 seconds
        strip_default_xmlns => 1,        # defaults to 1
        encoding => 'utf-8',    # defaults to 'utf-8' (see 'Encoding' below)
    }
  );


This constructor requires uri, proxy and xmlns to be
supplied, otherwise it will croak.

strip_default_xmlns is used to remove xmlns="http://.../"
from returned XML, it will NOT alter xmlns:FOO="http//.../"
set to '0' if you do not wish for this to happen.

To stop SOAP::Lite being overly keen to encode values as Base64, pass
in disable_base64:

   ...
     disable_base64 => 1,
   ...

=head2 header()

   my $header = SOAP::Header->name(
          SomeDomain => {
              Username => "a_user",
              Password => 'xxxxx',
          }
      )->uri('http://www.thedomain.com/')->prefix('');

    $soap_client->header($header);

Add a soap header to the soap call, probably useful if there is
credential based authenditcation

=head2 fetch()

  # Generate the required XML, this is the bit after the Method XML element
  # in the services.asmx descriptor for this method (see SOAP::XML::Client::DotNet SYNOPSIS).
  my $user_id = '900109';
  my $xml = "<userId _value_type='long'>$user_id</userId>";

  if($soap_client->fetch({ method => 'GetActivity', xml => $xml }) {
      # Get result as a string
      my $xml_string = $soap_client->results();

      # Get result as a XML::LibXML object
      my $xml_libxml_object = $soap_client->results_xml();

  } else {
      # There was some sort of error
      print $soap_client->error() . "\n";
      print "Status: " . $soap_client->status();
  }

This method actually calls the web service, it takes a method name
and an xml string. If there is a problem with either the XML or
the SOAP transport (e.g. web server error/could not connect etc)
undef will be returned and the error() will be set.

Each node in the XML supplied (either by string or from a filename)
needs to have _value_type defined or the submitted format will
default to 'string'.

You can supply 'filename' rather than 'xml' and it will read in from
the file.

We check for Fault/faultstring in the returned XML,
anything else you'll need to check for yourself.

=head2 error()

  $soap_client->error();

If fetch returns undef then check this method, it will either be that the filename you
supplied couldn't be read, the XML you supplied was not correctly formatted (XML::LibXML
could not parse it), there was a transport error with the web service or Fault/faultstring
was found in the XML returned.

=head2 status()

  $soap_client->status();

This is set to the http status after fetch has been called