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