1NAME 2 Pod::WSDL - Creates WSDL documents from (extended) pod 3 4INSTALLATION 5 6To install this module type the following: 7 8 perl Makefile.PL 9 make 10 make test 11 make install 12 13SYNOPSIS 14 use Pod::WSDL; 15 16 my $pod = new Pod::WSDL(source => 'My::Server', 17 location => 'http://localhost/My/Server', 18 pretty => 1, 19 withDocumentation => 1); 20 21 print $pod->WSDL; 22 23DESCRIPTION - How to use Pod::WSDL 24 Parsing the pod 25 How does Pod::WSDL work? If you instantiate a Pod::WSDL object with the 26 name of the module (or the path of the file, or an open filehandle) 27 providing the web service like this 28 29 my $pwsdl = new Pod::WSDL(source => 'My::Module', 30 location => 'http://my.services.location/on/the/web'); 31 32 Pod::WSDL will try to find "My::Module" in @INC, open the file, parse it 33 for WSDL directives and prepare the information for WSDL output. By 34 calling 35 36 $pwsdl->WSDL; 37 38 Pod::WSDL will output the WSDL document. That's it. 39 40 When using Pod::WSDL, the parser expects you to do the following: 41 42 * Put the pod directly above the subroutines which the web service's 43 client is going to call. There may be whitespace between the pod and 44 the sub declaration but nothing else. 45 46 * Use the "=begin"/"=end" respectively the "=for" directives according 47 to standard pod: anything between "=begin WSDL" and "=end" will be 48 treated as pod. Anything composing a paragraph together with "=for 49 WSDL" will be treated as pod. 50 51 Any subroutine not preceeded by WSDL pod will be left unmentioned. Any 52 standard pod will be ignored (though, for an exception to this, see the 53 section on own complex types below). 54 55 The individual instructions for Pod::WSDL always begin with a keyword, 56 like "_RETURN" or "_DOC" or "_FAULT". After this different things may 57 follow, according to the specific type of instruction. The instruction 58 may take one or more lines - everything up to the next line beginning 59 with a keyword or the end of the pod is belonging to the current 60 instruction. 61 62 Describing Methods 63 How do we use Pod::WSDL? In describing a web service's method we have to 64 say something about parameters, return values and faults. In addition 65 you might want to add some documentation to these items and to the 66 method itself. 67 68 Parameters 69 WSDL differentiates between in-, out- and inout-parameters, so we do 70 that, too. A different matter is the question, if the client can do this 71 too, but now we are talking about possibilities, not actualities. 72 73 The pod string describing a parameter has the structure 74 75 (_IN|_OUT|_INOUT) NAME ($|@)TYPE DESCRIPTION 76 77 like 78 79 _IN foo $string This is a foo 80 81 or 82 83 _INOUT bar @bar An array of bars 84 85 You will easily guess what "_IN", "_OUT" and "_INOUT" stand for so we 86 can move on. "NAME" is the name of your parameter. It does not have any 87 real function (the order of the parameters being the only important 88 thing) but it is nice to have it since in a WSDL document the parameters 89 need to have names. So instead of having Pod::WSDL automatically 90 generate cryptic names (it cannot do that right now) be nice to the 91 client and use some sensible name. The "TYPE" of the parameters can be 92 any of the xsd (schema) standard types (see [5]) or a type of your own 93 creation. The "$" resp. "@" symbols tell Pod::WSDL and your client if it 94 is a scalar or array parameter. Everything following the type up to the 95 next instruction is treated as the parameter's documentation. If you 96 call the constructor of Pod::WSDL with the argument "withDocumentation 97 => 1", it will be added to the WSDL. 98 99 Return Values 100 Return values work like parameters but since in WSDL there is provision 101 for only one return value (you have (in)out parameters, or can return 102 arrays if that isn't enough), you do not need to give them a name. 103 Pod::WSDL will automatically call them 'Return' in the WSDL document. 104 So, the structure of "_RETURN" instructions is 105 106 _RETURN ($|@)TYPE DESCRIPTION 107 108 as in 109 110 _RETURN $string Returns a string 111 112 The pod for one method may only have one "_RETURN" instruction. If you 113 don't specify a "_RETURN" instruction, Pod::WSDL will assume that you 114 return void. Of course the perl subroutine still will return something, 115 but your web service won't. To make this clear Pod::WSDL generates an 116 empty response message for this. 117 118 If you want some method to be a one way operation (see [4], ch. 2.4.1), 119 say so by using the instruction "_ONEWAY" in the pod. In this case no 120 response message will be generated and a "_RETURN" instruction will be 121 ignored. 122 123 Faults 124 SOAP faults are usually translated into exceptions in languages like 125 Java. If you set up a web service using SOAP::Lite, SOAP will trap your 126 dying program and generate a generic fault using the message of "die". 127 It is also possible to access SOAP::Lite's SOAP::Fault directly if you 128 want more control - but this is not our issue. If you want to use 129 custom-made fault messages of your own, define them in "_FAULT" 130 instructions, which look like this: 131 132 _FAULT TYPE DESCRIPTION 133 134 An example could be the following: 135 136 _FAULT My::Fault If anything goes wrong 137 138 Since you probably won't return an array of fault objects, you do not 139 need to use the "($|@)" tokens. Just say that you return a fault, 140 declare it's type and add an optional description. 141 142 As with parameters (but in contrary to "_RETURN" instructions) you can 143 declare as many "_FAULT" instructions as you like, providing for 144 different exception types your method might throw. 145 146 Method Documentation 147 Method documentation is easily explained. It's structure is 148 149 _DOC Here comes my documentation ... 150 151 That's it. Use several lines of documentation if you like. If you 152 instantiate the Pod::WSDL object with the parameter "withDocumentation 153 => 1", it will be written into the WSDL document. 154 155 Describing Modules - Using Own Complex Types 156 Quite often it will be the case that you have to use complex types as 157 parameters or return values. One example of this we saw when talking 158 about faults: you might want to create custom fault types (exceptions) 159 of your own to fullfill special needs in the communication between web 160 service and client. But of course you also might simply want to pass a 161 complex parameter like a address object containing customer data to your 162 application. WSDL provides the means to describe complex types borrowing 163 the xsd schema syntax. Pod::WSDL makes use of this by allowing you to 164 add WSDL pod to your own types. Assuming you have some own type like 165 166 package My::Type; 167 168 sub new { 169 bless { 170 foo => 'foo', 171 bar => -1 172 }, $_[0]; 173 } 174 175 1; 176 177 simply describe the keys of your blessed hash like this. 178 179 =begin WSDL 180 181 _ATTR foo $string A foo 182 _ATTR bar $integer And a bar 183 184 =end WSDL 185 186 Put this pod anywhere within the package My::Type. Pod::WSDL will find 187 it (if it is in @INC), parse it and integrate it into the WSDL document. 188 The "_ATTR" instruction works exactly as the "_IN", "_OUT" and "_INOUT" 189 instructions for methods (see above). 190 191 If you initialize the Pod::WSDL object using "withDocumentation => 1", 192 Pod::WSDL will look for standard pod in the module, parse it using 193 Pod::Text and put it into the WSDL document. 194 195METHODS 196 new 197 Instantiates a new Pod::WSDL. 198 199 Parameters 200 * source - Name of the source file, package of the source module or 201 file handle on source file for which the WSDL shall be generated. 202 This source must contain specialized Pod tags. So, if your source is 203 '/some/directory/modules/Foo/Bar.pm' with package declaration 204 'Foo::Bar', source may be '/some/directory/modules/Foo/Bar.pm' or 205 'Foo::Bar' (in which case '/some/directory/modules' has to be in 206 @INC) or an open file handle on the file. Right? 207 208 * location - Target namespace for the WSDL, usually the full URL of 209 your webservice's proxy. 210 211 * pretty - Pretty print WSDL, if true. Otherwise the WSDL will come 212 out in one line. The software generating the client stubs might not 213 mind, but a person reading the WSDL will! 214 215 * withDocumentation - If true, put available documentation in the WSDL 216 (see "Pod Syntax" above). For used own complex types ('modules') 217 this will be the output of Pod::Text on these modules. The software 218 generating the client stubs might give a damn, but a person reading 219 the WSDL won't! 220 221 WSDL 222 Returns WSDL as string. 223 224 Parameters 225 * pretty - Pretty print WSDL, if true. Otherwise the WSDL will come 226 out in one line. The software generating the client stubs might not 227 mind, but a person reading the WSDL will! 228 229 * withDocumentation - If true, put available documentation in the WSDL 230 (see "Pod Syntax" above). For used own complex types ('modules') 231 this will be the output of Pod::Text on these modules. The software 232 generating the client stubs might give a damn, but a person reading 233 the WSDL won't! 234 235 addNamespace 236 Adds a namespace. Will be taken up in WSDL's definitions element. 237 238 Parameters 239 1 URI of the namespace 240 241 2 Declarator of the namespace 242 243EXTERNAL DEPENDENCIES 244 Carp 245 XML::Writer 246 IO::Scalar 247 Pod::Text 248 249 The test scripts use 250 251 XML::XPath 252 253EXAMPLES 254 see the *.t files in the distribution 255 256BUGS 257 Please send me any bug reports, I will fix them or mention the bugs here 258 :-) 259 260TODO 261 Describe Several Signatures for one Method 262 Of course, one subroutine declaration might take a lot of different sets 263 of parameters. In Java or C++ you would have to have several methods 264 with different signatures. In perl you fix this within the method. So 265 why not put several WSDL pod blocks above the method so the web 266 service's client can handle that. 267 268 Implement a Better Parsing of the pod 269 Right know, the pod is found using some rather complex regular 270 expressions. This is evil and will certainly fail in some situations. 271 So, an issue on top of the fixme list is to switch to regular parsing. 272 I'm not sure if I can use Pod::Parser since I need the sub declaration 273 outside the pod, too. 274 275 Handle Several Package Declarations in One File 276 So far, Pod::WSDL assumes a one to one relation between packages and 277 files. If it meets several package declarations in one file, it will 278 fail some way or the other. For most uses, one package in one file will 279 presumably suffice, but it would be nice to be able to handle the other 280 cases, too. 281 282 Handle Array based blessed References 283 Array based blessed references used for complex types are something of a 284 problem. 285 286 Get Information on Complex Types from Somewhere Else 287 If you use complex types for parameters that are not your own (we 288 assume, that the module containing the web service always is your own), 289 you might not be able to put the WSDL pod into the module files. So why 290 not fetch it from somewhere else like a configuration file? 291 292 Integrate Pod::WSDL with SOAP::Lite 293 With Axis, you simply call the web service's URL with the parameter 294 '?wsdl' and you get the WSDL document. It would be nice to be able to do 295 this with SOAP::Lite, too. 296 297 Implement Non RPC Style Messages 298 Pod::WSDL writes WSDL documents in encoded RPC style. It should be able 299 to generate literal RPC and document styles, too. 300 301REFERENCES 302 [1] <http://ws.apache.org/axis/> 303 304 [2] <http://search.cpan.org/~kbrown/SOAP-0.28/> 305 306 [3] <http://search.cpan.org/~byrne/SOAP-Lite-0.65_5/> 307 308 [4] <http://www.w3.org/TR/wsdl.html> 309 310 [5] <http://www.w3.org/TR/xmlschema-2/> 311 312SEE ALSO 313 http://ws.apache.org/axis/ 314 http://search.cpan.org/~kbrown/SOAP-0.28/ 315 http://search.cpan.org/~byrne/SOAP-Lite-0.65_5/ 316 http://www.w3.org/TR/wsdl 317 318 WSDL::Generator (a different way to do it) 319 SOAP::WSDL (the client side) 320 SOAP::Clean::WSDL (I have not tried this) 321 322AUTHOR 323 Tarek Ahmed, <bloerch -the character every email address contains- 324 oelbsk.org> 325 326COPYRIGHT AND LICENSE 327 Copyright (C) 2006 by Tarek Ahmed 328 329 This library is alpha software and comes with no warranty whatsoever. It 330 is free software; you can redistribute it and/or modify it under the 331 same terms as Perl itself, either Perl version 5.8.5 or, at your option, 332 any later version of Perl 5 you may have available. 333 334