Provided by: libpod-wsdl-perl_0.063-2_all bug

NAME

       Pod::WSDL - Creates WSDL documents from (extended) pod

SYNOPSIS

         use Pod::WSDL;

         my $pod = new Pod::WSDL(source => 'My::Server',
           location => 'http://localhost/My/Server',
           pretty => 1,
           withDocumentation => 1);

         print $pod->WSDL;

DESCRIPTION - How to use Pod::WSDL

   Parsing the pod
       How does Pod::WSDL work? If you instantiate a Pod::WSDL object with the name of the module
       (or the path of the file, or an open filehandle) providing the web service like this

         my $pwsdl = new Pod::WSDL(source => 'My::Module',
               location => 'http://my.services.location/on/the/web');

       Pod::WSDL will try to find "My::Module" in @INC, open the file, parse it for WSDL
       directives and prepare the information for WSDL output. By calling

         $pwsdl->WSDL;

       Pod::WSDL will output the WSDL document. That's it.

       When using Pod::WSDL, the parser expects you to do the following:

       • Put the pod directly above the subroutines which the web service's client is going to
         call. There may be whitespace between the pod and the sub declaration but nothing else.

       • Use the "=begin"/"=end" respectively the "=for" directives according to standard pod:
         anything between "=begin WSDL" and "=end" will be treated as pod. Anything composing a
         paragraph together with "=for WSDL" will be treated as pod.

       Any subroutine not preceded by WSDL pod will be left unmentioned. Any standard pod will be
       ignored (though, for an exception to this, see the section on own complex types below).

       The individual instructions for Pod::WSDL always begin with a keyword, like "_RETURN" or
       "_DOC" or "_FAULT". After this different things may follow, according to the specific type
       of instruction. The instruction may take one or more lines - everything up to the next
       line beginning with a keyword or the end of the pod is belonging to the current
       instruction.

   Describing Methods
       How do we use Pod::WSDL? In describing a web service's method we have to say something
       about parameters, return values and faults. In addition you might want to add some
       documentation to these items and to the method itself.

       Parameters

       WSDL differentiates between in-, out- and inout-parameters, so we do that, too. A
       different matter is the question, if the client can do this too, but now we are talking
       about possibilities, not actualities.

       The pod string describing a parameter has the structure

         (_IN|_OUT|_INOUT) NAME ($|@)TYPE DESCRIPTION

       like

         _IN foo $string This is a foo

       or

         _INOUT bar @bar An array of bars

       You will easily guess what "_IN", "_OUT" and "_INOUT" stand for so we can move on. "NAME"
       is the name of your parameter. It does not have any real function (the order of the
       parameters being the only important thing) but it is nice to have it since in a WSDL
       document the parameters need to have names. So instead of having Pod::WSDL automatically
       generate cryptic names (it cannot do that right now) be nice to the client and use some
       sensible name. The "TYPE" of the parameters can be any of the xsd (schema) standard types
       (see [5]) or a type of your own creation. The "$" resp. "@" symbols tell Pod::WSDL and
       your client if it is a scalar or array parameter. Everything following the type up to the
       next instruction is treated as the parameter's documentation. If you call the constructor
       of Pod::WSDL with the argument "withDocumentation => 1", it will be added to the WSDL.

       Return Values

       Return values work like parameters but since in WSDL there is provision for only one
       return value (you have (in)out parameters, or can return arrays if that isn't enough), you
       do not need to give them a name. Pod::WSDL will automatically call them 'Return' in the
       WSDL document. So, the structure of "_RETURN" instructions is

         _RETURN ($|@)TYPE DESCRIPTION

       as in

         _RETURN $string Returns a string

       The pod for one method may only have one "_RETURN" instruction. If you don't specify a
       "_RETURN" instruction, Pod::WSDL will assume that you return void. Of course the perl
       subroutine still will return something, but your web service won't. To make this clear
       Pod::WSDL generates an empty response message for this.

       If you want some method to be a one way operation (see [4], ch. 2.4.1), say so by using
       the instruction "_ONEWAY" in the pod. In this case no response message will be generated
       and a "_RETURN" instruction will be ignored.

       Faults

       SOAP faults are usually translated into exceptions in languages like Java. If you set up a
       web service using SOAP::Lite, SOAP will trap your dying program and generate a generic
       fault using the message of "die". It is also possible to access SOAP::Lite's SOAP::Fault
       directly if you want more control - but this is not our issue. If you want to use custom-
       made fault messages of your own, define them in "_FAULT" instructions, which look like
       this:

         _FAULT TYPE DESCRIPTION

       An example could be the following:

         _FAULT My::Fault If anything goes wrong

       Since you probably won't return an array of fault objects, you do not need to use the
       "($|@)" tokens. Just say that you return a fault, declare its type and add an optional
       description.

       As with parameters (but in contrary to "_RETURN" instructions) you can declare as many
       "_FAULT" instructions as you like, providing for different exception types your method
       might throw.

       Method Documentation

       Method documentation is easily explained. Its structure is

         _DOC Here comes my documentation ...

       That's it. Use several lines of documentation if you like. If you instantiate the
       Pod::WSDL object with the parameter "withDocumentation => 1", it will be written into the
       WSDL document.

   Describing Modules - Using Own Complex Types
       Quite often it will be the case that you have to use complex types as parameters or return
       values. One example of this we saw when talking about faults: you might want to create
       custom fault types (exceptions) of your own to fullfill special needs in the communication
       between web service and client. But of course you also might simply want to pass a complex
       parameter like a address object containing customer data to your application. WSDL
       provides the means to describe complex types borrowing the xsd schema syntax. Pod::WSDL
       makes use of this by allowing you to add WSDL pod to your own types. Assuming you have
       some own type like

         package My::Type;

         sub new {
           bless {
             foo => 'foo',
             bar => -1
           }, $_[0];
         }

         1;

       simply describe the keys of your blessed hash like this.

         =begin WSDL

           _ATTR foo $string A foo
           _ATTR bar $integer And a bar

         =end WSDL

       Put this pod anywhere within the package My::Type. Pod::WSDL will find it (if it is in
       @INC), parse it and integrate it into the WSDL document. The "_ATTR" instruction works
       exactly as the "_IN", "_OUT" and "_INOUT" instructions for methods (see above).

       If you initialize the Pod::WSDL object using "withDocumentation => 1", Pod::WSDL will look
       for standard pod in the module, parse it using Pod::Text and put it into the WSDL
       document.

METHODS

   new
       Instantiates a new Pod::WSDL.

       Parameters

       •   source - Name of the source file, package of the source module or file handle on
           source file for which the WSDL shall be generated. This source must contain
           specialized Pod tags. So, if your source is '/some/directory/modules/Foo/Bar.pm' with
           package declaration 'Foo::Bar', source may be '/some/directory/modules/Foo/Bar.pm' or
           'Foo::Bar' (in which case '/some/directory/modules' has to be in @INC) or an open file
           handle on the file. Right?

       •   location - Target namespace for the WSDL, usually the full URL of your webservice's
           proxy.

       •   pretty - Pretty print WSDL, if true. Otherwise the WSDL will come out in one line. The
           software generating the client stubs might not mind, but a person reading the WSDL
           will!

       •   withDocumentation - If true, put available documentation in the WSDL (see "Pod Syntax"
           above). For used own complex types ('modules') this will be the output of Pod::Text on
           these modules. The software generating the client stubs might give a damn, but a
           person reading the WSDL won't!

   WSDL
       Returns WSDL as string.

       Parameters

       •   pretty - Pretty print WSDL, if true. Otherwise the WSDL will come out in one line. The
           software generating the client stubs might not mind, but a person reading the WSDL
           will!

       •   withDocumentation - If true, put available documentation in the WSDL (see "Pod Syntax"
           above). For used own complex types ('modules') this will be the output of Pod::Text on
           these modules. The software generating the client stubs might give a damn, but a
           person reading the WSDL won't!

   addNamespace
       Adds a namespace. Will be taken up in WSDL's definitions element.

       Parameters

       1.  URI of the namespace

       2.  Declarator of the namespace

EXTERNAL DEPENDENCIES

         Carp
         XML::Writer
         IO::Scalar
         Pod::Text

       The test scripts use

         XML::XPath

EXAMPLES

       see the *.t files in the distribution

BUGS

       Please send me any bug reports, I will fix them or mention the bugs here :-)

TODO

   Describe Several Signatures for one Method
       Of course, one subroutine declaration might take a lot of different sets of parameters. In
       Java or C++ you would have to have several methods with different signatures. In perl you
       fix this within the method. So why not put several WSDL pod blocks above the method so the
       web service's client can handle that.

   Implement a Better Parsing of the pod
       Right know, the pod is found using some rather complex regular expressions. This is evil
       and will certainly fail in some situations. So, an issue on top of the fixme list is to
       switch to regular parsing. I'm not sure if I can use Pod::Parser since I need the sub
       declaration outside the pod, too.

   Handle Several Package Declarations in One File
       So far, Pod::WSDL assumes a one to one relation between packages and files. If it meets
       several package declarations in one file, it will fail some way or the other. For most
       uses, one package in one file will presumably suffice, but it would be nice to be able to
       handle the other cases, too.

   Handle Array based blessed References
       Array based blessed references used for complex types are something of a problem.

   Get Information on Complex Types from Somewhere Else
       If you use complex types for parameters that are not your own (we assume, that the module
       containing the web service always is your own), you might not be able to put the WSDL pod
       into the module files. So why not fetch it from somewhere else like a configuration file?

   Integrate Pod::WSDL with SOAP::Lite
       With Axis, you simply call the web service's URL with the parameter '?wsdl' and you get
       the WSDL document. It would be nice to be able to do this with SOAP::Lite, too.

   Implement Non RPC Style Messages
       Pod::WSDL writes WSDL documents in encoded RPC style. It should be able to generate
       literal RPC and document styles, too.

REFERENCES

       [1] <http://ws.apache.org/axis/>

       [2] <http://search.cpan.org/~kbrown/SOAP-0.28/>

       [3] <http://search.cpan.org/~byrne/SOAP-Lite-0.65_5/>

       [4] <http://www.w3.org/TR/wsdl.html>

       [5] <http://www.w3.org/TR/xmlschema-2/>

SEE ALSO

         http://ws.apache.org/axis/
         http://search.cpan.org/~kbrown/SOAP-0.28/
         http://search.cpan.org/~byrne/SOAP-Lite-0.65_5/
         http://www.w3.org/TR/wsdl

         WSDL::Generator (a different way to do it)
         SOAP::WSDL (the client side)
         SOAP::Clean::WSDL (I have not tried this)

AUTHOR

       Tarek Ahmed, <bloerch -the character every email address contains- oelbsk.org>

COPYRIGHT AND LICENSE

       Copyright (C) 2006 by Tarek Ahmed

       This library is alpha software and comes with no warranty whatsoever.  It is free
       software; you can redistribute it and/or modify it under the same terms as Perl itself,
       either Perl version 5.8.5 or, at your option, any later version of Perl 5 you may have
       available.