1SOAP::WSDL::Manual::XSDU(s3e)r Contributed Perl DocumentaStOiAoPn::WSDL::Manual::XSD(3)
2
3
4

NAME

6       SOAP::WSDL::Manual::XSD - SOAP::WSDL's XML Schema implementation
7

DESCRIPTION

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

USAGE

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

HOW IT WORKS

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

TRANSLATION RULES

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

FACETS

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

CAVEATS

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

BUGS AND LIMITATIONS

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

LICENSE

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

AUTHOR

488       Martin Kutter <martin.kutter fen-net.de>
489

REPOSITORY INFORMATION

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.36.0                      2023-01-20        SOAP::WSDL::Manual::XSD(3)
Impressum