.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SOAP::WSDL::Manual 3"
.TH SOAP::WSDL::Manual 3 "2010-10-06" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
SOAP::WSDL::Manual \- Accessing WSDL based web services
.SH "Accessing a WSDL-based web service"
.IX Header "Accessing a WSDL-based web service"
.SS "Quick walk-through for the unpatient"
.IX Subsection "Quick walk-through for the unpatient"
.IP "\(bu" 4
Create \s-1WSDL\s0 bindings
.Sp
.Vb 1
\&  perl wsdl2perl.pl \-b base_dir URL
.Ve
.IP "\(bu" 4
Look what has been generated
.Sp
Check the results of the generator. There should be one
MyInterfaces/SERVICE_NAME/PORT_NAME.pm file per port (and one directory per
service).
.IP "\(bu" 4
Write script
.Sp
.Vb 2
\& use MyInterfaces::SERVICE_NAME::PORT_NAME;
\& my $service = MyInterfaces::SERVICE_NAME::PORT_NAME\->new();
\&
\& my $result = $service\->SERVICE_METHOD();
\& die $result if not $result;
\&
\& print $result;
.Ve
.Sp
\&\f(CW\*(C`perldoc MyInterfaces::SERVICE_NAME::PORT_NAME\*(C'\fR should give you some overview
about the service's interface structure.
.Sp
The results of all calls to your service object's methods (except new) are
objects based on \s-1SOAP::WSDL\s0's \s-1XML\s0 schema implementation.
.Sp
To access the object's properties use get_NAME / set_NAME getter/setter
methods with \s-1NAME\s0 corresponding to the \s-1XML\s0 tag name / the hash structure as
showed in the generated pod.
.IP "\(bu" 4
Run script
.SS "Instrumenting web services with interface classes"
.IX Subsection "Instrumenting web services with interface classes"
\&\s-1SOAP::WSDL\s0 (starting from 2.00) instruments \s-1WSDL\s0 based web services with
interface classes. This means that \s-1SOAP::WSDL\s0 features a code generator
which creates one class for every web service you want to access.
.PP
Moreover, the data types from the \s-1WSDL\s0 definitions are also wrapped into
classes and returned to the user as objects.
.PP
To find out which class a particular \s-1XML\s0 node should be, \s-1SOAP::WSDL\s0 uses the
information built into type classes and interfaces.
.PP
Older versions of \s-1SOAP::WSDL\s0 used typemaps. For every Web service, a typemap
was created. Typemaps were dropped, as they don't allow recursive \s-1XML\s0 schema
declarations, eat up more memory and are slower. Old interfaces using typemaps
are still supported, but you're encouraged to re-generate your interfaces.
.SS "Interface class creation"
.IX Subsection "Interface class creation"
To create interface classes, follow the steps above from
Quick walk-through for the unpatient.
.PP
If this works fine for you, skip the next paragraphs. If not, read on.
.PP
The steps to instrument a web service with \s-1SOAP::WSDL\s0 perl bindings
(in detail) are as follows:
.IP "\(bu" 4
Gather web service information
.Sp
You'll need to know at least a \s-1URL\s0 pointing to the web service's \s-1WSDL\s0
definition.
.Sp
If you already know more \- like which methods the service provides, or how
the \s-1XML\s0 messages look like, that's fine. All these things will help you
later.
.IP "\(bu" 4
Create \s-1WSDL\s0 bindings
.Sp
.Vb 1
\& perl wsdl2perl.pl \-b base_dir URL
.Ve
.Sp
This will generate the perl bindings in the directory specified by base_dir.
.Sp
For more options, see wsdl2perl.pl \- you may want to specify class
prefixes for \s-1XML\s0 type and element classes, type maps and interface classes,
and you may even want to add custom typemap elements.
.IP "\(bu" 4
Check the result
.Sp
There should be a bunch of classes for types (in the MyTypes:: namespace by
default), elements (in MyElements::), and one or more interface classes
(in MyInterfaces::). Older versions also produced at least one typemap (in
MyTypemaps::), which isn't needed any more.
.Sp
If you don't already know the details of the web service you're going to
instrument, it's now time to read the perldoc of the generated interface
classes. It will tell you what methods each service provides, and which
parameters they take.
.Sp
If the \s-1WSDL\s0 definition is informative about what these methods do, the
included perldoc will be, too \- if not, blame the web service author.
.IP "\(bu" 4
Write a perl script (or module) accessing the web service.
.Sp
.Vb 2
\& use MyInterfaces::SERVICE_NAME::PORT_NAME;
\& my $service = MyInterfaces::SERVICE_NAME::PORT_NAME\->new();
\&
\& my $result = $service\->SERVICE_METHOD();
\& die $result if not $result;
\& print $result;
.Ve
.Sp
The above handling of errors (\*(L"die \f(CW$result\fR if not \f(CW$result\fR\*(R") may look a bit
strange \- it is due to the nature of the
SOAP::WSDL::SOAP::Typelib::Fault11
objects \s-1SOAP::WSDL\s0 uses for signalling failure.
.Sp
These objects are false in boolean context, but serialize to their \s-1XML\s0
structure on stringification.
.Sp
You may, of course, access individual fault properties, too. To get a list of
fault properties, see SOAP::WSDL::SOAP::Typelib::Fault11
.SS "Adding missing information"
.IX Subsection "Adding missing information"
Sometimes, \s-1WSDL\s0 definitions are incomplete. In most of these cases, proper
fault definitions are missing. This means that though the specification says
nothing about it, Fault messages include extra elements in the
<detail> section, or errors are even indicated by non-fault messages.
.PP
There are two steps you need to perform for adding additional information.
.IP "\(bu" 4
Provide required type classes
.Sp
For each extra data type used in the \s-1XML\s0 messages, a type class has to be
created.
.Sp
It is strongly discouraged to use the same namespace for hand-written and
generated classes \- while generated classes may be many, you probably will
only implement a few by hand. These (precious) few classes may get lost in
the mass of (cheap) generated ones. Just imagine one of your co-workers (or
even yourself) deleting the whole bunch and re-generating everything \- oops
\&\- almost everything. You get the point.
.Sp
For simplicity, you probably just want to use builtin types wherever possible
\&\- you are probably not interested in whether a fault detail's error code is
presented to you as a simpleType ranging from 1 to 10 (which you have to
write) or as an int (which is a builtin type ready to use).
.Sp
Using builtin types for simpleType definitions may greatly reduce the number
of additional classes you need to implement.
.Sp
If the extra type classes you need include <complexType > or
<element /> definitions, see SOAP::WSDL::SOAP::Typelib::ComplexType
and SOAP::WSDL::SOAP::Typelib::Element on how to create ComplexType and
Element type classes.
.IP "\(bu" 4
Provide a typemap snippet to wsdl2perl.pl
.Sp
\&\s-1SOAP::WSDL\s0 uses typemaps for finding out into which class' object a \s-1XML\s0 node
should be transformed.
.Sp
Typemaps basically map the path of every \s-1XML\s0 element inside the Body tag to a
perl class.
.Sp
Typemap snippets have to look like this (which is actually the default Fault
typemap included in every generated one):
.Sp
.Vb 7
\& (
\& \*(AqFault\*(Aq => \*(AqSOAP::WSDL::SOAP::Typelib::Fault11\*(Aq,
\& \*(AqFault/faultcode\*(Aq => \*(AqSOAP::WSDL::XSD::Typelib::Builtin::anyURI\*(Aq,
\& \*(AqFault/faultactor\*(Aq => \*(AqSOAP::WSDL::XSD::Typelib::Builtin::anyURI\*(Aq,
\& \*(AqFault/faultstring\*(Aq => \*(AqSOAP::WSDL::XSD::Typelib::Builtin::string\*(Aq,
\& \*(AqFault/detail\*(Aq => \*(AqSOAP::WSDL::XSD::Typelib::Builtin::anyType\*(Aq,
\& );
.Ve
.Sp
The lines are hash key \- value pairs. The keys are the XPath expressions
without occurence numbers (like [1]) relative to the Body element.
Namespaces are ignored.
.Sp
If you don't know about XPath: They are just the names of the \s-1XML\s0 tags,
starting from the one inside <Body> up to the current one joined by /.
.Sp
One line for every \s-1XML\s0 node is required.
.Sp
You may use all builtin, generated or custom type class names as values.
.Sp
Use wsdl2perl.pl \-mi=FILE to include custom typemap snippets.
.Sp
Note that typemap include files for wsdl2perl.pl must evaluate to a valid
perl hash \- it will be imported via eval (\s-1OK\s0, to be honest: via \fIdo \f(CI$file\fI\fR,
but that's almost the same...).
.Sp
Your extra statements are included last, so they override potential typemap
statements with the same keys.
.SH "Accessing a web service without a WSDL definition"
.IX Header "Accessing a web service without a WSDL definition"
Accessing a web service without a \s-1WSDL\s0 definition is more cumbersome. There
are two ways to go:
.IP "\(bu" 4
Write a \s-1WSDL\s0 definition and generate interface
.Sp
This is the way to go if you already are experienced in writing \s-1WSDL\s0 files.
If you are not, be warned: Writing a correct \s-1WSDL\s0 is not an easy task, and
writing correct \s-1WSDL\s0 files with only a text editor is almost impossible.
You should definitely use a \s-1WSDL\s0 editor. The \s-1WSDL\s0 editor should support
conformance checks for the WS-I Basic Profile (1.0 is preferred by
\&\s-1SOAP::WSDL\s0)
.IP "\(bu" 4
Write a typemap and class library from scratch
.Sp
If the web service is relatively simple, this is probably easier than first
writing a \s-1WSDL\s0 definition. Besides, it can be done in perl, a language you
are probably more familiar with than \s-1WSDL\s0.
.Sp
SOAP::WSDL::XSD::Typelib::ComplexType, SOAP::WSDL::XSD::Typelib::SimpleType and
SOAP::WSDL::XSD::Typelib::Element tell you how to create subclasses of \s-1XML\s0 schema
types.
.Sp
SOAP::WSDL::Manual::Parser will tell you how to create a typemap class.
.SH "Creating a SOAP Server"
.IX Header "Creating a SOAP Server"
Creating a \s-1SOAP\s0 server works just like creating a client \- just add the
\&\f(CW\*(C`\-\-server\*(C'\fR or \f(CW\*(C`\-s\*(C'\fR option to the call to \f(CW\*(C`wsdl2perl.pl\*(C'\fR.
.PP
.Vb 1
\& perl wsdl2perl.pl \-s \-b BASE_DIR URL
.Ve
.PP
\&\s-1SOAP::WSDL\s0 currently includes classes for building a basic \s-1CGI\s0 and a
mod_perl 2 based \s-1SOAP\s0 server.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
SOAP::WSDL::Manual::Cookbook cooking recipes for accessing web services,
altering the \s-1XML\s0 Serializer and others.
.PP
SOAP::WSDL::Manual::XSD \s-1SOAP::WSDL\s0's \s-1XML\s0 Schema implementation
.PP
SOAP::WSDL::Manual::Glossary The meaning of all these words
.PP
SOAP::WSDL::Client Basic client for \s-1SOAP::WSDL\s0 based interfaces
.PP
\&\s-1SOAP::WSDL\s0 an interpreting \s-1WSDL\s0 based \s-1SOAP\s0 client
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright 2007 Martin Kutter.
.PP
This file is part of SOAP-WSDL. You may distribute/modify it under
the same terms as perl itself
.SH "AUTHOR"
.IX Header "AUTHOR"
Martin Kutter <martin.kutter fen\-net.de>