Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Pod::WSDL(3)	      User Contributed Perl Documentation	  Pod::WSDL(3)

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:

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

       o 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 preceeded 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

       o   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?

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

       o   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!

       o   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

       o   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!

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

perl v5.24.1			  2010-12-17			  Pod::WSDL(3)

NAME | SYNOPSIS | DESCRIPTION - How to use Pod::WSDL | METHODS | EXTERNAL DEPENDENCIES | EXAMPLES | BUGS | TODO | REFERENCES | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Pod::WSDL&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help