import SOAP-WSDL 2.00.02 from CPAN
git-cpan-module: SOAP-WSDL git-cpan-version: 2.00.02 git-cpan-authorid: MKUTTER git-cpan-file: authors/id/M/MK/MKUTTER/SOAP-WSDL-2.00.02.tar.gz
This commit is contained in:
Martin Kutter
committed by
Michael G. Schwern
Michael G. Schwern
parent
745ce925c1
commit
915ee03cbe
@@ -0,0 +1,133 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
SOAP::WSDL::Manual::Cookbook - SOAP::WSDL recipes
|
||||
|
||||
=head2 Accessing HTTPS webservices
|
||||
|
||||
You need Crypt::SSLeay installed to access HTTPS webservices.
|
||||
|
||||
=head2 Accessing protected web services
|
||||
|
||||
Passing a username and password, or a client certificate and key, to the
|
||||
transport layer is highly dependent on the transport backend. The descriptions
|
||||
below are for HTTP(S) transport usingLWP::UserAgent
|
||||
|
||||
=head3 Accessing HTTP(S) webservices with basic/digest authentication
|
||||
|
||||
When using SOAP::WSDL::Transport::HTTP (SOAP::Lite not installed), add a
|
||||
method called "get_basic_credentials" to SOAP::WSDL::Transport::HTTP:
|
||||
|
||||
*SOAP::WSDL::Transport::HTTP::get_basic_credentials = sub {
|
||||
return ($user, $password);
|
||||
};
|
||||
|
||||
When using SOAP::Transport::HTTP (SOAP::Lite is installed), do the same to
|
||||
this backend:
|
||||
|
||||
*SOAP::Transport::HTTP::Client::get_basic_credentials = sub {
|
||||
return ($user, $password);
|
||||
};
|
||||
|
||||
=head3 Accessing HTTP(S) webservices protected by NTLM authentication
|
||||
|
||||
Besides passing user credentials as when accessing a web service protected
|
||||
by basic or digest authentication, you also need to enforce connection
|
||||
keep_alive on the transport backens.
|
||||
|
||||
To do so, pass a I<proxy> argument to the new() method of the generated
|
||||
class. This unfortunately means that you have to set the endpoint URL, too:
|
||||
|
||||
my $interface = MyInterfaces::SERVICE_NAME::PORT_NAME->new({
|
||||
proxy => [ $url, keep_alive => 1 ]
|
||||
});
|
||||
|
||||
You may, of course, decide to just hack the generated class. Be advised that
|
||||
subclassing might be a more appropriate solution - re-generating overwrites
|
||||
changes in interface classes.
|
||||
|
||||
=head3 Accessing HTTPS webservices protected by certificate authentication
|
||||
|
||||
You need Crypt::SSLeay installed to access HTTPS webservices.
|
||||
|
||||
See L<Crypt::SSLeay> on how to configure client certificate authentication.
|
||||
|
||||
=head1 XML OUTPUT
|
||||
|
||||
=head2 Outputting namespaces as prefixes
|
||||
|
||||
Q: I need to interface with a SOAP server which doesn't accept the following
|
||||
format:
|
||||
|
||||
<SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
|
||||
<SOAP-ENV:Body>
|
||||
<getElement xmlns="http://services.company.com/">
|
||||
<elementId>12345</elementId>
|
||||
</getElement>
|
||||
</SOAP-ENV:Body>
|
||||
</SOAP-ENV:Envelope>
|
||||
|
||||
Instead, it requires this:
|
||||
|
||||
<SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xmlns:ns2="http://services.company.com/"
|
||||
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
|
||||
<SOAP-ENV:Body>
|
||||
<ns2:getElement>
|
||||
<ns2:elementId>12345</ns2:elementId>
|
||||
</ns2:getElement>
|
||||
</SOAP-ENV:Body>
|
||||
</SOAP-ENV:Envelope>
|
||||
|
||||
How do I do this using SOAP::WSDL?
|
||||
|
||||
A: The following steps are neccessary to achieve this result:
|
||||
|
||||
First, you would need to write a new serializer, which is quite easy, as it
|
||||
just creates the envelope and calls ->serialize_qualified() on $header and
|
||||
$body to fill them in. The new serializer has to declare all namespace
|
||||
prefixes used, the rest is just the same as the original XSD serializer.
|
||||
|
||||
Second, you'd need to overwrite the start_tag method in
|
||||
L<SOAP::WSDL::XSD::Typelib::Element|SOAP::WSDL::XSD::Typelib::Element> to use
|
||||
the appropriate prefixes for the body elements.
|
||||
|
||||
In contrast to the original method, it would probably look up the appropriate
|
||||
prefix from some data set in the serializer class, so this could be the
|
||||
appropriate place to load SOAP::WSDL::XSD::Typelib::Element and override the
|
||||
method.
|
||||
|
||||
Something like this should do (without the handling of specialties like empty
|
||||
or nil elements):
|
||||
|
||||
%PREFIX_OF = { 'http://services.company.com/' => 'ns2' };
|
||||
|
||||
*SOAP::WSDL::XSD::Typelib::Element::start_tag = sub {
|
||||
# use prefix instead of xmlns attribute and copy the rest from
|
||||
# SOAP::WSDL::XSD::Typelib::Element::start_tag
|
||||
my $prefix = $PREFIX_OF{ $_[0]->get_xmlns() };
|
||||
my $name = $_[1]->{ name } || $self->__get_name();
|
||||
return "<$prefix:$name>";
|
||||
}
|
||||
|
||||
=head1 LICENSE AND COPYRIGHT
|
||||
|
||||
Copyright 2008 Martin Kutter.
|
||||
|
||||
This library is free software. You may distribute/modify it under
|
||||
the same terms as perl itself
|
||||
|
||||
=head1 AUTHOR
|
||||
|
||||
Martin Kutter E<lt>martin.kutter fen-net.deE<gt>
|
||||
|
||||
=head1 REPOSITORY INFORMATION
|
||||
|
||||
$Rev: 583 $
|
||||
$LastChangedBy: kutterma $
|
||||
$Id: $
|
||||
$HeadURL: $
|
||||
|
||||
=cut
|
||||
@@ -0,0 +1,152 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
SOAP::WSDL::Manual::FAQ - Frequently Asked Questions (and answers)
|
||||
|
||||
=head1 Development status
|
||||
|
||||
=head2 Can I use SOAP::WSDL in a production environment?
|
||||
|
||||
Yes. SOAP::WSDL is used in production environments. You should - as always -
|
||||
apply common sense and take appropriate safety measures, especially if
|
||||
running SOAP::WSDL as a server.
|
||||
|
||||
=head2 Can I throw the WSDL away after generating?
|
||||
|
||||
Please don't. Future versions of SOAP::WSDL may require you to re-generate
|
||||
interfaces in order to use them.
|
||||
|
||||
=head1 SOAP/WSDL Version and message styles
|
||||
|
||||
=head2 Which SOAP / WSDL versions does SOAP::WSDL support?
|
||||
|
||||
SOAP1.1 and WSDL1.1. SOAP1.2 and WSDL2 are not supported yet.
|
||||
|
||||
=head2 Which SOAP message Styles are supported?
|
||||
|
||||
document/literal.
|
||||
|
||||
The message / encoding styles rpc/encoded and rpc/literal are not supported
|
||||
(rpc/literal is hardly used).
|
||||
|
||||
rpc/literal is not implemented yet.
|
||||
|
||||
Unfortunately, SOAP::WSDL can't even parse many rpc/encoded WSDL definitions,
|
||||
and thus cannot inform you about unsupported message styles in some
|
||||
situations.
|
||||
|
||||
=head1 Aren't rpc variants bad anyway?
|
||||
|
||||
No. They can be as well-defined and useful as the document/literal variant.
|
||||
|
||||
The difference between rpc and document is that rpc SOAP messages have an
|
||||
additional container named after the remote procedure called.
|
||||
|
||||
rpc/literal is RPC with named parameters, whereas rpc/encoded corresponds to
|
||||
positional parameters.
|
||||
|
||||
rpc/encoded is prohibited by the WS-I Basic Profile. However, rpc/encoded
|
||||
is still popular, especially for scripting languages like perl, python or php.
|
||||
|
||||
You should probably use L<SOAP::Lite|SOAP::Lite> for rpc/encoded web services.
|
||||
|
||||
All the document/rpc literal/encoded discussion will cede with WSDL2.0: These
|
||||
variants are dropped in favour of an extensible operation style mechanism.
|
||||
|
||||
=head1 XML Parsing / Generation
|
||||
|
||||
=head2 Does SOAP::WSDL support namespaces?
|
||||
|
||||
Well, sort of. SOAP::WSDL can use WSDL definitions containing namespaces,
|
||||
and emits SOAP messages with namespace information.
|
||||
|
||||
Its SOAP message parser however, is not namespace sensitive but uses the
|
||||
pre-shared information from the WSDL for looking up what each XML node means.
|
||||
|
||||
SOAP::WSDL can parse SOAP messages including namespace informations up to the
|
||||
point where equally named elements from different namespaces may appear at
|
||||
the same position.
|
||||
|
||||
This is a long-standing feature request and will eventually be resolved.
|
||||
|
||||
=head2 Validation
|
||||
|
||||
=head3 Does SOAP::WSDL perform XML Schema Validation?
|
||||
|
||||
No, SOAP::WSDL does not perform XML Schema Validation. It does, however,
|
||||
enforce the correct structure on both XML and perl data. Occurrence, ordering,
|
||||
value-spaces, and identity constraints are not checked.
|
||||
|
||||
=head3 Does SOAP::WSDL perform XML Validation?
|
||||
|
||||
No, SOAP::WSDL does not perform XML Validation (that is, validation against
|
||||
a DTD). WS-I prohibits the use of DTDs in WSDL definitions.
|
||||
|
||||
=head3 Isn't validation required for XML?
|
||||
|
||||
No. The XML Specification does not require validation from XML processors.
|
||||
It states how validating and non-validating parsers must react on errors.
|
||||
|
||||
Note: Validation in the context of (only) XML actually means DTD validation.
|
||||
|
||||
=head3 And doesn't XML Schema require validation?
|
||||
|
||||
The XML Schema specification requires conformant XML Schema processors to
|
||||
be able to validate XML Schema constraints.
|
||||
|
||||
SOAP::WSDL is not a conformant XML Schema processor in this sense, as it does
|
||||
not validate all XML Schema constraints.
|
||||
|
||||
=head3 And does SOAP require XML Schema Validation?
|
||||
|
||||
No. The SOAP1.1 note does not say anything about validation. The SOAP1.2.
|
||||
specification explicitly states that XML Schema validation is not required
|
||||
for the SOAP envelope, and that applications may decide whether they need
|
||||
XML Schema Validation for the SOAP payload or not.
|
||||
|
||||
The WSDL 1.1. specification does not mandate XML Schema validation. It does
|
||||
actually not even mandate the use of XML Schema for type definitions.
|
||||
|
||||
=head2 Can SOAP::WSDL parse SOAP message fragments?
|
||||
|
||||
No. SOAP::WSDL can parse neither well-formed nor not-well-formed
|
||||
SOAP message chunks.
|
||||
|
||||
|
||||
=head1 Persistence
|
||||
|
||||
=head2 Can I use Storable to freeze/thaw SOAP::WSDL's objects?
|
||||
|
||||
You can freeze almost all of SOAP::WSDL's objects. The only exceptions are
|
||||
the objects used in parsing WSDL definitions itself - they cannot be frozen.
|
||||
|
||||
Note that freezing/thawing inside-out objects comes with a performance penalty
|
||||
and is at around the speed of XML generation/parsing.
|
||||
|
||||
=head1 Performance and memory consumption
|
||||
|
||||
=head2 How fast is SOAP::WSDL?
|
||||
|
||||
As of this writing, SOAP::WSDL is the fastest SOAP Client toolkit for perl
|
||||
available on CPAN. There are no published server benchmarks yet.
|
||||
|
||||
If you need extra speed you can try SOAP::WSDL_XS available
|
||||
from SOAP::WSDL's subversion repository at:
|
||||
|
||||
https://soap-wsdl.svn.sourceforge.net/svnroot/soap-wsdl/SOAP-WSDL_XS/trunk
|
||||
|
||||
Note however that SOAP::WSDL_XS is not very mature yet and only suitable for
|
||||
use in trusted environments - you definitely should not use it on a public
|
||||
internet SOAP server yet.
|
||||
|
||||
Note further that SOAP::WSDL's inside-out objects come with a big performance
|
||||
penalty when freezing/thawing them with Storable.
|
||||
|
||||
=head2 There's a lot of perl modules generated. Don't they eat up all my
|
||||
memory?
|
||||
|
||||
SOAP::WSDL usually uses a bit more memory than SOAP::Lite, but less than
|
||||
XML::Compile. Test if in question.
|
||||
|
||||
=cut
|
||||
@@ -93,7 +93,7 @@ Martin Kutter E<lt>martin.kutter fen-net.deE<gt>
|
||||
$Rev: 391 $
|
||||
$LastChangedBy: kutterma $
|
||||
$Id: Glossary.pod 391 2007-11-17 21:56:13Z kutterma $
|
||||
$HeadURL: http://soap-wsdl.svn.sourceforge.net/svnroot/soap-wsdl/SOAP-WSDL/trunk/lib/SOAP/WSDL/Manual/Glossary.pod $
|
||||
$HeadURL: https://soap-wsdl.svn.sourceforge.net/svnroot/soap-wsdl/SOAP-WSDL/trunk/lib/SOAP/WSDL/Manual/Glossary.pod $
|
||||
|
||||
=cut
|
||||
|
||||
|
||||
@@ -241,7 +241,7 @@ Martin Kutter E<lt>martin.kutter fen-net.deE<gt>
|
||||
$Rev: 391 $
|
||||
$LastChangedBy: kutterma $
|
||||
$Id: Parser.pod 391 2007-11-17 21:56:13Z kutterma $
|
||||
$HeadURL: http://soap-wsdl.svn.sourceforge.net/svnroot/soap-wsdl/SOAP-WSDL/trunk/lib/SOAP/WSDL/Manual/Parser.pod $
|
||||
$HeadURL: https://soap-wsdl.svn.sourceforge.net/svnroot/soap-wsdl/SOAP-WSDL/trunk/lib/SOAP/WSDL/Manual/Parser.pod $
|
||||
|
||||
=cut
|
||||
|
||||
|
||||
@@ -1255,7 +1255,7 @@ Martin Kutter E<lt>martin.kutter fen-net.deE<gt>
|
||||
$Rev: 562 $
|
||||
$LastChangedBy: kutterma $
|
||||
$Id: WS_I.pod 562 2008-02-22 20:32:17Z kutterma $
|
||||
$HeadURL: http://soap-wsdl.svn.sourceforge.net/svnroot/soap-wsdl/SOAP-WSDL/trunk/lib/SOAP/WSDL/Manual/WS_I.pod $
|
||||
$HeadURL: https://soap-wsdl.svn.sourceforge.net/svnroot/soap-wsdl/SOAP-WSDL/trunk/lib/SOAP/WSDL/Manual/WS_I.pod $
|
||||
|
||||
=cut
|
||||
|
||||
|
||||
Reference in New Issue
Block a user