1SOAP::WSDL::Manual::XSDU(s3e)r Contributed Perl DocumentaStOiAoPn::WSDL::Manual::XSD(3)
2
3
4
6 SOAP::WSDL::Manual::XSD - SOAP::WSDL's XML Schema implementation
7
9 SOAP::WSDL's XML Schema implementation translates XML Schema
10 definitions into perl classes.
11
12 Every top-level type or element in a XML schema is translated into a
13 perl class (usually in it's own file).
14
15 Atomic types are either directly included in the class of their
16 parent's node, or as sub-package in their parent class' file.
17
18 While the implementation is still incomplete, it covers the XML schema
19 definitions used by most object mappers.
20
22 You can use SOAP::WSDL::XSD based classes just like any perl class -
23 you may instantiate it, inherit from it etc.
24
25 You should be aware, that SOAP::WSDL::XSD based classes are inside-out
26 classes using Class::Std::Fast, though - things you would expect from
27 hash-based classes like using the blessed hash ref as data storage
28 won't work.
29
30 Moreover, most all SOAP::WSDL::XSD::Typelib based classes override
31 Class::Std::Fast's default constructor for speed - you should not
32 expect BUILD or START methods to work, unless you call them yourself
33 (or define a new constructor).
34
35 All SOAP::WSDL::XSD based complexType classes allow a hash ref matching
36 their data structure as only parameter to new(). You may mix hash and
37 list refs and objects in the structure passed to new - as long as the
38 structure matches, it will work fine.
39
40 All SOAP::WSDL::XSD based simpleType (and builtin) classes accept a
41 single hash ref with the only key "value" and the value to be set as
42 value.
43
44 Conversions
45 Array dereference
46
47 All SOAP::WSDL::XSD based classes overload arrayification - that is
48 being accessed as a list ref - with a method returning [ $self ].
49
50 This means that you can safely use the results of get_ELEMENT calls on
51 complexTypes as list refs (you'll have to check for definedness, though
52 - see SOAP::WSDL::XSD::Typelib::Builtin for details.
53
54 To iterate over a (potential) list of child elements just do the
55 following:
56
57 if (defined $obj->get_ELEMENT()) {
58 for (@{ $obj->get_ELEMENT() }) {
59 ...
60 }
61 }
62
63 This is especially useful in mini-languages like
64 HTML::Template::Compiled, where you could say
65
66 <%IF_DEFINED obj.get_ELEMENT %>
67 <%LOOP obj.get_ELEMENT %>
68 ...
69 <%/LOOP>
70 <%IF%>
71
72 Note that this does not work in HTML::Template::Compiled yet - the code
73 generated for the template checks UNIVERSAL::isa instead of
74 dereferencing. There's a ticket open in HTC to solve the issue.
75
76 as_hash_ref
77
78 SOAP::WSDL::XSD::Typelib::ComplexType based objects have a method
79 as_hash_ref, which returns the object's content as a hash reference.
80
81 This can be convenient for cloning:
82
83 my $class = ref $old;
84 my $clone = $class->new( $old->as_hash_ref() );
85
86 To convert from one type to another, you can just say
87
88 my $new = MyTypes::NewType->new( $old->as_hash_ref() );
89
90 Of course this will only work if MyTypes::NewType has a superset of the
91 old object class' elements.
92
93 Note that XML attribute data is not included in the hash ref output
94 yet.
95
97 Base classes
98 SOAP::WSDL::XSD provides a set of base classes for the construction of
99 XML schema defined type classes.
100
101 Builtin types
102
103 SOAP::WSDL::XSD provides classes for all builtin XML Schema datatypes.
104
105 For a list and reference on these classes, see
106 SOAP::WSDL::XSD::Typelib::Builtin.
107
108 Derivation classes
109
110 For derivation by list, the list derivation class
111 SOAP::WSDL::XSD::Typelib::Builtin::list exists.
112
113 Derivation by restriction is handled without the help of additional
114 classes.
115
116 Element construction class
117
118 For the construction of element classes, the element superclass
119 SOAP::WSDL::XSD::Typelib::Element exists. All elements are ultimately
120 derived from this class. Elements may inherit from type classes, too -
121 see "TRANSLATION RULES" for details.
122
123 complexType construction class
124
125 For the construction of complexType classes, the construction class
126 SOAP::WSDL::XSD::Typelib::ComplexType is provided. It provides a
127 __factory method for placing attributes in generated classes, and
128 generating appropriate setter/getter accessors.
129
130 The setters are special: They handle complex data structures of any
131 type (meaning hash refs, list refs and objects, and any combination of
132 them), as long as their structure matches the expected structure.
133
135 element
136 TODO add more elaborate description
137
138 element with type attribute
139
140 Elements defined by referencing a builtin or user defined type inherit
141 from SOAP::WSDL::XSD::Typelib::Element and from the corresponding type
142 class.
143
144 Element Type
145 base class class
146 ^ ^
147 | |
148 ------------
149 |
150 Element type="" class
151
152 element with ref attribute
153
154 Elements defined by referencing another element inherit from the
155 corresponding element class.
156
157 referenced Element class
158 ^
159 |
160 Element ref="" class
161
162 element with atomic simpleType
163
164 Elements defined by a atomic simpleType from
165 SOAP::WSDL::XSD::Typelib::Element and from the base type of the atomic
166 type.
167
168 Element atomic Type
169 base class base class
170 ^ ^
171 | |
172 --------------
173 |
174 element simpleType class
175
176 element with atomic complexType
177
178 Elements defined with a atomic complexType inherit from
179 SOAP::WSDL::XSD::Typelib::Element and from
180 SOAP::WSDL::XSD::Typelib::ComplexType.
181
182 Element complexType
183 base class base class
184 ^ ^
185 | |
186 --------------
187 |
188 element complexType class
189
190 complexType
191 TODO add more elaborate description
192
193 Some content models are not implemented yet. The content models
194 implemented are described below.
195
196 complexType with "all" variety
197
198 Complex types with "all" variety inherit from
199 SOAP::WSDL::XSD::Typelib::ComplexType, and call it's factory method for
200 creating fields and accessors/mutators for the complexType's elements.
201
202 All element's type classes are loaded. Complex type classes have a "has
203 a" relationship to their element fields.
204
205 Element fields may either be element classes (for element ref="") or
206 type classes (for element type=""). No extra element classes are
207 created for a complexType's elements.
208
209 complexType
210 base class
211 ^
212 |
213 complexType all
214 ---------------- has a
215 element name="a" ------------> Element or type class object
216 element name="b" ------------> Element or type class object
217
218 The implementation for all does enforce the order of elements as
219 described in the WSDL, even though this is not required by the XML
220 Schema specification.
221
222 complexType with "sequence" variety
223
224 The implementation of the "sequence" variety is the same as for all.
225
226 complexType with "choice" variety
227
228 The implementation for choice currently is the same as for all - which
229 means, no check for occurrence are made.
230
231 complexType with complexContent content model
232
233 Note that complexType classes with complexContent content model don't
234 exhibit their type via the xsi:type attribute yet, so they currently
235 cannot be used as a replacement for their base type.
236
237 SOAP::WSDL's XSD deserializer backend does not recognize the
238 xsi:type="" attribute either yet.
239
240 · restriction variety
241
242 ComplexType classes with restriction variety inherit from their
243 base type. No additional processing or content checking is
244 performed yet.
245
246 complexType
247 base type class
248 ^
249 |
250 complexType
251 restriction
252
253 · extension variety
254
255 ComplexType classes with extension variety inherit from the XSD
256 base complexType class and from their base type.
257
258 Extension classes are checked for (re-)defining all elements of
259 their parent class.
260
261 Note that a derived type's elements (=properties) overrides the
262 getter / setter methods for all inherited elements. All object data
263 is stored in the derived type's class, not in the defining class
264 (See Class::Std for a discussion on inside out object data
265 storage).
266
267 No additional processing or content checking is performed yet.
268
269 complexType complexType
270 base class base type class
271 ^ ^
272 | |
273 -----------------
274 |
275 complexType
276 extension
277
278 SimpleType
279 TODO add more elaborate description
280
281 Some derivation methods are not implemented yet. The derivation methods
282 implemented are described below.
283
284 Derivation by list
285
286 Derivation by list is implemented by inheriting from both the base type
287 and SOAP::WSDL::XSD::Typelib::XSD::list.
288
289 Derivation by restriction
290
291 Derivation by restriction is implemented by inheriting from a base type
292 and applying the required restrictions.
293
295 XML Schema facets are not implemented yet.
296
297 They will probably implemented some day by putting constant methods
298 into the correspondent classes.
299
300 Attributes
301 The attribute set for a XML element (derived from anySimpleType or
302 complexType) is implemented as a sub-package of the element derived
303 from SOAP::WSDL::XSD::Typelib::AttributeSet.
304
305 The sub-package is named as the corresponding type or element package,
306 suffixed with "XmlAttr". The suffix "XmlAttr" has carefully been chosen
307 to avoid potential naming clashes: The name XmlAttr cannot be included
308 as element or type name in XML schemas - the XML standard bans the use
309 of names starting with "xml" (case-insensitive).
310
311 All XML attributes for a XML element are set- and retrievable via the
312 method "attr". The name is chosen to allow mimicking SOAP::Lite's
313 behaviour, which allows setting a SOAP::Data object's attributes via
314 "attr".
315
316 my $attrSet = $obj->attr();
317 $obj->attr({
318 whitespace => 'preserve',
319 nillable => 1,
320 });
321
322 SOAP::WSDL::XSD::Typelib::AttributeSet is derived from
323 SOAP::WSDL::XSD::Typelib::ComplexType with content model "all". The
324 individual attributes can be set and retrieved via the respective
325 set_FOO / get_FOO methods.
326
327 The "attr" method provides auto-vivification: An xml object's attribute
328 set is instantiated when accessed.
329
330 Auto-vivification is only triggered if there actually is a set of
331 attributes for the class/object in question, so you may want to test
332 whether the result of ->attr is defined:
333
334 my $attr = $unknownObject->attr();
335 if (defined($attr)) {
336 $unknownObject->attr({
337 some => 'value',
338 });
339 }
340
341 group
342 CAVEAT: Group resolution is not implemented yet.
343
344 XML Schema Group definitions are just treated as aliases that can be
345 inserted in complexType definitions by referencing them. That is,
346 there's no difference between a complexType with simpleContent and a
347 sequence of three elements, and a complexType with simpleContent
348 referencing a group containing the same sequence of elements.
349
351 · START and BUILD are not being called
352
353 In contrast to "normal" Class::Std::Fast based objects, the classes
354 of the SOAP::WSDL::XSD::Typelib:: hierarchy (and all type and
355 element classes generated by SOAP::WSDL) override Class::Std's
356 constructor for performance reasons.
357
358 If you inherit from such a class and place a START or BUILD method
359 in it, it will not get called - at least not unless you place
360 something like this at the top of you code:
361
362 use Class::Std::Fast::Storable;
363
364 In this case, Class::Std::Fast::Storable will export a new() method
365 into your class, which in turn calls START and BUILD.
366
367 The constructors of all SOAP::WSDL::XSD::Typelib:: classes don't !
368
370 The following XML Schema declaration elements are not supported yet:
371
372 XML Schema elements partially supported
373 Type definition elements
374
375 · simpleContent
376
377 simpleContent is only supported with a restriction or extension
378 with a "base" attribute. simpleContent declarations deriving from a
379 atomic type are not supported (yet).
380
381 Inclusion elements
382
383 · import
384
385 The import inclusion element requires the schemaLocation attribute
386 for resolving the XML schema to import. Support for the import
387 element is implemented in SOAP::WSDL::Expat::WSDLParser, so
388 alternative parsers may or may not support the import element.
389
390 SOAP::WSDL::Expat::WSDLParser keeps track of included schemas and
391 prevents import loops.
392
393 Facets
394
395 The following XML Schema declaration elements are supported, but have
396 no effect yet.
397
398 · enumeration
399
400 · fractionDigits
401
402 · length
403
404 · maxExclusive
405
406 · maxInclusiove
407
408 · maxLength
409
410 · minExclusive
411
412 · minInclusive
413
414 · minLength
415
416 · pattern
417
418 · totalDigits
419
420 · whitespace
421
422 XML Schema elements not implemented
423 Declaration elements
424
425 · notation
426
427 Content model definition elements
428
429 · any
430
431 The horror of each XML schema implementation: Just anything...
432
433 "any" declarations are not supported yet.
434
435 · anyAttribute
436
437 · attributeGroup
438
439 "attributeGroup" declarations actually just are macros for XML
440 Schema writers: Including an attributeGroup in a declaration has
441 the same effect as including all attributes in the group.
442
443 Just not implemented yet.
444
445 · group
446
447 The group definition element is not supported yet.
448
449 Identity definition elements
450
451 These declaration elements don't declare XML elements, but apply
452 identity constraints. They have no effect yet.
453
454 · field
455
456 · key
457
458 · keyref
459
460 · selector
461
462 · unique
463
464 Inclusion elements
465
466 · include
467
468 Use of the include inclusion element is forbidden by the WS-I basic
469 profile. It is not supported (yet).
470
471 · redefine
472
473 Not supported (yet).
474
475 * Documentation elements
476
477 · appinfo
478
479 The appinfo documentation element is ignored.
480
482 Copyright 2007,2008 Martin Kutter.
483
484 This file is part of SOAP-WSDL. You may distribute/modify it under the
485 same terms as perl itself
486
488 Martin Kutter <martin.kutter fen-net.de>
489
491 $Rev: 390 $
492 $LastChangedBy: kutterma $
493 $Id: Client.pm 390 2007-11-16 22:18:32Z kutterma $
494 $HeadURL: http://soap-wsdl.svn.sourceforge.net/svnroot/soap-wsdl/SOAP-WSDL/trunk/lib/SOAP/WSDL/Client.pm $
495
496
497
498perl v5.30.1 2020-01-30 SOAP::WSDL::Manual::XSD(3)