=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