NAME
SOAP::Lite::Simple - Simple frame work for talking with web services
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. <SOAP::Lite::Simple::DotNet> or <SOAP::Lite::Simple::Real>
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, it doesn't try to be cleaver in any way (patches for 'cleaverness' welcome).
SYNOPSIS
See SOAP::Lite::Simple::DotNet for usage example.
If you are creating a child class you just need to
impliment the actual _call();
package SOAP::Lite::Simple::<PACKAGE NAME>;
use base qw(SOAP::Lite::Simple);
sub _call {
my ($self,$method) = @_;
# Impliment it! - below is the code from Simple::DotNet
# This code is the .NET specific way of calling SOAP,
# it might work for other stuff as well
my $soap_action = sub {return $self->uri() . '/' . $method};
my $caller = $self->{soap}
->uri($self->uri())
->proxy($self->proxy(), timeout => $self->timeout())
->on_action( $soap_action );
$caller->soapversion($self->soapversion());
# Create a SOAP::Data node for the method name
my $method_name = SOAP::Data->name($method)->attr({'xmlns' => $self->xmlns()});
# Execute the SOAP Request and get the resulting XML
my $res = $caller->call( $method_name => $self->{sdb}->to_soap_data());
return $res;
}
1;
methods
new()
my $soap_simple->SOAP::Lite::Simple::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', # detauls to 30 seconds
strip_default_xmlns => 1, # defaults to 1
});
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.
fetch()
# Generate the required XML, this is the bit after the Method XML element
# in the services.asmx descriptor for this method (see Soap::Lite::Simple::DotNet SYNOPSIS).
my $user_id = '900109';
my $xml = "<userId _value_type='long'>$user_id</userId>";
if(my $xml_result = $soap_simple->fetch({ method => 'GetActivity', xml => $xml }) {
# You got some XML back
my $parser = XML::LibXML->new();
my $doc = $parser->parse_string($xml_result);
# now validate the XML is what you were expecting.
} else {
# There was some sort of error
print $soap_simple->error() . "\n";
}
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.
If all is successful the the XML string will be parsed back. This still has all the SOAP wrapper stuff on it, so you'll want to strip that out.
We check for Fault/faultstring in the returned XML, anything else you'll need to check for yourself.
error()
$self->error();
If fetch returns undef then check this method, it will either be that the XML you supplied was not correctly formatted and XML::LibXML could not parse it, there was a transport error with the web service or either soap:Fault and soapenv:Fault error messages were returned in the XML.
results();
my $results = $soap_simple->results();
Can be called after fetch() to get the raw XML, if fetch was sucessful.
results_xml();
my $results_as_xml = $soap_simple->results_xml();
Can be called after fetch() to get the XML::LibXML Document element of the returned xml, as long as fetch was sucessful.
HOW TO DEBUG
At the top of your script, before 'use SOAP::Lite::Simple::<TYPE>' add:
use SOAP::Lite ( +trace => 'all', readable => 1, outputxml => 1, );
It may or may not help, not all web services give you many helpful error messages! At least you can see what's being submitted and returned. It can be the smallest thing that causes a problem, mis-typed data (see _value_type in xml), or typo in xmlns line.
If the type of module (e.g. SOAP::Lite::Simple::DotNet) doesn't work, switch to one of the other ones and see if that helps.
SEE ALSO
<SOAP::Lite::Simple::DotNet> <SOAP::Lite::Simple::Real>
AUTHOR
Leo Lapworth <LLAP@cuckoo.org>
COPYRIGHT
(c) 2005 Leo Lapworth
This library is free software, you can use it under the same terms as perl itself.
THANKS
Thanks to Foxtons for letting me develope this on their time and to Aaron for his help with understanding SOAP a bit more and the London.pm list for ideas.