Provided by: libsoap-wsdl-perl_3.004-2_all bug

NAME

       SOAP::WSDL::Manual - Accessing WSDL based web services

Accessing a WSDL-based web service

   Quick walk-through for the unpatient
       •   Create WSDL bindings

             perl wsdl2perl -b base_dir URL

       •   Look what has been generated

           Check  the  results of the generator. There should be one MyInterfaces/SERVICE_NAME/PORT_NAME.pm file
           per port (and one directory per service).

       •   Write script

            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;

           "perldoc MyInterfaces::SERVICE_NAME::PORT_NAME" should give you some  overview  about  the  service's
           interface structure.

           The  results  of  all  calls  to  your  service  object's  methods  (except new) are objects based on
           SOAP::WSDL's XML schema implementation.

           To  access  the  object's  properties  use  get_NAME  /  set_NAME  getter/setter  methods  with  NAME
           corresponding to the XML tag name / the hash structure as showed in the generated pod.

       •   Run script

   Instrumenting web services with interface classes
       SOAP::WSDL  (starting  from  2.00) instruments WSDL based web services with interface classes. This means
       that SOAP::WSDL features a code generator which creates one class for  every  web  service  you  want  to
       access.

       Moreover, the data types from the WSDL definitions are also wrapped into classes and returned to the user
       as objects.

       To find out which class a particular XML node should be, SOAP::WSDL uses typemaps. For every Web service,
       there's also a typemap created.

   Interface class creation
       To create interface classes, follow the steps above.

       If this works fine for you, skip the next paragraphs. If not, read on.

       The steps to instrument a web service with SOAP::WSDL perl bindings (in detail) are as follows:

       •   Gather web service information

           You'll need to know at least a URL pointing to the web service's WSDL definition.

           If  you  already  know  more  - like which methods the service provides, or how the XML messages look
           like, that's fine. All these things will help you later.

       •   Create WSDL bindings

            perl wsdl2perl -b base_dir URL

           This will generate the perl bindings in the directory specified by base_dir.

           For more options, see wsdl2perl - you may want to specify class prefixes for  XML  type  and  element
           classes, type maps and interface classes, and you may even want to add custom typemap elements.

       •   Check the result

           There  should  be  a bunch of classes for types (in the MyTypes:: namespace by default), elements (in
           MyElements::), and at least one typemap (in MyTypemaps::) and  one  or  more  interface  classes  (in
           MyInterfaces::).

           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.

           If the WSDL definition is informative about what these methods do, the included perldoc will be,  too
           - if not, blame the web service author.

       •   Write a perl script (or module) accessing the web service.

            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;

           The above handling of errors ("die $result if not $result") may look a bit strange - it is due to the
           nature of the SOAP::WSDL::SOAP::Typelib::Fault11 objects SOAP::WSDL uses for signalling failure.

           These objects are false in boolean context, but serialize to their XML structure on stringification.

           You  may,  of course, access individual fault properties, too. To get a list of fault properties, see
           SOAP::WSDL::SOAP::Typelib::Fault11

   Adding missing information
       Sometimes, WSDL 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.

       There are two steps you need to perform for adding additional information.

       •   Provide required type classes

           For each extra data type used in the XML messages, a type class has to be created.

           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.

           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).

           Using  builtin  types  for simpleType definitions may greatly reduce the number of additional classes
           you need to implement.

           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.

       •   Provide a typemap snippet to wsdl2perl

           SOAP::WSDL uses typemaps for finding out into which class' object a XML node should be transformed.

           Typemaps basically map the path of every XML element inside the Body tag to a perl class.

           Typemap snippets have to look like this (which is actually the  default  Fault  typemap  included  in
           every generated one):

            (
            'Fault' => 'SOAP::WSDL::SOAP::Typelib::Fault11',
            'Fault/faultcode' => 'SOAP::WSDL::XSD::Typelib::Builtin::anyURI',
            'Fault/faultactor' => 'SOAP::WSDL::XSD::Typelib::Builtin::anyURI',
            'Fault/faultstring' => 'SOAP::WSDL::XSD::Typelib::Builtin::string',
            'Fault/detail' => 'SOAP::WSDL::XSD::Typelib::Builtin::anyType',
            );

           The  lines  are hash key - value pairs. The keys are the XPath expressions without occurrence numbers
           (like [1]) relative to the Body element.  Namespaces are ignored.

           If you don't know about XPath: They are just the names of the XML tags, starting from the one  inside
           <Body> up to the current one joined by /.

           One line for every XML node is required.

           You may use all builtin, generated or custom type class names as values.

           Use wsdl2perl -mi=FILE to include custom typemap snippets.

           Note  that  typemap  include  files  for  wsdl2perl  must  evaluate to a valid perl hash - it will be
           imported via eval (OK, to be honest: via do $file, but that's almost the same...).

           Your extra statements are included last, so they override potential typemap statements with the  same
           keys.

Accessing a web service without a WSDL definition

       Accessing a web service without a WSDL definition is more cumbersome. There are two ways to go:

       •   Write a WSDL definition and generate interface

           This  is  the  way  to  go  if you already are experienced in writing WSDL files.  If you are not, be
           warned: Writing a correct WSDL is not an easy task, and writing correct WSDL files with only  a  text
           editor is almost impossible.  You should definitely use a WSDL editor. The WSDL editor should support
           conformance checks for the WS-I Basic Profile (1.0 is preferred by SOAP::WSDL)

       •   Write a typemap and class library from scratch

           If  the  web  service  is  relatively  simple,  this  is  probably  easier  than first writing a WSDL
           definition. Besides, it can be done in perl, a language you are  probably  more  familiar  with  than
           WSDL.

           SOAP::WSDL::XSD::Typelib::ComplexType,            SOAP::WSDL::XSD::Typelib::SimpleType            and
           SOAP::WSDL::XSD::Typelib::Element tell you how to create subclasses of XML schema types.

           SOAP::WSDL::Manual::Parser will tell you how to create a typemap class.

Creating a SOAP Server

       Creating a SOAP server works just like creating a client - just add the "--server" or "-s" option to  the
       call to "wsdl2perl".

        perl wsdl2perl -s -b BASE_DIR URL

       SOAP::WSDL currently includes classes for building a basic CGI and a mod_perl 2 based SOAP server.

SEE ALSO

       SOAP::WSDL::Manual::Cookbook  cooking recipes for accessing web services, altering the XML Serializer and
       others.

       SOAP::WSDL::Manual::XSD SOAP::WSDL's XML Schema implementation

       SOAP::WSDL::Manual::Glossary The meaning of all these words

       SOAP::WSDL::Client Basic client for SOAP::WSDL based interfaces

       SOAP::WSDL an interpreting WSDL based SOAP client

LICENSE AND COPYRIGHT

       Copyright 2007 Martin Kutter.

       This file is part of SOAP-WSDL. You may distribute/modify it under the same terms as perl itself

AUTHOR

       Martin Kutter <martin.kutter fen-net.de>

perl v5.36.0                                       2022-10-14                            SOAP::WSDL::Manual(3pm)